sltcodec 0.2.0__py3-none-any.whl

sltcodec/__init__.py

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

sltcodec/codec.py

@@ -0,0 +1,428 @@
+"""Encoding and decoding of structured layouts into bytearrays."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from sltcalc import SltEval
+from sltcore import Info, InfoSize, bits_get, bits_set
+
+from .types import FieldDef, FieldInstance, StructDef, StructInstance
+
+_PRIMITIVE_TYPES = {
+    "bool",
+    "signed int",
+    "int",
+    "unsigned int",
+    "float",
+    "bytearray",
+    "bytes",
+}
+
+
+def _as_field_defs(struct_def: StructDef | list[FieldDef]) -> list[FieldDef]:
+    """Normalize StructDef/list inputs to a list of field definitions."""
+    if isinstance(struct_def, StructDef):
+        return struct_def.fields
+    return struct_def
+
+
+def _validate_struct_instance(struct_instance: StructInstance) -> None:
+    """Validate that encode input is a well-typed StructInstance."""
+    if not isinstance(struct_instance, StructInstance):
+        raise TypeError("encode() expects StructInstance for struct_instance")
+    for index, field_instance in enumerate(struct_instance.field_instances):
+        if not isinstance(field_instance, FieldInstance):
+            raise TypeError(
+                "encode() expects StructInstance.field_instances to be "
+                "list[FieldInstance]. "
+                f"Invalid item at index {index}: "
+                f"{type(field_instance).__name__}")
+
+
+def save_struct_def_dict(path: str | Path,
+                         struct_def_dict: dict[str, StructDef]) -> None:
+    """Save a structure definition dictionary to a JSON file."""
+    payload = {
+        name: struct_def.to_dict()
+        for name, struct_def in struct_def_dict.items()
+    }
+    Path(path).write_text(json.dumps(payload, ensure_ascii=False, indent=2),
+                          encoding="utf-8")
+
+
+def load_struct_def_dict(path: str | Path) -> dict[str, StructDef]:
+    """Load a structure definition dictionary from a JSON file."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    return {
+        name: StructDef.from_dict(field_def_data)
+        for name, field_def_data in data.items()
+    }
+
+
+def _resolve_info_size(value: InfoSize | str, env: dict[str, Any]) -> InfoSize:
+    """Resolve an InfoSize value that can be static or expression-based."""
+    if isinstance(value, str):
+        stleval = SltEval(env)
+        resolved_byte = stleval.eval(value)
+        return InfoSize(resolved_byte, 0)
+    return value
+
+
+def _resolve_offset(field_def: FieldDef, env: dict[str, Any]) -> InfoSize:
+    """Resolve a field offset that can be static or expression-based."""
+    return _resolve_info_size(field_def.offset, env)
+
+
+def _resolve_size(field_def: FieldDef, env: dict[str, Any]) -> InfoSize:
+    """Resolve a field size that can be static or expression-based."""
+    return _resolve_info_size(field_def.size, env)
+
+
+def _is_padding_field_def(field_def: FieldDef) -> bool:
+    """Check whether a field definition represents padding."""
+    return (field_def.name.startswith("padding[")
+            and field_def.type in ["bytes", "bytearray"])
+
+
+def _info_size_to_bits(info_size: InfoSize) -> int:
+    """Convert InfoSize to an absolute bit count."""
+    return info_size.byte * 8 + info_size.bit
+
+
+def _info_size_from_bits(total_bits: int) -> InfoSize:
+    """Create InfoSize from an absolute bit count."""
+    return InfoSize(total_bits >> 3, total_bits & 0x7)
+
+
+def _resolve_field_type(field_type: str | StructDef,
+                        struct_def_dict: dict[str, StructDef] | None = None,
+                        env: dict[str, Any] | None = None) -> str | StructDef:
+    """Resolve a field type that can be primitive, named, or nested."""
+    if isinstance(field_type, StructDef):
+        return field_type
+    if field_type in _PRIMITIVE_TYPES:
+        return field_type
+
+    resolved_struct_def = _get_struct_def(field_type, struct_def_dict, env)
+    if isinstance(resolved_struct_def, StructDef):
+        return resolved_struct_def
+    if (isinstance(resolved_struct_def, str)
+            and resolved_struct_def in _PRIMITIVE_TYPES):
+        return resolved_struct_def
+    return field_type
+
+
+def _encode_primitive(field_type: str, value: Any, size: InfoSize,
+                      scale: float) -> Info:
+    """Convert a primitive typed value into an Info object for bits_set."""
+    if field_type == "bool":
+        return Info.from_bool(bool(value), size, scale=scale)
+    if field_type == "signed int":
+        return Info.from_signed_int(int(value), size, scale=scale)
+    if field_type in ["int", "unsigned int"]:
+        return Info.from_unsigned_int(int(value), size, scale=scale)
+    if field_type == "float":
+        return Info.from_float(float(value), size, scale=scale)
+    if field_type in ["bytearray", "bytes"]:
+        return Info.from_bytes(bytes(value), size, scale=scale)
+    if isinstance(value, (bytes, bytearray)):
+        return Info.from_bytes(bytes(value), size, scale=scale)
+    if isinstance(value, bool):
+        return Info.from_bool(value, size, scale=scale)
+    if isinstance(value, int):
+        return Info.from_unsigned_int(value, size, scale=scale)
+
+    return Info(raw_value=value, info_size=size, scale=scale)
+
+
+def _prepare_field_info(
+    field_def: FieldDef,
+    value: Any,
+    env: dict[str, Any],
+    struct_def_dict: dict[str, StructDef] | None = None
+) -> tuple[InfoSize, InfoSize, Info] | None:
+    """Resolve a field definition into an offset, size, and info payload."""
+    offset = _resolve_offset(field_def, env)
+    size = _resolve_size(field_def, env)
+    if size.byte == 0 and size.bit == 0:
+        return None
+
+    resolved_type = _resolve_field_type(field_def.type, struct_def_dict, env)
+    if isinstance(resolved_type, StructDef):
+        if not isinstance(value, StructInstance):
+            raise TypeError(
+                "Nested StructDef fields must be encoded with StructInstance "
+                "values")
+        nested_bytes = encode(value, bytearray(), struct_def_dict)
+        info = Info.from_bytes(bytes(nested_bytes), size, scale=field_def.scale)
+    else:
+        info = _encode_primitive(resolved_type, value, size, field_def.scale)
+    return offset, size, info
+
+
+def _split_repeated_field(field_def: FieldDef,
+                          index: int,
+                          env: dict[str, Any],
+                          offset: InfoSize | str | None = None) -> FieldDef:
+    """Create a repeated-field definition with resolved offset and size."""
+    resolved_offset = (_resolve_offset(field_def, env)
+                       if offset is None else offset)
+    resolved_size = _resolve_size(field_def, env)
+    return 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:
+    """Encode a single field into a bytearray."""
+    if env is None:
+        env = {}
+
+    prepared = _prepare_field_info(field_def, value, env, struct_def_dict)
+    if prepared is None:
+        return
+
+    offset, size, info = prepared
+    required_bytes = (offset + size).bytes
+    if len(buf) < required_bytes:
+        buf.extend(b"\x00" * (required_bytes - len(buf)))
+
+    bits_set(buf, offset, info)
+
+
+def encode(struct_instance: StructInstance,
+           buf: bytearray,
+           struct_def_dict: dict[str, StructDef] | None = None) -> bytearray:
+    """Encode decode() result into a bytearray.
+
+    Parameters
+    ----------
+    struct_instance : StructInstance
+        The structure instance to encode.
+    buf : bytearray
+        The base bytearray instance to write into.
+    struct_def_dict : dict[str, StructDef] | None, optional
+        A dictionary of structure definitions, by default None.
+
+    Returns
+    -------
+    bytearray
+        The encoded bytearray.
+    """
+    _validate_struct_instance(struct_instance)
+    env: dict[str, Any] = {}
+    has_padding = False
+
+    for field_value in struct_instance.field_instances:
+        field_def = field_value.field_def
+        if _is_padding_field_def(field_def):
+            has_padding = True
+        value = field_value.value
+        if _is_padding_field_def(field_def):
+            padding_size = _resolve_size(field_def, env)
+            value = bytearray(padding_size.bytes)
+        if field_def.repeat is not None and field_def.repeat > 1:
+            current_offset = _resolve_offset(field_def, env)
+            resolved_size = _resolve_size(field_def, env)
+            values = list(value)
+
+            for i in range(field_def.repeat):
+                field_def_repeat = _split_repeated_field(
+                    field_def, i, env, current_offset)
+                encode_field(field_def_repeat, values[i], buf, env,
+                             struct_def_dict)
+                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)
+        env[field_def.name] = value
+
+    if has_padding and struct_instance.size.bytes > len(buf):
+        buf.extend(b"\x00" * (struct_instance.size.bytes - len(buf)))
+
+    return buf
+
+
+def decode_field(
+    field_def: FieldDef,
+    data: bytearray | bytes,
+    env: dict[str, Any] | None = None,
+    struct_def_dict: dict[str, StructDef] | None = None
+) -> FieldInstance | None:
+    """Decode a single field from a bytearray according to a field definition.
+
+    Parameters
+    ----------
+    field_def : FieldDef
+        The definition of the field to decode.
+    data : bytearray | bytes
+        The data to decode.
+    env : dict[str, Any] | None, optional
+        The environment for evaluating expressions, by default None.
+    struct_def_dict : dict[str, StructDef] | None, optional
+        A dictionary of structure definitions, by default None.
+    Returns
+    -------
+    FieldInstance | None
+        The decoded field instance, or None when size is zero.
+    """
+    if env is None:
+        env = {}
+    offset = _resolve_offset(field_def, env)
+    size = _resolve_size(field_def, env)
+    if size.byte == 0 and size.bit == 0:
+        return None
+    info = bits_get(data, offset, size, scale=field_def.scale)
+    resolved_type = _resolve_field_type(field_def.type, struct_def_dict, env)
+    if isinstance(resolved_type, StructDef):
+        return FieldInstance(
+            field_def=field_def,
+            value=decode(resolved_type, bytearray(info.to_bytes),
+                         struct_def_dict),
+        )
+    if resolved_type == "bool":
+        return FieldInstance(field_def=field_def, value=info.to_bool)
+    if resolved_type == "signed int":
+        return FieldInstance(field_def=field_def, value=info.to_signed_int)
+    if resolved_type in ["int", "unsigned int"]:
+        return FieldInstance(field_def=field_def, value=info.to_unsigned_int)
+    if resolved_type == "float":
+        return FieldInstance(field_def=field_def, value=info.to_float)
+    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)
+
+
+def decode(
+        struct_def: StructDef | list[FieldDef],
+        data: bytearray | bytes,
+        struct_def_dict: dict[str, StructDef] | None = None) -> StructInstance:
+    """Decode a bytearray into field values according to a layout.
+
+    Parameters
+    ----------
+    struct_def : StructDef | list[FieldDef]
+        The definitions of the fields to decode.
+    data : bytearray | bytes
+        The data to decode.
+    struct_def_dict : dict[str, StructDef] | None, optional
+        A dictionary of structure definitions, by default None.
+    Returns
+    -------
+    StructInstance
+        The decoded structure instance.
+    """
+    env = {}
+    struct_def_obj = (struct_def if isinstance(struct_def, StructDef) else
+                      StructDef(fields=struct_def))
+    result = StructInstance(struct_def=struct_def_obj)
+    current_position = InfoSize(0, 0)
+    padding_index = 0
+
+    def append_padding_until(target_offset: InfoSize) -> None:
+        nonlocal current_position, padding_index
+        start_bits = _info_size_to_bits(current_position)
+        end_bits = _info_size_to_bits(target_offset)
+        if end_bits <= start_bits:
+            return
+
+        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)
+            padding_field_def = FieldDef(
+                name=f"padding[{padding_index}]",
+                offset=_info_size_from_bits(chunk_start_bits),
+                size=_info_size_from_bits(chunk_end_bits - chunk_start_bits),
+                type="bytes",
+                description="Auto-generated padding",
+            )
+            padding_field_instance = decode_field(padding_field_def, data)
+            if padding_field_instance is not None:
+                result.append_field_instance(padding_field_instance)
+            padding_index += 1
+            chunk_start_bits = chunk_end_bits
+
+        current_position = target_offset
+
+    for field_def in _as_field_defs(struct_def_obj):
+        # Handle non-repeated fields
+        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)
+            if field_instance is not None:
+                env[field_instance.field_def.name] = field_instance.value
+                result.append_field_instance(field_instance)
+                current_position = (resolved_offset +
+                                    _resolve_size(field_def, env))
+            continue
+        # Handle repeated fields
+        current_offset = _resolve_offset(field_def, env)
+        resolved_size = _resolve_size(field_def, env)
+        append_padding_until(current_offset)
+        for i in range(field_def.repeat):
+            field_def_repeat = _split_repeated_field(field_def, i, env,
+                                                     current_offset)
+            field_instance = decode_field(field_def_repeat, data, env,
+                                          struct_def_dict)
+            if field_instance is not None:
+                env[field_instance.field_def.name] = field_instance.value
+                result.append_field_instance(field_instance)
+                current_position = current_offset + resolved_size
+            current_offset += resolved_size
+
+    append_padding_until(result.size)
+
+    return result
+
+
+def _get_struct_def(
+        struct_def_name: str,
+        struct_def_dict: dict[str, StructDef] | None = None,
+        env: dict[str, Any] | None = None) -> StructDef | str | None:
+    """Get a structure definition from a dictionary or evaluate it.
+
+    Parameters
+    ----------
+    struct_def_name : str
+        The name of the structure definition to get.
+    struct_def_dict : dict[str, StructDef] | None, optional
+        A dictionary of structure definitions, by default None.
+    env : dict[str, Any] | None, optional
+        The environment for evaluating the structure definition,
+        by default None.
+
+    Returns
+    -------
+    StructDef | str | None
+        The structure definition, primitive type, or None if not found.
+    """
+    if struct_def_dict and struct_def_name in struct_def_dict:
+        return struct_def_dict[struct_def_name]
+
+    stleval = SltEval(env)
+    try:
+        eval_result = stleval.eval(struct_def_name)
+    except (SyntaxError, NameError, TypeError, ValueError):
+        return None
+
+    if isinstance(eval_result, str) and eval_result in _PRIMITIVE_TYPES:
+        return eval_result
+    if (isinstance(eval_result, str) and struct_def_dict
+            and eval_result in struct_def_dict):
+        return struct_def_dict[eval_result]
+    return None

sltcodec/types.py

@@ -0,0 +1,359 @@
+"""Type definitions for structured layout metadata."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from sltcore import Info, InfoSize
+
+
+@dataclass(frozen=True)
+class FieldDef:
+    """A field in a structured layout."""
+    name: str = field(default_factory=str,
+                      metadata={"desc": "The name of the field"})
+    offset: InfoSize | str = field(default_factory=InfoSize,
+                                   metadata={"desc": "The offset of the field"})
+    size: InfoSize | str = field(default_factory=InfoSize,
+                                 metadata={"desc": "The size of the field"})
+    type: str | "StructDef" = field(default_factory=str,
+                                    metadata={"desc": "The type of the field"})
+    scale: float = field(default=1.0,
+                         metadata={"desc": "The scale of the field"})
+    repeat: int | None = field(
+        default=None, metadata={"desc": "The repeat count of the field"})
+    description: str | None = field(
+        default=None, metadata={"desc": "The description of the field"})
+
+    def split_repeat(self,
+                     index: int,
+                     offset: 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,
+                        scale=self.scale,
+                        repeat=None,
+                        description=self.description)
+
+    def __lt__(self, other: object) -> bool:
+        """Compare field definitions using a stable serialized sort key."""
+        if not isinstance(other, FieldDef):
+            return NotImplemented
+        return self._sort_key() < other._sort_key()
+
+    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,
+        }
+
+    def to_json(self) -> str:
+        """Convert this field 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]) -> "FieldDef":
+        """Create a field definition from a JSON-serializable dictionary."""
+        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"),
+        )
+
+    @classmethod
+    def from_json(cls, data: str) -> "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 (
+            self._sortable_info_size_or_expr(self.offset),
+            self._sortable_info_size_or_expr(self.size),
+            self.name,
+            self._sortable_type(self.type),
+            self.scale,
+            -1 if self.repeat is None else self.repeat,
+            "" if self.description is None else self.description,
+        )
+
+    @staticmethod
+    def _sortable_info_size_or_expr(value: InfoSize | str) -> tuple[Any, ...]:
+        """Build a comparable key for InfoSize-or-expression values."""
+        if isinstance(value, InfoSize):
+            return (0, value.byte, value.bit)
+        return (1, value)
+
+    @staticmethod
+    def _sortable_type(value: str | "StructDef") -> tuple[Any, ...]:
+        """Build a comparable key for primitive or nested field types."""
+        if isinstance(value, StructDef):
+            return (0, json.dumps(value.to_dict(), sort_keys=True))
+        return (1, value)
+
+
+@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"})
+    is_padding: bool = field(
+        default=False,
+        metadata={"desc": "Whether this field instance represents padding"},
+    )
+
+    def __lt__(self, other: object) -> bool:
+        """Compare field instances using their field definition order."""
+        if not isinstance(other, FieldInstance):
+            return NotImplemented
+        return self.field_def < other.field_def
+
+
+@dataclass(frozen=True)
+class StructDef:
+    """A structured layout definition that groups multiple fields."""
+    name: str = field(default_factory=str,
+                      metadata={"desc": "The name of the structure"})
+    description: str = field(
+        default_factory=str,
+        metadata={"desc": "The description of the structure"},
+    )
+    fields: list[FieldDef] = field(
+        default_factory=list,
+        metadata={"desc": "The fields of the structure"},
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert this structure definition to JSON-serializable data."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "fields": [field_def.to_dict() for field_def in self.fields],
+        }
+
+    def to_json(self) -> str:
+        """Convert this structure 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] | list[dict[str, Any]],
+    ) -> "StructDef":
+        """Create a structure definition from JSON-serializable data."""
+        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", [])
+                   ])
+
+    @classmethod
+    def from_json(cls, data: str) -> "StructDef":
+        """Create a structure definition from a JSON string."""
+        return cls.from_dict(json.loads(data))
+
+
+@dataclass
+class StructInstance:
+    """A decoded/encodable structure instance."""
+    struct_def: StructDef = field(
+        default_factory=StructDef,
+        metadata={"desc": "The structure definition"},
+    )
+    field_instances: list[FieldInstance] = field(
+        default_factory=list,
+        metadata={"desc": "The decoded/encodable field instances"},
+    )
+    size: InfoSize = field(
+        default_factory=InfoSize,
+        metadata={"desc": "The total size of the structure instance"},
+    )
+
+    def __post_init__(self) -> None:
+        """Normalize stored field instances to sorted order."""
+        self._sort_field_instances()
+        self._update_size()
+        self._rebuild_padding_field_instances()
+
+    def append_field_instance(self, field_instance: FieldInstance) -> None:
+        """Append one field instance to this structure instance."""
+        if not isinstance(field_instance, FieldInstance):
+            raise TypeError("field_instance must be FieldInstance")
+        self.field_instances.append(field_instance)
+        self._update_size()
+        self._rebuild_padding_field_instances()
+
+    def extend_field_instances(self,
+                               field_instances: list[FieldInstance]) -> None:
+        """Append multiple field instances to this structure instance."""
+        for field_instance in field_instances:
+            if not isinstance(field_instance, FieldInstance):
+                raise TypeError("field_instance must be FieldInstance")
+        self.field_instances.extend(field_instances)
+        self._update_size()
+        self._rebuild_padding_field_instances()
+
+    def __iter__(self):
+        """Iterate over stored field instances."""
+        return iter(self.field_instances)
+
+    def __len__(self) -> int:
+        """Return the number of stored field instances."""
+        return len(self.field_instances)
+
+    def __getitem__(self, index: int) -> FieldInstance:
+        """Return one field instance by index."""
+        return self.field_instances[index]
+
+    def _sort_field_instances(self) -> None:
+        """Keep field instances sorted by FieldDef order."""
+        self.field_instances.sort()
+
+    def _rebuild_padding_field_instances(self) -> None:
+        """Rebuild padding field instances for gaps between stored values."""
+        non_padding_instances = [
+            field_instance for field_instance in self.field_instances
+            if not field_instance.is_padding
+        ]
+        non_padding_instances.sort()
+
+        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)
+            if field_offset > current_offset:
+                gap_size = field_offset - current_offset
+                if gap_size.byte > 0 or gap_size.bit > 0:
+                    rebuilt_instances.append(
+                        FieldInstance(
+                            field_def=FieldDef(
+                                name=f"padding[{padding_index}]",
+                                offset=current_offset,
+                                size=gap_size,
+                                type="bytes",
+                                description="Auto-generated padding",
+                            ),
+                            value=bytearray(gap_size.byte),
+                            is_padding=True,
+                        ))
+                    padding_index += 1
+            rebuilt_instances.append(field_instance)
+            current_offset = field_offset + field_size
+
+        if self.size > current_offset:
+            gap_size = self.size - current_offset
+            if gap_size.byte > 0 or gap_size.bit > 0:
+                rebuilt_instances.append(
+                    FieldInstance(
+                        field_def=FieldDef(
+                            name=f"padding[{padding_index}]",
+                            offset=current_offset,
+                            size=gap_size,
+                            type="bytes",
+                            description="Auto-generated padding",
+                        ),
+                        value=bytearray(gap_size.byte),
+                        is_padding=True,
+                    ))
+
+        self.field_instances = rebuilt_instances
+        self._sort_field_instances()
+        self._update_size()
+
+    def _update_size(self) -> None:
+        """Update the instance size from the current field layout."""
+        if not self.field_instances:
+            return
+
+        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)
+            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.2.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: sltcodec
+Version: 0.2.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
+Project-URL: Repository, https://github.com/fangface-hub/StructLayoutToolkitCodec
+Project-URL: Issues, https://github.com/fangface-hub/StructLayoutToolkitCodec/issues
+Author: fangface
+License-Expression: MIT
+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
+Description-Content-Type: text/markdown
+
+# StructLayoutToolkitCodec
+
+sltcodec is a small package for decoding and encoding bytearrays according to structured layout definitions. It uses sltcore for bit-level access and provides a simple API for turning a layout definition into binary data and back again.
+
+## Installation
+
+```bash
+pip install sltcodec
+```
+
+## Quick Example
+
+`FieldDef.description` is an optional human-readable note that can be attached to each field definition.
+
+`decode` returns a `StructInstance`.
+`encode` accepts a `StructInstance` and a destination `bytearray`.
+
+```python
+from sltcore import InfoSize
+from sltcodec import (FieldDef, FieldInstance, StructDef, StructInstance,
+                      decode, encode)
+
+struct_def = [
+    FieldDef(name="flag",
+             offset=InfoSize(0, 0),
+             size=InfoSize(0, 1),
+             type="bool",
+             scale=1.0,
+             description="Whether the feature is enabled"),
+    FieldDef(name="value",
+             offset=InfoSize(0, 1),
+             size=InfoSize(1, 0),
+             type="unsigned int",
+             scale=1.0,
+             description="The encoded numeric payload"),
+]
+
+encoded = encode(
+    StructInstance(
+        struct_def=StructDef(fields=struct_def),
+        field_instances=[
+            FieldInstance(struct_def[0], True),
+            FieldInstance(struct_def[1], 0xA5),
+        ],
+    ),
+    bytearray(),
+)
+decoded = decode(struct_def, encoded)
+
+print(encoded)
+print(decoded)
+print(decoded.field_instances)
+```
+
+Output:
+
+```python
+bytearray(b"\xd2\x80")
+StructInstance(struct_def=StructDef(...), field_instances=[...])
+[FieldInstance(field_def=FieldDef(name='flag', offset=InfoSize(byte=0, bit=0), size=InfoSize(byte=0, bit=1), type='bool', scale=1.0, repeat=None), value=True),
+ FieldInstance(field_def=FieldDef(name='value', offset=InfoSize(byte=0, bit=1), size=InfoSize(byte=1, bit=0), type='unsigned int', scale=1.0, repeat=None), value=165)]
+
+```
+
+## Nested Field Types
+
+`FieldDef.type` can be a `StructDef`, not only a primitive type name.
+This allows you to define an inline nested structure and keep `encode_field` / `decode_field` behavior symmetrical.
+
+```python
+from sltcore import InfoSize
+from sltcodec import FieldDef, FieldInstance, StructDef, StructInstance, decode, encode
+
+child_struct_def = [
+    FieldDef(name="left", offset=InfoSize(0, 0), size=InfoSize(1, 0), type="unsigned int"),
+    FieldDef(name="right", offset=InfoSize(1, 0), size=InfoSize(1, 0), type="unsigned int"),
+]
+
+parent_field_def = FieldDef(
+    name="pair",
+    offset=InfoSize(0, 0),
+    size=InfoSize(2, 0),
+    type=StructDef(
+        name="Pair",
+        description="Two adjacent unsigned ints",
+        fields=child_struct_def,
+    ),
+)
+
+encoded = encode(
+    StructInstance(
+        struct_def=StructDef(fields=[parent_field_def]),
+        field_instances=[
+            FieldInstance(
+                parent_field_def,
+                StructInstance(
+                    struct_def=StructDef(fields=child_struct_def),
+                    field_instances=[
+                        FieldInstance(child_struct_def[0], 3),
+                        FieldInstance(child_struct_def[1], 4),
+                    ],
+                ),
+            )
+        ],
+    ),
+    bytearray(),
+)
+
+decoded = decode([parent_field_def], encoded)
+print(encoded)
+print(decoded)
+print(decoded.field_instances)
+```
+
+Output:
+
+```python
+bytearray(b"\x03\x04")
+StructInstance(struct_def=StructDef(...), field_instances=[...])
+[FieldInstance(field_def=FieldDef(name='pair', offset=InfoSize(byte=0, bit=0), size=InfoSize(byte=2, bit=0), type=[...], scale=1.0, repeat=None),
+               value=StructInstance(struct_def=StructDef(...), field_instances=[...]))]
+```
+
+## Expression-Based Type Selection
+
+`FieldDef.type` can also be an expression string.
+The expression is evaluated with previously processed field values in scope, so you can switch decoding/encoding type dynamically.
+
+```python
+from sltcore import InfoSize
+from sltcodec import (FieldDef, FieldInstance, StructDef, StructInstance,
+                      decode, encode)
+
+struct_def = [
+    FieldDef(name="kind", offset=InfoSize(0, 0), size=InfoSize(1, 0), type="unsigned int"),
+    FieldDef(
+        name="payload",
+        offset=InfoSize(1, 0),
+        size="{1: 1, 2: 4}[kind]",
+        type="{1: 'int', 2: 'float'}[kind]",
+    ),
+]
+
+# kind=1 -> payload is int (1 byte)
+encoded_int = encode(
+    StructInstance(
+        struct_def=StructDef(fields=struct_def),
+        field_instances=[
+            FieldInstance(struct_def[0], 1),
+            FieldInstance(struct_def[1], 7),
+        ],
+    ),
+    bytearray(),
+)
+decoded_int = decode(struct_def, encoded_int)
+
+# kind=2 -> payload is float (4 bytes)
+encoded_float = encode(
+    StructInstance(
+        struct_def=StructDef(fields=struct_def),
+        field_instances=[
+            FieldInstance(struct_def[0], 2),
+            FieldInstance(struct_def[1], 1.5),
+        ],
+    ),
+    bytearray(),
+)
+decoded_float = decode(struct_def, encoded_float)
+
+print(encoded_int, decoded_int)
+print(encoded_float, decoded_float)
+```
+
+## Saving And Loading StructDef Dictionaries
+
+You can persist reusable structure definitions by name with
+`save_struct_def_dict` / `load_struct_def_dict`.
+
+```python
+from pathlib import Path
+
+from sltcore import InfoSize
+from sltcodec import FieldDef, StructDef, load_struct_def_dict, save_struct_def_dict
+
+struct_defs = {
+    "Header": StructDef(
+        name="Header",
+        description="Simple header",
+        fields=[
+            FieldDef(name="kind", offset=InfoSize(0, 0), size=InfoSize(1, 0), type="unsigned int"),
+            FieldDef(name="flags", offset=InfoSize(1, 0), size=InfoSize(1, 0), type="unsigned int"),
+        ],
+    )
+}
+
+path = Path("struct_defs.json")
+save_struct_def_dict(path, struct_defs)
+loaded = load_struct_def_dict(path)
+
+print(loaded["Header"].name)
+print(loaded["Header"].description)
+```
+
+Example output:
+
+```python
+bytearray(b"\x01\x07") StructInstance(struct_def=StructDef(...), field_instances=[...])
+bytearray(b"\x02?\xc0\x00\x00") StructInstance(struct_def=StructDef(...), field_instances=[...])
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+```

sltcodec-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sltcodec/__init__.py,sha256=w7a_ZGDowo6-Gx2TjENJU23Ded6QkC9w6pBShADZj0s,394
+sltcodec/codec.py,sha256=YPTjEBtzKT6vu63ErYDwxn4bFsbBZO5S4sUx7_fdwDg,16826
+sltcodec/types.py,sha256=P1_g2ccJYpdygBboaBeb9H5YMY7n8WtH_MNKg2FtxG4,14416
+sltcodec-0.2.0.dist-info/METADATA,sha256=UwgpHqOdJ_iwlcZA-0QeXLhnuwhrqPsq5Ofq5nJ5_QU,6871
+sltcodec-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+sltcodec-0.2.0.dist-info/licenses/LICENSE,sha256=_WBHmfGHT8uGAnHK2W-hi7O_rO8t70lubivrqYujdIw,1065
+sltcodec-0.2.0.dist-info/RECORD,,

sltcodec-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sltcodec-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fangface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.