pyoq-sql 1.0.2__py3-none-any.whl

pyoq/generation/model.py

@@ -0,0 +1,1001 @@
+"""Canonical Python generation model derived from a schema snapshot."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pyoq.config import DatabaseDialect
+from pyoq.naming import (
+    NameRequest,
+    NamingPolicy,
+    NamingResult,
+    NamingScope,
+    PythonNameStyle,
+)
+from pyoq.relations import (
+    RelationDirection,
+    RelationGraph,
+    TypedRelation,
+    build_relation_graph,
+)
+from pyoq.schema import (
+    Catalog,
+    Column,
+    Domain,
+    EnumType,
+    Identifier,
+    Key,
+    KeyKind,
+    ObjectReference,
+    ParameterMode,
+    Routine,
+    RoutineKind,
+    RoutineParameter,
+    Schema,
+    SchemaSnapshot,
+    SqlType,
+    Table,
+    TypeKind,
+)
+
+_FIELD_RESERVED_NAMES = (
+    "build",
+    "builder",
+    "update_builder",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedColumn:
+    source: Column
+    field_name: str
+    constant_name: str
+    annotation: str
+
+    @property
+    def writable(self) -> bool:
+        return self.source.generated is None
+
+    @property
+    def required(self) -> bool:
+        return (
+            self.writable and not self.source.nullable and self.source.default is None
+        )
+
+    @property
+    def value_annotation(self) -> str:
+        if self.source.nullable:
+            return f"{self.annotation} | None"
+        return self.annotation
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedKey:
+    source: Key
+    type_name: str
+    constant_name: str
+    columns: tuple[GeneratedColumn, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedRelation:
+    source: TypedRelation
+    constant_name: str
+    target_row_name: str
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedTable:
+    source: Table
+    schema_name: str | None
+    catalog_name: str | None
+    class_name: str
+    constant_name: str
+    row_name: str
+    insert_name: str
+    update_name: str
+    builder_name: str
+    complete_builder_name: str
+    update_builder_name: str
+    columns: tuple[GeneratedColumn, ...]
+    keys: tuple[GeneratedKey, ...]
+    relations: tuple[GeneratedRelation, ...]
+
+    @property
+    def writable_columns(self) -> tuple[GeneratedColumn, ...]:
+        return tuple(column for column in self.columns if column.writable)
+
+    @property
+    def required_columns(self) -> tuple[GeneratedColumn, ...]:
+        return tuple(column for column in self.columns if column.required)
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedEnum:
+    source: EnumType
+    schema_name: str | None
+    catalog_name: str | None
+    class_name: str
+    members: tuple[tuple[str, str], ...]
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedDomain:
+    """A domain as a type of its own, distinct from the type it is written over.
+
+    Two domains over one base are two types, so each becomes a name a checker
+    can tell apart. The value is still the base value, so nothing is converted
+    on the way in or out.
+    """
+
+    source: Domain
+    schema_name: str | None
+    catalog_name: str | None
+    type_name: str
+    base_annotation: str
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedRoutineParameter:
+    source: RoutineParameter
+    field_name: str
+    annotation: str
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedRoutine:
+    """A routine as a call a caller can make, with the database's own signature.
+
+    The parameters and the result come from the catalog rather than from a
+    caller's assertion, so arity, order, and types are the database's facts.
+    """
+
+    source: Routine
+    schema_name: str | None
+    catalog_name: str | None
+    function_name: str
+    parameters: tuple[GeneratedRoutineParameter, ...]
+    returns_annotation: str | None
+    dialect: DatabaseDialect
+
+    @property
+    def given_parameters(self) -> tuple[GeneratedRoutineParameter, ...]:
+        """Values a caller supplies, excluding values the routine only writes."""
+        return tuple(
+            parameter
+            for parameter in self.parameters
+            if parameter.source.mode is not ParameterMode.OUT
+        )
+
+    @property
+    def sql_parameters(self) -> tuple[GeneratedRoutineParameter, ...]:
+        """Parameters represented in SQL for this dialect and routine kind."""
+        if self.source.kind is RoutineKind.FUNCTION:
+            return self.given_parameters
+        return self.parameters
+
+    @property
+    def unsupported_reason(self) -> str | None:
+        """Why the generated adapter cannot safely invoke this routine."""
+        has_outputs = any(
+            parameter.source.mode is not ParameterMode.IN
+            for parameter in self.parameters
+        )
+        if self.dialect is DatabaseDialect.MYSQL and has_outputs:
+            return "MySQL OUT and INOUT routines require an output adapter"
+        if self.source.kind is RoutineKind.PROCEDURE and _default_precedes_output(
+            self.parameters
+        ):
+            return "Procedure defaults followed by OUT parameters are not supported"
+        return None
+
+    @property
+    def outputs(self) -> tuple[GeneratedRoutineParameter, ...]:
+        """The parameters the procedure answers through rather than reads."""
+        return tuple(
+            parameter
+            for parameter in self.parameters
+            if parameter.source.mode is not ParameterMode.IN
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedOverload:
+    """Routines a database lets share one name, called under that name.
+
+    Python resolves an overload from what a call gives it, and the only thing
+    it can tell two calls apart by at runtime is how many values they carry.
+    A group is written only where every routine in it takes a different
+    number, so the call that arrives names exactly one of them.
+    """
+
+    function_name: str
+    routines: tuple[GeneratedRoutine, ...]
+
+
+def _default_precedes_output(
+    parameters: tuple[GeneratedRoutineParameter, ...],
+) -> bool:
+    default_seen = False
+    for parameter in parameters:
+        default_seen = default_seen or parameter.source.has_default
+        if default_seen and parameter.source.mode is ParameterMode.OUT:
+            return True
+    return False
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedPackage:
+    tables: tuple[GeneratedTable, ...]
+    enums: tuple[GeneratedEnum, ...]
+    domains: tuple[GeneratedDomain, ...] = ()
+    routines: tuple[GeneratedRoutine, ...] = ()
+    overloads: tuple[GeneratedOverload, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class _TableSource:
+    key: str
+    catalog: Catalog
+    schema: Schema
+    table: Table
+
+
+@dataclass(frozen=True, slots=True)
+class _RoutineSource:
+    key: str
+    catalog: Catalog
+    schema: Schema
+    routine: Routine
+    shared_name: bool = False
+    """Whether another routine of this schema is written under the same name."""
+
+    @property
+    def group(self) -> tuple[str | None, str | None, str]:
+        """What makes two routines overloads of each other rather than two names."""
+        return (
+            _identifier_value(self.catalog.name),
+            _identifier_value(self.schema.name),
+            self.routine.name.value,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _DomainSource:
+    key: str
+    catalog: Catalog
+    schema: Schema
+    domain: Domain
+
+
+@dataclass(frozen=True, slots=True)
+class _EnumSource:
+    key: str
+    catalog: Catalog
+    schema: Schema
+    enum: EnumType
+
+
+def build_codegen_package(
+    snapshot: SchemaSnapshot,
+    naming_policy: NamingPolicy | None = None,
+) -> GeneratedPackage:
+    tables = _table_sources(snapshot)
+    enums = _enum_sources(snapshot)
+    domains = _domain_sources(snapshot)
+    routines = _routine_sources(snapshot)
+    graph = build_relation_graph(snapshot)
+    scopes = _naming_scopes(tables, enums, domains, routines, graph)
+    names = (naming_policy or NamingPolicy()).resolve(scopes)
+    generated_enums = _generated_enums(enums, names)
+    enum_names = _enum_name_map(generated_enums)
+    generated_domains = _generated_domains(domains, names, enum_names)
+    domain_names = _domain_name_map(generated_domains)
+    generated_routines = _generated_routines(
+        routines, names, enum_names, domain_names, snapshot.dialect
+    )
+    table_row_names = {
+        (
+            _identifier_value(table.catalog.name),
+            _identifier_value(table.schema.name),
+            table.table.name.value,
+        ): f"{names.get('tables', table.key)}Row"
+        for table in tables
+    }
+    generated_tables = tuple(
+        _generated_table(table, names, enum_names, domain_names, table_row_names, graph)
+        for table in tables
+    )
+    return GeneratedPackage(
+        generated_tables,
+        generated_enums,
+        generated_domains,
+        generated_routines,
+        _generated_overloads(routines, generated_routines, names),
+    )
+
+
+def _table_sources(snapshot: SchemaSnapshot) -> tuple[_TableSource, ...]:
+    sources: list[_TableSource] = []
+    for catalog_index, catalog in enumerate(snapshot.catalogs):
+        for schema_index, schema in enumerate(catalog.schemas):
+            for table_index, table in enumerate(schema.tables):
+                key = _qualified_key(
+                    catalog.name,
+                    schema.name,
+                    table.name,
+                    (catalog_index, schema_index, table_index),
+                )
+                sources.append(_TableSource(key, catalog, schema, table))
+    return tuple(sorted(sources, key=lambda source: source.key))
+
+
+def _enum_sources(snapshot: SchemaSnapshot) -> tuple[_EnumSource, ...]:
+    sources: list[_EnumSource] = []
+    for catalog_index, catalog in enumerate(snapshot.catalogs):
+        for schema_index, schema in enumerate(catalog.schemas):
+            for enum_index, enum in enumerate(schema.enums):
+                key = _qualified_key(
+                    catalog.name,
+                    schema.name,
+                    enum.name,
+                    (catalog_index, schema_index, enum_index),
+                )
+                sources.append(_EnumSource(key, catalog, schema, enum))
+    return tuple(sorted(sources, key=lambda source: source.key))
+
+
+def _qualified_key(
+    catalog: Identifier | None,
+    schema: Identifier | None,
+    name: Identifier,
+    indexes: tuple[int, int, int],
+) -> str:
+    qualified = tuple(
+        identifier.value if identifier is not None else ""
+        for identifier in (catalog, schema, name)
+    )
+    return "/".join((*qualified, *(str(index) for index in indexes)))
+
+
+def _naming_scopes(
+    tables: tuple[_TableSource, ...],
+    enums: tuple[_EnumSource, ...],
+    domains: tuple[_DomainSource, ...],
+    routines: tuple[_RoutineSource, ...],
+    graph: RelationGraph,
+) -> tuple[NamingScope, ...]:
+    scopes: list[NamingScope] = [
+        NamingScope(
+            "tables",
+            PythonNameStyle.PASCAL_CASE,
+            tuple(NameRequest(table.key, table.table.name) for table in tables),
+        ),
+        NamingScope(
+            "table-constants",
+            PythonNameStyle.UPPER_SNAKE_CASE,
+            tuple(NameRequest(table.key, table.table.name) for table in tables),
+        ),
+        NamingScope(
+            "enums",
+            PythonNameStyle.PASCAL_CASE,
+            tuple(NameRequest(enum.key, enum.enum.name) for enum in enums),
+        ),
+        NamingScope(
+            "domains",
+            PythonNameStyle.PASCAL_CASE,
+            tuple(NameRequest(domain.key, domain.domain.name) for domain in domains),
+        ),
+        NamingScope(
+            "routines",
+            PythonNameStyle.SNAKE_CASE,
+            _routine_name_requests(routines),
+        ),
+        *(
+            NamingScope(
+                f"routine-parameters:{routine.key}",
+                PythonNameStyle.SNAKE_CASE,
+                tuple(
+                    NameRequest(str(index), parameter.name or Identifier(f"a{index}"))
+                    for index, parameter in enumerate(routine.routine.parameters)
+                ),
+            )
+            for routine in routines
+        ),
+    ]
+    for table in tables:
+        scopes.extend(_table_scopes(table, _table_relations(table, graph)))
+    for enum in enums:
+        scopes.append(
+            NamingScope(
+                f"enum-members:{enum.key}",
+                PythonNameStyle.UPPER_SNAKE_CASE,
+                tuple(
+                    NameRequest(str(index), Identifier(value))
+                    for index, value in enumerate(enum.enum.values)
+                ),
+            )
+        )
+    return tuple(scopes)
+
+
+def _table_relations(
+    table: _TableSource,
+    graph: RelationGraph,
+) -> tuple[TypedRelation, ...]:
+    """Both directions of every key that touches this table."""
+    return graph.relations_from(
+        ObjectReference(table.table.name, table.schema.name, table.catalog.name)
+    )
+
+
+def _table_scopes(
+    table: _TableSource,
+    relations: tuple[TypedRelation, ...],
+) -> tuple[NamingScope, ...]:
+    column_requests = tuple(
+        NameRequest(str(index), column.name)
+        for index, column in enumerate(table.table.columns)
+    )
+    key_requests = tuple(
+        NameRequest(str(index), _key_type_identifier(key))
+        for index, key in enumerate(table.table.keys)
+    )
+    key_constant_requests = tuple(
+        NameRequest(str(index), _key_constant_identifier(key, index))
+        for index, key in enumerate(table.table.keys)
+    )
+    relation_requests = tuple(
+        NameRequest(str(index), _relation_identifier(relation))
+        for index, relation in enumerate(relations)
+    )
+    return (
+        NamingScope(
+            f"fields:{table.key}",
+            PythonNameStyle.SNAKE_CASE,
+            column_requests,
+            _FIELD_RESERVED_NAMES,
+        ),
+        NamingScope(
+            f"columns:{table.key}",
+            PythonNameStyle.UPPER_SNAKE_CASE,
+            column_requests,
+        ),
+        NamingScope(
+            f"key-types:{table.key}",
+            PythonNameStyle.PASCAL_CASE,
+            key_requests,
+        ),
+        NamingScope(
+            f"key-constants:{table.key}",
+            PythonNameStyle.UPPER_SNAKE_CASE,
+            key_constant_requests,
+        ),
+        NamingScope(
+            f"relations:{table.key}",
+            PythonNameStyle.UPPER_SNAKE_CASE,
+            relation_requests,
+        ),
+    )
+
+
+def _key_constant_identifier(key: Key, index: int) -> Identifier:
+    if key.name is not None:
+        return key.name
+    columns = "_".join(column.value for column in key.columns)
+    prefix = "primary" if key.kind is KeyKind.PRIMARY else "unique"
+    return Identifier(f"{prefix}_{columns}_{index}")
+
+
+def _key_type_identifier(key: Key) -> Identifier:
+    if key.kind is KeyKind.PRIMARY:
+        return Identifier("primary_key")
+    columns = "_".join(column.value for column in key.columns)
+    return Identifier(f"{columns}_unique_key")
+
+
+def _relation_identifier(relation: TypedRelation) -> Identifier:
+    """Name a relation after the key it follows, and say which way.
+
+    Both directions of one key land on one table when the key points at that
+    table itself, so the direction is always part of the name rather than only
+    when it happens to be needed.
+    """
+    base = _relation_base_identifier(relation)
+    if relation.direction is RelationDirection.FORWARD:
+        return base
+    return Identifier(f"{base.value}_reverse")
+
+
+def _relation_base_identifier(relation: TypedRelation) -> Identifier:
+    """Name the key by the table across it and the columns that carry it.
+
+    Nothing here depends on where the relation sits in a list, so adding a key
+    to some other table cannot rename the ones already generated.
+    """
+    if relation.constraint is not None:
+        return relation.constraint
+    columns = "_".join(column.value for column in _referencing_columns(relation))
+    return Identifier(f"{relation.target.table.name.value}_{columns}")
+
+
+def _referencing_columns(relation: TypedRelation) -> tuple[Identifier, ...]:
+    """The columns that carry the key, which always sit on the child side."""
+    if relation.direction is RelationDirection.FORWARD:
+        return relation.source.columns
+    return relation.target.columns
+
+
+def _generated_enums(
+    sources: tuple[_EnumSource, ...],
+    names: NamingResult,
+) -> tuple[GeneratedEnum, ...]:
+    return tuple(
+        GeneratedEnum(
+            source=source.enum,
+            schema_name=_identifier_value(source.schema.name),
+            catalog_name=_identifier_value(source.catalog.name),
+            class_name=names.get("enums", source.key),
+            members=tuple(
+                (
+                    names.get(f"enum-members:{source.key}", str(index)),
+                    value,
+                )
+                for index, value in enumerate(source.enum.values)
+            ),
+        )
+        for source in sources
+    )
+
+
+def _domain_sources(snapshot: SchemaSnapshot) -> tuple[_DomainSource, ...]:
+    sources: list[_DomainSource] = []
+    for catalog_index, catalog in enumerate(snapshot.catalogs):
+        for schema_index, schema in enumerate(catalog.schemas):
+            for domain_index, domain in enumerate(schema.domains):
+                key = _qualified_key(
+                    catalog.name,
+                    schema.name,
+                    domain.name,
+                    (catalog_index, schema_index, domain_index),
+                )
+                sources.append(_DomainSource(key, catalog, schema, domain))
+    return tuple(sorted(sources, key=lambda source: source.key))
+
+
+def _generated_domains(
+    sources: tuple[_DomainSource, ...],
+    names: NamingResult,
+    enum_names: dict[tuple[str | None, str | None, str], str],
+) -> tuple[GeneratedDomain, ...]:
+    return tuple(
+        GeneratedDomain(
+            source=source.domain,
+            schema_name=_identifier_value(source.schema.name),
+            catalog_name=_identifier_value(source.catalog.name),
+            type_name=names.get("domains", source.key),
+            base_annotation=_python_annotation(
+                source.domain.data_type,
+                enum_names,
+                default_catalog=_identifier_value(source.catalog.name),
+                default_schema=_identifier_value(source.schema.name),
+            ),
+        )
+        for source in sources
+    )
+
+
+def _routine_sources(snapshot: SchemaSnapshot) -> tuple[_RoutineSource, ...]:
+    placed: list[tuple[tuple[int, int, int], Catalog, Schema, Routine]] = [
+        ((catalog_index, schema_index, routine_index), catalog, schema, routine)
+        for catalog_index, catalog in enumerate(snapshot.catalogs)
+        for schema_index, schema in enumerate(catalog.schemas)
+        for routine_index, routine in enumerate(schema.routines)
+    ]
+    shared = _shared_routine_names(placed)
+    sources: list[_RoutineSource] = []
+    for position, catalog, schema, routine in placed:
+        group = (
+            _identifier_value(catalog.name),
+            _identifier_value(schema.name),
+            routine.name.value,
+        )
+        is_shared = group in shared
+        sources.append(
+            _RoutineSource(
+                _qualified_key(
+                    catalog.name,
+                    schema.name,
+                    _overloaded(routine, is_shared),
+                    position,
+                ),
+                catalog,
+                schema,
+                routine,
+                is_shared,
+            )
+        )
+    return tuple(sorted(sources, key=lambda source: source.key))
+
+
+def _routine_name_requests(
+    routines: tuple[_RoutineSource, ...],
+) -> tuple[NameRequest, ...]:
+    """Every routine, and the shared names the calls between them are written under.
+
+    They are asked for together so that no shared name can collide with a
+    routine that happens to be spelled the same way.
+    """
+    requests = [
+        NameRequest(routine.key, _overloaded(routine.routine, routine.shared_name))
+        for routine in routines
+    ]
+    shared = {
+        routine.group: routine.routine.name
+        for routine in routines
+        if routine.shared_name
+    }
+    requests.extend(
+        NameRequest(_overload_key(group), name) for group, name in shared.items()
+    )
+    return tuple(requests)
+
+
+def _generated_overloads(
+    sources: tuple[_RoutineSource, ...],
+    generated: tuple[GeneratedRoutine, ...],
+    names: NamingResult,
+) -> tuple[GeneratedOverload, ...]:
+    """One call per shared name, where the calls can be told apart.
+
+    Two routines of the same name and the same number of parameters differ
+    only by the types of them, and nothing a Python call carries at runtime
+    separates those reliably, so no call is written for that name and each
+    routine keeps the name of its own.
+    """
+    grouped: dict[tuple[str | None, str | None, str], list[GeneratedRoutine]] = {}
+    for source, routine in zip(sources, generated, strict=True):
+        if source.shared_name:
+            grouped.setdefault(source.group, []).append(routine)
+    overloads: list[GeneratedOverload] = []
+    for group, members in grouped.items():
+        ordered = sorted(members, key=lambda item: len(item.given_parameters))
+        if not _tellable_apart(ordered):
+            continue
+        overloads.append(
+            GeneratedOverload(
+                names.get("routines", _overload_key(group)), tuple(ordered)
+            )
+        )
+    return tuple(sorted(overloads, key=lambda item: item.function_name))
+
+
+def _tellable_apart(ordered: list[GeneratedRoutine]) -> bool:
+    """Whether one call written under the shared name can reach each of them.
+
+    Each routine must take a different number of values, so the call names
+    one, and the routines must agree on the type of every position they
+    share, so the one signature that carries them out states each once.
+    """
+    arities = [len(routine.given_parameters) for routine in ordered]
+    if len(set(arities)) != len(arities):
+        return False
+    widest = ordered[-1].given_parameters
+    return all(
+        parameter.annotation == widest[position].annotation
+        for routine in ordered
+        for position, parameter in enumerate(routine.given_parameters)
+    )
+
+
+def _overload_key(group: tuple[str | None, str | None, str]) -> str:
+    """The naming key the shared name itself is written under."""
+    catalog, schema, name = group
+    return f"overload:{catalog}.{schema}.{name}"
+
+
+def _shared_routine_names(
+    placed: list[tuple[tuple[int, int, int], Catalog, Schema, Routine]],
+) -> frozenset[tuple[str | None, str | None, str]]:
+    """Names more than one routine of a schema is written under."""
+    seen: dict[tuple[str | None, str | None, str], int] = {}
+    for _, catalog, schema, routine in placed:
+        group = (
+            _identifier_value(catalog.name),
+            _identifier_value(schema.name),
+            routine.name.value,
+        )
+        seen[group] = seen.get(group, 0) + 1
+    return frozenset(group for group, count in seen.items() if count > 1)
+
+
+def _overloaded(routine: Routine, shared: bool) -> Identifier:
+    """A name that separates two routines the database lets share one.
+
+    A shared name is never taken by one of the routines that share it, so the
+    call that chooses between them can be written under the name itself.
+    """
+    if routine.overload is not None:
+        return Identifier(f"{routine.name.value} {routine.overload}")
+    if shared:
+        return Identifier(f"{routine.name.value} 1")
+    return routine.name
+
+
+def _generated_routines(
+    sources: tuple[_RoutineSource, ...],
+    names: NamingResult,
+    enum_names: dict[tuple[str | None, str | None, str], str],
+    domain_names: dict[tuple[str | None, str | None, str], str],
+    dialect: DatabaseDialect,
+) -> tuple[GeneratedRoutine, ...]:
+    return tuple(
+        GeneratedRoutine(
+            source=source.routine,
+            schema_name=_identifier_value(source.schema.name),
+            catalog_name=_identifier_value(source.catalog.name),
+            function_name=names.get("routines", source.key),
+            parameters=tuple(
+                _generated_parameter(
+                    source, parameter, index, names, enum_names, domain_names
+                )
+                for index, parameter in enumerate(source.routine.parameters)
+            ),
+            returns_annotation=(
+                None
+                if source.routine.returns is None
+                else _routine_annotation(
+                    source, source.routine.returns, enum_names, domain_names
+                )
+            ),
+            dialect=dialect,
+        )
+        for source in sources
+    )
+
+
+def _generated_parameter(
+    source: _RoutineSource,
+    parameter: RoutineParameter,
+    index: int,
+    names: NamingResult,
+    enum_names: dict[tuple[str | None, str | None, str], str],
+    domain_names: dict[tuple[str | None, str | None, str], str],
+) -> GeneratedRoutineParameter:
+    written = _routine_annotation(source, parameter.data_type, enum_names, domain_names)
+    return GeneratedRoutineParameter(
+        source=parameter,
+        field_name=names.get(f"routine-parameters:{source.key}", str(index)),
+        annotation=f"{written} | None" if parameter.nullable else written,
+    )
+
+
+def _routine_annotation(
+    source: _RoutineSource,
+    data_type: SqlType,
+    enum_names: dict[tuple[str | None, str | None, str], str],
+    domain_names: dict[tuple[str | None, str | None, str], str],
+) -> str:
+    return _python_annotation(
+        data_type,
+        enum_names,
+        default_catalog=_identifier_value(source.catalog.name),
+        default_schema=_identifier_value(source.schema.name),
+        domain_names=domain_names,
+    )
+
+
+def _domain_name_map(
+    domains: tuple[GeneratedDomain, ...],
+) -> dict[tuple[str | None, str | None, str], str]:
+    return {
+        (
+            domain.catalog_name,
+            domain.schema_name,
+            domain.source.name.value,
+        ): domain.type_name
+        for domain in domains
+    }
+
+
+def _enum_name_map(
+    enums: tuple[GeneratedEnum, ...],
+) -> dict[tuple[str | None, str | None, str], str]:
+    return {
+        (enum.catalog_name, enum.schema_name, enum.source.name.value): enum.class_name
+        for enum in enums
+    }
+
+
+def _generated_table(
+    source: _TableSource,
+    names: NamingResult,
+    enum_names: dict[tuple[str | None, str | None, str], str],
+    domain_names: dict[tuple[str | None, str | None, str], str],
+    table_row_names: dict[tuple[str | None, str | None, str], str],
+    graph: RelationGraph,
+) -> GeneratedTable:
+    class_name = names.get("tables", source.key)
+    columns = tuple(
+        _generated_column(source, column, index, names, enum_names, domain_names)
+        for index, column in enumerate(source.table.columns)
+    )
+    column_map = {column.source.name: column for column in columns}
+    keys = tuple(
+        _generated_key(source, key, index, names, column_map, class_name)
+        for index, key in enumerate(source.table.keys)
+    )
+    relations = tuple(
+        GeneratedRelation(
+            relation,
+            (
+                f"{names.get('table-constants', source.key)}_"
+                f"{names.get(f'relations:{source.key}', str(index))}"
+            ),
+            _target_row_name(relation.target.table, table_row_names, source),
+        )
+        for index, relation in enumerate(_table_relations(source, graph))
+    )
+    return GeneratedTable(
+        source=source.table,
+        schema_name=_identifier_value(source.schema.name),
+        catalog_name=_identifier_value(source.catalog.name),
+        class_name=class_name,
+        constant_name=names.get("table-constants", source.key),
+        row_name=f"{class_name}Row",
+        insert_name=f"{class_name}Insert",
+        update_name=f"{class_name}Update",
+        builder_name=f"{class_name}Builder",
+        complete_builder_name=f"_{class_name}CompleteBuilder",
+        update_builder_name=f"{class_name}UpdateBuilder",
+        columns=columns,
+        keys=keys,
+        relations=relations,
+    )
+
+
+def _generated_column(
+    table: _TableSource,
+    column: Column,
+    index: int,
+    names: NamingResult,
+    enum_names: dict[tuple[str | None, str | None, str], str],
+    domain_names: dict[tuple[str | None, str | None, str], str],
+) -> GeneratedColumn:
+    return GeneratedColumn(
+        source=column,
+        field_name=names.get(f"fields:{table.key}", str(index)),
+        constant_name=names.get(f"columns:{table.key}", str(index)),
+        annotation=_python_annotation(
+            column.data_type,
+            enum_names,
+            default_catalog=_identifier_value(table.catalog.name),
+            default_schema=_identifier_value(table.schema.name),
+            domain_names=domain_names,
+        ),
+    )
+
+
+def _generated_key(
+    table: _TableSource,
+    key: Key,
+    index: int,
+    names: NamingResult,
+    columns: dict[Identifier, GeneratedColumn],
+    table_name: str,
+) -> GeneratedKey:
+    suffix = names.get(f"key-types:{table.key}", str(index))
+    return GeneratedKey(
+        source=key,
+        type_name=f"{table_name}{suffix}",
+        constant_name=names.get(f"key-constants:{table.key}", str(index)),
+        columns=tuple(columns[column] for column in key.columns),
+    )
+
+
+def _python_annotation(
+    sql_type: SqlType,
+    enum_names: dict[tuple[str | None, str | None, str], str],
+    *,
+    default_catalog: str | None,
+    default_schema: str | None,
+    domain_names: dict[tuple[str | None, str | None, str], str] | None = None,
+) -> str:
+    scalar_annotations = {
+        TypeKind.BOOLEAN: "bool",
+        TypeKind.SMALL_INTEGER: "int",
+        TypeKind.INTEGER: "int",
+        TypeKind.BIG_INTEGER: "int",
+        TypeKind.DECIMAL: "Decimal",
+        TypeKind.REAL: "float",
+        TypeKind.DOUBLE: "float",
+        TypeKind.STRING: "str",
+        TypeKind.BINARY: "bytes",
+        TypeKind.DATE: "date",
+        TypeKind.TIME: "time",
+        TypeKind.DATETIME: "datetime",
+        TypeKind.INTERVAL: "timedelta",
+        TypeKind.UUID: "UUID",
+        TypeKind.JSON: "JsonValue",
+        TypeKind.OTHER: "object",
+    }
+    if sql_type.kind is TypeKind.DOMAIN and sql_type.element_type is not None:
+        named = _named_reference(
+            sql_type.named_type,
+            domain_names,
+            default_catalog=default_catalog,
+            default_schema=default_schema,
+        )
+        if named is not None:
+            return named
+        return _python_annotation(
+            sql_type.element_type,
+            enum_names,
+            default_catalog=default_catalog,
+            default_schema=default_schema,
+        )
+    if sql_type.kind is TypeKind.ARRAY and sql_type.element_type is not None:
+        element = _python_annotation(
+            sql_type.element_type,
+            enum_names,
+            default_catalog=default_catalog,
+            default_schema=default_schema,
+        )
+        return f"tuple[{element}, ...]"
+    if sql_type.kind is TypeKind.ENUM and sql_type.named_type is not None:
+        named = _named_reference(
+            sql_type.named_type,
+            enum_names,
+            default_catalog=default_catalog,
+            default_schema=default_schema,
+        )
+        return named if named is not None else "str"
+    return scalar_annotations[sql_type.kind]
+
+
+def _named_reference(
+    reference: ObjectReference | None,
+    names: dict[tuple[str | None, str | None, str], str] | None,
+    *,
+    default_catalog: str | None,
+    default_schema: str | None,
+) -> str | None:
+    """What a generated artifact of this named type is called, if one exists."""
+    if reference is None or not names:
+        return None
+    key = (
+        _identifier_value(reference.catalog) or default_catalog,
+        _identifier_value(reference.schema) or default_schema,
+        reference.name.value,
+    )
+    return names.get(key)
+
+
+def _target_row_name(
+    reference: ObjectReference,
+    table_row_names: dict[tuple[str | None, str | None, str], str],
+    source: _TableSource,
+) -> str:
+    catalog_name = reference.catalog or source.catalog.name
+    schema_name = reference.schema or source.schema.name
+    prefix = (
+        _identifier_value(catalog_name),
+        _identifier_value(schema_name),
+        reference.name.value,
+    )
+    return table_row_names.get(prefix, "object")
+
+
+def _identifier_value(identifier: Identifier | None) -> str | None:
+    return identifier.value if identifier is not None else None
+
+
+__all__ = (
+    "GeneratedColumn",
+    "GeneratedEnum",
+    "GeneratedKey",
+    "GeneratedPackage",
+    "GeneratedRelation",
+    "GeneratedTable",
+    "build_codegen_package",
+)