Wreath

Many separate parts, gathered and woven until they hold a single shape.

A Python 3.14-first ASGI framework with an ORM over its own PostgreSQL driver, durable jobs, authentication and policy, OpenAPI with typed clients — and a native HTTP/1.1, HTTP/2 and HTTP/3 server underneath, when you want it.

Documentation · Getting started · From FastAPI · Issues

A wreath is a circle of separate things — leaves, branches, small flowers — gathered and woven until they hold a single shape. That is the idea behind this framework. A web application is made of many parts: routing, validation, authentication, data access, and the server that carries it all. Wreath gathers those parts into one coherent whole and gives each of them a clear, honest place to live.

The brand is allowed to be poetic. The API is not. A middleware is called a middleware. A dependency is a dependency. Routes are routes, startup is startup, a connection pool is a connection pool. You should be able to guess where a feature lives without first learning our vocabulary — wreath.pagination is pagination, wreath.jobs is jobs.

from wreath import Wreath, Request

app = Wreath()

@app.get("/hello/{name}")
async def hello(request: Request, name: str) -> dict:
    return {"hello": name}

wreath run app:app          # the native Wreath server
wreath dev app:app          # ... with autoreload while you develop
uvicorn app:app             # ... or any ASGI server you already run

Status: pre-1.0. Everything described below is implemented and tested; expect additions, and expect what already works to keep working as it grows. What is deliberately not shipped yet lives in one file: docs/reference/roadmap.md.

Why it feels different

What's in the circle

Each part keeps to its own clearly-named module, so the whole stays easy to hold in your head.

Serving a request

Knowing who is asking

Data

Work that outlives the request

Running it

A fuller table — including what each part means you don't have to install — is on the capability map.

Install

Wreath targets Python 3.14 and newer.

pip install wreath
# or
uv add wreath

# Linux io_uring event loop and native TLS transport
uv add 'wreath[linux]'

# HTTP/3 (the h3 and http3 names are aliases)
uv add 'wreath[h3]'

The base wheel always ships Wreath's portable C implementation and needs no compiler or runtime package. The linux extra adds Wreath's io_uring reactor; h3/http3 adds the HTTP/3 extension with its pinned QUIC/TLS libraries bundled into the wheel. Neither extra changes the framework API.

Your first few minutes

Declare where each value comes from, and Wreath compiles a validator for it at startup. Bad input becomes a clear 422 before your handler runs:

from typing import Annotated

from wreath import Request
from wreath.binding import Query
from wreath.response import JSONResponse

@app.get("/search")
async def search(
    request: Request,
    q: str,
    limit: Annotated[int, Query(minimum=1, maximum=100)] = 20,
) -> JSONResponse:
    return JSONResponse({"q": q, "limit": limit})

A model earns its keep twice — it describes a table, and its columns are the validator for a request body, so the two cannot drift apart:

from wreath.orm import Mapped, Model, column
from wreath.orm.types import Int64, Text

class Widget(Model, table="widgets"):
    id: Mapped[int] = column(Int64, primary_key=True)
    name: Mapped[str] = column(Text)

And you never need a socket to test any of it:

from wreath.testing import TestClient

async def test_index():
    async with TestClient(app) as client:
        response = await client.get("/")
        assert response.status == 200

Here is the shape of the path that carries it, and where the language boundary sits when the native build is in use:

   request
      │
      ▼
   ingress ─▶ middleware ─▶ routing ─▶ authentication ─▶ authorization
                                                               │
   ═══ into Python ════════════════════════════════════════════╪══════
                                                               ▼
                                                         your handler
                                                               │
   ═══ back to native ═════════════════════════════════════════╪══════
                                                               │
   response ◀───────────────── egress ◀────────────────────────╯

The intended shape is that everything before the handler stays native, and Python is entered when a route is activated. That is a measured property, not an aspiration: uv run wreath-request-trace counts every boundary crossing for a whole request against a realistic app, attributes each to a lifecycle phase, and compares the total to a baseline checked into the repository.

The command line

wreath --help lists the rest — mcp, capture, replay, passes, schema.

Documentation

The published site is https://alexogeny.github.io/wreath/.

• Getting started — install and build your first app, start to finish.
• Wreath for FastAPI developers — the same application in both dialects, with every habit mapped to its home.
• Guides — a page for each part of the framework, with the reasoning behind it.
• Cookbook — recipes for developers, and a set written for coding agents.
• API reference — every public module, generated from the source.
• Performance and internals — how it measures up, with the methodology, and what makes it quick.
• Release notes — what changed in each version.

Build them locally — there is no mkdocs and no Sphinx here, Wreath renders its own site:

uv run wreath-docs            # strict build; --serve to watch

Development

uv sync                       # dev group; builds the native extensions
uv run wreath-check           # ruff, ty, pytest, native lints, map lint, trace baseline
uv run wreath-check --docs    # ... and a strict docs build
uv run wreath test            # live grid, timing outliers, 192-control confidence sample
uv run wreath test --mutant full  # complete mutation sweep, overlapping green tests
uv run pytest                 # the default suite, serially
uv run pytest -m '' -n 6      # everything, including network, fuzz, and performance

The test grid keeps one tile per file: green means passed, purple ▣ means its tests are currently probing a mutant, and solid gold ▰ means one of those tests caught the removed control. A surviving mutant is reported as a finding and never earns the gold state.

[!IMPORTANT] Prefer the task entry points over a bare uv sync --group X. uv sync reconciles the venv to exactly the groups you name and removes everything else, so syncing one group uninstalls the last one's tools. The task runners use uv sync --inexact, which adds without evicting.

Contributing — the invariants a change must preserve, how to verify one, and why each rule exists — is documented in AGENTS.md and the cookbook's section for coding agents. If you are a coding agent, start there: docs/agents/manifest.json maps every subsystem to its sources, tests, and invariants so you can find one without reading the tree.

Benchmarks

Wreath ships equivalent applications across several frameworks and a renderer that reports medians with their run-to-run range, so a real win can be told from noise. Results are regenerated locally:

uv run wreath-bench-report    # one report across every benchmark family

See benchmarks/README.md for methodology. A single run is not a result, and no number here comes from one.

License

Wreath is licensed under the Mozilla Public License 2.0 (MPL-2.0).

In practice: use it freely, commercially, as a dependency of anything — proprietary applications and closed-source SaaS included. Your own code is never affected. The only obligation is that if you ship a product containing modified copies of wreath's own files, those file changes must remain source-available to your recipients.

The spirit of this release (a request, not a license term): if you make substantial improvements to wreath — bug fixes, features, performance work — we'd love to see them upstream rather than living in a fork. Massive divergent forks are legal; they're just not the point. The MPL grants no rights to the "wreath" name (§2.3), so a fork should pick its own.