Registry / type-stubs / construct-typing

construct-typing

JSON →
library0.8.1pypypi✓ verified 21d ago

Construct Typing is an extension for the `construct` Python package, which provides a powerful declarative and symmetrical parser and builder for binary data. It enhances `construct` by adding comprehensive typing features, including `.pyi` stub files for the entire `construct` library (via `construct-stubs`) and additional strongly-typed classes (via `construct_typed`) for improved autocompletion and type hints, particularly for complex structures like `Struct` and `Enum`. The library is actively maintained, with regular releases, and the latest version is 0.7.0.

pip install construct-typing
INSTALL
IMPORT
SIG · CONSTRUCT-TYPING
C
construct-typing
type-stubspythonv0.8.1
Install
2.0s avg
Import
163ms
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.8.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.172s · 23.2MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.0s · import 0.154s · 24MB
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DataclassStruct
from construct_typed import DataclassStruct
Used to create strongly-typed structs based on dataclasses.
TEnum
from construct_typed import TEnum
Used to create strongly-typed enums for `construct` fields.
csfield
from construct_typed import csfield
A field descriptor to associate `construct` definitions with dataclass fields.
DataclassMixin
from construct_typed import DataclassMixin
Mixin for dataclasses to enable `construct_typed` functionality.
construct
import construct as cs
from construct import *
While `construct-typing` adds stubs, standard `construct` imports should still use `import construct as cs` or specific imports for clarity and to avoid namespace pollution.

This quickstart demonstrates defining a typed binary structure using `construct-typing`'s `DataclassStruct` and `TEnum`. It shows how to combine standard `construct` fields with Python dataclasses, enabling strong type hints for both parsing and building binary data. The example includes parsing existing binary data into a typed object and building binary data from a typed object, highlighting the symmetric nature of `construct` augmented with type safety.

import dataclasses import typing as t from construct import Array, Byte, Const, Int8ub, this from construct_typed import DataclassMixin, DataclassStruct, TEnum, csfield # Define a typed Enum class Orientation(TEnum, Int8ub): HORIZONTAL: t.ClassVar[int] = 0 VERTICAL: t.ClassVar[int] = 1 # Define a typed Struct using dataclasses @dataclasses.dataclass class Image(DataclassMixin): signature: bytes = csfield(Const(b"BMP")) orientation: Orientation = csfield(TEnum(Int8ub, Orientation)) width: int = csfield(Int8ub) height: int = csfield(Int8ub) pixels: t.List[int] = csfield(Array(this.width * this.height, Byte)) # Example usage: Parse binary data img_bytes = b"BMP\x00\x03\x02\x07\x08\t\x0b\x0c\r" parsed_image = Image.parse(img_bytes) print(f"Parsed Image: {parsed_image}") # Expected: Parsed Image: Image(signature=b'BMP', orientation=<Orientation.HORIZONTAL: 0>, width=3, height=2, pixels=[7, 8, 9, 11, 12, 13]) # Example usage: Build binary data from a typed object built_bytes = Image.build( Image( orientation=Orientation.HORIZONTAL, width=3, height=2, pixels=[7, 8, 9, 11, 12, 13] ) ) print(f"Built Bytes: {built_bytes}") # Expected: Built Bytes: b'BMP\x00\x03\x02\x07\x08\t\x0b\x0c\r'
Debug
Known issues
breakingThe `construct-stubs` package underwent a significant rework in version `v0.6.0` to improve compatibility with `pyright>=v1.1.310`. This involved changes to the `__new__` and `__init__` methods of various constructs, which could cause type checking errors or unexpected runtime behavior for users relying on older `pyright` versions or specific type inference patterns.
fix
Update `pyright` to a compatible version (e.g., `v1.1.310` or newer) and review type checking errors, adjusting code if necessary to align with the new stub definitions.
affects: >=0.6.0
gotchaWhen using `DataclassStruct` or similar strongly typed constructs for building binary data, you must provide an instance of the corresponding `dataclass` (e.g., `Image(...)` in the quickstart) instead of a generic Python dictionary. `construct-typing` enforces the correct container type to leverage static type checking, departing from the dictionary-based building often used with standard `construct`.
fix
Always pass an instance of the associated `dataclass` when building with `DataclassStruct` and related typed constructs. The `dataclass` instance ensures type correctness at build time.
affects: All
gotchaThe `construct_typed` package, which provides the core enhanced typing features (like `DataclassStruct` and `TEnum`), is explicitly marked as an "EXPERIMENTAL VERSION" in the official documentation. While actively developed, this implies that its API or behavior might be subject to non-backward compatible changes in future minor or patch releases.
fix
Exercise caution when relying on advanced features of `construct_typed` in production. Monitor release notes for potential breaking changes. Consider pinning to specific `construct-typing` versions to mitigate unexpected updates.
affects: All
gotchaWhile `construct-typing` aims for compatibility with both `mypy` and `pyright`, these static type checkers can exhibit semantic differences, especially with complex type annotations, overloads, or in scenarios with partially untyped code. Users might encounter discrepancies in reported errors or warnings between the two tools.
fix
Choose a primary type checker and configure it strictly (e.g., `pyright` is often preferred by `construct-typing` for its `__new__` handling). If supporting both, be aware of potential differences and consult each tool's documentation for specific configurations or known limitations related to complex typing.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'construct_typed'
The 'construct_typed' sub-package, which contains the strongly-typed constructs like DataclassStruct and TEnum, is not directly importable because the 'construct-typing' package, which includes it, has not been installed or is not accessible in the current Python environment.
fix
Install the 'construct-typing' package using pip: `pip install construct-typing`
AttributeError: module 'construct' has no attribute 'DataclassStruct'
Developers are attempting to import or use typed constructs like `DataclassStruct` or `TEnum` directly from the base `construct` module, but these specialized classes are provided by the `construct_typed` sub-package.
fix
Import the specialized typed constructs from the `construct_typed` module: `from construct_typed import DataclassStruct, TEnum`
Stub file not found for "construct"
Static type checkers like Pyright or MyPy report this diagnostic when they cannot locate the `.pyi` stub files for the original `construct` library, which are provided by the `construct-stubs` part of `construct-typing` to enable type checking for `construct`'s core components.
fix
Ensure that the `construct-typing` package is correctly installed in the Python environment being used by the type checker. Running `pip install construct-typing` should resolve this by installing `construct-stubs`.
error: "Container" has no attribute "my_field" [attr-defined]
When using the standard `construct.Struct` or similar constructs, static type checkers often default to less specific types like `construct.Container[typing.Any]` or `typing.Dict[str, typing.Any]` for their parsed output, leading to type errors when accessing fields with dot notation or expecting specific member types.
fix
To achieve strongly-typed structures with proper autocompletion and type validation, use `DataclassStruct` from `construct_typed` in conjunction with a Python `dataclass` to define the structure and its fields with explicit type annotations.
Upgrade
Version history
0.8.1latest on PyPI · released Jul 23, 2026
Audit
Dependencies
constructrequiredCore dependency for binary data parsing and building functionality.
typing-extensionsrequiredProvides backported and experimental typing features for wider Python version compatibility.
Agent activity
39 hits · last 30 days
node
32
Amazon
1
OpenAI (training)
1
Resources
construct-typing — pip install construct-typing · libregistry