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)

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.

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.