app

The frozenToolRegistry — available after app.run()/ freeze.

Use to inspect registered tools::

for tool_info in app.tools.list_tools():
    print(tool_info["name"])

RaisesRuntimeErrorif accessed before the app is frozen.

Setconfigon the app and mirror it into internal subsystems.

The compiler, ASGI runtime, server launcher, lifecycle coordinator, and contract checker each hold their own reference from construction. Reassigningapp.configalone leaves those stale — use this after App() when CLI helpers or extensions replace fields (e.g. debug, alpine, dev_browser_reload) before run()/freeze.

Register an OOB region for automatic layout-contract discovery.

Call during setup (before app.run()). The block_name must match a {% region <block_name>(...) %}in your layout template.

optional: When True, layouts that omit the block are allowed — the region is silently skipped at render time and the orphan-registration check downgrades to WARNING. Default False means missing blocks are ERRORs atapp.check()and render-time KeyErrors become BlockNotFoundErrorwith a clear message.

Register a fragment target for HTMX content-region block selection.

When HX-Target matches target_id (e.g.page-root), Chirp uses fragment_block instead of composition.page_block. Call during setup.

triggers_shell_update: When True (default), swapping this target triggers shell_actions OOB (topbar, breadcrumbs, sidebar). Use False for narrow content swaps (e.g. page-content-inner) that should not update the shell.

scope_name: Optional symbolic scope (e.g."site") for hierarchical OOB propagation. When set, OOB updates are scoped to this level and above.

omit_outer_layouts: When True, boosted fragment responses for this target skip wrapping with filesystem layouts (page block only). Use for root marketing shells whose outlet is the primary{% block content %} region so the layout is not nested inside itself on swap.

Register a named page shell contract and its fragment targets.

This makes app-shell expectations explicit and lets contract checks validate required fragment blocks across page templates.

Register a named preset for_layout.htmlmetadata defaults.

Layouts opt in with{# preset: name #}. Explicit comments in the template override preset defaults, letting apps encode a shell convention once and keep route-tree metadata terse.

Map a symbolic swap scope to a concrete fragment target id (no#).

Used byresolve_navigation_swap() and the swap_attrstemplate global so layouts can declare{# swap_scope: name #}and links can resolvehx-targetfrom route geometry.

Return the filesystemLayoutChainfor a GET route path, if any.

Uses the compiled router and route table built at freeze time. Unknown paths or non-filesystem routes returnNone.

Register a parameter provider forchirp freeze.

The decorated function must return a list of dicts, each mapping parameter names to values. Example::

@app.freeze_params("/docs/{slug:path}")
def docs_params():
    return [{"slug": p.slug} for p in collection.pages]

Exclude a route path fromchirp freeze.

Fragment-only or dynamic routes that should never be written as static pages can call this during setup::

app.freeze_exclude("/docs/search")

Declare a live block — a template block served dynamically from a frozen page.

At freeze time the named block is replaced in the emitted HTML with an htmx placeholder that fetches from/_frag{route}?_b={block}. At request time the block-fetch dispatcher invokes the decorated handler and returns only the named block.

route must match a registered route; blockmust be a named block in that route's template. Both are validated atapp.check()::

@app.live_block("/docs/{slug:path}", "recent_updates")
async def recent_updates(request: Request) -> Fragment:
    return Fragment("docs/page.html", "recent_updates", updates=...)

Mount a plugin at the given URL prefix.

Callsplugin.register(app, prefix)during setup phase.

Mount another ChirpApp at prefix, consuming it.

Hoists the sub-app's pending routes (prefixed), middleware, lifecycle hooks, template globals/filters, and other registrations ontoself. Parent wins on template-global / filter / error-handler / provider collisions (seechirp.app.mountfor the full merge matrix).

After this call,sub_appis consumed — calling sub_app.freeze() or sub_app.run() raises RuntimeError. Use this during migrations when you need two full apps on one port, not as a permanent composition pattern. Seedocs/rfcs/005-mount-app.md.

Register a custom contract check that runs duringapp.check().

The callable must accept(snapshot, result)where snapshot is aContractCheckSnapshotand result is a CheckResult. Append issues to result.issues.

Both plain functions and callable class instances are accepted.

Store arbitrary data for use by custom contract checks.

Data is available insnapshot.extras[key]during app.check().

Override the severity of all contract issues in category.

Applied as a post-processing step after all checks (built-in and custom) have run. For example, to promote dead-template warnings to errors::

app.override_contract_severity("dead", Severity.ERROR)

Reverse a named route to a URL path.

Path-param kwargs substitute into{braces}and are percent-encoded; any leftover kwargs become a urlencoded query string.

RaisesLookupError when nameis not registered (the message lists every known name) andKeyErrorwhen a required path param is missing. Also registered as theurl_fortemplate global.

Freeze the app and start the development server.

In debug mode, freeze runs the full hypermedia contract suite (routes, fragment targets, OOB regions, htmx attrs, SSE wiring, layouts, alpine CDN, defer_falsy, composition_extends, plus any registered custom checks) and prints a colored banner to stderr. An ERROR-severity issue exits before the server starts. Disable withAppConfig(skip_contract_checks=True)or CHIRP_SKIP_CONTRACT_CHECKS=1.

Fused sync path — bypass ASGI for simple request-response handlers.

Returns RawResponse for sync handling, or None to fall through to ASGI.

Freeze the app, finalizing all configuration.

Idempotent — safe to call multiple times. After freezing, no further routes, middleware, or plugins can be registered.

In debug mode, freeze also runs the hypermedia contract checks and exits on ERROR (same suite asapp.check()). Disable with AppConfig(skip_contract_checks=True)or the CHIRP_SKIP_CONTRACT_CHECKSenv var.

Useful in tests and CI to callapp.check()without starting a server::

app.freeze()
app.check()

Validate hypermedia contracts against the frozen app and print a report.

Runs every registered contract check (routes, fragment targets, OOB regions, htmx attributes, SSE wiring, accessibility, layout chains, plus any custom checks added viaregister_contract_check()) and writes a colored report to stdout.

Intended use: call from CI or a startup script.chirp check <app> wraps this method.

Render a Fragment, Template, or InlineTemplate to HTML without an HTTP request.

Use for tests, background jobs, scripts, or AI runtimes that need to produce HTML from the app's templates.