Korvex

A fast router for Python, written in Rust, with an optional ASGI app on top.

pip install korvex

The router

Router maps a path and an HTTP method to a handler name. It never calls your code: what you do with the name is up to you.

from korvex import Router

router = Router()
router.get("/users/{id:int}", "get_user")
router.post("/users", "create_user", middleware=["auth"])

router.match("/users/42")         # ("get_user", {"id": "42"}, [])
router.match("/users", "POST")    # ("create_user", {}, ["auth"])
router.match("/nope")             # None
router.match("/users", "DELETE")  # raises MethodNotAllowed, .allowed == ["POST"]

Path syntax

Captured values are always strings. When several routes could match, the most specific one wins: literal, then {id:int}/{id:uuid}, then {id}, then *path.

API

Invalid paths or methods raise ValueError.

Route groups

api = router.group("/api", middleware=["auth"])
api.get("/users", "list_users")             # GET /api/users, middleware ["auth"]

admin = api.group("/admin", middleware=["admin"])
admin.get("/stats", "stats")                # GET /api/admin/stats, middleware ["auth", "admin"]

The ASGI app

App runs the matched handler for you. Serve it with any ASGI server (uvicorn, hypercorn, granian...).

from korvex import App, Response

app = App()

@app.get("/users/{id:int}", middleware=["auth"])
async def get_user(request, id):
    return Response.json({"id": id})

@app.middleware("auth")
def auth(request):
    if request.headers.get("Authorization") is None:
        return Response.text("Unauthorized", status=401)  # stops here
    return None                                          # carries on

pip install "korvex[serve]"   # installs uvicorn
uvicorn mymodule:app

• Handlers receive the Request plus path params as keyword arguments, and return a Response. Middleware returns a Response to answer early, or None to continue. Both can be sync or async.
• Request has method, path, headers, query_params, path_params, and await request.body() / await request.json().
• Response(body, status=, headers=), Response.text(...), Response.json(...), Response.redirect(...).
• Unknown paths get a 404; known paths with the wrong method get a 405 with an Allow header.
• Routes registered on app.router directly (for example through a group) are linked to a function with @app.handler("name").

More in examples/.

Performance

Median time per lookup, 10,000 routes:

• Korvex does the actual matching fastest, and its time stays flat as routes are added. Django and Starlette try routes one by one, so they slow down linearly.
• Litestar and Sanic cache the last 1,024 lookups. When the same URLs come back, that cache beats Korvex. It helps less with parameters (/users/1, /users/2, ... are all different URLs).
• This measures routing only. In a full app, the handler and the ASGI server cost more than the router.

Reproduce with uv run pytest benches/bench_router.py --benchmark-only --benchmark-json=benches/results.json, then uv run python benches/plot.py to redraw the chart. Results depend on the machine: measure your own workload before relying on any number.

Development

uv run maturin develop --release   # build the Rust extension
uv run pytest                      # Python tests
cargo test                         # Rust tests

See CONTRIBUTING.md.

License

MIT