Metadata-Version: 2.5
Name: fastapi-canon
Version: 0.23.0
Summary: Typed FastAPI applications with Dishka, HTTP contracts, SSE, WebSockets, WebRTC and client generation
Project-URL: Homepage, https://github.com/mathisarends/fastapi-canon
Project-URL: Repository, https://github.com/mathisarends/fastapi-canon
Project-URL: Documentation, https://github.com/mathisarends/fastapi-canon/tree/main/docs
Project-URL: Issues, https://github.com/mathisarends/fastapi-canon/issues
Author: mathisarends
License-Expression: MIT
License-File: LICENSE
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Requires-Dist: dishka<1.11,>=1.10
Requires-Dist: fastapi<1,>=0.143.1
Requires-Dist: pydantic<3,>=2.9
Provides-Extra: aiortc
Requires-Dist: aiortc<1.16,>=1.14; extra == 'aiortc'
Provides-Extra: codegen
Requires-Dist: jinja2<4,>=3.1; extra == 'codegen'
Requires-Dist: jsonschema<5,>=4.23; extra == 'codegen'
Requires-Dist: pydantic<3,>=2.11.2; extra == 'codegen'
Requires-Dist: typing-extensions>=4.12.2; extra == 'codegen'
Provides-Extra: database
Requires-Dist: anyio<5,>=4; extra == 'database'
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.38; extra == 'database'
Provides-Extra: mcp
Requires-Dist: fastmcp<5,>=4.1.3; extra == 'mcp'
Requires-Dist: pydantic<3,>=2.12; extra == 'mcp'
Provides-Extra: migrations
Requires-Dist: alembic<2,>=1.14; extra == 'migrations'
Requires-Dist: anyio<5,>=4; extra == 'migrations'
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.38; extra == 'migrations'
Provides-Extra: otel
Requires-Dist: opentelemetry-api<2,>=1.40; extra == 'otel'
Requires-Dist: opentelemetry-instrumentation<1,>=0.61b0; extra == 'otel'
Provides-Extra: otel-httpx
Requires-Dist: opentelemetry-api<2,>=1.40; extra == 'otel-httpx'
Requires-Dist: opentelemetry-instrumentation-httpx<1,>=0.65b0; extra == 'otel-httpx'
Requires-Dist: opentelemetry-instrumentation<1,>=0.61b0; extra == 'otel-httpx'
Provides-Extra: otel-sqlalchemy
Requires-Dist: opentelemetry-api<2,>=1.40; extra == 'otel-sqlalchemy'
Requires-Dist: opentelemetry-instrumentation<1,>=0.61b0; extra == 'otel-sqlalchemy'
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0; extra == 'otel-sqlalchemy'
Provides-Extra: postgres
Requires-Dist: anyio<5,>=4; extra == 'postgres'
Requires-Dist: asyncpg<1,>=0.30; extra == 'postgres'
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.38; extra == 'postgres'
Provides-Extra: sqlite
Requires-Dist: aiosqlite<1,>=0.20; extra == 'sqlite'
Requires-Dist: anyio<5,>=4; extra == 'sqlite'
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.38; extra == 'sqlite'
Provides-Extra: sqlmodel
Requires-Dist: anyio<5,>=4; extra == 'sqlmodel'
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.38; extra == 'sqlmodel'
Requires-Dist: sqlmodel<0.1,>=0.0.22; extra == 'sqlmodel'
Provides-Extra: sse
Requires-Dist: fastapi<1,>=0.143.3; extra == 'sse'
Requires-Dist: pydantic<3,>=2.11.2; extra == 'sse'
Provides-Extra: uploads
Requires-Dist: python-multipart<1,>=0.0.20; extra == 'uploads'
Provides-Extra: webrtc
Requires-Dist: anyio>=4; extra == 'webrtc'
Requires-Dist: starlette>=0.41; extra == 'webrtc'
Requires-Dist: typing-extensions>=4.12; extra == 'webrtc'
Provides-Extra: websockets
Requires-Dist: pydantic-core>=2.33; extra == 'websockets'
Requires-Dist: pydantic<3,>=2.11; extra == 'websockets'
Requires-Dist: typing-extensions>=4.12.2; extra == 'websockets'
Description-Content-Type: text/markdown

# fastapi-canon

Canon adds typed HTTP contracts, SSE, WebSockets and application composition to
FastAPI. Define public errors once, reuse them across transports and export
contracts for Python and TypeScript clients.

## Install

```console
uv add fastapi-canon
```

Python 3.12–3.14 is supported. Add extras for the features you use, for example
`fastapi-canon[sse,websockets]` or `fastapi-canon[codegen]`.

**Published: 0.22.0 (2026-11-15).**
Follow the [migration guide](docs/package-migration.md#upgrade-to-0220) when upgrading.
See the [release and verified artifacts](https://github.com/mathisarends/fastapi-canon/releases/tag/fastapi-canon-v0.22.0).

## Shared error handling

Keep domain exceptions in ordinary Python and declare their public representation:

```python
from fastapi import FastAPI

from fastapi_canon import APIRouter, Composition, Error, Feature


class ProjectMissing(Exception):
    pass


project_missing = Error(
    ProjectMissing,
    status=404,
    code="project_missing",
    title="Project not found",
    detail="Choose another project.",
)
router = APIRouter()


@router.get("/projects/{project_id}", raises=[project_missing])
async def get_project(project_id: int) -> dict[str, int]:
    if project_id == 0:
        raise ProjectMissing()
    return {"id": project_id}


app = Composition(
    features=(Feature(name="projects", routers=[router]),),
).build(FastAPI())
```

`GET /projects/0` returns a 404 RFC 9457 Problem Details response.
OpenAPI describes the same error; exception messages stay private by default.
Reuse `project_missing` in SSE and RPC declarations. See the
[quickstart](docs/quickstart.md) for the complete server and clients.

## What you can build

| Task | Guide |
| --- | --- |
| HTTP routes, dependencies and feature lifecycles | [Composition](docs/composition.md) |
| Shared public errors and typed extensions | [Problems](docs/problems.md) |
| File uploads and binary downloads | [File transfers](docs/integrations/uploads.md) |
| Typed event streams | [SSE](docs/integrations/sse/README.md) |
| RPC, sockets and binary streams | [WebSockets](docs/integrations/websockets/README.md) |
| Media sessions, tools or database resources | [WebRTC](docs/integrations/webrtc/README.md), [MCP](docs/integrations/mcp/README.md), [database](docs/database.md) |
| Service tracing and request logs | [Telemetry](docs/telemetry.md), [logging](docs/request-logging.md) |

## Generate and check clients

The generation workflow exports contracts and runs specialized SSE,
WebSocket and WebRTC generators. Add your HTTP generator through external
commands. Configure it with the [generation guide](docs/codegen.md), then run:

```console
uv run fastapi-canon generate
uv run fastapi-canon generate --check --diff
uv run fastapi-canon check errors src --strict --require-complete
```

Python models and error declarations are shared on the server. Generated
clients have separate APIs and error classes. Static checks complement runtime
tests and report paths they cannot resolve.

Browse the [task guides](docs/README.md), [examples](examples/README.md) or
[contributor commands](docs/contributing.md). Coding agents can install the
[bundled backend skill](fastapi_canon/skills/build-canon-backend/SKILL.md)
with `uv run fastapi-canon skill install`.
