Minor UX improvement: Add the UnknownCodecError. (#689)

* Add the UnknownCodecError

* Remove trailing whitespace

* Ruff formatting

* Add a release note

* Add doctest

* Fix failing test case

* Formatting again

* Update numcodecs/tests/test_registry.py

Co-authored-by: David Stansby <[email protected]>

* Make UnknownCodecError inherit from ValueError

---------

Co-authored-by: David Stansby <[email protected]>

Author: cwognum

docs/release.rst

@@ -70,6 +70,8 @@ Improvements
   Import errors caused by optional dependencies (ZFPY, MsgPack, CRC32C, and PCodec)
   are still silently caught.
   By :user:`David Stansby <dstansby>`, :issue:`550`.
+* Raise a custom `UnknownCodecError` when trying to retrieve an unavailable codec.
+  By :user:`Cas Wognum <cwognum>`.
 
 .. _release_0.14.1:
 

numcodecs/errors.py

@@ -0,0 +1,26 @@
+"""
+This module defines custom exceptions that are raised in the `numcodecs` codebase.
+"""
+
+
+class UnknownCodecError(ValueError):
+    """
+    An exception that is raised when trying to receive a codec that has not been registered.
+
+    Parameters
+    ----------
+    codec_id : str
+        Codec identifier.
+
+    Examples
+    ----------
+    >>> import numcodecs
+    >>> numcodecs.get_codec({"codec_id": "unknown"})
+    Traceback (most recent call last):
+        ...
+    UnknownCodecError: codec not available: 'unknown'
+    """
+
+    def __init__(self, codec_id: str):
+        self.codec_id = codec_id
+        super().__init__(f"codec not available: '{codec_id}'")

numcodecs/registry.py

@@ -5,6 +5,7 @@
 from importlib.metadata import EntryPoints, entry_points
 
 from numcodecs.abc import Codec
+from numcodecs.errors import UnknownCodecError
 
 logger = logging.getLogger("numcodecs")
 codec_registry: dict[str, Codec] = {}
@@ -50,7 +51,7 @@ def get_codec(config):
         register_codec(cls, codec_id=codec_id)
     if cls:
         return cls.from_config(config)
-    raise ValueError(f'codec not available: {codec_id!r}')
+    raise UnknownCodecError(f"{codec_id!r}")
 
 
 def register_codec(cls, codec_id=None):

numcodecs/tests/test_registry.py

@@ -3,11 +3,12 @@
 import pytest
 
 import numcodecs
+from numcodecs.errors import UnknownCodecError
 from numcodecs.registry import get_codec
 
 
 def test_registry_errors():
-    with pytest.raises(ValueError):
+    with pytest.raises(UnknownCodecError, match='foo'):
         get_codec({'id': 'foo'})