{"id":21106255,"url":"https://github.com/moreal/pystructs","last_synced_at":"2026-04-06T03:31:24.264Z","repository":{"id":62583788,"uuid":"191009528","full_name":"moreal/pystructs","owner":"moreal","description":"Useful django-model like struct package for human","archived":false,"fork":false,"pushed_at":"2024-11-19T11:54:50.000Z","size":79,"stargazers_count":5,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-24T22:07:56.926Z","etag":null,"topics":["bytes","django-model-like","marshalling","pypi-package","python","python-library","struct"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moreal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-06-09T13:25:28.000Z","updated_at":"2024-11-19T11:54:53.000Z","dependencies_parsed_at":"2025-05-17T09:40:52.704Z","dependency_job_id":"d462db2d-b44c-405d-86d6-7bf2820e947c","html_url":"https://github.com/moreal/pystructs","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/moreal/pystructs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreal%2Fpystructs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreal%2Fpystructs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreal%2Fpystructs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreal%2Fpystructs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moreal","download_url":"https://codeload.github.com/moreal/pystructs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moreal%2Fpystructs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262648078,"owners_count":23342763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bytes","django-model-like","marshalling","pypi-package","python","python-library","struct"],"created_at":"2024-11-20T00:14:11.308Z","updated_at":"2026-04-06T03:31:24.259Z","avatar_url":"https://github.com/moreal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pystructs\n\n[![Documentation Status](https://readthedocs.org/projects/pystructs/badge/?version=latest)](https://pystructs.readthedocs.io/en/latest/?badge=latest)\n[![CI](https://github.com/moreal/pystructs/actions/workflows/ci.yml/badge.svg)](https://github.com/moreal/pystructs/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/moreal/pystructs/branch/main/graph/badge.svg)](https://codecov.io/gh/moreal/pystructs)\n\n**pystructs** is a Django-like declarative binary parsing library for Python. Define binary data structures as classes and parse/serialize them with ease.\n\n## Features\n\n- **Declarative syntax** - Define structs like Django models\n- **Bidirectional** - Parse binary data and serialize back to bytes\n- **Rich field types** - Integers, floats, bytes, strings, arrays, and more\n- **Bit-level parsing** - `BitStruct` for parsing individual bits\n- **Conditional fields** - Fields that exist based on runtime conditions\n- **Validation system** - Built-in and custom validators\n- **Zero runtime dependencies** - Pure Python implementation\n\n## Installation\n\n```bash\npip install pystructs\nuv add pystructs\n```\n\n## Quick Start\n\n```python\nfrom pystructs import Struct, UInt8, UInt16, UInt32, Bytes, Ref, SyncRule\n\nclass Packet(Struct):\n    class Meta:\n        endian = \"big\"\n        sync_rules = [\n            SyncRule(\"length\", from_field=\"payload\", compute=len),\n        ]\n\n    magic = UInt32(default=0xDEADBEEF)\n    version = UInt8(default=1)\n    length = UInt16()\n    payload = Bytes(size=Ref(\"length\"))\n\n# Parse from bytes\ndata = b\"\\xde\\xad\\xbe\\xef\\x01\\x00\\x05Hello\"\npacket = Packet.parse(data)\nprint(packet.magic)    # 3735928559 (0xDEADBEEF)\nprint(packet.version)  # 1\nprint(packet.payload)  # b'Hello'\n\n# Create and serialize\nnew_packet = Packet(payload=b\"World\")\nnew_packet.sync()  # Auto-calculate length\nprint(new_packet.to_bytes())\n```\n\n## More Examples\n\n### Variable-Length Arrays\n\n```python\nfrom pystructs import Struct, UInt8, UInt16, Array, Ref, SyncRule\n\nclass ScoreBoard(Struct):\n    class Meta:\n        sync_rules = [\n            SyncRule(\"count\", from_field=\"scores\", compute=len),\n        ]\n\n    player_id = UInt16()\n    count = UInt8()\n    scores = Array(UInt16(), count=Ref(\"count\"))\n\nboard = ScoreBoard(player_id=1234, scores=[100, 250, 180])\nboard.sync()\nprint(board.to_bytes())  # Serializes with count=3\n```\n\n### Bit-Level Parsing\n\n```python\nfrom pystructs import Struct, UInt16, BitStruct, Bit, Bits, EmbeddedBitStruct\n\nclass TCPFlags(BitStruct):\n    class Meta:\n        size = 1\n\n    fin = Bit()\n    syn = Bit()\n    rst = Bit()\n    psh = Bit()\n    ack = Bit()\n    urg = Bit()\n    reserved = Bits(2)\n\nclass TCPHeader(Struct):\n    class Meta:\n        endian = \"big\"\n\n    src_port = UInt16()\n    dst_port = UInt16()\n    flags = EmbeddedBitStruct(TCPFlags)\n\nheader = TCPHeader.parse(b\"\\x00\\x50\\x1f\\x90\\x12\")\nprint(header.src_port)     # 80\nprint(header.flags.syn)    # True\n```\n\n### Conditional Fields\n\n```python\nfrom pystructs import Struct, UInt8, UInt32, Conditional, Ref\n\nclass VersionedPacket(Struct):\n    version = UInt8()\n    # Only present in version 2+\n    extended_header = Conditional(\n        UInt32(),\n        when=Ref(\"version\") \u003e= 2,\n    )\n    data = UInt8()\n\n# Version 1: no extended header\nv1 = VersionedPacket.parse(b\"\\x01\\x42\")\nprint(v1.extended_header)  # None\n\n# Version 2: with extended header\nv2 = VersionedPacket.parse(b\"\\x02\\x00\\x00\\x00\\x01\\x42\")\nprint(v2.extended_header)  # 1\n```\n\n### Tagged Unions (Switch)\n\n```python\nfrom pystructs import Struct, UInt8, UInt16, UInt32, Switch, Ref\n\nclass TextPayload(Struct):\n    length = UInt8()\n    # text would use Bytes(size=Ref(\"length\"))\n\nclass BinaryPayload(Struct):\n    size = UInt16()\n    # data would use Bytes(size=Ref(\"size\"))\n\nclass Message(Struct):\n    msg_type = UInt8()\n    payload = Switch(\n        discriminator=Ref(\"msg_type\"),\n        cases={\n            1: TextPayload,\n            2: BinaryPayload,\n        },\n    )\n```\n\n## Field Types\n\n| Category | Fields |\n|----------|--------|\n| **Integers** | `Int8`, `UInt8`, `Int16`, `UInt16`, `Int32`, `UInt32`, `Int64`, `UInt64` |\n| **Floats** | `Float32`, `Float64` |\n| **Bytes** | `FixedBytes`, `Bytes` |\n| **Strings** | `FixedString`, `String`, `NullTerminatedString` |\n| **Composite** | `Array`, `EmbeddedStruct`, `Conditional`, `Switch` |\n| **Special** | `Bool`, `Padding`, `Flags`, `Enum` |\n| **Bit-level** | `BitStruct`, `Bit`, `Bits`, `EmbeddedBitStruct` |\n\n## Documentation\n\nFull documentation is available at [Read the Docs](https://pystructs.readthedocs.io/).\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and contribution guidelines.\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoreal%2Fpystructs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoreal%2Fpystructs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoreal%2Fpystructs/lists"}