Introduction

Crous is a high-performance binary serialization library implemented as a C extension for Python. It provides compact, type-preserving serialization that is significantly smaller and faster than JSON for most workloads.

Key Features

• Blazing fast — C extension core with zero-copy optimizations
• Ultra compact — Zigzag varint encoding, small-integer optimization, up to 75% smaller than JSON
• Type preserving — Native support for int, float, bytes, tuple, set, frozenset, and tagged values
• Three formats — FLUX binary (default), CROUT text (human-readable), and legacy CROUS binary
• Streaming — File and stream-based I/O with dump/load
• Custom serializers — Register handlers for any Python type with MRO-aware lookup
• Thread safe — Lock-protected custom serializer registry for concurrent use
• Cross-platform — Compatible with Node.js SDK for polyglot applications

Quick Example

import crous

# Serialize Python data to compact binary
data = {
    "name": "Alice",
    "scores": [98, 95, 100],
    "active": True,
    "tags": {"python", "developer"},
}

# Encode to FLUX binary
binary = crous.dumps(data)
print(f"Encoded: {len(binary)} bytes")

# Decode back to Python
result = crous.loads(binary)
assert result == data
print(f"Decoded: {result}")

Supported Types

Architecture

Crous uses a three-layer architecture:

1. Python Wrapper (__init__.py) — Enhanced API with file path support and error handling
2. C Extension (pycrous.c) — N-API bindings that convert between Python objects and the C value tree
3. Core C Library — Arena allocator, value tree, FLUX/CROUT/CROUS encoders, lexer, and parser

Data flows through an intermediate crous_value tree that decouples Python types from the wire format, enabling format-agnostic encoding and easy addition of new formats.

Wire Format Versions