pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/recursion.py

@@ -0,0 +1,265 @@
+"""Declaring a recursive common table before it is defined.
+
+A recursive term reads the table it is part of, so that table has to exist
+before the query that defines it can be written. Declaring the name and the
+columns first is what gives the recursive term something typed to read, and
+what keeps the two halves agreeing on width and order.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar, overload
+
+from pyoq.errors import QueryValidationError
+from pyoq.query.nodes import ScalarFamily
+from pyoq.query.results import expression_family, family_for_type
+from pyoq.query.select_nodes import (
+    CommonTableNode,
+    CommonTableSourceNode,
+    ProjectionNode,
+    SetNode,
+    SetOperator,
+)
+from pyoq.query.sources import CommonTable, SourceBase, require_identifier
+
+if TYPE_CHECKING:
+    from pyoq.query.fields import Field
+    from pyoq.query.select import Query
+
+FieldValue = TypeVar("FieldValue")
+ColumnValue = TypeVar("ColumnValue", covariant=True)
+ResultRow = TypeVar("ResultRow")
+A = TypeVar("A")
+B = TypeVar("B")
+C = TypeVar("C")
+D = TypeVar("D")
+E = TypeVar("E")
+F = TypeVar("F")
+G = TypeVar("G")
+H = TypeVar("H")
+
+
+@dataclass(frozen=True, slots=True)
+class RecursiveColumn(Generic[ColumnValue]):
+    """One column a recursive common table declares, and what it holds."""
+
+    name: str
+    value_type: type[ColumnValue]
+
+
+class RecursiveTable(SourceBase, Generic[ResultRow]):
+    """A common table named and typed before either of its terms is written.
+
+    It is a source, so the recursive term reads it the way it reads any other
+    table, and the columns it answers with are the ones declared here.
+    """
+
+    __slots__ = ("_columns", "_name")
+    _name: str
+    _columns: tuple[RecursiveColumn[object], ...]
+
+    def __init__(self, name: str, columns: tuple[RecursiveColumn[object], ...]) -> None:
+        super().__init__(CommonTableSourceNode(name), name)
+        object.__setattr__(self, "_name", name)
+        object.__setattr__(self, "_columns", columns)
+
+    @property
+    def column_names(self) -> tuple[str, ...]:
+        return tuple(column.name for column in self._columns)
+
+    def field(
+        self,
+        column: RecursiveColumn[FieldValue],
+        /,
+    ) -> Field[FieldValue]:
+        """One column of this table, held to what the declaration said it holds.
+
+        The declaration owns the type, so reading a column as something else
+        is a disagreement the table can see and a database never would.
+        """
+        declared = {item.name: item.value_type for item in self._columns}
+        if column.name not in declared:
+            named = ", ".join(sorted(declared))
+            message = f"{self._name} declares {named}, not {column.name}"
+            raise QueryValidationError(message)
+        if declared[column.name] is not column.value_type:
+            message = (
+                f"{self._name}.{column.name} was declared to hold "
+                f"{declared[column.name].__name__}, read here as "
+                f"{column.value_type.__name__}"
+            )
+            raise QueryValidationError(message)
+        from pyoq.query.fields import field
+
+        return field(column.value_type, column.name, table_name=self._name)
+
+    def define(
+        self,
+        anchor: Query[ResultRow],
+        recursive: Query[ResultRow],
+        /,
+    ) -> CommonTable[ResultRow]:
+        """The rows it starts with, and the rows it reaches from those.
+
+        The two are combined with UNION ALL, which is what a recursive common
+        table is: a starting set and a rule for growing it.
+        """
+        _require_terms(anchor, self._columns, "anchor")
+        _require_terms(recursive, self._columns, "recursive")
+        combined = SetNode(anchor.node, SetOperator.UNION_ALL, recursive.node)
+        return CommonTable[ResultRow](
+            CommonTableNode(self._name, combined, self.column_names, recursive=True)
+        )
+
+
+def column(name: str, value_type: type[FieldValue], /) -> RecursiveColumn[FieldValue]:
+    """One column of a recursive common table, and what it holds."""
+    require_identifier(name, "common table column")
+    return RecursiveColumn(name, value_type)
+
+
+@overload
+def recursive_table(
+    name: str, column_a: RecursiveColumn[A], /
+) -> RecursiveTable[tuple[A]]: ...
+
+
+@overload
+def recursive_table(
+    name: str, column_a: RecursiveColumn[A], column_b: RecursiveColumn[B], /
+) -> RecursiveTable[tuple[A, B]]: ...
+
+
+@overload
+def recursive_table(
+    name: str,
+    column_a: RecursiveColumn[A],
+    column_b: RecursiveColumn[B],
+    column_c: RecursiveColumn[C],
+    /,
+) -> RecursiveTable[tuple[A, B, C]]: ...
+
+
+@overload
+def recursive_table(
+    name: str,
+    column_a: RecursiveColumn[A],
+    column_b: RecursiveColumn[B],
+    column_c: RecursiveColumn[C],
+    column_d: RecursiveColumn[D],
+    /,
+) -> RecursiveTable[tuple[A, B, C, D]]: ...
+
+
+@overload
+def recursive_table(
+    name: str,
+    column_a: RecursiveColumn[A],
+    column_b: RecursiveColumn[B],
+    column_c: RecursiveColumn[C],
+    column_d: RecursiveColumn[D],
+    column_e: RecursiveColumn[E],
+    /,
+) -> RecursiveTable[tuple[A, B, C, D, E]]: ...
+
+
+@overload
+def recursive_table(
+    name: str,
+    column_a: RecursiveColumn[A],
+    column_b: RecursiveColumn[B],
+    column_c: RecursiveColumn[C],
+    column_d: RecursiveColumn[D],
+    column_e: RecursiveColumn[E],
+    column_f: RecursiveColumn[F],
+    /,
+) -> RecursiveTable[tuple[A, B, C, D, E, F]]: ...
+
+
+@overload
+def recursive_table(
+    name: str,
+    column_a: RecursiveColumn[A],
+    column_b: RecursiveColumn[B],
+    column_c: RecursiveColumn[C],
+    column_d: RecursiveColumn[D],
+    column_e: RecursiveColumn[E],
+    column_f: RecursiveColumn[F],
+    column_g: RecursiveColumn[G],
+    /,
+) -> RecursiveTable[tuple[A, B, C, D, E, F, G]]: ...
+
+
+@overload
+def recursive_table(
+    name: str,
+    column_a: RecursiveColumn[A],
+    column_b: RecursiveColumn[B],
+    column_c: RecursiveColumn[C],
+    column_d: RecursiveColumn[D],
+    column_e: RecursiveColumn[E],
+    column_f: RecursiveColumn[F],
+    column_g: RecursiveColumn[G],
+    column_h: RecursiveColumn[H],
+    /,
+) -> RecursiveTable[tuple[A, B, C, D, E, F, G, H]]: ...
+
+
+def recursive_table(
+    name: str,
+    /,
+    *columns: RecursiveColumn[object],
+) -> object:
+    """Declare a recursive common table, so its own term can read it.
+
+    The columns are what the table answers with, and what the recursive term
+    reads from it. Each says what it holds, so both terms are held to the
+    types as well as to the width, and two terms that disagree are refused
+    here rather than reaching a database that would refuse them anyway.
+    """
+    if not columns:
+        message = "a recursive common table declares at least one column"
+        raise QueryValidationError(message)
+    require_identifier(name, "common table")
+    return RecursiveTable[tuple[object, ...]](name, columns)
+
+
+def _require_terms(
+    query: Query[ResultRow],
+    columns: tuple[RecursiveColumn[object], ...],
+    term: str,
+) -> None:
+    """Both terms answer with what the table said it holds, in that order."""
+    node = query.node
+    projections = getattr(node, "projections", ())
+    if len(projections) != len(columns):
+        message = (
+            f"the {term} term selects {len(projections)} columns where the "
+            f"common table declares {len(columns)}"
+        )
+        raise QueryValidationError(message)
+    for position, (projection, declared) in enumerate(
+        zip(projections, columns, strict=True)
+    ):
+        _require_kind(projection, declared, term, position)
+
+
+def _require_kind(
+    projection: ProjectionNode,
+    declared: RecursiveColumn[object],
+    term: str,
+    position: int,
+) -> None:
+    answered = expression_family(projection.expression)
+    wanted = family_for_type(declared.value_type)
+    if answered is wanted or ScalarFamily.NULL in {answered, wanted}:
+        return
+    message = (
+        f"the {term} term answers with {answered.value} at column "
+        f"{position + 1}, where {declared.name} holds {wanted.value}"
+    )
+    raise QueryValidationError(message)
+
+
+__all__ = ("RecursiveColumn", "RecursiveTable", "column", "recursive_table")

pyoq/query/rendering/__init__.py

@@ -0,0 +1 @@
+"""Shared SQL rendering for every dialect."""