seampact-django 1.0.0__tar.gz

seampact_django-1.0.0/.gitignore

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

seampact_django-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_django-1.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: seampact-django
+Version: 1.0.0
+Summary: The Django layer the seampact DRF and Ninja targets share: the URLconf and settings emitters and the Django runtime of generated code.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: django>=5.2
+Requires-Dist: seampact-codegen==1.0.0
+Provides-Extra: generate
+Requires-Dist: seampact-codegen[generate]==1.0.0; extra == 'generate'
+Description-Content-Type: text/markdown
+
+The Django layer the seampact DRF and Ninja targets share: the URLconf, settings and boundary emitters, the `seampact.django` app and the Django runtime of generated code.

seampact_django-1.0.0/README.md

@@ -0,0 +1 @@
+The Django layer the seampact DRF and Ninja targets share: the URLconf, settings and boundary emitters, the `seampact.django` app and the Django runtime of generated code.

seampact_django-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seampact-django"
+version = "1.0.0"
+description = "The Django layer the seampact DRF and Ninja targets share: the URLconf and settings emitters and the Django runtime of generated code."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["django>=5.2", "seampact-codegen==1.0.0"]
+classifiers = [
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+# What the emitters need; a production install of an app leaves it out.
+generate = ["seampact-codegen[generate]==1.0.0"]
+
+# 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_django-1.0.0/src/seampact/django/__init__.py

@@ -0,0 +1,2 @@
+"""The Django layer the DRF and Ninja targets share: the emitters of each api's URLconf, settings and boundary
+modules, the `seampact.django` app an app lists in `INSTALLED_APPS`, and the Django runtime of generated code."""

seampact_django-1.0.0/src/seampact/django/apps.py

@@ -0,0 +1,21 @@
+"""The `seampact.django` app, which an app lists in `INSTALLED_APPS` beside the generated boundaries (ADR 0027
+"Distributions"); it registers the system check and carries the `seampact_check` and `seampact_generate`
+commands."""
+
+from typing import Final
+
+from django.apps import AppConfig
+from django.core.checks import register
+
+APP_LABEL: Final = "seampact_django"
+
+
+class SeampactDjangoConfig(AppConfig):
+    name = "seampact.django"
+    label = APP_LABEL
+    verbose_name = "seampact"
+
+    def ready(self) -> None:
+        from seampact.django.checks import seampact_check
+
+        register(seampact_check)

seampact_django-1.0.0/src/seampact/django/checks.py

@@ -0,0 +1,17 @@
+"""The Django system check of the seampact apis (ADR 0027 "The system check and the boot check"): it runs on
+`check`, `runserver`, `migrate` and `test`, and reports each problem of the boot check as a `Warning` whose id is
+`seampact.<api>`, so a broken api never stops `migrate` or `shell`."""
+
+from collections.abc import Sequence
+
+from django.apps import AppConfig
+from django.core.checks import CheckMessage, Warning
+
+from seampact.django.runtime.boot_check import every_problem
+
+
+def seampact_check(app_configs: Sequence[AppConfig] | None = None, **kwargs: object) -> list[CheckMessage]:
+    return [
+        Warning(problem, hint="Run `python manage.py seampact_check` in CI.", id=f"seampact.{api}")
+        for api, problem in every_problem()
+    ]

seampact_django-1.0.0/src/seampact/django/emitters/__init__.py

@@ -0,0 +1,22 @@
+"""The emitters of the modules every Django target writes per api: the URLconf of the contract paths, the typed settings
+the api reads from `settings.SEAMPACT`, the boundary middleware's declaration, and the options every Django target
+reads. They need the `generate` extra."""
+
+from seampact.django.emitters.boundary_module import BoundaryBase, boundary_module
+from seampact.django.emitters.settings_module import SettingsKey, settings_module
+from seampact.django.emitters.target_options import DjangoTargetOptions, OptionReader, django_target_options
+from seampact.django.emitters.urls_module import ContractPath, contract_paths, routes_named_by_path, urls_module
+
+__all__ = [
+    "BoundaryBase",
+    "ContractPath",
+    "DjangoTargetOptions",
+    "OptionReader",
+    "SettingsKey",
+    "boundary_module",
+    "contract_paths",
+    "django_target_options",
+    "routes_named_by_path",
+    "settings_module",
+    "urls_module",
+]

seampact_django-1.0.0/src/seampact/django/emitters/boundary_module.py

@@ -0,0 +1,145 @@
+"""The `django` module of one api: the declaration of its boundary middleware (ADR 0027 "The boundary middleware"),
+which the app lists first in `MIDDLEWARE` as `<package>.django.<Api>Boundary`. It records the api, the version of
+the generator, the api's contract and settings keys, its handler resources, the framework majors `generate`
+accepted, the entry's `frameworkRoutes`, and the target options the boundary reads at run time, each a Python
+literal."""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Final
+
+from seampact.codegen.placement_lines import tuple_literal
+from seampact.codegen.printer import INDENT, PythonModule, bracketed, string_literal
+from seampact.ir.run.generator import FrameworkRoute, TargetEntry
+
+
+@dataclass(frozen=True, slots=True)
+class BoundaryBase:
+    """The runtime class a generated boundary extends, and the alias of its module."""
+
+    module: str
+    alias: str
+    name: str
+
+
+_DJANGO_RUNTIME: Final = "_django_runtime"
+SETTINGS_MODULE: Final = ".settings"
+DJANGO_BOUNDARY_BASE: Final = BoundaryBase("seampact.django.runtime", _DJANGO_RUNTIME, "ContractBoundary")
+
+
+def boundary_module(
+    api: str,
+    api_class: str,
+    generated_by: str,
+    handler_resources: Mapping[str, Sequence[str]],
+    run_time_options: Sequence[tuple[str, str]],
+    entry: TargetEntry,
+    base: BoundaryBase = DJANGO_BOUNDARY_BASE,
+    settings_module: str | None = SETTINGS_MODULE,
+    model_framework: tuple[str, str] | None = None,
+) -> str:
+    """`base` is the target's own boundary class when the target adds settings keys the boot check reads.
+    `settings_module` is None for a target that takes the api's handlers and hooks in code rather than from
+    `settings.SEAMPACT`; an empty `handler_resources` is left out likewise. `model_framework` is the package and major
+    the generated models are written for (Pydantic 2 on Ninja), accepted by that major alone."""
+    module = PythonModule(f"The Django boundary of api '{api}': list {api_class}Boundary first in MIDDLEWARE.")
+    base_module = module.imported(base.module, base.alias)
+    frameworks = _accepted_frameworks(_DJANGO_RUNTIME, entry) + _model_framework(_DJANGO_RUNTIME, model_framework)
+    framework_routes = _framework_routes(_DJANGO_RUNTIME, entry.framework_routes)
+
+    if frameworks or framework_routes:
+        module.imported(DJANGO_BOUNDARY_BASE.module, _DJANGO_RUNTIME)
+    contract = module.imported(".contract", "_contract")
+    settings_lines = (
+        [f"{INDENT}settings_keys = {module.imported(settings_module, '_settings')}.SETTINGS_KEYS"]
+        if settings_module is not None
+        else []
+    )
+    module.add_block(
+        [
+            f"class {api_class}Boundary({base_module}.{base.name}):",
+            f'{INDENT}"""The boundary middleware of api \'{api}\'."""',
+            "",
+            f"{INDENT}api = {string_literal(api)}",
+            f"{INDENT}generated_by = {string_literal(generated_by)}",
+            f"{INDENT}contract = {contract}.CONTRACT",
+            *settings_lines,
+            *(_handler_resources(module, handler_resources) if handler_resources else []),
+            *(f"{INDENT}{attribute} = {literal}" for attribute, literal in run_time_options),
+            *_tuple_attribute("frameworks", frameworks),
+            *_tuple_attribute("framework_routes", framework_routes),
+        ]
+    )
+
+    return module.text()
+
+
+def _handler_resources(module: PythonModule, handler_resources: Mapping[str, Sequence[str]]) -> list[str]:
+    """Each handler resource's settings key and the operations it serves, so a missing factory names them."""
+    typing = module.imported("typing", "_typing")
+    abc = module.imported("collections.abc", "_abc")
+    lines = [f"{INDENT}handler_resources: {typing}.ClassVar[{abc}.Mapping[str, {abc}.Sequence[str]]] = {{"]
+
+    for resource, operation_ids in handler_resources.items():
+        head = f"{string_literal(resource)}: "
+
+        if len(operation_ids) == 1:
+            lines.append(f"{INDENT * 2}{head}{tuple_literal(operation_ids)},")
+        else:
+            lines += bracketed(INDENT * 2, head, [string_literal(item) for item in operation_ids], ",")
+
+    return [*lines, f"{INDENT}}}"]
+
+
+def _accepted_frameworks(runtime: str, entry: TargetEntry) -> list[str]:
+    """The matrix row's frameworks, each by its unit, with the entry's `allowUntested` units and the tested minors."""
+    lines: list[str] = []
+
+    for framework in entry.matrix.frameworks if entry.matrix is not None else ():
+        arguments = [
+            f"package={string_literal(framework.package)}",
+            f"unit={runtime}.VersionUnit.{framework.unit.name}",
+            f"accepted={tuple_literal(framework.accepted_units(entry.allow_untested))}",
+        ]
+
+        if framework.tested_minors:
+            arguments.append(f"tested_minors={tuple_literal(framework.tested_minors)}")
+
+        lines += bracketed(INDENT * 2, f"{runtime}.AcceptedFramework", arguments, ",")
+
+    return lines
+
+
+def _model_framework(runtime: str, model_framework: tuple[str, str] | None) -> list[str]:
+    if model_framework is None:
+        return []
+
+    package, major = model_framework
+    arguments = [
+        f"package={string_literal(package)}",
+        f"unit={runtime}.VersionUnit.MAJOR",
+        f"accepted={tuple_literal((major,))}",
+    ]
+
+    return bracketed(INDENT * 2, f"{runtime}.AcceptedFramework", arguments, ",")
+
+
+def _framework_routes(runtime: str, routes: Sequence[FrameworkRoute]) -> list[str]:
+    lines: list[str] = []
+
+    for allowed in 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)}",
+        ]
+        lines += bracketed(INDENT * 2, f"{runtime}.FrameworkRouteRule", arguments, ",")
+
+    return lines
+
+
+def _tuple_attribute(name: str, items: list[str]) -> list[str]:
+    if not items:
+        return [f"{INDENT}{name} = ()"]
+
+    return [f"{INDENT}{name} = (", *items, f"{INDENT})"]

seampact_django-1.0.0/src/seampact/django/emitters/settings_module.py

@@ -0,0 +1,78 @@
+"""The `settings` module of one api (ADR 0027 "Settings"): the typed shape of `settings.SEAMPACT["<api>"]`, whose
+keys mirror `bind_<api>()`'s arguments, hooks and handler factories given as dotted paths, and `SETTINGS_KEYS`, the
+keys the boot check accepts. A target adds its own keys (DRF's `access`); an annotation may use the module's
+`_abc` (`collections.abc`) and `_typing` aliases."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from seampact.codegen.printer import INDENT, PythonModule, string_literal
+
+_RESPONSES_MODES = '_typing.Literal["strict", "warn"]'
+_DOTTED_PATHS_BY_NAME = "_abc.Mapping[str, str]"
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsKey:
+    name: str
+    annotation: str
+
+
+_SHARED_KEYS = (
+    SettingsKey("authenticate", _DOTTED_PATHS_BY_NAME),
+    SettingsKey("deciders", _DOTTED_PATHS_BY_NAME),
+    SettingsKey("scope_resolvers", _DOTTED_PATHS_BY_NAME),
+    SettingsKey("idempotency_store", "str"),
+    SettingsKey("on_unexpected_error", "str"),
+    SettingsKey("responses", _RESPONSES_MODES),
+    SettingsKey("body_validation", "bool"),
+    SettingsKey("public_origin", "str"),
+)
+
+
+def settings_module(api: str, api_class: str, handler_owners: Sequence[str], target_keys: Sequence[SettingsKey]) -> str:
+    """`handler_owners` are the attribute names of the api's handler groups, one factory each."""
+    module = PythonModule(f"The settings of api '{api}', read from settings.SEAMPACT[\"{api}\"].")
+    typing = module.imported("typing", "_typing")
+    module.imported("collections.abc", "_abc")
+    operations = SettingsKey("operations", f"_abc.Mapping[str, {api_class}OperationSettings]")
+    keys = [
+        SettingsKey("handlers", f"{typing}.Required[{api_class}HandlerSettings]"),
+        *_SHARED_KEYS,
+        operations,
+        *target_keys,
+    ]
+
+    module.add_block(
+        [
+            f"class {api_class}HandlerSettings({typing}.TypedDict):",
+            f'{INDENT}"""The dotted path of each handler factory, which builds the handlers from the HttpRequest."""',
+            "",
+            *(f"{INDENT}{owner}: str" for owner in handler_owners),
+        ]
+    )
+    module.add_block(
+        [
+            f"class {api_class}OperationSettings({typing}.TypedDict, total=False):",
+            f'{INDENT}"""What one operation sets over the api\'s settings."""',
+            "",
+            f"{INDENT}responses: {_RESPONSES_MODES}",
+        ]
+    )
+    module.add_block(
+        [
+            f"class {api_class}Settings({typing}.TypedDict, total=False):",
+            f'{INDENT}"""The value of settings.SEAMPACT["{api}"]."""',
+            "",
+            *(f"{INDENT}{key.name}: {key.annotation}" for key in keys),
+        ]
+    )
+    module.add_block(
+        [
+            f"SETTINGS_KEYS: {typing}.Final = (",
+            *(f"{INDENT}{string_literal(key.name)}," for key in keys),
+            ")",
+        ]
+    )
+
+    return module.text()

seampact_django-1.0.0/src/seampact/django/emitters/target_options.py

@@ -0,0 +1,212 @@
+"""The options and artefact switches every Django target reads (ADR 0026 "Options and registration", ADR 0027 "Options
+and registration"), each unknown key and each value the target does not take refused by name. The run-time defaults
+(`responses`, `bodyValidation`, `frameworkEtag`, `catchAll`, the boot check's parts) go into the boundary's
+declaration; `routeHelpers` decides the `routes` module. A target reads its own keys (`rules`, Ninja's `views`) with
+`OptionReader`."""
+
+import json
+from collections.abc import Mapping, Sequence
+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.refusals import Delivery, IrPlace, Refusals
+from seampact.codegen.runtime.reply_verdict import FrameworkEtagMode, ResponsesMode
+from seampact.ir.config.json_value import JsonValue
+
+_HANDLERS: Final = "handlers"
+_PER_RESOURCE: Final = "perResource"
+_INDENT: Final = "indent"
+_INDENT_SPACES: Final = 4
+_NAMING_KEYS: Final = ("suffixes", "escape", "enumCase")
+_LAYOUT: Final = "layout"
+_SHARED_OPTIONS: Final = ("responses", "bodyValidation", "frameworkEtag", "catchAll")
+_ROUTE_HELPERS: Final = "routeHelpers"
+_BOOT_CHECK: Final = "bootCheck"
+_ACCESS_HOOKS: Final = "accessHooks"
+_BOOT_CHECK_PARTS: Final = ("frameworkRoutes", "hooks")
+
+
+@dataclass(frozen=True, slots=True)
+class BootCheck:
+    """The boot check, on unless `bootCheck: false`; its framework-route and hook parts each turned off alone."""
+
+    enabled: bool = True
+    framework_routes: bool = True
+    hooks: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class DjangoTargetOptions:
+    responses: ResponsesMode = ResponsesMode.STRICT
+    body_validation: bool = False
+    framework_etag: FrameworkEtagMode = FrameworkEtagMode.STRIP
+    catch_all: bool = True
+    route_helpers: bool = True
+    boot_check: BootCheck = BootCheck()
+
+    def run_time_options(self) -> list[tuple[str, str]]:
+        """Each run-time default as the boundary declaration's attribute and its Python literal."""
+        return [
+            ("responses", json.dumps(self.responses.value)),
+            ("body_validation", repr(self.body_validation)),
+            ("framework_etag", json.dumps(self.framework_etag.value)),
+            ("catch_all", repr(self.catch_all)),
+            ("boot_check", repr(self.boot_check.enabled)),
+            ("boot_check_framework_routes", repr(self.boot_check.framework_routes)),
+            ("boot_check_hooks", repr(self.boot_check.hooks)),
+        ]
+
+
+def django_target_options(
+    target: str,
+    own_options: Sequence[str],
+    options: Mapping[str, JsonValue],
+    artefacts: Mapping[str, JsonValue],
+    refusals: Refusals,
+    *,
+    own_artefacts: Sequence[str] = (),
+) -> DjangoTargetOptions:
+    """The shared options and artefacts of `target`; `own_options` are the keys the target reads itself, and
+    `own_artefacts` the `true` or `false` switches it reads itself."""
+    known_options = (_HANDLERS, _INDENT, *own_options, *_SHARED_OPTIONS)
+    reader = OptionReader(options, refusals)
+
+    for key in options:
+        if key in _NAMING_KEYS:
+            reader.refuse(
+                "options.naming.unsupported",
+                key,
+                f"The naming option '{key}' is not taken by the {target} target: it names Python with the defaults of "
+                "ADR 0007, which the shared naming vectors test.",
+                f"Remove '{key}' from the target's `options`.",
+            )
+        elif key == _LAYOUT:
+            reader.refuse(
+                "options.layout.unsupported",
+                key,
+                f"The option 'layout' is set; the {target} target writes one package per api, the only layout it "
+                "takes.",
+                "Remove 'layout' from the target's `options`.",
+            )
+        elif key not in known_options:
+            reader.refuse(
+                "options.unknown",
+                key,
+                f"The option '{key}' is not one the {target} target knows; it takes '{"', '".join(known_options)}'.",
+                f"Remove '{key}' from the target's `options`.",
+            )
+
+    if options.get(_HANDLERS, _PER_RESOURCE) != _PER_RESOURCE:
+        refusals.waiting(
+            "options.handlers",
+            f"The option 'handlers: {_shown(options[_HANDLERS])}'",
+            _at(_HANDLERS),
+            Delivery.CONSUMER,
+        )
+
+    if options.get(_INDENT, _INDENT_SPACES) != _INDENT_SPACES:
+        refusals.waiting(
+            "options.indent", f"The option 'indent: {_shown(options[_INDENT])}'", _at(_INDENT), Delivery.CONSUMER
+        )
+
+    return DjangoTargetOptions(
+        responses=reader.choice("responses", ResponsesMode.STRICT),
+        body_validation=reader.flag("bodyValidation", default=False),
+        framework_etag=reader.choice("frameworkEtag", FrameworkEtagMode.STRIP),
+        catch_all=reader.flag("catchAll", default=True),
+        route_helpers=_artefacts(target, artefacts, own_artefacts, refusals),
+        boot_check=_boot_check(artefacts.get(_BOOT_CHECK, True), refusals),
+    )
+
+
+def _artefacts(
+    target: str, artefacts: Mapping[str, JsonValue], own_artefacts: Sequence[str], refusals: Refusals
+) -> bool:
+    """Refuses each switch the target does not take, and returns `routeHelpers`."""
+    for key, value in artefacts.items():
+        if key in own_artefacts and isinstance(value, bool):
+            continue
+
+        at = IrPlace(f"/artefacts/{key}")
+
+        if key == _ACCESS_HOOKS and value is False:
+            refusals.waiting(
+                "artefacts.accessHooks", "Native access instead of hooks ('accessHooks: false')", at, Delivery.CONSUMER
+            )
+        elif key not in (_ROUTE_HELPERS, _BOOT_CHECK, _ACCESS_HOOKS) or not _is_switch(key, value):
+            refusals.add(
+                "artefacts.unknown",
+                f"The artefact switch '{key}: {_shown(value)}' is not one the {target} target takes.",
+                f"Remove '{key}' from the entry's `artefacts`; the {target} target takes "
+                f"'{"', '".join((_ROUTE_HELPERS, _BOOT_CHECK, *own_artefacts))}' and '{_ACCESS_HOOKS}: true'.",
+                at,
+            )
+
+    return artefacts.get(_ROUTE_HELPERS, True) is not False
+
+
+def _is_switch(key: str, value: JsonValue) -> bool:
+    if key == _BOOT_CHECK and isinstance(value, Mapping):
+        return all(part in _BOOT_CHECK_PARTS for part in value)
+
+    return isinstance(value, bool)
+
+
+def _boot_check(value: JsonValue, refusals: Refusals) -> BootCheck:
+    if not isinstance(value, Mapping):
+        return BootCheck(enabled=value is not False)
+
+    hooks = read_boot_check_hooks(value.get("hooks", HOOKS_ERROR), IrPlace("/artefacts/bootCheck/hooks"), refusals)
+
+    return BootCheck(framework_routes=value.get("frameworkRoutes", True) is not False, hooks=hooks)
+
+
+class OptionReader:
+    """Reads one option of an entry, refusing by name a value outside its set."""
+
+    def __init__(self, options: Mapping[str, JsonValue], refusals: Refusals) -> None:
+        self._options = options
+        self._refusals = refusals
+
+    def refuse(self, code: str, key: str, message: str, fix: str) -> None:
+        self._refusals.add(code, message, fix, _at(key))
+
+    def choice[E: StrEnum](self, key: str, default: E) -> E:
+        value = self._options.get(key, default.value)
+        chosen = next((member for member in type(default) if member.value == value), None)
+
+        if chosen is not None:
+            return chosen
+
+        allowed = "', '".join(member.value for member in type(default))
+        self.refuse(
+            f"options.{key}.invalid",
+            key,
+            f"The option '{key}' is {_shown(value)}, 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 {_shown(value)}, not true or false.",
+            f"Set '{key}' to true or false (the default is {json.dumps(default)}).",
+        )
+        return default
+
+
+def _at(key: str) -> IrPlace:
+    return IrPlace(f"/options/{key}")
+
+
+def _shown(value: JsonValue) -> str:
+    return json.dumps(value, ensure_ascii=False)

seampact_django-1.0.0/src/seampact/django/emitters/urls_module.py

@@ -0,0 +1,78 @@
+"""The URLconf of one api (ADR 0027 "Routes"): one `path()` entry per contract path, which the app includes at `""`
+in its root URLconf. Each placeholder uses Django's `str` converter, so it takes one whole segment, and is named
+`path_<attribute>`, so a parameter named `request` or `self` never meets the view's own arguments. Per path depth,
+literal segments come before placeholders, as the route table orders them. An entry is named
+`seampact.<api>.<operationId>` after the path's first operation, and points to the view the target names."""
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, replace
+from typing import Final
+
+from seampact.codegen.printer import INDENT, PythonModule, fits, string_literal
+from seampact.codegen.routes import RouteEntry
+
+PATH_ARGUMENT_PREFIX: Final = "path_"
+"""The prefix of each converter name: the view receives the value of parameter attribute `a` as `path_a`."""
+
+
+@dataclass(frozen=True, slots=True)
+class ContractPath:
+    """A contract path and the route entries of the operations it serves, in the api's operation order."""
+
+    entries: tuple[RouteEntry, ...]
+
+    @property
+    def first(self) -> RouteEntry:
+        return self.entries[0]
+
+    def django_route(self) -> str:
+        """The `path()` route: no leading slash, `<str:path_attribute>` for each placeholder."""
+        return "/".join(
+            segment.text if segment.attribute is None else f"<str:{PATH_ARGUMENT_PREFIX}{segment.attribute}>"
+            for segment in self.first.segments
+        )
+
+
+def contract_paths(routes: Sequence[RouteEntry], operation_order: Sequence[str]) -> list[ContractPath]:
+    """The api's paths in route order, each with its operations in `operation_order`."""
+    position = {operation_id: index for index, operation_id in enumerate(operation_order)}
+    grouped: dict[str, list[RouteEntry]] = {}
+
+    for route in routes:
+        grouped.setdefault(route.contract_path, []).append(route)
+
+    return [
+        ContractPath(tuple(sorted(entries, key=lambda entry: position[entry.operation_id])))
+        for entries in grouped.values()
+    ]
+
+
+def routes_named_by_path(paths: Sequence[ContractPath]) -> list[RouteEntry]:
+    """Each operation's route under the name the URLconf registers for its path, for `<Api>RouteNames`."""
+    return [replace(entry, name=contract_path.first.name) for contract_path in paths for entry in contract_path.entries]
+
+
+def urls_module(api: str, paths: Sequence[ContractPath], view_of: Callable[[PythonModule, ContractPath], str]) -> str:
+    """`view_of` imports the target's views module into the URLconf and returns the view expression of a path."""
+    module = PythonModule(f"The URL patterns of api '{api}': include them at \"\" in the root URLconf.")
+    urls = module.imported("django.urls", "_urls")
+    lines = ["urlpatterns = ["]
+
+    for contract_path in paths:
+        arguments = [
+            string_literal(contract_path.django_route()),
+            view_of(module, contract_path),
+            f"name={string_literal(contract_path.first.name)}",
+        ]
+        single = f"{INDENT}{urls}.path({', '.join(arguments)}),"
+
+        if fits(single):
+            lines.append(single)
+            continue
+
+        lines += [f"{INDENT}{urls}.path(", *(f"{INDENT * 2}{argument}," for argument in arguments), f"{INDENT}),"]
+
+    lines.append("]")
+    module.add_block(lines)
+
+    return module.text()