cello-framework 1.3.0

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)

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

📦 Installation

pip install cello-framework

From source:

git clone https://github.com/jagadeesh32/cello.git
cd cello
pip install maturin
maturin develop

Requirements: Python 3.12+

🚀 Quick Start

from cello 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

Security Features

v1.2.0 — Bug Fixes & Rust-Native AsyncClient

Template Engine (v1.1.0)

Enterprise Features (v0.7.0+)

Data Layer Features (v0.8.0)

API Protocol Features (v0.9.0)

Protocol Support

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

@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()

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

app.enable_grpc(GrpcConfig(port=50051, reflection=True))
app.add_grpc_service("UserService", ["GetUser", "ListUsers"])

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

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

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

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

🔒 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

# Setup
git clone https://github.com/jagadeesh32/cello.git
cd cello
python -m venv .venv
source .venv/bin/activate
pip install maturin pytest

# Build
maturin develop

# Test
pytest tests/ -v

# Lint
cargo clippy
cargo fmt

📋 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: Aggregate root pattern, event store, snapshot support, event versioning
• 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 for N+1 prevention, schema introspection
• gRPC: Protocol buffer integration, bidirectional streaming, gRPC-Web, reflection service
• Kafka: Consumer/producer decorators, consumer group management, dead letter queues
• RabbitMQ: AMQP messaging with topic exchanges and prefetch control
• SQS/SNS: AWS message queue integration with LocalStack support

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: cello.lineupcode.com

• 📖 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