Metadata-Version: 2.4
Name: cello-framework
Version: 1.1.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Framework :: AsyncIO
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0 ; extra == 'dev'
Requires-Dist: requests>=2.28 ; extra == 'dev'
Requires-Dist: websockets>=11.0 ; extra == 'dev'
Requires-Dist: aiohttp>=3.8 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Ultra-fast Rust-powered Python async web framework
Keywords: web,framework,async,rust,fast,http,websocket
Author: Jagadeesh Katla
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://cello-framework.vercel.app/
Project-URL: Homepage, https://github.com/jagadeesh32/cello
Project-URL: Repository, https://github.com/jagadeesh32/cello

<p align="center">
  <img src="https://cello-framework.vercel.app/logo-full.png" alt="Cello" width="400">
</p>

<p align="center">
  <strong>Ultra-Fast Python Web Framework</strong><br>
  <em>Rust-powered performance with Python simplicity</em>
</p>

<p align="center">
  <a href="https://github.com/jagadeesh32/cello/actions/workflows/ci.yml"><img src="https://github.com/jagadeesh32/cello/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/cello-framework/"><img src="https://img.shields.io/pypi/v/cello-framework.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/cello-framework/"><img src="https://img.shields.io/pypi/pyversions/cello-framework.svg" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
</p>

<p align="center">
  <a href="#-installation">Installation</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-features">Features</a> •
  <a href="#-examples">Examples</a> •
  <a href="https://cello-framework.vercel.app/">Documentation</a>
</p>

---

## 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 is the **fastest Python web framework** — benchmarked with `wrk` on the same machine, same worker count, same settings.

### Benchmark Results (4 workers, 5 processes each, wrk -t12 -c400 -d10s)

| Framework | Server | Req/sec | Avg Latency | p99 Latency | Relative |
|-----------|--------|---------|-------------|-------------|----------|
| **Cello** | **Built-in (Rust/Tokio)** | **170,000+** | **2.76ms** | **15.34ms** | **1.0x (fastest)** |
| BlackSheep + Granian | Granian (Rust) | ~92,000 | 4.31ms | 12.63ms | 1.9x slower |
| FastAPI + Granian | Granian (Rust) | ~55,000 | 7.14ms | 16.86ms | 3.1x slower |
| Robyn | Built-in (Rust) | ~29,000 | 14.21ms | 37.91ms | 5.9x slower |

> **How to reproduce**: See [`benchmarks/compare/`](benchmarks/compare/) for the automated comparison runner. All frameworks use the same JSON endpoint, same process count, and same `wrk` settings for a fair comparison.

---

## 📦 Installation

```bash
pip install cello-framework
```

**From source:**
```bash
git clone https://github.com/jagadeesh32/cello.git
cd cello
pip install maturin
maturin develop
```

**Requirements:** Python 3.12+

---

## 🚀 Quick Start

```python
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()
```

```bash
python app.py
# 🐍 Cello v1.0.1 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** | Flask-like route grouping and modular apps |
| 🌐 **WebSocket** | Real-time bidirectional communication |
| 📡 **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 |

### 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 decorators with Schema builder |
| 📊 **DataLoader** | N+1 prevention with automatic batching and caching |
| 🔌 **gRPC** | Service-based gRPC with unary, streaming, and bidirectional support |
| 📨 **Kafka** | Consumer/producer decorators with automatic message routing |
| 🐰 **RabbitMQ** | AMQP messaging with topic exchanges and prefetch control |
| ☁️ **SQS/SNS** | AWS message queue integration with LocalStack support |

### Protocol Support

| Feature | Description |
|---------|-------------|
| 🔒 **TLS/SSL** | Native HTTPS with rustls |
| ⚡ **HTTP/2** | Multiplexed connections with h2 |
| 🚀 **HTTP/3** | QUIC protocol support with quinn |
| 🏭 **Cluster Mode** | Multi-worker process deployment |

---

## 📘 Examples

### Data Layer Features (v0.8.0)

```python
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.0.1"}

app.run()
```

### API Protocol Features (v0.9.0)

```python
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.0.1", "protocols": ["graphql", "grpc", "kafka", "rabbitmq"]}

app.run()
```

### Enterprise Features (v0.7.0+)

```python
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.0.1"}

app.run()
```

### Blueprints (Route Grouping)

```python
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)

```python
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

```python
@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

```python
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)

```python
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:
```html
<!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:
```html
{% 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 %}
```

### Response Types

```python
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** | Kafka, RabbitMQ, SQS adapters |
| **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

```bash
# 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.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 (fastest Python web framework)
- 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-framework.vercel.app](https://cello-framework.vercel.app/)**

- 📖 [Getting Started](https://cello-framework.vercel.app/getting-started/)
- ✨ [Features](https://cello-framework.vercel.app/features/)
- 📘 [API Reference](https://cello-framework.vercel.app/reference/)
- 🏢 [Enterprise Guide](https://cello-framework.vercel.app/enterprise/)
- 📝 [Examples](https://cello-framework.vercel.app/examples/)

---

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📄 License

MIT License - see [LICENSE](LICENSE)

---

## 👤 Author

**Jagadeesh Katla** - [@jagadeesh32](https://github.com/jagadeesh32)

---

<p align="center">
  Made with ❤️ using 🐍 Python and 🦀 Rust
</p>

