API Reference

Public API

Everything you need is importable fromchirp:

from chirp import (
    # Core
    App,
    AppConfig,

    # HTTP
    Request,
    Response,
    Redirect,

    # Template return types
    Template,
    InlineTemplate,
    Fragment,
    Page,
    Stream,
    ValidationError,
    OOB,

    # Real-time
    EventStream,
    SSEEvent,

    # Middleware types
    Middleware,
    Next,
    AnyResponse,

    # Context
    g,
    get_request,

    # Auth
    get_user,
    login,
    logout,
    login_required,
    requires,
    is_safe_url,

    # Forms
    form_from,
    form_or_errors,
    form_values,
    FormBindingError,

    # Errors
    ChirpError,
    ConfigurationError,
    HTTPError,
    MethodNotAllowed,
    NotFound,

    # Tools
    ToolCallEvent,
)

Core

App

The application class. Mutable during setup, frozen at runtime.

app = App(config=AppConfig(...))

Decorators:

Decorator	Description
`@app.route(path, methods=...)`	Register a route handler
`@app.error(code_or_type)`	Register an error handler
`@app.template_filter(name=...)`	Register a kida template filter
`@app.template_global(name=...)`	Register a kida template global
`@app.on_startup`	Register a startup callback
`@app.on_shutdown`	Register a shutdown callback
`@app.on_worker_startup`	Register a per-worker startup callback
`@app.on_worker_shutdown`	Register a per-worker shutdown callback
`@app.tool(name, description)`	Register an MCP tool

Methods:

Method	Description
`app.add_middleware(mw)`	Add middleware to the pipeline
`app.run()`	Start the development server (freezes the app)
`app.check()`	Validate hypermedia contracts

CLI

Thechirpcommand is registered as a console script:

Command	Description
`chirp new <name>`	Scaffold a new project
`chirp new <name> --minimal`	Scaffold a minimal project
`chirp run <app>`	Start the dev server (e.g.`chirp run myapp:app`)
`chirp check <app>`	Validate hypermedia contracts

The<app> argument is an import string in module:attribute format. The attribute defaults to app when omitted (e.g. chirp run myapp resolves to myapp:app).

AppConfig

Frozen dataclass for application configuration. See Configuration.

HTTP

Request

Frozen dataclass representing an incoming HTTP request.

Properties:method, path, query, headers, cookies, content_type

htmx Properties:is_fragment, htmx_target, htmx_trigger, is_history_restore

Async Methods:body(), text(), json(), form(), stream()

Response

HTTP response with chainable.with_*()API.

Methods:with_status(), with_header(), with_headers(), with_content_type(), with_cookie(), without_cookie(), with_hx_redirect(), with_hx_location(), with_hx_trigger(), with_hx_trigger_after_settle()

Redirect

Convenience for 302 redirects:Redirect(url).

Template Return Types

Type	Description
`Template(name, **ctx)`	Full template render
`Template.inline(source, **ctx)`	Render from string (prototyping)
`InlineTemplate(source, **ctx)`	String-based template (returned by`Template.inline()`)
`Fragment(name, block, **ctx)`	Named block render
`Page(name, block, **ctx)`	Auto-detect fragment vs full page
`Stream(name, **ctx)`	Progressive streaming render
`ValidationError(name, block, **ctx)`	422 fragment response
`OOB(main, *fragments)`	Out-of-band multi-fragment response

Real-Time

Type	Description
`EventStream(generator)`	Server-Sent Event stream
`SSEEvent(data, event, id, retry)`	Structured SSE event

Context

Export	Description
`g`	Request-scoped mutable namespace (ContextVar-backed)
`get_request()`	Get the current request from ContextVar

Auth

Export	Description
`get_user()`	Get the current authenticated user (or`AnonymousUser`)
`login(user)`	Regenerate session and set the authenticated user
`logout()`	Regenerate session and clear the authenticated user
`@login_required`	Decorator: require authentication
`@requires(*permissions)`	Decorator: require specific permissions
`is_safe_url(url)`	Check whether a redirect URL is safe (relative, same origin)

See Built-in Middleware for setup and usage.

Forms

Export	Description
`form_from(request, datacls)`	Bind form data to a frozen dataclass. Raises`FormBindingError`on failure.
`form_or_errors(request, datacls, template, block, ...)`	Bind or return`ValidationError`. Returns `T \| ValidationError`.
`form_values(form)`	Convert dataclass or mapping to`dict[str, str]`for template re-population.
`FormBindingError`	Raised when form binding fails.`.errors` is `dict[str, list[str]]`.

Errors

Error	Description
`ChirpError`	Base exception for all Chirp errors
`ConfigurationError`	Invalid configuration (missing secret_key, etc.)
`HTTPError`	Base for HTTP errors
`NotFound`	404 Not Found
`MethodNotAllowed`	405 Method Not Allowed

Next Steps

Errors -- Error handling in detail
Return Values -- Return type guide
Configuration -- AppConfig options