Chirp API Reference

Typed extraction of query parameters and form/JSON body data.

Automatically populates frozen dataclass instances from request data, converting string values to the annotated field types. Used by the…

Chirp — A Python web framework for the modern web platform.

Serves HTML beautifully: full pages, fragments, streams, and real-time events. Built for Python 3.14t with free-threading support.…

Chirp exception hierarchy.

Shared across Router, App, handler, and middleware so every module raises and catches the same types.

Plugin protocol — structural typing for reusable Chirp plugins.

A plugin is any object with aregister(app, prefix)method. No base class required.

Usage (plugin author)::

class BlogPlugin:…

Health probes for Kubernetes and load balancers.

Provides liveness and readiness endpoints for container orchestration.

Chirp auto-mounts/health (liveness) and /ready(readiness) at the paths inAppConfig(…

Application configuration.

AppConfig is a frozen dataclass — immutable after creation, IDE-autocompletable, no string-key dict lookups.

Shared source protocols and types.

A source is anything that produces typed data — a database, an LLM, a file watcher, a message queue. Sources have two modes:…

Structured logging with request correlation.

Provides request_id propagation via ContextVar and a structured_log helper for JSON-formatted logs with request_id, user_id, path, etc.

WhenAppConfig.log_format == "json"the framework…

Shell action constants — shared by pages and templating without circular deps.

For all documented shell region element ids (including this target), see chirp.shell_regions.

Stable DOM ids for Chirp shell regions (HTMX OOB targets).

Shell regions live outside#page-content. They are updated via hx-swap-oobduring fragment navigations, not by the primary …

Resilience patterns for external dependencies.

Documents recommended patterns for timeouts, retries, and circuit breakers when calling external services. Chirp does not bundle a circuit breaker; usetenacityor…

Domain protocol for pluggable feature modules.

Domains register routes, middleware, and other app extensions on first access.

Freeze — render routes to static HTML files.

Walks the app's route table after freeze, renders each freezable URL through the full ASGI middleware stack via TestClient, and…

Live-block declarations for hybrid static/dynamic freeze output.

A live blockis a named template block on a frozen page that is swapped out at freeze time for an…

Request-scoped context via ContextVar.

Provides:

• request_var: The current Requestfor this task/thread.
• g: A mutable namespace scoped to the current request.

Both are set by the…

Best-effort OpenTelemetry spans for Chirp internals.

Chirp has no hard dependency onopentelemetry— OTel is configured through Pounce viaAppConfig.otel_endpoint. These helpers no-op when the SDK…

Experimental declarative WebMCP form projection.

This module implements only the attribute vocabulary from the WebMCP declarative proposal pinned by RFC 014. It does not register imperative browser tools…

Browse Python API documentation by package.