Catzilla

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

---

Overview

<img align="right" src="https://raw.githubusercontent.com/rezwanahmedsami/catzilla/main/logo.png" width="250px" alt="Catzilla Logo" />

Catzilla is a modern Python web framework purpose-built for extreme performance and developer productivity. At its heart is a sophisticated C HTTP engine—built using libuv and llhttp—featuring an advanced trie-based routing system that delivers O(log n) route lookup performance.

By exposing its speed-focused C core through a clean, Pythonic decorator API, Catzilla gives developers full control with minimal overhead. Whether you're building real-time AI applications, low-latency APIs, or high-throughput microservices, Catzilla is engineered to deliver maximum efficiency with minimal boilerplate.

<br>

✨ Features

Core Performance

• ⚡ Hybrid C/Python Core — Event-driven I/O in C, exposed to Python
• 🔥 Advanced Trie-Based Routing — O(log n) lookup with dynamic path parameters
• 🧱 Zero Boilerplate — Decorator-style routing: @app.get(...)
• 🔁 Concurrency First — GIL-aware bindings, supports streaming & WebSockets
• 📦 Zero Dependencies — Uses only Python standard library (no pydantic, no bloat!)

Advanced Routing System

• 🛣️ Dynamic Path Parameters — /users/{user_id}, /posts/{post_id}/comments/{comment_id}
• 🚦 HTTP Status Code Handling — 404, 405 Method Not Allowed, 415 Unsupported Media Type
• 🔍 Route Introspection — Debug routes, detect conflicts, performance monitoring
• 📊 Production-Grade Memory Management — Zero memory leaks, efficient allocation

Developer Experience

• 🧩 Modular Architecture — Add plugins, middleware, or extend protocols easily
• 🧪 Comprehensive Testing — 90 tests covering C core and Python integration
• 📖 Developer-Friendly — Clear documentation and contribution guidelines
• 🔧 Method Normalization — Case-insensitive HTTP methods (get → GET)

🚀 NEW in v0.2.0: Memory Revolution

The Python Framework That BREAKS THE RULES

"Zero-Python-Overhead Architecture"

• 🔥 30-35% Memory Efficiency — Automatic jemalloc optimization
• ⚡ C-Speed Allocations — Specialized arenas for web workloads
• 🎯 Zero Configuration — Works automatically out of the box
• 📈 Gets Faster Over Time — Adaptive memory management
• 🛡️ Production Ready — Graceful fallback to standard malloc

Memory Features

app = Catzilla()  # Memory revolution activated!

# 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")

# Automatic optimization - no configuration needed!

Performance Gains

• 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 your first Catzilla app with Memory Revolution:

# app.py
from catzilla import (
    Catzilla, Request, Response, JSONResponse, BaseModel,
    Query, Path, ValidationError
)
from typing import Optional
import asyncio

# Initialize Catzilla
app = Catzilla(
    production=False,      # Enable development features
    show_banner=True,      # Show startup banner
    log_requests=True      # Log requests in development
)

# Data model for validation
class UserCreate(BaseModel):
    """User creation model with auto-validation"""
    id: Optional[int] = 1
    name: str = "Unknown"
    email: Optional[str] = None

# Basic sync route
@app.get("/")
def home(request: Request) -> Response:
    """Home endpoint - SYNC handler"""
    return JSONResponse({
        "message": "Welcome to Catzilla v0.2.0!",
        "framework": "Catzilla v0.2.0",
        "router": "C-Accelerated with Async Support",
        "handler_type": "sync"
    })

# Async route with I/O simulation
@app.get("/async-home")
async def async_home(request: Request) -> Response:
    """Async home endpoint - ASYNC handler"""
    await asyncio.sleep(0.1)  # Simulate async I/O
    return JSONResponse({
        "message": "Welcome to Async Catzilla!",
        "framework": "Catzilla v0.2.0",
        "handler_type": "async",
        "async_feature": "Non-blocking I/O"
    })

# Route with path parameters and validation
@app.get("/users/{user_id}")
def get_user(request, user_id: int = Path(..., description="User ID", ge=1)) -> Response:
    """Get user by ID with path parameter validation"""
    return JSONResponse({
        "user_id": user_id,
        "message": f"Retrieved user {user_id}",
        "handler_type": "sync"
    })

# Route with query parameters
@app.get("/search")
def search(
    request,
    q: str = Query("", description="Search query"),
    limit: int = Query(10, ge=1, le=100, description="Results limit")
) -> Response:
    """Search with query parameter validation"""
    return JSONResponse({
        "query": q,
        "limit": limit,
        "results": [{"id": i, "title": f"Result {i}"} for i in range(limit)]
    })

# POST route with JSON body validation
@app.post("/users")
def create_user(request, user: UserCreate) -> Response:
    """Create user with automatic JSON validation"""
    return JSONResponse({
        "message": "User created successfully",
        "user": {"id": user.id, "name": user.name, "email": user.email}
    }, status_code=201)

# Health check
@app.get("/health")
def health_check(request: Request) -> Response:
    """Health check endpoint"""
    return JSONResponse({
        "status": "healthy",
        "version": "0.2.0",
        "async_support": "enabled"
    })

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

Run your app:

python app.py

Visit http://localhost:8000 to see your blazing-fast API with 30% memory efficiency in action! 🚀

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

• **