seampact-fastapi 1.0.0__py3-none-any.whl

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/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/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

seampact/fastapi/placement_module.py

@@ -0,0 +1,287 @@
+"""The `fastapi` module of an api's package (ADR 0026 "Placement" and "Routes"): `GENERATED_BY`, the api's placement
+(its contract routes in registration order, literal segments first, under the entry's `mount`; its contract exception
+base; the run-time defaults of the target options; the boot check switches and the entry's framework routes), the
+`<Api>HandlerFactories` the app fills with one FastAPI dependency per endpoints protocol, one coroutine per operation
+calling its handler method, and `bind_<api>()`, which declares each contract route on the api's router and hands it
+to the runtime."""
+
+from collections.abc import Mapping, Sequence
+from typing import Final
+
+from seampact.codegen.native_docs_file import NATIVE_DOCS_FILE
+from seampact.codegen.placement_lines import (
+    add_operation_call,
+    credentials_types,
+    operation_types_arguments,
+    tuple_literal,
+    unexpected_error_listener,
+)
+from seampact.codegen.printer import INDENT, PythonModule, bracketed, string_literal
+from seampact.codegen.pydantic_layout import ApiLayout
+from seampact.codegen.pydantic_models import PYDANTIC_MAJOR, PYDANTIC_PACKAGE
+from seampact.codegen.routes import RouteEntry
+from seampact.codegen.runtime import RUNTIME_VERSION
+from seampact.codegen.source_lines import with_local_imports
+from seampact.fastapi.options import FastApiOptions
+from seampact.ir.model import ContractIR
+from seampact.ir.run.generator import FrameworkDocs, TargetEntry
+
+_RUNTIME: Final = "_runtime"
+_HOOKS: Final = "_hooks"
+_ABC: Final = "_abc"
+# Each operation's coroutine: no module alias starts so, whatever the operation's name.
+_CALL_PREFIX: Final = "_call_"
+_CONTRACT_MODULE: Final = "contract"
+_SCHEMAS_MODULE: Final = "schemas"
+_BIND_DOC: Final = "Places api '{api}' in the app; call it last, after its own middleware and exception handlers."
+
+
+def placement_module(
+    ir: ContractIR,
+    layout: ApiLayout,
+    proof_models: Mapping[str, str],
+    routes: Sequence[RouteEntry],
+    options: FastApiOptions,
+    entry: TargetEntry,
+) -> str:
+    """`proof_models` names the `<Op>Proofs` class of the schemas module for each operation whose body has proofs."""
+    module = PythonModule(f"The FastAPI placement of api '{ir.api.id}'.")
+    module.imported("collections.abc", _ABC)
+    module.imported("dataclasses", "_dataclasses")
+
+    if options.native_docs:
+        module.imported("pathlib", "_pathlib")
+
+    module.imported("typing", "_typing")
+    module.imported("seampact.fastapi.runtime", _RUNTIME)
+    module.imported("seampact.hooks", _HOOKS)
+    root_names = [layout.contract_error, *(credentials.class_name for credentials in layout.credentials.values())]
+    operations = [operation for operation in ir.operations if operation.id in layout.operations]
+
+    for operation in operations:
+        names = layout.operations[operation.id]
+        root_names += [names.endpoints, names.request, names.result, names.errors, *names.responses.values()]
+
+    head = [f"GENERATED_BY: _typing.Final = {string_literal(RUNTIME_VERSION)}"]
+    local_modules = [_CONTRACT_MODULE, _SCHEMAS_MODULE] if proof_models else [_CONTRACT_MODULE]
+    module.add_block(with_local_imports(local_modules, root_names, head))
+    module.add_block(_placement(ir, layout, routes, options, entry))
+    module.add_block(_handler_factories(layout))
+    module.add_block(unexpected_error_listener(ir.api.id, _HOOKS, layout))
+
+    for operation in operations:
+        names = layout.operations[operation.id]
+        module.add_block(
+            [
+                *bracketed(
+                    "",
+                    f"async def {_CALL_PREFIX}{names.method}",
+                    [f"endpoints: {names.endpoints}", f"request: {names.request}"],
+                    f" -> {names.result}:",
+                ),
+                f"{INDENT}return await {_RUNTIME}.call_handler(endpoints.{names.method}, request)",
+            ]
+        )
+
+    module.add_block(_bind(ir, layout, proof_models, routes))
+
+    return module.text()
+
+
+def _placement(
+    ir: ContractIR, layout: ApiLayout, routes: Sequence[RouteEntry], options: FastApiOptions, entry: TargetEntry
+) -> list[str]:
+    route_lines: list[str] = []
+
+    for route in routes:
+        methods = tuple_literal(route.methods)
+        arguments = [
+            string_literal(route.operation_id),
+            string_literal(route.name),
+            string_literal(route.path()),
+            methods,
+        ]
+        route_lines += bracketed(INDENT * 2, f"{_RUNTIME}.OperationRoute", arguments, ",")
+
+    framework_routes: list[str] = []
+
+    for allowed in entry.framework_routes:
+        arguments = [
+            f"path={string_literal(allowed.path)}",
+            f"method={'None' if allowed.method is None else string_literal(allowed.method)}",
+            f"reason={string_literal(allowed.reason)}",
+        ]
+        framework_routes += bracketed(INDENT * 2, f"{_RUNTIME}.FrameworkRouteRule", arguments, ",")
+
+    boot = options.boot_check
+    defaults = options.defaults
+
+    return [
+        f"PLACEMENT: _typing.Final = {_RUNTIME}.ApiPlacement(",
+        f"{INDENT}api={string_literal(ir.api.id)},",
+        f"{INDENT}generated_by=GENERATED_BY,",
+        f"{INDENT}mount={string_literal(entry.mount or '')},",
+        f"{INDENT}routes=(",
+        *route_lines,
+        f"{INDENT}),",
+        f"{INDENT}error_base={layout.contract_error},",
+        *bracketed(
+            INDENT,
+            f"defaults={_RUNTIME}.TargetDefaults",
+            [
+                f"responses={_RUNTIME}.ResponsesMode.{defaults.responses.name}",
+                f"body_validation={defaults.body_validation}",
+                f"framework_etag={_RUNTIME}.FrameworkEtagMode.{defaults.framework_etag.name}",
+                f"catch_all={defaults.catch_all}",
+            ],
+            ",",
+        ),
+        *bracketed(
+            INDENT,
+            f"boot_check={_RUNTIME}.BootCheckSwitches",
+            [
+                f"enabled={boot.enabled}",
+                f"framework_routes={_RUNTIME}.FrameworkRoutesCheck.{boot.framework_routes.name}",
+                f"hooks={_RUNTIME}.HooksCheck.{boot.hooks.name}",
+            ],
+            ",",
+        ),
+        *(
+            [f"{INDENT}framework_routes=(),"]
+            if not framework_routes
+            else [f"{INDENT}framework_routes=(", *framework_routes, f"{INDENT}),"]
+        ),
+        f"{INDENT}frameworks=(",
+        *_accepted_frameworks(entry),
+        f"{INDENT}),",
+        *credentials_types(_RUNTIME, layout),
+        *_framework_document(options, entry),
+        ")",
+    ]
+
+
+def _framework_document(options: FastApiOptions, entry: TargetEntry) -> list[str]:
+    """`frameworkDocs: off` and `nativeDocs`, each written only when the entry asks for it."""
+    lines: list[str] = []
+
+    if entry.framework_docs is FrameworkDocs.OFF:
+        lines.append(f"{INDENT}framework_docs={_RUNTIME}.FrameworkDocs.OFF,")
+
+    if options.native_docs:
+        native_docs_path = f"_pathlib.Path(__file__).with_name({string_literal(NATIVE_DOCS_FILE)})"
+        lines.append(f"{INDENT}native_docs={_RUNTIME}.read_native_docs({native_docs_path}),")
+
+    return lines
+
+
+def _accepted_frameworks(entry: TargetEntry) -> list[str]:
+    """The matrix row's frameworks (FastAPI by minor, Starlette by major) with the entry's `allowUntested` units, then
+    Pydantic 2, which the generated models are written for."""
+    accepted = [
+        (framework.package, framework.unit.name, framework.accepted_units(entry.allow_untested))
+        for framework in (entry.matrix.frameworks if entry.matrix is not None else ())
+    ]
+    accepted.append((PYDANTIC_PACKAGE, "MAJOR", (PYDANTIC_MAJOR,)))
+    lines: list[str] = []
+
+    for package, unit, units in accepted:
+        arguments = [
+            f"package={string_literal(package)}",
+            f"unit={_RUNTIME}.VersionUnit.{unit}",
+            f"accepted={tuple_literal(units)}",
+        ]
+        lines += bracketed(INDENT * 2, f"{_RUNTIME}.AcceptedFramework", arguments, ",")
+
+    return lines
+
+
+def _handler_factories(layout: ApiLayout) -> list[str]:
+    lines = [
+        "@_dataclasses.dataclass(frozen=True, slots=True, kw_only=True)",
+        f"class {layout.handler_factories}:",
+        f'{INDENT}"""The FastAPI dependency that builds each endpoints protocol\'s handlers; None fails the boot."""',
+        "",
+    ]
+    lines += [
+        f"{INDENT}{attribute}: {_RUNTIME}.Factory[{endpoints}] | None"
+        for endpoints, attribute in layout.endpoints_owners().items()
+    ]
+
+    return lines
+
+
+def _bind(
+    ir: ContractIR, layout: ApiLayout, proof_models: Mapping[str, str], routes: Sequence[RouteEntry]
+) -> list[str]:
+    def factories(hook: str) -> str:
+        return f"{_ABC}.Mapping[str, {_RUNTIME}.Factory[{_HOOKS}.{hook}]] | None = None"
+
+    parameters = [
+        f"target: {_RUNTIME}.BindTarget",
+        "*",
+        f"handlers: {layout.handler_factories}",
+        f"app: {_RUNTIME}.App | None = None",
+        f"authenticate: {factories('AuthenticateHook')}",
+        f"deciders: {factories('DecideHook')}",
+        f"scope_resolvers: {factories('ResolveScopeHook')}",
+        f"idempotency_store: {_RUNTIME}.Factory[{_HOOKS}.IdempotencyStore] | None = None",
+        f"on_unexpected_error: {_RUNTIME}.Factory[{layout.unexpected_error_listener}] | None = None",
+        f"responses: {_RUNTIME}.ResponsesMode | None = None",
+        "body_validation: bool | None = None",
+        f"operations: {_ABC}.Mapping[str, {_RUNTIME}.OperationSettings] | None = None",
+        "public_origin: str | None = None",
+    ]
+    head = [
+        *bracketed("", f"def {layout.bind_function}", parameters, " -> None:"),
+        f'{INDENT}"""{_BIND_DOC.format(api=ir.api.id)}"""',
+    ]
+    lines: list[str] = []
+
+    for route in routes:
+        lines += _add_operation(layout, route.operation_id, proof_models.get(route.operation_id))
+
+    hooks = [
+        "authenticate=authenticate or {}",
+        "deciders=deciders or {}",
+        "scope_resolvers=scope_resolvers or {}",
+        "idempotency_store=idempotency_store",
+        "on_unexpected_error=on_unexpected_error",
+    ]
+    settings = [
+        "responses=responses",
+        "body_validation=body_validation",
+        "operations=operations or {}",
+        "public_origin=public_origin",
+    ]
+
+    return [
+        *head,
+        f"{INDENT}binding = {_RUNTIME}.api_binding(",
+        f"{INDENT * 2}PLACEMENT,",
+        f"{INDENT * 2}_{_CONTRACT_MODULE}.CONTRACT,",
+        f"{INDENT * 2}target,",
+        f"{INDENT * 2}app=app,",
+        *bracketed(INDENT * 2, f"hooks={_RUNTIME}.HookFactories", hooks, ","),
+        *bracketed(INDENT * 2, f"settings={_RUNTIME}.RunSettings", settings, ","),
+        f"{INDENT})",
+        "",
+        *lines,
+        "",
+        f"{INDENT}{_RUNTIME}.bind_api(binding)",
+    ]
+
+
+def _add_operation(layout: ApiLayout, operation_id: str, proof_model: str | None) -> list[str]:
+    """One `add_operation` call, split as ruff splits it: the call on one line when it fits, else one argument per
+    line, the operation's types a nested call split the same way."""
+    names = layout.operations[operation_id]
+    proofs = None if proof_model is None else f"_{_SCHEMAS_MODULE}.{proof_model}"
+    types = operation_types_arguments(layout, operation_id, proofs)
+    arguments = [
+        "binding",
+        string_literal(operation_id),
+        f"handlers.{names.owner_attribute}",
+        f"{_CALL_PREFIX}{names.method}",
+    ]
+
+    return add_operation_call(_RUNTIME, arguments, types)

seampact/fastapi/runtime/__init__.py

@@ -0,0 +1,63 @@
+"""The FastAPI placement runtime the generated code imports (ADR 0026 "What the generated code depends on"): the
+declarations of one api's placement, its binding, its contract routes with the access and input dependencies, the
+boundary middleware, the exception map and the boot check. The framework-neutral steps come from
+`seampact.codegen.runtime`."""
+
+from seampact.codegen.runtime.access_steps import CredentialsType
+from seampact.codegen.runtime.framework_routes import FrameworkRouteRule
+from seampact.codegen.runtime.framework_versions import AcceptedFramework, VersionUnit
+from seampact.codegen.runtime.native_docs import NativeDocsError, read_native_docs
+from seampact.codegen.runtime.reply_verdict import FrameworkEtagMode, ResponsesMode
+from seampact.codegen.runtime.run_settings import OperationSettings, OperationTypes, RunSettings
+from seampact.fastapi.runtime.api_binding import ApiBinding, BindingError, api_binding
+from seampact.fastapi.runtime.binding import bind_api
+from seampact.fastapi.runtime.boot_check import BootCheckError
+from seampact.fastapi.runtime.boundary import ContractBoundary
+from seampact.fastapi.runtime.handler_call import call_handler
+from seampact.fastapi.runtime.native_docs import FrameworkDocs
+from seampact.fastapi.runtime.placement import (
+    ApiPlacement,
+    App,
+    BindTarget,
+    BootCheckSwitches,
+    Factory,
+    FrameworkRoutesCheck,
+    HookFactories,
+    HooksCheck,
+    OperationRoute,
+    TargetDefaults,
+)
+from seampact.fastapi.runtime.routes import add_operation
+
+__all__ = [
+    "AcceptedFramework",
+    "ApiBinding",
+    "ApiPlacement",
+    "App",
+    "BindTarget",
+    "BindingError",
+    "BootCheckError",
+    "BootCheckSwitches",
+    "ContractBoundary",
+    "CredentialsType",
+    "Factory",
+    "FrameworkDocs",
+    "FrameworkEtagMode",
+    "FrameworkRouteRule",
+    "FrameworkRoutesCheck",
+    "HookFactories",
+    "HooksCheck",
+    "NativeDocsError",
+    "OperationRoute",
+    "OperationSettings",
+    "OperationTypes",
+    "ResponsesMode",
+    "RunSettings",
+    "TargetDefaults",
+    "VersionUnit",
+    "add_operation",
+    "api_binding",
+    "bind_api",
+    "call_handler",
+    "read_native_docs",
+]