ltcodecs 4.4.2__tar.gz → 4.5.1__tar.gz

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltcodecs
-Version: 4.4.2
+Version: 4.5.1
 Summary: LT Codecs: Lightweight codecs for use over low-throughput links
 Author: Woods Hole Oceanographic Institution, Acoustic Communications Group
 License: LGPL-3.0-or-later
@@ -16,7 +16,7 @@ Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: armw
-Requires-Dist: bitstring
+Requires-Dist: bitstring<5,>=4
 Requires-Dist: msgpack
 Requires-Dist: crccheck
 Requires-Dist: rospy-yaml-include

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/docs/codec_configs.rst

@@ -284,6 +284,30 @@ target fields use no bits.
 The input dictionary or ROS message must contain both ``has_extra`` and
 ``extra`` when ``has_extra`` is true.
 
+Array-Optional Fields
+---------------------
+
+Use ``variable_len_array_optional`` when the presence of additional fields
+depends on a variable-length array. It uses the same array parameters as
+``variable_len_array``. By default, ``target_fields`` are encoded immediately
+after the array only when the encoded array is nonempty. Set
+``target_fields_length_threshold`` to require more than that many elements.
+
+.. code-block:: yaml
+
+   samples:
+     codec: variable_len_array_optional
+     element_type: uint8
+     max_length: 10
+     target_fields:
+       sample_time:
+         codec: uint32
+         value: 0
+
+When ``samples`` is empty, ``sample_time`` uses no bits and decodes to ``0``.
+Without ``value``, the field is absent from the decoded result. When the array
+is nonempty, the input must provide ``sample_time`` and its value is encoded.
+
 Padding
 -------
 

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/docs/reference/codec_aliases.rst

@@ -51,6 +51,9 @@ Alias                     Codec Class
 ``variable_len_bit_array``
    :py:class:`~ltcodecs.variable_len_bit_array_codec.VariableLenBitArrayCodec`
 
+``variable_len_array_optional``
+   :py:class:`~ltcodecs.variable_len_array_optional_codec.VariableLenArrayOptionalCodec`
+
 Metadata Aliases
 ----------------
 

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/docs/reference/codecs.rst

@@ -85,6 +85,10 @@ Container Codecs
    and a three-bit count of unused final-byte bits. Configure the derived field
    with ``bit_length_field``; it is not a separate configured wire field.
 
+``variable_len_array_optional``
+   Encodes a variable-length array followed by ``target_fields`` when the
+   encoded array length exceeds ``target_fields_length_threshold`` (default 0).
+
 ``fixed_len_array``
    Encodes a fixed number of elements.  The encoded bitstream does not include
    a length field, so the decoder always reads ``length`` elements.

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/docs/reference/config_schema.rst

@@ -38,8 +38,9 @@ Common Field Keys
    codecs.
 
 ``min_length``
-   Minimum number of elements for ``variable_len_array``.  Encoding fails when
-   the provided list is shorter than this value.
+   Minimum number of elements for ``variable_len_array`` and
+   ``variable_len_array_optional``. Encoding fails when the provided list is
+   shorter than this value.
 
 ``length_mode``
    Length handling mode for ``string``, ``bytes``, and
@@ -69,7 +70,13 @@ Common Field Keys
    absent/present bit.
 
 ``target_fields``
-   Field mapping controlled by an ``optional`` field.
+   Field mapping controlled by an ``optional`` or
+   ``variable_len_array_optional`` field. For the latter, an individual target
+   may set ``value`` to supply its decoded value when it is not encoded.
+
+``target_fields_length_threshold``
+   For ``variable_len_array_optional``, target fields are present when the
+   encoded array length is greater than this value. Defaults to 0.
 
 ``ros_type``
    ROS message type for ``msg`` fields.  ROS 1 and ROS 2 type names are

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/docs/reference/python_api.rst

@@ -197,6 +197,14 @@ ltcodecs.variable\_len\_array\_codec module
    :undoc-members:
    :show-inheritance:
 
+ltcodecs.variable\_len\_array\_optional\_codec module
+-----------------------------------------------------
+
+.. automodule:: ltcodecs.variable_len_array_optional_codec
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 ltcodecs.variable\_len\_bit\_array\_codec module
 ---------------------------------------------------
 

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/pyproject.toml

@@ -11,7 +11,7 @@ classifiers = [
     "Topic :: Scientific/Engineering",
 ]
 requires-python = ">=3.6"
-dependencies = ["armw", "bitstring", "msgpack", "crccheck", "rospy-yaml-include"]
+dependencies = ["armw", "bitstring>=4,<5", "msgpack", "crccheck", "rospy-yaml-include"]
 
 readme = {file = "README.md", content-type = "text/markdown"}
 
@@ -32,7 +32,12 @@ inspect_codec = "ltcodecs.inspect_cli:main"
 # No optional dependencies
 
 [build-system]
-requires = ["setuptools>=64", "wheel", "setuptools_scm>=8"]
+requires = [
+    "setuptools>=64",
+    "wheel",
+    "setuptools_scm>=8; python_version >= '3.8'",
+    "setuptools_scm>=7,<8; python_version < '3.8'",
+]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools_scm]

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/src/ltcodecs/__init__.py

@@ -12,6 +12,7 @@ from .string_enum_codec import StringEnumCodec
 from .bytes_codec import BytesCodec
 from .metadata_field_codec import MetadataFieldCodec
 from .variable_len_array_codec import VariableLenArrayCodec
+from .variable_len_array_optional_codec import VariableLenArrayOptionalCodec
 from .variable_len_bit_array_codec import VariableLenBitArrayCodec
 from .fixed_len_array_codec import FixedLenArrayCodec
 from .dict_field_codec import DictFieldCodec
@@ -56,6 +57,7 @@ field_codec_classes = {
     "msg": RosMsgFieldCodec,
     "ros_msg": RosMsgFieldCodec,
     "variable_len_array": VariableLenArrayCodec,
+    "variable_len_array_optional": VariableLenArrayOptionalCodec,
     "variable_len_bit_array": VariableLenBitArrayCodec,
     "fixed_len_array": FixedLenArrayCodec,
     "ccl_latlon": CclLatLonCodec,

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/src/ltcodecs/inspection.py

@@ -209,9 +209,9 @@ class CodecInspector:
                 continue
             if codec_name in ("dict", "dictionary"):
                 issues.extend(cls._validate_fields(params.get("fields"), path))
-            elif codec_name == "optional":
+            elif codec_name in ("optional", "variable_len_array_optional"):
                 issues.extend(cls._validate_fields(params.get("target_fields"), path))
-            elif codec_name in ("variable_len_array", "fixed_len_array"):
+            if codec_name in ("variable_len_array", "variable_len_array_optional", "fixed_len_array"):
                 element_type = params.get("element_type")
                 if not isinstance(element_type, str):
                     issues.append(ValidationIssue(path, "Missing required string parameter 'element_type'"))
@@ -269,6 +269,28 @@ class CodecInspector:
                 cls._make_conditional(child)
             return FieldReport(path, codec_name, "controls following fields", 1, 1 + child_max, children), []
 
+        if codec_name == "variable_len_array_optional":
+            array_params = dict(params)
+            array_params["codec"] = "variable_len_array"
+            array_report, issues = cls._inspect_array(array_params, path)
+            if issues:
+                return None, issues
+            children, issues, _child_min, child_max = cls._inspect_fields(params["target_fields"], path)
+            if issues:
+                return None, issues
+            try:
+                field_codec = ltcodecs.VariableLenArrayOptionalCodec(**params)
+            except Exception as err:
+                return None, [ValidationIssue(path, str(err))]
+            if field_codec.array_codec.min_length <= field_codec.target_fields_length_threshold:
+                for child in children:
+                    cls._make_conditional(child)
+            return FieldReport(
+                path, codec_name, "array controls following fields",
+                field_codec.min_length_bits, field_codec.max_length_bits,
+                array_report.children + children,
+            ), []
+
         if codec_name in ("variable_len_array", "fixed_len_array"):
             return cls._inspect_array(params, path)
 

ltcodecs-4.5.1/src/ltcodecs/variable_len_array_optional_codec.py

@@ -0,0 +1,103 @@
+"""Variable-length arrays that control optional fields."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+
+from bitstring import BitArray, ConstBitStream
+
+import ltcodecs as ltcodecs
+
+from .exceptions import EncodingFailed
+from .field_codec import encode_configured_field
+from .multiple_field_codec import MultipleFieldCodec
+from .variable_len_array_codec import VariableLenArrayCodec
+
+
+class VariableLenArrayOptionalCodec(MultipleFieldCodec):
+    """Encode an array, followed by target fields when its length exceeds a threshold.
+
+    Array parameters match :class:`VariableLenArrayCodec`. The default
+    ``target_fields_length_threshold`` of zero includes targets for any
+    nonempty encoded array. A target field's optional ``value`` parameter
+    supplies its decoded value when the array omits that target.
+    """
+
+    def __init__(
+        self, element_type: str, max_length: int, target_fields: dict,
+        target_fields_length_threshold: int = 0, **kwargs,
+    ) -> None:
+        if not isinstance(target_fields_length_threshold, int) or not 0 <= target_fields_length_threshold < max_length:
+            raise ValueError("target_fields_length_threshold must be an integer from 0 to max_length - 1")
+        if kwargs.get("length_mode") == "fill_outer":
+            raise ValueError("VariableLenArrayOptionalCodec requires an encoded array length")
+
+        self.array_codec = VariableLenArrayCodec(
+            element_type=element_type, max_length=max_length, **kwargs
+        )
+        self.target_fields = target_fields or {}
+        self.target_fields_length_threshold = target_fields_length_threshold
+        self.absent_values = {
+            field_name: field_params["value"]
+            for field_name, field_params in self.target_fields.items()
+            if "value" in field_params
+        }
+        self.field_codecs = {}
+        for field_name, field_params in self.target_fields.items():
+            try:
+                self.field_codecs[field_name] = ltcodecs.field_codec_classes[field_params["codec"]](**field_params)
+            except KeyError as err:
+                raise KeyError(
+                    f"Error parsing codec config for {field_name}. Got params:\n{field_params}\nError: {err}"
+                ) from err
+
+    def encode_multiple(self, value: list, message_dict: dict) -> tuple[BitArray, list, dict]:
+        bits, encoded_array = self.array_codec.encode(value)
+        if len(encoded_array) <= self.target_fields_length_threshold:
+            return bits, encoded_array, deepcopy(self.absent_values)
+
+        encoded_fields = {}
+        for field_name in self.target_fields:
+            field_codec = self.field_codecs[field_name]
+            try:
+                if isinstance(field_codec, MultipleFieldCodec):
+                    field_bits, encoded_fields[field_name], extra_fields = field_codec.encode_multiple(
+                        message_dict[field_name], message_dict
+                    )
+                    encoded_fields.update(extra_fields)
+                else:
+                    field_bits, encoded_fields[field_name] = encode_configured_field(
+                        field_codec, message_dict, field_name
+                    )
+                bits.append(field_bits)
+            except Exception as err:
+                raise EncodingFailed(f'Error encoding target field "{field_name}"') from err
+        return bits, encoded_array, encoded_fields
+
+    def decode_multiple(self, bits_to_decode: ConstBitStream) -> tuple[list, dict]:
+        decoded_array = self.array_codec.decode(bits_to_decode)
+        if len(decoded_array) <= self.target_fields_length_threshold:
+            return decoded_array, deepcopy(self.absent_values)
+
+        decoded_fields = {}
+        for field_name in self.target_fields:
+            field_codec = self.field_codecs[field_name]
+            if isinstance(field_codec, MultipleFieldCodec):
+                decoded_fields[field_name], extra_fields = field_codec.decode_multiple(bits_to_decode)
+                decoded_fields.update(extra_fields)
+            else:
+                decoded_fields[field_name] = field_codec.decode(bits_to_decode)
+        return decoded_array, decoded_fields
+
+    @property
+    def min_length_bits(self) -> int:
+        target_bits = 0
+        if self.array_codec.min_length > self.target_fields_length_threshold:
+            target_bits = sum(codec.min_length_bits for codec in self.field_codecs.values())
+        return self.array_codec.min_length_bits + target_bits
+
+    @property
+    def max_length_bits(self) -> int:
+        return self.array_codec.max_length_bits + sum(
+            codec.max_length_bits for codec in self.field_codecs.values()
+        )

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/src/ltcodecs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltcodecs
-Version: 4.4.2
+Version: 4.5.1
 Summary: LT Codecs: Lightweight codecs for use over low-throughput links
 Author: Woods Hole Oceanographic Institution, Acoustic Communications Group
 License: LGPL-3.0-or-later
@@ -16,7 +16,7 @@ Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: armw
-Requires-Dist: bitstring
+Requires-Dist: bitstring<5,>=4
 Requires-Dist: msgpack
 Requires-Dist: crccheck
 Requires-Dist: rospy-yaml-include

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/src/ltcodecs.egg-info/SOURCES.txt

@@ -48,6 +48,7 @@ src/ltcodecs/rostime_codec.py
 src/ltcodecs/string_codecs.py
 src/ltcodecs/string_enum_codec.py
 src/ltcodecs/variable_len_array_codec.py
+src/ltcodecs/variable_len_array_optional_codec.py
 src/ltcodecs/variable_len_bit_array_codec.py
 src/ltcodecs/varint_codec.py
 src/ltcodecs.egg-info/PKG-INFO

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/src/ltcodecs.egg-info/requires.txt

@@ -1,5 +1,5 @@
 armw
-bitstring
+bitstring<5,>=4
 msgpack
 crccheck
 rospy-yaml-include

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/src/ltcodecs.egg-info/scm_file_list.json

@@ -50,6 +50,7 @@
     "src/ltcodecs/string_codecs.py",
     "src/ltcodecs/string_enum_codec.py",
     "src/ltcodecs/variable_len_array_codec.py",
+    "src/ltcodecs/variable_len_array_optional_codec.py",
     "src/ltcodecs/variable_len_bit_array_codec.py",
     "src/ltcodecs/varint_codec.py",
     "tests/__init__.py",

ltcodecs-4.5.1/src/ltcodecs.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "4.5.1",
+  "distance": 0,
+  "node": "g9f9b23b3e2382e44090cbdcbfb1c66e66c2b621a",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-21"
+}

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/tests/test_codecs.py

@@ -600,6 +600,71 @@ class TestCodecs:
         assert isinstance(decoded["nested"], String)
         assert decoded["nested"].data == msg.data
 
+    def test_variable_len_array_optional_length_controls_targets(self) -> None:
+        # An empty array carries no target bits; a nonempty array carries both targets.
+        codec = ltcodecs.VariableLenArrayOptionalCodec(
+            element_type="uint8",
+            max_length=3,
+            target_fields={
+                "sample_time": {"codec": "uint8", "value": 0},
+                "quality": {"codec": "uint8"},
+            },
+        )
+
+        empty_bits, empty_array, empty_fields = codec.encode_multiple([], {})
+        decoded_array, decoded_fields = codec.decode_multiple(ConstBitStream(empty_bits))
+        assert empty_array == decoded_array == []
+        assert empty_fields == decoded_fields == {"sample_time": 0}
+        assert len(empty_bits) == len(codec.array_codec.encode([])[0])
+
+        source = {"sample_time": 37, "quality": 5}
+        present_bits, present_array, present_fields = codec.encode_multiple([9], source)
+        decoded_array, decoded_fields = codec.decode_multiple(ConstBitStream(present_bits))
+        assert present_array == decoded_array == [9]
+        assert present_fields == decoded_fields == source
+        assert len(present_bits) == len(codec.array_codec.encode([9])[0]) + 16
+
+    def test_variable_len_array_optional_copies_absent_value(self) -> None:
+        # Mutating one decoded fallback must not change later decoded messages.
+        codec = ltcodecs.VariableLenArrayOptionalCodec(
+            element_type="uint8",
+            max_length=2,
+            target_fields={
+                "details": {
+                    "codec": "dict",
+                    "fields": {"count": {"codec": "uint8"}},
+                    "value": {"count": 0},
+                },
+            },
+        )
+
+        bits, _, _ = codec.encode_multiple([], {})
+        first = codec.decode_multiple(ConstBitStream(bits))[1]
+        first["details"]["count"] = 99
+        second = codec.decode_multiple(ConstBitStream(bits))[1]
+        assert second == {"details": {"count": 0}}
+
+    def test_variable_len_array_optional_absent_value_matches_checksum(self) -> None:
+        # The checksum must use the same fallback or wire value that decode returns.
+        codec = ltcodecs.DictCodec(
+            {
+                "samples": {
+                    "codec": "variable_len_array_optional",
+                    "element_type": "uint8",
+                    "max_length": 2,
+                    "target_fields": {"sample_time": {"codec": "uint8", "value": 0}},
+                },
+            },
+            checksum="crc8",
+        )
+
+        for source, expected in (
+            ({"samples": []}, {"samples": [], "sample_time": 0}),
+            ({"samples": [9], "sample_time": 37}, {"samples": [9], "sample_time": 37}),
+        ):
+            bits, _ = codec.encode(source)
+            assert codec.decode(ConstBitStream(bits)) == expected
+
     def test_ros_message_field_codec(self) -> None:
         """test functionality of the ros message field codec"""
 

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/tests/test_dict_codec.py

@@ -184,3 +184,64 @@ def test_dict_codec_variable_length_bit_array_derives_bit_length() -> None:
     decoded_msg = codec.decode(ConstBitStream(encoded_msg[0]))
 
     assert decoded_msg == {"payload": [0xAB, 0xC0], "payload_size_in_bits": 13}
+
+
+def test_variable_len_array_optional_omits_targets_for_empty_array() -> None:
+    # At the dictionary boundary, target fields appear only for nonempty arrays.
+    codec = ltcodecs.DictCodec({
+        "samples": {
+            "codec": "variable_len_array_optional",
+            "element_type": "uint8",
+            "max_length": 4,
+            "target_fields": {"sample_time": {"codec": "uint32"}},
+        },
+    })
+
+    for source in ({"samples": []}, {"samples": [3, 5], "sample_time": 123}):
+        bits, encoded = codec.root_field_codec.encode(source)
+        assert encoded == source
+        assert codec.decode(ConstBitStream(bits)) == source
+
+
+def test_variable_len_array_optional_uses_encoded_length_and_threshold() -> None:
+    # With a threshold of one, one element omits targets and two include them.
+    codec = ltcodecs.DictCodec({
+        "samples": {
+            "codec": "variable_len_array_optional",
+            "element_type": "uint8",
+            "max_length": 2,
+            "target_fields_length_threshold": 1,
+            "target_fields": {"sample_time": {"codec": "uint32"}},
+        },
+    })
+
+    for source in ({"samples": [3]}, {"samples": [3, 5], "sample_time": 123}):
+        bits, encoded = codec.root_field_codec.encode(source)
+        assert codec.decode(ConstBitStream(bits)) == encoded
+
+    # Truncation to max_length determines the array length used on the wire.
+    bits, encoded = codec.root_field_codec.encode({"samples": [3, 5, 7], "sample_time": 123})
+    assert encoded == {"samples": [3, 5], "sample_time": 123}
+    assert codec.decode(ConstBitStream(bits)) == encoded
+
+
+def test_variable_len_array_optional_supports_nested_target_controller() -> None:
+    # A present target can itself control another optional field.
+    codec = ltcodecs.DictCodec({
+        "samples": {
+            "codec": "variable_len_array_optional",
+            "element_type": "uint8",
+            "max_length": 2,
+            "target_fields": {
+                "has_extra": {
+                    "codec": "optional",
+                    "target_fields": {"extra": {"codec": "uint8"}},
+                },
+            },
+        },
+    })
+    source = {"samples": [1], "has_extra": True, "extra": 9}
+
+    bits, encoded = codec.root_field_codec.encode(source)
+    assert encoded == source
+    assert codec.decode(ConstBitStream(bits)) == source

{ltcodecs-4.4.2 → ltcodecs-4.5.1}/tests/test_inspection.py

@@ -31,6 +31,38 @@ def test_inspect_fields_reports_nested_and_optional_sizes() -> None:
     assert (optional_target.min_length_bits, optional_target.max_length_bits) == (0, 8)
 
 
+def test_inspect_array_controlled_fields() -> None:
+    # With an empty array allowed, the target contributes zero minimum bits.
+    report = CodecInspector.inspect_fields({
+        "samples": {
+            "codec": "variable_len_array_optional",
+            "element_type": "uint8",
+            "max_length": 3,
+            "target_fields": {"sample_time": {"codec": "uint32"}},
+        },
+    })
+
+    assert report.is_valid
+    assert report.fields[0].children[0].path == "samples[]"
+    assert report.fields[0].children[1].path == "samples.sample_time"
+    assert report.fields[0].children[1].min_length_bits == 0
+    assert report.max_length_bits == 58
+
+    # Requiring an element makes the target mandatory in the size report.
+    required = CodecInspector.inspect_fields({
+        "samples": {
+            "codec": "variable_len_array_optional",
+            "element_type": "uint8",
+            "max_length": 3,
+            "min_length": 1,
+            "target_fields": {"sample_time": {"codec": "uint32"}},
+        },
+    })
+    assert required.is_valid
+    assert required.fields[0].children[1].min_length_bits == 32
+    assert required.min_length_bits == 42
+
+
 def test_inspect_file_resolves_include_directory(tmp_path: Path) -> None:
     include_directory = tmp_path / "includes"
     include_directory.mkdir()

ltcodecs-4.4.2/src/ltcodecs.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "4.4.2",
-  "distance": 0,
-  "node": "ga9636d4658ff2656726da9b973e30356019e708d",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-13"
-}