pyoq-sql 1.0.2__py3-none-any.whl

pyoq/generation/rendering/routines.py

@@ -0,0 +1,396 @@
+"""Generated stored routine call rendering."""
+
+from pathlib import PurePosixPath
+
+from pyoq.generation.contracts import RenderedFile
+from pyoq.generation.model import (
+    GeneratedOverload,
+    GeneratedPackage,
+    GeneratedRoutine,
+    GeneratedRoutineParameter,
+)
+from pyoq.generation.rendering.imports import plan_annotation_imports
+from pyoq.generation.rendering.source import (
+    PythonSource,
+    literal,
+    render_all,
+    render_from_import,
+)
+from pyoq.schema import ParameterMode
+
+
+def render_routines(package: GeneratedPackage) -> RenderedFile:
+    """A routine as a call whose signature is the database's, not a caller's.
+
+    Arity, parameter order, and types come from the catalog, so a call that
+    no longer matches the routine stops type checking rather than failing at
+    the server.
+    """
+    source = PythonSource()
+    source.line('"""Generated database routine calls."""')
+    if package.routines:
+        _render_imports(source, package)
+    for routine in package.routines:
+        if routine.returns_annotation is not None:
+            source.line()
+            _render_declaration(source, routine)
+    for routine in package.routines:
+        _render_routine(source, routine)
+    for overload in package.overloads:
+        _render_overload(source, overload)
+    source.line()
+    if package.routines:
+        source.line()
+    source.lines(
+        render_all(
+            tuple(routine.function_name for routine in package.routines)
+            + tuple(item.function_name for item in package.overloads)
+        )
+    )
+    return RenderedFile(PurePosixPath("routines.py"), source.render())
+
+
+def _render_imports(source: PythonSource, package: GeneratedPackage) -> None:
+    annotations = tuple(
+        annotation
+        for routine in package.routines
+        for annotation in _annotations(routine)
+    )
+    imports = plan_annotation_imports(annotations, package)
+    source.line()
+    source.line("from __future__ import annotations")
+    source.line()
+    if package.overloads:
+        source.line("from typing import overload")
+        source.line()
+    errors = _error_import_names(package)
+    if errors:
+        source.lines(render_from_import("pyoq.errors", tuple(errors)))
+    if imports.standard:
+        source.lines(imports.standard)
+        source.line()
+    if imports.descriptor_names:
+        source.lines(render_from_import("pyoq.descriptors", imports.descriptor_names))
+    source.lines(render_from_import("pyoq.query", _query_import_names(package)))
+    if any(
+        item.sql_parameters
+        for item in package.routines
+        if item.unsupported_reason is None
+    ):
+        source.lines(render_from_import("pyoq.query.routines", ("argument",)))
+    if package.overloads or any(_has_defaults(item) for item in package.routines):
+        source.lines(render_from_import("pyoq.unset", ("UNSET", "UnsetType")))
+    if imports.enum_names:
+        source.line()
+        source.lines(render_from_import(".enums", imports.enum_names))
+    if imports.domain_names:
+        source.line()
+        source.lines(render_from_import(".domains", imports.domain_names))
+
+
+def _error_import_names(package: GeneratedPackage) -> tuple[str, ...]:
+    names: list[str] = []
+    if any(routine.unsupported_reason is not None for routine in package.routines):
+        names.append("UnsupportedQueryError")
+    if any(_needs_default_gap_guard(routine) for routine in package.routines):
+        names.append("QueryValidationError")
+    return tuple(names)
+
+
+def _query_import_names(package: GeneratedPackage) -> tuple[str, ...]:
+    routines = package.routines
+    functions = tuple(item for item in routines if item.returns_annotation is not None)
+    procedures = tuple(item for item in routines if item.returns_annotation is None)
+    supported = tuple(item for item in procedures if item.unsupported_reason is None)
+    names: list[str] = []
+    if any(item.given_parameters for item in routines):
+        names.append("Expression")
+    if functions:
+        names.extend(("ComputedExpression", "vendor_function"))
+    if procedures:
+        names.append("Call")
+    if supported:
+        names.append("call")
+    if any(item.outputs for item in supported):
+        names.append("routine_output")
+    if any(_has_defaults(item) for item in routines):
+        names.append("NodeProvider")
+    return tuple(names)
+
+
+def _annotations(routine: GeneratedRoutine) -> tuple[str, ...]:
+    """What the input signature and output descriptor write."""
+    given = tuple(parameter.annotation for parameter in routine.given_parameters)
+    outputs = tuple(parameter.annotation for parameter in routine.outputs)
+    if routine.returns_annotation is None:
+        return (*given, *outputs)
+    return (*given, *outputs, routine.returns_annotation)
+
+
+def _render_routine(source: PythonSource, routine: GeneratedRoutine) -> None:
+    source.line()
+    source.line()
+    given = routine.given_parameters
+    _render_signature(source, routine.function_name, given, _returns(routine))
+    if routine.unsupported_reason is not None:
+        source.line(f'    """Refuse {routine.source.name.value} before SQL is sent."""')
+        source.line("    raise UnsupportedQueryError(")
+        source.line(f"        {literal(routine.unsupported_reason)}")
+        source.line("    )")
+        return
+    if _has_defaults(routine):
+        _render_dynamic_call(source, routine)
+        return
+    arguments = ", ".join(
+        _sql_argument(parameter) for parameter in routine.sql_parameters
+    )
+    named = literal(routine.source.name.value)
+    if routine.returns_annotation is None:
+        source.line(f'    """Run {routine.source.name.value}."""')
+        _render_run(source, routine, named, arguments, given)
+        return
+    source.line(f'    """Ask {routine.source.name.value} for a value."""')
+    source.line(f"    return _{routine.function_name}({arguments})")
+
+
+def _render_overload(source: PythonSource, overload: GeneratedOverload) -> None:
+    """One name for routines a database lets share one, chosen by the call.
+
+    The declarations give a call site the exact signature it wrote, and the
+    one that carries them out reads the parameters no shorter call was given
+    as unset, so nothing is asserted and nothing is suppressed.
+    """
+    widest = overload.routines[-1].given_parameters
+    for member in overload.routines:
+        source.line()
+        source.line()
+        source.line("@overload")
+        _render_signature(
+            source,
+            overload.function_name,
+            member.given_parameters,
+            _returns(member),
+            body="...",
+        )
+    source.line()
+    source.line()
+    _render_optional_signature(
+        source, overload, widest, len(overload.routines[0].given_parameters)
+    )
+    named = overload.routines[0].source.name.value
+    source.line(f'    """Call {named}, whichever of them the arguments name."""')
+    for member in overload.routines[:-1]:
+        count = len(member.given_parameters)
+        source.line(f"    if {widest[count].field_name} is UNSET:")
+        given = ", ".join(item.field_name for item in member.given_parameters)
+        source.line(f"        return {member.function_name}({given})")
+    last = overload.routines[-1]
+    given = ", ".join(item.field_name for item in last.given_parameters)
+    source.line(f"    return {last.function_name}({given})")
+
+
+def _render_optional_signature(
+    source: PythonSource,
+    overload: GeneratedOverload,
+    widest: tuple[GeneratedRoutineParameter, ...],
+    required: int,
+) -> None:
+    """Everything past the shortest call is unset until it is given."""
+    source.line(f"def {overload.function_name}(")
+    for position, parameter in enumerate(widest):
+        annotation = parameter.annotation
+        written = f"Expression[{annotation}] | {annotation}"
+        if position < required:
+            source.line(f"    {parameter.field_name}: {written},")
+        else:
+            source.line(f"    {parameter.field_name}: {written} | UnsetType = UNSET,")
+    source.line(f") -> {_shared_return(overload)}:")
+
+
+def _shared_return(overload: GeneratedOverload) -> str:
+    """What the call answers with, which is any of what its routines answer with."""
+    written = sorted({_returns(member) for member in overload.routines})
+    return " | ".join(written)
+
+
+def _returns(routine: GeneratedRoutine) -> str:
+    """What a call answers with: a value for a function, a row for a procedure."""
+    if routine.returns_annotation is not None:
+        return f"ComputedExpression[{routine.returns_annotation}]"
+    outputs = routine.outputs
+    if not outputs:
+        return "Call[object]"
+    written = ", ".join(parameter.annotation for parameter in outputs)
+    return f"Call[tuple[{written}]]"
+
+
+def _render_signature(
+    source: PythonSource,
+    function_name: str,
+    given: tuple[GeneratedRoutineParameter, ...],
+    returns: str,
+    *,
+    body: str | None = None,
+) -> None:
+    """One parameter per line, because a signature has no width to spare."""
+    if not given:
+        source.line(f"def {function_name}() -> {returns}:{_body(body)}")
+        return
+    source.line(f"def {function_name}(")
+    for parameter in given:
+        annotation = parameter.annotation
+        written = f"Expression[{annotation}] | {annotation}"
+        if parameter.source.has_default:
+            written = f"{written} | UnsetType = UNSET"
+        source.line(f"    {parameter.field_name}: {written},")
+    source.line(f") -> {returns}:{_body(body)}")
+
+
+def _body(body: str | None) -> str:
+    return "" if body is None else f" {body}"
+
+
+def _render_declaration(source: PythonSource, routine: GeneratedRoutine) -> None:
+    """A function the catalog declared, named where the catalog keeps it.
+
+    Written a line at a time where it says a schema, because one line of it
+    would be longer than a generated file is allowed to hold.
+    """
+    name = f"_{routine.function_name}"
+    named = literal(routine.source.name.value)
+    kept = _kept_in(routine)
+    if not kept:
+        source.line(f"{name} = vendor_function({routine.returns_annotation}, {named})")
+        return
+    source.line(f"{name} = vendor_function(")
+    source.line(f"    {routine.returns_annotation},")
+    source.line(f"    {named},")
+    for part in kept:
+        source.line(f"    {part},")
+    source.line(")")
+
+
+def _render_run(
+    source: PythonSource,
+    routine: GeneratedRoutine,
+    named: str,
+    arguments: str,
+    given: tuple[GeneratedRoutineParameter, ...],
+) -> None:
+    """A procedure run where the catalog keeps it, one line at a time if long."""
+    kept = _kept_in(routine)
+    answered = _answered_with(routine)
+    if not kept and not answered:
+        source.line(f"    return call({named}{_comma(given)}{arguments})")
+        return
+    source.line("    return call(")
+    source.line(f"        {named},")
+    for parameter in routine.sql_parameters:
+        source.line(f"        {_sql_argument(parameter)},")
+    for part in kept:
+        source.line(f"        {part},")
+    source.line(f"    ){answered}")
+
+
+def _answered_with(routine: GeneratedRoutine) -> str:
+    """What the procedure answers through, which is its OUT and INOUT values.
+
+    A procedure that reads every parameter answers with nothing, and one that
+    writes any of them answers with a row of those, named as the catalog names
+    them and read back as the types it declared.
+    """
+    outputs = routine.outputs
+    if not outputs:
+        return ""
+    expressions = tuple(
+        f"routine_output({parameter.annotation.removesuffix(' | None')}, "
+        f"{literal(_output_name(parameter))}, nullable={parameter.source.nullable})"
+        for parameter in outputs
+    )
+    if len(expressions) == 1:
+        return f".returning({expressions[0]})"
+    written = "\n".join(f"        {expression}," for expression in expressions)
+    return f".returning(\n{written}\n    )"
+
+
+def _render_dynamic_call(source: PythonSource, routine: GeneratedRoutine) -> None:
+    """Build only the trailing arguments whose defaults callers override."""
+    source.line("    arguments: list[NodeProvider] = []")
+    previous_default: GeneratedRoutineParameter | None = None
+    for parameter in routine.sql_parameters:
+        if parameter.source.mode is ParameterMode.OUT:
+            source.line("    arguments.append(argument(None))")
+            continue
+        if parameter.source.has_default:
+            _render_optional_argument(source, parameter, previous_default)
+            previous_default = parameter
+            continue
+        source.line(f"    arguments.append(argument({parameter.field_name}))")
+    if routine.returns_annotation is not None:
+        source.line(f"    return _{routine.function_name}(*arguments)")
+        return
+    named = literal(routine.source.name.value)
+    kept = _kept_in(routine)
+    keywords = "".join(f", {part}" for part in kept)
+    source.line(
+        f"    return call({named}, *arguments{keywords}){_answered_with(routine)}"
+    )
+
+
+def _render_optional_argument(
+    source: PythonSource,
+    parameter: GeneratedRoutineParameter,
+    previous: GeneratedRoutineParameter | None,
+) -> None:
+    if previous is not None:
+        source.line(
+            f"    if {previous.field_name} is UNSET and "
+            f"{parameter.field_name} is not UNSET:"
+        )
+        source.line(
+            '        raise QueryValidationError("routine defaults cannot be skipped")'
+        )
+    source.line(f"    if {parameter.field_name} is not UNSET:")
+    source.line(f"        arguments.append(argument({parameter.field_name}))")
+
+
+def _has_defaults(routine: GeneratedRoutine) -> bool:
+    return any(parameter.source.has_default for parameter in routine.given_parameters)
+
+
+def _needs_default_gap_guard(routine: GeneratedRoutine) -> bool:
+    return (
+        sum(parameter.source.has_default for parameter in routine.given_parameters) > 1
+    )
+
+
+def _output_name(parameter: GeneratedRoutineParameter) -> str:
+    """What the answered column is called, which is the parameter's own name."""
+    named = parameter.source.name
+    return parameter.field_name if named is None else named.value
+
+
+def _kept_in(routine: GeneratedRoutine) -> tuple[str, ...]:
+    """Where the catalog says the routine is, written as the call's own words.
+
+    A routine outside the search path resolves to nothing, and one whose name
+    another schema shares resolves to the wrong one, so the schema the catalog
+    gave is carried into every generated call.
+    """
+    if routine.schema_name is None:
+        return ()
+    return (f"schema={literal(routine.schema_name)}",)
+
+
+def _sql_argument(parameter: GeneratedRoutineParameter) -> str:
+    """A supplied value, or the placeholder PostgreSQL requires for OUT."""
+    if parameter.source.mode is ParameterMode.OUT:
+        return "argument(None)"
+    return f"argument({parameter.field_name})"
+
+
+def _comma(parameters: tuple[object, ...]) -> str:
+    return ", " if parameters else ""
+
+
+__all__ = ("render_routines",)

pyoq/generation/rendering/rows.py

@@ -0,0 +1,79 @@
+"""Generated immutable row and key source rendering."""
+
+from pathlib import PurePosixPath
+
+from pyoq.generation.contracts import RenderedFile
+from pyoq.generation.model import GeneratedKey, GeneratedPackage, GeneratedTable
+from pyoq.generation.rendering.imports import plan_annotation_imports
+from pyoq.generation.rendering.source import (
+    PythonSource,
+    render_all,
+    render_from_import,
+    within_limit,
+)
+
+
+def render_rows(package: GeneratedPackage) -> RenderedFile:
+    source = PythonSource()
+    source.line('"""Generated immutable row and key value types."""')
+    source.line()
+    source.line("from __future__ import annotations")
+    if package.tables:
+        source.line()
+        source.line("from dataclasses import dataclass")
+        imports = plan_annotation_imports(_annotations(package), package)
+        source.lines(imports.standard)
+        if imports.descriptor_names:
+            source.line()
+            source.lines(
+                render_from_import("pyoq.descriptors", imports.descriptor_names)
+            )
+        if imports.enum_names:
+            source.line()
+            source.lines(render_from_import(".enums", imports.enum_names))
+        if imports.domain_names:
+            source.line()
+            source.lines(render_from_import(".domains", imports.domain_names))
+    for table in package.tables:
+        _render_row(source, table)
+        for key in table.keys:
+            _render_key(source, key)
+    source.line()
+    source.line()
+    source.lines(render_all(_exported_names(package)))
+    return RenderedFile(PurePosixPath("rows.py"), source.render())
+
+
+def _annotations(package: GeneratedPackage) -> tuple[str, ...]:
+    return tuple(
+        column.value_annotation for table in package.tables for column in table.columns
+    )
+
+
+def _render_row(source: PythonSource, table: GeneratedTable) -> None:
+    source.line()
+    source.line()
+    source.line("@dataclass(frozen=True, slots=True)")
+    source.line(within_limit(f"class {table.row_name}:"))
+    for column in table.columns:
+        source.line(f"    {column.field_name}: {column.value_annotation}")
+
+
+def _render_key(source: PythonSource, key: GeneratedKey) -> None:
+    source.line()
+    source.line()
+    source.line("@dataclass(frozen=True, slots=True)")
+    source.line(within_limit(f"class {key.type_name}:"))
+    for column in key.columns:
+        source.line(f"    {column.field_name}: {column.value_annotation}")
+
+
+def _exported_names(package: GeneratedPackage) -> tuple[str, ...]:
+    names: list[str] = []
+    for table in package.tables:
+        names.append(table.row_name)
+        names.extend(key.type_name for key in table.keys)
+    return tuple(names)
+
+
+__all__ = ("render_rows",)

pyoq/generation/rendering/source.py

@@ -0,0 +1,121 @@
+"""Deterministic Python source assembly."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Final
+
+LINE_LIMIT: Final = 88
+
+
+@dataclass(slots=True)
+class PythonSource:
+    _lines: list[str] = field(default_factory=list[str])
+
+    def line(self, value: str = "") -> None:
+        self._lines.append(value.rstrip())
+
+    def lines(self, values: tuple[str, ...]) -> None:
+        for value in values:
+            self.line(value)
+
+    def render(self) -> str:
+        return "\n".join(self._lines).rstrip() + "\n"
+
+
+def literal(value: str | None) -> str:
+    return "None" if value is None else json.dumps(value, ensure_ascii=False)
+
+
+def render_string_tuple(values: tuple[str, ...]) -> str:
+    rendered = ", ".join(literal(value) for value in values)
+    trailing_comma = "," if len(values) == 1 else ""
+    return f"({rendered}{trailing_comma})"
+
+
+def render_all(names: tuple[str, ...]) -> tuple[str, ...]:
+    if not names:
+        return ("__all__ = ()",)
+    if len(names) == 1:
+        return (f'__all__ = ("{names[0]}",)',)
+    lines = ["__all__ = ("]
+    lines.extend(f'    "{name}",' for name in sorted(names, key=_export_name_key))
+    lines.append(")")
+    return tuple(lines)
+
+
+def render_from_import(module: str, names: tuple[str, ...]) -> tuple[str, ...]:
+    ordered_names = tuple(sorted(set(names), key=_import_name_key))
+    if not ordered_names:
+        return ()
+    inline = f"from {module} import {', '.join(ordered_names)}"
+    if len(inline) <= LINE_LIMIT:
+        return (inline,)
+    lines = [f"from {module} import ("]
+    lines.extend(f"    {name}," for name in ordered_names)
+    lines.append(")")
+    return tuple(lines)
+
+
+def within_limit(line: str) -> str:
+    """Suppress the length rule on a line only a longer name could shorten.
+
+    A formatter breaks this line where it can and still leaves it over the
+    limit, because what overflows is an identifier the database chose. A line
+    that is one unbroken word is already exempt from the rule, so suppressing
+    it there would leave a directive that reports itself as unused.
+    """
+    if len(line) <= LINE_LIMIT or " " not in line.strip():
+        return line
+    return f"{line}  # noqa: E501"
+
+
+def render_subscript(
+    prefix: str,
+    name: str,
+    arguments: tuple[str, ...],
+    *,
+    argument_indent: str,
+    closing_indent: str,
+    suffix: str,
+) -> tuple[str, ...]:
+    inline = f"{prefix}{name}[{', '.join(arguments)}]{suffix}"
+    if len(inline) <= LINE_LIMIT:
+        return (inline,)
+    lines = [within_limit(f"{prefix}{name}[")]
+    separator = "" if len(arguments) == 1 else ","
+    lines.extend(f"{argument_indent}{argument}{separator}" for argument in arguments)
+    lines.append(f"{closing_indent}]{suffix}")
+    return tuple(lines)
+
+
+def _export_name_key(name: str) -> tuple[int, str]:
+    """Order `__all__` the way a linter checking it expects to find it.
+
+    Same grouping as an import block, but comparing letters as written rather
+    than folded, because that is the order the check is written against.
+    """
+    return _import_name_key(name)[0], name
+
+
+def _import_name_key(name: str) -> tuple[int, str]:
+    if name.isupper():
+        category = 0
+    elif name[0].isupper():
+        category = 1
+    else:
+        category = 2
+    return category, name.casefold()
+
+
+__all__ = (
+    "LINE_LIMIT",
+    "PythonSource",
+    "literal",
+    "render_all",
+    "render_from_import",
+    "render_string_tuple",
+    "render_subscript",
+    "within_limit",
+)