Minor UX improvement: Add the UnknownCodecError. (zarr-developers#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]>
DimitriPapadopoulos · Jan 17, 2025 · 6d090a3 · 6d090a3
1 parent bd517ab
commit 6d090a3
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 2 deletions.
diff --git a/docs/release.rst b/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:
 

diff --git a/numcodecs/errors.py b/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}'")
diff --git a/numcodecs/registry.py b/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):

diff --git a/numcodecs/tests/test_registry.py b/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'})