Getting Started

This guide walks you through installing Crous and running your first serialization.

Requirements

  • Python 3.6 or later
  • A C compiler (GCC, Clang, or MSVC) — required to build the C extension
  • pip (Python package manager)

Installation

From PyPI

pip install crous

From Source

git clone https://github.com/axiomchronicles/crous.git
cd crous
pip install -e .

Build from Source

When installing from source, the C extension is compiled automatically by setup.py. The build uses -O3 -Wall -Wextra -std=c99 optimization flags.

Verify Installation

verify.py
import crous

# Check version
print(f"Crous version: {crous.__version__}")
# Output: Crous version: 2.0.0

# Quick round-trip test
data = {"hello": "world", "numbers": [1, 2, 3]}
encoded = crous.dumps(data)
decoded = crous.loads(encoded)
assert decoded == data
print("✓ Crous is working correctly!")

Your First Serialization

Crous provides a simple API similar to Python's json module:

first_example.py
import crous

# Create some data
user = {
    "name": "Alice",
    "age": 30,
    "email": "alice@example.com",
    "scores": [98.5, 95.0, 100.0],
    "verified": True,
    "avatar": b"\x89PNG\r\n...",  # binary data!
    "tags": {"admin", "developer"},   # sets too!
}

# Serialize to binary
binary_data = crous.dumps(user)
print(f"Serialized to {len(binary_data)} bytes")

# Save to file
crous.dump(user, "user.crous")

# Load from file
loaded = crous.load("user.crous")
assert loaded == user
print("✓ File round-trip successful!")

Comparison with JSON

FeatureCrousJSON
Binary data✅ Native bytes❌ Base64 encoding
Tuples✅ Preserved as tuples❌ Becomes list
Sets✅ Native set/frozenset❌ Not supported
Integer precision✅ Full 64-bit signed⚠️ May lose precision
Size✅ 40-75% smaller—
Human readable✅ CROUT text format✅ Native
IntroductionSerialization