Catzilla

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

---

Overview

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.

✨ 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)

---

📦 Installation

Quick Start (Recommended)

Install Catzilla from PyPI:

pip install catzilla

System Requirements:

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

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.8-3.13
• CMake 3.15+
• C Compiler: GCC/Clang (Linux/macOS) or MSVC (Windows)

---

🚀 Quick Start

Create your first Catzilla app:

# app.py
from catzilla import App

app = App()

@app.get("/")
def hello():
    return "Hello, Catzilla! 🐱⚡"

@app.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}"}

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

Run your app:

python app.py

Visit http://localhost:8000 to see your blazing-fast API in action! 🚀

---

🖥️ System Compatibility

Catzilla v0.1.0 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.8	✅	✅	✅	✅
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/v0.1.0/catzilla-0.1.0.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 v0.1.0 has been extensively benchmarked against other popular Python web frameworks using wrk with 100 concurrent connections over 10 seconds on a real production server.

🏗️ Real Server Environment

Intel Xeon E3-1245 v5 @ 3.5GHz | 31GB RAM | AlmaLinux 8.10 | Python 3.8.12

This is authentic benchmark data collected from a real server environment, not synthetic or optimized conditions.

🚀 Exceptional Performance Results

Massive Throughput Advantage: Catzilla delivers extraordinary performance compared to all competitors:

Endpoint	Catzilla	FastAPI	Django	Flask	vs FastAPI
Hello World	24,759	2,844	2,339	2,875	+771% faster
JSON Response	15,754	2,421	2,208	2,672	+551% faster
Path Parameters	17,590	2,341	2,219	2,624	+651% faster
Query Parameters	11,145	1,419	1,975	2,431	+685% faster
Complex JSON	14,843	2,008	2,162	2,521	+639% faster

Ultra-Low Latency: Catzilla consistently delivers significantly lower latency:

• Average Latency: 5.97ms vs FastAPI's 47.69ms (87% lower)
• Hello World: 4.07ms vs FastAPI's 35.04ms (88% lower)
• Complex JSON: 6.79ms vs FastAPI's 49.63ms (86% lower)

Performance Summary

• Average RPS: 16,818 vs FastAPI's 2,207 (+662% faster)
• Peak Performance: 24,759 RPS on hello world endpoint
• Ultra-Low Latency: Sub-7ms average response times
• Framework Leadership: Fastest Python web framework tested by massive margins

📋 View Complete Performance Report - Detailed analysis with technical insights

📈 Performance Visualizations

Performance charts and detailed analysis available in the Complete Performance Report

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.

---

🗂️ Project Structure

catzilla/
├── CMakeLists.txt                # CMake build config
├── setup.py                      # Python package build entry (uses CMake)
├── CONTRIBUTING.md               # Comprehensive development guide
├── .gitmodules                   # Git submodules: libuv, llhttp
├── deps/                         # External C dependencies
│   ├── libuv/                    # Event loop lib
│   └── unity/                    # C testing framework
├── src/                          # C core source
│   ├── core/                     # Event loop, server & advanced router
│   │   ├── server.c/h           # Main HTTP server implementation
│   │   └── router.c/h           # Trie-based routing engine
│   └── python/                   # CPython bindings
│       └── module.c             # Python C extension
├── python/                       # Python package (catzilla/)
│   └── catzilla/
│       ├── __init__.py          # Public API
│       └── routing.py           # High-level Router class
├── tests/                        # Comprehensive test suite (90 tests)
│   ├── c/                       # C unit tests (28 tests)
│   │   ├── test_router.c        # Basic router tests
│   │   ├── test_advanced_router.c # Advanced routing features
│   │   └── test_server_integration.c # Server integration
│   └── python/                  # Python tests (62 tests)
│       ├── test_advanced_routing.py # Python routing tests
│       ├── test_http_responses.py   # HTTP response handling
│       ├── test_basic.py           # Basic functionality
│       └── test_request.py         # Request handling
├── examples/                     # Example applications
├── scripts/                      # Development scripts
│   ├── build.sh                 # Complete build script
│   ├── run_tests.sh             # Unified test runner
│   └── run_example.sh           # Example runner
├── docs/                         # Sphinx-based docs
└── .github/                      # CI/CD workflows

---

🚀 Getting Started

Quick Start

1. Clone the repository:

   git clone https://github.com/rezwanahmedsami/catzilla.git
   cd catzilla
   git submodule update --init --recursive

2. Build and install:

   ./scripts/build.sh

3. Run an example:

   ./scripts/run_example.sh examples/hello_world/main.py

Advanced Routing Examples

from catzilla import Router

app = Router()

# Static routes
@app.get("/")
def home():
    return "Welcome to Catzilla!"

# Dynamic path parameters
@app.get("/users/{user_id}")
def get_user(request, user_id):
    return f"User ID: {user_id}"

# Multiple parameters
@app.get("/users/{user_id}/posts/{post_id}")
def get_user_post(request, user_id, post_id):
    return f"User {user_id}, Post {post_id}"

# Multiple HTTP methods on same path
@app.get("/api/data")
def get_data():
    return {"method": "GET"}

@app.post("/api/data")
def create_data():
    return {"method": "POST"}

# HTTP status codes are handled automatically:
# - 404 Not Found for missing routes
# - 405 Method Not Allowed for wrong methods (includes Allow header)
# - 415 Unsupported Media Type for parsing errors

🔧 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 test suite includes 90 comprehensive tests covering both C and Python components:

# Run all tests (90 tests: 28 C + 62 Python)
./scripts/run_tests.sh

# Run specific test suites
./scripts/run_tests.sh --python  # Python tests only (62 tests)
./scripts/run_tests.sh --c       # C tests only (28 tests)
./scripts/run_tests.sh --verbose # Detailed output

# Test results overview:
# ✅ C Tests: 28/28 PASSING
#   - Basic router: 3 tests
#   - Advanced router: 14 tests
#   - Server integration: 11 tests
# ✅ Python Tests: 62/62 PASSING
#   - Advanced routing: 22 tests
#   - HTTP responses: 17 tests
#   - Basic functionality: 10 tests
#   - Request handling: 13 tests

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
• API Reference - Complete API documentation
• Routing Guide - Advanced routing features
• System Compatibility - Platform support and installation guide
• Examples - Real-world example applications
• Contributing - Development guide for contributors

---

🤖 Built with the Help of AI Development Partners

Claude Sonnet 4	GitHub Copilot	Visual Studio Code
Technical Guidance	Code Assistance	Development Environment

Catzilla was developed with the assistance of cutting-edge AI development tools that enhanced productivity and code quality:

• Claude Sonnet 4 - Technical consultation for architecture decisions, debugging assistance, and problem-solving guidance
• GitHub Copilot - Intelligent code suggestions and development acceleration
• Visual Studio Code - Primary development environment with integrated AI assistance

AI partnership accelerated development from an estimated 3-6 months to just 1 week, while maintaining production-grade code quality, comprehensive testing (90 tests), and cross-platform compatibility.

Development Approach

• Human-Driven Architecture: Core design decisions and technical vision by the developer
• AI-Assisted Implementation: Code suggestions, boilerplate generation, and pattern completion
• Collaborative Debugging: AI-enhanced problem identification and solution guidance
• Enhanced Documentation: AI-supported technical writing and comprehensive guides

This showcases the potential of human creativity amplified by AI assistance—developer expertise enhanced by intelligent tooling. 🚀

---

👤 Author

Rezwan Ahmed Sami 📧 [email protected] 📘 Facebook

---

🪪 License

MIT License — See LICENSE for full details.