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.
  • 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.0.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.0.0
File Size Uploaded Provenance Actions
rombob-1.0.0.tar.gz 31.0 kB Without provenance Details for rombob-1.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 63.6 kB

Release files / rombob-1.0.0.tar.gz

Download URL rombob-1.0.0.tar.gz
Size 31.0 kB
Tags Source
SHA-256 checksum
How to use checksums
e28041cce45d2b1e2f65f4796ecc190d80cd4084798f92bd782c56789fce0ce2
BLAKE2b-256 checksum
How to use checksums
a4fae8b7abf44f3cfcc3429cfb1ad99e77d77097c739a773c20fdca597ae5fb9
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.0.0-py3-none-any.whl

Download URL rombob-1.0.0-py3-none-any.whl
Size 32.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c886408ad93349f2c36bd37a3ade35bd06c6c1f981c7ba7dc1797052b3e55fcf
BLAKE2b-256 checksum
How to use checksums
45a272d5a7092409a4ee235f74ad505b656b0b3c25ab02ffe64485b77cc1a55a
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.0.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.0.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