structed

C-style packed binary structs for Python, declared with type annotations. Zero runtime dependencies, byte-for-byte compatible with C struct layouts (including __attribute__((packed))), and friendly to cross-language interop and network protocols.

Install

pip install structed

Quick start

from typing import Annotated
from structed import Endian, Struct, uint8_t, uint32_t, char, cstring, cppstring

class Header(Struct, endian=Endian.LITTLE):
    magic:  Annotated[bytes, char[4]]        # fixed-width, NUL-padded
    version: Annotated[int, uint8_t]
    count:  Annotated[int, uint32_t]
    note:   Annotated[str, cstring[16]]      # NUL-terminated C string
    data:   Annotated[str, cppstring]         # length-prefixed string

binary = Header(magic=b"PROT", version=1, count=3, note="hi", data="x").pack()
header = Header.unpack(binary)
obj, rest = Header.unpack_tail(binary + b"more")  # stream framing

Field types

Annotations use typing.Annotated: Annotated[int, uint16_t], Annotated[str, cstring[16]], Annotated[str, cppstring].

Arrays

An array packs N elements back-to-back and round-trips as a list. The element type is given explicitly, inferred from a list[T] annotation, or repeated with *:

class S(Struct, endian=Endian.LITTLE):
    flags: Annotated[list[int], Array(4, uint16_t)]  # explicit
    ages:  Annotated[list[int], uint8_t * 2]          # shorthand for Array(2, uint8_t)
    pts:   Annotated[list[Point], Array(3)]           # array of nested structs

s = S(flags=[1, 2, 3, 4], ages=[12, 13], pts=[...])
assert s.flags == [1, 2, 3, 4] and s.ages == [12, 13]

The value must have exactly N elements, otherwise packing raises PackingError. Arrays cannot hold variable-length (cppstring) elements.

Struct options

class Packet(Struct, endian=Endian.BIG, packed=True, truncate=False):
    ...

• endian: Endian.LITTLE, Endian.BIG, Endian.NATIVE, Endian.NETWORK.
• packed: True (default) lays fields back-to-back like C __attribute__((packed)); False applies natural C alignment.
• truncate: when False (default) a value longer than its char[N] / cstring[N] field raises PackingError; when True it is silently cut to fit (and still NUL-terminated for cstring).

The same options are available via the binary_struct(endian=..., packed=..., truncate=...) class decorator.

Struct methods

• obj.pack() -> bytes
• S.unpack(data) -> S (consumes from the front)
• S.unpack_tail(data) -> (S, tail) for stream framing
• S.unpack_from(data, offset) -> S
• S.sizeof() -> int (fixed minimum for variable-length structs)

Variable-length fields

cppstring fields are length-prefixed and may be followed by fixed-size fields; parsing always resumes right after the payload. Only one variable field is allowed per struct, packed=True is required, and a struct with a variable field cannot be nested or used as an array element.

Development

make venv          # create .venv and install editable + deps
make check         # run tests + syntax + type checks
make example       # run examples/
make build-release # verify, then build sdist + wheel