causeway (Python)

A lean backend framework for type-safe Python APIs.

uv add causeway

This is the core Python package of Causeway. It ships:

• A file-based router that walks src/app/routes/**/*.py, picks up $id.py, (group)/, _middleware.py, and _scope.py, and registers handlers into the app's route table.
• A typed config layer that wraps pydantic-settings and exposes non-secret fields to the generated TypeScript client.
• A scoped DI container driven by _scope.py providers.
• A @task contract for background jobs with a Dramatiq reference adapter.
• A plugin registry with Python-entry-point discovery and per-environment activation.
• A route-key client generator that emits typed TypeScript clients from the same route IR.
• An App Graph that exposes routes, scopes, permissions, middleware, providers, tasks, plugins, events, and refresh contracts.
• A CLI (causeway new, causeway dev, causeway build, causeway inspect, causeway deploy <target>) that runs the whole loop.

For the full story, the design rationale, and a side-by-side vs. FastAPI / Django + Ninja / Encore.ts / NestJS, see the repo README.

30-second example

my-app/
├── pyproject.toml
├── causeway.toml
└── src/app/
    ├── config.py
    ├── plugins.py
    └── routes/
        ├── _middleware.py
        ├── index.py
        └── users/
            ├── _scope.py
            ├── index.py
            └── $id.py

# src/app/routes/users/$id.py
from typing import Annotated
from uuid import UUID
from msgspec import Struct
from causeway import get, raises
from causeway.errors import NotFound

class User(Struct):
    id: UUID
    name: str

@get
@raises(NotFound)
async def show(id: UUID) -> User:
    ...

Run it:

causeway dev

causeway dev discovers the routes, boots uvicorn once, hot-swaps route edits without restarting the process, and exposes /__causeway with the route tree, registered tasks, current config, plugin list, and App Graph.

The public client identity is the route key:

const user = await client.query("GET /users/$id", { id });

Primitives in this package

Full reference: https://github.com/tamimbinhakim/causeway/tree/main/docs/reference

Optional extras

uv add 'causeway[dramatiq]'  # reference task adapter
uv add 'causeway[otel]'      # OpenTelemetry middleware hooks
uv add 'causeway[all]'       # everything

Scope

Causeway ships project shape and a small set of contracts. It does not ship vertical integrations — no ORM, no admin panel, no template engine, no infrastructure provisioning. Those layers compose on top of the fundamentals and live in their own plugin packages or in user code.

License

MIT