Metadata-Version: 2.4
Name: surp
Version: 1.0.1
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: Native Rust-backed Surp encoder/decoder with RFC-001 CTN/CBF/CQL support
Keywords: serialization,binary,encoder,decoder,surp
Home-Page: https://github.com/tubox-labs/surp
Author: Pawan Kumar
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/tubox-labs/surp/issues
Project-URL: Documentation, https://github.com/tubox-labs/surp/blob/master/docs/PYTHON_API.md
Project-URL: Homepage, https://github.com/tubox-labs/surp
Project-URL: Repository, https://github.com/tubox-labs/surp

# 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

```sh
pip install surp
```

From a checkout:

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

## v1 API

```python
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:

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

## RFC-001 Helpers

```python
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:

```python
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()`.

```python
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()
assert User.from_cbf(cbf) == 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.

