sltcodec 2.0.0__tar.gz → 2.1.1__tar.gz

{sltcodec-2.0.0 → sltcodec-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sltcodec
-Version: 2.0.0
+Version: 2.1.1
 Summary: Decode and encode bytearrays according to struct layout definitions using sltcore.
 Project-URL: Homepage, https://github.com/fangface-hub/StructLayoutToolkitCodec
 Project-URL: Documentation, https://readthedocs.org
@@ -63,6 +63,12 @@ encoded = encode(layout, instance, bytearray())
 decoded = decode(layout, encoded)
 ```
 
+`decode` returns a `StructInstance` whose `size` is the actual end of the
+decoded layout. `decode_field` stores the actual decoded size in the returned
+`FieldInstance.field_def.size`. For nested `StructDef` fields, that size comes
+from the nested `StructInstance.size`; for repeated fields, the next element's
+offset advances by the actual size of the previous element.
+
 ## Field Types
 
 The public `PRIMITIVE_TYPES` set contains:
@@ -78,7 +84,6 @@ The public `PRIMITIVE_TYPES` set contains:
 Store named structures in `TypeDict.struct_dict` and enums in `TypeDict.enum_dict`. A field refers to an enum by its `enum_def_name`; the codec resolves it through `StructLayout.type_dict`.
 
 ```python
-| `__lt__(other)` | Compare enum definitions using their serialized ordering. |
 from sltcore import InfoSize
 from sltcodec import EnumDef, FieldDef, StructDef, StructLayout, TypeDict, decode
 
@@ -102,7 +107,6 @@ layout = StructLayout(
 )
 
 decoded = decode(layout, bytearray(b"\x01"))
-| `__lt__(other)` | Compare field definitions using their serialized ordering. |
 assert decoded.field_instances[0].enum_item == ("NG", 1)
 ```
 
@@ -117,7 +121,6 @@ from sltcodec import load_struct_layout, save_struct_layout
 path = Path("struct_layout.json")
 save_struct_layout(layout, path)
 loaded = load_struct_layout(path)
-| `__lt__(other)` | Compare field instances using field-definition order. |
 assert loaded == layout
 ```
 
@@ -185,7 +188,6 @@ internal implementation details and are omitted from the public method tables.
 
 | Method | Description |
 | --- | --- |
-| `split_repeat(index, offset=None, size=None)` | Create one field definition from a repeated field. |
 | `to_dict()` | Convert the definition to a JSON-compatible dictionary. |
 | `to_json()` | Convert the definition to a JSON string. |
 | `from_dict(data)` | Create a `FieldDef` from a dictionary. |
@@ -205,6 +207,7 @@ internal implementation details and are omitted from the public method tables.
 | --- | --- |
 | `range_check(env=None)` | Evaluate the field's range expression. |
 | `from_value(field_def, value, type_dict=None, is_padding=False)` | Create an instance and resolve matching enum metadata. |
+| `with_value(value, type_dict=None)` | Return a new instance with the given value; keeps `field_def` and `is_padding` and recomputes `enum_item`. |
 | `__lt__(other)` | Compare field instances using field-definition order. |
 
 #### `StructDef`

{sltcodec-2.0.0 → sltcodec-2.1.1}/README.md

@@ -61,6 +61,25 @@ Layout persistence uses the explicit names `save_struct_layout` and
 `load_struct_layout`. The former `save_type_dict` and `load_type_dict` API is
 not part of the current public interface.
 
+`FieldInstance` stays frozen. To change a decoded value, use
+`FieldInstance.with_value(value, type_dict=None)`, which returns a new
+instance instead of mutating the original. It keeps `field_def` and
+`is_padding`, and recomputes `enum_item` from the new value and `type_dict`
+by delegating to `FieldInstance.from_value`.
+
+```python
+updated_field = field_instance.with_value(
+    new_value,
+    struct_layout.type_dict,
+)
+```
+
+Decoded sizes reflect the actual data consumed. `decode` sets
+`StructInstance.size` to the end of the decoded layout, and `decode_field`
+stores the actual size in `FieldInstance.field_def.size`. For nested structures,
+the nested `StructInstance.size` is used; repeated fields advance each next
+offset by the preceding element's actual size.
+
 ## Versioning And Release
 
 Version bump scripts are provided for patch, minor, and major releases:

{sltcodec-2.0.0 → sltcodec-2.1.1}/README_pypi.md

@@ -46,6 +46,12 @@ encoded = encode(layout, instance, bytearray())
 decoded = decode(layout, encoded)
 ```
 
+`decode` returns a `StructInstance` whose `size` is the actual end of the
+decoded layout. `decode_field` stores the actual decoded size in the returned
+`FieldInstance.field_def.size`. For nested `StructDef` fields, that size comes
+from the nested `StructInstance.size`; for repeated fields, the next element's
+offset advances by the actual size of the previous element.
+
 ## Field Types
 
 The public `PRIMITIVE_TYPES` set contains:
@@ -61,7 +67,6 @@ The public `PRIMITIVE_TYPES` set contains:
 Store named structures in `TypeDict.struct_dict` and enums in `TypeDict.enum_dict`. A field refers to an enum by its `enum_def_name`; the codec resolves it through `StructLayout.type_dict`.
 
 ```python
-| `__lt__(other)` | Compare enum definitions using their serialized ordering. |
 from sltcore import InfoSize
 from sltcodec import EnumDef, FieldDef, StructDef, StructLayout, TypeDict, decode
 
@@ -85,7 +90,6 @@ layout = StructLayout(
 )
 
 decoded = decode(layout, bytearray(b"\x01"))
-| `__lt__(other)` | Compare field definitions using their serialized ordering. |
 assert decoded.field_instances[0].enum_item == ("NG", 1)
 ```
 
@@ -100,7 +104,6 @@ from sltcodec import load_struct_layout, save_struct_layout
 path = Path("struct_layout.json")
 save_struct_layout(layout, path)
 loaded = load_struct_layout(path)
-| `__lt__(other)` | Compare field instances using field-definition order. |
 assert loaded == layout
 ```
 
@@ -168,7 +171,6 @@ internal implementation details and are omitted from the public method tables.
 
 | Method | Description |
 | --- | --- |
-| `split_repeat(index, offset=None, size=None)` | Create one field definition from a repeated field. |
 | `to_dict()` | Convert the definition to a JSON-compatible dictionary. |
 | `to_json()` | Convert the definition to a JSON string. |
 | `from_dict(data)` | Create a `FieldDef` from a dictionary. |
@@ -188,6 +190,7 @@ internal implementation details and are omitted from the public method tables.
 | --- | --- |
 | `range_check(env=None)` | Evaluate the field's range expression. |
 | `from_value(field_def, value, type_dict=None, is_padding=False)` | Create an instance and resolve matching enum metadata. |
+| `with_value(value, type_dict=None)` | Return a new instance with the given value; keeps `field_def` and `is_padding` and recomputes `enum_item`. |
 | `__lt__(other)` | Compare field instances using field-definition order. |
 
 #### `StructDef`

{sltcodec-2.0.0 → sltcodec-2.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sltcodec"
-version = "2.0.0"
+version = "2.1.1"
 description = "Decode and encode bytearrays according to struct layout definitions using sltcore."
 readme = "README_pypi.md"
 requires-python = ">=3.12"

{sltcodec-2.0.0 → sltcodec-2.1.1}/src/sltcodec/codec.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
 from typing import Any
 
@@ -259,17 +260,30 @@ def _prepare_field_info(
     return offset, size, info
 
 
-def _split_repeated_field(field_def: FieldDef,
-                          index: int,
-                          env: dict[str, Any],
-                          offset: InfoSize | str | None = None) -> FieldDef:
-    """Create a repeated-field definition with resolved offset and size."""
-    resolved_offset = (_resolve_offset(field_def, env)
-                       if offset is None else offset)
-    resolved_size = _resolve_size(field_def, env)
-    return field_def.split_repeat(index,
-                                  offset=resolved_offset,
-                                  size=resolved_size)
+def _repeated_field_def(field_def: FieldDef, index: int, offset: InfoSize,
+                        size: InfoSize | str) -> FieldDef:
+    """Create a resolved field definition for one repeated value."""
+    repeated_name = f"{field_def.name}[{index}]"
+
+    def replace_name(value: Any) -> Any:
+        if not isinstance(value, str):
+            return value
+        pattern = (rf"(?<![0-9A-Za-z_]){re.escape(field_def.name)}"
+                   rf"(?![0-9A-Za-z_])")
+        return re.sub(pattern, repeated_name, value)
+
+    return FieldDef(
+        name=repeated_name,
+        offset=offset,
+        size=size,
+        type=replace_name(field_def.type),
+        scale=field_def.scale,
+        repeat=None,
+        description=field_def.description,
+        range_expression=replace_name(field_def.range_expression),
+        enum_def_name=field_def.enum_def_name,
+        byte_swap=replace_name(field_def.byte_swap),
+    )
 
 
 def encode_field(
@@ -345,17 +359,17 @@ def encode(
             value = bytearray(padding_size.bytes)
         if field_def.repeat is not None and field_def.repeat > 1:
             current_offset = _resolve_offset(field_def, env)
-            resolved_size = _resolve_size(field_def, env)
             values = list(value)
 
             for i in range(field_def.repeat):
-                field_def_repeat = _split_repeated_field(
-                    field_def, i, env, current_offset)
+                field_def_repeat = _repeated_field_def(field_def, i,
+                                                       current_offset,
+                                                       field_def.size)
+                resolved_size = _resolve_size(field_def_repeat, env)
                 encode_field(field_def_repeat, values[i], buf, env, type_dict,
                              padding_alignment_bits)
                 env[field_def_repeat.name] = values[i]
-                if isinstance(current_offset, InfoSize) and isinstance(
-                        resolved_size, InfoSize):
+                if isinstance(current_offset, InfoSize):
                     current_offset += resolved_size
             continue
 
@@ -405,10 +419,20 @@ def decode_field(
     if byte_swap:
         info = _byte_swap_info(info, size)
     resolved_type = _resolve_field_type(field_def.type, type_dict, env)
+    nested_value = None
+    if isinstance(resolved_type, StructDef):
+        nested_layout = _layout_for_struct_def(resolved_type,
+                                               type_dict,
+                                               name=field_def.name)
+        nested_value = decode(nested_layout, bytearray(info.to_bytes),
+                              padding_alignment_bits)
+        actual_size = nested_value.size
+    else:
+        actual_size = info.info_size
     resolved_field_def = FieldDef(
         name=field_def.name,
         offset=offset,
-        size=size,
+        size=actual_size,
         type=resolved_type,
         scale=field_def.scale,
         repeat=field_def.repeat,
@@ -418,13 +442,9 @@ def decode_field(
         byte_swap=byte_swap,
     )
     if isinstance(resolved_type, StructDef):
-        nested_layout = _layout_for_struct_def(resolved_type,
-                                               type_dict,
-                                               name=field_def.name)
         return FieldInstance(
             field_def=resolved_field_def,
-            value=decode(nested_layout, bytearray(info.to_bytes),
-                         padding_alignment_bits),
+            value=nested_value,
         )
     if resolved_type == "bool":
         return FieldInstance.from_value(resolved_field_def,
@@ -548,19 +568,32 @@ def decode(
             continue
         # Handle repeated fields
         current_offset = _resolve_offset(field_def, env)
-        resolved_size = _resolve_size(field_def, env)
         append_padding_until(current_offset)
         for i in range(field_def.repeat):
-            field_def_repeat = _split_repeated_field(field_def, i, env,
-                                                     current_offset)
+            field_def_repeat = _repeated_field_def(field_def, i, current_offset,
+                                                   field_def.size)
             field_instance = decode_field(field_def_repeat, data, env,
                                           type_dict, padding_alignment_bits)
             if field_instance is not None:
                 env[field_instance.field_def.name] = field_instance.value
                 result.append_field_instance(field_instance)
-                current_position = current_offset + resolved_size
-            current_offset += resolved_size
-
+                actual_size = field_instance.field_def.size
+            else:
+                actual_size = _resolve_size(field_def_repeat, env)
+            if isinstance(current_offset, InfoSize) and isinstance(
+                    actual_size, InfoSize):
+                current_offset += actual_size
+                current_position = current_offset
+
+    actual_size = InfoSize(0, 0)
+    for field_instance in result.field_instances:
+        field_def = field_instance.field_def
+        if (isinstance(field_def.offset, InfoSize)
+                and isinstance(field_def.size, InfoSize)):
+            field_end = field_def.offset + field_def.size
+            if field_end > actual_size:
+                actual_size = field_end
+    result.size = actual_size
     append_padding_until(result.size)
 
     return result

{sltcodec-2.0.0 → sltcodec-2.1.1}/src/sltcodec/types.py

@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 import json
-import re
 from collections.abc import MutableMapping
 from dataclasses import dataclass, field
 from functools import total_ordering
@@ -112,46 +111,6 @@ class FieldDef:
         default=False,
         metadata={"desc": "Whether to reverse the field byte order"})
 
-    def split_repeat(self,
-                     index: int,
-                     offset: InfoSize | str | None = None,
-                     size: InfoSize | str | None = None) -> "FieldDef":
-        """Create a single repeated-field definition for the given index."""
-        split_name = f"{self.name}[{index}]"
-        split_offset_source = self.offset if offset is None else offset
-        split_size_source = self.size if size is None else size
-        split_offset = self._replace_name_in_expression(split_offset_source,
-                                                        self.name, split_name)
-        split_size = self._replace_name_in_expression(split_size_source,
-                                                      self.name, split_name)
-        split_type = self._replace_name_in_expression(self.type, self.name,
-                                                      split_name)
-        split_range_expression = self._replace_name_in_expression(
-            self.range_expression, self.name, split_name)
-        split_byte_swap = self._replace_name_in_expression(
-            self.byte_swap, self.name, split_name)
-
-        return FieldDef(name=split_name,
-                        offset=split_offset,
-                        size=split_size,
-                        type=split_type,
-                        scale=self.scale,
-                        repeat=None,
-                        description=self.description,
-                        range_expression=split_range_expression,
-                        enum_def_name=self.enum_def_name,
-                        byte_swap=split_byte_swap)
-
-    @staticmethod
-    def _replace_name_in_expression(value: Any, old_name: str,
-                                    new_name: str) -> Any:
-        """Replace standalone old_name tokens in expression-like strings."""
-        if not isinstance(value, str):
-            return value
-        pattern = (rf"(?<![0-9A-Za-z_]){re.escape(old_name)}"
-                   rf"(?![0-9A-Za-z_])")
-        return re.sub(pattern, lambda _: new_name, value)
-
     def __lt__(self, other: object) -> bool:
         """Compare field definitions using a stable serialized sort key."""
         if not isinstance(other, FieldDef):
@@ -347,6 +306,15 @@ class FieldInstance:
                    enum_item=enum_item,
                    is_padding=is_padding)
 
+    def with_value(self,
+                   value: Any,
+                   type_dict: "TypeDict | None" = None) -> "FieldInstance":
+        """Return a new FieldInstance with the given value applied."""
+        return type(self).from_value(field_def=self.field_def,
+                                     value=value,
+                                     type_dict=type_dict,
+                                     is_padding=self.is_padding)
+
     @staticmethod
     def _resolve_enum_def(field_def: FieldDef,
                           type_dict: "TypeDict | None") -> EnumDef | None:

{sltcodec-2.0.0 → sltcodec-2.1.1}/tests/test_codec.py

@@ -215,6 +215,24 @@ def test_encode_recurses_for_nested_field_types():
             ]
 
 
+def test_decode_field_uses_nested_struct_instance_size():
+    """Test that nested decoding determines the field's actual size."""
+    child_field_def = FieldDef(name="value",
+                               offset=InfoSize(0, 0),
+                               size=InfoSize(1, 0),
+                               type="unsigned int")
+    parent_field_def = FieldDef(name="nested",
+                                offset=InfoSize(0, 0),
+                                size=InfoSize(4, 0),
+                                type=StructDef(fields=[child_field_def]))
+
+    decoded = decode_field(parent_field_def, bytearray(b"\x7f"))
+
+    assert decoded is not None
+    assert decoded.field_def.size == InfoSize(1, 0)
+    assert decoded.value.size == InfoSize(1, 0)
+
+
 def test_repeated_field_preserves_description():
     """Test that repeated fields keep their description on decoded entries."""
     field_def = FieldDef(name="value",
@@ -572,6 +590,37 @@ def test_decode_field_returns_field_instance():
     assert decoded == FieldInstance(field_def=field_def, value=127)
 
 
+def test_decode_field_sets_actual_size_on_field_instance():
+    """Test that decode_field stores the resolved Info size."""
+    field_def = FieldDef(name="value",
+                         offset="offset",
+                         size="field_size",
+                         type="unsigned int")
+
+    decoded = decode_field(field_def,
+                           bytearray(b"\x7f"),
+                           env={
+                               "offset": 0,
+                               "field_size": 1
+                           })
+
+    assert decoded is not None
+    assert decoded.field_def.size == InfoSize(1, 0)
+
+
+def test_decode_struct_instance_size_matches_decoded_layout():
+    """Test that decode reports the complete decoded layout size."""
+    field_def = FieldDef(name="value",
+                         offset=InfoSize(2, 0),
+                         size=InfoSize(2, 0),
+                         type="unsigned int")
+    data = bytearray(b"\x00\x00\x7f\x00")
+
+    decoded = decode(layout_for(StructDef(fields=[field_def])), data)
+
+    assert decoded.size == InfoSize(len(data), 0)
+
+
 def test_encode_padding_fields_use_zero_value_and_extend_to_struct_size():
     """Test that padding fields are zeroed and trailing bytes are padded.
 

{sltcodec-2.0.0 → sltcodec-2.1.1}/tests/test_types.py

@@ -13,23 +13,6 @@ class ValueKind(Enum):
     B = 2
 
 
-def test_split_repeat_replaces_name_in_range_expression():
-    """Test split_repeat replaces field-name tokens in range expressions."""
-    field_def = FieldDef(
-        name="value",
-        offset=InfoSize(0, 0),
-        size=InfoSize(1, 0),
-        type="unsigned int",
-        repeat=2,
-        range_expression=("0 <= value and value <= limit and value_count"))
-
-    split = field_def.split_repeat(1)
-
-    assert split.name == "value[1]"
-    assert split.range_expression == (
-        "0 <= value[1] and value[1] <= limit and value_count")
-
-
 def test_field_def_json_round_trip():
     """Test that FieldDef can be serialized and deserialized from JSON."""
     field_def = FieldDef(name="value",
@@ -169,6 +152,89 @@ def test_field_instance_from_value_sets_enum_item_from_field_enum_def():
     assert field_instance.enum_item == ("MANUAL", 1)
 
 
+def _mode_enum_fixture() -> tuple[EnumDef, FieldDef, TypeDict]:
+    """Build an enum-backed field definition and its type dictionary."""
+    enum_def = EnumDef(name="Mode", values={"AUTO": 0, "MANUAL": 1})
+    field_def = FieldDef(name="mode",
+                         offset=InfoSize(0, 0),
+                         size=InfoSize(1, 0),
+                         type="unsigned int",
+                         enum_def_name=enum_def.name)
+    type_dict = TypeDict(enum_dict={enum_def.name: enum_def})
+    return enum_def, field_def, type_dict
+
+
+def test_field_instance_with_value_keeps_original_unchanged():
+    """Test FieldInstance.with_value does not mutate the original."""
+    _, field_def, type_dict = _mode_enum_fixture()
+    original = FieldInstance.from_value(field_def, 0, type_dict=type_dict)
+
+    original.with_value(1, type_dict)
+
+    assert original.value == 0
+    assert original.enum_item == ("AUTO", 0)
+
+
+def test_field_instance_with_value_returns_new_instance():
+    """Test FieldInstance.with_value returns a new instance with the value."""
+    _, field_def, type_dict = _mode_enum_fixture()
+    original = FieldInstance.from_value(field_def, 0, type_dict=type_dict)
+
+    updated = original.with_value(1, type_dict)
+
+    assert updated is not original
+    assert updated.value == 1
+
+
+def test_field_instance_with_value_preserves_field_def_and_padding():
+    """Test FieldInstance.with_value preserves field_def and is_padding."""
+    _, field_def, type_dict = _mode_enum_fixture()
+    original = FieldInstance.from_value(field_def,
+                                        0,
+                                        type_dict=type_dict,
+                                        is_padding=True)
+
+    updated = original.with_value(1, type_dict)
+
+    assert updated.field_def is original.field_def
+    assert updated.is_padding is True
+
+
+def test_field_instance_with_value_updates_enum_item():
+    """Test FieldInstance.with_value recomputes a matching enum_item."""
+    _, field_def, type_dict = _mode_enum_fixture()
+    original = FieldInstance.from_value(field_def, 0, type_dict=type_dict)
+
+    updated = original.with_value(1, type_dict)
+
+    assert updated.enum_item == ("MANUAL", 1)
+
+
+def test_field_instance_with_value_clears_unmatched_enum_item():
+    """Test FieldInstance.with_value clears enum_item when unmatched."""
+    _, field_def, type_dict = _mode_enum_fixture()
+    original = FieldInstance.from_value(field_def, 0, type_dict=type_dict)
+
+    updated = original.with_value(7, type_dict)
+
+    assert updated.enum_item is None
+
+
+def test_field_instance_with_value_without_type_dict():
+    """Test FieldInstance.with_value works for plain fields."""
+    field_def = FieldDef(name="count",
+                         offset=InfoSize(0, 0),
+                         size=InfoSize(1, 0),
+                         type="unsigned int")
+    original = FieldInstance.from_value(field_def, 1)
+
+    updated = original.with_value(2)
+
+    assert updated.value == 2
+    assert updated.enum_item is None
+    assert original.value == 1
+
+
 def test_struct_def_metadata_json_round_trip():
     """Test that StructDef name/description are preserved in JSON."""
     child = FieldDef(name="value",

{sltcodec-2.0.0 → sltcodec-2.1.1}/uv.lock

@@ -74,7 +74,7 @@ wheels = [
 
 [[package]]
 name = "sltcodec"
-version = "1.3.0"
+version = "2.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "sltcalc" },