sltcodec 0.2.0__tar.gz → 0.4.0__tar.gz

{sltcodec-0.2.0 → sltcodec-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sltcodec
-Version: 0.2.0
+Version: 0.4.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
@@ -12,7 +12,7 @@ License-File: LICENSE
 Keywords: byte,deserialization,layout,serialization,struct
 Requires-Python: >=3.12
 Requires-Dist: sltcalc>=0.1.0
-Requires-Dist: sltcore>=1.3.0
+Requires-Dist: sltcore>=1.5.0
 Description-Content-Type: text/markdown
 
 # StructLayoutToolkitCodec

{sltcodec-0.2.0 → sltcodec-0.4.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "sltcodec"
-version = "0.2.0"
+version = "0.4.0"
 description = "Decode and encode bytearrays according to struct layout definitions using sltcore."
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "sltcalc>=0.1.0",
-    "sltcore>=1.3.0",
+    "sltcore>=1.5.0",
 ]
 license = "MIT"
 license-files = ["LICENSE"]

{sltcodec-0.2.0 → sltcodec-0.4.0}/src/sltcodec/__init__.py

@@ -1,8 +1,9 @@
 from .codec import (decode, encode, encode_field, load_struct_def_dict,
                     save_struct_def_dict)
-from .types import FieldDef, FieldInstance, StructDef, StructInstance
+from .types import EnumDef, FieldDef, FieldInstance, StructDef, StructInstance
 
 __all__ = [
+    "EnumDef",
     "FieldDef",
     "FieldInstance",
     "StructDef",

{sltcodec-0.2.0 → sltcodec-0.4.0}/src/sltcodec/codec.py

@@ -8,7 +8,7 @@ from typing import Any
 from sltcalc import SltEval
 from sltcore import Info, InfoSize, bits_get, bits_set
 
-from .types import FieldDef, FieldInstance, StructDef, StructInstance
+from .types import EnumDef, FieldDef, FieldInstance, StructDef, StructInstance
 
 _PRIMITIVE_TYPES = {
     "bool",
@@ -20,6 +20,8 @@ _PRIMITIVE_TYPES = {
     "bytes",
 }
 
+_DEFAULT_PADDING_ALIGNMENT_BITS = 32
+
 
 def _as_field_defs(struct_def: StructDef | list[FieldDef]) -> list[FieldDef]:
     """Normalize StructDef/list inputs to a list of field definitions."""
@@ -96,6 +98,16 @@ def _info_size_from_bits(total_bits: int) -> InfoSize:
     return InfoSize(total_bits >> 3, total_bits & 0x7)
 
 
+def _validate_padding_alignment_bits(padding_alignment_bits: int) -> None:
+    """Validate padding alignment as a positive power-of-two bit size."""
+    if (isinstance(padding_alignment_bits, bool)
+            or not isinstance(padding_alignment_bits, int)
+            or padding_alignment_bits <= 0
+            or (padding_alignment_bits & (padding_alignment_bits - 1)) != 0):
+        raise ValueError(
+            "padding_alignment_bits must be a positive power of two")
+
+
 def _resolve_field_type(field_type: str | StructDef,
                         struct_def_dict: dict[str, StructDef] | None = None,
                         env: dict[str, Any] | None = None) -> str | StructDef:
@@ -141,7 +153,9 @@ def _prepare_field_info(
     field_def: FieldDef,
     value: Any,
     env: dict[str, Any],
-    struct_def_dict: dict[str, StructDef] | None = None
+    struct_def_dict: dict[str, StructDef] | None = None,
+    enum_def_dict: dict[str, EnumDef] | None = None,
+    padding_alignment_bits: int = _DEFAULT_PADDING_ALIGNMENT_BITS,
 ) -> tuple[InfoSize, InfoSize, Info] | None:
     """Resolve a field definition into an offset, size, and info payload."""
     offset = _resolve_offset(field_def, env)
@@ -155,7 +169,11 @@ def _prepare_field_info(
             raise TypeError(
                 "Nested StructDef fields must be encoded with StructInstance "
                 "values")
-        nested_bytes = encode(value, bytearray(), struct_def_dict)
+        nested_bytes = encode(value,
+                              bytearray(),
+                              struct_def_dict,
+                              enum_def_dict,
+                              padding_alignment_bits=padding_alignment_bits)
         info = Info.from_bytes(bytes(nested_bytes), size, scale=field_def.scale)
     else:
         info = _encode_primitive(resolved_type, value, size, field_def.scale)
@@ -170,25 +188,26 @@ def _split_repeated_field(field_def: FieldDef,
     resolved_offset = (_resolve_offset(field_def, env)
                        if offset is None else offset)
     resolved_size = _resolve_size(field_def, env)
-    return FieldDef(name=f"{field_def.name}[{index}]",
-                    offset=resolved_offset,
-                    size=resolved_size,
-                    type=field_def.type,
-                    scale=field_def.scale,
-                    repeat=None,
-                    description=field_def.description)
-
-
-def encode_field(field_def: FieldDef,
-                 value: Any,
-                 buf: bytearray,
-                 env: dict[str, Any] | None = None,
-                 struct_def_dict: dict[str, StructDef] | None = None) -> None:
+    return field_def.split_repeat(index,
+                                  offset=resolved_offset,
+                                  size=resolved_size)
+
+
+def encode_field(
+    field_def: FieldDef,
+    value: Any,
+    buf: bytearray,
+    env: dict[str, Any] | None = None,
+    struct_def_dict: dict[str, StructDef] | None = None,
+    enum_def_dict: dict[str, EnumDef] | None = None,
+    padding_alignment_bits: int = _DEFAULT_PADDING_ALIGNMENT_BITS,
+) -> None:
     """Encode a single field into a bytearray."""
     if env is None:
         env = {}
 
-    prepared = _prepare_field_info(field_def, value, env, struct_def_dict)
+    prepared = _prepare_field_info(field_def, value, env, struct_def_dict,
+                                   enum_def_dict, padding_alignment_bits)
     if prepared is None:
         return
 
@@ -200,9 +219,13 @@ def encode_field(field_def: FieldDef,
     bits_set(buf, offset, info)
 
 
-def encode(struct_instance: StructInstance,
-           buf: bytearray,
-           struct_def_dict: dict[str, StructDef] | None = None) -> bytearray:
+def encode(
+    struct_instance: StructInstance,
+    buf: bytearray,
+    struct_def_dict: dict[str, StructDef] | None = None,
+    enum_def_dict: dict[str, EnumDef] | None = None,
+    padding_alignment_bits: int = _DEFAULT_PADDING_ALIGNMENT_BITS,
+) -> bytearray:
     """Encode decode() result into a bytearray.
 
     Parameters
@@ -213,6 +236,10 @@ def encode(struct_instance: StructInstance,
         The base bytearray instance to write into.
     struct_def_dict : dict[str, StructDef] | None, optional
         A dictionary of structure definitions, by default None.
+    enum_def_dict : dict[str, EnumDef] | None, optional
+        A dictionary of enum definitions, by default None.
+    padding_alignment_bits : int, optional
+        The padding alignment boundary in bits, by default 32.
 
     Returns
     -------
@@ -220,6 +247,7 @@ def encode(struct_instance: StructInstance,
         The encoded bytearray.
     """
     _validate_struct_instance(struct_instance)
+    _validate_padding_alignment_bits(padding_alignment_bits)
     env: dict[str, Any] = {}
     has_padding = False
 
@@ -240,14 +268,16 @@ def encode(struct_instance: StructInstance,
                 field_def_repeat = _split_repeated_field(
                     field_def, i, env, current_offset)
                 encode_field(field_def_repeat, values[i], buf, env,
-                             struct_def_dict)
+                             struct_def_dict, enum_def_dict,
+                             padding_alignment_bits)
                 env[field_def_repeat.name] = values[i]
                 if isinstance(current_offset, InfoSize) and isinstance(
                         resolved_size, InfoSize):
                     current_offset += resolved_size
             continue
 
-        encode_field(field_def, value, buf, env, struct_def_dict)
+        encode_field(field_def, value, buf, env, struct_def_dict, enum_def_dict,
+                     padding_alignment_bits)
         env[field_def.name] = value
 
     if has_padding and struct_instance.size.bytes > len(buf):
@@ -260,7 +290,9 @@ def decode_field(
     field_def: FieldDef,
     data: bytearray | bytes,
     env: dict[str, Any] | None = None,
-    struct_def_dict: dict[str, StructDef] | None = None
+    struct_def_dict: dict[str, StructDef] | None = None,
+    enum_def_dict: dict[str, EnumDef] | None = None,
+    padding_alignment_bits: int = _DEFAULT_PADDING_ALIGNMENT_BITS,
 ) -> FieldInstance | None:
     """Decode a single field from a bytearray according to a field definition.
 
@@ -291,25 +323,41 @@ def decode_field(
         return FieldInstance(
             field_def=field_def,
             value=decode(resolved_type, bytearray(info.to_bytes),
-                         struct_def_dict),
+                         struct_def_dict, enum_def_dict,
+                         padding_alignment_bits),
         )
     if resolved_type == "bool":
-        return FieldInstance(field_def=field_def, value=info.to_bool)
+        return FieldInstance.from_value(field_def,
+                                        info.to_bool,
+                                        enum_def_dict=enum_def_dict)
     if resolved_type == "signed int":
-        return FieldInstance(field_def=field_def, value=info.to_signed_int)
+        return FieldInstance.from_value(field_def,
+                                        info.to_signed_int,
+                                        enum_def_dict=enum_def_dict)
     if resolved_type in ["int", "unsigned int"]:
-        return FieldInstance(field_def=field_def, value=info.to_unsigned_int)
+        return FieldInstance.from_value(field_def,
+                                        info.to_unsigned_int,
+                                        enum_def_dict=enum_def_dict)
     if resolved_type == "float":
-        return FieldInstance(field_def=field_def, value=info.to_float)
+        return FieldInstance.from_value(field_def,
+                                        info.to_float,
+                                        enum_def_dict=enum_def_dict)
     if resolved_type in ["bytearray", "bytes"]:
-        return FieldInstance(field_def=field_def, value=info.to_bytes)
-    return FieldInstance(field_def=field_def, value=info.raw_value)
+        return FieldInstance.from_value(field_def,
+                                        info.to_bytes,
+                                        enum_def_dict=enum_def_dict)
+    return FieldInstance.from_value(field_def,
+                                    info.raw_value,
+                                    enum_def_dict=enum_def_dict)
 
 
 def decode(
-        struct_def: StructDef | list[FieldDef],
-        data: bytearray | bytes,
-        struct_def_dict: dict[str, StructDef] | None = None) -> StructInstance:
+    struct_def: StructDef | list[FieldDef],
+    data: bytearray | bytes,
+    struct_def_dict: dict[str, StructDef] | None = None,
+    enum_def_dict: dict[str, EnumDef] | None = None,
+    padding_alignment_bits: int = _DEFAULT_PADDING_ALIGNMENT_BITS,
+) -> StructInstance:
     """Decode a bytearray into field values according to a layout.
 
     Parameters
@@ -320,11 +368,16 @@ def decode(
         The data to decode.
     struct_def_dict : dict[str, StructDef] | None, optional
         A dictionary of structure definitions, by default None.
+    enum_def_dict : dict[str, EnumDef] | None, optional
+        A dictionary of enum definitions, by default None.
+    padding_alignment_bits : int, optional
+        The padding alignment boundary in bits, by default 32.
     Returns
     -------
     StructInstance
         The decoded structure instance.
     """
+    _validate_padding_alignment_bits(padding_alignment_bits)
     env = {}
     struct_def_obj = (struct_def if isinstance(struct_def, StructDef) else
                       StructDef(fields=struct_def))
@@ -341,8 +394,11 @@ def decode(
 
         chunk_start_bits = start_bits
         while chunk_start_bits < end_bits:
-            next_boundary_bits = ((chunk_start_bits // 32) + 1) * 32
-            chunk_end_bits = min(end_bits, next_boundary_bits)
+            chunk_start = _info_size_from_bits(chunk_start_bits)
+            bits_to_boundary = _info_size_to_bits(
+                chunk_start.align_to(padding_alignment_bits))
+            chunk_size_bits = bits_to_boundary or padding_alignment_bits
+            chunk_end_bits = min(end_bits, chunk_start_bits + chunk_size_bits)
             padding_field_def = FieldDef(
                 name=f"padding[{padding_index}]",
                 offset=_info_size_from_bits(chunk_start_bits),
@@ -363,7 +419,8 @@ def decode(
         if field_def.repeat is None or field_def.repeat <= 1:
             resolved_offset = _resolve_offset(field_def, env)
             append_padding_until(resolved_offset)
-            field_instance = decode_field(field_def, data, env, struct_def_dict)
+            field_instance = decode_field(field_def, data, env, struct_def_dict,
+                                          enum_def_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)
@@ -378,7 +435,8 @@ def decode(
             field_def_repeat = _split_repeated_field(field_def, i, env,
                                                      current_offset)
             field_instance = decode_field(field_def_repeat, data, env,
-                                          struct_def_dict)
+                                          struct_def_dict, enum_def_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)

{sltcodec-0.2.0 → sltcodec-0.4.0}/src/sltcodec/types.py

@@ -2,12 +2,72 @@
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass, field
 from typing import Any
 
+from sltcalc import SltEval
 from sltcore import Info, InfoSize
 
 
+@dataclass(frozen=True)
+class EnumDef:
+    """An enumeration definition."""
+    name: str = field(default_factory=str,
+                      metadata={"desc": "The name of the enum"})
+    description: str | None = field(
+        default=None, metadata={"desc": "The description of the enum"})
+    values: dict[str, int] = field(
+        default_factory=dict,
+        metadata={"desc": "The mapping of enum names to integer values"},
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert this enum definition to a JSON-serializable dictionary."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "values": self.values,
+        }
+
+    def to_json(self) -> str:
+        """Convert this enum definition to a JSON string."""
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=2)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "EnumDef":
+        """Create an enum definition from a JSON-serializable dictionary."""
+        name = data.get("name", "")
+        description = data.get("description")
+        values = data.get("values", {})
+        return cls(name=name, description=description, values=values)
+
+    def serialize(self) -> dict[str, Any]:
+        """Serialize this enum definition with an explicit type tag."""
+        return {
+            "__type__": "EnumDef",
+            "name": self.name,
+            "description": self.description,
+            "values": self.values,
+        }
+
+    @classmethod
+    def deserialize(cls, data: dict[str, Any]) -> "EnumDef":
+        """Deserialize an enum definition from a typed dictionary."""
+        if data.get("__type__") != "EnumDef":
+            raise ValueError("Invalid EnumDef payload")
+        return cls(
+            name=data.get("name", ""),
+            description=data.get("description"),
+            values=data.get("values", {}),
+        )
+
+    @classmethod
+    def from_json(cls, data: str) -> "EnumDef":
+        """Create an enum definition from a JSON string."""
+        return cls.from_dict(json.loads(data))
+
+
 @dataclass(frozen=True)
 class FieldDef:
     """A field in a structured layout."""
@@ -25,18 +85,47 @@ class FieldDef:
         default=None, metadata={"desc": "The repeat count of the field"})
     description: str | None = field(
         default=None, metadata={"desc": "The description of the field"})
+    range_expression: str | None = field(
+        default=None, metadata={"desc": "The value range expression"})
+    enum_def: EnumDef | None = field(
+        default=None, metadata={"desc": "The enum definition for the field"})
 
     def split_repeat(self,
                      index: int,
-                     offset: InfoSize | str | None = None) -> "FieldDef":
+                     offset: InfoSize | str | None = None,
+                     size: InfoSize | str | None = None) -> "FieldDef":
         """Create a single repeated-field definition for the given index."""
-        return FieldDef(name=f"{self.name}[{index}]",
-                        offset=self.offset if offset is None else offset,
-                        size=self.size,
-                        type=self.type,
+        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)
+
+        return FieldDef(name=split_name,
+                        offset=split_offset,
+                        size=split_size,
+                        type=split_type,
                         scale=self.scale,
                         repeat=None,
-                        description=self.description)
+                        description=self.description,
+                        range_expression=split_range_expression,
+                        enum_def=self.enum_def)
+
+    @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."""
@@ -47,13 +136,33 @@ class FieldDef:
     def to_dict(self) -> dict[str, Any]:
         """Convert this field definition to a JSON-serializable dictionary."""
         return {
-            "name": self.name,
-            "offset": self._serialize_value(self.offset),
-            "size": self._serialize_value(self.size),
-            "type": self._serialize_type(self.type),
-            "scale": self.scale,
-            "repeat": self.repeat,
-            "description": self.description,
+            "name":
+            self.name,
+            "offset":
+            self.offset.serialize() if isinstance(self.offset,
+                                                  (Info,
+                                                   InfoSize)) else self.offset,
+            "size":
+            self.size.serialize() if isinstance(self.size,
+                                                (Info,
+                                                 InfoSize)) else self.size,
+            "type": {
+                "__type__": "StructDef",
+                "fields": self.type.to_dict(),
+            } if isinstance(self.type, StructDef) else {
+                "__type__": "StructDef",
+                "fields": [field.to_dict() for field in self.type],
+            } if isinstance(self.type, list) else self.type,
+            "scale":
+            self.scale,
+            "repeat":
+            self.repeat,
+            "description":
+            self.description,
+            "range_expression":
+            self.range_expression,
+            "enum_def":
+            None if self.enum_def is None else self.enum_def.serialize(),
         }
 
     def to_json(self) -> str:
@@ -63,14 +172,68 @@ class FieldDef:
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "FieldDef":
         """Create a field definition from a JSON-serializable dictionary."""
+        name = data.get("name", "")
+        offset_data = data.get("offset")
+        size_data = data.get("size")
+        type_data = data.get("type")
+        scale = data.get("scale", 1.0)
+        repeat = data.get("repeat")
+        description = data.get("description")
+        range_expression = data.get("range_expression")
+        enum_def_data = data.get("enum_def")
+
+        def _deserialize_info_like(value: Any) -> Any:
+            if isinstance(value, dict):
+                value_type = value.get("__type__")
+                if value_type == "Info":
+                    return Info.deserialize(json.dumps(value))
+                if value_type == "InfoSize":
+                    return InfoSize.deserialize(json.dumps(value))
+                return value
+            if not isinstance(value, str):
+                return value
+            try:
+                parsed_value = json.loads(value)
+            except json.JSONDecodeError:
+                return value
+            if (isinstance(parsed_value, dict)
+                    and parsed_value.get("__type__") == "Info"):
+                return Info.deserialize(value)
+            if (isinstance(parsed_value, dict)
+                    and parsed_value.get("__type__") == "InfoSize"):
+                return InfoSize.deserialize(value)
+            return value
+
+        offset = _deserialize_info_like(offset_data)
+        size = _deserialize_info_like(size_data)
+
+        if (isinstance(type_data, dict)
+                and type_data.get("__type__") == "StructDef"):
+            type_value = StructDef.from_dict(type_data["fields"])
+        elif isinstance(type_data, list):
+            # Backward-compatibility for legacy list-based nested types.
+            type_value = StructDef.from_dict(type_data)
+        else:
+            type_value = type_data
+
+        if enum_def_data is None:
+            enum_def = None
+        elif (isinstance(enum_def_data, dict)
+              and enum_def_data.get("__type__") == "EnumDef"):
+            enum_def = EnumDef.deserialize(enum_def_data)
+        else:
+            enum_def = None
+
         return cls(
-            name=data.get("name", ""),
-            offset=cls._deserialize_value(data.get("offset")),
-            size=cls._deserialize_value(data.get("size")),
-            type=cls._deserialize_type(data.get("type")),
-            scale=data.get("scale", 1.0),
-            repeat=data.get("repeat"),
-            description=data.get("description"),
+            name=name,
+            offset=offset,
+            size=size,
+            type=type_value,
+            scale=scale,
+            repeat=repeat,
+            description=description,
+            range_expression=range_expression,
+            enum_def=enum_def,
         )
 
     @classmethod
@@ -78,52 +241,6 @@ class FieldDef:
         """Create a field definition from a JSON string."""
         return cls.from_dict(json.loads(data))
 
-    @staticmethod
-    def _serialize_value(value: Any) -> Any:
-        if isinstance(value, Info):
-            return {
-                "__type__": "Info",
-                "value": value.to_json(),
-            }
-        if isinstance(value, InfoSize):
-            return {
-                "__type__": "InfoSize",
-                "value": value.to_json(),
-            }
-        return value
-
-    @classmethod
-    def _deserialize_value(cls, value: Any) -> Any:
-        if isinstance(value, dict) and value.get("__type__") == "Info":
-            return Info.from_json(value["value"])
-        if isinstance(value, dict) and value.get("__type__") == "InfoSize":
-            return InfoSize.from_json(value["value"])
-        return value
-
-    @staticmethod
-    def _serialize_type(value: Any) -> Any:
-        if isinstance(value, StructDef):
-            return {
-                "__type__": "StructDef",
-                "fields": value.to_dict(),
-            }
-        if isinstance(value, list):
-            # Backward-compatibility for legacy list-based nested types.
-            return {
-                "__type__": "StructDef",
-                "fields": [field.to_dict() for field in value],
-            }
-        return value
-
-    @classmethod
-    def _deserialize_type(cls, value: Any) -> Any:
-        if isinstance(value, dict) and value.get("__type__") == "StructDef":
-            return StructDef.from_dict(value["fields"])
-        if isinstance(value, list):
-            # Backward-compatibility for legacy list-based nested types.
-            return StructDef.from_dict(value)
-        return value
-
     def _sort_key(self) -> tuple[Any, ...]:
         """Build a stable comparison key for ordering field definitions."""
         return (
@@ -134,6 +251,8 @@ class FieldDef:
             self.scale,
             -1 if self.repeat is None else self.repeat,
             "" if self.description is None else self.description,
+            "" if self.range_expression is None else self.range_expression,
+            self._sortable_enum_type(self.enum_def),
         )
 
     @staticmethod
@@ -150,12 +269,29 @@ class FieldDef:
             return (0, json.dumps(value.to_dict(), sort_keys=True))
         return (1, value)
 
+    @staticmethod
+    def _sortable_enum_type(value: EnumDef | None) -> str:
+        """Build a comparable key for enum definition metadata."""
+        if value is None:
+            return ""
+        return json.dumps(
+            {
+                "name": value.name,
+                "description": value.description,
+                "values": value.values,
+            },
+            sort_keys=True)
+
 
 @dataclass(frozen=True)
 class FieldInstance:
     """A decoded/encodable field value with its field definition."""
     field_def: FieldDef = field(metadata={"desc": "The field definition"})
     value: Any = field(metadata={"desc": "The decoded/encodable value"})
+    enum_item: tuple[str, int] | None = field(
+        default=None,
+        metadata={"desc": "Matched enum item for this value"},
+    )
     is_padding: bool = field(
         default=False,
         metadata={"desc": "Whether this field instance represents padding"},
@@ -167,6 +303,57 @@ class FieldInstance:
             return NotImplemented
         return self.field_def < other.field_def
 
+    def range_check(self, env: dict[str, Any] | None = None) -> Any | None:
+        """Evaluate range_expression and return its evaluated result."""
+        range_expression = self.field_def.range_expression
+        if range_expression is None:
+            return None
+
+        eval_env = {} if env is None else dict(env)
+        eval_env[self.field_def.name] = self.value
+        stleval = SltEval(eval_env)
+        return stleval.eval(range_expression)
+
+    @classmethod
+    def from_value(cls,
+                   field_def: FieldDef,
+                   value: Any,
+                   enum_def_dict: dict[str, EnumDef] | None = None,
+                   is_padding: bool = False) -> "FieldInstance":
+        """Create a FieldInstance and attach a matched enum item if any."""
+        enum_def = cls._resolve_enum_def(field_def, enum_def_dict)
+        enum_item = cls._resolve_enum_item(enum_def, value)
+        return cls(field_def=field_def,
+                   value=value,
+                   enum_item=enum_item,
+                   is_padding=is_padding)
+
+    @staticmethod
+    def _resolve_enum_def(
+            field_def: FieldDef,
+            enum_def_dict: dict[str, EnumDef] | None) -> EnumDef | None:
+        """Resolve enum definition from field metadata or lookup dictionary."""
+        if field_def.enum_def is not None:
+            return field_def.enum_def
+        if not enum_def_dict:
+            return None
+        if isinstance(field_def.type, str) and field_def.type in enum_def_dict:
+            return enum_def_dict[field_def.type]
+        return enum_def_dict.get(field_def.name)
+
+    @staticmethod
+    def _resolve_enum_item(enum_def: EnumDef | None,
+                           value: Any) -> tuple[str, int] | None:
+        """Resolve one enum values item that matches the given value."""
+        if enum_def is None:
+            return None
+        if isinstance(value, bool) or not isinstance(value, int):
+            return None
+        for enum_name, enum_value in enum_def.values.items():
+            if enum_value == value:
+                return enum_name, enum_value
+        return None
+
 
 @dataclass(frozen=True)
 class StructDef:
@@ -203,12 +390,11 @@ class StructDef:
         if isinstance(data, list):
             # Backward-compatibility for legacy list-only StructDef payloads.
             return cls(fields=[FieldDef.from_dict(item) for item in data])
-        return cls(name=data.get("name", ""),
-                   description=data.get("description", ""),
-                   fields=[
-                       FieldDef.from_dict(item)
-                       for item in data.get("fields", [])
-                   ])
+        name = data.get("name", "")
+        description = data.get("description", "")
+        fields_data = data.get("fields", [])
+        fields = [FieldDef.from_dict(item) for item in fields_data]
+        return cls(name=name, description=description, fields=fields)
 
     @classmethod
     def from_json(cls, data: str) -> "StructDef":

{sltcodec-0.2.0 → sltcodec-0.4.0}/tests/test_codec.py

@@ -1,15 +1,22 @@
 """Tests for the sltcodec module."""
+from enum import Enum
 from pathlib import Path
 
 import pytest
 from sltcore import InfoSize
 
-from sltcodec import (FieldDef, FieldInstance, StructDef, StructInstance,
-                      decode, encode, load_struct_def_dict,
+from sltcodec import (EnumDef, FieldDef, FieldInstance, StructDef,
+                      StructInstance, decode, encode, load_struct_def_dict,
                       save_struct_def_dict)
 from sltcodec.codec import decode_field
 
 
+class ValueKind(Enum):
+    """Enum used for EnumDef metadata tests."""
+    A = 1
+    B = 2
+
+
 def test_encode_and_decode_round_trip():
     """Test that encoding and then decoding returns the original data."""
     struct_def = [
@@ -146,6 +153,52 @@ def test_repeated_field_preserves_description():
         decoded.field_instances[1].field_def.description == "A repeated value")
 
 
+def test_repeated_field_preserves_range_and_enum_metadata():
+    """Test repeated fields preserve range/enum metadata on decoded entries."""
+    enum_def = EnumDef(
+        name="ValueKind",
+        values={member.name: member.value
+                for member in ValueKind})
+    field_def = FieldDef(name="value",
+                         offset=InfoSize(0, 0),
+                         size=InfoSize(1, 0),
+                         type="unsigned int",
+                         repeat=2,
+                         range_expression="0 <= value <= 255",
+                         enum_def=enum_def)
+
+    encoded = encode(
+        StructInstance(struct_def=StructDef(fields=[field_def]),
+                       field_instances=[FieldInstance(field_def, [1, 2])]),
+        bytearray(),
+    )
+    decoded = decode([field_def], encoded)
+
+    assert decoded.field_instances[0].field_def.range_expression == (
+        "0 <= value[0] <= 255")
+    assert decoded.field_instances[1].field_def.range_expression == (
+        "0 <= value[1] <= 255")
+    assert decoded.field_instances[0].field_def.enum_def == enum_def
+    assert decoded.field_instances[1].field_def.enum_def == enum_def
+
+
+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",
@@ -163,18 +216,135 @@ def test_field_def_json_round_trip():
 
 def test_field_def_to_json_from_json_round_trip():
     """Test FieldDef.to_json/from_json round-trip conversion."""
+    enum_def = EnumDef(
+        name="ValueKind",
+        values={member.name: member.value
+                for member in ValueKind})
     field_def = FieldDef(name="value",
                          offset=InfoSize(0, 0),
                          size=InfoSize(1, 0),
                          type="unsigned int",
                          scale=2.0,
                          repeat=3,
-                         description="A repeated value")
+                         description="A repeated value",
+                         range_expression="0 <= value <= 255",
+                         enum_def=enum_def)
 
     payload = field_def.to_json()
     restored = FieldDef.from_json(payload)
 
     assert restored == field_def
+    assert restored.range_expression == "0 <= value <= 255"
+    assert restored.enum_def == enum_def
+    assert restored.to_dict()["enum_def"] == {
+        "__type__": "EnumDef",
+        "name": "ValueKind",
+        "description": None,
+        "values": {
+            member.name: member.value
+            for member in ValueKind
+        },
+    }
+
+
+def test_enum_def_to_json_from_json_round_trip():
+    """Test EnumDef.to_json/from_json round-trip conversion."""
+    enum_def = EnumDef(name="Status",
+                       description="Status enum",
+                       values={
+                           "OK": 1,
+                           "NG": 2
+                       })
+
+    payload = enum_def.to_json()
+    restored = EnumDef.from_json(payload)
+
+    assert restored == enum_def
+    assert restored.to_dict() == {
+        "name": "Status",
+        "description": "Status enum",
+        "values": {
+            "OK": 1,
+            "NG": 2,
+        },
+    }
+
+
+def test_enum_def_to_dict_from_dict_round_trip():
+    """Test EnumDef.to_dict/from_dict round-trip conversion."""
+    enum_def = EnumDef(name="Mode",
+                       description="Mode enum",
+                       values={
+                           "AUTO": 0,
+                           "MANUAL": 1,
+                       })
+
+    payload = enum_def.to_dict()
+    restored = EnumDef.from_dict(payload)
+
+    assert restored == enum_def
+    assert payload == {
+        "name": "Mode",
+        "description": "Mode enum",
+        "values": {
+            "AUTO": 0,
+            "MANUAL": 1,
+        },
+    }
+
+
+def test_enum_def_serialize_deserialize_round_trip():
+    """Test EnumDef.serialize/deserialize round-trip conversion."""
+    enum_def = EnumDef(name="State",
+                       description="State enum",
+                       values={
+                           "ON": 1,
+                           "OFF": 0,
+                       })
+
+    payload = enum_def.serialize()
+    restored = EnumDef.deserialize(payload)
+
+    assert restored == enum_def
+    assert payload == {
+        "__type__": "EnumDef",
+        "name": "State",
+        "description": "State enum",
+        "values": {
+            "ON": 1,
+            "OFF": 0,
+        },
+    }
+
+
+def test_decode_uses_enum_def_dict_to_set_enum_item():
+    """Test decode uses enum_def_dict to resolve FieldInstance enum_item."""
+    enum_def = EnumDef(name="Status", values={"OK": 1, "NG": 2})
+    field_def = FieldDef(name="status",
+                         offset=InfoSize(0, 0),
+                         size=InfoSize(1, 0),
+                         type="unsigned int")
+
+    decoded = decode([field_def],
+                     bytearray(b"\x02"),
+                     enum_def_dict={"status": enum_def})
+
+    assert decoded.field_instances[0].value == 2
+    assert decoded.field_instances[0].enum_item == ("NG", 2)
+
+
+def test_field_instance_from_value_sets_enum_item_from_field_enum_def():
+    """Test FieldInstance.from_value sets enum_item from field enum_def."""
+    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=enum_def)
+
+    field_instance = FieldInstance.from_value(field_def, 1)
+
+    assert field_instance.enum_item == ("MANUAL", 1)
 
 
 def test_struct_def_metadata_json_round_trip():
@@ -357,6 +527,84 @@ def test_decode_inserts_padding_fields_for_gaps_and_trailing_space():
     assert decoded.field_instances[2].value == b"\xdd\xee"
 
 
+def test_decode_splits_padding_at_32_bit_boundaries():
+    """Test split into 32-bit chunks when a gap crosses a boundary."""
+    struct_def = StructDef(fields=[
+        FieldDef(name="head",
+                 offset=InfoSize(0, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+        FieldDef(name="tail",
+                 offset=InfoSize(5, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+    ])
+    decoded = decode(struct_def, bytearray(8))
+
+    assert [
+        field_instance.field_def.name
+        for field_instance in decoded.field_instances
+    ] == [
+        "head",
+        "padding[0]",
+        "padding[1]",
+        "tail",
+    ]
+
+
+def test_decode_splits_padding_with_custom_alignment_bits():
+    """Test that decode can split padding by a custom bit alignment."""
+    struct_def = StructDef(fields=[
+        FieldDef(name="head",
+                 offset=InfoSize(0, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+        FieldDef(name="tail",
+                 offset=InfoSize(4, 0),
+                 size=InfoSize(1, 0),
+                 type="unsigned int"),
+    ])
+    data = bytearray(b"\x11\xaa\xbb\xcc\x22")
+
+    decoded = decode(struct_def, data, padding_alignment_bits=16)
+
+    assert [
+        field_instance.field_def.name
+        for field_instance in decoded.field_instances
+    ] == [
+        "head",
+        "padding[0]",
+        "padding[1]",
+        "tail",
+    ]
+    assert decoded.field_instances[1].field_def.offset == InfoSize(1, 0)
+    assert decoded.field_instances[1].field_def.size == InfoSize(1, 0)
+    assert decoded.field_instances[1].value == b"\xaa"
+    assert decoded.field_instances[2].field_def.offset == InfoSize(2, 0)
+    assert decoded.field_instances[2].field_def.size == InfoSize(2, 0)
+    assert decoded.field_instances[2].value == b"\xbb\xcc"
+
+
+def test_decode_rejects_invalid_padding_alignment_bits():
+    """Test that decode validates padding alignment bit size."""
+    struct_def = StructDef(fields=[])
+
+    with pytest.raises(
+            ValueError,
+            match=r"padding_alignment_bits must be a positive power of two"):
+        decode(struct_def, bytearray(), padding_alignment_bits=24)
+
+
+def test_encode_rejects_invalid_padding_alignment_bits():
+    """Test that encode validates padding alignment bit size."""
+    struct_instance = StructInstance(struct_def=StructDef(fields=[]))
+
+    with pytest.raises(
+            ValueError,
+            match=r"padding_alignment_bits must be a positive power of two"):
+        encode(struct_instance, bytearray(), padding_alignment_bits=0)
+
+
 def test_encode_rejects_tuple_input():
     """Test that encode only accepts StructInstance input."""
     field_def = FieldDef(name="value",
@@ -482,6 +730,33 @@ def test_field_instance_sort_uses_field_def_order():
     assert sorted_instances == [earlier, later]
 
 
+def test_field_instance_range_check_evaluates_expression_with_field_env():
+    """Test that range_check evaluates expression with field name bound."""
+    field_def = FieldDef(name="value",
+                         offset=InfoSize(0, 0),
+                         size=InfoSize(1, 0),
+                         type="unsigned int",
+                         range_expression="0 <= value <= limit")
+    field_instance = FieldInstance(field_def=field_def, value=7)
+
+    assert field_instance.range_check({"limit": 10}) is True
+    assert field_instance.range_check({"limit": 5}) is False
+
+
+def test_field_instance_range_check_returns_none_when_expression_is_none():
+    """Test that range_check returns None when range_expression is None."""
+    field_def = FieldDef(name="value",
+                         offset=InfoSize(0, 0),
+                         size=InfoSize(1, 0),
+                         type="unsigned int",
+                         range_expression=None)
+    field_instance = FieldInstance(field_def=field_def, value=7)
+
+    result = field_instance.range_check()
+
+    assert result is None
+
+
 def test_struct_instance_size_property_returns_initial_size():
     """Test that StructInstance size is initialized from the provided value."""
     struct_instance = StructInstance(size=InfoSize(5, 0),

{sltcodec-0.2.0 → sltcodec-0.4.0}/uv.lock

@@ -74,7 +74,7 @@ wheels = [
 
 [[package]]
 name = "sltcodec"
-version = "0.2.0"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "sltcalc" },
@@ -89,7 +89,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "sltcalc", specifier = ">=0.1.0" },
-    { name = "sltcore", specifier = ">=1.3.0" },
+    { name = "sltcore", specifier = ">=1.5.0" },
 ]
 
 [package.metadata.requires-dev]
@@ -97,9 +97,9 @@ dev = [{ name = "pytest", specifier = ">=9.1.1" }]
 
 [[package]]
 name = "sltcore"
-version = "1.3.0"
+version = "1.5.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/9a/fa/856dea8a444493506f1c73aa434d30c895fb793ef73f47ff777e938fc639/sltcore-1.3.0.tar.gz", hash = "sha256:01b77f2932a028a1a1d7239ac15aa8c7fa88973f4db71a851a4bcc399649fd15", size = 16916, upload-time = "2026-08-08T13:10:11.545Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f0/8d/692c45c8d007b71b627fb4c53d90ecb5ea1168d892dc14e5ad3ecae0b8d3/sltcore-1.5.0.tar.gz", hash = "sha256:26280f743947f22e31e334fd793679f3aad19367bbf9bfddb6215123d7bd2d18", size = 18050, upload-time = "2026-08-11T13:14:51.241Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/7f/5f/15c2d6d78df481a62c60762c3824a9574f9bf610bc9d0463d3c8e5197e04/sltcore-1.3.0-py3-none-any.whl", hash = "sha256:85368bd7014879f4e67f98cdd6d489c29b3dc12f04e8964fcb701d75efa0c953", size = 9729, upload-time = "2026-08-08T13:10:10.5Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/ca/38d1ab93a871ba9e60e500b93f8c48fdb2be3308a8ab08e6ea0a73e516c2/sltcore-1.5.0-py3-none-any.whl", hash = "sha256:148611c58329fcadc793b38a973412144c073a036516baf9430b3170e71180c4", size = 10458, upload-time = "2026-08-11T13:14:50.295Z" },
 ]