sltcodec 0.3.0__tar.gz → 0.5.0__tar.gz

{sltcodec-0.3.0 → sltcodec-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sltcodec
-Version: 0.3.0
+Version: 0.5.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.3.0 → sltcodec-0.5.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "sltcodec"
-version = "0.3.0"
+version = "0.5.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.3.0 → sltcodec-0.5.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.3.0 → sltcodec-0.5.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)
@@ -175,16 +193,21 @@ def _split_repeated_field(field_def: FieldDef,
                                   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) -> None:
+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
 
@@ -196,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
@@ -209,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
     -------
@@ -216,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
 
@@ -236,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):
@@ -256,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.
 
@@ -283,29 +319,56 @@ def decode_field(
         return None
     info = bits_get(data, offset, size, scale=field_def.scale)
     resolved_type = _resolve_field_type(field_def.type, struct_def_dict, env)
+    resolved_field_def = FieldDef(
+        name=field_def.name,
+        offset=offset,
+        size=size,
+        type=resolved_type,
+        scale=field_def.scale,
+        repeat=field_def.repeat,
+        description=field_def.description,
+        range_expression=field_def.range_expression,
+        enum_def=field_def.enum_def,
+    )
     if isinstance(resolved_type, StructDef):
         return FieldInstance(
-            field_def=field_def,
+            field_def=resolved_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(resolved_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(resolved_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(resolved_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(resolved_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(resolved_field_def,
+                                        info.to_bytes,
+                                        enum_def_dict=enum_def_dict)
+    return FieldInstance.from_value(resolved_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
@@ -316,11 +379,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))
@@ -337,8 +405,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),
@@ -359,7 +430,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)
@@ -374,7 +446,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.3.0 → sltcodec-0.5.0}/src/sltcodec/types.py

@@ -1,16 +1,90 @@
 """Type definitions for structured layout metadata."""
 from __future__ import annotations
 
-import importlib
 import json
 import re
 from dataclasses import dataclass, field
-from enum import Enum
+from functools import total_ordering
 from typing import Any
 
+from sltcalc import SltEval
 from sltcore import Info, InfoSize
 
 
+@total_ordering
+@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))
+
+    def __lt__(self, other: object) -> bool:
+        """Compare enum definitions using a stable serialized sort key."""
+        if not isinstance(other, EnumDef):
+            return NotImplemented
+        return self._sort_key() < other._sort_key()
+
+    def _sort_key(self) -> tuple[Any, ...]:
+        """Build a stable comparison key for ordering enum definitions."""
+        return (
+            self.name,
+            "" if self.description is None else self.description,
+            json.dumps(self.values, sort_keys=True),
+        )
+
+
+@total_ordering
 @dataclass(frozen=True)
 class FieldDef:
     """A field in a structured layout."""
@@ -30,8 +104,8 @@ class FieldDef:
         default=None, metadata={"desc": "The description of the field"})
     range_expression: str | None = field(
         default=None, metadata={"desc": "The value range expression"})
-    enum_type: type[Enum] | None = field(default=None,
-                                         metadata={"desc": "The enum type"})
+    enum_def: EnumDef | None = field(
+        default=None, metadata={"desc": "The enum definition for the field"})
 
     def split_repeat(self,
                      index: int,
@@ -58,7 +132,7 @@ class FieldDef:
                         repeat=None,
                         description=self.description,
                         range_expression=split_range_expression,
-                        enum_type=self.enum_type)
+                        enum_def=self.enum_def)
 
     @staticmethod
     def _replace_name_in_expression(value: Any, old_name: str,
@@ -79,15 +153,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,
-            "range_expression": self.range_expression,
-            "enum_type": self._serialize_enum_type(self.enum_type),
+            "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:
@@ -97,16 +189,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"),
-            range_expression=data.get("range_expression"),
-            enum_type=cls._deserialize_enum_type(data.get("enum_type")),
+            name=name,
+            offset=offset,
+            size=size,
+            type=type_value,
+            scale=scale,
+            repeat=repeat,
+            description=description,
+            range_expression=range_expression,
+            enum_def=enum_def,
         )
 
     @classmethod
@@ -114,83 +258,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
-
-    @staticmethod
-    def _serialize_enum_type(value: type[Enum] | None) -> Any:
-        if value is None:
-            return None
-        return {
-            "__type__": "EnumType",
-            "module": value.__module__,
-            "qualname": value.__qualname__,
-        }
-
-    @classmethod
-    def _deserialize_enum_type(cls, value: Any) -> type[Enum] | None:
-        if value is None:
-            return None
-        if not isinstance(value, dict) or value.get("__type__") != "EnumType":
-            return None
-        module_name = value.get("module")
-        qualname = value.get("qualname")
-        if not isinstance(module_name, str) or not isinstance(qualname, str):
-            return None
-        try:
-            module = importlib.import_module(module_name)
-            enum_type: Any = module
-            for attr in qualname.split("."):
-                enum_type = getattr(enum_type, attr)
-            if isinstance(enum_type, type) and issubclass(enum_type, Enum):
-                return enum_type
-        except (ImportError, AttributeError, TypeError):
-            return None
-        return None
-
     def _sort_key(self) -> tuple[Any, ...]:
         """Build a stable comparison key for ordering field definitions."""
         return (
@@ -202,7 +269,7 @@ class FieldDef:
             -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_type),
+            self._sortable_enum_type(self.enum_def),
         )
 
     @staticmethod
@@ -220,18 +287,29 @@ class FieldDef:
         return (1, value)
 
     @staticmethod
-    def _sortable_enum_type(value: type[Enum] | None) -> str:
-        """Build a comparable key for enum type metadata."""
+    def _sortable_enum_type(value: EnumDef | None) -> str:
+        """Build a comparable key for enum definition metadata."""
         if value is None:
             return ""
-        return f"{value.__module__}.{value.__qualname__}"
+        return json.dumps(
+            {
+                "name": value.name,
+                "description": value.description,
+                "values": value.values,
+            },
+            sort_keys=True)
 
 
+@total_ordering
 @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"},
@@ -243,7 +321,59 @@ 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
+
+
+@total_ordering
 @dataclass(frozen=True)
 class StructDef:
     """A structured layout definition that groups multiple fields."""
@@ -258,6 +388,21 @@ class StructDef:
         metadata={"desc": "The fields of the structure"},
     )
 
+    def __lt__(self, other: object) -> bool:
+        """Compare structure definitions using a stable serialized sort key."""
+        if not isinstance(other, StructDef):
+            return NotImplemented
+        return self._sort_key() < other._sort_key()
+
+    def _sort_key(self) -> tuple[Any, ...]:
+        """Build a stable comparison key for ordering structure definitions."""
+        return (
+            self.name,
+            "" if self.description is None else self.description,
+            json.dumps([field.to_dict() for field in self.fields],
+                       sort_keys=True),
+        )
+
     def to_dict(self) -> dict[str, Any]:
         """Convert this structure definition to JSON-serializable data."""
         return {
@@ -279,12 +424,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":
@@ -292,6 +436,7 @@ class StructDef:
         return cls.from_dict(json.loads(data))
 
 
+@total_ordering
 @dataclass
 class StructInstance:
     """A decoded/encodable structure instance."""
@@ -344,6 +489,23 @@ class StructInstance:
         """Return one field instance by index."""
         return self.field_instances[index]
 
+    def __lt__(self, other: object) -> bool:
+        """Compare structure instances using a stable serialized sort key."""
+        if not isinstance(other, StructInstance):
+            return NotImplemented
+        return self._sort_key() < other._sort_key()
+
+    def _sort_key(self) -> tuple[Any, ...]:
+        """Build a stable comparison key for ordering structure instances."""
+        return (
+            self.struct_def._sort_key(),
+            json.dumps([
+                field_instance.to_dict()
+                for field_instance in self.field_instances
+            ],
+                       sort_keys=True),
+        )
+
     def _sort_field_instances(self) -> None:
         """Keep field instances sorted by FieldDef order."""
         self.field_instances.sort()
@@ -356,14 +518,25 @@ class StructInstance:
         ]
         non_padding_instances.sort()
 
+        has_unresolved_layout = any(
+            not isinstance(field_instance.field_def.offset, InfoSize)
+            or not isinstance(field_instance.field_def.size, InfoSize)
+            for field_instance in non_padding_instances)
+        if has_unresolved_layout:
+            # Layout expressions are resolved later in codec paths.
+            self.field_instances = non_padding_instances
+            self._sort_field_instances()
+            self._update_size()
+            return
+
         rebuilt_instances: list[FieldInstance] = []
         current_offset = InfoSize(0, 0)
         padding_index = 0
 
         for field_instance in non_padding_instances:
             field_def = field_instance.field_def
-            field_offset = self._resolve_field_offset(field_def)
-            field_size = self._resolve_field_size(field_def)
+            field_offset = field_def.offset
+            field_size = field_def.size
             if field_offset > current_offset:
                 gap_size = field_offset - current_offset
                 if gap_size.byte > 0 or gap_size.bit > 0:
@@ -411,25 +584,15 @@ class StructInstance:
         max_end_offset = InfoSize(0, 0)
         for field_instance in self.field_instances:
             field_def = field_instance.field_def
-            field_offset = self._resolve_field_offset(field_def)
-            field_size = self._resolve_field_size(field_def)
+            if not isinstance(field_def.offset, InfoSize):
+                continue
+            if not isinstance(field_def.size, InfoSize):
+                continue
+            field_offset = field_def.offset
+            field_size = field_def.size
             field_end = field_offset + field_size
             if field_end > max_end_offset:
                 max_end_offset = field_end
 
         if max_end_offset > self.size:
             self.size = max_end_offset
-
-    @staticmethod
-    def _resolve_field_offset(field_def: FieldDef) -> InfoSize:
-        """Resolve field offsets to InfoSize values when possible."""
-        if isinstance(field_def.offset, InfoSize):
-            return field_def.offset
-        return InfoSize(0, 0)
-
-    @staticmethod
-    def _resolve_field_size(field_def: FieldDef) -> InfoSize:
-        """Resolve field sizes to InfoSize values when possible."""
-        if isinstance(field_def.size, InfoSize):
-            return field_def.size
-        return InfoSize(0, 0)

{sltcodec-0.3.0 → sltcodec-0.5.0}/tests/test_codec.py

@@ -5,14 +5,14 @@ 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 FieldDef enum_type metadata tests."""
+    """Enum used for EnumDef metadata tests."""
     A = 1
     B = 2
 
@@ -155,13 +155,17 @@ def test_repeated_field_preserves_description():
 
 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_type=ValueKind)
+                         enum_def=enum_def)
 
     encoded = encode(
         StructInstance(struct_def=StructDef(fields=[field_def]),
@@ -174,8 +178,8 @@ def test_repeated_field_preserves_range_and_enum_metadata():
         "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_type is ValueKind
-    assert decoded.field_instances[1].field_def.enum_type is ValueKind
+    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():
@@ -212,6 +216,10 @@ 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),
@@ -220,14 +228,123 @@ def test_field_def_to_json_from_json_round_trip():
                          repeat=3,
                          description="A repeated value",
                          range_expression="0 <= value <= 255",
-                         enum_type=ValueKind)
+                         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_type is ValueKind
+    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():
@@ -358,10 +475,11 @@ def test_type_expression_uses_previous_field_value():
         bytearray(),
     )
     decoded_int = decode(struct_def, encoded_int)
-    assert decoded_int.field_instances == [
-        FieldInstance(struct_def[0], 1),
-        FieldInstance(struct_def[1], 7),
-    ]
+    assert decoded_int.field_instances[0] == FieldInstance(struct_def[0], 1)
+    assert decoded_int.field_instances[1].field_def.offset == InfoSize(1, 0)
+    assert decoded_int.field_instances[1].field_def.size == InfoSize(1, 0)
+    assert decoded_int.field_instances[1].field_def.type == "int"
+    assert decoded_int.field_instances[1].value == 7
 
     encoded_float = encode(
         StructInstance(struct_def=StructDef(fields=struct_def),
@@ -373,7 +491,9 @@ def test_type_expression_uses_previous_field_value():
     )
     decoded_float = decode(struct_def, encoded_float)
     assert decoded_float.field_instances[0] == FieldInstance(struct_def[0], 2)
-    assert decoded_float.field_instances[1].field_def == struct_def[1]
+    assert decoded_float.field_instances[1].field_def.offset == InfoSize(1, 0)
+    assert decoded_float.field_instances[1].field_def.size == InfoSize(4, 0)
+    assert decoded_float.field_instances[1].field_def.type == "float"
     assert decoded_float.field_instances[1].value == 1.5
 
 
@@ -410,6 +530,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",
@@ -535,6 +733,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.3.0 → sltcodec-0.5.0}/uv.lock

@@ -74,7 +74,7 @@ wheels = [
 
 [[package]]
 name = "sltcodec"
-version = "0.2.0"
+version = "0.4.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" },
 ]