seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/runtime/framework_routes.py

@@ -0,0 +1,36 @@
+"""The entry's `frameworkRoutes` allow-list as the Python boot checks read it (FR-25): an app route at or under one of
+the api's base paths is refused unless an item lists it, by a path pattern where `*` takes one segment and `**` any
+number, and a method or every method."""
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FrameworkRouteRule:
+    """An item of the entry's `frameworkRoutes`: `path` a pattern where `*` takes one segment and `**` any number,
+    `method` None for every method."""
+
+    path: str
+    method: str | None
+    reason: str
+
+
+def allow_listed(rules: Sequence[FrameworkRouteRule], path: str, method: str) -> bool:
+    return any(_path_rule(rule.path).fullmatch(path) and rule.method in (None, method) for rule in rules)
+
+
+def base_path_of(path: str, base_paths: Sequence[str]) -> str | None:
+    """The first base path `path` sits at or under, None when it sits under none."""
+    return next((base for base in base_paths if _under(path, base)), None)
+
+
+def _path_rule(pattern: str) -> re.Pattern[str]:
+    parts = [re.escape(part).replace(r"\*", "[^/]*") for part in pattern.split("**")]
+
+    return re.compile(".*".join(parts))
+
+
+def _under(path: str, base: str) -> bool:
+    return base == "" or path == base or path.startswith(base + "/") or path.startswith(base + "{")

seampact/codegen/runtime/framework_versions.py

@@ -0,0 +1,91 @@
+"""The framework versions `generate` accepted (ADR 0026 "The boot check"): the generated code records, per framework
+the target serves or runs on, the units of the compatibility matrix (a major, or a `<major>.<minor>` for a 0.x
+framework) plus the entry's `allowUntested` ones, and the boot check refuses an installed version outside them, so an
+upgrade after `generate` fails the boot by name. A framework checked by major may also record the matrix's tested
+minors: an installed minor outside them, within a tested major, is only warned of (ADR 0027 "Matrix")."""
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from importlib import metadata
+from typing import Final
+
+_VERSION: Final = re.compile(r"(\d+)\.(\d+)")
+
+
+class VersionUnit(StrEnum):
+    MAJOR = "major"
+    MINOR = "minor"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AcceptedFramework:
+    """A distribution (`fastapi`) and the units `generate` accepted for it, compared by `unit`."""
+
+    package: str
+    unit: VersionUnit
+    accepted: tuple[str, ...]
+    tested_minors: tuple[str, ...] = ()
+
+    def unit_of(self, version: str) -> str | None:
+        match = _VERSION.match(version)
+
+        if match is None:
+            return None
+
+        return match.group(1) if self.unit is VersionUnit.MAJOR else f"{match.group(1)}.{match.group(2)}"
+
+
+def framework_version_problems(frameworks: Sequence[AcceptedFramework], api: str) -> list[str]:
+    return [problem for framework in frameworks if (problem := _version_problem(framework, api)) is not None]
+
+
+def framework_version_warnings(frameworks: Sequence[AcceptedFramework], api: str) -> list[str]:
+    """One line per installed framework whose minor is outside the tested minors of its major."""
+    return [warning for framework in frameworks if (warning := _untested_minor(framework, api)) is not None]
+
+
+def _untested_minor(framework: AcceptedFramework, api: str) -> str | None:
+    if not framework.tested_minors:
+        return None
+
+    try:
+        installed = metadata.version(framework.package)
+    except metadata.PackageNotFoundError:
+        return None
+
+    match = _VERSION.match(installed)
+    tested_majors = {minor.partition(".")[0] for minor in framework.tested_minors}
+
+    if match is None or match.group(1) not in tested_majors:
+        return None
+
+    if f"{match.group(1)}.{match.group(2)}" in framework.tested_minors:
+        return None
+
+    tested = ", ".join(framework.tested_minors)
+
+    return (
+        f"{framework.package} {installed} is installed, and the api '{api}' is tested on {framework.package} "
+        f"{tested} only, so this minor is untested; install a tested minor to serve on a tested version"
+    )
+
+
+def _version_problem(framework: AcceptedFramework, api: str) -> str | None:
+    try:
+        installed = metadata.version(framework.package)
+    except metadata.PackageNotFoundError:
+        return f"{framework.package} is not installed; the api '{api}' was generated for {_units(framework)}"
+
+    if framework.unit_of(installed) in framework.accepted:
+        return None
+
+    return (
+        f"{framework.package} {installed} is installed, but the api '{api}' was generated for {_units(framework)}; "
+        f"install one of those, or run seampact generate again (with `allowUntested` for an untested {framework.unit})"
+    )
+
+
+def _units(framework: AcceptedFramework) -> str:
+    return ", ".join(f"{framework.package} {unit}" for unit in framework.accepted)

seampact/codegen/runtime/handler_call.py

@@ -0,0 +1,31 @@
+"""How an async placement calls a handler or hook method (ADR 0026 "Sync and async"): an `async def` on the event
+loop, a plain `def` through the framework's thread runner (Starlette's threadpool, Django's `sync_to_async`), then
+what a `def` returns awaited when it is awaitable."""
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Protocol
+
+
+class ThreadRunner(Protocol):
+    """Runs a plain `def` off the event loop and gives back its result."""
+
+    def __call__[A, R](self, method: Callable[[A], R], argument: A, /) -> Awaitable[R]: ...
+
+
+async def call_handler_in[A, T](method: Callable[[A], T | Awaitable[T]], argument: A, run_in_thread: ThreadRunner) -> T:
+    if inspect.iscoroutinefunction(method):
+        # `iscoroutinefunction` narrows `method` to a coroutine function returning Any; its declared arm is the
+        # awaitable one, so the awaited value is taken as T.
+        coroutine: Awaitable[T] = method(argument)
+        return await coroutine
+
+    result: T | Awaitable[T] = await run_in_thread(method, argument)
+
+    if isinstance(result, Awaitable):
+        # The checkers read `Awaitable[Any]` here, since T might be awaitable itself: a plain `def` returning an
+        # awaitable takes the `Awaitable[T]` arm its protocol declares, so the awaited value is taken as that T.
+        awaited: T = await result
+        return awaited
+
+    return result

seampact/codegen/runtime/handler_reply.py

@@ -0,0 +1,148 @@
+"""The reply of a handler's result or of a raised contract exception (ADR 0026 "The reply path"): a declared success
+written in its format's envelope with the boundary's own JSON encoding, less the restricted output members the caller
+may not see, with its page parts, its cache headers and the headers its response derives (deprecation, version tag);
+or a declared error code with its params in wire names. A result the operation does not declare is a failure of the
+boundary, answered with the api's 500."""
+
+import dataclasses
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from seampact.codegen.runtime.access_steps import AccessHooks, AccessState, HookCaller
+from seampact.codegen.runtime.cache_headers import with_cache_headers
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.failures import BoundaryFailureError
+from seampact.codegen.runtime.field_rights import visible_output
+from seampact.codegen.runtime.ir_view import IrMap, ir_maps, ir_string
+from seampact.codegen.runtime.page_facts import page_facts
+from seampact.codegen.runtime.page_reply import PageParts, page_parts
+from seampact.codegen.runtime.replies import CONTENT_TYPE, JSON_MEDIA, Reply, error_reply, json_bytes, success_body
+from seampact.codegen.runtime.response_headers import derived_response_headers, with_entity_tag, with_success_headers
+from seampact.codegen.runtime.run_settings import OperationTypes
+from seampact.codegen.runtime.wire_codec import WireCodec
+
+_ITEM_SHAPE: Final = "item"
+_PAGE_SHAPE: Final = "page"
+_ITEMS: Final = "items"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ReplyContext:
+    """What a success reads of its request: the access steps' state and hooks (the output field rights ask the
+    deciders, through `call`), the query the input step read and the raw one page links keep, the request path,
+    `If-None-Match`, and the origin absolute page links start with (None under relative URLs)."""
+
+    access: AccessState
+    hooks: AccessHooks
+    call: HookCaller
+    query: Mapping[str, object]
+    raw_query: str
+    path: str
+    if_none_match: str | None
+    public_origin: str | None
+
+
+async def result_reply(
+    contract: ApiContract, operation_id: str, types: OperationTypes, result: object, context: ReplyContext
+) -> Reply:
+    """A declared error, or a success with its restricted output members left out, its page parts and its cache
+    headers (the ETag's 304 when `If-None-Match` names it)."""
+    if isinstance(result, types.errors):
+        return code_reply(contract, operation_id, getattr(result, "_code", ""), getattr(result, "_params", None))
+
+    status = next((status for status, success in types.responses if isinstance(result, success)), None)
+
+    if status is None:
+        raise BoundaryFailureError(
+            f"seampact: the handler of operation '{operation_id}' returned a {type(result).__qualname__}, which is "
+            "none of the operation's generated results; return one of them."
+        )
+
+    response = next(
+        (
+            declared
+            for declared in ir_maps(contract.operation(operation_id), "responses")
+            if declared.get("status") == status
+        ),
+        None,
+    )
+
+    if response is None:
+        return Reply(status, (), b"")
+
+    raw_parameters = context.access.raw_parameters
+
+    if not hasattr(result, "body"):
+        derived = derived_response_headers(contract, operation_id, response, None, raw_parameters)
+
+        return with_success_headers(Reply(status, (), b""), derived, status)
+
+    shape = ir_string(response, "shape") or _ITEM_SHAPE
+    media_headers = ((CONTENT_TYPE, ir_string(response, "media") or JSON_MEDIA),)
+
+    if shape == _PAGE_SHAPE:
+        derived = derived_response_headers(contract, operation_id, response, None, raw_parameters)
+        page = await _page(contract, operation_id, response, result.body, status, context)
+        reply = Reply(status, (*media_headers, *page.headers), json_bytes(page.body))
+    else:
+        payload = WireCodec(contract).body_to_wire(response, result.body)
+        derived = derived_response_headers(contract, operation_id, response, payload, raw_parameters)
+        visible = await visible_output(context.access, context.hooks, context.call, response, payload)
+        body = success_body(contract.format(operation_id), shape, visible, status, context.path)
+        reply = Reply(status, with_entity_tag(media_headers, derived), json_bytes(body))
+
+    cached = with_cache_headers(contract, operation_id, reply, context.access.principal, context.if_none_match)
+
+    return with_success_headers(cached, derived, status)
+
+
+async def _page(
+    contract: ApiContract, operation_id: str, response: IrMap, page: object, status: int, context: ReplyContext
+) -> PageParts:
+    """The page's items encoded and projected, then the body, headers and links of its paging style."""
+    if not dataclasses.is_dataclass(page) or isinstance(page, type):
+        raise BoundaryFailureError(
+            f"seampact: the handler of operation '{operation_id}' answered its page with a {type(page).__qualname__}, "
+            "not its generated page class; return the generated page."
+        )
+
+    attributes = {field.name: getattr(page, field.name) for field in dataclasses.fields(page)}
+    facts = page_facts(operation_id, page, attributes)
+    items = WireCodec(contract).body_to_wire(response, facts.pop(_ITEMS, []))
+    visible = await visible_output(context.access, context.hooks, context.call, response, items)
+
+    if not isinstance(visible, list):
+        raise BoundaryFailureError(
+            f"seampact: the items of operation '{operation_id}' encoded to a {type(visible).__qualname__}, not a "
+            "list; return the page's items as a list."
+        )
+
+    return page_parts(
+        contract,
+        operation_id,
+        context.query,
+        context.raw_query,
+        visible,
+        facts,
+        status,
+        context.path,
+        public_origin=context.public_origin,
+    )
+
+
+def code_reply(contract: ApiContract, operation_id: str, code: str, params: object) -> Reply:
+    """A declared code of the operation, its params model written in wire names."""
+    if not contract.declares(operation_id, code):
+        raise BoundaryFailureError(
+            f"seampact: operation '{operation_id}' answered '{code}', which it does not declare; answer one of its "
+            "declared codes."
+        )
+
+    params_schema = contract.catalog_entry(code).get("params")
+    wire_params: object = None
+
+    if params is not None and isinstance(params_schema, str):
+        wire_params = WireCodec(contract).to_wire({"kind": "ref", "schema": params_schema}, params)
+
+    return error_reply(contract, operation_id, code, wire_params if isinstance(wire_params, dict) else None)

seampact/codegen/runtime/hinted_values.py

@@ -0,0 +1,48 @@
+"""A generated frozen dataclass built from a tree keyed by Python attribute whose scalars are already converted, each
+member by its type hint: nested dataclasses, lists and mappings walked, and an enum member's wire text turned into the
+member. A member already of its hinted type is kept, so a tree a serializer converted builds the same."""
+
+import dataclasses
+import typing
+from collections.abc import Mapping, Sequence
+from enum import Enum
+from typing import TypeAliasType, get_args, get_origin, get_type_hints
+
+
+def built_dataclass(cls: type, data: Mapping[str, object]) -> object:
+    hints = get_type_hints(cls)
+    values = {
+        field.name: _converted(hints[field.name], data[field.name])
+        for field in dataclasses.fields(cls)
+        if field.name in data
+    }
+
+    return cls(**values)
+
+
+def _converted(hint: object, value: object) -> object:
+    if value is None:
+        return None
+
+    origin = get_origin(hint)
+
+    if isinstance(origin, TypeAliasType) or isinstance(hint, TypeAliasType):
+        arguments = get_args(hint)
+        return _converted(arguments[0] if arguments else typing.Any, value)
+
+    if origin in (list, Sequence) and isinstance(value, list):
+        item = get_args(hint)[0]
+        return [_converted(item, element) for element in value]
+
+    if origin in (dict, Mapping) and isinstance(value, Mapping):
+        item = get_args(hint)[1]
+        return {key: _converted(item, element) for key, element in value.items()}
+
+    for arm in get_args(hint) if origin in (typing.Union, type(int | None)) else (hint,):
+        if isinstance(arm, type) and dataclasses.is_dataclass(arm) and isinstance(value, Mapping):
+            return built_dataclass(arm, value)
+
+        if isinstance(arm, type) and issubclass(arm, Enum) and isinstance(value, str) and not isinstance(value, arm):
+            return arm(value)
+
+    return value

seampact/codegen/runtime/hook_check.py

@@ -0,0 +1,77 @@
+"""The hook problems of the boot check (ADR 0016 "The boot check"): an identity without its authenticate hook, a scope
+without its resolver, a right or rule without a decider. Each problem names the hook and ends with the fix the
+placement gives, since each framework registers hooks its own way."""
+
+from collections.abc import Collection
+from dataclasses import dataclass
+
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.ir_view import ir_map, ir_maps, ir_string
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HookFixes:
+    """How the app registers each kind of hook, ending a problem line."""
+
+    authenticate: str
+    decider: str
+    scope_resolver: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HookNeeds:
+    """The hook names the api's operations call, in first-use order."""
+
+    identities: list[str]
+    scopes: list[str]
+    deciders: list[str]
+
+
+def hook_needs(contract: ApiContract, operation_ids: Collection[str] | None = None) -> HookNeeds:
+    """The hooks the given operations call, every operation of the api by default."""
+    needs = HookNeeds(identities=[], scopes=[], deciders=[])
+
+    for operation_id in contract.operation_ids() if operation_ids is None else operation_ids:
+        operation = contract.operation(operation_id)
+        _add(needs.identities, ir_string(ir_map(operation, "access"), "identity"))
+
+        for scope in ir_maps(operation, "scopes"):
+            _add(needs.scopes, ir_string(scope, "scope"))
+
+        for requirement in ir_maps(operation, "requires"):
+            _add(needs.deciders, ir_string(requirement, "right") or ir_string(requirement, "rule"))
+
+        for field_right in ir_maps(operation, "fieldRights"):
+            _add(needs.deciders, ir_string(field_right, "right"))
+
+    return needs
+
+
+def hook_problems(
+    contract: ApiContract,
+    *,
+    identities: Collection[str],
+    scopes: Collection[str],
+    deciders: Collection[str],
+    fixes: HookFixes,
+) -> list[str]:
+    """The problem lines of the hooks the app did not register, given the names it registered."""
+    needs = hook_needs(contract)
+    problems = [
+        f"no authenticate hook for the identity '{identity}': {fixes.authenticate}"
+        for identity in needs.identities
+        if identity not in identities
+    ]
+    problems += [
+        f"no scope resolver for the scope '{scope}': {fixes.scope_resolver}"
+        for scope in needs.scopes
+        if scope not in scopes
+    ]
+    problems += [f"no decider for '{name}': {fixes.decider}" for name in needs.deciders if name not in deciders]
+
+    return problems
+
+
+def _add(names: list[str], name: str | None) -> None:
+    if name is not None and name not in names:
+        names.append(name)