Catzilla Documentation

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

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

Key Features:

• 🚀 Ultra-fast C core with Python bindings for maximum performance

• 🔗 Advanced trie-based routing with O(log n) lookup performance

• 🎯 Dynamic path parameters and flexible route patterns

• 📦 Router groups for organized, modular code structure

• ⚡ Built-in JSON/HTML responses with automatic content-type handling

• 🛡️ Production-ready error handling with clean responses

• 🔧 Simple CLI integration for easy deployment

• 📊 Comprehensive testing across platforms (Windows, macOS, Linux)

Quick Start:

pip install catzilla

from catzilla import App

app = App()

@app.get("/")
def home(request):
    return "Hello, World!"

@app.get("/users/{user_id}")
def get_user(request):
    user_id = request.path_params["user_id"]
    return {"user_id": user_id}

if __name__ == "__main__":
    app.listen(8000)

Getting Started

• Quickstart Guide
  • Installation
  • Hello World
  • Decorator-Based Routing
  • Dynamic Path Parameters
  • Request and Response Usage
  • Router Groups for Organization
  • Running via CLI
  • Next Steps

User Guide

• Advanced Guide
  • Dynamic Routes and Patterns
  • Error Handling
  • Running via CLI
  • Performance Optimization
  • Real-World Example

Performance

• Performance Benchmarks & Analysis
  • Executive Summary
  • Test Environment
  • Performance Results
  • Technical Performance Insights
  • Real-World Implications
  • Benchmark Reproducibility
  • System Specifications Record
  • Conclusion

Reference

• C-Accelerated Routing
  • Overview
  • Basic Usage
  • RouterGroup Integration
  • Performance Benefits
  • Best Practices
  • How It Works
• Catzilla Error Handling Implementation
  • ✅ Completed Features
  • Implementation Details
  • Example Implementation
  • API Reference
  • Performance Impact
  • Thread Safety
  • Best Practices
• Performance Features
  • Overview
  • C-Accelerated Components
  • RouterGroup Efficiency
  • Performance Best Practices
  • Performance Monitoring
  • Scaling Considerations
  • Scaling Considerations
  • Testing Your Performance

Why Choose Catzilla?

🚀 Exceptional Performance

Catzilla delivers 6-8x faster throughput than FastAPI with 87% lower latency. Real server benchmarks show 24,759 RPS vs FastAPI’s 2,844 RPS on Intel Xeon hardware. Our C-accelerated routing engine provides production-grade performance for high-traffic applications.

⚡ Zero Boilerplate

Clean decorator-style routing with no configuration overhead. Write @app.get("/users/{id}") and Catzilla handles the rest - parameter extraction, HTTP method routing, and error handling.

🧱 Production Ready

Comprehensive test coverage (90+ tests), memory-safe C core, automatic error handling (404, 405, 415), and battle-tested routing algorithms.

🔧 Developer Experience

RouterGroup system for organizing complex APIs, intuitive path parameters via request.path_params, and familiar Python patterns throughout.

Quick Start

Install and create your first API in under 30 seconds:

pip install catzilla

from catzilla import App, RouterGroup

app = App()

# Simple routes
@app.get("/")
def home(request):
    return {"message": "Welcome to Catzilla!"}

# RouterGroup for organization
api = RouterGroup(prefix="/api/v1")

@api.get("/users/{user_id}")
def get_user(request):
    user_id = request.path_params["user_id"]
    return {"user_id": user_id, "name": f"User {user_id}"}

@api.post("/users")
def create_user(request):
    return {"message": "User created"}, 201

app.include_routes(api)

if __name__ == "__main__":
    app.listen(8000)

This creates a production-ready API with:

• GET / - Welcome message

• GET /api/v1/users/123 - Get user with ID extraction

• POST /api/v1/users - Create new user

• Automatic 404/405 error handling

• C-accelerated route matching

Performance Highlights

Catzilla has been extensively benchmarked against popular Python frameworks on Intel Xeon E3-1245 v5 server:

Performance Comparison vs FastAPI

Endpoint Type	Catzilla RPS	FastAPI RPS	Performance Gain
Hello World	24,759	2,844	+771% faster
JSON Response	15,754	2,421	+551% faster
Path Parameters	17,590	2,341	+651% faster
Query Parameters	11,145	1,419	+685% faster
Complex JSON	14,843	2,008	+639% faster

Latency Excellence: Average latency of 6.37ms vs FastAPI’s 47.70ms (87% lower)

Architecture Overview

Hybrid C-Python Design

C-accelerated trie-based routing with Python handler execution. Automatic fallback to pure Python ensures compatibility across all environments.

Advanced Routing Engine

• O(log n) route lookup performance

• Dynamic path parameter extraction in C

• Method-specific routing with conflict detection

• Memory-efficient trie data structure

RouterGroup System

Hierarchical route organization with shared prefixes, metadata inheritance, and nested group support for building complex APIs.

Production Features

• Zero memory leaks with C-level memory management

• Comprehensive HTTP status code handling

• Thread-safe design for concurrent workloads

• Extensive test coverage (90+ tests)

Core Concepts

App: The main application instance that orchestrates HTTP request handling

app = App()

@app.get("/health")
def health_check(request):
    return {"status": "healthy"}

RouterGroup: Organize related routes with shared prefixes and metadata

users_api = RouterGroup(prefix="/users", tags=["users"])

@users_api.get("/{user_id}")
def get_user(request):
    return {"user_id": request.path_params["user_id"]}

Path Parameters: Dynamic URL segments extracted automatically

@app.get("/posts/{post_id}/comments/{comment_id}")
def get_comment(request):
    post_id = request.path_params["post_id"]
    comment_id = request.path_params["comment_id"]
    return {"post_id": post_id, "comment_id": comment_id}

Request & Response: Intuitive request/response handling

from catzilla import JSONResponse, HTMLResponse

@app.post("/data")
def handle_data(request):
    # Access request properties
    method = request.method
    headers = request.headers

    # Return various response types
    return JSONResponse({"received": "data"}, status_code=201)

Real-World Example

Here’s a complete blog API showcasing Catzilla’s capabilities:

from catzilla import App, RouterGroup, JSONResponse

app = App()

# Authentication API
auth = RouterGroup(prefix="/auth")

@auth.post("/login")
def login(request):
    return {"token": "jwt-token-here"}

@auth.post("/logout")
def logout(request):
    return {"message": "Logged out successfully"}

# Blog Posts API
posts = RouterGroup(prefix="/posts")

@posts.get("/")
def list_posts(request):
    return {
        "posts": [
            {"id": 1, "title": "Hello World", "author": "alice"},
            {"id": 2, "title": "Catzilla Guide", "author": "bob"}
        ]
    }

@posts.get("/{post_id}")
def get_post(request):
    post_id = request.path_params["post_id"]
    return {
        "id": post_id,
        "title": f"Post {post_id}",
        "content": "Post content here..."
    }

@posts.post("/")
def create_post(request):
    return JSONResponse({"message": "Post created"}, status_code=201)

@posts.put("/{post_id}")
def update_post(request):
    post_id = request.path_params["post_id"]
    return {"message": f"Post {post_id} updated"}

# Users API
users = RouterGroup(prefix="/users")

@users.get("/{user_id}")
def get_user(request):
    user_id = request.path_params["user_id"]
    return {"id": user_id, "name": f"User {user_id}"}

@users.get("/{user_id}/posts")
def get_user_posts(request):
    user_id = request.path_params["user_id"]
    return {
        "user_id": user_id,
        "posts": [{"id": 1, "title": "My First Post"}]
    }

# Include all route groups
app.include_routes(auth)
app.include_routes(posts)
app.include_routes(users)

if __name__ == "__main__":
    app.listen(8000)

This creates a full REST API with organized endpoints:

Authentication - POST /auth/login - User authentication - POST /auth/logout - User logout

Blog Management - GET /posts/ - List all posts - GET /posts/123 - Get specific post - POST /posts/ - Create new post - PUT /posts/123 - Update existing post

User Management - GET /users/456 - Get user profile - GET /users/456/posts - Get user’s posts

When to Use Catzilla

Perfect For:

✅ High-throughput APIs - Microservices, API gateways, data processing pipelines

✅ Low-latency applications - Real-time APIs, financial systems, gaming backends

✅ Resource-constrained environments - Cloud functions, edge computing, embedded systems

✅ Performance-critical workloads - When every millisecond and CPU cycle matters

Consider Alternatives For:

❌ Full-stack web applications - Catzilla focuses on APIs, not template rendering

❌ Rapid prototyping - More mature frameworks may have richer ecosystems for quick builds

❌ Complex authentication flows - Built-in auth systems may be more convenient

Installation & Dependencies

Catzilla uses only Python standard library - no external runtime dependencies:

# Production installation (v0.1.0 from GitHub Releases)
pip install https://github.com/rezwanahmedsami/catzilla/releases/download/v0.1.0/catzilla-0.1.0-cp310-cp310-linux_x86_64.whl

# Future PyPI installation (v1.0.0+)
pip install catzilla

# Development installation
git clone --recursive https://github.com/rezwanahmedsami/catzilla.git
cd catzilla
pip install -e .

System Compatibility:

Catzilla provides comprehensive cross-platform support with pre-built wheels:

• Linux (x86_64): Python 3.8, 3.9, 3.10-3.13 - Full Support

• macOS Intel (x86_64): Python 3.8, 3.9, 3.10-3.13 - Full Support

• macOS Apple Silicon: Python 3.8, 3.9, 3.10-3.13 - Full Support

• Windows (x86_64): Python 3.8, 3.9, 3.10-3.13 - Full Support

Build Requirements (Source Installation): - Python 3.8-3.13 with development headers - CMake 3.15+ - C compiler (GCC/Clang/MSVC) with C11 support - Git (for submodule dependencies)

Note

For detailed platform support, wheel information, and troubleshooting, see the System Compatibility Guide.

Community & Support

GitHub Repository

https://github.com/rezwanahmedsami/catzilla

Documentation

Complete guides, API reference, and examples

Issue Tracking

Bug reports, feature requests, and community discussion

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines

Author

Rezwan Ahmed Sami - samiahmed0f0@gmail.com

License

Catzilla is released under the MIT License. See LICENSE file for complete terms.

The MIT License allows you to: - ✅ Use Catzilla in commercial applications - ✅ Modify and distribute the source code - ✅ Include in proprietary software - ✅ Sell applications built with Catzilla

Index & Search

• Index

• Module Index

• Search Page