EncodableType alias is now recursive

Closes #7

dag_cbor/__init__.py

@@ -2,13 +2,12 @@
     Python implementation of the `DAG-CBOR codec <https://ipld.io/specs/codecs/dag-cbor/spec/>`_ specification.
 """
 
-__version__ = "0.2.3"
+from __future__ import annotations # See https://peps.python.org/pep-0563/
 
-from .encoding import encode
+__version__ = "0.2.4"
+
+from .encoding import encode, EncodableType
 from .decoding import decode
 
 # explicit re-exports
-__all__ = [
-    "encode",
-    "decode"
-]
+__all__ = ["encode", "EncodableType", "decode"]

dag_cbor/encoding.py

@@ -2,11 +2,13 @@
     Encoding functions for DAG-CBOR codec.
 """
 
+from __future__ import annotations # See https://peps.python.org/pep-0563/
+
 from io import BufferedIOBase, BytesIO
 import math
 import struct
 from typing import Any, Dict, List, Optional, overload, Union
-from typing_validation import validate
+from typing_validation import validate, validation_aliases
 
 from multiformats import varint, multicodec, CID
 
@@ -17,12 +19,9 @@
     Union of non-container Python types that can be encoded by this implementation of the DAG-CBOR codec.
 """
 
-EncodableType = Union[FlatEncodableType, List[Any], Dict[str, Any]]
+EncodableType = Union[FlatEncodableType, List["EncodableType"], Dict[str, "EncodableType"]]
 """
-    Union of Python types that can be encoded (at top level) by this implementation of the DAG-CBOR codec.
-
-    Because of limited support for recursive types (see `Mypy issue #731 <https://github.com/python/mypy/issues/731>`_),
-    the list items and dictionary values are not recursively typechecked.
+    Union of Python types that can be encoded by this implementation of the DAG-CBOR codec.
 """
 
 _dag_cbor_multicodec = multicodec.get("dag-cbor")
@@ -85,7 +84,8 @@ def encode(data: EncodableType, stream: BufferedIOBase) -> int:
         :raises ~dag_cbor.utils.DAGCBOREncodingError: if a key of a dictionary is not a string
 
     """
-    validate(data, EncodableType)
+    with validation_aliases(EncodableType=EncodableType):
+        validate(data, EncodableType)
     validate(stream, Optional[BufferedIOBase])
     validate(include_multicodec, bool)
     if stream is None:

dag_cbor/random.py

@@ -3,6 +3,7 @@
 """
 # pylint: disable = global-statement
 
+from __future__ import annotations # See https://peps.python.org/pep-0563/
 
 from contextlib import contextmanager
 import math

dag_cbor/utils.py

@@ -13,6 +13,8 @@
       of the corresponding UTF-8 bytestrings (according to DAG-CBOR specification)
 """
 
+from __future__ import annotations # See https://peps.python.org/pep-0563/
+
 from typing import Any, Dict
 from typing_validation import validate
 

docs/api/dag_cbor.rst

@@ -8,5 +8,6 @@ dag_cbor.__all__
 
 The following members were explicitly reexported using ``__all__``:
 
+    - :py:obj:`typing.EncodableType`
     - :py:func:`dag_cbor.decoding.decode`
     - :py:func:`dag_cbor.encoding.encode`

docs/conf.py

@@ -28,9 +28,9 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = "0.2.0"
+release = "0.2.4"
 # The short X.Y version.
-version = "0.2.0"
+version = "0.2.4"
 
 
 # -- General configuration ---------------------------------------------------

docs/getting-started.rst

@@ -30,15 +30,6 @@ b'\xa2aa\x0cabfhello!'
 The :mod:`~dag_cbor.random` module contains functions to generate random data compatible with DAG-CBOR encoding.
 The :mod:`~dag_cbor.utils` module contains errors and utility functions.
 
-Please note that :mod:`dag_cbor` internally imports `multiformats <https://github.com/hashberg-io/multiformats>`_: if you'd like to initialise multiformats
-with a custom selection of multicodecs/multihashes, you should call ``multiformats_config.enable()`` **before** you import :mod:`dag_cbor` (see the `multiformats docs <https://multiformats.readthedocs.io/en/latest/getting-started.html>`_ for further details):
-
-.. code-block:: python
-
-    import multiformats_config
-    multiformats_config.enable(codecs=["sha1", 0x29], bases=["base64url", "9"])
-    import dag_cbor # internally imports multiformats
-
 
 The DAG-CBOR codec
 ------------------
@@ -61,3 +52,16 @@ The `DAG-CBOR codec <https://ipld.io/specs/codecs/dag-cbor/spec/>`_ is a restric
   are not allowed.
 
 Because the CBOR codec can encode/decode all data handled by the DAG-CBOR codec, we use an established CBOR implementation as the reference when testing, namely the `cbor2 <https://github.com/agronholm/cbor2>`_ package (with the exception of CID data, which is not natively handled by cbor2).
+
+
+Multiformats Config
+-------------------
+
+Please note that :mod:`dag_cbor` internally imports `multiformats <https://github.com/hashberg-io/multiformats>`_: if you'd like to initialise multiformats
+with a custom selection of multicodecs/multihashes, you should call ``multiformats_config.enable()`` **before** you import :mod:`dag_cbor` (see the `multiformats docs <https://multiformats.readthedocs.io/en/latest/getting-started.html>`_ for further details):
+
+.. code-block:: python
+
+    import multiformats_config
+    multiformats_config.enable(codecs=["sha1", 0x29], bases=["base64url", "9"])
+    import dag_cbor # internally imports multiformats

test_decode_error_messages.py

@@ -128,4 +128,4 @@ def print_decode_error(test_case: str) -> bool:
     print("==== Deep test cases ====")
     print()
     for idx, test_case in enumerate(deep_test_cases):
-        assert print_decode_error(test_case), f"Decoding of deep test case {idx} should have raised error."
+        assert print_decode_error(test_case), f"Decoding of deep test case {idx} should have raised error."