Clarify serdes dict contract in API docs

The serialize()/deserialize() public API operates on composite values represented as dictionaries, but the docstrings used wording that implied other return types were expected ("typically a dict"). This change tightens the wording to state the dict contract explicitly for both arguments and return values.

The module-level description in pydsdl/_serdes.py is also corrected to match actual behavior for array decoding: arrays are usually lists, while UTF-8 and byte arrays decode to str and bytes respectively.

To prevent regressions, a dedicated API test now verifies that deserialize() always returns dict for structure/union/delimited composites (including with delimiter headers) and that serialize() rejects non-dict composite inputs for the same schema categories.

Author: pavel-kirienko

pydsdl/_serdes.py

@@ -6,7 +6,8 @@
 The binary serialization module is a tiny addition to the main functionality of the library that uses instances of
 :class:`pydsdl.CompositeType` to build and parse serialized representations. This is an alternative approach to
 serialization that does not involve code generation compared to Nunavut et al.
-Deserialized objects are represented using Python primitives: composites are dicts, arrays are lists, etc.
+Deserialized objects are represented using Python primitives: composites are dicts; arrays are usually lists
+(UTF-8 arrays become ``str`` and byte arrays become ``bytes``).
 """
 
 from __future__ import annotations
@@ -84,7 +85,7 @@ def serialize(schema: CompositeType, obj: _Obj, *, with_delimiter_header: bool =
     Serialize a Python object to bytes according to the given schema.
 
     :param schema: The composite type schema defining the structure.
-    :param obj: The Python object to serialize (typically a dict).
+    :param obj: The Python object to serialize as a dict keyed by field name.
     :param with_delimiter_header: If True, prepend a delimiter header to the output.
     :return: The serialized bytes.
     :raises SerDesError: If serialization fails.
@@ -147,7 +148,7 @@ def deserialize(
     :param schema: The composite type schema defining the structure.
     :param data: The bytes to deserialize.
     :param with_delimiter_header: If True, expect and parse a delimiter header from the input.
-    :return: The deserialized Python object (typically a dict).
+    :return: The deserialized Python object as a dict keyed by field name.
     :raises SerDesError: If deserialization fails.
     :raises TypeError: If schema is a ServiceType.
     :raises ValueError: If with_delimiter_header=True on a non-delimited type.

pydsdl/_test_serdes.py

@@ -129,6 +129,46 @@ class MockStructureType(StructureType):
     assert hasattr(pydsdl, "SerDesError")
 
 
+def _unittest_serdes_api_dict_contract() -> None:
+    """
+    The public API operates on composite objects represented strictly as dict instances.
+    """
+    structure = _mk_structure("test.APIDictContractStruct", [Field(UnsignedIntegerType(8, CM.TRUNCATED), "x")])
+    union = _mk_union(
+        "test.APIDictContractUnion",
+        [Field(UnsignedIntegerType(8, CM.TRUNCATED), "a"), Field(UnsignedIntegerType(8, CM.TRUNCATED), "b")],
+    )
+    delimited_inner = _mk_structure("test.APIDictContractDelimitedInner", [Field(BooleanType(), "flag")])
+    delimited = DelimitedType(delimited_inner, delimited_inner.extent)
+
+    structure_result = deserialize(structure, serialize(structure, {"x": 42}))
+    assert isinstance(structure_result, dict)
+    assert structure_result == {"x": 42}
+
+    union_result = deserialize(union, serialize(union, {"b": 99}))
+    assert isinstance(union_result, dict)
+    assert union_result == {"b": 99}
+
+    delimited_payload = serialize(delimited, {"flag": True})
+    delimited_result = deserialize(delimited, delimited_payload)
+    assert isinstance(delimited_result, dict)
+    assert delimited_result == {"flag": True}
+
+    delimited_with_header = serialize(delimited, {"flag": True}, with_delimiter_header=True)
+    delimited_header_result = deserialize(delimited, delimited_with_header, with_delimiter_header=True)
+    assert isinstance(delimited_header_result, dict)
+    assert delimited_header_result == {"flag": True}
+
+    with pytest.raises(ValueError, match="Structure value must be a dict"):
+        serialize(structure, typing.cast(_Obj, typing.cast(object, 123)))
+
+    with pytest.raises(ValueError, match="Union value must be a dict"):
+        serialize(union, typing.cast(_Obj, typing.cast(object, 123)))
+
+    with pytest.raises(ValueError, match="Structure value must be a dict"):
+        serialize(delimited, typing.cast(_Obj, typing.cast(object, 123)))
+
+
 def _unittest_serdes_bit_writer() -> None:
     """
     Test _BitWriter with various bit lengths, cross-byte writes, and alignment.