catzilla 0.2.1

Ultra-fast Python web framework with C-accelerated routing

Catzilla

Blazing-fast Python web framework with production-grade routing backed by a minimal, event-driven C core

---

Overview

Catzilla is a high-performance Python web framework built for teams that want Python ergonomics without paying the usual runtime tax. Its HTTP engine lives in C, uses libuv and llhttp, and exposes a clean decorator-based API that feels familiar to Python developers while keeping request handling tight and predictable.

It is designed for low-latency APIs, high-throughput services, streaming workloads, and systems where memory usage matters just as much as raw throughput.

Why Catzilla

• Fast where it matters: C-backed request parsing, routing, and response dispatch
• Pythonic to use: @app.get(...), typed parameters, validation, and clean handler code
• Built for production: middleware, background tasks, uploads, streaming, caching, and DI
• Memory-aware by default: jemalloc-backed allocation strategy where available
• Portable: supports Linux, macOS, and Windows with source and wheel-based workflows

🏆 Performance Snapshot

In the benchmark suite included in this repository, Catzilla currently leads FastAPI, Flask, and Django in direct localhost HTTP benchmarks for both single-worker and 10-worker runs. These numbers should be read as framework-overhead and runtime-efficiency comparisons, not as universal production guarantees.

Single / 1 Worker

• Average throughput: 52,700 req/s
• Best endpoint: basic_hello_world at 76,169 req/s
• Average latency: 2.16ms
• Average peak memory: 28.52MB
• Lead over FastAPI: 6.3x average throughput

Multi / 10 Workers

• Average throughput: 166,877 req/s
• Best endpoint: basic_hello_world at 197,947 req/s
• Average latency: 6.84ms
• Average peak memory: 270.37MB
• Lead over FastAPI: 4.4x average throughput

Async Operations

• Raw async endpoint: 29,235 req/s
• Lead over FastAPI: 4.7x on the current async benchmark slice
• Lead over Django: 10.4x on the current async benchmark slice

For benchmark methodology, reproducible commands, fairness notes, and raw output guidance, see benchmarks/README.md.

✨ Features

Core Runtime

• ⚡ Hybrid C/Python architecture for low-overhead request handling
• 🔥 Trie-based routing with dynamic path parameters and fast lookup
• 🧱 Minimal API surface with familiar decorator-style routing
• 🔁 Sync and async handlers with native deferred async response support
• 📦 Lean dependency model focused on the standard library and native code

Web Framework Features

• 🛣️ Dynamic path and query parameters with typed extraction
• ✅ Validation layer for request models and parameter constraints
• 🧩 Dependency injection and middleware composition
• 📤 Streaming responses, file uploads, background tasks, and static file serving
• 🚦 HTTP error handling for 404, 405, 415, and framework-level exceptions

Developer Experience

• 📖 Readable Python handlers on top of a high-performance core
• 🧪 Comprehensive unit and end-to-end validation across Python and C layers
• 🔧 Cross-platform build and packaging support
• 🧰 Benchmark suite included so performance claims are reproducible

🚀 Memory Architecture

Catzilla ships with a memory strategy tuned for long-running services, including jemalloc integration where available. The goal is simple: keep throughput high while reducing fragmentation and avoiding the typical memory blow-up that shows up under sustained load.

Memory Features

app = Catzilla()

# Real-time memory statistics
stats = app.get_memory_stats()
print(f"Memory efficiency: {stats['fragmentation_percent']:.1f}%")
print(f"Allocated: {stats['allocated_mb']:.2f} MB")

Allocator Strategy

• Request Arena: Optimized for short-lived request processing
• Response Arena: Efficient response building and serialization
• Cache Arena: Long-lived data with minimal fragmentation
• Static Arena: Static file serving with memory pooling
• Task Arena: Background operations with isolated allocation

---

📦 Installation

Quick Start (Recommended)

Install Catzilla from PyPI:

pip install catzilla

System Requirements:

• Python 3.9+ (3.10+ recommended)
• Windows, macOS, or Linux
• No additional dependencies required

Platform-Specific Features:

• Linux/macOS: jemalloc memory allocator (high performance)
• Windows: Standard malloc (reliable performance)
• See Platform Support Guide for details

Installation Verification

python -c "import catzilla; print(f'Catzilla v{catzilla.__version__} installed successfully!')"

Alternative Installation Methods

From GitHub Releases

For specific versions or if PyPI is unavailable:

# Download specific wheel for your platform from:
# https://github.com/rezwanahmedsami/catzilla/releases/tag/v0.1.0
pip install <downloaded-wheel-file>

From Source (Development)

For development or contributing:

# Clone with submodules
git clone --recursive https://github.com/rezwanahmedsami/catzilla.git
cd catzilla

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

Build Requirements (Source Only):

• Python 3.9-3.13
• CMake 3.15+
• C Compiler: GCC/Clang (Linux/macOS) or MSVC (Windows)

---

🚀 Quick Start

Create a small application with sync routes, async routes, and typed parameters:

# app.py
from typing import Optional
import asyncio

from catzilla import BaseModel, Catzilla, JSONResponse, Path, Query, Request, Response

app = Catzilla(
    production=False,
    show_banner=True,
    log_requests=True,
)

class UserCreate(BaseModel):
    id: Optional[int] = None
    name: str
    email: Optional[str] = None

@app.get("/")
def home(request: Request) -> Response:
    return JSONResponse({
        "framework": "catzilla",
        "message": "Hello from Catzilla",
        "mode": "sync",
    })

@app.get("/health")
async def health(request: Request) -> Response:
    await asyncio.sleep(0)
    return JSONResponse({
        "status": "ok",
        "mode": "async",
    })

@app.get("/users/{user_id}")
def get_user(request: Request, user_id: int = Path(..., ge=1)) -> Response:
    return JSONResponse({
        "user_id": user_id,
        "message": f"Retrieved user {user_id}",
    })

@app.get("/search")
def search(
    request: Request,
    q: str = Query(""),
    limit: int = Query(10, ge=1, le=100),
) -> Response:
    return JSONResponse({
        "query": q,
        "limit": limit,
        "results": [{"id": index, "title": f"Result {index}"} for index in range(limit)],
    })

@app.post("/users")
def create_user(request: Request, user: UserCreate) -> Response:
    return JSONResponse({
        "message": "User created successfully",
        "user": {"id": user.id, "name": user.name, "email": user.email},
    }, status_code=201)

if __name__ == "__main__":
    app.listen(port=8000, host="127.0.0.1")

Run your app:

python app.py

Then visit http://127.0.0.1:8000.

Backward Compatibility

Existing code works unchanged (App is an alias for Catzilla):

from catzilla import App  # Still works!
app = App()  # Same memory benefits

---

🖥️ System Compatibility

Catzilla provides comprehensive cross-platform support with pre-built wheels for all major operating systems and Python versions.

📋 Supported Platforms

Platform	Architecture	Status	Wheel Available
Linux	x86_64	✅ Full Support	✅ manylinux2014
macOS	x86_64 (Intel)	✅ Full Support	✅ macOS 10.15+
macOS	ARM64 (Apple Silicon)	✅ Full Support	✅ macOS 11.0+
Windows	x86_64	✅ Full Support	✅ Windows 10+
Linux	ARM64	⚠️ Source Only*	❌ No pre-built wheel

*ARM64 Linux requires building from source with proper build tools installed.

🐍 Python Version Support

Python Version	Linux x86_64	macOS Intel	macOS ARM64	Windows
3.9	✅	✅	✅	✅
3.10	✅	✅	✅	✅
3.11	✅	✅	✅	✅
3.12	✅	✅	✅	✅
3.13	✅	✅	✅	✅

🔧 Installation Methods by Platform

✅ Pre-built Wheels (Recommended)

• Instant installation with zero compilation time
• No build dependencies required (CMake, compilers, etc.)
• Optimized binaries for maximum performance
• Available for: Linux x86_64, macOS (Intel/ARM64), Windows x86_64

# Automatic platform detection
pip install <wheel-url-from-releases>

🛠️ Source Installation

• Build from source when pre-built wheels aren't available
• Requires build tools: CMake 3.15+, C compiler, Python headers
• Longer installation time due to compilation

# For ARM64 Linux or custom builds
pip install https://github.com/rezwanahmedsami/catzilla/releases/download/vx.x.x/catzilla-x.x.x.tar.gz

⚡ Performance Notes

• Native performance on all supported platforms
• Architecture-specific optimizations in pre-built wheels
• Cross-platform C core ensures consistent behavior
• Platform-specific wheel tags for optimal compatibility

For detailed compatibility information, see SYSTEM_COMPATIBILITY.md.

---

📊 Performance Benchmarks

Catzilla includes a benchmark harness that compares it against FastAPI, Flask, and Django across direct HTTP paths and feature-specific slices. The current published results cover basic endpoints, validation, background tasks, middleware, dependency injection, and async operations.

🏗️ Real Server Environment

Production Server | wrk Benchmarking Tool | macOS | 10s duration, 100 connections, 4 threads

This is real benchmark data collected from the repository benchmark runner. It is useful for comparing framework overhead and implementation efficiency on the same machine and workload shape.

Current Benchmark Highlights

Advanced Features Performance

Feature	Catzilla	FastAPI	Flask	Django	vs FastAPI
Dependency Injection	34,947	5,778	N/A	15,080	+505% faster
Database Operations	35,984	5,721	15,221	N/A	+529% faster
Background Tasks	32,614	4,669	15,417	1,834	+598% faster
Middleware Processing	21,574	1,108	N/A	15,049	+1,847% faster
Validation	17,344	4,759	16,946	15,396	+264% faster

Latency Snapshot

• Basic Operations: 5.5ms vs FastAPI's 22.1ms (75% lower)
• Dependency Injection: 3.1ms vs FastAPI's 17.7ms (82% lower)
• Database Operations: 3.1ms vs FastAPI's 17.6ms (82% lower)
• Background Tasks: 3.3ms vs FastAPI's 21.3ms (85% lower)

Performance Summary

• Peak Performance: 35,984 RPS (Database Operations)
• Average Performance: 24,000+ RPS across all categories
• Latency Leadership: 3-6x lower latency than FastAPI
• Feature Advantage: Outstanding performance even with complex features
• Framework Leadership: Leads the current benchmark comparison set across the tested scenarios

📋 View Complete Performance Report - Detailed analysis with technical insights

📎 Benchmark Methodology - Commands, runner behavior, and interpretation notes

📈 Performance Visualizations

Overall Performance Comparison

Feature-Specific Performance

📋 View Complete Performance Report - Detailed analysis with all benchmark visualizations and technical insights

When to Choose Catzilla

• ⚡ High-throughput requirements (API gateways, microservices, data pipelines)
• 🎯 Low-latency critical applications (real-time APIs, financial trading, gaming backends)
• 🧬 Resource efficiency (cloud computing, embedded systems, edge computing)
• 🚀 C-level performance with Python developer experience

Note: Comprehensive benchmark suite with automated testing available in benchmarks/ directory.

---

🔧 Development

For detailed development instructions, see CONTRIBUTING.md.

Build System

# Complete build (recommended)
./scripts/build.sh

# Manual CMake build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)
pip install -e .

Testing

The project includes C tests, Python unit tests, and end-to-end validation:

# Run all tests ( C + Python Unit + e2e)
./scripts/run_tests.sh

# Run specific test suites
./scripts/run_tests.sh --python  # Python Unit tests only
./scripts/run_tests.sh --c       # C tests only
./scripts/run_tests.sh --e2e       # e2e tests only
./scripts/run_tests.sh --verbose # Detailed output

Performance Features

• Trie-Based Routing: O(log n) average case lookup performance
• Memory Efficient: Zero memory leaks, optimized allocation patterns
• Route Conflict Detection: Warns about potentially overlapping routes during development
• Method Normalization: Case-insensitive HTTP methods with automatic uppercase conversion
• Parameter Injection: Automatic extraction and injection of path parameters to handlers

🎯 Performance Characteristics

• Route Lookup: O(log n) average case with advanced trie data structure
• Memory Management: Zero memory leaks with efficient recursive cleanup
• Scalability: Tested with 100+ routes without performance degradation
• Concurrency: Thread-safe design ready for production workloads
• HTTP Processing: Built on libuv and llhttp for maximum throughput

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

• Setting up the development environment
• Building and testing the project
• Code style and conventions
• Submitting pull requests
• Debugging and performance optimization

📚 Documentation

📖 Complete Documentation - Comprehensive guides, API reference, and tutorials

Quick References

• Getting Started Guide - Quick start tutorial
• System Compatibility - Platform support and installation guide
• Examples - Real-world example applications
• Contributing - Development guide for contributors

---

👤 Author

Rezwan Ahmed Sami 📧 [e-mail] 📘 Facebook

---

🪪 License

MIT License — See LICENSE for full details.