Module

app

Chirp application facade.

1Class

Classes

App 29 ▼
The chirp application. Mutable during setup (route registration, middleware, filters). Frozen at r…

The chirp application.

Mutable during setup (route registration, middleware, filters). Frozen at runtime whenapp.run() or __call__()is first invoked.

Methods

db 0 Database ▼
property
def db(self) -> Database
Returns
Database
tool_events 0 ▼
property
def tool_events(self)
bind_config 1 ▼
Set ``config`` on the app and mirror it into internal subsystems. The compiler…
def bind_config(self, config: AppConfig) -> None

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.

Parameters
Name Type Description
config —
route 6 Callable[[Callable[..., … ▼
def route(self, path: str, *, methods: list[str] | None = None, name: str | None = None, referenced: bool = False, template: str | None = None, inline: bool = False) -> Callable[[Callable[..., Any]], Callable[..., Any]]
Parameters
Name Type Description
path —
methods — Default:None
name — Default:None
referenced — Default:False
template — Default:None
inline — Default:False
Returns
Callable[[Callable[..., Any]], Callable[..., Any]]
provide 2 ▼
def provide(self, annotation: type, factory: Callable[..., Any]) -> None
Parameters
Name Type Description
annotation —
factory —
mount_pages 1 ▼
def mount_pages(self, pages_dir: str | None = None) -> None
Parameters
Name Type Description
pages_dir — Default:None
register_domain 1 ▼
def register_domain(self, domain: object) -> None
Parameters
Name Type Description
domain —
tool 2 Callable[[Callable[..., … ▼
def tool(self, name: str, *, description: str = '') -> Callable[[Callable[..., Any]], Callable[..., Any]]
Parameters
Name Type Description
name —
description — Default:''
Returns
Callable[[Callable[..., Any]], Callable[..., Any]]
error 1 Callable[[Callable[..., … ▼
def error(self, code_or_exception: int | type[Exception]) -> Callable[[Callable[..., Any]], Callable[..., Any]]
Parameters
Name Type Description
code_or_exception —
Returns
Callable[[Callable[..., Any]], Callable[..., Any]]
register_oob_region 4 ▼
Register an OOB region for automatic layout-contract discovery. Call during se…
def register_oob_region(self, block_name: str, *, target_id: str, swap: str = 'innerHTML', wrap: bool = True) -> None

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.

Parameters
Name Type Description
block_name —
target_id —
swap — Default:'innerHTML'
wrap — Default:True
register_fragment_target 3 ▼
Register a fragment target for HTMX content-region block selection. When HX-Ta…
def register_fragment_target(self, target_id: str, *, fragment_block: str, triggers_shell_update: bool = True) -> None

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.

Parameters
Name Type Description
target_id —
fragment_block —
triggers_shell_update — Default:True
register_page_shell_contract 1 ▼
Register a named page shell contract and its fragment targets. This makes app-…
def register_page_shell_contract(self, contract: PageShellContract) -> None

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.

Parameters
Name Type Description
contract —
mount 2 ▼
Mount a plugin at the given URL prefix. Calls ``plugin.register(app, prefix)``…
def mount(self, prefix: str, plugin: object) -> None

Mount a plugin at the given URL prefix.

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

Parameters
Name Type Description
prefix —
plugin —
add_loader 1 ▼
Add a template loader (e.g., from a plugin's PackageLoader).
def add_loader(self, loader: object) -> None
Parameters
Name Type Description
loader —
add_middleware 1 ▼
def add_middleware(self, middleware: object) -> None
Parameters
Name Type Description
middleware —
add_reload_dir 1 ▼
def add_reload_dir(self, path: str) -> None
Parameters
Name Type Description
path —
register_section 1 ▼
Register a named section for route metadata resolution.
def register_section(self, section: Section) -> None
Parameters
Name Type Description
section —
template_filter 1 Callable[[Callable[..., … ▼
def template_filter(self, name: str | None = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]
Parameters
Name Type Description
name — Default:None
Returns
Callable[[Callable[..., Any]], Callable[..., Any]]
template_global 1 Callable[[Callable[..., … ▼
def template_global(self, name: str | None = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]
Parameters
Name Type Description
name — Default:None
Returns
Callable[[Callable[..., Any]], Callable[..., Any]]
on_startup 1 Callable[..., Any] ▼
def on_startup(self, func: Callable[..., Any]) -> Callable[..., Any]
Parameters
Name Type Description
func —
Returns
Callable[..., Any]
on_shutdown 1 Callable[..., Any] ▼
def on_shutdown(self, func: Callable[..., Any]) -> Callable[..., Any]
Parameters
Name Type Description
func —
Returns
Callable[..., Any]
on_worker_startup 1 Callable[..., Any] ▼
def on_worker_startup(self, func: Callable[..., Any]) -> Callable[..., Any]
Parameters
Name Type Description
func —
Returns
Callable[..., Any]
on_worker_shutdown 1 Callable[..., Any] ▼
def on_worker_shutdown(self, func: Callable[..., Any]) -> Callable[..., Any]
Parameters
Name Type Description
func —
Returns
Callable[..., Any]
run 3 ▼
def run(self, host: str | None = None, port: int | None = None, *, lifecycle_collector: LifecycleCollector | None = None) -> None
Parameters
Name Type Description
host — Default:None
port — Default:None
lifecycle_collector — Default:None
handle_sync 1 object | None ▼
Fused sync path — bypass ASGI for simple request-response handlers. Returns Ra…
def handle_sync(self, raw: object) -> object | None

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

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

Parameters
Name Type Description
raw —
Returns
object | None
check 1 ▼
def check(self, *, warnings_as_errors: bool = False) -> None
Parameters
Name Type Description
warnings_as_errors — Default:False
render 1 str ▼
Render a Fragment, Template, or InlineTemplate to HTML without an HTTP request.…
def render(self, value: Fragment | Template | InlineTemplate) -> str

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.

Parameters
Name Type Description
value —
Returns
str
Internal Methods 2 ▼
__init__ 4 ▼
def __init__(self, config: AppConfig | None = None, *, db: Database | str | None = None, migrations: str | None = None, kida_env: Environment | None = None) -> None
Parameters
Name Type Description
config — Default:None
db — Default:None
migrations — Default:None
kida_env — Default:None
__call__ 3 ▼
async
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None
Parameters
Name Type Description
scope —
receive —
send —