Metadata-Version: 2.4
Name: crousr
Version: 1.0.2
Summary: Pure-Python encoder/decoder for the Crous binary serialization format — compact, canonical, and human-readable alternative to JSON
Author: Pawan Kumar
License-Expression: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/axiomchronicles/crous
Project-URL: Repository, https://github.com/axiomchronicles/crous
Project-URL: Documentation, https://github.com/axiomchronicles/crous/blob/main/docs/PYTHON_API.md
Project-URL: Bug Tracker, https://github.com/axiomchronicles/crous/issues
Project-URL: Changelog, https://github.com/axiomchronicles/crous/blob/main/CHANGELOG.md
Keywords: serialization,binary,encoding,codec,format,json-alternative,msgpack,crous
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-benchmark; extra == "test"
Requires-Dist: hypothesis; extra == "test"
Provides-Extra: bench
Requires-Dist: msgpack; extra == "bench"
Requires-Dist: cbor2; extra == "bench"
Requires-Dist: bson; extra == "bench"
Dynamic: license-file

# crous

**A compact, canonical binary serializer and human-readable alternative to JSON — pure Python.**

[![PyPI](https://img.shields.io/pypi/v/crous)](https://pypi.org/project/crous/)
[![Python](https://img.shields.io/pypi/pyversions/crous)](https://pypi.org/project/crous/)
[![License](https://img.shields.io/pypi/l/crous)](https://github.com/axiomchronicles/crous/blob/main/LICENSE-MIT)

## Overview

Crous is a production-grade binary serialization format that provides:

- **Compact binary encoding** — 2×–5× smaller than equivalent JSON
- **Human-readable text notation** — unique syntax with deterministic binary mapping
- **Zero-copy decoding** — borrow directly from input buffers
- **Block-framed format** — per-block XXH64 checksums for data integrity
- **File I/O** — `load()` / `dump()` familiar API, like `json.load` / `json.dump`
- **Cross-language** — wire-compatible with the Rust implementation

## Installation

```bash
pip install crous
```

## Quick Start

```python
import crous

# Encode any Python object
data = crous.encode({"name": "Alice", "age": 30, "active": True})
print(data[:7])  # b'CROUSv1'

# Decode back to Python
obj = crous.decode(data)
print(obj)  # {'name': 'Alice', 'age': 30, 'active': True}
```

## File I/O

```python
import crous

# Write to a .crous file (like json.dump)
crous.dump({"name": "Alice", "age": 30}, "data.crous")

# Read from a .crous file (like json.load)
obj = crous.load("data.crous")
print(obj)  # {'name': 'Alice', 'age': 30}

# Append a value to an existing file
crous.append({"event": "stop"}, "log.crous")

# Lossless round-trip with Value objects
from crous.value import Value
crous.dump_values([Value.str_("hello"), Value.uint(42)], "typed.crous")
values = crous.load_values("typed.crous")
print(values[0].type)  # ValueType.STR
```

## Human-Readable Text Format

```crous
{
    name: "Alice";
    age: 30;
    tags: ["admin", "user"];
    config: {
        theme: "dark";
        notifications: true;
    };
    avatar: b64#iVBORw0KGgo=;
}
```

Parse and pretty-print:

```python
import crous

text = '{ name: "Alice"; age: 30; }'
value = crous.parse_text(text)
print(crous.pretty_print(value))
```

## Encoder / Decoder Classes

```python
from crous.encoder import Encoder
from crous.value import Value

enc = Encoder()
enc.enable_dedup()          # Enable string deduplication
enc.encode_value(Value.from_python({"key": "value"}))
data = enc.finish()
```

```python
from crous.decoder import Decoder

dec = Decoder(data)
values = dec.decode_all()
print(values[0].to_python())
```

## Wire Format

```
File:    [Header 8B] [Block]* [Trailer Block]
Header:  "CROUSv1" (7B) | flags (1B)
Block:   type(1B) | length(varint) | compression(1B) | checksum(8B) | payload
```

The format is deterministic: the same input always produces the same bytes.

## Cross-Language Compatibility

Data encoded by the pure-Python `crous` package is fully wire-compatible with the Rust implementation (`crous-core`). Files can be written in Python and read in Rust, or vice versa.

## License

Licensed under either of:

- MIT License ([LICENSE-MIT](https://github.com/axiomchronicles/crous/blob/main/LICENSE-MIT))
- Apache License, Version 2.0 ([LICENSE-APACHE](https://github.com/axiomchronicles/crous/blob/main/LICENSE-APACHE))

at your option.
