A Python web framework for HTMX, HTML fragments, streaming HTML, and Server-Sent Events.
from chirp import App
app = App()
@app.route("/")
def index():
return "Hello, World!"
app.run()Chirp is a Python web framework built for the modern web platform: browser-native UI, HTML over the wire, streaming responses, and Server-Sent Events. Routes return intent — Page, Fragment, OOB, EventStream, Suspense — and the framework handles content negotiation, layout composition, and htmx awareness automatically. One template with named blocks serves as a full page, a fragment endpoint, an SSE payload, and a Suspense deferred block. No make_response(). No jsonify(). The type is the intent.
@app.route("/search")
async def search(request: Request):
results = await db.search(request.query.get("q", ""))
return Page("search.html", "results", results=results)
# Full page for browsers. Fragment for htmx. Same template, same data.- Browser-native UI —
<dialog>,popover, View Transitions, container queries. Let the browser be the framework. - HTML over the wire — Full pages, fragments, streaming HTML, and SSE. Built for htmx.
- Streaming HTML — Shell first, content fills in as data arrives. No loading spinners.
- Server-Sent Events — Real-time updates over plain HTTP. No WebSocket upgrade required.
- MCP tools — Register functions as tools callable by LLMs and MCP clients.
Read the Philosophy for the full picture.
- HTMX-driven web apps — Server-rendered UI with fragment swaps and progressive enhancement
- Server-rendered applications — Full pages plus partial updates from the same templates
- Streaming interfaces — Progressive HTML delivery and token-by-token responses
- Real-time dashboards — SSE-powered updates without WebSocket complexity
- Teams avoiding heavy frontend stacks — HTML, CSS, templates, and browser-native features
# pip
pip install bengal-chirp
# uv
uv add bengal-chirpRequires Python 3.14+.
Chirp works on its own with plain templates. chirp-ui is an optional companion UI layer, not part of the framework core.
chirp new myapp && cd myapp && python app.py| Function | Description |
|---|---|
chirp new <name> |
Scaffold an auth-ready project |
chirp new <name> --shell |
Scaffold with a persistent app shell (topbar + sidebar) |
chirp new <name> --sse |
Scaffold with SSE boilerplate (EventStream, sse_scope) |
chirp run <app> |
Start the dev server from an import string |
chirp check <app> |
Validate hypermedia contracts |
chirp check <app> --warnings-as-errors |
Fail CI on contract warnings |
chirp routes <app> |
Print the registered route table |
App() |
Create an application |
@app.route(path) |
Register a route handler |
Template(name, **ctx) |
Render a full template |
Template.inline(src, **ctx) |
Render from string (prototyping) |
Page(name, block, **ctx) |
Auto Fragment or Template based on request |
PageComposition(template, fragment_block, ...) |
Python-first composition with regions |
Fragment(name, block, **ctx) |
Render a named template block |
Stream(name, **ctx) |
Stream HTML progressively |
Suspense(name, **ctx) |
Shell first, OOB swaps for deferred data |
EventStream(gen) |
Server-Sent Events stream |
hx_redirect(url) |
Redirect helper for htmx and full-page requests |
app.run() |
Start the development server |
| Feature | Description | Docs |
|---|---|---|
| HTMX Patterns | Search, inline edit, infinite scroll, modal, and fragment workflows | htmx Patterns → |
| Comparison | When Chirp fits compared with Flask, FastAPI, and Django | When to Use Chirp → |
| Routing | Pattern matching, path params, method dispatch | Routing → |
| Filesystem routing | Route discovery from pages/ with layouts |
Filesystem → |
| Route directory contract | _meta.py, _context.py, _actions.py, sections, shell context, and route validation |
Route Directory → |
| Route introspection | Reserved files, inheritance rules, debug headers, and route explorer | Route Contract → |
| Templates | Kida integration, rendering, filters | Templates → |
| Fragments | Render named template blocks independently | Fragments → |
| Forms | form_or_errors, form macros, validation |
Forms → |
| Streaming | Progressive HTML rendering via Kida | Streaming → |
| SSE | Server-Sent Events for real-time updates | SSE → |
| Middleware | CORS, sessions, static files, security headers, custom | Middleware → |
| Contracts | Validate htmx attrs, form actions, and route-bearing dialog args | Reference → |
| Testing | Test client, assertions, isolation utilities | Testing → |
| Data | Database integration and form validation | Data → |
| Optional UI layer | chirp-ui companion components and styles |
chirp-ui → |
📚 Full documentation: lbliii.github.io/chirp
Chirp now ships a synthetic benchmark suite for comparing Chirp, FastAPI, and Flask across JSON and CPU workloads, plus Chirp-specific fused sync and mixed JSON+SSE scenarios.
uv sync --extra benchmark
uv run poe benchmarkSee benchmarks/README.md for how the benchmarks work, their caveats, and the available runners.
Chirp apps run on Pounce, a production-grade ASGI server with HTTP/2, graceful shutdown, Prometheus metrics, rate limiting, and multi-worker scaling. See the deployment guide for details.
Return Values — Type-driven content negotiation
Route functions return values. The framework handles content negotiation based on the type:
return "Hello" # -> 200, text/html
return {"users": [...]} # -> 200, application/json
return Template("page.html", title="Home") # -> 200, rendered via Kida
return Page("search.html", "results", items=x) # -> Fragment or Template (auto)
return Fragment("page.html", "results", items=x) # -> 200, rendered block
return Stream("dashboard.html", **async_ctx) # -> 200, streamed HTML
return Suspense("dashboard.html", stats=...) # -> shell + OOB swaps
return EventStream(generator()) # -> SSE stream
return hx_redirect("/dashboard") # -> Location + HX-Redirect
return Response(body=b"...", status=201) # -> explicit control
return Redirect("/login") # -> 302No make_response(). No jsonify(). The type is the intent.
For htmx-driven form posts or mutations that should trigger a full-page
navigation, prefer hx_redirect() so both plain browser and htmx requests
follow the redirect correctly.
Fragments and htmx — Render template blocks independently
Kida can render a named block from a template independently, without rendering the whole page:
{# templates/search.html #}
{% extends "base.html" %}
{% block content %}
<input type="search" hx-get="/search" hx-target="#results" name="q">
{% block results_list %}
<div id="results">
{% for item in results %}
<div class="result">{{ item.title }}</div>
{% end %}
</div>
{% endblock %}
{% endblock %}@app.route("/search")
async def search(request: Request):
results = await db.search(request.query.get("q", ""))
if request.is_fragment:
return Fragment("search.html", "results_list", results=results)
return Template("search.html", results=results)Full page request renders everything. htmx request renders just the results_list block.
Same template, same data, different scope. No separate "partials" directory.
Streaming HTML — Progressive rendering
Kida renders template sections as they complete. The browser receives the shell immediately and content fills in progressively:
@app.route("/dashboard")
async def dashboard(request: Request):
return Stream("dashboard.html",
header=site_header(),
stats=await load_stats(),
activity=await load_activity(),
)Server-Sent Events — Real-time HTML updates
Push Kida-rendered HTML fragments to the browser in real-time:
@app.route("/notifications")
async def notifications(request: Request):
async def stream():
async for event in notification_bus.subscribe(request.user):
yield Fragment("components/notification.html", event=event)
return EventStream(stream())Combined with htmx's SSE support, this enables real-time UI updates with zero client-side JavaScript. The server renders HTML, the browser swaps it in.
Middleware — Composable request/response pipeline
No base class. No inheritance. A middleware is anything that matches the protocol:
async def timing(request: Request, next: Next) -> Response:
start = time.monotonic()
response = await next(request)
elapsed = time.monotonic() - start
return response.with_header("X-Time", f"{elapsed:.3f}")
app.add_middleware(timing)Built-in middleware: CORS, StaticFiles, HTMLInject, Sessions, SecurityHeaders.
Typed Contracts — Compile-time hypermedia validation
Chirp validates the server-client boundary at startup:
# Prints a contract report and exits non-zero on errors.
app.check()
# Optional strict mode: treat warnings as failures too.
app.check(warnings_as_errors=True)Every hx-get, hx-post, and action attribute in your templates is checked against the
registered route table. Every Fragment and SSE return type is checked against available
template blocks. SSE safety checks catch broken sse-connect / sse-swap structures and
unsafe inherited target scopes before runtime.
For strict CI:
chirp check myapp:app --warnings-as-errorsgit clone https://github.com/lbliii/chirp.git
cd chirp
uv sync --group dev
pytestA structured reactive stack written in pure Python for 3.14t free-threading. Chirp is the framework; packages like chirp-ui sit on top as optional companions.
| ᓚᘏᗢ | Bengal | Static site generator | Docs |
| ∿∿ | Purr | Content runtime | — |
| ⌁⌁ | Chirp | Web framework ← You are here | Docs |
| ʘ | chirp-ui | Optional companion UI layer | — |
| =^..^= | Pounce | ASGI server | Docs |
| )彡 | Kida | Template engine | Docs |
| ฅᨐฅ | Patitas | Markdown parser | Docs |
| ⌾⌾⌾ | Rosettes | Syntax highlighter | Docs |
| ⚡ | Zoomies | QUIC / HTTP/3 | — |
Python-native. Free-threading ready. No npm required.
MIT