Surp Python

Rust-backed Python bindings for Surp, a compact binary serialization format with a human-readable text notation and an additive RFC-001 CTN/CBF/CQL path.

The Python distribution is named surp and is backed by the PyO3 extension module surp._surp_native.

Install

pip install surp

From a checkout:

cd surp-python
maturin develop --release
python -m pytest tests/ -v

v1 API

import surp

payload = {
    "name": "Alice",
    "age": 30,
    "active": True,
    "avatar": b"\x01\x02\x03",
}

data = surp.dumps(payload, dedup=True, sort_keys=True)
assert surp.loads(data) == payload

Supported inputs are None, bool, int, float, str, bytes, list, tuple, and dictionaries with string keys. Tuples decode as lists.

Public helpers:

• dumps, loads, dump, load
• encode, decode, encode_to_file, decode_from_file
• parse_text, pretty_print
• to_value, loads_value, parse_text_value, SurpValue
• Encoder, SurpDecoder

Use loads_value() or parse_text_value() when you want native-backed attribute access instead of plain Python containers:

view = surp.loads_value(data)
assert view["name"].value == "Alice"
assert view["tags"][0].value == "admin"

RFC-001 Helpers

from surp import rfc001

cbf = rfc001.compile_ctn('User\n  name = "Alice"', alignment=4)
decoded = rfc001.decode_cbf(cbf)

assert decoded["header"]["magic"] == "SURP"
assert rfc001.query_cbf(cbf, ".name", as_ctn=True) == ['"Alice"']

surp.rfc001 exposes CTN parsing/normalization, CTN-to-CBF compilation, CBF decoding, CBF-to-CTN formatting, and baseline CQL path queries.

For IDE-friendly RFC access, use the model helpers:

doc = rfc001.parse_ctn_model('User\n  name = "Alice"')
user = doc.effective_root()
assert user["name"].scalar_value == "Alice"

RFC-001 Model Schemas

surp.model provides a declarative validation layer for RFC-001 products and documents. Model classes use explicit RFC-001 type markers and encode through surp.rfc001.compile_ctn().

from surp.model import Field, SurpModel
from surp.model.types import Bool, Int64, SeqOf, Str


class User(SurpModel):
    name: Str = Field(required=True)
    age: Int64 = Field(required=False, default=0)
    active: Bool = Field(required=True)
    tags: SeqOf[Str] = Field(required=False, default_factory=list)


user = User(name="Alice", active=True, tags=["admin"])
cbf = user.to_cbf()
data = user.to_surp()
assert User.from_cbf(cbf) == user
assert User.from_surp(data) == user

Typing

The wheel includes .pyi stubs and py.typed for type checkers.

License

Licensed under either MIT or Apache-2.0, at your option.