app

The database instance, if configured.

RaisesRuntimeErrorif no database was configured on this app.

Usage::

app = App(db="sqlite:///app.db")

@app.route("/users")
async def users():
    return await app.db.fetch(User, "SELECT * FROM users")

Public access to the tool event bus for SSE subscriptions.

Usage::

@app.route("/dashboard/feed")
async def feed(request: Request):
    async def stream():
        async for event in app.tool_events.subscribe():
            yield Fragment("dashboard.html", "row", event=event)
    return EventStream(stream())

Register a provider factory for dependency injection.

When a handler parameter's type annotation matches annotation, chirp calls factory (with no arguments) and injects the result.

Works for both@app.routeand filesystem page handlers::

app.provide(DocumentStore, get_store)

# Any handler with ``store: DocumentStore`` gets it injected:
def get(store: DocumentStore) -> Page: ...

Mount a filesystem-based pages directory.

Walks the directory and registers routes for everypage.py and handler.pyfile, with automatic layout nesting and context cascade.

_layout.html files define shells with {% block content %} and{# target: element_id #}declarations. _context.pyfiles provide shared context that cascades from parent directories to children.

Register a function as an MCP tool via decorator.

The tool is callable by MCP clients via JSON-RPC at/mcp and can also be called directly from route handlers as a normal Python function.

Tool calls emitToolCallEvent to app.tool_events for real-time dashboard subscriptions.

Usage::

@app.tool("search", description="Search inventory")
async def search(query: str, category: str | None = None) -> list[dict]:
    return await db.search(query, category=category)

Register an async or sync startup hook via decorator.

Hooks run in registration order during ASGI lifespan startup, before the server begins accepting HTTP requests.

Usage::

@app.on_startup
async def setup():
    await db.connect()

Register an async or sync shutdown hook via decorator.

Hooks run in registration order during ASGI lifespan shutdown, after the server stops accepting new requests.

Usage::

@app.on_shutdown
async def teardown():
    await db.disconnect()

Register a per-worker startup hook via decorator.

Unlikeon_startup(which runs once during ASGI lifespan), this hook runs on each worker's event loop before that worker begins accepting connections. Use this for async resources that bind to the event loop (httpx clients, DB connection pools, etc.).

Requires a server that sendspounce.worker.startupscopes (e.g. pounce). Under other servers, the hooks simply never fire.

Usage::

@app.on_worker_startup
async def create_client():
    _client_var.set(httpx.AsyncClient(...))

Register a per-worker shutdown hook via decorator.

Runs on each worker's event loop after that worker stops accepting connections. Pair withon_worker_startupfor per-worker resource cleanup.

Usage::

@app.on_worker_shutdown
async def close_client():
    client = _client_var.get(None)
    if client:
        await client.aclose()

Start the development server via pounce.

Compiles the app (freezing routes, middleware, templates) and starts serving requests with auto-reload enabled.

Validate the hypermedia surface and print results.

Freezes the app if needed, then checks that every htmx target, form action, and fragment contract resolves to a valid route. RaisesSystemExit(1)if errors are found.

Usage::

app.check()  # prints results and exits on errors