{"id":18746688,"url":"https://github.com/matrixeditor/construct-dataclasses","last_synced_at":"2026-03-07T20:31:58.242Z","repository":{"id":216812814,"uuid":"729853345","full_name":"MatrixEditor/construct-dataclasses","owner":"MatrixEditor","description":"Small python package that combines construct with dataclasses.","archived":false,"fork":false,"pushed_at":"2025-12-07T07:51:30.000Z","size":32,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-06T15:17:29.992Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatrixEditor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-12-10T15:03:15.000Z","updated_at":"2025-12-07T07:51:16.000Z","dependencies_parsed_at":"2024-01-13T01:41:31.502Z","dependency_job_id":"96157272-5dfb-49e0-8463-b398db76be73","html_url":"https://github.com/MatrixEditor/construct-dataclasses","commit_stats":null,"previous_names":["matrixeditor/construct-dataclasses"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/MatrixEditor/construct-dataclasses","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fconstruct-dataclasses","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fconstruct-dataclasses/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fconstruct-dataclasses/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fconstruct-dataclasses/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatrixEditor","download_url":"https://codeload.github.com/MatrixEditor/construct-dataclasses/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fconstruct-dataclasses/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30229743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T19:01:10.287Z","status":"ssl_error","status_checked_at":"2026-03-07T18:59:58.103Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T16:26:31.349Z","updated_at":"2026-03-07T20:31:58.205Z","avatar_url":"https://github.com/MatrixEditor.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# construct-dataclasses\n\n[![python](https://img.shields.io/badge/python-3.7+-blue.svg?logo=python\u0026labelColor=grey)](https://www.python.org/downloads/)\n![Codestyle](https://img.shields.io:/static/v1?label=Codestyle\u0026message=black\u0026color=black)\n![License](https://img.shields.io:/static/v1?label=License\u0026message=GNU+GPLv3\u0026color=blue)\n[![PyPI](https://img.shields.io/pypi/v/construct-dataclasses)](https://pypi.org/project/construct-dataclasses/)\n\nThis small repository is an enhancement of the python package [*construct*](https://pypi.org/project/construct/), which is a powerful tool to declare symmetrical parsers and builders for binary data. This project combines construct with python's dataclasses with support for nested structs.\n\n## Installation\n\nYou can install the package via pip or just copy the python file (*\\_\\_init\\_\\_.py*) as it is only one.\n\n```bash\npip install construct-dataclasses\n```\n\n## Usage\n\nMore usage examples are placed in the [*examples/*](/examples/) directory.\n\n### Define dataclasses\n\nBefore we can start declaring fields on a dataclass, the class itself has to be created. Currently, there are two ways on how to create\na dataclass usable by this package.\n\n1. Use the standard `@dataclass` decorator and create the parser instance afterwards (**recommended for type checking**):\n\n    ```python\n    from construct_dataclasses import DataclassStruct\n\n    @dataclasses.dataclass\n    class Foo: ...\n\n    # Create the parser manually\n    parser = DataclassStruct(Foo)\n    instance = parser.parse(...)\n    ```\n\n2. Use the `@dataclass_struct` decorator to define a new dataclass and automatically create a parser instance that will be assigned as a class attribute:\n\n    ```python\n    from construct_dataclasses import dataclass_struct\n\n    @dataclass_struct\n    class Foo: ...\n\n    # Use the class-parser to parse\n    instance = Foo.parser.parse(...)\n    # or to build\n    data = Foo.parser.build(instance)\n    ```\n\n\u003e Hint: Use `@container` to mimic a construct container instance if needed. That may be the case if you have to access\n\u003e an already parsed object of a custom type:\n\u003e ```python\n\u003e @container\n\u003e @dataclasses.dataclass\n\u003e class ImageHeader:\n\u003e   length: int = csfield(Int32ub)\n\u003e\n\u003e @dataclasses.dataclass\n\u003e class Image:\n\u003e   header: ImageHeader = csfield(ImageHeader)\n\u003e   data: bytes = csfield(Bytes(this.header.length))\n\u003e ```\n\u003e  The access to `header.length` would throw an exception without the container annotation.\n\n### Define fields\n\nThis module defines a new way how to declare fields of a dataclass. In order to combine the python package construct with python's dataclasses module, this project introduces the following four methods:\n\n- `csfield`: Default definition of a field using a subcon or other dataclass\n\n    ```python\n    @dataclass_struct\n    class ImageHeader:\n        signature: bytes = csfield(cs.Const(b\"BMP\"))\n        num_entries: int = csfield(cs.Int32ul)\n    ```\n\n- `subcsfield`: Definition of nested constructs that are contained in list-like structures.\n\n    ```python\n    @dataclass_struct\n    class Image:\n        header: ImageHeader = csfield(ImageHeader) # dataclass reference\n        width: int          = csfield(cs.Int8ub)\n        height: int         = csfield(cs.Int8ub)\n        # Note that we have to convert our dataclass into a struct using\n        # the method \"to_struct(...)\"\n        pixels: list[Pixel] = subcsfield(Pixel, cs.Array(this.width * this.height, to_struct(Pixel)))\n    ```\n\n- `tfield`: a simple typed field that tries to return an instance of the given model class. **Use `subcsfield` for dataclass models, `csenum`for simple enum fields and `tfield` for enum types in list fields**.\n\n    ```python\n    @dataclass_struct\n    class ImageHeader:\n        orientations: list[Orientation] = tfield(Orientation, cs.Enum(cs.Int8ul, Orientation))\n    ```\n\n- `csenum`: shortcut for simple enum fields\n\n    ```python\n    @dataclass_struct\n    class ImageHeader:\n        orientations: Orientation = csenum(Orientation, cs.Int8ul)\n    ```\n\n### Convert dataclasses\n\nBy default, all conversion is done automatically if you don't use instances of `SubContruct` classes in your field definitions. If you have to define a subcon that needs a nested subcon, like `Array` or `RepeatUntil` and you would like to parse a dataclass struct, it is required to convert the defined dataclass into a struct.\n\n- `to_struct`: This method converts all fields defined in a dataclass into a single `Struct` or `AlignedStruct` instance.\n\n    ```python\n    @dataclass_struct\n    class Pixel:\n        data: int = csfield(cs.Int8ub)\n\n    pixel_struct: construct.Struct = to_struct(Pixel)\n    ```\n- `to_object`: In order to use data returned by `Struct.parse`, this method can be used to apply this data and create a dataclass object from it.\n\n    ```python\n    data = pixel_struct.parse(b\"...\")\n    pixel = to_object(data, Pixel)\n    ```\n\nThe complete example is shown below:\n\n```python\n# Example modifed from here: https://github.com/timrid/construct-typing/\nimport dataclasses\nimport enum\nimport construct as cs\n\nfrom construct_dataclasses import dataclass_struct, csfield, to_struct, subcsfield, csenum\n\nclass Orientation(enum.IntEnum):\n    NONE = 0\n    HORIZONTAL = 1\n    VERTICAL = 2\n\n@dataclass_struct\nclass ImageHeader:\n    signature: bytes         = csfield(cs.Const(b\"BMP\"))\n    orientation: Orientation = csenum(Orientation, cs.Int8ub)\n\n@dataclass_struct\nclass Pixel:\n    data: int = csfield(cs.Int8ub)\n\n@dataclass_struct\nclass Image:\n    header: ImageHeader = csfield(ImageHeader)\n    width: int          = csfield(cs.Int8ub)\n    height: int         = csfield(cs.Int8ub)\n    pixels: list[Pixel] = subcsfield(Pixel, cs.Array(this.width * this.height, to_struct(Pixel)))\n\nobj = Image(\n    header=ImageHeader(\n        orientation=Orientation.VERTICAL\n    ),\n    width=3,\n    height=2,\n    pixels=[Pixel(1), Pixel(2), Pixel(3), Pixel(4), Pixel(5), Pixel(6)]\n)\n\nprint(Image.parser.build(obj))\nprint(Image.parser.parse(b\"BMP\\x02\\x03\\x02\\x01\\x02\\x03\\x04\\x05\\06\"))\n```\n\nThe expected output would be:\n\n    b'BMP\\x02\\x03\\x02\\x01\\x02\\x03\\x04\\x05\\x06'\n    Image(\n        header=ImageHeader(signature=b'BMP', orientation=\u003cOrientation.VERTICAL: 2\u003e),\n        width=3, height=2,\n        pixels=[Pixel(data=1), Pixel(data=2), Pixel(data=3), Pixel(data=4), Pixel(data=5), Pixel(data=6)]\n    )","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixeditor%2Fconstruct-dataclasses","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrixeditor%2Fconstruct-dataclasses","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixeditor%2Fconstruct-dataclasses/lists"}