seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/printer.py

@@ -0,0 +1,196 @@
+"""The deterministic line printer of generated Python modules: a docstring, the imports as `import x as _x` sorted in
+ruff's sections (standard library, third party, seampact, then the api's own modules as `from . import x as _x`),
+then top-level blocks two blank lines apart. Output never
+depends on the installed Python's `ast.unparse`; the golden files check it against `ruff format --check`."""
+
+import re
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Final
+
+LINE_LENGTH: Final = 120
+INDENT: Final = "    "
+
+_FIRST_PARTY: Final = "seampact"
+_SIBLING_PREFIX: Final = "."
+_SECTIONS: Final = 4
+_DEFINITIONS: Final = ("class ", "def ", "@")
+
+
+_DOUBLE_QUOTE: Final = '"'
+_SINGLE_QUOTE: Final = "'"
+_NAMED_ESCAPES: Final = {"\\": "\\\\", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+_LAST_PRINTABLE_ASCII: Final = 0x7E
+_FIRST_PRINTABLE_ASCII: Final = 0x20
+_LAST_BMP: Final = 0xFFFF
+# Each piece of a long string ends after a space or a slash, where a part may end.
+_BREAK_AFTER: Final = re.compile(r"[^ /]*[ /]|[^ /]+")
+
+
+def string_literal(text: str) -> str:
+    """A Python string literal of `text`, ASCII only, quoted as ruff quotes it: double quotes unless the text holds more
+    double quotes than single ones; a character outside the Basic Multilingual Plane is one `\\U` escape."""
+    quote = _SINGLE_QUOTE if text.count(_DOUBLE_QUOTE) > text.count(_SINGLE_QUOTE) else _DOUBLE_QUOTE
+
+    return quote + "".join(_escaped(character, quote) for character in text) + quote
+
+
+def _escaped(character: str, quote: str) -> str:
+    if character == quote:
+        return "\\" + character
+
+    named = _NAMED_ESCAPES.get(character)
+
+    if named is not None:
+        return named
+
+    code_point = ord(character)
+
+    if _FIRST_PRINTABLE_ASCII <= code_point <= _LAST_PRINTABLE_ASCII:
+        return character
+
+    if code_point < _FIRST_PRINTABLE_ASCII or code_point == _LAST_PRINTABLE_ASCII + 1:
+        return f"\\x{code_point:02x}"
+
+    return f"\\u{code_point:04x}" if code_point <= _LAST_BMP else f"\\U{code_point:08x}"
+
+
+def literal_lines(indent: str, head: str, value: object, tail: str) -> list[str]:
+    """`head`, the Python literal of the JSON value `value`, then `tail`, at `indent`, as ruff formats it: a non-empty
+    object or array one item per line with a trailing comma, which keeps it so, and a string too long for its line
+    split at spaces into parenthesised parts."""
+    if isinstance(value, dict):
+        items = [
+            line
+            for key, item in value.items()
+            for line in literal_lines(indent + INDENT, f"{string_literal(str(key))}: ", item, ",")
+        ]
+
+        return _bracketed_items(indent, head, "{", items, "}", tail)
+
+    if isinstance(value, list | tuple):
+        items = [line for item in value for line in literal_lines(indent + INDENT, "", item, ",")]
+
+        return _bracketed_items(indent, head, "[", items, "]", tail)
+
+    if isinstance(value, str):
+        return _string_lines(indent, head, value, tail)
+
+    return [f"{indent}{head}{_scalar_literal(value)}{tail}"]
+
+
+def _bracketed_items(indent: str, head: str, opening: str, items: list[str], closing: str, tail: str) -> list[str]:
+    if not items:
+        return [f"{indent}{head}{opening}{closing}{tail}"]
+
+    return [f"{indent}{head}{opening}", *items, f"{indent}{closing}{tail}"]
+
+
+def _string_lines(indent: str, head: str, text: str, tail: str) -> list[str]:
+    single = f"{indent}{head}{string_literal(text)}{tail}"
+
+    if fits(single):
+        return [single]
+
+    parts = _string_parts(text, len(indent) + len(INDENT))
+
+    return [f"{indent}{head}(", *(f"{indent}{INDENT}{string_literal(part)}" for part in parts), f"{indent}){tail}"]
+
+
+def _string_parts(text: str, indent_width: int) -> list[str]:
+    """`text` cut after spaces and slashes into parts whose literal fits a line at `indent_width`."""
+    parts: list[str] = []
+    current = ""
+
+    for piece in _BREAK_AFTER.findall(text):
+        if current and indent_width + len(string_literal(current + piece)) > LINE_LENGTH:
+            parts.append(current)
+            current = piece
+        else:
+            current += piece
+
+    return [*parts, current]
+
+
+def _scalar_literal(value: object) -> str:
+    if value is None or isinstance(value, bool | int | float):
+        return repr(value)
+
+    raise TypeError(f"seampact-codegen: {type(value).__name__} is not a JSON value.")
+
+
+@dataclass(slots=True)
+class PythonModule:
+    docstring: str
+    _imports: dict[str, str] = field(default_factory=dict)
+    _blocks: list[list[str]] = field(default_factory=list)
+
+    def imported(self, module: str, alias: str) -> str:
+        """Imports `module` under a private alias, so no framework name sits bare beside contract names (ADR 0026
+        "Naming"); returns the alias. A module written `.name` is a sibling module of the api's package."""
+        self._imports[module] = alias
+
+        return alias
+
+    def add_block(self, lines: Sequence[str]) -> None:
+        self._blocks.append(list(lines))
+
+    def text(self) -> str:
+        sections = [
+            [line for module, line in self._import_lines() if _section(module) == section]
+            for section in range(_SECTIONS)
+        ]
+        parts = [f'"""{self.docstring}"""', *("\n".join(lines) for lines in sections if lines)]
+        head = "\n\n".join(parts)
+        body = "\n\n\n".join("\n".join(block) for block in self._blocks)
+
+        if not body:
+            return f"{head}\n"
+
+        # ruff's import sorting leaves two blank lines before a class or function, one before a statement.
+        separator = "\n\n\n" if body.startswith(_DEFINITIONS) else "\n\n"
+
+        return f"{head}{separator}{body}\n"
+
+    def _import_lines(self) -> list[tuple[str, str]]:
+        return [(module, _import_line(module, self._imports[module])) for module in sorted(self._imports)]
+
+
+def _import_line(module: str, alias: str) -> str:
+    if module.startswith(_SIBLING_PREFIX):
+        return f"from {_SIBLING_PREFIX} import {module.removeprefix(_SIBLING_PREFIX)} as {alias}"
+
+    return f"import {module} as {alias}"
+
+
+def _section(module: str) -> int:
+    """ruff's import sections: the standard library, third party, seampact (first party), the api's own modules."""
+    if module.startswith(_SIBLING_PREFIX):
+        return 3
+
+    top = module.split(".", 1)[0]
+
+    if top == _FIRST_PARTY:
+        return 2
+
+    return 0 if top in sys.stdlib_module_names else 1
+
+
+def bracketed(indent: str, head: str, arguments: Sequence[str], tail: str) -> list[str]:
+    """`head(arguments)tail` at `indent`, split as ruff splits it."""
+    single = f"{indent}{head}({', '.join(arguments)}){tail}"
+
+    if fits(single):
+        return [single]
+
+    hugged = f"{indent}{INDENT}{', '.join(arguments)}"
+
+    if fits(hugged) and not any(argument == "*" for argument in arguments):
+        return [f"{indent}{head}(", hugged, f"{indent}){tail}"]
+
+    return [f"{indent}{head}(", *(f"{indent}{INDENT}{argument}," for argument in arguments), f"{indent}){tail}"]
+
+
+def fits(line: str) -> bool:
+    return len(line) <= LINE_LENGTH

seampact/codegen/pydantic_forms.py

@@ -0,0 +1,53 @@
+"""The contract forms the Pydantic targets, FastAPI and Ninja, do not generate yet (ADR 0026 "Refused by name or
+waiting"), each refused by name: a body other than JSON, a binary or redirect response, native access, a page fact other
+than those the page class carries, and a sort key restricted by a right. The forms no Python target serves are refused
+by `seampact.codegen.kept_forms`, and unions and other schema forms by the shared Pydantic emitter."""
+
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.codegen.restricted_sort_keys import refuse_restricted_sort_keys
+from seampact.ir.model import (
+    ContractIR,
+    IdentityAccess,
+    InputMediaType,
+    OptionalAccess,
+    PublicAccess,
+    ResponseShape,
+)
+
+_SERVED_SHAPES = frozenset(
+    {ResponseShape.ITEM, ResponseShape.TABLE, ResponseShape.LIST, ResponseShape.PAGE, ResponseShape.EMPTY}
+)
+
+
+def refuse_unserved_forms(ir: ContractIR, refusals: Refusals) -> None:
+    for index, operation in enumerate(ir.operations):
+        at = IrPlace(f"/operations/{index}", operation.id)
+
+        if operation.input is not None and operation.input.media is not InputMediaType.APPLICATION_JSON:
+            refusals.waiting(
+                "input.media",
+                f"A '{operation.input.media}' request body",
+                at.below("input", "media"),
+                Delivery.CONSUMER,
+            )
+
+        for position, response in enumerate(operation.responses):
+            if isinstance(response.shape, ResponseShape) and response.shape not in _SERVED_SHAPES:
+                refusals.waiting(
+                    f"response.{response.shape.value}",
+                    f"A '{response.shape.value}' response",
+                    at.below("responses", position, "shape"),
+                    Delivery.CONSUMER,
+                )
+            elif not isinstance(response.shape, ResponseShape):
+                refusals.unknown_value(response.shape.raw, at.below("responses", position, "shape"))
+
+        if not isinstance(operation.access, IdentityAccess | OptionalAccess | PublicAccess):
+            refusals.waiting(
+                f"access.{operation.access.kind}",
+                f"The access kind '{operation.access.kind}'",
+                at.below("access"),
+                Delivery.CONSUMER,
+            )
+
+        refuse_restricted_sort_keys(operation, at, refusals)

seampact/codegen/pydantic_layout.py

@@ -0,0 +1,178 @@
+"""The Python names of one api's package on the Pydantic targets, FastAPI and Ninja (ADR 0026 "Placement"): per
+operation its request, input parts, results, typed errors, page and scopes, and its handler method; the credentials
+class of each identity an operation reads, with one attribute per scheme; the endpoints protocol of each resource (an
+operation without a resource joins its surface's); one exception per error code and the api's contract exception base;
+and the placement's own names. Two classes of one module taking one name are refused as `name.collision`."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from seampact.codegen.credentials_classes import CredentialsNames, identity_credentials
+from seampact.codegen.refusals import IrPlace, Refusals
+from seampact.ir.model import ContractIR, Operation, ResponseShape
+from seampact.ir.naming import IrName, NameSource, NamingRole, python_identifier, segments_of
+
+
+@dataclass(frozen=True, slots=True)
+class OperationNames:
+    method: str
+    request: str
+    input: str
+    result: str
+    errors: str
+    responses: Mapping[int, str]
+    page: str | None
+    scopes: str | None
+    endpoints: str
+    owner_attribute: str
+
+
+@dataclass(frozen=True, slots=True)
+class ApiLayout:
+    contract_error: str
+    handler_factories: str
+    unexpected_error_listener: str
+    bind_function: str
+    error_classes: Mapping[str, str]
+    error_factories: Mapping[str, str]
+    operations: Mapping[str, OperationNames]
+    credentials: Mapping[str, CredentialsNames]
+
+    def endpoints_owners(self) -> dict[str, str]:
+        """Each endpoints protocol and the attribute of `<Api>HandlerFactories` that builds it, in operation order."""
+        return {names.endpoints: names.owner_attribute for names in self.operations.values()}
+
+
+class _Claims:
+    """The names of one module, each with what took it first."""
+
+    def __init__(self, module: str, refusals: Refusals) -> None:
+        self._module = module
+        self._refusals = refusals
+        self._owners: dict[str, str] = {}
+
+    def claim(self, name: str, owner: str, at: IrPlace) -> str:
+        previous = self._owners.setdefault(name, owner)
+
+        if previous != owner:
+            self._refusals.add(
+                "name.collision",
+                f"The Python name '{name}' of the {self._module} module would be written for both {previous} and "
+                f"{owner}.",
+                "Rename one of them in the contract (a schema name, an operation's `operationId` or an error code).",
+                at,
+            )
+
+        return name
+
+
+def api_layout(ir: ContractIR, error_codes: list[str], refusals: Refusals) -> ApiLayout:
+    root = _Claims("operation types", refusals)
+    api_segments = tuple(ir.api.name.segments)
+    at_api = IrPlace("/api/name")
+    contract_error = root.claim(
+        python_identifier(IrName((*api_segments, "contract"), NamingRole.ERROR)), "the api's contract error", at_api
+    )
+    handler_factories = root.claim(
+        python_identifier(IrName((*api_segments, "handler", "factories"), NamingRole.SCHEMA)),
+        "the api's handler factories",
+        at_api,
+    )
+    unexpected_error_listener = root.claim(
+        python_identifier(IrName((*api_segments, "unexpected", "error", "listener"), NamingRole.SCHEMA)),
+        "the api's unexpected-error listener",
+        at_api,
+    )
+    error_classes: dict[str, str] = {}
+    error_factories: dict[str, str] = {}
+
+    for code in error_codes:
+        at = IrPlace(f"/errors/{code}")
+        segments = segments_of(code, NameSource.NAME)
+
+        if not segments:
+            refusals.inconsistent("error.code.no-segment", f"The error code '{code}' yields no name segment", at)
+            continue
+
+        error_classes[code] = root.claim(
+            python_identifier(IrName(tuple(segments), NamingRole.ERROR)), f"the exception of error '{code}'", at
+        )
+        error_factories[code] = python_identifier(IrName(tuple(segments), NamingRole.MEMBER))
+
+    operations: dict[str, OperationNames] = {}
+
+    for index, operation in enumerate(ir.operations):
+        at = IrPlace(f"/operations/{index}", operation.id)
+        owner = _endpoints_owner(ir, operation)
+
+        if not owner:
+            refusals.inconsistent(
+                "endpoints.owner.no-segment",
+                f"The operation '{operation.id}' has no resource or surface that yields a name segment",
+                at.below("surface"),
+            )
+            continue
+
+        operations[operation.id] = _operation_names(operation, tuple(owner), root, at)
+
+    return ApiLayout(
+        contract_error,
+        handler_factories,
+        unexpected_error_listener,
+        python_identifier(IrName(("bind", *api_segments), NamingRole.OPERATION)),
+        error_classes,
+        error_factories,
+        operations,
+        identity_credentials(ir, operations, root.claim, refusals),
+    )
+
+
+def _operation_names(operation: Operation, owner: tuple[str, ...], root: _Claims, at: IrPlace) -> OperationNames:
+    segments = tuple(operation.name.segments)
+    owned = f"a type of operation '{operation.id}'"
+
+    def in_root(extra: tuple[str, ...], role: NamingRole = NamingRole.SCHEMA) -> str:
+        return root.claim(python_identifier(IrName((*segments, *extra), role)), owned, at.below("name"))
+
+    responses = {
+        response.status: root.claim(
+            python_identifier(IrName(segments, NamingRole.RESPONSE, response.status)),
+            f"the {response.status} result of operation '{operation.id}'",
+            at.below("name"),
+        )
+        for response in operation.responses
+    }
+    paged = operation.paging is not None and any(
+        response.shape is ResponseShape.PAGE for response in operation.responses
+    )
+    return OperationNames(
+        method=python_identifier(IrName(segments, NamingRole.OPERATION)),
+        request=in_root(("request",)),
+        input=in_root((), NamingRole.INPUT),
+        result=in_root(("result",)),
+        errors=in_root((), NamingRole.ERRORS),
+        responses=responses,
+        page=in_root(("page",)) if paged else None,
+        scopes=in_root(("scopes",)) if operation.scopes else None,
+        endpoints=root.claim(
+            python_identifier(IrName(owner, NamingRole.ENDPOINTS)),
+            f"the endpoints protocol of '{'-'.join(owner)}'",
+            at.below("name"),
+        ),
+        owner_attribute=python_identifier(IrName(owner, NamingRole.MEMBER)),
+    )
+
+
+def _endpoints_owner(ir: ContractIR, operation: Operation) -> list[str] | None:
+    if operation.resource is not None:
+        segments = segments_of(operation.resource.type, NameSource.NAME)
+
+        if segments:
+            return segments
+
+    surface = ir.api.surfaces.get(operation.surface)
+
+    if surface is not None:
+        return list(surface.name.segments)
+
+    return segments_of(operation.surface, NameSource.NAME)