Examples & Recipes¶

Learn by doing

Every example below is a complete, runnable application. Clone the repo, pick a recipe, and have it running in seconds. Examples are organized by difficulty so you can progress at your own pace.

Run an Example¶

Get any example running in under a minute.

# Clone the repository
git clone https://github.com/jagadeesh32/cello.git
cd cello

# Set up the environment
python -m venv .venv && source .venv/bin/activate
pip install -e .

# Run any example
python examples/hello.py

Live reload for development

Add --reload to automatically restart when you edit the file:

python examples/hello.py --reload

Beginner¶

Start here if you are new to Cello. These examples cover the fundamentals with minimal code.

Hello World

Beginner { .md-tag }

The simplest possible Cello app — one route, one response. Understand the core pattern that every Cello application follows.

Features used: App @app.get() dict response
```
@app.get("/")
def hello(request):
    return {"message": "Hello, World!"}
```
Full Example
REST API

Beginner { .md-tag }

Build a complete CRUD API with JSON validation, proper status codes, and error handling. The bread and butter of web development.

Features used: Blueprint Response.json() request.json() status codes
```
@api.post("/users")
def create_user(request):
    data = request.json()
    return Response.json(user, status=201)
```
Full Example
Form Handling

Beginner { .md-tag }

Accept form submissions and file uploads with multipart support. Covers both URL-encoded forms and file uploads.

Features used: request.form() multipart file uploads
```
@app.post("/upload")
def upload(request):
    file = request.files["document"]
    return {"filename": file.filename}
```
Full Example
JWT Authentication

Beginner { .md-tag }

Secure your routes with JSON Web Tokens. Covers token generation, verification, and protecting endpoints with a lightweight auth guard.

Features used: JWT Guards request.headers 401 responses
```
@app.get("/me")
@requires_auth
def profile(request):
    user = request.state.user
    return {"id": user.id, "email": user.email}
```
Full Example
Database Integration

Beginner { .md-tag }

Connect to SQLite or PostgreSQL using Cello's async DB helpers. Create tables, run queries, and map results to Python dicts with zero boilerplate.

Features used: async_db connection pool query helpers migrations
```
@app.get("/products")
async def list_products(request):
    rows = await db.fetch("SELECT * FROM products")
    return {"products": rows}
```
Full Example
Query Parameters & Validation

Beginner { .md-tag }

Parse and validate URL query parameters with automatic type coercion, default values, and descriptive error messages on invalid input.

Features used: request.query validators 400 error responses
```
@app.get("/search")
def search(request):
    q = request.query.get("q", "")
    page = int(request.query.get("page", 1))
    return {"query": q, "page": page}
```
Full Example

Intermediate¶

Ready to build real applications? These examples combine multiple Cello features into production-worthy patterns.

Full-Stack App

Intermediate { .md-tag }

A complete web application with HTML templates, static file serving, form handling, and database integration. Everything you need for a traditional web app.

Features used: Templates Static files Sessions Blueprints CSRF

Full Example
Microservices

Intermediate { .md-tag }

Break your application into independent services that communicate via HTTP and message queues. Includes service discovery and health checks.

Features used: gRPC Message queues Health checks Circuit breaker OpenTelemetry

Full Example
Real-time Dashboard

Intermediate { .md-tag }

Live-updating dashboard using WebSocket and Server-Sent Events. Push data to connected clients in real time with automatic reconnection.

Features used: WebSocket SSE Background tasks Prometheus metrics

Full Example
Redis Caching

Intermediate { .md-tag }

Cache expensive query results in Redis with the cache-aside pattern. Covers TTL management, cache invalidation on writes, and cache warming strategies.

Features used: Redis middleware Caching TTL cache invalidation
```
@app.get("/stats")
@cache(ttl=60, backend="redis")
async def get_stats(request):
    return await compute_heavy_stats()
```
Full Example
Background Tasks

Intermediate { .md-tag }

Offload slow work — emails, image processing, reports — to background workers. Covers task queues, retries, progress tracking, and scheduled cron jobs.

Features used: task_queue @background_task retry cron
```
@app.post("/reports")
async def generate_report(request):
    task = await queue.enqueue(build_report, request.json())
    return {"task_id": task.id, "status": "queued"}
```
Full Example
GraphQL API

Intermediate { .md-tag }

Expose a fully-typed GraphQL schema alongside your REST routes. Demonstrates queries, mutations, subscriptions, and DataLoader for N+1 query prevention.

Features used: GraphQL schema resolvers DataLoader subscriptions
```
@app.mount("/graphql")
graphql_app = GraphQL(schema, context_value=get_context)
```
Full Example
File Storage (S3-Compatible)

Intermediate { .md-tag }

Upload, download, and stream files to S3-compatible object storage. Handles multipart uploads, pre-signed URLs, and chunked streaming responses.

Features used: multipart streaming response S3 client pre-signed URLs
```
@app.post("/files")
async def upload_file(request):
    url = await storage.upload(request.files["file"])
    return {"url": url}
```
Full Example

Enterprise¶

Battle-tested patterns for large-scale production systems. These examples demonstrate how Cello handles the complexity of enterprise software.

Multi-tenant SaaS

Advanced { .md-tag }

Tenant isolation at the middleware level with per-tenant databases, RBAC, and custom domain routing. The foundation for any SaaS product.

Features used: Guards (RBAC) Middleware JWT Dependency injection Data partitioning

Full Example
API Gateway

Advanced { .md-tag }

A centralized API gateway with authentication, rate limiting, request transformation, and upstream load balancing. Control all traffic in one place.

Features used: Rate limiting JWT auth CORS Circuit breaker Prometheus Request ID tracing

Full Example
Event Sourcing

Advanced { .md-tag }

Event-driven architecture with CQRS, an append-only event store, and the Saga pattern for distributed transaction coordination.

Features used: Event store CQRS Saga pattern Background tasks Message queues

Full Example
Rate Limiting & DDoS Protection

Advanced { .md-tag }

Protect your APIs with sliding-window rate limiting, IP allowlists/blocklists, adaptive throttling, and Prometheus alerting when thresholds are breached.

Features used: Rate limiting Redis IP filtering Prometheus Circuit breaker
```
@app.middleware
class RateLimiter:
    async def __call__(self, request, next):
        if await limiter.is_limited(request.ip):
            return Response.json({"error": "Too Many Requests"}, 429)
        return await next(request)
```
Full Example
Health Checks & Observability

Advanced { .md-tag }

Production-ready /health, /ready, and /metrics endpoints. Integrates with Kubernetes liveness/readiness probes, OpenTelemetry tracing, and Grafana dashboards.

Features used: Health checks Prometheus OpenTelemetry Structured logging
```
@app.get("/health")
async def health(request):
    checks = await run_health_checks(db, redis, queue)
    status = "ok" if all(checks.values()) else "degraded"
    return {"status": status, "checks": checks}
```
Full Example

OAuth2 & Social Login

Advanced { .md-tag }

Complete OAuth2 authorization code flow with Google, GitHub, and custom providers. Covers PKCE, token refresh, session management, and account linking.

Features used: OAuth2 JWT Sessions PKCE Token refresh

@app.get("/auth/google/callback")
async def google_callback(request):
    token = await oauth.google.authorize_access_token(request)
    user = await oauth.google.parse_id_token(request, token)
    return await login_or_create(user)

Full Example

Example Architecture¶

How Cello's features layer together in a typical application.

graph LR
    A[Client Request] --> B[Middleware Pipeline]
    B --> C{Router}
    C -->|Blueprint A| D[Auth Guards]
    C -->|Blueprint B| E[Public Handler]
    D --> F[Handler + DI]
    F --> G[Response]
    E --> G
    G --> H[Middleware Pipeline]
    H --> I[Client Response]

    style A fill:#FFF3E0,stroke:#E65100,color:#BF360C
    style I fill:#FFF3E0,stroke:#E65100,color:#BF360C
    style C fill:#FFF3E0,stroke:#E65100,color:#BF360C
    style D fill:#F3E5F5,stroke:#7B1FA2,color:#4A148C

Feature Matrix¶

Which features are used in each example? Select a difficulty level:

Beginner Intermediate Enterprise

Feature	Hello World	REST API	Forms	JWT Auth	Database	Query Params
Routing	✅	✅	✅	✅	✅	✅
Blueprints		✅
Middleware		✅		✅
JWT Auth				✅
Guards / RBAC				✅
File Uploads			✅
Database					✅
Query Params						✅

Feature	Full-Stack	Microservices	Dashboard	Redis Cache	Background	GraphQL	File Storage
Routing	✅	✅	✅	✅	✅	✅	✅
Blueprints	✅	✅	✅
Middleware	✅	✅	✅	✅
JWT Auth	✅	✅
Guards / RBAC	✅
WebSocket / SSE			✅
Dependency Injection	✅	✅
Background Tasks		✅	✅		✅
Prometheus Metrics		✅	✅
Redis / Caching				✅
File Uploads	✅						✅
Database	✅	✅				✅
OAuth2 / Sessions	✅

Feature	Multi-tenant	API Gateway	Event Sourcing	Rate Limiting	Health Checks	OAuth2
Routing	✅	✅	✅	✅	✅	✅
Blueprints	✅	✅	✅			✅
Middleware	✅	✅	✅	✅	✅	✅
JWT Auth	✅	✅				✅
Guards / RBAC	✅	✅
Dependency Injection	✅		✅
Background Tasks			✅
Prometheus Metrics		✅		✅	✅
Redis / Caching				✅	✅
Circuit Breaker		✅		✅
Database	✅		✅		✅
OpenTelemetry					✅
Message Queues			✅
OAuth2 / Sessions	✅					✅

More Examples¶

Browse the full collection of examples in the GitHub repository. Contributions are welcome — see the Contributing Guide to add your own example.