---
id: construct-classes
version: "0.2.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# construct-classes — Parse your binary structs into dataclasses

License: permissive · Maintenance: active · Downloads: 158.5K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 158.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

binary data parsing dataclass, struct serialization deserialization, binary format to dataclass, construct wrapper dataclass, pack unpack binary struct, binary protocol dataclass, typed binary parsing, binary-parsing, dataclass-serialization

[View on SkillFed](https://skillfed.io/packages/construct-classes) · [View on PyPI](https://pypi.org/project/construct-classes/)