Requests & responses¶

A hunt succeeds because the raptor reads every sign: the scent on the wind, the snap of a twig, the shape of the terrain. VelociPy parses HTTP with the same attentiveness - query strings, headers, cookies, path segments, and body content become typed parameters you declare once and receive already parsed.

This page walks through reading request data, validating it, and returning the response shape that fits the moment.

Reading request data¶

VelociPy injects request data through Python type hints. The framework looks at each parameter and decides where it comes from:

• Path parameters come from the route.
• Query, Header, Cookie, and Form markers come from their matching request locations.
• Pydantic or msgspec models come from the JSON body.
• dict or list parameters come from the raw JSON body.
• Request parameters receive the full request object.

from typing import Annotated
from velocipy import Cookie, Header, Query, VelociPy

app = VelociPy()

@app.get("/search")
async def search(
    q: Annotated[str, Query()],
    x_request_id: Annotated[str | None, Header()] = None,
    session: Annotated[str | None, Cookie()] = None,
):
    return {"q": q, "x_request_id": x_request_id, "session": session}

The Annotated[..., Marker()] form is recommended because it keeps the type and source together. The framework coerces values to the declared type and returns 422 Unprocessable Entity when the data does not fit.

Query parameters¶

Query parameters are the easiest trail to follow. Declare them with Query(...) to make them required, or give them a default to make them optional.

from typing import Annotated, Any
from velocipy import Query, VelociPy

app = VelociPy()

@app.get("/items")
async def list_items(
    q: Annotated[str, Query(...)],
    limit: Annotated[int, Query(10)],
    offset: int = 0,
) -> dict[str, Any]:
    return {"q": q, "limit": limit, "offset": offset}

A request to /items?q=hoodie&limit=5 returns {"q": "hoodie", "limit": 5, "offset": 0}. Missing required parameters produce a 422 response.

Lists and aliases¶

Use list[T] or set[T] to accept repeated values, and alias to map a Python name to a different query key:

@app.get("/tags")
async def tags(tag: Annotated[list[str], Query(...)]) -> dict[str, list[str]]:
    return {"tags": tag}

@app.get("/search")
async def search(
    sort_by: Annotated[str, Query(..., alias="sort-by")]
) -> dict[str, str]:
    return {"sort_by": sort_by}

/tags?tag=red&tag=blue captures {"tags": ["red", "blue"]} and /search?sort-by=price binds sort_by="price".

See examples/query_params.py for more.

Headers and cookies¶

Headers and cookies work exactly like query parameters, but they read from their own parts of the request.

from typing import Annotated, Any
from velocipy import Cookie, Header, VelociPy

app = VelociPy()

@app.get("/items")
async def list_items(
    x_token: Annotated[str, Header(...)],
    user_agent: Annotated[str | None, Header(None)] = None,
) -> dict[str, Any]:
    return {"token": x_token, "user_agent": user_agent}

@app.get("/theme")
async def theme(
    session_theme: Annotated[str, Cookie(..., alias="theme")]
) -> dict[str, Any]:
    return {"theme": session_theme}

Header names are case-insensitive and underscores in parameter names are converted to hyphens automatically, so user_agent matches the User-Agent header. Use alias to override this when the real header name is unusual.

See examples/headers_cookies.py for more.

Body models¶

When the prey arrives as JSON, declare a model and VelociPy validates the body before the handler runs.

from pydantic import BaseModel
from velocipy import VelociPy

app = VelociPy()

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

@app.post("/items")
async def create_item(item: Item):
    return {"created": item}

You can use pydantic.BaseModel, msgspec.Struct, or any model type registered with the app's serialization backend. Invalid bodies return 422 with the validation errors.

See examples/model_backends.py for msgspec, pydantic, and custom adapters.

Raw JSON bodies¶

For quick endpoints or internal tooling, accept a raw dict or list and skip the model layer:

@app.post("/raw")
async def raw(payload: dict):
    return {"received": payload}

VelociPy parses the JSON body and passes the result through. This is the lightest path, but you lose validation and OpenAPI schema detail.

Accessing the request object directly¶

Sometimes you need the full request: the URL, method, headers, stream, or form data. Declare a Request parameter and VelociPy hands it over.

from velocipy import Request, VelociPy

app = VelociPy()

@app.get("/info")
async def info(request: Request):
    return {
        "method": request.method,
        "path": request.path,
        "headers": request.headers,
    }

The Request object is protocol-neutral, so the same code runs under ASGI and RSGI. Useful properties include:

For streamed or large bodies, call request.stream() as an async iterator instead of await request.body().

Response types¶

A handler can return almost anything and VelociPy will wrap it sensibly:

• dict / list → JSONResponse
• str → PlainTextResponse
• bytes → Response with application/octet-stream
• None → 204 No Content
• Response subclass → used as-is

When you need explicit control, return a response object directly.

Common response classes¶

from velocipy import VelociPy
from velocipy.http.responses import (
    HTMLResponse,
    PlainTextResponse,
    RedirectResponse,
)

app = VelociPy()

@app.get("/text")
async def text():
    return PlainTextResponse("hello")

@app.get("/html")
async def html():
    return HTMLResponse("<h1>hello</h1>")

@app.get("/redirect")
async def redirect():
    return RedirectResponse("/text")

Streaming responses¶

For responses that are too large to build in memory, stream byte chunks:

from collections.abc import AsyncIterator
from velocipy import VelociPy
from velocipy.http.responses import StreamingResponse

app = VelociPy()

async def byte_generator() -> AsyncIterator[bytes]:
    for i in range(5):
        yield f"chunk {i}\n".encode()

@app.get("/stream")
async def stream():
    return StreamingResponse(byte_generator(), media_type="text/plain")

File responses¶

Serve files from disk with FileResponse. The framework handles content delivery through the active protocol adapter:

from velocipy import FileResponse, VelociPy

app = VelociPy()

@app.get("/report.pdf")
async def report():
    return FileResponse("static/report.pdf")

See examples/responses.py for the full set.

Response metadata¶

Route decorators let you set status codes, response models, and response classes so the handler stays focused on business logic.

from velocipy import VelociPy
from velocipy.http.responses import PlainTextResponse
from velocipy.status import HTTP_201_CREATED

app = VelociPy()

@app.post("/items", status_code=HTTP_201_CREATED)
async def create_item():
    return {"id": 1}

@app.get("/text", response_class=PlainTextResponse)
async def text():
    return "plain text"

At a glance¶

Related examples¶