bstruct

Simple and efficient binary (de)serialization using type annotations. Supports easy fallback to Python's built-in struct library for maximum performance.

Getting Started

pip install bstruct

from typing import Annotated
from dataclasses import dataclass

import bstruct


@dataclass
class Measurement:
    timestamp: bstruct.u32  # shorthand for: Annotated[int, bstruct.Encodings.u32]
    values: Annotated[list[bstruct.u8], bstruct.Array(3)]


MeasurementEncoding = bstruct.derive(Measurement)


measurement = Measurement(
    timestamp=1672764049,
    values=[1, 2, 3],
)

encoded = MeasurementEncoding.encode(measurement)
decoded = MeasurementEncoding.decode(encoded)

assert decoded == measurement

See the documentation for more information.

Benchmarks

Please see the source of the benchmarks in the benchmarks directory. Feel free to create an issue or PR should there be a problem with the methodology. The benchmarks where executed with pyperf using Python 3.11.1 and construct 2.10.68 on a MacBook Pro 2018 with a 2.3GHz i5 processor.

benchmarks/builtins.py

benchmarks/native_list.py

benchmarks/class_list.py

benchmarks/nested.py

Issues and Contributing

I am very happy to receive any kind of feedback or contribution. Just open an issue and let me know.