construct-classes

What it is and what it does

construct-classes bridges the gap between the construct library and Python dataclasses, letting you define binary data formats as typed dataclass structs. You write a Construct expression in a SUBCON class attribute, and the package handles parsing binary input into dataclass instances and building dataclass instances back into binary output. The dataclass fields must match the Construct struct field names, and you are responsible for keeping them in sync—there is no automatic type verification.

The package supports nested structs and lists through explicit type hints and a subcon() helper, and it integrates with the dataclass decorator system, allowing you to use standard dataclass parameters like frozen=True or kw_only. It typechecks cleanly with mypy and pyright, making it suitable for projects that want strong typing around binary protocols.

Use it for:

• Parse network protocol packets or binary file formats into typed dataclass objects for type-safe processing
• Serialize application dataclasses into binary format for storage or transmission over binary protocols
• Define binary struct schemas as Python classes with IDE autocompletion and static type checking
• Build binary protocol handlers where construct expressions define the wire format and dataclasses define the in-memory representation

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Parses binary data into Python dataclasses and packs dataclasses back into binary data using construct expressions.

Yes, if you need to work with binary data formats and want the safety of typed dataclasses. The package is actively maintained, has no security vulnerabilities, and low install friction. The main trade-off is that you must manually keep Construct expressions and dataclass fields in sync—this is acceptable for small to medium projects but could become error-prone at scale without additional tooling like construct-typing.

Install

construct-classes on PyPI

pip install construct-classes

uv add construct-classes

poetry add construct-classes

Installing construct-classes

Before you install

Low friction: pure Python wheel with a single runtime dependency (construct). Actively maintained with recent commits and no known vulnerabilities.

License in practice

MIT license permits commercial and private use with minimal restrictions—suitable for most projects.

Quickstart

pip install construct-classes

import construct as c
from construct_classes import Struct

class BasicStruct(Struct):
    x: int
    y: int
    SUBCON = c.Struct(
        "x" / c.Int32ul,
        "y" / c.Int32ul,
    )

data = b"\x01\x00\x00\x00\x02\x00\x00\x00"
parsed = BasicStruct.parse(data)
built = BasicStruct(x=100, y=200).build()

Requires Python 3.10 or later. Programmer must manually write matching Construct expressions and dataclass fields—no automatic type verification.

Verify before relying

• Whether construct-typing provides the full type-checking experience mentioned in the description and how it integrates with construct-classes
• Performance characteristics when parsing or packing large or deeply nested binary structures

Package facts

Evidence: construct_classes-0.2.3-py3-none-any.whl

Tags

More Software Development packages