seampact-fastapi 1.0.0__tar.gz

seampact_fastapi-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/

seampact_fastapi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Metral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seampact_fastapi-1.0.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.5
+Name: seampact-fastapi
+Version: 1.0.0
+Summary: The FastAPI target of seampact: its generator and the placement runtime of the generated code.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.162
+Requires-Dist: seampact-codegen[pydantic]==1.0.0
+Requires-Dist: seampact-hooks==1.0.0
+Provides-Extra: generate
+Requires-Dist: seampact-codegen[generate]==1.0.0; extra == 'generate'
+Requires-Dist: seampact-ir==1.0.0; extra == 'generate'
+Description-Content-Type: text/markdown
+
+The FastAPI target of seampact: the generator that `seampact generate` finds through its entry point, and the runtime the generated placement imports.

seampact_fastapi-1.0.0/README.md

@@ -0,0 +1 @@
+The FastAPI target of seampact: the generator that `seampact generate` finds through its entry point, and the runtime the generated placement imports.

seampact_fastapi-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seampact-fastapi"
+version = "1.0.0"
+description = "The FastAPI target of seampact: its generator and the placement runtime of the generated code."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+# FastAPI breaks in minors: 0.162 is the matrix floor, a later minor is untested and refused at boot unless the app
+# config allows it. Starlette and Pydantic come through FastAPI's own ranges; Pydantic 2.9 is FastAPI 0.162's floor.
+dependencies = [
+    "fastapi>=0.162",
+    "seampact-codegen[pydantic]==1.0.0",
+    "seampact-hooks==1.0.0",
+]
+classifiers = [
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+# What the generator itself needs; a production install of an app leaves it out.
+generate = ["seampact-codegen[generate]==1.0.0", "seampact-ir==1.0.0"]
+
+[project.entry-points."seampact.generators"]
+fastapi = "seampact.fastapi.generator:FastApiGenerator"
+
+# PEP 420: `seampact` is a namespace shared by every seampact distribution, so it has no `__init__.py`.
+[tool.hatch.build.targets.wheel]
+packages = ["src/seampact"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/seampact", "LICENSE"]
+
+[tool.uv.sources]
+seampact-codegen = { workspace = true }
+seampact-hooks = { workspace = true }
+seampact-ir = { workspace = true }

seampact_fastapi-1.0.0/src/seampact/fastapi/__init__.py

@@ -0,0 +1,2 @@
+"""The FastAPI target of seampact (ADR 0026): the generator `seampact generate` finds through the `seampact.generators`
+entry point, behind the `generate` extra, and the placement runtime the generated code imports."""

seampact_fastapi-1.0.0/src/seampact/fastapi/generator.py

@@ -0,0 +1,85 @@
+"""The fastapi target (ADR 0026), which `seampact generate` finds through the `seampact.generators` entry point of
+`seampact-fastapi`. Per api it writes one package: `schemas.py` (the schema models and each operation's input model,
+through the shared Pydantic emitter), `operations.py` (the operation types), `contract.py` (the contract the runtime
+reads, shared with every Python target), `routes.py` (the route names and URL
+builders, unless `routeHelpers: false`), `fastapi.py` (the placement and `bind_<api>()`) and, with `nativeDocs`,
+`native_docs.json` (seampact's operation objects for FastAPI's document). It refuses by name every
+option, artefact and contract form it does not serve, all at once."""
+
+from collections.abc import Sequence
+from typing import Final
+
+from seampact.codegen.contract_module import contract_module
+from seampact.codegen.handler_forms import handler_warnings
+from seampact.codegen.input_schemas import proof_models, with_input_schemas
+from seampact.codegen.kept_forms import refuse_kept_forms
+from seampact.codegen.matrix_row import refuse_missing_matrix_row
+from seampact.codegen.names import api_names
+from seampact.codegen.native_docs_file import FrameworkDocument, native_docs_file
+from seampact.codegen.operation_types import operation_types_module
+from seampact.codegen.printer import PythonModule
+from seampact.codegen.pydantic_forms import refuse_unserved_forms
+from seampact.codegen.pydantic_layout import api_layout
+from seampact.codegen.pydantic_models import pydantic_schemas_module
+from seampact.codegen.refusals import Refusals
+from seampact.codegen.route_helpers import route_helpers_module
+from seampact.codegen.routes import route_table
+from seampact.fastapi.options import read_options
+from seampact.fastapi.placement_module import placement_module
+from seampact.ir.config.problem import ConfigProblem
+from seampact.ir.model import ContractIR
+from seampact.ir.read import IrSupport
+from seampact.ir.run.generator import TargetEntry
+from seampact.ir.write import GeneratedFile
+
+TARGET: Final = "fastapi"
+DISTRIBUTION: Final = "seampact-fastapi"
+_HTTP_OPERATION: Final = "httpOperation"
+_FASTAPI_DOCUMENT: Final = FrameworkDocument(TARGET, "FastAPI", ("ValidationError", "HTTPValidationError"))
+
+
+class FastApiGenerator:
+    def ir_support(self) -> IrSupport:
+        return IrSupport.of_model(kinds=[_HTTP_OPERATION])
+
+    def framework_docs_off_fix(self) -> str | None:
+        return None
+
+    def handler_warnings(self, ir: ContractIR, entry: TargetEntry) -> Sequence[ConfigProblem]:
+        return handler_warnings(ir, entry.id, entry.api)
+
+    def generate(self, ir: ContractIR, entry: TargetEntry) -> Sequence[GeneratedFile]:
+        refusals = Refusals(entry.id, TARGET, DISTRIBUTION)
+        options = read_options(entry.options, entry.artefacts, refusals)
+
+        refuse_kept_forms(ir, refusals)
+
+        refuse_missing_matrix_row(entry, refusals, "FastAPI and Starlette")
+        refuse_unserved_forms(ir, refusals)
+        error_codes = sorted({error.code for operation in ir.operations for error in operation.errors})
+        layout = api_layout(ir, error_codes, refusals)
+        with_inputs = with_input_schemas(ir, layout)
+        names = api_names(with_inputs, refusals)
+        routes = route_table(ir, entry.mount or "", refusals)
+        files = [
+            GeneratedFile("schemas.py", pydantic_schemas_module(with_inputs, names, options.rules, refusals)),
+            GeneratedFile(
+                "__init__.py", PythonModule(f"The generated code of api '{ir.api.id}' for the FastAPI target.").text()
+            ),
+            GeneratedFile("operations.py", operation_types_module(with_inputs, names, layout, refusals)),
+            GeneratedFile("contract.py", contract_module(ir, names, entry.mount or "", refusals)),
+            GeneratedFile(
+                "fastapi.py", placement_module(ir, layout, proof_models(layout, names), routes, options, entry)
+            ),
+        ]
+
+        if options.route_helpers:
+            files.append(GeneratedFile("routes.py", route_helpers_module(ir, routes, refusals)))
+
+        if options.native_docs:
+            native_docs = native_docs_file(entry.native_docs, layout.operations, _FASTAPI_DOCUMENT, refusals)
+            files.extend([] if native_docs is None else [native_docs])
+
+        refusals.raise_if_any()
+
+        return sorted(files, key=lambda generated: generated.path)

seampact_fastapi-1.0.0/src/seampact/fastapi/options.py

@@ -0,0 +1,241 @@
+"""The options and artefact switches of a fastapi target entry (ADR 0026 "Options and registration" and "What the
+shape-imposing features turn off with"), each unknown key or value outside its set refused by name: `handlers`
+(`perResource` only), `indent` (the four spaces ruff writes), `rules`, and the run-time defaults `responses`,
+`bodyValidation`, `frameworkEtag` and `catchAll`; the naming options and `layout` are refused. The artefacts are
+`bootCheck`, `accessHooks` (`false` waits for a consumer), `routeHelpers` and `nativeDocs`."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Final
+
+from seampact.codegen.boot_check_hooks import HOOKS_ERROR, read_boot_check_hooks
+from seampact.codegen.pydantic_models import RulesMode
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.codegen.runtime.reply_verdict import FrameworkEtagMode, ResponsesMode
+from seampact.fastapi.runtime.placement import BootCheckSwitches, FrameworkRoutesCheck, HooksCheck, TargetDefaults
+from seampact.ir.config.json_value import JsonValue
+
+INDENT_SPACES: Final = 4
+_HANDLERS: Final = "handlers"
+_PER_RESOURCE: Final = "perResource"
+_INDENT: Final = "indent"
+_RULES: Final = "rules"
+_RESPONSES: Final = "responses"
+_BODY_VALIDATION: Final = "bodyValidation"
+_FRAMEWORK_ETAG: Final = "frameworkEtag"
+_CATCH_ALL: Final = "catchAll"
+_LAYOUT: Final = "layout"
+_NAMING_KEYS: Final = ("suffixes", "escape", "enumCase")
+_KNOWN_KEYS: Final = (
+    _HANDLERS,
+    _INDENT,
+    _RULES,
+    _RESPONSES,
+    _BODY_VALIDATION,
+    _FRAMEWORK_ETAG,
+    _CATCH_ALL,
+    _LAYOUT,
+    *_NAMING_KEYS,
+)
+_BOOT_CHECK: Final = "bootCheck"
+_ACCESS_HOOKS: Final = "accessHooks"
+_ROUTE_HELPERS: Final = "routeHelpers"
+_NATIVE_DOCS: Final = "nativeDocs"
+_ARTEFACTS: Final = (_BOOT_CHECK, _ACCESS_HOOKS, _ROUTE_HELPERS, _NATIVE_DOCS)
+_STRICT_ROUTES: Final = "strict"
+_FRAMEWORK_ROUTES: Final = "frameworkRoutes"
+_HOOKS: Final = "hooks"
+_BOOT_CHECK_KEYS: Final = (_FRAMEWORK_ROUTES, _HOOKS)
+
+
+@dataclass(frozen=True, slots=True)
+class FastApiOptions:
+    rules: RulesMode
+    defaults: TargetDefaults
+    boot_check: BootCheckSwitches
+    route_helpers: bool
+    native_docs: bool
+
+
+def read_options(
+    options: Mapping[str, JsonValue], artefacts: Mapping[str, JsonValue], refusals: Refusals
+) -> FastApiOptions:
+    """The entry's options and artefacts; every refusal goes to `refusals`, and a refused value reads as its default."""
+    values = _OptionValues(options, refusals)
+    values.refuse_unknown()
+    values.refuse_unsupported()
+
+    return FastApiOptions(
+        rules=values.choice(_RULES, RulesMode.NATIVE),
+        defaults=TargetDefaults(
+            responses=values.choice(_RESPONSES, ResponsesMode.STRICT),
+            body_validation=values.flag(_BODY_VALIDATION, default=False),
+            framework_etag=values.choice(_FRAMEWORK_ETAG, FrameworkEtagMode.STRIP),
+            catch_all=values.flag(_CATCH_ALL, default=True),
+        ),
+        boot_check=_boot_check(artefacts.get(_BOOT_CHECK, True), refusals),
+        route_helpers=_read_artefacts(artefacts, refusals),
+        native_docs=artefacts.get(_NATIVE_DOCS) is True,
+    )
+
+
+class _OptionValues:
+    def __init__(self, options: Mapping[str, JsonValue], refusals: Refusals) -> None:
+        self._options = options
+        self._refusals = refusals
+
+    def refuse_unknown(self) -> None:
+        for key in self._options:
+            if key not in _KNOWN_KEYS:
+                self._refuse(
+                    "options.unknown",
+                    key,
+                    f"The option '{key}' is not one the fastapi target knows; it takes "
+                    f"'{"', '".join(_KNOWN_KEYS[:7])}'.",
+                    f"Remove '{key}' from the target's `options`.",
+                )
+
+    def refuse_unsupported(self) -> None:
+        handlers = self._options.get(_HANDLERS, _PER_RESOURCE)
+
+        if handlers != _PER_RESOURCE:
+            self._refuse(
+                "options.handlers.unsupported",
+                _HANDLERS,
+                f"The option 'handlers' is {handlers!r}; the fastapi target groups operations per resource only (ADR "
+                "0007 'perResource'), and 'perOperation' waits for an app that needs it.",
+                "Set 'handlers' to 'perResource', or leave it out.",
+            )
+
+        indent = self._options.get(_INDENT, INDENT_SPACES)
+
+        if indent != INDENT_SPACES or isinstance(indent, bool):
+            self._refuse(
+                "options.indent.unsupported",
+                _INDENT,
+                f"The option 'indent' is {indent!r}; the fastapi target writes the four spaces ruff formats with.",
+                f"Set 'indent' to {INDENT_SPACES}, or leave it out.",
+            )
+
+        if _LAYOUT in self._options:
+            self._refuse(
+                "options.layout.unsupported",
+                _LAYOUT,
+                "The option 'layout' is set; the fastapi target writes one package per api, the only layout it takes.",
+                "Remove 'layout' from the target's `options`.",
+            )
+
+        for key in _NAMING_KEYS:
+            if key in self._options:
+                self._refuse(
+                    "options.naming.unsupported",
+                    key,
+                    f"The naming option '{key}' is not taken by the fastapi target yet: it names Python with the "
+                    "defaults of ADR 0007, which the shared naming vectors test.",
+                    f"Remove '{key}' from the target's `options`.",
+                )
+
+    def choice[E: StrEnum](self, key: str, default: E) -> E:
+        value = self._options.get(key, default.value)
+
+        for case in type(default):
+            if case.value == value:
+                return case
+
+        allowed = "', '".join(case.value for case in type(default))
+        self._refuse(
+            f"options.{key}.invalid",
+            key,
+            f"The option '{key}' is {value!r}, not one of '{allowed}'.",
+            f"Set '{key}' to '{default.value}' (the default) or another listed value.",
+        )
+
+        return default
+
+    def flag(self, key: str, *, default: bool) -> bool:
+        value = self._options.get(key, default)
+
+        if isinstance(value, bool):
+            return value
+
+        self._refuse(
+            f"options.{key}.invalid",
+            key,
+            f"The option '{key}' is {value!r}, not true or false.",
+            f"Set '{key}' to true or false (the default is {str(default).lower()}).",
+        )
+
+        return default
+
+    def _refuse(self, code: str, key: str, message: str, fix: str) -> None:
+        self._refusals.add(code, message, fix, IrPlace(f"/options/{key}"))
+
+
+def _boot_check(value: JsonValue, refusals: Refusals) -> BootCheckSwitches:
+    """`bootCheck`: a boolean, or `{ frameworkRoutes, hooks }`; a value outside its set is refused and reads as the
+    default."""
+    at = IrPlace(f"/artefacts/{_BOOT_CHECK}")
+
+    if not isinstance(value, Mapping):
+        if not isinstance(value, bool):
+            _refuse_boot_check_value(_BOOT_CHECK, value, "true, false or an object", at, refusals)
+
+        enabled = value is not False
+        on = FrameworkRoutesCheck.ON if enabled else FrameworkRoutesCheck.OFF
+
+        return BootCheckSwitches(enabled=enabled, framework_routes=on, hooks=HooksCheck.ERROR)
+
+    for key in value:
+        if key not in _BOOT_CHECK_KEYS:
+            _refuse_boot_check_value(f"{_BOOT_CHECK}.{key}", value[key], "absent", at.below(key), refusals)
+
+    framework_routes = value.get(_FRAMEWORK_ROUTES, True)
+    routes_check = _framework_routes_check(framework_routes)
+    hooks_error = read_boot_check_hooks(value.get(_HOOKS, HOOKS_ERROR), at.below(_HOOKS), refusals)
+    hooks_check = HooksCheck.ERROR if hooks_error else HooksCheck.OFF
+
+    if routes_check is None:
+        allowed = f"true, false or '{_STRICT_ROUTES}'"
+        _refuse_boot_check_value(
+            f"{_BOOT_CHECK}.{_FRAMEWORK_ROUTES}", framework_routes, allowed, at.below(_FRAMEWORK_ROUTES), refusals
+        )
+
+    return BootCheckSwitches(enabled=True, framework_routes=routes_check or FrameworkRoutesCheck.ON, hooks=hooks_check)
+
+
+def _framework_routes_check(value: JsonValue) -> FrameworkRoutesCheck | None:
+    if value is True:
+        return FrameworkRoutesCheck.ON
+
+    if value is False:
+        return FrameworkRoutesCheck.OFF
+
+    return FrameworkRoutesCheck.STRICT if value == _STRICT_ROUTES else None
+
+
+def _refuse_boot_check_value(name: str, value: JsonValue, allowed: str, at: IrPlace, refusals: Refusals) -> None:
+    refusals.add(
+        f"artefacts.{name}.invalid",
+        f"The artefact '{name}' is {value!r}, not {allowed}.",
+        f"Set '{name}' to one of the listed values, or remove it for its default.",
+        at,
+    )
+
+
+def _read_artefacts(artefacts: Mapping[str, JsonValue], refusals: Refusals) -> bool:
+    """Refuses the artefacts the target does not take yet; returns whether the route helpers are on."""
+    for key, value in artefacts.items():
+        at = IrPlace(f"/artefacts/{key}")
+
+        if key not in _ARTEFACTS:
+            refusals.add(
+                "artefacts.unknown",
+                f"The artefact '{key}' is not one the fastapi target declares; it takes '{"', '".join(_ARTEFACTS)}'.",
+                f"Remove '{key}' from the entry's `artefacts`.",
+                at,
+            )
+        elif key == _ACCESS_HOOKS and value is False:
+            refusals.waiting("artefacts.accessHooks", "The artefact switch 'accessHooks: false'", at, Delivery.CONSUMER)
+
+    return artefacts.get(_ROUTE_HELPERS, True) is not False