Home

The speed of a velociraptor, the flexibility of Python.

A micro framework built to hunt.

VelociPy doesn't lumber through the jungle with bulked-up gear. It stays light, feathered, and alert - reading the terrain, then striking with a sickle claw when the moment is right. When the hunt calls for sharper talons, tougher hide, or a keener nose, it grows them - then sheds them when the job is done.

The result is a micro framework with a tiny core and a set of swappable adapters and optional modules. Start with nothing but the core. Add validation, OpenAPI, security, rate limiting, multipart uploads, Redis storage, and more by importing what you need. Only httpx2 is required at runtime.

Why hunt with VelociPy?¶

• Light bones, fast muscles - a radix-tree router, lightweight request/response objects, and precomputed handler plans keep the core tiny.
• Hunt on any terrain - the same app runs unchanged on ASGI (Uvicorn, Hypercorn) or RSGI (Granian).
• Swap your claws - pick your JSON encoder, model validator, and protocol independently.
• Keen senses - typed parameters for query, header, cookie, path, and body injection.
• Armor and discipline - optional security helpers, rate limiting, and request-size limits.

Quick start¶

Create main.py:

from velocipy import VelociPy

app = VelociPy()

@app.get("/")
async def hello():
    return {"message": "Hello, VelociPy!"}

Run it under the fastest terrain:

# RSGI - the open plain
granian main:app --interface rsgi --reload

# ASGI - the dense, well-trodden forest
uvicorn main:app --reload

Visit http://localhost:8000/docs for the auto-generated Swagger UI.

A hunt in one file¶

This single file shows the essentials: validation, dependencies, rate limiting, headers, and OpenAPI tags.

from typing import Annotated
from pydantic import BaseModel
from velocipy import Depends, Header, Query, VelociPy
from velocipy.limiter import (
    Limiter,
    RateLimitAlgorithm,
    RateLimitRule,
    rate_limit,
)
from velocipy.storage import MemoryStorage

app = VelociPy()
limiter = Limiter(storage=MemoryStorage())

class Item(BaseModel):
    name: str
    price: float

async def page_params(
    page: Annotated[int, Query(ge=1)] = 1,
    size: Annotated[int, Query(le=100)] = 20,
):
    return {"page": page, "size": size}

rule = RateLimitRule(
    name="items",
    limit=60,
    window=60,
    algorithm=RateLimitAlgorithm.TOKEN_BUCKET,
)

@app.get("/items", response_model=list[Item], tags=["items"])
async def list_items(
    params: Annotated[dict, Depends(page_params)],
    _: None = Depends(rate_limit(limiter, rules=[rule])),
    x_request_id: Annotated[str | None, Header()] = None,
):
    return [{"name": "hoodie", "price": 49.99}]

Test the catch in-process:

from velocipy.testing import TestClient

client = TestClient(app)
assert client.get("/items?page=1").status_code == 200

See examples/basic.py for a runnable version with lifespan events, custom OpenAPI metadata, and authentication dependencies.

The raptor at a glance¶

Choose your terrain¶

Example hunts¶

The examples/ directory has small, runnable demos. Start with the essentials, then move through common patterns and advanced integrations.

Start here¶

Common patterns¶

Advanced and integrations¶

Next steps¶

• Getting started - install VelociPy and build your first app.
• Routing - routes, parameters, and handlers.
• Requests & responses - read the request and shape the response.
• Dependencies - share logic with dependency injection.
• Uploads - multipart file uploads with UploadFile.
• Testing - test apps in-process with TestClient and AsyncTestClient.
• API Versioning - version by path, header, or Accept header.
• GraphQL - expose a Strawberry schema over HTTP and WebSocket.
• Deployment - run in production on RSGI or ASGI.