fastapi-canon 0.1.0__tar.gz

fastapi_canon-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: "3.14"
+      - run: uv sync --frozen --all-groups
+      - run: >-
+          uv run pre-commit run
+          --config .pre-commit-config.yml
+          --all-files
+          --show-diff-on-failure
+      - run: uv run mypy
+
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python }}, ${{ matrix.resolution }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: "3.12"
+            resolution: locked
+          - os: ubuntu-latest
+            python: "3.13"
+            resolution: locked
+          - os: ubuntu-latest
+            python: "3.14"
+            resolution: locked
+          - os: ubuntu-latest
+            python: "3.12"
+            resolution: lowest-direct
+          - os: ubuntu-latest
+            python: "3.14"
+            resolution: latest
+          - os: windows-latest
+            python: "3.14"
+            resolution: locked
+          - os: macos-latest
+            python: "3.14"
+            resolution: locked
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - if: matrix.resolution == 'locked'
+        run: uv sync --frozen --all-groups
+      - if: matrix.resolution == 'lowest-direct'
+        run: >-
+          uv run --isolated --no-project --python 3.12
+          --with .
+          --with "dishka==1.10.0"
+          --with "fastapi==0.115.0"
+          --with "pydantic==2.9.0"
+          --with "httpx==0.27.0"
+          --with "httpx2>=2.12.0"
+          --with "pytest>=8.3"
+          --with "jsonschema>=4.23"
+          --with "openapi-spec-validator>=0.7.1"
+          pytest
+      - if: matrix.resolution == 'latest'
+        run: >-
+          uv run --isolated --no-project --python 3.14
+          --with .
+          --with httpx
+          --with httpx2
+          --with pytest
+          --with jsonschema
+          --with openapi-spec-validator
+          pytest
+      - if: matrix.resolution == 'locked'
+        run: uv run pytest
+
+  package:
+    name: Build and clean-wheel import
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: "3.14"
+      - run: uv build
+      - run: uv venv --python 3.14 .wheel-venv
+      - run: uv pip install --python .wheel-venv/bin/python dist/*.whl
+      - run: >-
+          .wheel-venv/bin/python -I -c
+          "from fastapi_canon import Composition, Error, ErrorConfigurationError,
+          ErrorOptions, ErrorRegistry, Feature, Problem;
+          assert all((Composition, Error, ErrorConfigurationError,
+          ErrorOptions, ErrorRegistry, Feature, Problem))"

fastapi_canon-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.wheel-venv/
+__pycache__/
+*.egg-info/
+*.py[cod]
+build/
+dist/
+htmlcov/

fastapi_canon-0.1.0/.pre-commit-config.yml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff-check
+        args: [--fix, --line-length=88]
+      - id: ruff-format
+        args: [--line-length=88]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

fastapi_canon-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

fastapi_canon-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: fastapi-canon
+Version: 0.1.0
+Summary: Opinionated FastAPI feature composition with Dishka and Problem Details
+Project-URL: Homepage, https://github.com/mathisarends/fastapi_canon
+Project-URL: Repository, https://github.com/mathisarends/fastapi_canon
+Project-URL: Issues, https://github.com/mathisarends/fastapi_canon/issues
+Author: mathisarends
+License-Expression: MIT
+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<2,>=1.10
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: pydantic<3,>=2.9
+Description-Content-Type: text/markdown
+
+# fastapi-canon
+
+`fastapi-canon` is an opinionated composition library for feature-oriented
+FastAPI applications. A feature groups its routers, Dishka providers, error
+contracts, exception handlers, and lifespan into one immutable value. The
+application installs an explicitly ordered set of those values at its
+composition root.
+
+Dishka is a deliberate part of this canon, not an optional integration.
+`fastapi-canon` defines one dependency-injection approach: features contribute
+Dishka providers, and the composition builds and owns one shared Dishka
+container. Applications that choose another dependency-injection framework are
+outside the library's intended architecture.
+
+```python
+from fastapi import APIRouter, FastAPI
+from fastapi_canon import Composition, Feature
+
+projects = APIRouter(prefix="/projects", tags=["projects"])
+
+
+@projects.get("")
+async def list_projects() -> list[str]:
+    return []
+
+
+project_feature = Feature(routers=[projects])
+
+app = Composition(project_feature).apply(FastAPI())
+```
+
+## Contributions
+
+Every contribution is optional:
+
+```python
+feature = Feature(
+    routers=[router],
+    providers=[provider],
+    errors=feature_errors,
+    exception_handlers=[handler_spec],
+    lifespan=feature_lifespan,
+)
+```
+
+Mutable sequences passed to `Feature` are copied to tuples. Installing features
+preserves declaration order for routes and startup. Shutdown runs in reverse
+order, including cleanup of features that started before a later feature failed.
+
+### Dishka
+
+Dishka is a required runtime dependency and the canonical dependency-injection
+mechanism. Provider instances from every feature are validated together and
+used to build one `AsyncContainer`. Applying the composition configures
+Dishka's FastAPI middleware and closes the container during application
+shutdown. Dishka exposes the container as `app.state.dishka_container`.
+
+### Errors
+
+Error contracts are implemented directly by `fastapi-canon`; no separate error
+library is required. Each feature may expose one `ErrorRegistry`. Registries are
+merged and installed once, so runtime RFC 9457 Problem Details and OpenAPI use
+the same definitions:
+
+```python
+from fastapi_canon import Composition, Error, ErrorOptions, ErrorRegistry, Feature
+
+
+class ProjectNotFound(Exception):
+    pass
+
+
+project_not_found = Error(
+    ProjectNotFound,
+    status=404,
+    code="project_not_found",
+    title="Project not found",
+    detail=lambda error: str(error),
+)
+
+project_errors = ErrorRegistry(
+    name="projects",
+    errors=[project_not_found],
+)
+
+project_feature = Feature(
+    routers=[projects],
+    errors=project_errors,
+)
+
+app = Composition(
+    project_feature,
+    errors=ErrorOptions(
+        type_base="https://api.example.com/problems",
+    ),
+).apply(FastAPI())
+```
+
+Declare endpoint responses from the same registry used at runtime:
+
+```python
+@projects.get(
+    "/{project_id}",
+    responses=project_errors.responses(project_not_found),
+)
+async def get_project(project_id: str) -> dict[str, str]:
+    raise ProjectNotFound(project_id)
+```
+
+#### OpenAPI representation
+
+Every declared error becomes a reusable schema in `components.schemas`. The
+corresponding operation references it as an `application/problem+json`
+response:
+
+```yaml
+paths:
+  /projects/{project_id}:
+    get:
+      responses:
+        "404":
+          description: Project not found
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/ProjectNotFoundProblem"
+
+components:
+  schemas:
+    ProjectNotFoundProblem:
+      type: object
+      required: [type, title, status, code]
+      properties:
+        type:
+          type: string
+          const: https://api.example.com/problems/project_not_found
+        title:
+          type: string
+          const: Project not found
+        status:
+          type: integer
+          const: 404
+        code:
+          type: string
+          const: project_not_found
+        detail:
+          type: [string, "null"]
+```
+
+Typed extension fields and documented response headers are added to that same
+schema and response. If multiple errors share one status code, the response
+uses `oneOf` with `code` as its discriminator. When validation normalization is
+enabled, FastAPI's default `422` response is replaced by
+`RequestValidationProblem` using the same media type.
+
+When all local registries already share a `type_base`, it is inferred. The
+`ErrorOptions` settings `include_validation_error`,
+`include_http_exceptions`, and `include_unhandled_error` are passed to
+the integrated error engine and default to `True`.
+
+Use `ExceptionHandlerSpec` for a deliberately custom Starlette/FastAPI handler:
+
+```python
+from fastapi_canon import ExceptionHandlerSpec
+
+feature = Feature(
+    exception_handlers=[ExceptionHandlerSpec(DomainError, domain_error_handler)],
+)
+```
+
+## Installation guarantees
+
+- Feature order is explicit and deterministic.
+- Reinstalling the exact same feature objects with the same options is a no-op.
+- A different second installation is rejected.
+- Duplicate routers, providers, handlers, and error collisions fail during
+  configuration.
+- Known configuration errors are validated against a temporary application
+  before the real application is changed.
+- Provider-backed features must be installed before the application starts.
+- Disabling a feature means omitting it from `Composition`, which removes all of
+  its contributions together.
+
+Configuration failures raise `FeatureConfigurationError`.
+
+## Requirements
+
+- CPython 3.12, 3.13, or 3.14
+- FastAPI 0.115 or newer, below 1.0
+- Dishka 1.10 or newer, below 2.0
+- Pydantic 2.9 or newer, below 3.0
+
+## Development
+
+Install the development dependencies and run the quality gates:
+
+```console
+uv sync --all-groups
+uv run pre-commit install --config .pre-commit-config.yml
+uv run pre-commit run --config .pre-commit-config.yml --all-files
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+## Showcase
+
+See [`examples/showcase`](examples/showcase) for a runnable two-feature FastAPI
+application. It keeps error contracts alongside their feature routes and merges
+them once at the composition root.

fastapi_canon-0.1.0/README.md

@@ -0,0 +1,212 @@
+# fastapi-canon
+
+`fastapi-canon` is an opinionated composition library for feature-oriented
+FastAPI applications. A feature groups its routers, Dishka providers, error
+contracts, exception handlers, and lifespan into one immutable value. The
+application installs an explicitly ordered set of those values at its
+composition root.
+
+Dishka is a deliberate part of this canon, not an optional integration.
+`fastapi-canon` defines one dependency-injection approach: features contribute
+Dishka providers, and the composition builds and owns one shared Dishka
+container. Applications that choose another dependency-injection framework are
+outside the library's intended architecture.
+
+```python
+from fastapi import APIRouter, FastAPI
+from fastapi_canon import Composition, Feature
+
+projects = APIRouter(prefix="/projects", tags=["projects"])
+
+
+@projects.get("")
+async def list_projects() -> list[str]:
+    return []
+
+
+project_feature = Feature(routers=[projects])
+
+app = Composition(project_feature).apply(FastAPI())
+```
+
+## Contributions
+
+Every contribution is optional:
+
+```python
+feature = Feature(
+    routers=[router],
+    providers=[provider],
+    errors=feature_errors,
+    exception_handlers=[handler_spec],
+    lifespan=feature_lifespan,
+)
+```
+
+Mutable sequences passed to `Feature` are copied to tuples. Installing features
+preserves declaration order for routes and startup. Shutdown runs in reverse
+order, including cleanup of features that started before a later feature failed.
+
+### Dishka
+
+Dishka is a required runtime dependency and the canonical dependency-injection
+mechanism. Provider instances from every feature are validated together and
+used to build one `AsyncContainer`. Applying the composition configures
+Dishka's FastAPI middleware and closes the container during application
+shutdown. Dishka exposes the container as `app.state.dishka_container`.
+
+### Errors
+
+Error contracts are implemented directly by `fastapi-canon`; no separate error
+library is required. Each feature may expose one `ErrorRegistry`. Registries are
+merged and installed once, so runtime RFC 9457 Problem Details and OpenAPI use
+the same definitions:
+
+```python
+from fastapi_canon import Composition, Error, ErrorOptions, ErrorRegistry, Feature
+
+
+class ProjectNotFound(Exception):
+    pass
+
+
+project_not_found = Error(
+    ProjectNotFound,
+    status=404,
+    code="project_not_found",
+    title="Project not found",
+    detail=lambda error: str(error),
+)
+
+project_errors = ErrorRegistry(
+    name="projects",
+    errors=[project_not_found],
+)
+
+project_feature = Feature(
+    routers=[projects],
+    errors=project_errors,
+)
+
+app = Composition(
+    project_feature,
+    errors=ErrorOptions(
+        type_base="https://api.example.com/problems",
+    ),
+).apply(FastAPI())
+```
+
+Declare endpoint responses from the same registry used at runtime:
+
+```python
+@projects.get(
+    "/{project_id}",
+    responses=project_errors.responses(project_not_found),
+)
+async def get_project(project_id: str) -> dict[str, str]:
+    raise ProjectNotFound(project_id)
+```
+
+#### OpenAPI representation
+
+Every declared error becomes a reusable schema in `components.schemas`. The
+corresponding operation references it as an `application/problem+json`
+response:
+
+```yaml
+paths:
+  /projects/{project_id}:
+    get:
+      responses:
+        "404":
+          description: Project not found
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/ProjectNotFoundProblem"
+
+components:
+  schemas:
+    ProjectNotFoundProblem:
+      type: object
+      required: [type, title, status, code]
+      properties:
+        type:
+          type: string
+          const: https://api.example.com/problems/project_not_found
+        title:
+          type: string
+          const: Project not found
+        status:
+          type: integer
+          const: 404
+        code:
+          type: string
+          const: project_not_found
+        detail:
+          type: [string, "null"]
+```
+
+Typed extension fields and documented response headers are added to that same
+schema and response. If multiple errors share one status code, the response
+uses `oneOf` with `code` as its discriminator. When validation normalization is
+enabled, FastAPI's default `422` response is replaced by
+`RequestValidationProblem` using the same media type.
+
+When all local registries already share a `type_base`, it is inferred. The
+`ErrorOptions` settings `include_validation_error`,
+`include_http_exceptions`, and `include_unhandled_error` are passed to
+the integrated error engine and default to `True`.
+
+Use `ExceptionHandlerSpec` for a deliberately custom Starlette/FastAPI handler:
+
+```python
+from fastapi_canon import ExceptionHandlerSpec
+
+feature = Feature(
+    exception_handlers=[ExceptionHandlerSpec(DomainError, domain_error_handler)],
+)
+```
+
+## Installation guarantees
+
+- Feature order is explicit and deterministic.
+- Reinstalling the exact same feature objects with the same options is a no-op.
+- A different second installation is rejected.
+- Duplicate routers, providers, handlers, and error collisions fail during
+  configuration.
+- Known configuration errors are validated against a temporary application
+  before the real application is changed.
+- Provider-backed features must be installed before the application starts.
+- Disabling a feature means omitting it from `Composition`, which removes all of
+  its contributions together.
+
+Configuration failures raise `FeatureConfigurationError`.
+
+## Requirements
+
+- CPython 3.12, 3.13, or 3.14
+- FastAPI 0.115 or newer, below 1.0
+- Dishka 1.10 or newer, below 2.0
+- Pydantic 2.9 or newer, below 3.0
+
+## Development
+
+Install the development dependencies and run the quality gates:
+
+```console
+uv sync --all-groups
+uv run pre-commit install --config .pre-commit-config.yml
+uv run pre-commit run --config .pre-commit-config.yml --all-files
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+## Showcase
+
+See [`examples/showcase`](examples/showcase) for a runnable two-feature FastAPI
+application. It keeps error contracts alongside their feature routes and merges
+them once at the composition root.

fastapi_canon-0.1.0/examples/showcase/README.md

@@ -0,0 +1,64 @@
+# fastapi-canon showcase
+
+This small application demonstrates the recommended application boundary:
+each feature owns its router and its domain-error contracts, while `app.py`
+is the only composition root. Its layout is deliberately suitable as a starting
+point for a real service:
+
+```text
+showcase/
+  app.py                         # composition root
+  features/
+    catalog/
+      __init__.py                # public `feature` export
+      router.py                  # HTTP layer
+      models.py                  # request and response models
+      exceptions.py              # domain exceptions, without HTTP concerns
+      errors.py                  # Error / ErrorRegistry contracts
+      service.py                 # framework-independent use cases
+      providers.py               # Dishka bindings contributed by the feature
+    status/
+      __init__.py
+      router.py
+```
+
+Run it from the repository root:
+
+```console
+uv run --with uvicorn uvicorn examples.showcase.app:app --reload
+```
+
+Then open [the API documentation](http://127.0.0.1:8000/docs), or try the
+following requests:
+
+```console
+curl http://127.0.0.1:8000/health
+curl http://127.0.0.1:8000/products/coffee
+curl http://127.0.0.1:8000/products/missing
+curl -X POST http://127.0.0.1:8000/products/tea/reservations -H "content-type: application/json" -d '{"quantity": 1}'
+curl -X POST http://127.0.0.1:8000/products/coffee/reservations -H "content-type: application/json" -d '{"quantity": 0}'
+```
+
+The last three calls show the three error classes handled by the shared error
+engine:
+
+| Situation | Result |
+| --- | --- |
+| Unknown product | Feature-defined `404 product_not_found` problem |
+| Insufficient stock | Feature-defined `409 product_unavailable` problem, including typed extension members |
+| Invalid request body | Built-in normalized `422 request_validation_error` problem |
+
+`catalog/errors.py` deliberately has no application-wide problem-type URL. Its
+`ErrorRegistry` is local to the feature. `Composition` merges that registry
+and `ErrorOptions(type_base=...)` resolves every feature error type to the
+same public namespace. The `responses=errors.responses(...)` declarations use
+the very same contracts as runtime handling, so `/openapi.json` documents the
+`404` and `409` responses without duplicating schemas.
+
+The router only validates HTTP input and calls `CatalogService`; it receives
+that service through Dishka. `catalog/__init__.py` contributes the provider,
+router, and error registry as one `Feature`, so removing the feature removes
+all of those pieces together.
+
+To turn a feature off, remove `catalog_feature` from `Composition` in `app.py`.
+Its routes and error definitions disappear together.

fastapi_canon-0.1.0/examples/showcase/app.py

@@ -0,0 +1,19 @@
+from fastapi import FastAPI
+
+from examples.showcase.features.catalog import feature as catalog_feature
+from examples.showcase.features.status import feature as status_feature
+from fastapi_canon import Composition, ErrorOptions
+
+composition = Composition(
+    status_feature,
+    catalog_feature,
+    errors=ErrorOptions(type_base="https://api.example.test/problems"),
+)
+
+app = composition.apply(
+    FastAPI(
+        title="fastapi-canon showcase",
+        version="0.1.0",
+        description="Feature composition with RFC 9457 Problem Details.",
+    )
+)

fastapi_canon-0.1.0/examples/showcase/features/catalog/__init__.py

@@ -0,0 +1,13 @@
+from fastapi_canon import Feature
+
+from .errors import registry
+from .providers import CatalogProvider
+from .router import router
+
+feature = Feature(
+    routers=[router],
+    providers=[CatalogProvider()],
+    errors=registry,
+)
+
+__all__ = ["feature"]