bier 0.0.3

Endian-aware binary IO streams and annotation driven serialization helpers

Binaryhelper

Binary IO and annotation driven serialization utilities for Python.

Highlights

• Stream-friendly readers and writers that respect explicit endianness.
• C++ backed implementations for EndianedStreamIO and EndianedBytesIO to keep hot loops fast.
• Python 3.12+ serialization helpers that turn type hints into binary schemas.
• Works with in-memory buffers, files, and arbitrary Python streams.

Installation

pip install bier

EndianedBinaryIO (Python 3.8+)

bier.EndianedBinaryIO wraps common binary IO patterns so you can describe data once and reuse it across different stream types.

Core classes

• EndianedBytesIO: in-memory buffer with read and write helpers for integers, floats, strings, and byte arrays.
• EndianedStreamIO: fast wrapper around any file-like object that exposes endian aware helpers by delegating to an underlying stream.
• EndianedBufferedReader and EndianedBufferedWriter: buffered adaptors for existing binary readers and writers.
• EndianedFileIO: convenience subclass that opens files and exposes the same API as in-memory streams.

Quick start

from bier.EndianedBinaryIO import EndianedBytesIO

stream = EndianedBytesIO(endian=">")
stream.write_u16(0x1234)
stream.write_cstring("bier")
stream.seek(0)

value = stream.read_u16()
text = stream.read_cstring()

assert value == 0x1234
assert text == "bier"

Stick with a single API whether you are reading from a BytesIO, a file handle, or a socket-like object. The helpers handle array packing, alignment, and endian swapping for you.

Serialization (Python 3.12+)

bier.serialization turns annotated data classes into binary serializers.

• Subclass BinarySerializable and describe fields with provided marker types like u32, f32, cstr, list_d, and tuple.
• Use convert, custom, member, and length_type options to tweak encoding without hand writing parsing logic.
• Serialization uses the same readers and writers as EndianedBinaryIO, so the two modules fit together.

from bier.EndianedBinaryIO import EndianedBytesIO
from bier.serialization import BinarySerializable, cstr, list_d, u16, u32

class Player(BinarySerializable[u16]):
    id: u32
    name: cstr
    scores: list_d[u16, u16]

class Team(BinarySerializable[u16]):
    head: "Player"
    members: list[Player]

buffer = EndianedBytesIO(endian="<")
player = Player(id=7, name="Ada", scores=[10, 20, 30])
player.write_to(buffer)

buffer.seek(0)
roundtrip = Player.read_from(buffer)
assert roundtrip.id == 7

Annotation Types

• ints:
  • u8
  • u16
  • u32
  • u64
  • i8
  • i16
  • i32
  • i64
• floats:
  • f16
  • f32
  • f64
• strings:
  • cstr (null terminated string)
  • str (default delimited length)
  • str_d[T] (delimited length of type T)
• lists:
  • list[S] (default delimited length)
  • list_d[S, T] (delimited length of type T)
• tuples:
  • tuple[T1, T2, ...]
• objects
  • class (has to inherit from BinarySerializible as well)
• bytes:
  • bytes (default delimited length)
  • bytes_d[T] (delimited length of type T)

Roadmap

• Block oriented ComplexStreams for compressed or encrypted segments.
• Multi-stream wrappers for treating concatenated streams as one logical source.
• Extended struct-like helpers for varints, grouped tuples, and length prefixed fields.