construct-typing

What it is and what it does

construct-typing extends the construct binary parser library with type hints and static type checking. It provides two components: stub files (.pyi) that add PEP 561 type information to construct's parse and build methods, and additional typed wrapper classes that map binary structures to dataclasses with strict type enforcement and IDE autocompletion.

The package is designed for developers who want compile-time type safety when working with binary data. Instead of accepting Any types for complex nested structures, you define strongly-typed dataclasses that map directly to binary formats. This enables static type checkers like mypy and pyright to catch type errors before runtime and provides IDE autocompletion for field access. The trade-off is slightly more verbose code—you must use the correct typed container rather than generic dicts—but the benefit is early error detection and better developer experience.

Use it for:

• Add type hints to an existing construct-based binary parser to enable static type checking.
• Define a strongly-typed binary file format with IDE autocompletion for structured binary data.
• Build a declarative parser with full type safety and dataclass integration.
• Enforce correct types at build time using typed enum wrappers instead of raw constants.
• Generate type stubs for a custom construct library to enable type checking across a team.

Worth the install?

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

Adds type hints and static type checking support to the construct binary parser library, enabling type-safe parsing and building of binary data structures.

Yes, if you use construct and want type safety. The stubs alone provide immediate value for existing code via PEP 561 auto-discovery. The additional typed classes are marked experimental but functional. Low install friction, active maintenance, no known vulnerabilities, and MIT licensing make it a safe addition. Skip it only if you have no type-checking infrastructure or prefer construct's flexibility over strict typing.

Install

construct-typing on PyPI

pip install construct-typing

uv add construct-typing

poetry add construct-typing

Installing construct-typing

Before you install

Low install friction with a pure-Python wheel. Actively maintained with a recent release 22 days ago. Depends on construct, arrow, and typing_extensions—all stable, widely-used packages.

License in practice

MIT license permits unrestricted use, modification, and distribution in commercial and private projects with minimal attribution requirements.

Quickstart

pip install construct-typing

import dataclasses
from construct import Int8ub, Bytes
from construct_typing import DataclassMixin, DataclassStruct, csfield

@dataclasses.dataclass
class Image(DataclassMixin):
    width: int = csfield(Int8ub)
    height: int = csfield(Int8ub)

format = DataclassStruct(Image)
obj = Image(width=3, height=2)
print(format.build(obj))

Requires Python 3.10 or later; construct must be installed as a runtime dependency.

Verify before relying

• Stability and production-readiness of the typed constructs module beyond its experimental status.
• Performance overhead of typed wrappers compared to raw construct for large-scale parsing.
• Compatibility guarantees with future versions of construct beyond 2.10.

Package facts

Evidence: construct_typing-0.8.1-py3-none-any.whl

Keywords: construct, kaitai, declarative, data structure, struct, binary, symmetric, parser, builder, parsing, building, pack, unpack, packer, unpacker, bitstring, bytestring, annotation, type hint, typing, typed, bitstruct, PEP 561

Tags

More Python Modules packages