construct-classes 0.2.2

Parse your binary structs into dataclasses

Parse your binary data into dataclasses. Pack your dataclasses into binary data.

construct-classes rely on construct for parsing and packing. The programmer needs to manually write the Construct expressions. There is also no type verification, so it is the programmer’s responsibility that the dataclass and the Construct expression match.

For fully type annotated experience, install construct-typing.

This package typechecks with mypy and pyright.

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

Changelog

See CHANGELOG.rst.

Footer

• Free software: MIT License