StructLayoutToolkitCodec

sltcodec encodes and decodes bytearrays according to structured layout definitions. It uses sltcore for bit-level access.

Installation

pip install sltcodec

Quick Example

StructLayout bundles the root structure name with its TypeDict. Pass the same layout to both encode and decode.

from sltcore import InfoSize
from sltcodec import (
    FieldDef,
    FieldInstance,
    StructDef,
    StructInstance,
    StructLayout,
    TypeDict,
    decode,
    encode,
)

fields = [
    FieldDef(name="flag", offset=InfoSize(0, 0), size=InfoSize(0, 1), type="bool"),
    FieldDef(name="value", offset=InfoSize(0, 1), size=InfoSize(1, 0), type="unsigned int"),
]
struct_def = StructDef(name="Packet", fields=fields)
layout = StructLayout(
    struct_def_name="Packet",
    type_dict=TypeDict(struct_dict={"Packet": struct_def}),
)
instance = StructInstance(
    struct_def=struct_def,
    field_instances=[
        FieldInstance(fields[0], True),
        FieldInstance(fields[1], 0xA5),
    ],
)

encoded = encode(layout, instance, bytearray())
decoded = decode(layout, encoded)

Progress Callbacks

encode and decode accept an optional progress_callback argument. The callback is typed as ProgressCallback and receives a float progress value from 0.0 to 1.0.

Progress is calculated for top-level fields as (offset + size) / total_size. Nested structure encode/decode calls pass None internally, so recursive fields do not emit additional callback events.

encode and decode also accept an optional env dictionary for evaluating expression-based field definitions. The default is None, which uses an empty environment. The same environment is passed to recursive nested structure encode and decode calls.

from sltcodec import ProgressCallback, decode

def update_progress(progress: float) -> None:
    progress_bar.value = progress

progress_callback: ProgressCallback = update_progress
decoded = decode(layout, encoded, progress_callback=progress_callback)

decode returns a StructInstance whose size is the actual end of the decoded layout. decode_field stores the actual decoded size in the returned FieldInstance.field_def.size. For nested StructDef fields, that size comes from the nested StructInstance.size; for repeated fields, the next element's offset advances by the actual size of the previous element.

FieldDef.repeat also accepts the special string value "end". When repeat="end", decoding repeats until the input bytearray ends. Decoding stops when the next element offset is out of range or when the next element size would exceed the remaining input.

Field Types

The public PRIMITIVE_TYPES set contains:

{"bool", "signed int", "int", "unsigned int", "float", "bytearray", "bytes"}

FieldDef.type may also be a nested StructDef or an expression string. Expressions can use values from previously processed fields, allowing dynamic types, sizes, and repeat counts. Repeated fields, byte swapping, padding, ranges, and enum metadata are supported.

Enums And Named Structures

Store named structures in TypeDict.struct_dict and enums in TypeDict.enum_dict. A field refers to an enum by its enum_def_name; the codec resolves it through StructLayout.type_dict.

from sltcore import InfoSize
from sltcodec import EnumDef, FieldDef, StructDef, StructLayout, TypeDict, decode

enum_def = EnumDef(name="Status", values={"OK": 0, "NG": 1})
packet = StructDef(
    name="Packet",
    fields=[FieldDef(
        name="status",
        offset=InfoSize(0, 0),
        size=InfoSize(1, 0),
        type="unsigned int",
        enum_def_name="Status",
    )],
)
layout = StructLayout(
    struct_def_name="Packet",
    type_dict=TypeDict(
        struct_dict={"Packet": packet},
        enum_dict={"Status": enum_def},
    ),
)

decoded = decode(layout, bytearray(b"\x01"))
assert decoded.field_instances[0].enum_item == ("NG", 1)

Saving And Loading

Persist a complete StructLayout, including its root structure name, structure definitions, and enum definitions, with save_struct_layout and load_struct_layout.

from pathlib import Path
from sltcodec import load_struct_layout, save_struct_layout

path = Path("struct_layout.json")
save_struct_layout(layout, path)
loaded = load_struct_layout(path)
assert loaded == layout

InfoSize values are stored as typed JSON dictionaries. Expression-based offsets and sizes remain strings and are evaluated when the layout is used.

Public API Reference

The following symbols are exported by sltcodec.__all__ in this order:

Types (types.py)

Classes are listed in their definition order. The member tables show the dataclass fields or constructor attributes. Methods beginning with _ are internal implementation details and are omitted from the public method tables.

EnumDef

FieldDef

FieldInstance

StructDef

StructInstance

EnumDict

StructDict

TypeDict

TypeDict(enum_dict=None, struct_dict=None) constructs both containers from optional dictionaries.

StructLayout

StructLayout(struct_def_name, type_dict) constructs a layout bundle.

Codec (codec.py)

The following public definitions are listed in their definition order. Names beginning with _ are internal helpers and are not part of the public API.

save_struct_def_dict, load_struct_def_dict, save_enum_def_dict, and load_enum_def_dict are available from sltcodec.codec for dictionary-level compatibility. The package root exports the complete StructLayout API: save_struct_layout and load_struct_layout.