cleanup

Author: pavel-kirienko

demo/DemoMessage.1.0.dsdl

@@ -1,11 +1,10 @@
-# DemoMessage.1.0.dsdl
-# Self-contained demo type for serialization/deserialization demonstration
+# A simple demo type.
 
 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
+byte[<=64] binary_data    # Raw binary data
 
 @extent 1024 * 8

demo/demo_serdes.py

@@ -1,80 +1,59 @@
 #!/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
+Self-contained demo of PyDSDL serialization.
 """
 
 import pydsdl
 from pathlib import Path
 
+SCRIPT_DIR = Path(__file__).parent
+DSDL_FILE = SCRIPT_DIR / "DemoMessage.1.0.dsdl"
 
-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)
-    
+def main() -> None:
+    print("Loading DSDL type from:", DSDL_FILE.name)
     types, _ = pydsdl.read_files(
         dsdl_files=DSDL_FILE,
         root_namespace_directories_or_names=SCRIPT_DIR,
-        lookup_directories=[]
+        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")
+    print("Creating example object:")
     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]
+        "numeric_data": [1.0, 2.0, 3, 4],
+        "text_data": "Hello, SerDes!",
+        "binary_data": b"\x00\x01\x02\x03",
     }
-    
-    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")
+    print("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(f"✓ Serialized to {len(serialized_data)} bytes:")
+    print(f"  {serialized_data.hex()}")
 
-    print("\n[Step 4] Deserializing bytes back to object")
+    print("Deserializing bytes back to object")
     deserialized = pydsdl.deserialize(schema, serialized_data)
-    print("✓ Deserialized successfully")
-    print("  Deserialized structure:")
+    print("✓ Deserialized successfully:")
     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")
+    print("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

@@ -15,44 +15,18 @@ You can find a practical usage example in the Nunavut code generation library th
 The main functions
 ++++++++++++++++++
 
+DSDL parsing frint-end:
+
 .. autofunction:: pydsdl.read_namespace
 .. autofunction:: pydsdl.read_files
 
-
-Serialization
-+++++++++++++
-
-PyDSDL provides built-in serialization and deserialization functions for binary encoding/decoding
-of DSDL types without code generation.
+Data (de)serialization:
 
 .. 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
 ++++++++++
@@ -88,6 +62,12 @@ Exceptions
    :show-inheritance:
    :special-members:
 
+.. autoexception:: pydsdl.SerDesError
+   :undoc-members:
+   :no-inherited-members:
+   :show-inheritance:
+   :special-members:
+
 .. autoexception:: pydsdl.InternalError
    :undoc-members:
    :no-inherited-members:

pydsdl/__init__.py

@@ -31,10 +31,12 @@
 
 # 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
 
+# Deprecated compatibility alias, to be removed.
+FrontendError = Error
+
 # Data type model - meta types.
 from ._serializable import SerializableType as SerializableType
 from ._serializable import PrimitiveType as PrimitiveType
@@ -80,9 +82,5 @@
 from ._serdes import serialize as serialize
 from ._serdes import deserialize as deserialize
 from ._serdes import SerDesError as SerDesError
-from ._serdes import ArrayLengthError as ArrayLengthError
-from ._serdes import UnionFieldError as UnionFieldError
-from ._serdes import UnionTagError as UnionTagError
-from ._serdes import DelimiterHeaderError as DelimiterHeaderError
 
 _sys.path = _original_sys_path

pydsdl/_dsdl_definition.py

@@ -11,7 +11,7 @@
 from . import _parser
 from ._data_type_builder import DataTypeBuilder, UndefinedDataTypeError
 from ._dsdl import DefinitionVisitor, ReadableDSDLFile
-from ._error import FrontendError, InternalError, InvalidDefinitionError
+from ._error import Error, InternalError, InvalidDefinitionError
 from ._serializable import CompositeType, Version
 
 _logger = logging.getLogger(__name__)
@@ -275,7 +275,7 @@ def read(
                 self._cached_type.fixed_port_id,
             )
             return self._cached_type
-        except FrontendError as ex:  # pragma: no cover
+        except Error as ex:  # pragma: no cover
             ex.set_error_location_if_unknown(path=self.file_path)
             raise ex
         except (MemoryError, SystemError):  # pragma: no cover

pydsdl/_error.py

@@ -71,10 +71,6 @@ def __repr__(self) -> str:
         return self.__class__.__name__ + ": " + repr(self.__str__())
 
 
-# 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
@@ -138,7 +134,7 @@ def _unittest_error() -> None:
 def _unittest_internal_error_github_reporting() -> None:
     try:
         raise InternalError(path=Path("FILE_PATH"), line=42)
-    except FrontendError as ex:
+    except Error as ex:
         assert ex.path == Path("FILE_PATH")
         assert ex.line == 42
         assert str(ex) == "FILE_PATH:42: "
@@ -147,13 +143,13 @@ def _unittest_internal_error_github_reporting() -> None:
         try:
             try:  # TRY HARDER
                 raise InternalError(text="BASE TEXT", culprit=Exception("ERROR TEXT"))
-            except FrontendError as ex:
+            except Error as ex:
                 ex.set_error_location_if_unknown(path=Path("FILE_PATH"))
                 raise
-        except FrontendError as ex:
+        except Error as ex:
             ex.set_error_location_if_unknown(line=42)
             raise
-    except FrontendError as ex:
+    except Error as ex:
         print(ex)
         assert ex.path == Path("FILE_PATH")
         assert ex.line == 42
@@ -168,5 +164,5 @@ def _unittest_internal_error_github_reporting() -> None:
 
     try:
         raise InternalError(text="BASE TEXT", path=Path("FILE_PATH"))
-    except FrontendError as ex:
+    except Error as ex:
         assert str(ex) == "FILE_PATH: BASE TEXT"

pydsdl/_namespace.py

@@ -112,7 +112,7 @@ def read_namespace(
              version (newest version first). The ordering guarantee allows the caller to always find the newest version
              simply by picking the first matching occurrence.
 
-    :raises: :class:`pydsdl.FrontendError`, :class:`MemoryError`, :class:`SystemError`,
+    :raises: :class:`pydsdl.Error`, :class:`MemoryError`, :class:`SystemError`,
         :class:`OSError` if directories do not exist or inaccessible,
         :class:`ValueError`/:class:`TypeError` if the arguments are invalid.
     """
@@ -250,7 +250,7 @@ def read_files(
         fields that provide links back to the filesystem where the dsdl files were located when parsing the type;
         ``source_file_path`` and ``source_file_path_to_root``.
 
-    :raises: :class:`pydsdl.FrontendError`, :class:`MemoryError`, :class:`SystemError`,
+    :raises: :class:`pydsdl.Error`, :class:`MemoryError`, :class:`SystemError`,
         :class:`OSError` if directories do not exist or inaccessible,
         :class:`ValueError`/:class:`TypeError` if the arguments are invalid.
     """
@@ -366,7 +366,7 @@ def _construct_lookup_directories_path_list(
 
     :return: A list of lookup directories as paths.
 
-    :raises: :class:`pydsdl.FrontendError`, :class:`MemoryError`, :class:`SystemError`,
+    :raises: :class:`pydsdl.Error`, :class:`MemoryError`, :class:`SystemError`,
         :class:`OSError` if directories do not exist or inaccessible,
         :class:`ValueError`/:class:`TypeError` if the arguments are invalid.
     """

pydsdl/_namespace_reader.py

@@ -11,7 +11,7 @@
 
 from ._dsdl import DefinitionVisitor, DSDLFile, ReadableDSDLFile, PrintOutputHandler, SortedFileList
 from ._dsdl import file_sort as dsdl_file_sort
-from ._error import FrontendError, InternalError
+from ._error import Error, InternalError
 from ._serializable._composite import CompositeType
 
 
@@ -69,7 +69,7 @@ def print_handler(file: Path, line: int, message: str) -> None:
                 functools.partial(print_handler, target_definition.file_path),
                 allow_unregulated_fixed_port_id,
             )
-        except FrontendError as ex:  # pragma: no cover
+        except Error as ex:  # pragma: no cover
             ex.set_error_location_if_unknown(path=target_definition.file_path)
             raise ex
         except Exception as ex:  # pragma: no cover

pydsdl/_parser.py

@@ -29,7 +29,7 @@ def parse(text: str, statement_stream_processor: "StatementStreamProcessor", *,
     pr = _ParseTreeProcessor(statement_stream_processor, strict=strict)
     try:
         pr.visit(_get_grammar().parse(text))  # type: ignore
-    except _error.FrontendError as ex:
+    except _error.Error as ex:
         # Inject error location. If this exception is being propagated from a recursive instance, it already has
         # its error location populated, so nothing will happen here.
         ex.set_error_location_if_unknown(line=pr.current_line_number)
@@ -132,7 +132,7 @@ class _ParseTreeProcessor(parsimonious.NodeVisitor):
 
     # Intentional exceptions that shall not be treated as parse errors.
     # Beware that those might be propagated from recursive parser instances!
-    unwrapped_exceptions = (_error.FrontendError, SystemError, MemoryError, SystemExit)  # type: ignore
+    unwrapped_exceptions = (_error.Error, SystemError, MemoryError, SystemExit)  # type: ignore
 
     def __init__(self, statement_stream_processor: StatementStreamProcessor, *, strict: bool):
         assert isinstance(statement_stream_processor, StatementStreamProcessor)

pydsdl/_test.py

@@ -656,7 +656,7 @@ def standalone(rel_path: str, definition: str, allow_unregulated: bool = False)
                    """
             ),
         )
-    except _error.FrontendError as ex:
+    except _error.Error as ex:
         assert ex.path and ex.path.parts[-3:] == ("vendor", "types", "A.1.0.dsdl")
         assert ex.line and ex.line == 4
     else:  # pragma: no cover