feat(serdes): complete polish - Error rename, optimized bit I/O, enriched errors, docs, demo

Author: pavel-kirienko

.github/workflows/test-and-release.yml

@@ -46,12 +46,12 @@ jobs:
       - name: Run build and test
         run: |
           if [ "$RUNNER_OS" == "Linux" ]; then
-            nox --non-interactive --error-on-missing-interpreters --session test pristine lint --python ${{ matrix.python }}
+            nox --non-interactive --error-on-missing-interpreters --session test pristine lint demo --python ${{ matrix.python }}
             nox --non-interactive --session docs
           elif [ "$RUNNER_OS" == "Windows" ]; then
             nox --forcecolor --non-interactive --session test pristine lint
           elif [ "$RUNNER_OS" == "macOS" ]; then
-            nox --non-interactive --error-on-missing-interpreters --session test pristine lint --python ${{ matrix.python }}
+            nox --non-interactive --error-on-missing-interpreters --session test pristine lint demo --python ${{ matrix.python }}
           else
             echo "${{ runner.os }} not supported"
             exit 1

demo/DemoMessage.1.0.dsdl

@@ -0,0 +1,11 @@
+# DemoMessage.1.0.dsdl
+# Self-contained demo type for serialization/deserialization demonstration
+
+bool flag
+uint32 counter
+float64 temperature
+float32[4] numeric_data
+uint8[<=256] text_data    # UTF-8 encoded text data
+uint8[<=64] binary_data   # Raw binary data
+
+@extent 1024 * 8

demo/demo_serdes.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+Self-contained demo of pydsdl serialization and deserialization.
+
+Demonstrates the complete workflow:
+1. Load a custom DSDL type using read_files()
+2. Create an object using the representation convention (dict, list, str, bytes, primitives)
+3. Serialize the object to bytes
+4. Deserialize the bytes back to an object
+5. Verify roundtrip equality
+"""
+
+import pydsdl
+from pathlib import Path
+
+
+def main() -> None:
+    SCRIPT_DIR = Path(__file__).parent
+    DSDL_FILE = SCRIPT_DIR / "DemoMessage.1.0.dsdl"
+
+    print("=" * 70)
+    print("PyDSDL Serialization/Deserialization Demo")
+    print("=" * 70)
+
+    print("\n[Step 1] Loading DSDL type from:", DSDL_FILE.name)
+    
+    types, _ = pydsdl.read_files(
+        dsdl_files=DSDL_FILE,
+        root_namespace_directories_or_names=SCRIPT_DIR,
+        lookup_directories=[]
+    )
+    
+    schema = types[0]
+    print(f"✓ Loaded type: {schema.full_name} v{schema.version.major}.{schema.version.minor}")
+    print(f"  Fields: {[f.name for f in schema.fields_except_padding]}")
+
+    print("\n[Step 2] Creating example object")
+    print("  Representation convention: dict→struct, list→array, primitives as-is")
+    obj = {
+        "flag": True,
+        "counter": 42,
+        "temperature": 23.5,
+        "numeric_data": [1.0, 2.0, 3.0, 4.0],
+        "text_data": list("Hello, SerDes!".encode("utf-8")),
+        "binary_data": [0x00, 0x01, 0x02, 0x03]
+    }
+    
+    print("  Object structure:")
+    for key, value in obj.items():
+        value_repr = repr(value)
+        if len(value_repr) > 50:
+            value_repr = value_repr[:47] + "..."
+        print(f"    {key:15} = {value_repr} ({type(value).__name__})")
+
+    print("\n[Step 3] Serializing object to bytes")
+    serialized_data = pydsdl.serialize(schema, obj)
+    print(f"✓ Serialized to {len(serialized_data)} bytes")
+    print(f"  Hex: {serialized_data.hex()}")
+
+    print("\n[Step 4] Deserializing bytes back to object")
+    deserialized = pydsdl.deserialize(schema, serialized_data)
+    print("✓ Deserialized successfully")
+    print("  Deserialized structure:")
+    for key, value in deserialized.items():
+        value_repr = repr(value)
+        if len(value_repr) > 50:
+            value_repr = value_repr[:47] + "..."
+        print(f"    {key:15} = {value_repr} ({type(value).__name__})")
+
+    print("\n[Step 5] Verifying roundtrip equality")
+    assert obj == deserialized, "Roundtrip failed! Objects don't match."
+    print("✓ Roundtrip verification passed: Original == Deserialized")
+
+    print("\n" + "=" * 70)
+    print("Demo completed successfully!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

docs/pages/pydsdl.rst

@@ -19,6 +19,41 @@ The main functions
 .. autofunction:: pydsdl.read_files
 
 
+Serialization
++++++++++++++
+
+PyDSDL provides built-in serialization and deserialization functions for binary encoding/decoding
+of DSDL types without code generation.
+
+.. autofunction:: pydsdl.serialize
+.. autofunction:: pydsdl.deserialize
+
+Object Representation Convention
+---------------------------------
+
+Deserialized objects use Python primitives:
+
+- **Composites (StructureType)**: ``dict[str, Any]`` with field names as keys
+- **Unions (UnionType)**: ``dict`` with exactly one key (the active variant)
+- **Arrays (Fixed/Variable)**: ``list``
+- **UTF-8 arrays**: ``str``
+- **Byte arrays**: ``bytes``
+- **Primitives**: ``bool``, ``int``, ``float``
+- **Void**: ``None`` (skipped in output)
+
+Example::
+
+    obj = {"flag": True, "values": [1, 2, 3], "text": "hello"}
+    data = pydsdl.serialize(schema, obj)
+    reconstructed = pydsdl.deserialize(schema, data)
+    assert obj == reconstructed
+
+See ``demo/demo_serdes.py`` for a complete working example.
+
+.. autoexception:: pydsdl.SerDesError
+   :show-inheritance:
+
+
 Type model
 ++++++++++
 
@@ -36,14 +71,17 @@ Exceptions
 
 .. computron-injection::
     :filename: ../descendant_diagram.py
-    :argv: FrontendError
+    :argv: Error
 
-.. autoexception:: pydsdl.FrontendError
+.. autoexception:: pydsdl.Error
    :undoc-members:
    :no-inherited-members:
    :show-inheritance:
    :special-members:
 
+.. note::
+   ``FrontendError`` is retained as a backward-compatibility alias for ``Error``.
+
 .. autoexception:: pydsdl.InvalidDefinitionError
    :undoc-members:
    :no-inherited-members:

noxfile.py

@@ -72,6 +72,13 @@ def pristine(session):
     exe("import pydsdl")
 
 
+@nox.session(python=PYTHONS[-1:])
+def demo(session):
+    """Run the serialization/deserialization demo script."""
+    session.install("-e", ".")
+    session.run("python", "demo/demo_serdes.py")
+
+
 @nox.session(python=PYTHONS, reuse_venv=True)
 def lint(session):
     session.log("Using the newest supported Python: %s", is_latest_python(session))

pydsdl/__init__.py

@@ -30,6 +30,7 @@
 from ._namespace import read_files as read_files
 
 # Error model.
+from ._error import Error as Error
 from ._error import FrontendError as FrontendError
 from ._error import InvalidDefinitionError as InvalidDefinitionError
 from ._error import InternalError as InternalError

pydsdl/_error.py

@@ -9,7 +9,7 @@
 import urllib.parse
 
 
-class FrontendError(Exception):  # PEP8 says that the "Exception" suffix is redundant and should not be used.
+class Error(Exception):  # PEP8 says that the "Exception" suffix is redundant and should not be used.
     """
     This is the root exception type for all custom exceptions defined in the library.
     This type itself is not expected to be particularly useful to the library user;
@@ -71,7 +71,11 @@ def __repr__(self) -> str:
         return self.__class__.__name__ + ": " + repr(self.__str__())
 
 
-class InternalError(FrontendError):
+# Backward compatibility alias
+FrontendError = Error
+
+
+class InternalError(Error):
     """
     This exception is used to report internal errors in the front end itself that prevented it from
     processing the definitions. Every occurrence should be reported to the developers.
@@ -100,7 +104,7 @@ def __init__(
         super().__init__(text=text, path=path, line=line)
 
 
-class InvalidDefinitionError(FrontendError):
+class InvalidDefinitionError(Error):
     """
     This exception type is used to point out mistakes and errors in DSDL definitions.
     This type is inherited by a dozen of specialized exception types; however, the class hierarchy beneath
@@ -113,21 +117,21 @@ class InvalidDefinitionError(FrontendError):
 
 def _unittest_error() -> None:
     try:
-        raise FrontendError("Hello world!")
+        raise Error("Hello world!")
     except Exception as ex:
         assert str(ex) == "Hello world!"
-        assert repr(ex) == "FrontendError: 'Hello world!'"
+        assert repr(ex) == "Error: 'Hello world!'"
 
     try:
-        raise FrontendError("Hello world!", path=Path("path/to/file.dsdl"), line=123)
+        raise Error("Hello world!", path=Path("path/to/file.dsdl"), line=123)
     except Exception as ex:
         assert str(ex) == "path/to/file.dsdl:123: Hello world!"
-        assert repr(ex) == "FrontendError: 'path/to/file.dsdl:123: Hello world!'"
+        assert repr(ex) == "Error: 'path/to/file.dsdl:123: Hello world!'"
 
     try:
-        raise FrontendError("Hello world!", path=Path("path/to/file.dsdl"))
+        raise Error("Hello world!", path=Path("path/to/file.dsdl"))
     except Exception as ex:
-        assert repr(ex) == "FrontendError: 'path/to/file.dsdl: Hello world!'"
+        assert repr(ex) == "Error: 'path/to/file.dsdl: Hello world!'"
         assert str(ex) == "path/to/file.dsdl: Hello world!"