pyoq-sql 1.0.2__py3-none-any.whl

pyoq/generation/rendering/writes.py

@@ -0,0 +1,514 @@
+"""Generated immutable write values and builder source rendering."""
+
+from __future__ import annotations
+
+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_subscript,
+    within_limit,
+)
+
+
+def render_writes(package: GeneratedPackage) -> RenderedFile:
+    source = PythonSource()
+    source.line('"""Generated immutable insert and update values."""')
+    source.line()
+    source.line("from __future__ import annotations")
+    if package.tables:
+        _render_imports(source, package)
+        if any(table.required_columns for table in package.tables):
+            _render_required_value(source)
+    for table in package.tables:
+        _render_table_writes(source, table)
+    source.line()
+    source.line()
+    source.lines(render_all(_exported_names(package)))
+    return RenderedFile(PurePosixPath("writes.py"), source.render())
+
+
+def _render_imports(source: PythonSource, package: GeneratedPackage) -> None:
+    annotations = plan_annotation_imports(_annotations(package), package)
+    has_writable = any(table.writable_columns for table in package.tables)
+    has_required = any(table.required_columns for table in package.tables)
+    has_optional = any(
+        column.writable and not column.required
+        for table in package.tables
+        for column in table.columns
+    )
+    has_overloads = any(len(table.required_columns) > 1 for table in package.tables)
+    typing_names = ["TypedDict"]
+    if has_writable:
+        typing_names.append("NotRequired")
+    if has_required:
+        typing_names.extend(("Generic", "Required", "TypeVar"))
+    if has_optional:
+        typing_names.append("Self")
+    if has_overloads:
+        typing_names.append("overload")
+    source.line()
+    typing_import = render_from_import("typing", tuple(typing_names))
+    standard_imports = (
+        "from dataclasses import dataclass",
+        *annotations.standard,
+        "\n".join(typing_import),
+    )
+    for standard_import in sorted(standard_imports):
+        source.lines(tuple(standard_import.splitlines()))
+    descriptor_names = list(annotations.descriptor_names)
+    if has_writable:
+        descriptor_names.extend(("UNSET", "UnsetType"))
+    if has_required:
+        descriptor_names.extend(("Missing", "Present"))
+    if descriptor_names:
+        source.line()
+        source.lines(render_from_import("pyoq.descriptors", tuple(descriptor_names)))
+    if annotations.enum_names:
+        source.line()
+        source.lines(render_from_import(".enums", annotations.enum_names))
+    if annotations.domain_names:
+        source.line()
+        source.lines(render_from_import(".domains", annotations.domain_names))
+
+
+def _annotations(package: GeneratedPackage) -> tuple[str, ...]:
+    return tuple(
+        column.value_annotation
+        for table in package.tables
+        for column in table.columns
+        if column.writable
+    )
+
+
+def _unset_union(annotation: str) -> str:
+    """`None` reads last in a union, so an unset marker goes before it."""
+    optional = " | None"
+    if annotation.endswith(optional):
+        return f"{annotation[: -len(optional)]} | UnsetType | None"
+    return f"{annotation} | UnsetType"
+
+
+def _render_required_value(source: PythonSource) -> None:
+    source.line()
+    source.line('_Value = TypeVar("_Value")')
+    source.line()
+    source.line()
+    source.line("def _required_value(")
+    source.line("    value: _Value | UnsetType,")
+    source.line("    field_name: str,")
+    source.line(") -> _Value:")
+    source.line("    if isinstance(value, UnsetType):")
+    source.line('        message = f"required field is missing: {field_name}"')
+    source.line("        raise ValueError(message)")
+    source.line("    return value")
+
+
+def _state_type_variable(state_name: str) -> tuple[str, ...]:
+    """A long enough column name pushes the declaration past the line limit."""
+    inline = f'{state_name} = TypeVar("{state_name}", bound=Missing | Present)'
+    if len(inline) <= 88:
+        return (inline,)
+    return (
+        within_limit(f"{state_name} = TypeVar("),
+        f'    "{state_name}",',
+        "    bound=Missing | Present,",
+        ")",
+    )
+
+
+def _render_table_writes(source: PythonSource, table: GeneratedTable) -> None:
+    writable = table.writable_columns
+    _render_typed_dict(source, f"{table.insert_name}Values", writable, insert=True)
+    _render_typed_dict(source, f"{table.update_name}Values", writable, insert=False)
+    _render_write_dataclass(source, table.insert_name, writable, insert=True)
+    _render_write_dataclass(source, table.update_name, writable, insert=False)
+    state_names = _render_state_variables(source, table)
+    _render_insert_builder(source, table, state_names)
+    _render_complete_builder(source, table, state_names)
+    _render_update_builder(source, table)
+
+
+def _render_typed_dict(
+    source: PythonSource,
+    name: str,
+    columns: tuple[GeneratedColumn, ...],
+    *,
+    insert: bool,
+) -> None:
+    source.line()
+    source.line()
+    source.line(f"class {name}(TypedDict):")
+    if not columns:
+        source.line("    pass")
+        return
+    for column in columns:
+        required = insert and column.required
+        wrapper = "Required" if required else "NotRequired"
+        source.line(f"    {column.field_name}: {wrapper}[{column.value_annotation}]")
+
+
+def _render_write_dataclass(
+    source: PythonSource,
+    name: str,
+    columns: tuple[GeneratedColumn, ...],
+    *,
+    insert: bool,
+) -> None:
+    source.line()
+    source.line()
+    source.line("@dataclass(frozen=True, slots=True)")
+    source.line(f"class {name}:")
+    ordered = _ordered_insert_columns(columns) if insert else columns
+    if not ordered:
+        source.line("    pass")
+        return
+    for column in ordered:
+        if insert and column.required:
+            source.line(f"    {column.field_name}: {column.value_annotation}")
+        else:
+            annotation = _unset_union(column.value_annotation)
+            source.line(f"    {column.field_name}: {annotation} = UNSET")
+
+
+def _ordered_insert_columns(
+    columns: tuple[GeneratedColumn, ...],
+) -> tuple[GeneratedColumn, ...]:
+    required = tuple(column for column in columns if column.required)
+    optional = tuple(column for column in columns if not column.required)
+    return required + optional
+
+
+def _render_state_variables(
+    source: PythonSource,
+    table: GeneratedTable,
+) -> tuple[str, ...]:
+    state_names = tuple(
+        f"_{table.class_name}{_pascal(column.field_name)}State"
+        for column in table.required_columns
+    )
+    if state_names:
+        source.line()
+    for state_name in state_names:
+        source.line()
+        source.lines(_state_type_variable(state_name))
+    return state_names
+
+
+def _render_insert_builder(
+    source: PythonSource,
+    table: GeneratedTable,
+    state_names: tuple[str, ...],
+) -> None:
+    source.line()
+    source.line()
+    source.line("@dataclass(frozen=True, slots=True)")
+    _render_builder_class_header(source, table.builder_name, "Generic", state_names)
+    if not table.writable_columns:
+        source.line("    pass")
+        return
+    for column in table.writable_columns:
+        source.line(
+            f"    _{column.field_name}: {_unset_union(column.value_annotation)} = UNSET"
+        )
+    for column in table.writable_columns:
+        if column.required:
+            _render_required_setter(source, table, column, state_names)
+        else:
+            _render_optional_setter(source, table, column)
+
+
+def _render_required_setter(
+    source: PythonSource,
+    table: GeneratedTable,
+    column: GeneratedColumn,
+    state_names: tuple[str, ...],
+) -> None:
+    required = table.required_columns
+    column_index = required.index(column)
+    fallback_states = list(state_names)
+    fallback_states[column_index] = "Present"
+    fallback_state_tuple = tuple(fallback_states)
+    if len(required) > 1:
+        completion_states = ["Present"] * len(required)
+        completion_states[column_index] = state_names[column_index]
+        source.line()
+        source.line("    @overload")
+        source.line(f"    def {column.field_name}(")
+        source.lines(
+            render_subscript(
+                "        self: ",
+                table.builder_name,
+                tuple(completion_states),
+                argument_indent="            ",
+                closing_indent="        ",
+                suffix=",",
+            )
+        )
+        source.line(f"        value: {column.value_annotation},")
+        source.line(f"    ) -> {table.complete_builder_name}: ...")
+        source.line()
+        source.line("    @overload")
+        source.line(f"    def {column.field_name}(")
+        source.line("        self,")
+        source.line(f"        value: {column.value_annotation},")
+        source.lines(
+            render_subscript(
+                "    ) -> ",
+                table.builder_name,
+                fallback_state_tuple,
+                argument_indent="        ",
+                closing_indent="    ",
+                suffix=": ...",
+            )
+        )
+    source.line()
+    source.line(f"    def {column.field_name}(")
+    source.line("        self,")
+    source.line(f"        value: {column.value_annotation},")
+    if len(required) == 1:
+        source.line(f"    ) -> {table.complete_builder_name}:")
+    else:
+        _render_union_return(source, table, fallback_state_tuple)
+    if len(required) == 1:
+        source.line(f"        return {table.complete_builder_name}(")
+        for candidate in table.writable_columns:
+            candidate_value = (
+                "value" if candidate is column else f"self._{candidate.field_name}"
+            )
+            source.line(f"            _{candidate.field_name}={candidate_value},")
+        source.line("        )")
+    else:
+        _render_candidate(source, table, column, "value", fallback_state_tuple)
+        _render_completion_check(source, table)
+        source.line("        return candidate")
+
+
+def _render_builder_class_header(
+    source: PythonSource,
+    class_name: str,
+    base_name: str,
+    arguments: tuple[str, ...],
+) -> None:
+    if not arguments:
+        base = "" if base_name == "Generic" else f"({base_name})"
+        source.line(f"class {class_name}{base}:")
+        return
+    inline = f"class {class_name}({base_name}[{', '.join(arguments)}]):"
+    if len(inline) <= 88:
+        source.line(inline)
+        return
+    source.line(f"class {class_name}(")
+    source.lines(
+        render_subscript(
+            "    ",
+            base_name,
+            arguments,
+            argument_indent="        ",
+            closing_indent="    ",
+            suffix="",
+        )
+    )
+    source.line("):")
+
+
+def _render_union_return(
+    source: PythonSource,
+    table: GeneratedTable,
+    builder_states: tuple[str, ...],
+) -> None:
+    builder_type = f"{table.builder_name}[{', '.join(builder_states)}]"
+    inline = f"    ) -> {builder_type} | {table.complete_builder_name}:"
+    if len(inline) <= 88:
+        source.line(inline)
+        return
+    source.line("    ) -> (")
+    source.lines(
+        render_subscript(
+            "        ",
+            table.builder_name,
+            builder_states,
+            argument_indent="            ",
+            closing_indent="        ",
+            suffix="",
+        )
+    )
+    source.line(f"        | {table.complete_builder_name}")
+    source.line("    ):")
+
+
+def _render_optional_setter(
+    source: PythonSource,
+    table: GeneratedTable,
+    column: GeneratedColumn,
+) -> None:
+    source.line()
+    source.line(f"    def {column.field_name}(")
+    source.line("        self,")
+    source.line(f"        value: {column.value_annotation},")
+    source.line("    ) -> Self:")
+    source.line("        return type(self)(")
+    for candidate in table.writable_columns:
+        value = "value" if candidate is column else f"self._{candidate.field_name}"
+        source.line(f"            _{candidate.field_name}={value},")
+    source.line("        )")
+
+
+def _render_candidate(
+    source: PythonSource,
+    table: GeneratedTable,
+    replaced: GeneratedColumn,
+    value: str,
+    candidate_states: tuple[str, ...],
+) -> None:
+    source.lines(
+        render_subscript(
+            "        candidate: ",
+            table.builder_name,
+            candidate_states,
+            argument_indent="            ",
+            closing_indent="        ",
+            suffix=f" = {table.builder_name}(",
+        )
+    )
+    for column in table.writable_columns:
+        candidate_value = value if column is replaced else f"self._{column.field_name}"
+        source.line(f"            _{column.field_name}={candidate_value},")
+    source.line("        )")
+
+
+def _render_completion_check(source: PythonSource, table: GeneratedTable) -> None:
+    source.line("        if all(")
+    source.line("            (")
+    for column in table.required_columns:
+        condition = f"not isinstance(candidate._{column.field_name}, UnsetType)"
+        source.line(f"                {condition},")
+    source.line("            )")
+    source.line("        ):")
+    source.line(f"            return {table.complete_builder_name}(")
+    _render_constructor_values(source, table, indent="                ")
+    source.line("            )")
+
+
+def _render_constructor_values(
+    source: PythonSource,
+    table: GeneratedTable,
+    *,
+    indent: str,
+    prefix: str = "candidate",
+) -> None:
+    for column in table.writable_columns:
+        source.line(f"{indent}_{column.field_name}={prefix}._{column.field_name},")
+
+
+def _render_complete_builder(
+    source: PythonSource,
+    table: GeneratedTable,
+    state_names: tuple[str, ...],
+) -> None:
+    states = tuple("Present" for _ in state_names)
+    source.line()
+    source.line()
+    source.line("@dataclass(frozen=True, slots=True)")
+    _render_builder_class_header(
+        source,
+        table.complete_builder_name,
+        table.builder_name,
+        states,
+    )
+    source.line(f"    def build(self) -> {table.insert_name}:")
+    columns = _ordered_insert_columns(table.writable_columns)
+    if not columns:
+        source.line(f"        return {table.insert_name}()")
+        return
+    source.line(f"        return {table.insert_name}(")
+    for column in columns:
+        source.lines(_build_argument(column))
+    source.line("        )")
+
+
+def _build_argument(column: GeneratedColumn) -> tuple[str, ...]:
+    """Wrap the call rather than the name, because only the call can wrap."""
+    if not column.required:
+        return (f"            {column.field_name}=self._{column.field_name},",)
+    inline = (
+        f"            {column.field_name}=_required_value("
+        f"self._{column.field_name}, {literal(column.field_name)}),"
+    )
+    if len(inline) <= LINE_LIMIT:
+        return (inline,)
+    return (
+        f"            {column.field_name}=_required_value(",
+        f"                self._{column.field_name},",
+        f"                {literal(column.field_name)},",
+        "            ),",
+    )
+
+
+def _render_update_builder(source: PythonSource, table: GeneratedTable) -> None:
+    source.line()
+    source.line()
+    source.line("@dataclass(frozen=True, slots=True)")
+    source.line(f"class {table.update_builder_name}:")
+    if not table.writable_columns:
+        source.line(f"    def build(self) -> {table.update_name}:")
+        source.line(f"        return {table.update_name}()")
+        return
+    for column in table.writable_columns:
+        source.line(
+            f"    _{column.field_name}: {_unset_union(column.value_annotation)} = UNSET"
+        )
+    for column in table.writable_columns:
+        _render_update_setter(source, table, column)
+    source.line()
+    source.line(f"    def build(self) -> {table.update_name}:")
+    source.line(f"        return {table.update_name}(")
+    for column in table.writable_columns:
+        source.line(f"            {column.field_name}=self._{column.field_name},")
+    source.line("        )")
+
+
+def _render_update_setter(
+    source: PythonSource,
+    table: GeneratedTable,
+    replaced: GeneratedColumn,
+) -> None:
+    source.line()
+    source.line(f"    def {replaced.field_name}(")
+    source.line("        self,")
+    source.line(f"        value: {replaced.value_annotation},")
+    source.line(f"    ) -> {table.update_builder_name}:")
+    source.line(f"        return {table.update_builder_name}(")
+    for column in table.writable_columns:
+        value = "value" if column is replaced else f"self._{column.field_name}"
+        source.line(f"            _{column.field_name}={value},")
+    source.line("        )")
+
+
+def _pascal(value: str) -> str:
+    return "".join(part[:1].upper() + part[1:] for part in value.split("_"))
+
+
+def _exported_names(package: GeneratedPackage) -> tuple[str, ...]:
+    return tuple(
+        name
+        for table in package.tables
+        for name in (
+            table.insert_name,
+            f"{table.insert_name}Values",
+            table.update_name,
+            f"{table.update_name}Values",
+            table.builder_name,
+            table.update_builder_name,
+        )
+    )
+
+
+__all__ = ("render_writes",)

pyoq/generation/validation.py

@@ -0,0 +1,27 @@
+"""Generated Python syntax validation."""
+
+from __future__ import annotations
+
+import ast
+
+from pyoq.errors import GenerationValidationError
+from pyoq.generation.contracts import GenerationPlan
+
+
+class PythonSyntaxValidator:
+    def validate(self, plan: GenerationPlan) -> None:
+        for generated_file in plan.files:
+            if generated_file.path.suffix not in {".py", ".pyi"}:
+                continue
+            try:
+                ast.parse(
+                    generated_file.content,
+                    filename=str(generated_file.path),
+                    type_comments=True,
+                )
+            except SyntaxError as error:
+                message = (
+                    f"invalid generated Python in {generated_file.path}: "
+                    f"line {error.lineno}"
+                )
+                raise GenerationValidationError(message) from error