sltcodec 2.5.2__tar.gz → 2.6.0__tar.gz

{sltcodec-2.5.2 → sltcodec-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sltcodec
-Version: 2.5.2
+Version: 2.6.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
@@ -73,6 +73,11 @@ Progress is calculated for top-level fields as `(offset + size) / total_size`.
 Nested structure encode/decode calls pass `None` internally, so recursive
 fields do not emit additional callback events.
 
+`encode` and `decode` also accept an optional `env` dictionary for evaluating
+expression-based field definitions. The default is `None`, which uses an empty
+environment. The same environment is passed to recursive nested structure
+encode and decode calls.
+
 ```python
 from sltcodec import ProgressCallback, decode
 
@@ -338,9 +343,9 @@ beginning with `_` are internal helpers and are not part of the public API.
 | `load_struct_def_dict` | `(path) -> dict[str, StructDef]` | Load a structure-definition dictionary. |
 | `save_enum_def_dict` | `(path, enum_def_dict) -> None` | Save an enum-definition dictionary through the layout format. |
 | `load_enum_def_dict` | `(path) -> dict[str, EnumDef]` | Load an enum-definition dictionary. |
-| `encode` | `(struct_layout, struct_instance, buf, padding_alignment_bits=32, progress_callback=None) -> bytearray` | Encode a complete structure. |
+| `encode` | `(struct_layout, struct_instance, buf, padding_alignment_bits=32, progress_callback=None, env=None) -> bytearray` | Encode a complete structure. `env` provides values for expression evaluation and is inherited by nested encodes. |
 | `decode_field` | `(field_def, data, env=None, type_dict=None, padding_alignment_bits=32) -> FieldInstance \| None` | Decode one field. |
-| `decode` | `(struct_layout, data, padding_alignment_bits=32, progress_callback=None) -> StructInstance` | Decode a complete structure. |
+| `decode` | `(struct_layout, data, padding_alignment_bits=32, progress_callback=None, env=None) -> StructInstance` | Decode a complete structure. `env` provides values for expression evaluation and is inherited by nested decodes. |
 
 `save_struct_def_dict`, `load_struct_def_dict`, `save_enum_def_dict`, and
 `load_enum_def_dict` are available from `sltcodec.codec` for dictionary-level

{sltcodec-2.5.2 → sltcodec-2.6.0}/README.md

@@ -63,6 +63,11 @@ from the top-level field extent: `(offset + size) / total_size`. Recursive
 nested structure calls pass `None`, so callers receive progress updates only
 for the top-level encode or decode operation.
 
+`encode` and `decode` also accept an optional `env` dictionary for evaluating
+expression-based field definitions. The default is `None`, which uses an empty
+environment. The same environment is passed to recursive nested structure
+encode and decode calls.
+
 ```python
 from sltcodec import ProgressCallback, decode
 

{sltcodec-2.5.2 → sltcodec-2.6.0}/README_pypi.md

@@ -56,6 +56,11 @@ Progress is calculated for top-level fields as `(offset + size) / total_size`.
 Nested structure encode/decode calls pass `None` internally, so recursive
 fields do not emit additional callback events.
 
+`encode` and `decode` also accept an optional `env` dictionary for evaluating
+expression-based field definitions. The default is `None`, which uses an empty
+environment. The same environment is passed to recursive nested structure
+encode and decode calls.
+
 ```python
 from sltcodec import ProgressCallback, decode
 
@@ -321,9 +326,9 @@ beginning with `_` are internal helpers and are not part of the public API.
 | `load_struct_def_dict` | `(path) -> dict[str, StructDef]` | Load a structure-definition dictionary. |
 | `save_enum_def_dict` | `(path, enum_def_dict) -> None` | Save an enum-definition dictionary through the layout format. |
 | `load_enum_def_dict` | `(path) -> dict[str, EnumDef]` | Load an enum-definition dictionary. |
-| `encode` | `(struct_layout, struct_instance, buf, padding_alignment_bits=32, progress_callback=None) -> bytearray` | Encode a complete structure. |
+| `encode` | `(struct_layout, struct_instance, buf, padding_alignment_bits=32, progress_callback=None, env=None) -> bytearray` | Encode a complete structure. `env` provides values for expression evaluation and is inherited by nested encodes. |
 | `decode_field` | `(field_def, data, env=None, type_dict=None, padding_alignment_bits=32) -> FieldInstance \| None` | Decode one field. |
-| `decode` | `(struct_layout, data, padding_alignment_bits=32, progress_callback=None) -> StructInstance` | Decode a complete structure. |
+| `decode` | `(struct_layout, data, padding_alignment_bits=32, progress_callback=None, env=None) -> StructInstance` | Decode a complete structure. `env` provides values for expression evaluation and is inherited by nested decodes. |
 
 `save_struct_def_dict`, `load_struct_def_dict`, `save_enum_def_dict`, and
 `load_enum_def_dict` are available from `sltcodec.codec` for dictionary-level

{sltcodec-2.5.2 → sltcodec-2.6.0}/pyproject.toml

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

{sltcodec-2.5.2 → sltcodec-2.6.0}/src/sltcodec/codec.py

@@ -40,9 +40,10 @@ def _notify_progress(progress_callback: ProgressCallback | None,
 
 
 def _estimate_encode_total_bits(struct_instance: StructInstance,
-                                initial_size_bits: int) -> int:
+                                initial_size_bits: int,
+                                env: dict[str, Any] | None = None) -> int:
     """Estimate encoded top-level extent before mutating the output buffer."""
-    env: dict[str, Any] = {}
+    env = dict(env) if env is not None else {}
     total_bits = max(struct_instance.size.bits, initial_size_bits)
 
     for field_value in struct_instance.field_instances:
@@ -309,7 +310,7 @@ def _prepare_field_info(
             _layout_for_struct_def(value.struct_def,
                                    type_dict,
                                    name=field_def.name), value, bytearray(),
-            padding_alignment_bits, None)
+            padding_alignment_bits, None, env)
         info = Info.from_bytes(bytes(nested_bytes), size, scale=field_def.scale)
     else:
         info = _encode_primitive(resolved_type, value, size, field_def.scale)
@@ -375,6 +376,7 @@ def encode(
     buf: bytearray,
     padding_alignment_bits: int = _DEFAULT_PADDING_ALIGNMENT_BITS,
     progress_callback: ProgressCallback | None = None,
+    env: dict[str, Any] | None = None,
 ) -> bytearray:
     """Encode decode() result into a bytearray.
 
@@ -392,6 +394,8 @@ def encode(
     progress_callback : Callable[[float], None] | None, optional
         Called after each top-level field is encoded with progress in the
         range 0.0 to 1.0. Nested recursive encodes are skipped.
+    env : dict[str, Any] | None, optional
+        The environment for evaluating expressions, by default None.
 
     Returns
     -------
@@ -406,9 +410,9 @@ def encode(
         raise ValueError("StructLayout.type_dict is required for encode()")
 
     type_dict = struct_layout.type_dict
-    env: dict[str, Any] = {}
+    env = env if env is not None else {}
     has_padding = False
-    total_bits = _estimate_encode_total_bits(struct_instance, len(buf) * 8)
+    total_bits = _estimate_encode_total_bits(struct_instance, len(buf) * 8, env)
 
     for field_value in struct_instance.field_instances:
         field_def = field_value.field_def
@@ -504,6 +508,7 @@ def decode_field(
             nested_data,
             padding_alignment_bits,
             None,
+            env,
         )
         actual_size = nested_value.size
     else:
@@ -574,6 +579,7 @@ def decode(
     data: bytearray | bytes,
     padding_alignment_bits: int = _DEFAULT_PADDING_ALIGNMENT_BITS,
     progress_callback: ProgressCallback | None = None,
+    env: dict[str, Any] | None = None,
 ) -> StructInstance:
     """Decode a bytearray into field values according to a layout.
 
@@ -589,6 +595,8 @@ def decode(
     progress_callback : Callable[[float], None] | None, optional
         Called after each top-level field is decoded with progress in the
         range 0.0 to 1.0. Nested recursive decodes are skipped.
+    env : dict[str, Any] | None, optional
+        The environment for evaluating expressions, by default None.
     Returns
     -------
     StructInstance
@@ -600,7 +608,7 @@ def decode(
     if struct_layout.type_dict is None:
         raise ValueError("StructLayout.type_dict is required for decode()")
 
-    env = {}
+    env = env if env is not None else {}
     type_dict = struct_layout.type_dict
     struct_def_obj = type_dict.struct_dict[struct_layout.struct_def_name]
     result = StructInstance(struct_def=struct_def_obj)

{sltcodec-2.5.2 → sltcodec-2.6.0}/tests/test_codec.py

@@ -435,6 +435,37 @@ def test_encode_recurses_for_nested_field_types():
             ]
 
 
+def test_env_is_used_and_inherited_by_nested_encode_and_decode():
+    """Test that the supplied env is available to recursive calls."""
+    child_field = FieldDef(name="value",
+                           offset=InfoSize(0, 0),
+                           size="payload_size",
+                           type="unsigned int")
+    parent_field = FieldDef(name="payload",
+                            offset=InfoSize(0, 0),
+                            size="payload_size",
+                            type=StructDef(fields=[child_field]))
+    child_def = StructDef(fields=[child_field])
+    parent_def = StructDef(fields=[parent_field])
+    instance = StructInstance(
+        struct_def=child_def,
+        field_instances=[FieldInstance(child_field, 0x1234)],
+    )
+    parent_instance = StructInstance(
+        struct_def=parent_def,
+        field_instances=[FieldInstance(parent_field, instance)],
+    )
+
+    encoded = encode(layout_for(parent_def),
+                     parent_instance,
+                     bytearray(),
+                     env={"payload_size": 2})
+    decoded = decode(layout_for(parent_def), encoded, env={"payload_size": 2})
+
+    assert encoded == bytearray(b"\x12\x34")
+    assert decoded.field_instances[0].value.field_instances[0].value == 0x1234
+
+
 def test_progress_callbacks_skip_nested_recursive_fields():
     """Test nested recursive encode/decode calls do not report progress."""
     child_field_defs = [