Chirp API Reference

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:…

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…

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:…

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 exception hierarchy.

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

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…

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…

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.…

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.

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…

Application configuration.

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

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…

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…

Domain protocol for pluggable feature modules.

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

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 …

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(…

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…

Browse Python API documentation by package.