pyoq-sql 1.0.2__py3-none-any.whl

pyoq/generation/rendering/tables.py

@@ -0,0 +1,300 @@
+"""Generated table and column descriptor source rendering."""
+
+from pathlib import PurePosixPath
+
+from pyoq.generation.contracts import RenderedFile
+from pyoq.generation.model import GeneratedColumn, GeneratedPackage, GeneratedTable
+from pyoq.generation.rendering.imports import plan_annotation_imports
+from pyoq.generation.rendering.source import (
+    LINE_LIMIT,
+    PythonSource,
+    literal,
+    render_all,
+    render_from_import,
+    render_string_tuple,
+    render_subscript,
+)
+from pyoq.query.results import family_for_kind
+from pyoq.schema import TypeKind
+
+
+def render_tables(package: GeneratedPackage) -> RenderedFile:
+    source = PythonSource()
+    source.line('"""Generated table and column descriptors."""')
+    source.line()
+    source.line("from __future__ import annotations")
+    if package.tables:
+        _render_imports(source, package)
+    for table in package.tables:
+        _render_table(source, table)
+    source.line()
+    source.line()
+    source.lines(render_all(_exported_names(package)))
+    return RenderedFile(PurePosixPath("tables.py"), source.render())
+
+
+def _render_imports(source: PythonSource, package: GeneratedPackage) -> None:
+    annotations = plan_annotation_imports(_column_annotations(package), package)
+    source.line()
+    source.lines(tuple(sorted((*annotations.standard, "from typing import ClassVar"))))
+    source.line()
+    descriptor_names = ["ColumnDescriptor", "TableDescriptor"]
+    if any(table.keys for table in package.tables):
+        descriptor_names.append("KeyDescriptor")
+    if any(table.required_columns for table in package.tables):
+        descriptor_names.append("Missing")
+    descriptor_names.extend(annotations.descriptor_names)
+    source.lines(
+        render_from_import(
+            "pyoq.descriptors",
+            tuple(descriptor_names),
+        )
+    )
+    source.line("from pyoq.query import ScalarFamily")
+    if any(table.keys for table in package.tables):
+        source.line("from pyoq.schema import KeyKind")
+    source.line()
+    if annotations.enum_names:
+        source.lines(render_from_import(".enums", annotations.enum_names))
+    if annotations.domain_names:
+        source.lines(render_from_import(".domains", annotations.domain_names))
+    row_names = tuple(
+        name
+        for table in package.tables
+        for name in (table.row_name, *(key.type_name for key in table.keys))
+    )
+    source.lines(render_from_import(".rows", row_names))
+    write_names = tuple(
+        name for table in package.tables for name in _write_names(table)
+    )
+    source.lines(render_from_import(".writes", write_names))
+
+
+def _write_names(table: GeneratedTable) -> tuple[str, ...]:
+    return (
+        table.insert_name,
+        table.update_name,
+        table.update_builder_name,
+        _returned_builder_name(table),
+    )
+
+
+def _returned_builder_name(table: GeneratedTable) -> str:
+    if table.required_columns:
+        return table.builder_name
+    return table.complete_builder_name
+
+
+def _column_annotations(package: GeneratedPackage) -> tuple[str, ...]:
+    return tuple(
+        column.value_annotation for table in package.tables for column in table.columns
+    )
+
+
+def _class_declaration(table: GeneratedTable) -> tuple[str, ...]:
+    """Long enough table names push the base past the line limit."""
+    inline = (
+        f"class {table.class_name}(TableDescriptor["
+        f"{table.row_name}, {table.insert_name}, {table.update_name}]):"
+    )
+    if len(inline) <= 88:
+        return (inline,)
+    return (
+        f"class {table.class_name}(",
+        *render_subscript(
+            "    ",
+            "TableDescriptor",
+            (table.row_name, table.insert_name, table.update_name),
+            argument_indent="        ",
+            closing_indent="    ",
+            suffix="",
+        ),
+        "):",
+    )
+
+
+def _render_table(source: PythonSource, table: GeneratedTable) -> None:
+    required_states = tuple("Missing" for _ in table.required_columns)
+    source.line()
+    source.line()
+    source.lines(_class_declaration(table))
+    for column in table.columns:
+        _render_column(source, table, column)
+    _render_column_tuple(source, table)
+    for key in table.keys:
+        database_name = literal(
+            key.source.name.value if key.source.name is not None else None
+        )
+        column_names = render_string_tuple(
+            tuple(column.source.name.value for column in key.columns)
+        )
+        _render_descriptor_assignment(
+            source,
+            key.constant_name,
+            "KeyDescriptor",
+            key.type_name,
+            "KeyDescriptor",
+            (
+                f"KeyKind.{key.source.kind.name}",
+                column_names,
+                database_name,
+            ),
+        )
+    source.line()
+    source.line("    @staticmethod")
+    if required_states:
+        source.lines(
+            render_subscript(
+                "    def builder() -> ",
+                table.builder_name,
+                required_states,
+                argument_indent="        ",
+                closing_indent="    ",
+                suffix=":",
+            )
+        )
+    else:
+        source.line(f"    def builder() -> {table.complete_builder_name}:")
+    source.line(
+        f"        return {table.complete_builder_name}()"
+        if not table.required_columns
+        else f"        return {table.builder_name}()"
+    )
+    source.line()
+    source.line("    @staticmethod")
+    source.line(f"    def update_builder() -> {table.update_builder_name}:")
+    source.line(f"        return {table.update_builder_name}()")
+    source.line()
+    source.line()
+    inline = f"{table.constant_name} = {table.class_name}("
+    wrapped = len(inline) > LINE_LIMIT
+    indent = "        " if wrapped else "    "
+    source.lines(_constant_head(table))
+    source.line(f"{indent}{literal(table.source.name.value)},")
+    source.line(f"{indent}{literal(table.schema_name)},")
+    source.line(f"{indent}{literal(table.catalog_name)},")
+    source.line(f"{indent}{table.row_name},")
+    source.lines(("    )", ")") if wrapped else (")",))
+
+
+def _render_column_tuple(source: PythonSource, table: GeneratedTable) -> None:
+    """A table has at least one column, which the schema model enforces."""
+    names = tuple(column.constant_name for column in table.columns)
+    inline = f"    COLUMNS: ClassVar[tuple[object, ...]] = ({names[0]},)"
+    if len(names) == 1 and len(inline) <= LINE_LIMIT:
+        source.line(inline)
+        return
+    source.line("    COLUMNS: ClassVar[tuple[object, ...]] = (")
+    for name in names:
+        source.line(f"        {name},")
+    source.line("    )")
+
+
+def _render_column(
+    source: PythonSource,
+    table: GeneratedTable,
+    generated_column: GeneratedColumn,
+) -> None:
+    _render_descriptor_assignment(
+        source,
+        generated_column.constant_name,
+        "ColumnDescriptor",
+        generated_column.value_annotation,
+        "ColumnDescriptor",
+        (
+            literal(generated_column.source.name.value),
+            f"nullable={generated_column.source.nullable!r}",
+            f"writable={generated_column.writable!r}",
+            f"has_default={generated_column.source.default is not None!r}",
+            f"generated={generated_column.source.generated is not None!r}",
+            f"scalar_family=ScalarFamily.{_scalar_family(generated_column.source.data_type.kind)}",
+            f"table_name={literal(table.source.name.value)}",
+            f"schema_name={literal(table.schema_name)}",
+            f"catalog_name={literal(table.catalog_name)}",
+            f"field_name={literal(generated_column.field_name)}",
+            f"value_type={_value_type(generated_column)}",
+        ),
+    )
+
+
+def _value_type(generated_column: GeneratedColumn) -> str:
+    """The class this column reads back as, where one class can name it.
+
+    Any JSON is a union of everything JSON can be, which is no class at all.
+    The scalar family says JSON on its own, and reading the column back asks
+    the family when the declared type names nothing.
+    """
+    if generated_column.source.data_type.kind is TypeKind.JSON:
+        return "None"
+    return generated_column.annotation
+
+
+def _scalar_family(kind: TypeKind) -> str:
+    """The name of the family this kind holds, asked of the one authority.
+
+    Rendered rather than restated, so generated code and the code that reads
+    it back cannot disagree about what a column holds.
+    """
+    return family_for_kind(kind).name
+
+
+def _constant_head(table: GeneratedTable) -> tuple[str, ...]:
+    """Wrap in parentheses when the name and the class will not share a line."""
+    inline = f"{table.constant_name} = {table.class_name}("
+    if len(inline) <= LINE_LIMIT:
+        return (inline,)
+    return (f"{table.constant_name} = (", f"    {table.class_name}(")
+
+
+def _render_descriptor_assignment(
+    source: PythonSource,
+    name: str,
+    descriptor: str,
+    parameter: str,
+    constructor: str,
+    arguments: tuple[str, ...],
+) -> None:
+    """Break where a formatter would break, in the order it prefers.
+
+    The value is parenthesized first and the annotation split only when even
+    that does not fit, because generated code a formatter would rewrite is
+    generated code a project cannot check.
+    """
+    annotated = f"{descriptor}[{parameter}]"
+    declaration = f"    {name}: ClassVar[{annotated}]"
+    argument_indent = "        "
+    closing_lines: tuple[str, ...] = ("    )",)
+    if len(f"{declaration} = {constructor}(") <= 88:
+        source.line(f"{declaration} = {constructor}(")
+    elif len(f"{declaration} = (") <= 88:
+        source.line(f"{declaration} = (")
+        source.line(f"        {constructor}(")
+        argument_indent = "            "
+        closing_lines = ("        )", "    )")
+    else:
+        source.line(f"    {name}: ClassVar[")
+        source.lines(
+            render_subscript(
+                "        ",
+                descriptor,
+                (parameter,),
+                argument_indent="            ",
+                closing_indent="        ",
+                suffix="",
+            )
+        )
+        source.line(f"    ] = {constructor}(")
+    for argument in arguments:
+        source.line(f"{argument_indent}{argument},")
+    source.lines(closing_lines)
+
+
+def _exported_names(package: GeneratedPackage) -> tuple[str, ...]:
+    return tuple(
+        name
+        for table in package.tables
+        for name in (table.class_name, table.constant_name)
+    )
+
+
+__all__ = ("render_tables",)