feature: Nesting ErrorCatalogs

Author: lhaze

ROADMAP.md

@@ -6,7 +6,7 @@
 
 ### 0.2.0
 
-- [ ] Introducing nested catalogs
+- [x] Introducing nested catalogs
 - [ ] Beta release
 
 ### 1.0.0

pca/packages/errors/__init__.py

@@ -4,4 +4,4 @@
 from .types import *  # noqa: F401, F403
 
 
-VERSION = (0, 1, 0)
+VERSION = (0, 1, 0, "alpha", 0)

pca/packages/errors/builder.py

@@ -70,10 +70,9 @@ class ErrorMeta(type):
     * human-readable description of the error should be computed as late as possible (not earlier
       than on the presentation layer, where l10n & i18n process is made)
     * error instance should have a unique code
-    * error instance can have an area which describes its general topic
     * error instances can be gathered into catalogs which describe their common reason or a place
       to be raised
-    * an error instance is a value object, defined by their code and area
+    * an error instance is a value object, defined by their code
     * an error can have params, which can be used to pass some data specific for the place
       the instance is raised, but isn't considered a part of the value for checking instance
       equality

pca/packages/errors/catalog.py

@@ -10,13 +10,17 @@
 
 class ErrorCatalogMeta(type):
 
-    _registry: t.Dict[str, ExceptionWithCodeType]
+    __error_registry: t.Dict[str, ExceptionWithCodeType]
+    __subcatalog_registry: t.Dict[str, "ErrorCatalogMeta"]
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
-        self._registry = OrderedDict(
+        self.__error_registry = OrderedDict(
             (v.code, v) for _, v in self.__dict__.items() if is_error_class(v)
         )
+        self.__subcatalog_registry = OrderedDict(
+            (v.__name__, v) for _, v in self.__dict__.items() if isinstance(v, ErrorCatalogMeta)
+        )
 
     def __str__(self) -> str:
         return self.__name__
@@ -26,42 +30,69 @@ def __repr__(self) -> str:
 
     def __iter__(self) -> t.Iterator[ExceptionWithCodeType]:
         """Iterate over registered errors."""
-        yield from self._registry.values()
+        yield from self.__error_registry.values()
+        yield from (e for c in self.__subcatalog_registry.values() for e in c)
 
     def __len__(self) -> int:
-        return len(self._registry)
+        return len(self.all())
 
     def __contains__(self, item: ExceptionWithCodeType) -> bool:
-        return item in self._registry.values()
+        return item in self.all()
 
     def add_instance(self, error_class: ExceptionWithCodeType) -> None:
         """Registers an ExceptionWithCode subtype as an element of the ErrorCatalog."""
-        self._registry[error_class.code] = error_class
+        self.__error_registry[error_class.code] = error_class
         setattr(self, error_class.code, error_class)
         error_class.catalog = t.cast("ErrorCatalog", self)
 
     def all(self) -> t.Tuple[ExceptionWithCodeType, ...]:
-        return tuple(self._registry.values())
+        return tuple(self.__iter__())
+
+    def subcatalogs(self) -> t.Tuple["ErrorCatalogMeta", ...]:
+        return tuple(self.__subcatalog_registry.values())
 
 
 class ErrorCatalog(metaclass=ErrorCatalogMeta):
     """
     A class that can serve as a collection of named BaseErrors, gathered with a common reason.
     Instances of BaseErrors are meant to be declared as fields. Names of their fields may be
-    used as default value of `code` for each instance. The catalog may set default value of
-    `area` for all of them.
+    used as default value of `code` for each instance.
+
+    >>> class SomeCatalog(ErrorCatalog):
+    ...     SomeError = error_builder()
+    ...     AnotherError = error_builder("ExpliciteNameForAnotherError")
+
 
     Developers are encouraged to gather errors of their business logic into such error classes.
+    Such catalogs can be nested to structurize their relation further, in a form of a tree.
+
+    >>> class ExternalCatalog(ErrorCatalog):
+    ...     ExternalError = error_builder()
+
+    >>> class CompositeCatalog(ErrorCatalog):
+    ...     OwnError = error_builder()
+    ...     ExternalCatalogIncluded = ExternalCatalog
+    ...
+    ...     class NestedCatalog(ErrorCatalog):
+    ...         NestedError = error_builder()
+
+    >>> assert CompositeCatalog.all() == (
+    ...     CompositeCatalog.OwnError,
+    ...     ExternalCatalog.ExternalError,
+    ...     CompositeCatalog.NestedCatalog.NestedError
+    ... )
+
+
     If you want to reuse an error already attached to a catalog, use error's `clone` method
     like this:
 
     >>> class OldCatalog(ErrorCatalog):
-    ...     ERROR = ExceptionWithCode()
+    ...     OldError = error_builder()
 
     >>> class NewCatalog(ErrorCatalog):
-    ...     AN_EXISTING_ERROR = OldCatalog.ERROR.clone()
+    ...     AnExistingError = OldCatalog.OldError.clone()
 
-    >>> assert OldCatalog.ERROR == NewCatalog.AN_EXISTING_ERROR
-    >>> assert OldCatalog.ERROR.catalog == OldCatalog
-    >>> assert NewCatalog.AN_EXISTING_ERROR.catalog == NewCatalog
+    >>> assert OldCatalog.OldCatalog is not NewCatalog.AnExistingError
+    >>> assert OldCatalog.OldCatalog.catalog == OldCatalog
+    >>> assert NewCatalog.AnExistingError.catalog == NewCatalog
     """

tests/test_nested_catalog.py

@@ -0,0 +1,49 @@
+import typing as t
+
+from pca.packages.errors import (
+    ErrorCatalog,
+    ExceptionWithCode,
+    error_builder,
+)
+
+
+class ExternalCatalog(ErrorCatalog):
+    ExternalError: t.Type[ExceptionWithCode] = error_builder()
+
+
+class CompositeCatalog(ErrorCatalog):
+    OwnError: t.Type[ExceptionWithCode] = error_builder()
+    ExternalCatalog = ExternalCatalog
+
+    class NestedCatalog(ErrorCatalog):
+        NestedError: t.Type[ExceptionWithCode] = error_builder()
+
+
+def test_subcatalogs() -> None:
+    assert ExternalCatalog.subcatalogs() == ()
+    assert CompositeCatalog.subcatalogs() == (ExternalCatalog, CompositeCatalog.NestedCatalog)
+
+
+def test_repr() -> None:
+    assert repr(CompositeCatalog.NestedCatalog) == (
+        "test_nested_catalog.CompositeCatalog.NestedCatalog"
+    )
+    assert repr(CompositeCatalog.ExternalCatalog) == "test_nested_catalog.ExternalCatalog"
+
+
+def test_all() -> None:
+    assert CompositeCatalog.all() == (
+        CompositeCatalog.OwnError,
+        ExternalCatalog.ExternalError,
+        CompositeCatalog.NestedCatalog.NestedError,
+    )
+
+
+def test_len() -> None:
+    assert len(CompositeCatalog.NestedCatalog) == 1
+    assert len(CompositeCatalog) == 3
+
+
+def test_contains() -> None:
+    assert CompositeCatalog.NestedCatalog.NestedError in CompositeCatalog
+    assert ExternalCatalog.ExternalError in CompositeCatalog