The App¶

App is the application: routes, hooks, errors, OpenAPI, and run() for the built-in server. app.group() and app.host() return a Group. The guide shows how they fit together; this page lists every method and option.

App ¶

App()

The application: routes, hooks, error handlers, OpenAPI, and run(). It is an ASGI app.

Guide: https://3d3n-pyc.github.io/korvex/routes/

local `instance-attribute` ¶

local = LoopLocal()

Attributes per event loop: see LoopLocal.

dependency_overrides `instance-attribute` ¶

dependency_overrides: dict[Callable[..., Any], Callable[..., Any]] = {}

{dependency: replacement}: called instead of the dependency, for tests.

get ¶

get(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers GET path, with the options of App.route().

post ¶

post(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers POST path, with the options of App.route().

put ¶

put(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers PUT path, with the options of App.route().

patch ¶

patch(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers PATCH path, with the options of App.route().

delete ¶

delete(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers DELETE path, with the options of App.route().

head ¶

head(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers HEAD path, with the options of App.route().

options ¶

options(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers OPTIONS path, with the options of App.route().

route ¶

route(path: str, *, method: str = 'GET', name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers path for method. @app.get(path) and the others take the same options.

name: what url_for() knows the route by (the function's name by default).
status: the status of a response made from a model or None (-> None with 204: empty).
dependencies: [Depends(func), ...], run before the handler.
tags, deprecated, responses, include_in_schema: the route's OpenAPI entry.
max_body (bytes): the built-in server's body limit for this route; ASGI servers ignore it.

Guide: https://3d3n-pyc.github.io/korvex/routes/#route-options

group ¶

group(prefix: str = '', *, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True) -> Group

Returns a Group that registers handlers under prefix, with dependencies and OpenAPI options for all.

Guide: https://3d3n-pyc.github.io/korvex/routes/#groups

host ¶

host(pattern: str, *, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True) -> Group

Returns a group whose routes only answer for requests to pattern, a host ({param} takes one label).

Calling it again with the same pattern adds to the same routes; a route's max_body applies to its path on every host. Guide: https://3d3n-pyc.github.io/korvex/routes/#hosts

websocket ¶

websocket(path: str, *, name: str | None = None, dependencies: Sequence[Any] = ()) -> Callable[[WebSocketHandler], WebSocketHandler]

Decorator: registers the function as the WebSocket handler for path.

It gets a WebSocket, path params, and parameters and dependencies as HTTP handlers do (no body). name: for url_for(). Guide: https://3d3n-pyc.github.io/korvex/websockets/

url_for ¶

url_for(name: str, /, **params: Any) -> str

The path of the route named name, with params for its path parameters.

Raises LookupError if several routes share a function's name (give a name=; routes share a name= only on one path, for different methods). Raises ValueError for a value that doesn't fit its constraint or the handler's annotation, is empty, . or .., or has a / outside a *wildcard, or when another route answers the path first (TypeError for an unsupported type). Every path parameter must be given, and nothing else: add a query string yourself. Values are percent-encoded; a host route gives the path only. An app is served under one root_path: it prefixes the path. Guide: https://3d3n-pyc.github.io/korvex/routes/#links-to-a-route

openapi ¶

openapi(*, title: str = 'API', version: str = '0.1.0', description: str | None = None, host: str | None = None) -> dict

An OpenAPI 3.1 description of the app's routes (static files and WebSockets left out).

With host, the routes that answer there; without, only those with no host. Guide: https://3d3n-pyc.github.io/korvex/openapi/

docs ¶

docs(*, title: str = 'API', version: str = '0.1.0', description: str | None = None, openapi_path: str = '/openapi.json', docs_path: str | None = '/docs') -> None

Serves the OpenAPI document at openapi_path and Swagger UI at docs_path (None: none).

title, version and description go in the document. Guide: https://3d3n-pyc.github.io/korvex/openapi/

constraint ¶

constraint(name: str, pattern: str) -> None

Defines a route constraint {param:name}, matching the whole value against pattern.

Rust regex syntax. Constrained parameters are tried in registration order, before plain ones; the handler gets a str. Define it before the routes that use it; it can't be redefined differently. Guide: https://3d3n-pyc.github.io/korvex/routes/#your-own-constraints

static ¶

static(prefix: str, directory: str | PathLike[str], *, name: str | None = None) -> None

Serves the files in directory under prefix; paths leaving it get a 404.

name ("static" by default) is what url_for() knows it by. Guide: https://3d3n-pyc.github.io/korvex/routes/#static-files

mount ¶

mount(prefix: str, asgi_app: Callable, *, name: str | None = None) -> None

Serves another ASGI app (a Starlette app, a Korvex App...) under prefix.

The app sees paths without prefix (its root_path has it). A route of this app that matches wins. This app's before hooks run first (they protect the mount); its after hooks and exception handlers don't run for the mount. The mounted app's lifespan runs with this app's startup and shutdown. The bare prefix redirects (308) to prefix/. name: url_for(name) gives prefix/, url_for(name, path="a/b") gives prefix/a/b. Raises ValueError for an invalid or already mounted prefix. Guide: https://3d3n-pyc.github.io/korvex/routes/#mounting-another-app

static_url ¶

static_url(path: str, /, *, name: str | None = None) -> str

The URL of a static file, with a hash of its content: /static/app.3f2a1c9b.css.

path: the file, relative to the folder given to static(). name: which static() mount, when there are several ("static" by default). Raises LookupError for an unknown mount, FileNotFoundError for a missing file. An app is served under one root_path: it prefixes the URL. Guide: https://3d3n-pyc.github.io/korvex/templates/

templates ¶

templates(directory: str | PathLike[str] = 'templates', *, reload: bool = False) -> Templates

Returns the Templates for directory, with url_for, static_url and get_flashed_messages available in every template.

directory: the template folder, relative to the current directory. reload: recompile templates when their files change. Guide: https://3d3n-pyc.github.io/korvex/templates/

on_startup ¶

on_startup(func: Hook) -> Hook

on_startup(func: None = None) -> Callable[[Hook], Hook]

on_startup(func: Hook | None = None) -> Hook | Callable[[Hook], Hook]

Decorator: runs the function at server start; if it raises, the server doesn't start.

Guide: https://3d3n-pyc.github.io/korvex/errors-and-hooks/#startup-and-shutdown

on_shutdown ¶

on_shutdown(func: Hook) -> Hook

on_shutdown(func: None = None) -> Callable[[Hook], Hook]

on_shutdown(func: Hook | None = None) -> Hook | Callable[[Hook], Hook]

Decorator: runs the function at server stop, in reverse order of declaration.

Guide: https://3d3n-pyc.github.io/korvex/errors-and-hooks/#startup-and-shutdown

before_request ¶

before_request(func: BeforeHook) -> BeforeHook

before_request(func: None = None) -> Callable[[BeforeHook], BeforeHook]

before_request(func: BeforeHook | None = None) -> BeforeHook | Callable[[BeforeHook], BeforeHook]

Decorator: runs the function before routing, so also for unknown paths and handshakes.

It gets the request (path_params empty) and returns a Response to answer, or None. For a WebSocket handshake, answering or raising HTTPException or Abort refuses it. Guide: https://3d3n-pyc.github.io/korvex/errors-and-hooks/#hooks-around-every-request

after_request ¶

after_request(func: AfterHook) -> AfterHook

after_request(func: None = None) -> Callable[[AfterHook], AfterHook]

after_request(func: AfterHook | None = None) -> AfterHook | Callable[[AfterHook], AfterHook]

Decorator: runs the function on every response, errors included, in reverse order.

It returns the response to send, or None to keep it. Guide: https://3d3n-pyc.github.io/korvex/errors-and-hooks/#hooks-around-every-request

exception_handler ¶

exception_handler(key: int | type[Exception]) -> Callable[[ExceptionHandler], ExceptionHandler]

Decorator: answers errors with the function's Response.

key: an HTTP status (404 also covers unknown paths) or an exception class.

Guide: https://3d3n-pyc.github.io/korvex/errors-and-hooks/#answering-errors-your-way

run ¶

run(host: str = '127.0.0.1', port: int = 8000, *, workers: int = 1, graceful_timeout: float = 30.0, max_body: int = 1024 * 1024, read_timeout: float = 30.0, uds: str | None = None, forwarded_allow_ips: Sequence[str] = ('127.0.0.1', '::1'), access_log: bool = False, ws_ping_interval: float = 20.0, forwarded_host: bool = False, threads: int = 1, max_connections: int = 0, max_requests: int = 0, root_path: str = '') -> None

Serves the app with the built-in server until Ctrl+C or SIGTERM (Linux and macOS only).

workers: processes sharing the port, each running the startup and shutdown hooks.
threads: event loops per worker; keep what they open in app.local.
graceful_timeout: seconds requests in progress get on stop.
max_body: bytes; larger bodies get a 413 (a route's max_body overrides it).
read_timeout: seconds a client gets to send headers, then body (408).
uds: a Unix socket path to listen on instead of host:port.
forwarded_allow_ips: proxies trusted for X-Forwarded-For/-Proto ("*": any).
forwarded_host: also take the forwarded host, only if your proxy sets it itself.
access_log: log each request to korvex.access.
ws_ping_interval: seconds between WebSocket pings; 0 turns them off.
max_connections: open connections per worker and thread; 0: no limit.
max_requests: a worker restarts after about that many requests; 0: never.
root_path: the prefix a proxy serves the app under ("/api"), for links.

Guide: https://3d3n-pyc.github.io/korvex/server/

Group ¶

Group(app: App, routes: RouteGroup, dependencies: Sequence[Any] = (), host: _Host | None = None, docs: _Docs | None = None)

Registers routes under a shared prefix, dependencies and OpenAPI options.

Guide: https://3d3n-pyc.github.io/korvex/routes/#groups

get ¶

get(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers GET path, with the options of App.route().

post ¶

post(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers POST path, with the options of App.route().

put ¶

put(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers PUT path, with the options of App.route().

patch ¶

patch(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers PATCH path, with the options of App.route().

delete ¶

delete(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers DELETE path, with the options of App.route().

head ¶

head(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers HEAD path, with the options of App.route().

options ¶

options(path: str, *, name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: the function answers OPTIONS path, with the options of App.route().

route ¶

route(path: str, *, method: str = 'GET', name: str | None = None, status: int = 200, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True, max_body: int | None = None) -> Callable[[Handler], Handler]

Decorator: registers the handler for path under the group's prefix.

Guide: https://3d3n-pyc.github.io/korvex/routes/#route-options

websocket ¶

websocket(path: str, *, name: str | None = None, dependencies: Sequence[Any] = ()) -> Callable[[WebSocketHandler], WebSocketHandler]

Decorator: registers the WebSocket handler for path under the group's prefix.

Guide: https://3d3n-pyc.github.io/korvex/websockets/

group ¶

group(prefix: str = '', *, dependencies: Sequence[Any] = (), tags: Sequence[str] = (), deprecated: bool = False, responses: Mapping[int | str, Any] | None = None, include_in_schema: bool = True) -> Group

Returns a nested group, adding its prefix, dependencies and OpenAPI options.

LoopLocal ¶

LoopLocal()

Attributes kept per event loop: app.local, for what a startup hook opens (a pool, a client).

Use it from a running loop only. Guide: https://3d3n-pyc.github.io/korvex/server/#threads

The App¶

App ¶

local instance-attribute ¶

dependency_overrides instance-attribute ¶

get ¶

post ¶

put ¶

patch ¶

delete ¶

head ¶

options ¶

route ¶

group ¶

host ¶

websocket ¶

url_for ¶

openapi ¶

docs ¶

constraint ¶

static ¶

mount ¶

static_url ¶

templates ¶

on_startup ¶

on_shutdown ¶

before_request ¶

after_request ¶

exception_handler ¶

run ¶

Group ¶

get ¶

post ¶

put ¶

patch ¶

delete ¶

head ¶

options ¶

route ¶

websocket ¶

group ¶

LoopLocal ¶

local `instance-attribute` ¶

dependency_overrides `instance-attribute` ¶