pyoq-sql 1.0.2__py3-none-any.whl

pyoq/generation/pipeline.py

@@ -0,0 +1,119 @@
+"""Generation planning and execution orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from pyoq.config import Configuration
+from pyoq.errors import (
+    GenerationDriftError,
+    GenerationOwnershipError,
+    GenerationValidationError,
+)
+from pyoq.generation.contracts import (
+    ConcernRenderer,
+    DriftChecker,
+    DriftReport,
+    GenerationMode,
+    GenerationPlan,
+    ManifestStore,
+    OwnershipManifest,
+    PlanValidator,
+    PlanWriter,
+    ProjectLock,
+    RenderedFile,
+)
+from pyoq.schema import SchemaSnapshot, SchemaSource
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationPlanner:
+    renderers: tuple[ConcernRenderer, ...]
+
+    def __post_init__(self) -> None:
+        if any(not renderer.concern for renderer in self.renderers):
+            message = "rendering concern must be a non-empty string"
+            raise GenerationValidationError(message)
+        duplicate_concerns = _duplicate_concerns(self.renderers)
+        if duplicate_concerns:
+            message = f"duplicate rendering concerns: {duplicate_concerns!r}"
+            raise GenerationValidationError(message)
+
+    def plan(
+        self,
+        snapshot: SchemaSnapshot,
+        configuration: Configuration,
+    ) -> GenerationPlan:
+        rendered_files: list[RenderedFile] = []
+        for renderer in sorted(self.renderers, key=lambda candidate: candidate.concern):
+            rendered_files.extend(renderer.render(snapshot, configuration))
+        return GenerationPlan(tuple(rendered_files))
+
+
+def _duplicate_concerns(
+    renderers: tuple[ConcernRenderer, ...],
+) -> tuple[str, ...]:
+    seen: set[str] = set()
+    duplicates: set[str] = set()
+    for renderer in renderers:
+        if renderer.concern in seen:
+            duplicates.add(renderer.concern)
+        seen.add(renderer.concern)
+    return tuple(sorted(duplicates))
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationPipeline:
+    schema_source: SchemaSource
+    planner: GenerationPlanner
+    validator: PlanValidator
+    manifest_store: ManifestStore
+    drift_checker: DriftChecker
+    writer: PlanWriter
+    project_lock: ProjectLock
+
+    def execute(self, configuration: Configuration, mode: GenerationMode) -> str:
+        snapshot = self.schema_source.load(configuration)
+        plan = self.planner.plan(snapshot, configuration)
+        self.validator.validate(plan)
+        desired_manifest = OwnershipManifest.from_plan(
+            configuration.codegen_package,
+            plan,
+        )
+        with self.project_lock.acquire(configuration.project_root):
+            current_manifest = self.manifest_store.load(configuration.generated_path)
+            report = self.drift_checker.compare(
+                configuration.generated_path,
+                plan,
+                current_manifest,
+                desired_manifest,
+            )
+            if mode is GenerationMode.DRY_RUN:
+                return f"generation dry run: {report.summary()}"
+            if mode is GenerationMode.CHECK:
+                return _checked_message(report)
+            if report.is_current:
+                return "generated package is current"
+            _require_no_conflicts(report.conflicts)
+            self.writer.write(
+                configuration.generated_path,
+                plan,
+                current_manifest,
+                desired_manifest,
+            )
+        return f"generated {len(plan.files)} files"
+
+
+def _checked_message(report: DriftReport) -> str:
+    if report.is_current:
+        return "generated package is current"
+    message = f"generated package has drift: {report.summary()}"
+    raise GenerationDriftError(message)
+
+
+def _require_no_conflicts(conflicts: tuple[PurePosixPath, ...]) -> None:
+    if conflicts:
+        joined_paths = ", ".join(str(path) for path in conflicts)
+        message = f"generated package contains ownership conflicts: {joined_paths}"
+        raise GenerationOwnershipError(message)

pyoq/generation/rendering/__init__.py

@@ -0,0 +1,5 @@
+"""Generated database package rendering."""
+
+from pyoq.generation.rendering.package import GeneratedTypesRenderer
+
+__all__ = ("GeneratedTypesRenderer",)

pyoq/generation/rendering/domains.py

@@ -0,0 +1,51 @@
+"""Generated database domain type rendering."""
+
+from pathlib import PurePosixPath
+
+from pyoq.generation.contracts import RenderedFile
+from pyoq.generation.model import GeneratedPackage
+from pyoq.generation.rendering.imports import plan_annotation_imports
+from pyoq.generation.rendering.source import (
+    PythonSource,
+    literal,
+    render_all,
+    render_from_import,
+)
+
+
+def render_domains(package: GeneratedPackage) -> RenderedFile:
+    """A domain becomes a name of its own over the type it is written over.
+
+    Two domains over one base are two types, and a distinct name is what lets
+    a checker tell them apart. The value is still the base value, so nothing
+    is converted on the way in or out.
+    """
+    source = PythonSource()
+    source.line('"""Generated database domain types."""')
+    annotations = tuple(domain.base_annotation for domain in package.domains)
+    imports = plan_annotation_imports(annotations, package)
+    if package.domains:
+        source.line()
+        source.lines(tuple(sorted((*imports.standard, "from typing import NewType"))))
+        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))
+    for domain in package.domains:
+        source.line()
+        source.line(
+            f"{domain.type_name} = NewType("
+            f"{literal(domain.type_name)}, {domain.base_annotation})"
+        )
+    source.line()
+    if package.domains:
+        source.line()
+    source.lines(render_all(tuple(domain.type_name for domain in package.domains)))
+    return RenderedFile(PurePosixPath("domains.py"), source.render())
+
+
+__all__ = ("render_domains",)

pyoq/generation/rendering/enums.py

@@ -0,0 +1,29 @@
+"""Generated enum source rendering."""
+
+from pathlib import PurePosixPath
+
+from pyoq.generation.contracts import RenderedFile
+from pyoq.generation.model import GeneratedPackage
+from pyoq.generation.rendering.source import PythonSource, literal, render_all
+
+
+def render_enums(package: GeneratedPackage) -> RenderedFile:
+    source = PythonSource()
+    source.line('"""Generated database enum types."""')
+    if package.enums:
+        source.line()
+        source.line("from enum import StrEnum")
+    for enum in package.enums:
+        source.line()
+        source.line()
+        source.line(f"class {enum.class_name}(StrEnum):")
+        for member_name, member_value in enum.members:
+            source.line(f"    {member_name} = {literal(member_value)}")
+    source.line()
+    if package.enums:
+        source.line()
+    source.lines(render_all(tuple(enum.class_name for enum in package.enums)))
+    return RenderedFile(PurePosixPath("enums.py"), source.render())
+
+
+__all__ = ("render_enums",)

pyoq/generation/rendering/exports.py

@@ -0,0 +1,70 @@
+"""Generated package facade source rendering."""
+
+from pathlib import PurePosixPath
+
+from pyoq.generation.contracts import RenderedFile
+from pyoq.generation.model import GeneratedPackage
+from pyoq.generation.rendering.source import (
+    PythonSource,
+    render_all,
+    render_from_import,
+)
+
+
+def render_exports(package: GeneratedPackage) -> RenderedFile:
+    source = PythonSource()
+    source.line('"""Generated database package."""')
+    module_exports = _module_exports(package)
+    if any(names for _, names in module_exports):
+        source.line()
+    for module_name, names in module_exports:
+        if names:
+            source.lines(render_from_import(f".{module_name}", names))
+    source.line()
+    source.lines(
+        render_all(tuple(name for _, names in module_exports for name in names))
+    )
+    return RenderedFile(PurePosixPath("__init__.py"), source.render())
+
+
+def _module_exports(
+    package: GeneratedPackage,
+) -> tuple[tuple[str, tuple[str, ...]], ...]:
+    enum_names = tuple(enum.class_name for enum in package.enums)
+    row_names = tuple(
+        name
+        for table in package.tables
+        for name in (table.row_name, *(key.type_name for key in table.keys))
+    )
+    write_names = 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,
+        )
+    )
+    table_names = tuple(
+        name
+        for table in package.tables
+        for name in (table.class_name, table.constant_name)
+    )
+    relation_names = tuple(
+        relation.constant_name
+        for table in package.tables
+        for relation in table.relations
+    )
+    return (
+        ("enums", enum_names),
+        ("relations", relation_names),
+        ("rows", row_names),
+        ("tables", table_names),
+        ("writes", write_names),
+    )
+
+
+__all__ = ("render_exports",)

pyoq/generation/rendering/imports.py

@@ -0,0 +1,63 @@
+"""Import planning for generated type annotations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pyoq.generation.model import GeneratedPackage
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationImports:
+    standard: tuple[str, ...]
+    descriptor_names: tuple[str, ...]
+    enum_names: tuple[str, ...]
+    domain_names: tuple[str, ...] = ()
+
+
+def plan_annotation_imports(
+    annotations: tuple[str, ...],
+    package: GeneratedPackage,
+) -> AnnotationImports:
+    standard: list[str] = []
+    datetime_names = tuple(
+        name
+        for name in ("date", "datetime", "time", "timedelta")
+        if any(_contains_type(annotation, name) for annotation in annotations)
+    )
+    if datetime_names:
+        standard.append(f"from datetime import {', '.join(datetime_names)}")
+    if any(_contains_type(annotation, "Decimal") for annotation in annotations):
+        standard.append("from decimal import Decimal")
+    if any(_contains_type(annotation, "UUID") for annotation in annotations):
+        standard.append("from uuid import UUID")
+    descriptor_names = (
+        ("JsonValue",)
+        if any(_contains_type(annotation, "JsonValue") for annotation in annotations)
+        else ()
+    )
+    enum_names = _named(tuple(enum.class_name for enum in package.enums), annotations)
+    domain_names = _named(
+        tuple(domain.type_name for domain in package.domains), annotations
+    )
+    return AnnotationImports(
+        tuple(sorted(standard)), descriptor_names, enum_names, domain_names
+    )
+
+
+def _named(generated: tuple[str, ...], annotations: tuple[str, ...]) -> tuple[str, ...]:
+    """The generated names an annotation writes, which are the ones to import."""
+    return tuple(
+        name
+        for name in generated
+        if any(_contains_type(annotation, name) for annotation in annotations)
+    )
+
+
+def _contains_type(annotation: str, type_name: str) -> bool:
+    normalized = annotation.replace("[", " ").replace("]", " ").replace(",", " ")
+    tokens = normalized.replace("|", " ").replace(".", " ").split()
+    return type_name in tokens
+
+
+__all__ = ("AnnotationImports", "plan_annotation_imports")

pyoq/generation/rendering/package.py

@@ -0,0 +1,56 @@
+"""Generated database package rendering orchestration."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from pyoq.config import Configuration
+from pyoq.generation.contracts import RenderedFile
+from pyoq.generation.model import GeneratedPackage, build_codegen_package
+from pyoq.generation.rendering.domains import render_domains
+from pyoq.generation.rendering.enums import render_enums
+from pyoq.generation.rendering.exports import render_exports
+from pyoq.generation.rendering.relations import render_relations
+from pyoq.generation.rendering.routines import render_routines
+from pyoq.generation.rendering.rows import render_rows
+from pyoq.generation.rendering.tables import render_tables
+from pyoq.generation.rendering.writes import render_writes
+from pyoq.naming import NamingPolicy
+from pyoq.schema import SchemaSnapshot
+
+PackageFileRenderer = Callable[[GeneratedPackage], RenderedFile]
+DEFAULT_FILE_RENDERERS: tuple[PackageFileRenderer, ...] = (
+    render_domains,
+    render_enums,
+    render_exports,
+    render_relations,
+    render_routines,
+    render_rows,
+    render_tables,
+    render_writes,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedTypesRenderer:
+    naming_policy: NamingPolicy = field(default_factory=NamingPolicy)
+    file_renderers: tuple[PackageFileRenderer, ...] = DEFAULT_FILE_RENDERERS
+
+    @property
+    def concern(self) -> str:
+        return "generated-types"
+
+    def render(
+        self,
+        snapshot: SchemaSnapshot,
+        configuration: Configuration,
+    ) -> tuple[RenderedFile, ...]:
+        codegen_package = build_codegen_package(snapshot, self.naming_policy)
+        rendered_files = tuple(
+            renderer(codegen_package) for renderer in self.file_renderers
+        )
+        return tuple(sorted(rendered_files, key=lambda generated: str(generated.path)))
+
+
+__all__ = ("DEFAULT_FILE_RENDERERS", "GeneratedTypesRenderer", "PackageFileRenderer")

pyoq/generation/rendering/relations.py

@@ -0,0 +1,133 @@
+"""Generated relationship descriptor source rendering."""
+
+from pathlib import PurePosixPath
+
+from pyoq.generation.contracts import RenderedFile
+from pyoq.generation.model import (
+    GeneratedPackage,
+    GeneratedRelation,
+    GeneratedTable,
+)
+from pyoq.generation.rendering.source import (
+    PythonSource,
+    literal,
+    render_all,
+    render_from_import,
+    render_string_tuple,
+    render_subscript,
+)
+from pyoq.schema import Identifier
+
+
+def render_relations(package: GeneratedPackage) -> RenderedFile:
+    source = PythonSource()
+    source.line('"""Generated typed relationship descriptors."""')
+    has_relations = any(table.relations for table in package.tables)
+    if has_relations:
+        source.line()
+        source.line("from __future__ import annotations")
+        source.line()
+        source.line("from pyoq.descriptors import RelationshipDescriptor")
+        source.line("from pyoq.relations import RelationCardinality, RelationDirection")
+        source.line("from pyoq.schema import ReferentialAction")
+        source.line()
+        source.lines(
+            render_from_import(
+                ".rows",
+                _imported_row_names(package),
+            )
+        )
+    _render_all_relations(source, package)
+    source.line()
+    if has_relations:
+        source.line()
+    source.lines(render_all(_exported_names(package)))
+    return RenderedFile(PurePosixPath("relations.py"), source.render())
+
+
+def _render_all_relations(source: PythonSource, package: GeneratedPackage) -> None:
+    """One blank line separates the imports from the first constant.
+
+    Two is what a definition gets. These are assignments, and the import
+    ordering check reads the difference.
+    """
+    written = False
+    for table in package.tables:
+        for relation in table.relations:
+            source.line()
+            if written:
+                source.line()
+            _render_relation(source, table, relation)
+            written = True
+
+
+def _render_relation(
+    source: PythonSource,
+    table: GeneratedTable,
+    relation: GeneratedRelation,
+) -> None:
+    fact = relation.source
+    source.lines(
+        render_subscript(
+            f"{relation.constant_name}: ",
+            "RelationshipDescriptor",
+            (table.row_name, relation.target_row_name),
+            argument_indent="    ",
+            closing_indent="",
+            suffix=" = RelationshipDescriptor(",
+        )
+    )
+    source.line(f"    source_table={literal(fact.source.table.name.value)},")
+    source.line(f"    source_columns={_columns(fact.source.columns)},")
+    source.line(f"    target_table={literal(fact.target.table.name.value)},")
+    source.line(f"    target_columns={_columns(fact.target.columns)},")
+    source.line(f"    source_schema={literal(_part(fact.source.table.schema))},")
+    source.line(f"    source_catalog={literal(_part(fact.source.table.catalog))},")
+    source.line(f"    target_schema={literal(_part(fact.target.table.schema))},")
+    source.line(f"    target_catalog={literal(_part(fact.target.table.catalog))},")
+    database_name = fact.constraint.value if fact.constraint is not None else None
+    source.line(f"    database_name={literal(database_name)},")
+    source.line(f"    on_update=ReferentialAction.{fact.on_update.name},")
+    source.line(f"    on_delete=ReferentialAction.{fact.on_delete.name},")
+    source.line(f"    direction=RelationDirection.{fact.direction.name},")
+    source.line(f"    cardinality=RelationCardinality.{fact.cardinality.name},")
+    source.line(f"    optional={fact.optional!r},")
+    source.line(f"    target_row_type={relation.target_row_name},")
+    source.line(")")
+
+
+def _part(value: Identifier | None) -> str | None:
+    return None if value is None else value.value
+
+
+def _imported_row_names(package: GeneratedPackage) -> tuple[str, ...]:
+    """Only the rows this file names, because an unused import is a defect.
+
+    A table without relations is never mentioned here, so importing its row
+    would leave the generated package failing a check the project runs.
+    """
+    return tuple(
+        row_name
+        for table in package.tables
+        if table.relations
+        for row_name in (
+            table.row_name,
+            *(relation.target_row_name for relation in table.relations),
+        )
+        if row_name != "object"
+    )
+
+
+def _columns(columns: tuple[Identifier, ...]) -> str:
+    return render_string_tuple(tuple(column.value for column in columns))
+
+
+def _exported_names(package: GeneratedPackage) -> tuple[str, ...]:
+    return tuple(
+        relation.constant_name
+        for table in package.tables
+        for relation in table.relations
+    )
+
+
+__all__ = ("render_relations",)