{"id":4912,"library":"construct-typing","title":"Construct Typing","description":"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.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/timrid/construct-typing","tags":["typing","construct","binary data","data parsing","type hints","dataclasses","mypy","pyright"],"install":[{"cmd":"pip install construct-typing","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for binary data parsing and building functionality.","package":"construct","optional":false},{"reason":"Provides backported and experimental typing features for wider Python version compatibility.","package":"typing-extensions","optional":false}],"imports":[{"note":"Used to create strongly-typed structs based on dataclasses.","symbol":"DataclassStruct","correct":"from construct_typed import DataclassStruct"},{"note":"Used to create strongly-typed enums for `construct` fields.","symbol":"TEnum","correct":"from construct_typed import TEnum"},{"note":"A field descriptor to associate `construct` definitions with dataclass fields.","symbol":"csfield","correct":"from construct_typed import csfield"},{"note":"Mixin for dataclasses to enable `construct_typed` functionality.","symbol":"DataclassMixin","correct":"from construct_typed import DataclassMixin"},{"note":"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.","wrong":"from construct import *","symbol":"construct","correct":"import construct as cs"}],"quickstart":{"code":"import dataclasses\nimport typing as t\nfrom construct import Array, Byte, Const, Int8ub, this\nfrom construct_typed import DataclassMixin, DataclassStruct, TEnum, csfield\n\n# Define a typed Enum\nclass Orientation(TEnum, Int8ub):\n    HORIZONTAL: t.ClassVar[int] = 0\n    VERTICAL: t.ClassVar[int] = 1\n\n# Define a typed Struct using dataclasses\n@dataclasses.dataclass\nclass Image(DataclassMixin):\n    signature: bytes = csfield(Const(b\"BMP\"))\n    orientation: Orientation = csfield(TEnum(Int8ub, Orientation))\n    width: int = csfield(Int8ub)\n    height: int = csfield(Int8ub)\n    pixels: t.List[int] = csfield(Array(this.width * this.height, Byte))\n\n# Example usage: Parse binary data\nimg_bytes = b\"BMP\\x00\\x03\\x02\\x07\\x08\\t\\x0b\\x0c\\r\"\nparsed_image = Image.parse(img_bytes)\nprint(f\"Parsed Image: {parsed_image}\")\n# Expected: Parsed Image: Image(signature=b'BMP', orientation=<Orientation.HORIZONTAL: 0>, width=3, height=2, pixels=[7, 8, 9, 11, 12, 13])\n\n# Example usage: Build binary data from a typed object\nbuilt_bytes = Image.build(\n    Image(\n        orientation=Orientation.HORIZONTAL,\n        width=3,\n        height=2,\n        pixels=[7, 8, 9, 11, 12, 13]\n    )\n)\nprint(f\"Built Bytes: {built_bytes}\")\n# Expected: Built Bytes: b'BMP\\x00\\x03\\x02\\x07\\x08\\t\\x0b\\x0c\\r'\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}