High-performance web framework for Granian RSGI, tuned for high single-worker throughput: routing, JSON/form parsing, JWT checks, response mapping, and native WebSockets run on a Rust hot path (PyO3 + Maturin), while business logic stays in plain Python handlers.
- RSGI entrypoint (
async def __rsgi__(scope, protocol)) compatible with Granian’s RSGI implementation - Routing via matchit (path parameters like
/users/:id) - JSON, form, and multipart bodies parsed on the native path; successful values passed to handlers as kwargs
- JWT verification on the Rust path before your handler runs (
require_jwt, HS*, RSA, EC, EdDSA public-key verification) - Optional
GET /openapi.jsonwith a minimal OpenAPI-style document - Dependencies: linear list of named factories (
Depends, sync or async) passed as kwargs - Optional middleware layers for pre-route decisions, CORS, CSRF, and browser security headers
- Native RSGI WebSockets via
@app.websocket(path)andoxyroute.WebSocket - Native extension wheel (abi3) for Python ≥ 3.10
Start with the full Usage guide, or use docs/index.md for topic-specific pages.
- Python 3.10 or newer
- For running a pre-built wheel: only
pip(and a server such as Granian) - For building from source: Rust toolchain + maturin (and
patchelfon some Linux setups is recommended for best wheel layout; see docs/installation.md)
From PyPI (when published):
pip install oxyrouteDevelopment / optional test dependencies:
pip install "oxyroute[dev]"From a git checkout (builds the native module):
pip install maturin
maturin develop
# or: pip install .examples/rsgi_app.py:
from oxyroute import App
app = App(title="Hello OxyRoute")
@app.get("/")
def root() -> str:
return "OxyRoute RSGI OK"
@app.get("/hello/:name")
def hello_name(name: str) -> dict:
return {"message": f"Hello, {name}"}Run (from the repo, after maturin develop or an editable install):
granian --interface rsgi examples.rsgi_app:appPer-worker setup (__rsgi_init__) is shown in examples/rsgi_lifespan_app.py and docs/rsgi.md.
OxyRoute v0.3.0 supports only Granian RSGI; the legacy ASGI bridge (uvicorn / granian --interface asgi) was removed.
- Usage guide — install, run, routing, bodies, responses, middleware, CORS, CSRF, JWT, WebSockets, deployment notes, limitations
- RSGI and Granian — app entrypoint, lifespan hooks, worker process model
- Handlers — injected parameters and response mapping details
- Routing — methods, path syntax,
APIRouter,freeze() - JWT, CORS, CSRF, Security headers
- WebSockets and SSE
OxyRoute is designed for Granian RSGI deployments. For public traffic, place it behind a normal production boundary (TLS, request-size limits, timeouts, logging, process supervision) and keep OXYROUTE_DEBUG disabled. Request bodies and multipart files are currently buffered in memory before parsing, so enforce limits both at the edge and with OXYROUTE_MAX_BODY_BYTES.
oxyroute/— Python package (App,Depends)src/— Rust extension (_oxyroute, routing, dispatch, JWT helpers)docs/— detailed English documentationtests/— pytest suite (run from a temp directory or an installed wheel so the source tree does not shadow the package; see docs/development.md)
See CONTRIBUTING.md (build, tests, issue backlog, batch gh script).
This project is licensed under the MIT License.