Welcome to pystructs’ documentation!
pystructs is a Django-like declarative binary parsing library for Python. Define binary data structures as classes and parse/serialize them with ease.
Quick Example
from pystructs import Struct, UInt8, UInt16, UInt32, Bytes, Ref, SyncRule
class Packet(Struct):
class Meta:
endian = "big"
sync_rules = [
SyncRule("length", from_field="payload", compute=len),
]
magic = UInt32(default=0xDEADBEEF)
version = UInt8(default=1)
length = UInt16()
payload = Bytes(size=Ref("length"))
# Parse from bytes
data = b"\xde\xad\xbe\xef\x01\x00\x05Hello"
packet = Packet.parse(data)
print(packet.magic) # 3735928559
print(packet.payload) # b'Hello'
# Create and serialize
new_packet = Packet(payload=b"World")
new_packet.sync()
print(new_packet.to_bytes())
Features
Declarative syntax - Define structs like Django models
Bidirectional - Parse binary data and serialize back to bytes
Rich field types - Integers, floats, bytes, strings, arrays, and more
Bit-level parsing - BitStruct for parsing individual bits
Conditional fields - Fields that exist based on runtime conditions
Validation system - Built-in and custom validators
Zero runtime dependencies - Pure Python implementation
Getting Started
Core Concepts