construct-classes

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.

There are currently no other features. In particular, the resulting class is a Python dataclass, but you cannot specify its parameters like frozen etc.

Installing

Install using pip:

$ pip install construct-classes

Changelog

See CHANGELOG.rst.

Footer

• Free software: MIT License