construct-classes 0.2.3

Usage

Any child of Struct is a Python dataclass. It expects a Construct Struct expression in the SUBCON attribute. The names of the attributes of the dataclass must match the names of the fields in the Construct struct.

import construct as c
from construct_classes import Struct, subcon

class BasicStruct(Struct):
    x: int
    y: int
    description: str

    SUBCON = c.Struct(
        "x" / c.Int32ul,
        "y" / c.Int32ul,
        "description" / c.PascalString(c.Int8ul, "utf8"),
    )


data = b"\x01\x00\x00\x00\x02\x00\x00\x00\x05hello"
parsed = BasicStruct.parse(data)
print(parsed)  # BasicStruct(x=1, y=2, description='hello')

new_data = BasicStruct(x=100, y=200, description="world")
print(new_data.build())  # b'\x64\x00\x00\x00\xc8\x00\x00\x00\x05world'

construct-classes support nested structs, but you need to declare them explicitly:

class LargerStruct(Struct):
    # specify the subclass type:
    basic: BasicStruct = subcon(BasicStruct)
    # in case of a list, specify the item type:
    basic_array: List[BasicStruct] = subcon(BasicStruct)
    # the `subcon()` function supports all arguments of `dataclass.field`:
    default_array: List[BasicStruct] = subcon(BasicStruct, default_factory=list)

    # to refer to the subcon, use the `SUBCON` class attribute:
    SUBCON = c.Struct(
        "basic" / BasicStruct.SUBCON,
        "basic_array" / c.Array(2, BasicStruct.SUBCON),
        "default_array" / c.PrefixedArray(c.Int8ul, BasicStruct.SUBCON),
    )

Use dataclasses.field() to specify attributes on fields that are not subcons.

By default, subclasses of Struct are kw_only. This is specifically to allow setting default values on any fields regardless of order, so that your attributes can be listed in the subcon order.

However, you can pass any valid dataclass parameters to the Struct class via class attributes:

class MyStruct(Struct, kw_only=False, frozen=True):
    a: int
    b: int

my_struct = MyStruct(1, 2)  # ok
my_struct.a = 2  # FrozenInstanceError

Installing

Install using pip:

$ pip install construct-classes

Footer

• Free software: MIT License