Cramjam

Extremely thin Python bindings to de/compression algorithms in Rust. Cramjam provides high-performance compression and decompression for multiple algorithms with a consistent API.

Package Information

• Package Name: cramjam
• Package Type: pypi
• Language: Python
• Installation: pip install cramjam

Supported Algorithms

• Snappy - Fast compression with optional raw format
• Brotli - Web-optimized compression (default level: 11)
• Bzip2 - Traditional compression (default level: 6)
• LZ4 - Ultra-fast compression with block operations
• Gzip - Standard compression (default level: 6)
• Zlib - Library compression (default level: 6)
• Deflate - Raw deflate compression (default level: 6)
• ZSTD - Modern compression (default level: 6)
• XZ/LZMA - High-ratio compression with advanced configuration

Core Imports

# Main package with core utilities
import cramjam
from cramjam import Buffer, File, CompressionError, DecompressionError

# Individual compression modules
from cramjam import snappy, gzip, bzip2, lz4, deflate, zlib, zstd, brotli, xz

Quick Start Examples

Basic Compression

import cramjam

# Simple compression/decompression
data = b"Hello, World!" * 100
compressed = cramjam.gzip.compress(data)
decompressed = cramjam.gzip.decompress(compressed)

# Try different algorithms
compressed_brotli = cramjam.brotli.compress(data, level=6)
compressed_zstd = cramjam.zstd.compress(data, level=3)

Memory-Efficient Operations

import cramjam

# Pre-allocate output buffer for efficiency
input_data = b"Large dataset" * 10000
output = cramjam.Buffer()

# Compress directly into buffer
bytes_written = cramjam.gzip.compress_into(input_data, output)
print(f"Compressed {len(input_data)} bytes to {bytes_written} bytes")

Streaming Compression

import cramjam

# Use streaming compressor for large data
compressor = cramjam.zstd.Compressor(level=5)

# Process data in chunks
compressor.compress(b"First chunk of data")
compressor.compress(b"Second chunk of data")

# Get final compressed result
compressed_data = compressor.finish()

Buffer Management

import cramjam

# Create and manipulate buffers
buffer = cramjam.Buffer(b"Initial data")
buffer.write(b" additional data")
buffer.seek(0)
content = buffer.read()

# File operations
file_obj = cramjam.File("data.txt", read=True, write=True)
file_obj.write(b"File content")
file_obj.seek(0)
data = file_obj.read()

Architecture

Buffer Protocol Support

All cramjam functions accept BufferProtocol objects:

• bytes - Immutable byte strings
• bytearray - Mutable byte arrays (often faster due to reduced allocations)
• memoryview - Memory views of other buffer objects
• Custom objects implementing __buffer__ protocol

Core Utility Classes

Buffer - Memory buffer with file-like interface supporting read/write operations

File - Rust-backed file object with buffer protocol support

Exceptions - Specific error types for compression failures:

• CompressionError - Raised when compression operations fail
• DecompressionError - Raised when decompression operations fail

Compression Patterns

1. Standard Functions: compress(data, level=None) -> Buffer and decompress(data) -> Buffer
2. Direct Buffer Operations: compress_into(input, output) -> int for pre-allocated buffers
3. Streaming Classes: Compressor and Decompressor classes for chunk processing
4. Special Features: Algorithm-specific enhancements (LZ4 blocks, Snappy raw, XZ filters)

Algorithm-Specific Features

Standard Compression Modules

All standard modules follow consistent patterns with compression level support:

• Gzip, Zlib, Deflate, Bzip2, ZSTD, Brotli - Traditional algorithms with level control

Advanced Compression Modules

Modules with enhanced capabilities beyond standard compress/decompress:

• Snappy - Framed and raw format support
• LZ4 - Block operations with advanced parameters
• XZ/LZMA - Comprehensive filter chains and format control

Performance Tips

• Use bytearray instead of bytes for input when possible (avoids double allocation)
• Use *_into functions with pre-allocated buffers for memory efficiency
• Use streaming classes (Compressor/Decompressor) for large datasets
• Buffer objects provide reference counting for memory management

Module Documentation

• Core Utilities - Buffer, File classes and exception handling
• Standard Compression - Gzip, Zlib, Deflate, Bzip2, ZSTD, Brotli
• Advanced Compression - Snappy, LZ4, XZ with special features

Version Information

import cramjam
print(cramjam.__version__)  # Package version string