Welcome to Crous 🚀

Crous is a high-performance binary serialization library for Python that provides compact, type-preserving serialization with a simple and intuitive API.

What is Crous?

Crous (pronounced "crux") is a Python library that serializes Python objects to a compact binary format and deserializes them back. It's designed for developers who need:

• ⚡ Performance: Optimized C core for blazing-fast serialization
• 📦 Compact output: 30-50% smaller than JSON for most data
• 🎯 Type safety: Preserves exact Python types (int vs float, str vs bytes, etc.)
• 🔧 Simplicity: Familiar API like the standard json module
• 🛠️ Extensibility: Support for custom types via serializers
• ✅ Reliability: Comprehensive error handling and validation

Quick Start

Installation

pip install crous

Basic Usage

import crous

# Serialize to bytes
data = {'name': 'Alice', 'age': 30, 'active': True}
binary = crous.dumps(data)

# Deserialize from bytes
result = crous.loads(binary)
print(result)  # {'name': 'Alice', 'age': 30, 'active': True}

File I/O

import crous

# Save to file
crous.dump(data, 'data.crous')

# Load from file
data = crous.load('data.crous')

Supported Types

Type	Example	Notes
None	None	NULL value
Boolean	True, False	Preserves bool type ✓
Integer	42, -1000, 2**60	64-bit signed
Float	3.14, inf, nan	IEEE 754 double
String	'hello', '你好'	Unicode UTF-8
Bytes	b'data', b'\x00\xff'	Binary data
List	[1, 2, 3], [1, 'a', None]	Heterogeneous
Dictionary	{'a': 1}, {'key': [1, 2]}	String keys only
Tuple	(1, 2, 3), (1, 'a')	Preserved as tuple ✓

Why Choose Crous?

🚀 Lightning Fast

Optimized C implementation delivers sub-millisecond performance for most operations

📦 Ultra Compact

Typically 30-50% smaller than JSON, perfect for storage and network transfer

🎯 Type Safe

Distinguishes between int/float, str/bytes, and tuple/list to maintain data integrity

🔧 Easy to Use

Simple API familiar to anyone who has used the json module

🛠️ Extensible

Register custom serializers for datetime, UUID, Decimal, and any custom type

✅ Reliable

Clear error messages and comprehensive exception types for debugging

Common Use Cases

Configuration Storage

Store structured configuration with type safety instead of INI/YAML files.

Network Communication

Serialize Python objects for efficient transmission between processes or services.

Caching

Cache complex Python objects efficiently with type preservation.

Testing

Serialize test fixtures to reproducible binary format for deterministic tests.

Example: Type Preservation in Action

import crous

# JSON loses type information
import json
data = {'int': 1, 'float': 1.0, 'text': 'hello', 'bytes': b'data'}

json_bytes = json.dumps(data).encode()  # 53 bytes
crous_bytes = crous.dumps(data)         # 24 bytes
print(f"JSON: {len(json_bytes)}, Crous: {len(crous_bytes)}")

# When loaded back, Crous preserves types:
result = crous.loads(crous_bytes)
assert type(result['int']) is int        # ✓ Preserved!
assert type(result['float']) is float    # ✓ Preserved!
assert isinstance(result['bytes'], bytes)  # ✓ Preserved!

Example: Custom Types

For types not directly supported (like datetime), use custom serializers:

from datetime import datetime
import crous

# Register a custom serializer
crous.register_serializer(
    datetime,
    lambda x: x.isoformat() if isinstance(x, datetime) else None
)

# Now datetime works seamlessly
data = {'created': datetime.now(), 'name': 'Project'}
binary = crous.dumps(data)
result = crous.loads(binary)
print(f"Created: {result['created']}")  # ISO format string

Learn More

See Custom Serializers for comprehensive examples with UUID, Decimal, Set, and more.

Documentation Structure

• 📚 Installation Guide - Setup for all platforms with troubleshooting
• 🎓 User Guide - Tutorials, examples, and best practices
• 🔌 API Reference - Complete function and exception reference
• 🎯 Custom Serializers - Extend Crous with custom types
• ⚙️ Architecture - System design and implementation details
• 🤝 Developer Guide - Contributing to Crous

Project Info

Version: 2.0.0Python: 3.7+License: MITStatus: Production Ready

Current Version	2.0.0
Python Support	3.7, 3.8, 3.9, 3.10, 3.11, 3.12+
Platforms	Linux, macOS, Windows, ARM64 (experimental)
License	MIT
GitHub	crous-project/crous
PyPI	crous

Getting Help

Have Questions?

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Full Documentation: Explore Docs

---

Ready to get started? Install Crous now or jump into the User Guide! 🎉