Cello Framework¶

🔥 Cello Framework 🚀

Ultra-Fast Python Web Framework

Rust-powered performance meets Python simplicity

Get Started GitHub PyPI

v1.0.1 394 tests passing MIT License Python 3.12+

Why Cello?¶

Blazing Fast

The entire hot path runs in native Rust -- SIMD JSON parsing, radix-tree routing, and middleware execution. Python only touches your business logic.

Performance benchmarks
Enterprise Security

Production-grade JWT authentication, RBAC guards, CSRF protection, rate limiting with sliding windows, and security headers with constant-time comparison.

Security features
Modern Protocols

First-class support for HTTP/2, HTTP/3 (QUIC), WebSocket, and Server-Sent Events -- all powered by Rust's async runtime.

Real-time features
Developer Experience

FastAPI-style dependency injection, Flask-like blueprints, auto-generated OpenAPI/Swagger docs, and full type hint support.

Quick start
API Protocols

Native GraphQL with subscriptions, gRPC with streaming, and message queue adapters for Kafka, RabbitMQ, and SQS.

API protocols
Advanced Patterns

Event Sourcing, CQRS, and Saga orchestration built right into the framework. Enterprise architecture, zero boilerplate. Stable in v1.0.1.

Event Sourcing

Quick Start¶

Installation Hello World REST API Event Sourcing

# Install from PyPI
pip install cello-framework

# Or with optional dependencies
pip install cello-framework[graphql,grpc,kafka]

# Verify installation
python -c "import cello; print(cello.__version__)"

from cello import App

app = App()

@app.get("/")
def home(request):
    return {"message": "Hello, Cello!"}

@app.get("/users/{id}")
def get_user(request):
    user_id = request.params["id"]
    return {"id": user_id, "name": "Alice"}

if __name__ == "__main__":
    app.run()
# => Cello running at http://127.0.0.1:8000

from cello import App, Response, Blueprint
from cello.guards import RoleGuard

app = App()
api = Blueprint("api", url_prefix="/api/v1")

admin_only = RoleGuard(["admin"])

@api.get("/users")
def list_users(request):
    return {"users": [{"id": 1, "name": "Alice"}]}

@api.post("/users", guards=[admin_only])
def create_user(request):
    data = request.json()
    return Response.json({"created": True, **data}, status=201)

@api.get("/users/{id}")
def get_user(request):
    return {"id": request.params["id"]}

app.register_blueprint(api)

if __name__ == "__main__":
    app.run(port=8000, workers=4)

from cello import App
from cello.eventsourcing import EventStore, Event, AggregateRoot

app = App()
store = EventStore()

class OrderCreated(Event):
    order_id: str
    customer: str
    total: float

class Order(AggregateRoot):
    def create(self, customer: str, total: float):
        self.apply(OrderCreated(
            order_id=self.id,
            customer=customer,
            total=total
        ))

    def on_order_created(self, event: OrderCreated):
        self.customer = event.customer
        self.total = event.total

@app.post("/orders")
async def create_order(request):
    data = request.json()
    order = Order()
    order.create(data["customer"], data["total"])
    await store.save(order)
    return {"order_id": order.id, "status": "created"}

Architecture¶

graph LR
    A["<b>Request</b><br/>HTTP/1.1, HTTP/2, HTTP/3"] --> B["<b>Rust HTTP Engine</b><br/>Tokio + Hyper"]
    B --> C{"<b>Radix Router</b><br/>matchit O(log n)"}
    C --> D["<b>Middleware Chain</b><br/>Auth, CORS, Rate Limit"]
    D --> E["<b>Python Handler</b><br/>Your Business Logic"]
    E --> F["<b>Rust Response Builder</b><br/>SIMD JSON Serialization"]
    F --> G["<b>Response</b><br/>Zero-Copy Output"]

    style A fill:#1A1A1A,stroke:#E65100,color:#FF9100
    style B fill:#1A1A1A,stroke:#E65100,color:#FF9100
    style C fill:#1A1A1A,stroke:#E65100,color:#FF9100
    style D fill:#1A1A1A,stroke:#E65100,color:#FF9100
    style E fill:#1A1A1A,stroke:#424242,color:#42a5f5
    style F fill:#1A1A1A,stroke:#E65100,color:#FF9100
    style G fill:#1A1A1A,stroke:#E65100,color:#FF9100

Rust owns the hot path. Every TCP connection, HTTP parse, route lookup, middleware check, and JSON serialization happens in native Rust. Python is invoked only for your handler function -- then Rust takes over again to build and send the response. The result: C-level throughput with Python-level simplicity.

Component	Technology	Why It Matters
HTTP Server	Tokio + Hyper	Async I/O with zero Python overhead
JSON Parsing	simd-json	10x faster than Python's `json` module
Routing	matchit (radix tree)	O(log n) lookup with compile-time optimization
Middleware	Pure Rust pipeline	No GIL contention, zero-copy data flow
TLS	rustls	Memory-safe TLS without OpenSSL
WebSocket	tokio-tungstenite	Native async WebSocket in Rust

Feature Comparison¶

How Cello stacks up against popular Python web frameworks (4 workers, 5 processes each, wrk 12t/400c/10s):

Feature	Cello	BlackSheep+Granian	FastAPI+Granian	Robyn
Requests/sec	170K+	92K	55K	29K
Async Native
Rust Core
SIMD JSON
WebSocket
HTTP/2
HTTP/3 (QUIC)
SSE
GraphQL
gRPC
Message Queues
Dependency Injection
RBAC Guards
OpenAPI Auto-Gen
Event Sourcing
CQRS
Saga Pattern

Tech Stack¶

Rust Core
- Tokio -- async runtime
- Hyper -- HTTP/1.1 & HTTP/2
- simd-json -- hardware-accelerated JSON
- matchit -- radix tree routing
- bumpalo -- arena allocators
Python API
- PyO3 -- zero-overhead FFI
- abi3-py312 -- single binary for all versions
- Type hints -- full IDE support
- Async/await -- native coroutines
- Pydantic -- optional validation
Security
- jsonwebtoken -- JWT auth
- subtle -- constant-time comparison
- rustls -- memory-safe TLS
- hmac + sha2 -- hashing
- DashMap -- lock-free concurrency
Protocols
- h2 -- HTTP/2 support
- quinn -- HTTP/3 / QUIC
- tokio-tungstenite -- WebSocket
- SSE -- Server-Sent Events
- rustls -- native HTTPS
API & Messaging
- async-graphql -- GraphQL engine
- tonic -- gRPC framework
- rdkafka -- Apache Kafka
- lapin -- RabbitMQ (AMQP)
- SQS -- AWS message queue

What's New in v1.0.1¶

v1.0.1 -- Production Ready

Cello reaches stable release with a complete feature set, major performance optimizations, and a semantic versioning commitment. The API is now frozen -- no breaking changes until v2.0.

Production Stable -- Battle-tested API with semantic versioning guarantees. Ready for enterprise deployments.
Performance Optimizations -- Handler metadata caching, lazy body parsing, zero-copy responses, TCP_NODELAY, and optimized release builds deliver peak throughput.
Complete Feature Set -- Routing, middleware, auth, WebSocket, SSE, DI, guards, caching, rate limiting, OpenTelemetry, GraphQL, gRPC, Event Sourcing, CQRS, and Saga patterns -- all in one framework.

Full Release Notes Migration Guide

Documentation¶

Getting Started

Installation, quick start guide, your first application, project structure, and configuration.

Get started
Features

Routing, middleware, security, real-time, dependency injection, templates, and file uploads.

Explore features
Learn

Step-by-step tutorials for REST APIs, chat apps, auth systems, and microservices.

Tutorials & guides
API Reference

Complete API documentation for App, Request, Response, Blueprint, Middleware, Guards, and Context.

Reference docs
Examples

Ready-to-run examples from hello world to full-stack apps, microservices, and event sourcing.

Browse examples
Enterprise

OpenTelemetry, GraphQL, gRPC, message queues, Docker, Kubernetes, and service mesh deployment.

Enterprise docs

Community & Contributing¶

We welcome contributions of all kinds. Whether it is a bug report, feature request, documentation improvement, or code contribution -- every bit helps.

Report Issues

Found a bug or have a feature request? Open an issue on GitHub and help us improve Cello.

Open an Issue
Submit Pull Requests

Want to contribute code? Check out the contributing guide, pick an issue, and submit a PR.

Contributing Guide
Join the Community

Questions, ideas, or just want to chat? Join our Discord server and connect with other developers.

:material-discord: Join Discord