cello-framework 1.4.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
#   ➜  Server:    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 (native, v1.4.0)

See the ORM and Database references.

API Protocol Features (v0.9.0)

Protocol Support

📘 Examples

Runnable examples (v1.4.0 data layer)

Each file lives in examples/ and has a page with captured output in the examples docs.

Data Layer (v1.4.0)

from cello import App, DatabaseConfig, RedisConfig, UniqueViolation, Response
from cello.database import transactional
from cello.orm import Model, AutoField, CharField, BooleanField, setup

app = App()

app.enable_database(DatabaseConfig(
    url="postgresql://user:pass@localhost/mydb",
    pool_size=20,
    sslmode="verify-full",          # default is "prefer"
))
app.enable_redis(RedisConfig(url="redis://localhost:6379"))

class User(Model):
    id = AutoField()
    name = CharField(max_length=100)
    email = CharField(max_length=255, unique=True)
    active = BooleanField(default=True)

@app.on_event("startup")
async def startup():
    setup(app.database)
    await User.create_table()

@app.get("/users")
async def users(request):
    # Returned querysets are encoded straight from Postgres rows to JSON in Rust
    return {"users": User.objects.filter(active=True).order_by("id")}

@app.post("/users", body=User)      # validated natively; 400 {"detail": [...]} on bad input
async def create(request, body):
    try:
        return await body.save()
    except UniqueViolation:
        return Response.json({"error": "email taken"}, status=409)

@app.post("/transfer")
@transactional
async def transfer(request, tx):
    await tx.execute("UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, 1)
    await tx.execute("UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, 2)
    return {"success": True}

app.run()

Headline numbers from a paired local benchmark against 1.3.0 (both servers running at the same time, wrk -t2 -c32, local Postgres; method and caveats in the release notes): a 200-row list returned as a queryset is 19.7× faster, Model.objects.get 5.4×, create 4.6×. Endpoints that do not touch the database are unchanged within noise.

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.4.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.4.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.4.0 — The Native Core (Oct 2026)

One model declaration, compiled once in Rust, drives the ORM, request validation, response serialization and OpenAPI.

• Speed: prepared-statement cache for every Postgres query; new async bridge (database and Redis calls no longer hop through extra threads); response serializer dispatches on concrete types first (~5.5×); Rust row → JSON pipeline — return {"users": qs}, await qs.json() and db.fetch_json() are encoded straight from Postgres rows, byte-identical to to_dict(). Paired local benchmark vs 1.3.0: 200-row list 19.7×, get 5.4×, create 4.6× (method and caveats in the release notes)
• Security: ORM identifier injection closed (every identifier resolves through the schema registry); write_only / read_only model fields; Postgres TLS with libpq-style sslmode; fixed an exit-time crash and Ctrl-C being ignored under load; production 500 responses no longer expose exception text (logged instead); async def shutdown hooks now run on Ctrl-C
• Simplicity: native body=Model validation and OpenAPI request schemas generated from the same model; exact NUMERIC, arrays, intervals and datetime/UUID binding with a DatabaseError hierarchy; Q objects, aggregates, select_related / prefetch_related, bulk_create / bulk_update; experimental python -m cello migrate
• Breaking: undeclared column names raise FieldError; out-of-range integers raise instead of wrapping; fetchrow / fetchval return the first row; exclude() is null-safe; filter(x=None) means IS NULL; default sslmode is prefer — see the migration notes in the release notes

v1.3.0 — Async Rework, Native Data Layer & Three-Pillar Upgrades (Jul 2026)

• async def handlers run on one persistent asyncio loop; native Postgres pool, async Redis client (incl. rediss://) and built-in async ORM replace the old mock layer
• Full audit of every enable_* plugin (health-check / GraphQL / Prometheus 404s, BasicAuth challenge, JWT iat, security-headers config, timeout panic fixed)
• Full security headers, gzip-compressed cache hits, declarative body= request validation, adaptive threadpool offload for blocking sync handlers
• CSRF / skip-path / CORS / BasicAuth / SSE hardening; request body-size limits and header / body / handler timeouts

v1.2.4 — Critical Async Fix (Jun 2026)

• Fixed every async def handler returning 500 since v1.2.1

v1.2.3 — Full Middleware Python API (Jun 2026)

• cello.middleware module, app.use() dispatcher, six new enable_* methods; all documentation import paths corrected

v1.2.2 — Security & Bug Fixes (Jun 2026)

• CSRF double-submit cookie HttpOnly fix; middleware skip_path prefix bypass fixed; rate limiter window reset fixed

v1.2.1 — Critical Bug Fixes (Jun 2026)

• Server port was never bound; ProblemDetails export added; And / Or guards accept *args and list styles

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