v0.1.0

First release of bytestruct: typed, dependency-free binary records and codecs on top of struct, extracted from pymobiledevice3 as its construct replacement.

Highlights

✨ Declarative fixed-size records

Dataclasses deriving from BinaryStruct, with each field's wire type given by its annotation: integers and floats in any byte order, Bytes, PaddedString, uuid_t, ipv4/ipv6, Array, int-enum fields and Const magics. The layout compiles into struct.Struct once, when the class is defined: 7x faster than construct to parse a header and 13x faster to build one.

@dataclass
class Header(BinaryStruct, byte_order="<"):
    magic: Annotated[u32, Const(0x1F3D5B79)] = field(default=0x1F3D5B79, init=False)
    size: u32
    name: Annotated[str, PaddedString(16)]

✨ Composable codecs for variable-length data

Prefixed, PrefixedArray, Switch, Aligned, Tuple, CSTRING, GREEDY_STRING, GREEDY_BYTES and the full set of scalars compose like construct's. Records are codecs too, and ByteReader covers formats with no declarative shape.

✨ Located errors

BinaryParseError/BinaryBuildError (both ValueErrors) name the record, field, path and absolute offset of the failure, e.g. DICTIONARY -> [2] -> STRING at offset 104: expected 200 bytes, found 16.

📚 Documentation

Guides, a cookbook, an extending guide and a full type reference with a round trip for every public name: https://doronz88.github.io/bytestruct/

Python 3.9+, pyright-clean, MIT licensed.