{"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":"python","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,"search_vec":"'0.7.0':83 'activ':73 'ad':30 'addit':48 'autocomplet':58 'binari':24,86 'builder':22 'class':52 'complex':64 'comprehens':31 'construct':1,3,10,28,41,45,54,85 'construct-stub':44 'data':25,87,88 'dataclass':92 'declar':17 'enhanc':27 'entir':40 'enum':69 'extens':7 'featur':33 'file':37 'hint':61,91 'improv':57 'includ':34 'latest':80 'librari':42,71 'like':66 'maintain':74 'mypi':93 'packag':12 'pars':89 'parser':20 'particular':62 'power':16 'provid':14 'pyi':35 'pyright':94 'python':11 'regular':76 'releas':77 'strong':50 'strongly-typ':49 'struct':67 'structur':65 'stub':36,46 'symmetr':19 'type':2,4,32,51,55,60,84,90 'version':81 'via':43,53","created_at":"2026-04-12T16:46:02.039382+00:00","updated_at":"2026-04-16T03:41:26.528637+00:00","problems":[{"fix":"Install the 'construct-typing' package using pip: `pip install construct-typing`","cause":"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.","error":"ModuleNotFoundError: No module named 'construct_typed'"},{"fix":"Import the specialized typed constructs from the `construct_typed` module: `from construct_typed import DataclassStruct, TEnum`","cause":"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.","error":"AttributeError: module 'construct' has no attribute 'DataclassStruct'"},{"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`.","cause":"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.","error":"Stub file not found for \"construct\""},{"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.","cause":"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.","error":"error: \"Container\" has no attribute \"my_field\" [attr-defined]"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.8.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/timrid/construct-typing","docs":null,"changelog":null,"pypi":"https://pypi.org/project/construct-typing/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}