sltcodec 2.0.0__tar.gz → 2.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sltcodec
-Version: 2.0.0
+Version: 2.1.0
 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
@@ -205,6 +205,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.0}/README.md

@@ -61,6 +61,19 @@ 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,
+)
+```
+
 ## Versioning And Release
 
 Version bump scripts are provided for patch, minor, and major releases:

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

@@ -188,6 +188,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.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sltcodec"
-version = "2.0.0"
+version = "2.1.0"
 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.0}/src/sltcodec/types.py

@@ -347,6 +347,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.0}/tests/test_types.py

@@ -169,6 +169,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",