seampact-drf 1.0.0__tar.gz

seampact_drf-1.0.0/.gitignore

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

seampact_drf-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_drf-1.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: seampact-drf
+Version: 1.0.0
+Summary: The seampact Django REST Framework target: its generator and the runtime of the code it generates.
+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: djangorestframework>=3.18
+Requires-Dist: seampact-django==1.0.0
+Provides-Extra: generate
+Requires-Dist: seampact-django[generate]==1.0.0; extra == 'generate'
+Description-Content-Type: text/markdown
+
+The seampact Django REST Framework target: the `seampact-drf` generator, found through the `seampact.generators` entry point, and the DRF runtime of the code it generates.

seampact_drf-1.0.0/README.md

@@ -0,0 +1 @@
+The seampact Django REST Framework target: the `seampact-drf` generator, found through the `seampact.generators` entry point, and the DRF runtime of the code it generates.

seampact_drf-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seampact-drf"
+version = "1.0.0"
+description = "The seampact Django REST Framework target: its generator and the runtime of the code it generates."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["djangorestframework>=3.18", "seampact-django==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 generator needs; a production install of an app leaves it out.
+generate = ["seampact-django[generate]==1.0.0"]
+
+# The target `use: pypi:seampact-drf` names; `seampact generate` finds it through this group.
+[project.entry-points."seampact.generators"]
+drf = "seampact.drf.generator:DrfGenerator"
+
+# 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-django = { workspace = true }

seampact_drf-1.0.0/src/seampact/drf/__init__.py

@@ -0,0 +1,3 @@
+"""The Django REST Framework target: the `seampact-drf` generator, found through the `seampact.generators` entry
+point, its emitters (frozen dataclass types, operation types and handler protocols, serializers and `APIView`
+declarations), and the DRF runtime of the code it generates."""

seampact_drf-1.0.0/src/seampact/drf/api_layout.py

@@ -0,0 +1,179 @@
+"""The Python names of one api's operation types on the DRF target: per operation its request, input and input
+parts, scopes, responses, page, errors and result; per resource (or surface, for an operation without one) its
+handler protocol and the settings key of its handler factory; per error code its exception and its factory method.
+Every name of the `operations` module is claimed once; a name taken twice is refused, naming both."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Final
+
+from seampact.codegen.credentials_classes import CredentialsNames, identity_credentials
+from seampact.codegen.refusals import IrPlace, Refusals
+from seampact.ir.model import ContractIR, CredentialIdentity, Operation, Param, SchemaPrincipal, SignedIdentity
+from seampact.ir.naming import IrName, NameSource, NamingRole, python_identifier, segments_of
+
+_BOUNDARY_HEADER_DERIVATIONS: Final = frozenset({"identity.authenticate"})
+_BOUNDARY_HEADER_DERIVATION_PREFIXES: Final = ("csrf.",)
+
+
+@dataclass(frozen=True, slots=True)
+class OperationNames:
+    request: str
+    input: str
+    path: str | None
+    query: str | None
+    headers: str | None
+    scopes: str | None
+    result: str
+    errors: str
+    page: str | None
+    method: str
+    owner: "HandlerOwner"
+    responses: Mapping[int, str]
+
+
+@dataclass(frozen=True, slots=True)
+class HandlerOwner:
+    """A handler protocol (`TasksEndpoints`) and the settings key of its factory (`tasks`)."""
+
+    protocol: str
+    key: str
+
+
+@dataclass(slots=True)
+class ApiLayout:
+    api_class: str
+    operations: dict[str, OperationNames] = field(default_factory=dict)
+    owners: dict[tuple[str, ...], HandlerOwner] = field(default_factory=dict)
+    error_classes: dict[str, str] = field(default_factory=dict)
+    error_factories: dict[str, str] = field(default_factory=dict)
+    credentials: dict[str, CredentialsNames] = field(default_factory=dict)
+
+
+def api_layout(ir: ContractIR, refusals: Refusals) -> ApiLayout:
+    layout = ApiLayout(python_identifier(IrName(tuple(ir.api.name.segments), NamingRole.SCHEMA)))
+    claim = NameClaims("operations", refusals)
+
+    claim.name(f"{layout.api_class}ContractError", IrPlace("/api/name"))
+
+    for code in sorted(ir.errors):
+        at = IrPlace(f"/errors/{code}")
+        segments = segments_of(code, NameSource.NAME, None, None)
+
+        if not segments:
+            refusals.inconsistent("error.code.no-segment", f"The error code '{code}' has no name segment", at)
+            continue
+
+        layout.error_classes[code] = claim.name(python_identifier(IrName(tuple(segments), NamingRole.ERROR)), at)
+        layout.error_factories[code] = python_identifier(IrName(tuple(segments), NamingRole.MEMBER))
+
+    for index, operation in enumerate(ir.operations):
+        at = IrPlace(f"/operations/{index}", operation.id)
+        owner = _owner(ir, operation)
+
+        if owner is None:
+            refusals.inconsistent(
+                "endpoints.owner.no-segment",
+                f"The operation '{operation.id}' has no resource or surface that gives a name segment",
+                at.below("surface"),
+            )
+            continue
+
+        if owner not in layout.owners:
+            protocol = claim.name(python_identifier(IrName(owner, NamingRole.ENDPOINTS)), at.below("name"))
+            layout.owners[owner] = HandlerOwner(protocol, python_identifier(IrName(owner, NamingRole.MEMBER)))
+
+        layout.operations[operation.id] = _operation_names(operation, layout.owners[owner], claim, at.below("name"))
+
+    layout.credentials = identity_credentials(ir, layout.operations, claim.owned_name, refusals)
+
+    return layout
+
+
+def _operation_names(operation: Operation, owner: HandlerOwner, claim: "NameClaims", at: IrPlace) -> OperationNames:
+    segments = tuple(operation.name.segments)
+
+    def type_name(role: NamingRole, *words: str, status: int | None = None) -> str:
+        return claim.name(python_identifier(IrName((*segments, *words), role, status)), at)
+
+    def part_name(present: bool, role: NamingRole, *words: str) -> str | None:
+        return type_name(role, *words) if present else None
+
+    return OperationNames(
+        request=type_name(NamingRole.SCHEMA, "request"),
+        input=type_name(NamingRole.INPUT),
+        path=part_name(bool(operation.params.path), NamingRole.PATH),
+        query=part_name(bool(operation.params.query), NamingRole.QUERY),
+        headers=part_name(bool(handler_headers(operation)), NamingRole.HEADERS),
+        scopes=part_name(bool(operation.scopes), NamingRole.SCHEMA, "scopes"),
+        result=type_name(NamingRole.SCHEMA, "result"),
+        errors=type_name(NamingRole.ERRORS),
+        page=part_name(operation.paging is not None, NamingRole.SCHEMA, "page"),
+        method=python_identifier(IrName(segments, NamingRole.OPERATION)),
+        owner=owner,
+        responses={
+            response.status: type_name(NamingRole.RESPONSE, status=response.status) for response in operation.responses
+        },
+    )
+
+
+def handler_headers(operation: Operation) -> list[Param]:
+    """The header parameters the handler reads: the credential and CSRF headers stay the boundary's."""
+    return [
+        param
+        for param in operation.params.header
+        if not _boundary_header(param.derived_from.derivation if param.derived_from is not None else "")
+    ]
+
+
+def _boundary_header(derivation: str) -> bool:
+    return derivation in _BOUNDARY_HEADER_DERIVATIONS or derivation.startswith(_BOUNDARY_HEADER_DERIVATION_PREFIXES)
+
+
+def _owner(ir: ContractIR, operation: Operation) -> tuple[str, ...] | None:
+    """A resource's operations share one protocol; one without a resource joins its surface's."""
+    if operation.resource is not None:
+        segments = segments_of(operation.resource.type, NameSource.NAME, None, None)
+
+        if segments:
+            return tuple(segments)
+
+    surface = ir.api.surfaces.get(operation.surface)
+    segments = list(surface.name.segments) if surface is not None else segments_of(operation.surface, NameSource.NAME)
+
+    return tuple(segments) if segments else None
+
+
+class NameClaims:
+    """The class names of one generated module; a name claimed twice is refused, naming both places."""
+
+    def __init__(self, module: str, refusals: Refusals) -> None:
+        self._module = module
+        self._refusals = refusals
+        self._claimed: dict[str, IrPlace] = {}
+
+    def owned_name(self, name: str, _owner: str, at: IrPlace) -> str:
+        """`name`, in the shape the shared emitters claim through: the place already names its owner."""
+        return self.name(name, at)
+
+    def name(self, name: str, at: IrPlace) -> str:
+        earlier = self._claimed.setdefault(name, at)
+
+        if earlier is not at:
+            self._refusals.add(
+                "name.collision",
+                f"The names at {earlier.pointer} and at {at.pointer} both give the Python class '{name}' in the "
+                f"{self._module} module.",
+                "Rename one of them in the contract, or give one a `codeName`.",
+                at,
+            )
+
+        return name
+
+
+def principal_schema(ir: ContractIR, identity: str) -> str | None:
+    """The object schema of an identity's principal; None for a principal of several variants."""
+    declared = ir.identities.get(identity)
+    principal = declared.principal if isinstance(declared, CredentialIdentity | SignedIdentity) else None
+
+    return principal.schema if isinstance(principal, SchemaPrincipal) else None

seampact_drf-1.0.0/src/seampact/drf/dataclass_schemas.py

@@ -0,0 +1,131 @@
+"""The `schemas` module of an api on the DRF target (ADR 0027 "Types and validation"): a `StrEnum` per enum and a
+frozen, slotted, keyword-only dataclass per object schema, which the handler reads. A member both optional and
+nullable is a `Field` of `seampact.hooks`, absent by default; an optional member that is not nullable is `None` when
+absent. Value rules are not part of the types: the serializers check them."""
+
+from collections.abc import Sequence
+
+from seampact.codegen.names import ApiNames
+from seampact.codegen.printer import INDENT, PythonModule, string_literal
+from seampact.codegen.redacted_members import redacted_dataclass_reprs, redacted_marker_block
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.drf.python_types import PythonTypes, use_nullable
+from seampact.ir.hydration import OMITTED
+from seampact.ir.model import ContractIR, MapSchema, ObjectSchema, Property, ScalarTypeUse, TypeUse, UnionSchema
+
+DATACLASS_DECORATOR = "dataclass(frozen=True, slots=True, kw_only=True)"
+_REDACTED_DATACLASS_DECORATOR = "dataclass(frozen=True, slots=True, kw_only=True, repr=False)"
+
+
+class FrozenDataclasses:
+    """The frozen dataclasses of one generated module. A class with sensitive members gets the generated `__repr__`
+    and `__rich_repr__` that print them `[redacted]` (ADR 0026 "Redaction"); the module declares the marker they print
+    once, before its first use."""
+
+    def __init__(self, module: PythonModule) -> None:
+        self.module = module
+        self._marker_declared = False
+
+    def block(
+        self, class_name: str, body: Sequence[str], attributes: Sequence[str], redacted: Sequence[str]
+    ) -> list[str]:
+        """The class with its `body` (docstring and member lines); `attributes` names its members in order."""
+        dataclasses = self.module.imported("dataclasses", "_dataclasses")
+
+        if not redacted:
+            return [f"@{dataclasses}.{DATACLASS_DECORATOR}", f"class {class_name}:", *body]
+
+        if not self._marker_declared:
+            self._marker_declared = True
+            self.module.add_block(redacted_marker_block())
+
+        abc = self.module.imported("collections.abc", "_abc")
+        reprs = redacted_dataclass_reprs(class_name, attributes, redacted, abc)
+
+        return [f"@{dataclasses}.{_REDACTED_DATACLASS_DECORATOR}", f"class {class_name}:", *body, *reprs]
+
+
+def is_sensitive_use(type_use: TypeUse) -> bool:
+    """A use of a declared scalar marked sensitive (ADR 0003 section 6)."""
+    return isinstance(type_use, ScalarTypeUse) and type_use.sensitive is True
+
+
+def dataclass_schemas_module(ir: ContractIR, names: ApiNames, refusals: Refusals) -> str:
+    module = PythonModule(f"The schema types of api '{ir.api.id}'.")
+    defined: set[str] = set()
+    types = PythonTypes(ir, names, refusals, defined=defined)
+    dataclasses = FrozenDataclasses(module)
+
+    for enum_id in sorted(ir.enums):
+        enum = module.imported("enum", "_enum")
+        module.add_block(
+            [
+                f"class {names.enum_classes[enum_id]}({enum}.StrEnum):",
+                *(
+                    f"{INDENT}{member} = {string_literal(value)}"
+                    for value, member in names.enum_members[enum_id].items()
+                ),
+            ]
+        )
+
+    for schema_id, schema in sorted(ir.schemas.items()):
+        at = IrPlace(f"/schemas/{schema_id}")
+
+        if isinstance(schema, ObjectSchema):
+            module.add_block(_dataclass(dataclasses, types, names, schema_id, schema, at, refusals))
+            defined.add(schema_id)
+        elif isinstance(schema, MapSchema | UnionSchema):
+            refusals.waiting(f"schema.{schema.kind}", f"A {schema.kind} schema", at, Delivery.CONSUMER)
+        else:
+            refusals.unknown_value(schema.kind, at.below("kind"))
+
+    return module.text()
+
+
+def _dataclass(
+    dataclasses: FrozenDataclasses,
+    types: PythonTypes,
+    names: ApiNames,
+    schema_id: str,
+    schema: ObjectSchema,
+    at: IrPlace,
+    refusals: Refusals,
+) -> list[str]:
+    module = dataclasses.module
+    members = names.members.get(schema_id, {})
+    body = [
+        _member(module, types, attribute, member, at.below("properties", index), refusals)
+        for index, member in enumerate(schema.properties)
+        if (attribute := members.get(member.name)) is not None
+    ]
+    redacted = [
+        attribute
+        for member in schema.properties
+        if (member.sensitive or is_sensitive_use(member.type)) and (attribute := members.get(member.name)) is not None
+    ]
+    attributes = [attribute for member in schema.properties if (attribute := members.get(member.name)) is not None]
+    class_name = names.schema_classes[schema_id]
+
+    if not body:
+        return dataclasses.block(
+            class_name, [f'{INDENT}"""The schema \'{schema_id}\', which has no member."""'], [], []
+        )
+
+    return dataclasses.block(class_name, body, attributes, redacted)
+
+
+def _member(
+    module: PythonModule, types: PythonTypes, attribute: str, member: Property, at: IrPlace, refusals: Refusals
+) -> str:
+    if member.default is not OMITTED:
+        refusals.waiting("member.default", "A member with a default", at.below("default"), Delivery.CONSUMER)
+
+    type_nullable = use_nullable(member.type)
+    suffix = " | None" if (member.optional or member.nullable) and not type_nullable else ""
+    annotation = types.annotation(module, member.type, at.below("type"), suffix)
+
+    if member.optional and (member.nullable or type_nullable):
+        hooks = module.imported("seampact.hooks", "_hooks")
+        return f"{INDENT}{attribute}: {hooks}.Field[{annotation}] = {hooks}.Absent.ABSENT"
+
+    return f"{INDENT}{attribute}: {annotation}{' = None' if member.optional else ''}"