Wred documentation

Build an app, look up an API, or find out which component owns the configuration. A tutorial and reference for a framework that still fits in one Python file.

Look something up

Following a lesson is useful. Finding the exact method signature without rereading a lesson is also useful. We have bravely decided to provide both.

• Installation & quick start — Python requirements, extras, servers, and editable installs.
• API reference — App, routes, Request, response formats, and ASGI helpers.
• Configuration & architecture — settings ownership and the notebook’s environment variables.
• Errors & troubleshooting — exceptions, HTTP statuses, and debugging.
• Frequently asked questions — the usual surprises, catalogued.
• Deployment boundaries — body limits, proxy trust, credentials, and input handling.
• Development & contributing — checks, source changes, docs, and bug reports.
• Release notes & upgrading — the 0.10 query-property change and the optional server extra.

The search box looks through these pages and the tutorial. Everything runs locally in the browser; no search account, index service, or ritual sacrifice required.

The app we’re actually building

The repository includes a notebook with accounts, private notes, search, pagination, JSON export, a browser interface, and MongoDB storage. We’ll run it, follow a request through its files, then explore the bits you might want to borrow for your own app.

Wred handles HTTP routes and responses. Your application chooses the database, authentication, middleware, and frontend. It’s a small framework with a very healthy relationship with the word “elsewhere.”

The chapters move from local development to deployment. The middleware and frontend recipes are independent examples; they don’t silently rewrite the notebook app while you’re looking away.

Bring these things

• Python 3.11 or newer, a terminal, and enough JavaScript to recognize fetch().
• A running MongoDB instance for the notebook chapters. The first API and most middleware examples work without it.
• A Linux or macOS shell for the commands shown. On Windows, use WSL or adapt virtualenv activation to PowerShell.

Examples use Weft through wred[server]. Wred itself only requires orjson. Starlette, PyMongo, ServeStatic, and the other extras belong to the examples that use them.

Work through the tutorial

1. 1. Your first API

   Routes, requests, validation, JSON, and response tuples.

2. 2. Run the notebook

   Start MongoDB, run the example, and follow the source files.

3. 3. Notes, accounts, and ownership

   Trace note creation, bearer tokens, refresh cookies, and ownership.

4. 4. Borrow Starlette’s middleware

   Add CORS, host checks, compression, errors, and signed sessions.

5. 5. Write a little ASGI middleware

   Build request context and reuse proxy-header middleware.

6. 6. Serve a frontend and other responses

   Compose static files, API mounts, downloads, and event streams.

7. 7. Put Caddy in front

   Deploy with automatic HTTPS and a private Python backend.

8. 8. Put Nginx in front

   Configure TLS, forwarding, body limits, and throttling.

9. 9. Keep it running

   Supervise workers, manage configuration, and diagnose failures.

Copy the bits you need

Python and configuration examples have download links. Save each example with the filename shown. Run the standalone Python examples from the directory you saved them in; stop one server with Ctrl+C before starting another on port 8000.

From a checkout of this repository, you can also run the standalone examples directly:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[server]' starlette itsdangerous
cd docs/tutorial/examples
weft first_api:app

The notebook chapters use the repository root instead. Each chapter says which directory and dependencies it expects, because scavenger hunts are a terrible package manager.