cellon 1.4.6

Ultra-Fast Python Web Framework
Rust-powered performance with Python simplicity

Installation • Quick Start • Features • Examples • Documentation

---

Why Cello?

Cello is an enterprise-grade Python web framework that combines Python's developer experience with Rust's raw performance. All HTTP handling, routing, JSON serialization, and middleware execute in native Rust while Python handles your business logic.

┌─────────────────────────────────────────────────────────────────┐
│  Request → Rust HTTP Engine → Python Handler → Rust Response   │
│                  │                    │                         │
│                  ├─ SIMD JSON         ├─ Return dict            │
│                  ├─ Radix routing     └─ Return Response        │
│                  └─ Middleware (Rust)                           │
└─────────────────────────────────────────────────────────────────┘

---

⚡ Performance

Cello sustains C-level throughput. The figures below are the latest measured run (release build, wrk -t12 -c400 -d10s, 4 workers / 5 processes) on an 8-core WSL2 box where wrk and the server share the same cores — dedicated hardware, or running wrk on a separate machine, scales higher.

Benchmark Results (release build, 4 workers, wrk -t12 -c400 -d10s)

Endpoint	Req/sec	Avg Latency
GET / (simple JSON)	~138,000	3.3–4.7 ms
GET /json (nested JSON)	~134,000	3.3–3.8 ms

How to reproduce: See benchmarks/ for the benchmark runner using the same JSON endpoint, process count, and wrk settings.

---

📦 Installation

pip install cellon

Requirements: Python 3.12+

Release artifacts are built by GitHub Actions. See PUBLISHING.md for the PYPI_API_TOKEN setup.

---

🚀 Quick Start

from cellon import App, Response

app = App()

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

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

@app.post("/users")
def create_user(request):
    data = request.json()
    return Response.json({"id": 1, **data}, status=201)

if __name__ == "__main__":
    app.run()

python app.py
# 🐍 Cello v1.2.0 server starting at http://127.0.0.1:8000

---

✨ Features

Core Features

Feature	Description
🚀 Blazing Fast	Tokio + Hyper async HTTP engine in pure Rust
📦 SIMD JSON	SIMD-accelerated JSON parsing with simd-json
🛤️ Radix Routing	Ultra-fast route matching with matchit
🔄 Async/Sync	Support for both async def and regular def handlers
🛡️ Middleware	Built-in CORS, logging, compression, rate limiting
📐 Blueprints	Modular route grouping for larger apps
🌐 WebSocket	Real RFC 6455 connections (tokio channels + tungstenite)
📡 SSE	Server-Sent Events for streaming
📁 Multipart	File uploads and form data handling

Security Features

Feature	Description
🔐 JWT Authentication	JSON Web Token with constant-time validation
🛡️ CSRF Protection	Double-submit cookie and signed token patterns
⏱️ Rate Limiting	Token bucket, sliding window, and adaptive algorithms
🍪 Sessions	Secure cookie-based session management
🔒 Security Headers	CSP, HSTS, X-Frame-Options, Referrer-Policy
🔑 API Key Auth	Header and query parameter authentication

v1.2.0 — Bug Fixes & Rust-Native AsyncClient

Feature	Description
🐛 Shutdown coroutine fix	async def shutdown hooks are now properly awaited via Tokio
🐛 KeyboardInterrupt fix	CTRL+C no longer leaks into shutdown handlers
🐛 request.redis fix	AttributeError on request.redis resolved when Redis is enabled
🦀 Rust AsyncClient	AsyncClient rewritten in Rust (reqwest + Tokio) — GIL never held during HTTP I/O
📜 Redis Lua scripting	eval, evalsha, script_load for atomic server-side operations

Template Engine (v1.1.0)

Feature	Description
🎨 MiniJinja	Full Jinja2-compatible templates rendered entirely in Rust
⚡ Zero Python overhead	Template rendering stays on the Rust side via minijinja 2
🔒 Auto HTML-escaping	XSS-safe output for .html/.htm/.xml by default
🧱 Template inheritance	{% extends %} / {% block %} for base + child layouts
🔁 Includes & macros	{% include %}, {% macro %}, {% import %} for reuse
🌍 Global variables	add_global() for site-wide values (app name, year, etc.)
📦 Standalone engine	MiniJinjaEngine usable independently from App (emails, CLI)

Enterprise Features (v0.7.0+)

Feature	Description
📊 OpenTelemetry	Distributed tracing with W3C Trace Context
🏥 Health Checks	Kubernetes-compatible liveness/readiness probes
🗄️ Database Pooling	Connection pool management with metrics
🔷 GraphQL	GraphQL endpoint with Playground UI
💉 Dependency Injection	Type-safe DI with Singleton/Request/Transient scopes
🛡️ Guards (RBAC)	Role & permission-based access control
📈 Prometheus Metrics	Production-ready metrics at /metrics
🔌 Circuit Breaker	Fault tolerance with automatic recovery

Data Layer Features (v0.8.0)

Feature	Description
🗄️ Enhanced DB Pooling	Async connection pool with health monitoring & reconnection
🔴 Redis Integration	Async Redis client with pool, Pub/Sub, cluster mode
🔄 Transactions	Automatic transaction management with decorator support

API Protocol Features (v0.9.0)

Feature	Description
🔷 GraphQL	Query/Mutation/Subscription engine with HTTP mounting + graphql-ws WebSocket subscriptions
📊 DataLoader	Explicit batching and caching loader
🔌 gRPC	grpc.aio HTTP/2 transport with unary, client/server/bidi streaming, reflection & gRPC-Web
📜 Structured Logging	JSON or text access logs via tracing-subscriber
📨 Kafka	Compatibility producer/consumer adapter; external Kafka client pending
🐰 RabbitMQ	Real AMQP producer/consumer with durable queues and acknowledgements
☁️ SQS/SNS	Compatibility configuration API; external SQS client pending

Protocol Support

Feature	Description
🔒 TLS/SSL	Native HTTPS with rustls
⚡ HTTP/2	Multiplexed connections with h2
🚀 HTTP/3	QUIC/UDP listener via quinn + h3 (requires TLS cert/key)
🏭 Cluster Mode	Multi-worker process deployment

---

📘 Examples

Data Layer Features (v0.8.0)

from cello import App, DatabaseConfig, RedisConfig
from cello.database import transactional

app = App()

# Enable database connection pooling
app.enable_database(DatabaseConfig(
    url="postgresql://user:pass@localhost/mydb",
    pool_size=20,
    max_lifetime_secs=1800
))

# Enable Redis connection
app.enable_redis(RedisConfig(
    url="redis://localhost:6379",
    pool_size=10
))

# NOTE: enable_database()/enable_redis() must run before routes are registered,
# otherwise request.database / request.redis are not injected into those routes.

@app.post("/transfer")
@transactional
async def transfer(request):
    # Automatic transaction management
    return {"success": True}

@app.get("/")
def home(request):
    return {"status": "ok", "version": "1.2.0"}

app.run()

API Protocol Features (v0.9.0)

from cello import App, GrpcConfig, KafkaConfig, RabbitMQConfig
from cello.graphql import Query, Mutation, Schema, DataLoader, GraphQL
from cello.grpc import GrpcService, grpc_method, GrpcServer
from cello.messaging import kafka_consumer, kafka_producer, Producer, Consumer

app = App()

# --- GraphQL ---
@Query
def users(info):
    return [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]

@Mutation
def create_user(info, name: str, email: str):
    return {"id": 3, "name": name, "email": email}

schema = Schema().query(users).mutation(create_user).build()
app.mount_graphql(schema)

# --- gRPC ---
class UserService(GrpcService):
    @grpc_method
    async def get_user(self, request):
        return {"id": request.data.get("id"), "name": "Alice"}

app.enable_grpc(GrpcConfig(address="[::]:50051"))
app.add_grpc_service(UserService())

# --- Kafka ---
app.enable_messaging(KafkaConfig(brokers=["localhost:9092"], group_id="my-app"))

@kafka_consumer(topic="user-events", group="processors")
async def handle_user_event(message):
    print(f"Received: {message.text}")

@app.post("/users")
@kafka_producer(topic="user-events")
def create_user_api(request):
    return {"id": 1, "name": request.json().get("name")}

# --- RabbitMQ ---
app.enable_rabbitmq(RabbitMQConfig(url="amqp://localhost:5672"))

@app.get("/")
def home(request):
    return {"status": "ok", "version": "1.3.0", "protocols": ["graphql", "grpc", "kafka", "rabbitmq"]}

app.run()

Enterprise Features (v0.7.0+)

from cello import App, OpenTelemetryConfig, HealthCheckConfig, GraphQLConfig

app = App()

# Enable distributed tracing
app.enable_telemetry(OpenTelemetryConfig(
    service_name="my-api",
    otlp_endpoint="http://collector:4317",
    sampling_rate=0.1
))

# Enable Kubernetes health checks
app.enable_health_checks(HealthCheckConfig(
    base_path="/health",
    include_details=True,
    include_system_info=True
))

# Enable GraphQL with Playground
app.enable_graphql(GraphQLConfig(
    path="/graphql",
    playground=True,
    introspection=True
))

# Enable Prometheus metrics
app.enable_prometheus(endpoint="/metrics")

@app.get("/")
def home(request):
    return {"status": "ok", "version": "1.2.0"}

app.run()

Blueprints (Route Grouping)

from cello import App, Blueprint

api_v1 = Blueprint("/api/v1")

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

@api_v1.post("/users")
def create_user(request):
    return Response.json(request.json(), status=201)

app = App()
app.register_blueprint(api_v1)
app.run()

Guards (RBAC)

from cello import App, RateLimitConfig

app = App()

# Role-based access control
@app.add_guard
def require_auth(request):
    return request.headers.get("Authorization") is not None

@app.add_guard
def require_admin(request):
    token = request.headers.get("Authorization", "")
    return "admin" in token

# Rate limiting
app.enable_rate_limit(RateLimitConfig.token_bucket(
    capacity=100,
    refill_rate=10
))

@app.get("/admin")
def admin_panel(request):
    return {"message": "Welcome, Admin!"}

WebSocket

Real connections: the server answers the RFC 6455 handshake (sha1-based Sec-WebSocket-Accept), then runs tokio-tungstenite with a channel pair per connection. Both async and sync handler styles are supported.

@app.websocket("/ws/chat")
async def chat_handler(ws):
    await ws.accept()
    await ws.send_text("Welcome to the chat!")

    while True:
        message = await ws.receive_text()
        if message is None:
            break
        await ws.send_json({"type": "echo", "content": message})

Structured Logging (JSON)

from cello.logging import LogFormat

app.configure_logging(
    format=LogFormat.JSON,
    level="INFO",
    exclude_paths=["/health", "/metrics"],
)
app.enable_logging()

Built-in Error Classes

from cello import NotFoundError, ValidationError, AuthenticationError, AuthorizationError

@app.exception_handler(NotFoundError)
def handle_not_found(request, exc):
    return {"error": "not found", "detail": str(exc)}

Server-Sent Events

from cello import SseStream

@app.get("/events")
def event_stream(request):
    stream = SseStream()
    stream.add_event("update", '{"count": 42}')
    stream.add_event("notification", '{"message": "New data"}')
    return stream

MiniJinja Templates (v1.1.0)

from cello import App, MiniJinjaEngine, Response

app = App()

# Attach once at startup — optional auto_escape and global variables
app.enable_templates(
    template_dir="templates",   # directory containing .html files
    auto_escape=True,           # HTML-escape {{ }} output (XSS safe)
    globals={"site_name": "My App", "year": 2026},
)

@app.get("/")
def home(request):
    html = app.render("index.html", {"title": "Home", "items": ["a", "b", "c"]})
    return Response.html(html)

# Inline rendering — no file needed
@app.get("/greet/{name}")
def greet(request):
    msg = app.render_string(
        "Hello, {{ name | title }}! Welcome to {{ site_name }}.",
        {"name": request.params["name"]},
    )
    return Response.html(msg)

# Standalone engine (outside of App — useful for emails, CLI, background tasks)
email_engine = MiniJinjaEngine(template_dir="templates/emails", auto_escape=False)
html = email_engine.render("welcome.html", {"user": "Alice"})

templates/base.html — base layout:

<!DOCTYPE html>
<html>
<head><title>{% block title %}{{ site_name }}{% endblock %}</title></head>
<body>
  <nav>{% block nav %}{% endblock %}</nav>
  <main>{% block content %}{% endblock %}</main>
  <footer>© {{ year }} {{ site_name }}</footer>
</body>
</html>

templates/index.html — child template:

{% extends "base.html" %}

{% block title %}Home — {{ site_name }}{% endblock %}

{% block content %}
<h1>{{ title }}</h1>
{% for item in items %}
<p>{{ loop.index }}. {{ item | upper }}</p>
{% endfor %}
{% endblock %}

Rust-Native AsyncClient (v1.2.0)

from cello import AsyncClient

client = AsyncClient(timeout=10.0)

# GET
resp = await client.get("https://api.example.com/data")
print(resp.status)    # int
print(resp.json())    # dict

# POST with JSON
resp = await client.post("https://api.example.com/items", json={"name": "widget"})

# PUT / PATCH / DELETE
resp = await client.put("https://api.example.com/items/1", json={"name": "updated"})
resp = await client.delete("https://api.example.com/items/1")

# Async context manager
async with AsyncClient() as c:
    resp = await c.get("https://example.com")

GIL is never held during network I/O. HTTP/2, gzip, and rustls TLS are included.

Redis Lua Scripting (v1.2.0)

app.enable_redis(RedisConfig(url="redis://localhost:6379", pool_size=10))

@app.get("/")
async def index(request):
    r = request.redis

    # Upload script once, reuse by SHA1
    sha = await r.script_load("""
        local m = redis.call('SISMEMBER', KEYS[1], ARGV[1])
        if m == 0 then return 0 end
        redis.call('LPUSH', KEYS[2], ARGV[2])
        return 1
    """)

    result = await r.evalsha(sha, 2, "tokens", "queue", "tok", "payload")
    return {"enqueued": result == 1}

Response Types

from cello import Response

# JSON (default)
return {"data": "value"}

# Explicit JSON with status
return Response.json({"created": True}, status=201)

# Other response types
return Response.text("Hello, World!")
return Response.html("<h1>Welcome</h1>")
return Response.file("/path/to/document.pdf")
return Response.redirect("/new-location")
return Response.no_content()

---

🏗️ Tech Stack

Component	Technology
Runtime	Tokio (async Rust)
HTTP Server	Hyper 1.x
JSON	simd-json + serde
Routing	matchit (radix tree)
Python Bindings	PyO3
TLS/SSL	rustls
HTTP/2	h2
HTTP/3	quinn (QUIC)
Tracing	OpenTelemetry
Metrics	Prometheus
JWT	jsonwebtoken
gRPC	Custom Rust gRPC engine
GraphQL	Python engine with Rust serialization
Messaging	Redis Streams and RabbitMQ clients; Kafka/SQS compatibility APIs
Templates	MiniJinja 2 (Jinja2-compatible, Rust)

---

🔒 Security

Cello is built with security as a priority:

• ✅ Constant-time comparison for passwords, API keys, and tokens
• ✅ CSRF protection with double-submit cookies and signed tokens
• ✅ Security headers (CSP, HSTS, X-Frame-Options, Referrer-Policy)
• ✅ Rate limiting with multiple algorithms
• ✅ Session security (Secure, HttpOnly, SameSite cookies)
• ✅ Path traversal protection in static file serving
• ✅ JWT blacklisting for token revocation

---

🛠️ Development

Source builds and CI checks run in GitHub Actions. See .github/workflows/ci.yml for the test matrix and PUBLISHING.md for the release workflow. Published users install the package with pip install cellon.

---

📋 Release History

v1.2.0 — Bug Fixes & Rust-Native AsyncClient (Jun 2026)

• Fix: async def shutdown handlers (@app.on_event("shutdown")) now correctly awaited via Tokio instead of silently dropped
• Fix: KeyboardInterrupt during CTRL+C no longer leaks into shutdown handler error output
• Fix: request.redis no longer raises AttributeError when app.enable_redis() is configured
• Rust AsyncClient: AsyncClient rewritten from Python stdlib to reqwest + Tokio — GIL is never held during HTTP I/O; HTTP/2, gzip, and rustls TLS included; API unchanged from v1.1.0
• Redis Lua scripting: eval(script, numkeys, *args), evalsha(sha, numkeys, *args), script_load(script) for atomic server-side operations

v1.1.0 — MiniJinja Template Engine (Apr 2026)

• MiniJinja integration: full Jinja2-compatible template engine built into Cello via minijinja 2 Rust crate — zero Python overhead on the render path
• app.enable_templates(): attach the engine as optional middleware in one line
• app.render(name, context) and app.render_string(source, context): render from file or inline string
• MiniJinjaEngine: standalone class for use outside of App (emails, CLI scripts, background tasks)
• HTML auto-escaping: XSS-safe by default for .html/.htm/.xml templates
• Global template variables: add_global() / add_globals() for site-wide variables
• Full Jinja2 syntax: {% if %}, {% for %}, {% block %}, {% extends %}, {% include %}, {% macro %}, {% import %}, all built-in filters
• Python type conversion: str, int, float, bool, None, list, tuple, dict, and objects with __dict__ all convert automatically

v1.0.1 — Cross-Platform & Compatibility Patch (Feb 2026)

• Windows multi-worker: subprocess re-execution (CELLO_WORKER=1) replaces broken multiprocessing.Process
• Windows signal handling: SIGTERM wrapped in try/except with platform validation
• Windows static files: UNC path normalization fix
• ARM JSON fallback: serde_json for non-SIMD architectures
• Linux-only CPU affinity: gated with warning on other platforms
• Async compatibility: wrap_handler_with_validation, _apply_guards, cache() all support async handlers
• Blueprint guards: Blueprint route decorators now support guards parameter and validation
• Export completeness: Guards (RoleGuard, PermissionGuard, Authenticated, And, Or, Not, GuardError, ForbiddenError, UnauthorizedError) and database (Database, Redis, Transaction) added to __all__

v1.0.0 — Production-Ready Stable Release (Feb 2026)

• 170,000+ req/s sustained throughput
• Handler metadata caching, lazy query parsing, zero-copy response building
• TCP_NODELAY, HTTP/1.1 keep-alive and pipeline flush optimization
• Pre-allocated headers, fast-path skip for empty middleware/guards
• Optimized release profile: LTO fat, panic abort, symbol stripping
• API stability guarantee under Semantic Versioning
• 394 tests passing, comprehensive security hardening

v0.10.0 — Event Sourcing, CQRS & Saga Pattern

• Event Sourcing: DuckDB/in-memory event store, replay, snapshots, and optimistic versions
• CQRS: Command/Query buses, separate read/write models, event-driven sync
• Saga Pattern: Distributed transaction coordination, compensation logic, persistent state, retry with backoff

v0.9.0 — GraphQL, gRPC & Message Queues

• GraphQL: Query, Mutation, Subscription decorators, DataLoader, HTTP query/mutation endpoint, and limited introspection
• gRPC: Real grpc.aio HTTP/2 generic transport with JSON payloads, unary calls, and server streaming; protobuf-generated stubs, reflection, gRPC-Web, and bidirectional streaming remain pending
• Kafka: Consumer/producer decorators, consumer group management, dead letter queues
• RabbitMQ: Real AMQP producer/consumer with durable queues and acknowledgements
• SQS/SNS: Compatibility configuration API; external SQS client pending

v0.8.0 — Database & Redis Integration

• Enhanced database connection pooling (PostgreSQL, MySQL, SQLite) with health monitoring
• Redis async client with connection pooling, Pub/Sub, and cluster mode
• Query builder with parameterized queries
• Transaction management with @transactional decorator and nested savepoints
• Pool metrics exposed via Prometheus

v0.7.0 — Enterprise Observability

• OpenTelemetry distributed tracing with OTLP export
• Health check endpoints (/health/live, /health/ready, /health/startup)
• Structured JSON logging with trace context injection
• Kubernetes deployment support and Docker multi-stage builds

v0.6.0 — Smart Caching & Validation

• @cache decorator with TTL and tag-based invalidation
• Adaptive rate limiting based on server health metrics
• DTO validation with RFC 7807 Problem Details errors
• Circuit breaker middleware for fault tolerance
• 15% faster JSON parsing, 20% lower memory usage

v0.5.0 — Dependency Injection & RBAC

• Dependency injection via Depends with singleton and transient lifetimes
• Composable guards: RoleGuard, PermissionGuard, AndGuard, OrGuard, NotGuard
• Prometheus metrics endpoint (/metrics)
• OpenAPI 3.0 schema generation with Swagger UI and ReDoc
• Background tasks and Jinja2 template rendering

v0.4.0 — Security & Cluster Mode

• JWT authentication (HS256/384/512, RS256/384/512, ES256/384)
• Rate limiting with token bucket and sliding window algorithms
• Encrypted cookie sessions with automatic rotation
• Security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options
• Cluster mode with multi-process workers via SO_REUSEPORT
• Native TLS via rustls (TLS 1.2 and 1.3)

v0.3.0 — Real-Time Communication

• WebSocket support via tokio-tungstenite with full-duplex communication
• Server-Sent Events (SSE) with async generators
• Multipart form handling and file uploads via multer
• Blueprints for modular route organization with nesting

v0.2.0 — Middleware System

• Composable middleware chain execution
• CORS middleware with configurable origins, methods, and headers
• Request/response logging middleware
• Gzip and brotli compression middleware

v0.1.0 — Initial Release

• Rust-powered HTTP server via Hyper and Tokio
• Python route registration with decorators (@app.get, @app.post, etc.)
• Radix tree routing via matchit with path parameters and wildcards
• SIMD-accelerated JSON parsing via simd-json
• Async handler support and static file serving
• PyO3 abi3 bindings for Python 3.12+

---

📚 Documentation

Full documentation available at: cellon.kuloon.qzz.io

• 📖 Getting Started
• ✨ Features
• 📘 API Reference
• 🏢 Enterprise Guide
• 📝 Examples

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

---

📄 License

MIT License - see LICENSE

---

👤 Author

Jagadeesh Katla - @jagadeesh32

---

Made with ❤️ using 🐍 Python and 🦀 Rust