seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/restricted_sort_keys.py

@@ -0,0 +1,18 @@
+"""A sort key restricted by a right, refused by name for every Python target: none checks the right on a sort."""
+
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.ir.model import Operation
+
+
+def refuse_restricted_sort_keys(operation: Operation, at: IrPlace, refusals: Refusals) -> None:
+    if operation.paging is None:
+        return
+
+    for position, sort_key in enumerate(operation.paging.sort_keys):
+        if sort_key.right is not None:
+            refusals.waiting(
+                "paging.sortKey.right",
+                f"The sort key '{sort_key.key}' restricted by the right '{sort_key.right}'",
+                at.below("paging", "sortKeys", position),
+                Delivery.CONSUMER,
+            )

seampact/codegen/route_helpers.py

@@ -0,0 +1,109 @@
+"""The route helpers of one api (ADR 0023 and ADR 0026 "Routes"): `<Api>RouteNames`, one constant per operation
+holding the route name the placement registers, and `<Api>Urls`, one static method per operation building the
+contract's path from one typed argument per path parameter, in path order, each value encoded as one segment by the
+runtime. The artefact switch `routeHelpers: false` leaves both out."""
+
+from collections.abc import Sequence
+from typing import Final
+
+from seampact.codegen.printer import INDENT, PythonModule, fits, string_literal
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.codegen.routes import RouteEntry, placeholders
+from seampact.ir.model import ContractIR, EnumTypeUse, Operation, ScalarType, ScalarTypeUse, TypeUse
+from seampact.ir.naming import IrName, NamingRole, python_identifier
+
+_SCALAR_ANNOTATIONS: Final = {
+    ScalarType.STRING: "str",
+    ScalarType.INTEGER: "int",
+    ScalarType.NUMBER: "float",
+    ScalarType.BOOLEAN: "bool",
+}
+_FORMAT_ANNOTATIONS: Final = {
+    "uuid": ("uuid", "_uuid", "_uuid.UUID"),
+    "date-time": ("datetime", "_datetime", "_datetime.datetime"),
+}
+
+
+_NAMES_REGISTERED: Final = "The route name of each operation, as the target registers it."
+
+
+def route_helpers_module(
+    ir: ContractIR, routes: Sequence[RouteEntry], refusals: Refusals, names_registered: str = _NAMES_REGISTERED
+) -> str:
+    """`names_registered` is the route names' docstring: a target that registers them under a namespace says so."""
+    api_class = python_identifier(IrName(tuple(ir.api.name.segments), NamingRole.SCHEMA))
+    module = PythonModule(f"The route names and contract paths of api '{ir.api.id}'.")
+    typing = module.imported("typing", "_typing")
+    wire = module.imported("seampact.codegen.runtime.wire_values", "_wire_values")
+    operations = {operation.id: (index, operation) for index, operation in enumerate(ir.operations)}
+    names = [
+        f"class {api_class}RouteNames:",
+        f'{INDENT}"""{names_registered}"""',
+        "",
+    ]
+    urls = [f"class {api_class}Urls:", f'{INDENT}"""The path of each operation, each value encoded as one segment."""']
+
+    for entry in sorted(routes, key=lambda route: operations[route.operation_id][0]):
+        index, operation = operations[entry.operation_id]
+        constant = python_identifier(IrName(tuple(operation.name.segments), NamingRole.ENUM_MEMBER))
+        names += [f"{INDENT}{constant}: {typing}.Final = {string_literal(entry.name)}"]
+        urls += [
+            "",
+            *_url_method(module, wire, entry, operation, IrPlace(f"/operations/{index}", operation.id), refusals),
+        ]
+
+    module.add_block(names)
+    module.add_block(urls)
+
+    return module.text()
+
+
+def _url_method(
+    module: PythonModule, wire: str, entry: RouteEntry, operation: Operation, at: IrPlace, refusals: Refusals
+) -> list[str]:
+    method = python_identifier(IrName(tuple(operation.name.segments), NamingRole.OPERATION))
+    types = {param.name: param.type for param in operation.params.path}
+    parameters = [
+        f"{segment.attribute}: {_annotation(module, types[segment.text], at, refusals)}"
+        for segment in placeholders(entry)
+    ]
+    doc = f'{INDENT * 2}"""The path of operation \'{operation.id}\', `{entry.contract_path}`."""'
+    head = [f"{INDENT}@staticmethod", f"{INDENT}def {method}({', '.join(parameters)}) -> str:", doc]
+    path = string_literal(entry.contract_path)
+
+    if not parameters:
+        return [*head, f"{INDENT * 2}return {path}"]
+
+    values = "{" + ", ".join(f"{string_literal(s.text)}: {s.attribute}" for s in placeholders(entry)) + "}"
+    single = f"{INDENT * 2}return {wire}.contract_path({path}, {values})"
+
+    if fits(single):
+        return [*head, single]
+
+    return [
+        *head,
+        f"{INDENT * 2}return {wire}.contract_path(",
+        f"{INDENT * 3}{path},",
+        f"{INDENT * 3}{values},",
+        f"{INDENT * 2})",
+    ]
+
+
+def _annotation(module: PythonModule, type_use: TypeUse, at: IrPlace, refusals: Refusals) -> str:
+    # An enum member is a `StrEnum` member, so a `str` takes it.
+    if isinstance(type_use, EnumTypeUse):
+        return "str"
+
+    if isinstance(type_use, ScalarTypeUse) and isinstance(type_use.type, ScalarType):
+        formatted = _FORMAT_ANNOTATIONS.get(type_use.format or "")
+
+        if formatted is not None:
+            module.imported(formatted[0], formatted[1])
+            return formatted[2]
+
+        return _SCALAR_ANNOTATIONS.get(type_use.type, "str")
+
+    refusals.waiting(
+        "path.param.type", f"A path parameter of kind '{type_use.kind}'", at.below("params", "path"), Delivery.CONSUMER
+    )
+    return "str"

seampact/codegen/routes.py

@@ -0,0 +1,139 @@
+"""The route table of one api, as every Python placement declares it (ADR 0026 "Routes"): one route per operation,
+named `seampact.<api>.<operationId>`, its path in the framework's placeholder syntax with each placeholder named after
+the parameter's attribute, `GET` also serving `HEAD`, and literal segments before placeholders at each depth. Static
+segments holding `{`, `}` or `?`, segments a client sends percent-encoded, and segments that mix a placeholder with
+text are refused by name."""
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from functools import cmp_to_key
+from typing import Final
+
+from seampact.codegen.names import member_identifier
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.ir.model import ContractIR, HttpMethod, Operation
+
+_PLACEHOLDER: Final = re.compile(r"\{([^{}]+)\}")
+# What a client sends unencoded in a path segment (RFC 3986 pchar without `%`).
+_SENT_AS_IS: Final = re.compile(r"[A-Za-z0-9\-._~!$&'()*+,;=:@]*")
+_LITERAL_SYNTAX: Final = frozenset("{}?")
+
+
+@dataclass(frozen=True, slots=True)
+class RouteSegment:
+    """A literal segment's text, or a placeholder's wire name and attribute."""
+
+    text: str
+    attribute: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RouteEntry:
+    operation_id: str
+    name: str
+    methods: tuple[str, ...]
+    contract_path: str
+    segments: tuple[RouteSegment, ...]
+
+    def path(self) -> str:
+        """The path with `{attribute}` placeholders, as Starlette, Django and Ninja name them."""
+        return "".join(
+            "/" + (segment.text if segment.attribute is None else f"{{{segment.attribute}}}")
+            for segment in self.segments
+        )
+
+
+def route_name(api_id: str, operation_id: str) -> str:
+    return f"seampact.{api_id}.{operation_id}"
+
+
+def route_table(ir: ContractIR, mount: str, refusals: Refusals) -> list[RouteEntry]:
+    entries = [
+        entry
+        for index, operation in enumerate(ir.operations)
+        if (entry := _entry(ir.api.id, operation, mount, IrPlace(f"/operations/{index}", operation.id), refusals))
+    ]
+
+    return sorted(entries, key=cmp_to_key(_literals_first))
+
+
+def _entry(api_id: str, operation: Operation, mount: str, at: IrPlace, refusals: Refusals) -> RouteEntry | None:
+    if not isinstance(operation.method, HttpMethod):
+        refusals.unknown_value(operation.method.raw, at.below("method"))
+        return None
+
+    method = operation.method.value.upper()
+    contract_path = mount + operation.path
+    segments = [_segment(text, operation, at.below("path"), refusals) for text in contract_path.split("/")[1:]]
+
+    if any(segment is None for segment in segments):
+        return None
+
+    methods = (method, "HEAD") if method == "GET" else (method,)
+
+    return RouteEntry(
+        operation.id,
+        route_name(api_id, operation.id),
+        methods,
+        contract_path,
+        tuple(segment for segment in segments if segment is not None),
+    )
+
+
+def _segment(text: str, operation: Operation, at: IrPlace, refusals: Refusals) -> RouteSegment | None:
+    placeholder = _PLACEHOLDER.fullmatch(text)
+
+    if placeholder is not None:
+        return _placeholder(placeholder.group(1), operation, at, refusals)
+
+    if "{" in text and "}" in text:
+        refusals.waiting(
+            "path.segment.mixed", f"The path segment '{text}', a placeholder mixed with text", at, Delivery.CONSUMER
+        )
+        return None
+
+    if _LITERAL_SYNTAX.intersection(text):
+        refusals.waiting(
+            "path.segment.literal",
+            f"The static path segment '{text}', holding '{{', '}}' or '?'",
+            at,
+            Delivery.CONSUMER,
+        )
+        return None
+
+    if _SENT_AS_IS.fullmatch(text) is None:
+        refusals.waiting(
+            "path.segment.encoded",
+            f"The static path segment '{text}', which a client percent-encodes",
+            at,
+            Delivery.CONSUMER,
+        )
+        return None
+
+    return RouteSegment(text)
+
+
+def _placeholder(wire_name: str, operation: Operation, at: IrPlace, refusals: Refusals) -> RouteSegment | None:
+    param = next((param for param in operation.params.path if param.name == wire_name), None)
+    attribute = None if param is None else member_identifier(param.name)
+
+    if attribute is None:
+        refusals.inconsistent(
+            "path.param.missing", f"The path placeholder '{{{wire_name}}}' names no path parameter", at
+        )
+        return None
+
+    return RouteSegment(wire_name, attribute)
+
+
+def _literals_first(first: RouteEntry, second: RouteEntry) -> int:
+    for mine, theirs in zip(first.segments, second.segments, strict=False):
+        if (mine.attribute is None) != (theirs.attribute is None):
+            return -1 if mine.attribute is None else 1
+
+    return len(first.segments) - len(second.segments)
+
+
+def placeholders(entry: RouteEntry) -> Sequence[RouteSegment]:
+    return [segment for segment in entry.segments if segment.attribute is not None]

seampact/codegen/runtime/__init__.py

@@ -0,0 +1,7 @@
+"""The framework-free runtime of generated Python code: step 1's raw-target match and decoding, the wire codec,
+replies, the outgoing verdict, the pattern check, the runtime version (G3) and the sync driver of the steps, which
+are written once as coroutines. A placement (FastAPI, Django) reads the request and writes the reply around them."""
+
+from seampact.codegen.runtime.version import RUNTIME_VERSION
+
+__all__ = ["RUNTIME_VERSION"]

seampact/codegen/runtime/access_kinds.py

@@ -0,0 +1,24 @@
+"""The access kind of an operation, which a framework's own security layer is configured by (ADR 0027 "DRF" and
+"Ninja"): `public`, `optional` or `identity` from its access, or `signed` when a signature verifies its identity."""
+
+from typing import Final
+
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.ir_view import ir_map, ir_string
+
+SIGNED_KIND: Final = "signed"
+# The kinds of the PHP targets' native security layers: a signed identity never shares the classes of a signed-in
+# caller's routes.
+ACCESS_KINDS: Final = ("public", "optional", "identity", SIGNED_KIND)
+
+
+def access_kind(contract: ApiContract, operation_id: str) -> str:
+    """`public`, `optional` or `identity` from the operation's access, or `signed` when a signature verifies its
+    identity."""
+    access = ir_map(contract.operation(operation_id), "access")
+    identity = ir_string(access, "identity")
+
+    if identity is not None and ir_string(contract.declaration("identities", identity), "signed") is not None:
+        return SIGNED_KIND
+
+    return ir_string(access, "kind") or ""