From 6d090a3840339d02d71a67aac1001946ab45066b Mon Sep 17 00:00:00 2001
From: Cas Wognum <caswognum@outlook.com>
Date: Fri, 17 Jan 2025 14:01:55 -0500
Subject: [PATCH] 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 <dstansby@gmail.com>

* Make UnknownCodecError inherit from ValueError

---------

Co-authored-by: David Stansby <dstansby@gmail.com>
---
 docs/release.rst                 |  2 ++
 numcodecs/errors.py              | 26 ++++++++++++++++++++++++++
 numcodecs/registry.py            |  3 ++-
 numcodecs/tests/test_registry.py |  3 ++-
 4 files changed, 32 insertions(+), 2 deletions(-)
 create mode 100644 numcodecs/errors.py

diff --git a/docs/release.rst b/docs/release.rst
index a012703e..d6852001 100644
--- 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
new file mode 100644
index 00000000..78e048e6
--- /dev/null
+++ 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
index cc3f3f42..ccb5b26b 100644
--- 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
index 3c779df3..93ed8f03 100644
--- 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'})