Skip to main content

🧩 Rombob

Binary serialization for Python, driven by plain type hints.

Describe your wire format as a dataclass or a NamedTuple — get a fast, validated encoder and decoder for free. Zero dependencies, pure python.

Installation · Quick Start · Advanced Example · Annotations · Types · Contributing


✨ Why Rombob?

  • 🏷️ Just type hints — no schema files, no code generation step, no base classes.
  • ⚡ Fast — consecutive fixed-size fields are compiled into a single struct call.
  • 🔗 Dependent fields — lengths and optional fields can depend on values read earlier.
  • 🛡️ Validated — constraints (Range, Gt, Predicate, ...) are checked on read and write.
  • 🔍 Readable errors — trace_errors=True points at the exact failing field, e.g. Packet.points[0].x.
  • 🧠 Stateless codecs — build once, share freely.

📦 Installation

Install the latest unreleased code straight from Git:

pip install git+https://github.com/loudblow/rombob.git@main

🚀 Quick Start

import dataclasses
import rombob


@dataclasses.dataclass
class Player:
    id: rombob.U8_B   # 1 byte, big-endian
    username: str     # UTF-8 with a 2-byte length prefix


# 📤 Serialize
encoded = rombob.encode(Player(id=1, username="Archer"))
print(encoded)  # b'\x01\x00\x06Archer'

# 📥 Deserialize
player = rombob.decode(encoded, cls=Player)
print(player)  # Player(id=1, username='Archer')

🔬 Advanced Example

A tiny network packet that uses most of the features at once: magic bytes, an enum, a length taken from an earlier field, a conditional field, validation, nested structures, and a raw tail.

import dataclasses
import enum
from typing import Annotated, Literal

import rombob
from rombob import (
    I16_L, U8_B, Len, Named, Prefix, Range, Raw, When,
)


class Kind(enum.IntEnum):
    PING = 1
    CHAT = 2


@dataclasses.dataclass
class Point:
    x: I16_L                                    # little-endian int16
    y: I16_L


@dataclasses.dataclass
class Packet:
    magic: Literal[b"RB"]                       # constant, checked on read
    version: Annotated[Literal[1, 2], U8_B]     # only 1 or 2 is accepted
    kind: Annotated[Kind, U8_B]                 # enum stored as one byte
    count: Named[U8_B]                          # remembered as "count"
    points: Annotated[list[Point], Len(ref="count")]   # length = count
    has_token: Named[bool]
    token: Annotated[str | None, When(ref="has_token")]  # only if has_token
    hp: Annotated[U8_B, Range(0, 100)]          # validated 0..100
    tags: Annotated[list[Annotated[str, Prefix(U8_B)]], Prefix(U8_B)]
    payload: Raw                                # everything that is left


packet = Packet(
    magic=b"RB",
    version=1,
    kind=Kind.CHAT,
    count=2,
    points=[Point(1, 2), Point(-3, 4)],
    has_token=True,
    token="secret",
    hp=80,
    tags=["a", "bc"],
    payload=b"\xde\xad",
)

data = rombob.encode(packet)
assert rombob.decode(data, cls=Packet) == packet

Something went wrong? Ask for a trace and get the exact location:

import dataclasses

rombob.encode(dataclasses.replace(packet, hp=200), trace_errors=True)
# BytesOperationError: Encoding failed at length 22 (Packet.hp):
#     200 violates Range(lo=0, hi=100)

rombob.decode(data[:5], cls=Packet, trace_errors=True)
# BytesOperationError: Decoding failed at offset 5 (Packet.points[0].x): ...

🧰 Annotations Cheat Sheet

Everything lives in rombob.metadata and is importable from rombob.

Annotation What it does Example
LE / BE Byte order for IntCodec (or use the *_L / *_B aliases) U16_L
Len(n) Exact length, no length prefix Annotated[str, Len(10)]
Len(ref=...) Length from an earlier Named field (or lambda ctx: ...); checked on write Len(ref="count")
Prefix(codec) Integer type of the length prefix (U16 big-endian by default) Prefix(U8_B)
Named[T] Remember the value so later fields can refer to it Named[U8_B]
When(...) Make a field conditional on earlier fields When(ref="has_token")
Optional[T] / T | None Present while there is data left int | None
Skip[T] Neither read nor written (needs a default) Skip[int]
Gt Ge Lt Le Range Numeric constraints, checked on read and write Range(1, 10)
Predicate(func) Any custom check Predicate(lambda v: v % 2 == 0)
Literal[...] Constants; bytes/str literals need no codec, int literals do Annotated[Literal[1, 2], U8_B]

🧱 Supported Types

Fields can be bools, integers, floats, strings, bytes, lists, tuples, sets, frozensets, enums, named tuples, or other dataclasses — plus Optional, Literal, Generic/TypeVar, fixed- and variable-length collections, and heterogeneous tuples such as tuple[int, str].

Plain Python types (defaults)

Python type Encoding Notes
bool ? Writes 1 or 0
str U16(BE) length + UTF-8 bytes
bytes U16(BE) length + bytes
int I64(BE) Signed 64-bit
float F64(BE) IEEE 754 double

Aliases

Every alias comes in two flavors: _B (big-endian) and _L (little-endian).

Family Aliases
Unsigned ints U8 U16 U24 U32 U48 U64
Signed ints I8 I16 I24 I32 I48 I64
Floats F16 F32 F64
Variable-length UVInt (unsigned), IVInt (signed)
Rest of the buffer Raw

⚙️ Going Further

  • Fast paths — Codec.encode/decode with an explicit codec, or Factory for dispatch by primary field. See rombob.get_codec(cls) to build and inspect a codec.
  • Custom types — rombob.register_codec(SystemAddress, SystemAddressCodec()) makes the codec the default for that type everywhere (fields, collections, get_codec); an explicit Annotated[..., codec] still wins. Pass override=True to replace an existing one, unregister_codec removes it. Register before building codecs and registering classes in a Factory.
  • Streaming — pass reader= / writer= to decode / encode to continue an existing buffer.
  • Benchmarks — see benchmarks/ (bench.py, bench_int24.py).

🤝 Contributing

make install   # poetry install + pre-commit hooks
make test      # pytest + coverage
make format    # ruff format
make lint      # pre-commit run

Pull requests and issues are welcome!

📚 References & Inspiration

Metadata

Release files for rombob 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rombob 1.1.0
File Size Uploaded Provenance Actions
rombob-1.1.0.tar.gz 32.4 kB Without provenance Details for rombob-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rombob 1.1.0
File Interpreter ABI Platform Actions
rombob-1.1.0-py3-none-any.whl Python 3 none any Details for rombob-1.1.0-py3-none-any.whl

Total release size: 66.4 kB

Release files / rombob-1.1.0.tar.gz

Download URL rombob-1.1.0.tar.gz
Size 32.4 kB
Tags Source
SHA-256 checksum
How to use checksums
9d1175627c04f4787d7adadc8024a55395df9cc97bb4f3dbba9dcb371e767024
BLAKE2b-256 checksum
How to use checksums
e17b2dd960f286b902fee9ade41fe1a48f34e4e579769d13ff16fe97fde62fb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.2.1 CPython/3.14.2 Darwin/24.6.0

Release files / rombob-1.1.0-py3-none-any.whl

Download URL rombob-1.1.0-py3-none-any.whl
Size 34.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
06834421f44a3e53bc504f795daaa217ea1e169b67b9b1b290fc55101cd86a24
BLAKE2b-256 checksum
How to use checksums
b82baf6562be09b7aaa4a97943008d65636924eb709c8f6d70ec401aa62cfbec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.2.1 CPython/3.14.2 Darwin/24.6.0

Security for rombob 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page