Construct Typing

0.7.0 · active · verified Sun Apr 12

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.

Warnings

breaking The `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.
gotcha When 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.
gotcha The `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.
gotcha While `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.

Install

pip install construct-typing Install stable version

Imports

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
```
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.

Quickstart

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'

view raw JSON →