pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/rendering/identifiers.py

@@ -0,0 +1,40 @@
+"""Dialect identifier quoting and qualification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pyoq.errors import UnsupportedQueryError
+
+
+@dataclass(frozen=True, slots=True)
+class IdentifierQuoting:
+    dialect: str
+    delimiter: str = '"'
+    allow_catalog: bool = False
+
+    def quote(self, value: str) -> str:
+        escaped = value.replace(self.delimiter, self.delimiter * 2)
+        return f"{self.delimiter}{escaped}{self.delimiter}"
+
+    def qualified(
+        self,
+        name: str,
+        /,
+        *,
+        table: str | None = None,
+        schema: str | None = None,
+        catalog: str | None = None,
+    ) -> str:
+        if catalog is not None and not self.allow_catalog:
+            message = f"{self.dialect} does not support catalog-qualified identifiers"
+            raise UnsupportedQueryError(message)
+        parts = tuple(
+            self.quote(part)
+            for part in (catalog, schema, table, name)
+            if part is not None
+        )
+        return ".".join(parts)
+
+
+__all__ = ("IdentifierQuoting",)

pyoq/query/rendering/projections.py

@@ -0,0 +1,63 @@
+"""Shared projection rendering."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from pyoq.query.nodes import ExpressionNode, WindowSpecificationNode
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+from pyoq.query.rendering.sources import OrderTextRenderer, QueryTextRenderer
+from pyoq.query.select_nodes import JsonElementsSourceNode, ProjectionNode
+
+
+class ExpressionText(Protocol):
+    def compile(self, node: ExpressionNode) -> str: ...
+
+    def compile_window_specification(self, node: WindowSpecificationNode) -> str:
+        """How a window divides and orders the rows it covers."""
+        ...
+
+    def render_json_elements(self, node: JsonElementsSourceNode) -> str:
+        """A JSON array read as rows."""
+        ...
+
+    def routine_name(
+        self,
+        name: str,
+        schema: str | None = None,
+        catalog: str | None = None,
+    ) -> str:
+        """A routine's name as this dialect writes it."""
+        ...
+
+    def declares_windows(self, names: frozenset[str], /) -> frozenset[str]:
+        """The windows named by the query being written, and the ones before it."""
+        ...
+
+    def reads_queries_with(self, render_query: QueryTextRenderer, /) -> None:
+        """How to write a query that appears inside an expression."""
+
+    def orders_rows_with(self, render_order: OrderTextRenderer, /) -> None:
+        """How to write one term of an ORDER BY, direction and nulls included."""
+
+
+def compile_projection(
+    expressions: ExpressionText,
+    node: ProjectionNode,
+    quoting: IdentifierQuoting,
+) -> str:
+    rendered = expressions.compile(node.expression)
+    if node.alias is None:
+        return rendered
+    return f"{rendered} AS {quoting.quote(node.alias)}"
+
+
+def compile_projections(
+    expressions: ExpressionText,
+    nodes: tuple[ProjectionNode, ...],
+    quoting: IdentifierQuoting,
+) -> str:
+    return ", ".join(compile_projection(expressions, node, quoting) for node in nodes)
+
+
+__all__ = ("ExpressionText", "compile_projection", "compile_projections")

pyoq/query/rendering/queries.py

@@ -0,0 +1,334 @@
+"""Shared SELECT and compound query rendering with dialect hooks."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+
+from pyoq.errors import CompilationError, UnsupportedQueryError
+from pyoq.query.nodes import FieldNode, NamedWindowNode
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+from pyoq.query.rendering.projections import ExpressionText, compile_projection
+from pyoq.query.rendering.sources import SourceRenderer
+from pyoq.query.select_nodes import (
+    CommonTableNode,
+    JoinKind,
+    JoinNode,
+    LockNode,
+    LockStrength,
+    LockWait,
+    NullOrder,
+    OrderDirection,
+    OrderNode,
+    QueryNode,
+    SelectNode,
+    SetNode,
+    SetOperator,
+)
+
+_LOCK_STRENGTHS: Mapping[LockStrength, str] = {
+    LockStrength.UPDATE: "UPDATE",
+    LockStrength.NO_KEY_UPDATE: "NO KEY UPDATE",
+    LockStrength.SHARE: "SHARE",
+    LockStrength.KEY_SHARE: "KEY SHARE",
+}
+"""Verified against a running PostgreSQL server, which has all four."""
+
+_LOCK_WAITS: Mapping[LockWait, str] = {
+    LockWait.NOWAIT: "NOWAIT",
+    LockWait.SKIP_LOCKED: "SKIP LOCKED",
+}
+"""Waiting is what a lock does unless it is told otherwise, so it is unwritten."""
+
+_ORDER_DIRECTIONS = {
+    OrderDirection.ASCENDING: "ASC",
+    OrderDirection.DESCENDING: "DESC",
+}
+_NULL_ORDERS = {
+    NullOrder.FIRST: "FIRST",
+    NullOrder.LAST: "LAST",
+}
+_SET_OPERATORS = {
+    SetOperator.UNION: "UNION",
+    SetOperator.UNION_ALL: "UNION ALL",
+    SetOperator.INTERSECT: "INTERSECT",
+    SetOperator.EXCEPT: "EXCEPT",
+}
+_JOIN_NAMES = {
+    JoinKind.INNER: "INNER JOIN",
+    JoinKind.LEFT: "LEFT JOIN",
+    JoinKind.RIGHT: "RIGHT JOIN",
+    JoinKind.FULL: "FULL JOIN",
+}
+
+_NATURAL_NAMES = {
+    JoinKind.INNER: "NATURAL JOIN",
+    JoinKind.LEFT: "NATURAL LEFT JOIN",
+    JoinKind.RIGHT: "NATURAL RIGHT JOIN",
+    JoinKind.FULL: "NATURAL FULL JOIN",
+}
+"""A natural join is inner unless it says otherwise, and reads that way."""
+
+
+class QueryRenderer(ABC):
+    __slots__ = ("_expressions", "_sources")
+
+    def __init__(self, expressions: ExpressionText) -> None:
+        self._expressions = expressions
+        self._sources = SourceRenderer(
+            self.compile,
+            self.quoting,
+            self.require_lateral_sources,
+            expressions.render_json_elements,
+        )
+        expressions.reads_queries_with(self.compile)
+        expressions.orders_rows_with(self._compile_order)
+
+    @property
+    @abstractmethod
+    def dialect(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def quoting(self) -> IdentifierQuoting: ...
+
+    @abstractmethod
+    def require_join_capability(self, kind: JoinKind) -> None: ...
+
+    @abstractmethod
+    def require_recursive_common_tables(self) -> None: ...
+
+    @abstractmethod
+    def require_lateral_sources(self) -> None: ...
+
+    @abstractmethod
+    def append_pagination(
+        self,
+        fragments: list[str],
+        limit: int | None,
+        offset: int | None,
+    ) -> None: ...
+
+    def compile(self, node: QueryNode) -> str:
+        if isinstance(node, SelectNode):
+            return self._compile_select(node)
+        return self._compile_set(node)
+
+    def _compile_select(self, node: SelectNode) -> str:
+        previous = self._expressions.declares_windows(
+            frozenset(declared.name for declared in node.windows)
+        )
+        try:
+            return self._compile_select_clauses(node)
+        finally:
+            self._expressions.declares_windows(previous)
+
+    def _compile_select_clauses(self, node: SelectNode) -> str:
+        fragments: list[str] = []
+        if node.common_tables:
+            fragments.append(self._compile_common_tables(node.common_tables))
+        projections = (
+            "*"
+            if node.every_column
+            else ", ".join(
+                compile_projection(self._expressions, projection, self.quoting)
+                for projection in node.projections
+            )
+        )
+        distinct = " DISTINCT" if node.distinct else ""
+        fragments.append(f"SELECT{distinct} {projections}")
+        if node.source is not None:
+            fragments.append(f"FROM {self._sources.compile(node.source)}")
+        fragments.extend(self._compile_join(join) for join in node.joins)
+        where = self._compile_where(node)
+        if where is not None:
+            fragments.append(where)
+        if node.groups:
+            groups = ", ".join(
+                self._expressions.compile(group) for group in node.groups
+            )
+            fragments.append(f"GROUP BY {groups}")
+        if node.having is not None:
+            fragments.append(f"HAVING {self._expressions.compile(node.having)}")
+        if node.windows:
+            fragments.append(self._compile_windows(node.windows))
+        self._append_ordering(fragments, node.orders)
+        self.append_pagination(fragments, node.limit, node.offset)
+        if node.lock is not None:
+            fragments.append(self.locking(node.lock))
+        return " ".join(fragments)
+
+    def _compile_windows(self, nodes: tuple[NamedWindowNode, ...]) -> str:
+        """The windows this query names, written once for every reader."""
+        declarations = ", ".join(
+            f"{declared.name} AS "
+            f"({self._expressions.compile_window_specification(declared.specification)})"
+            for declared in nodes
+        )
+        return f"WINDOW {declarations}"
+
+    def _compile_set(self, node: SetNode) -> str:
+        left = self._compile_compound_operand(node.left)
+        right = self._compile_compound_operand(node.right)
+        operator = _SET_OPERATORS.get(node.operator)
+        if operator is None:
+            message = f"unsupported {self.dialect} set operator: {node.operator}"
+            raise UnsupportedQueryError(message)
+        fragments = [left, operator, right]
+        self._append_set_ordering(fragments, node.orders)
+        self.append_pagination(fragments, node.limit, node.offset)
+        return " ".join(fragments)
+
+    def _compile_compound_operand(self, node: QueryNode) -> str:
+        if isinstance(node, SelectNode) and _is_plain_compound_operand(node):
+            return self.compile(node)
+        nested = f"({self.compile(node)})"
+        return " ".join(("SELECT", "*", "FROM", nested))
+
+    def _compile_where(self, node: SelectNode) -> str | None:
+        """The condition and whatever the semi joins ask, joined by AND."""
+        parts = [
+            self._expressions.compile(expression)
+            for expression in (node.condition, *node.matches)
+            if expression is not None
+        ]
+        if not parts:
+            return None
+        return "WHERE " + " AND ".join(parts)
+
+    def _compile_join(self, node: JoinNode) -> str:
+        self.require_join_capability(node.kind)
+        source = self._sources.compile(node.source)
+        if node.kind is JoinKind.CROSS:
+            return f"CROSS JOIN {source}"
+        join_name = _JOIN_NAMES.get(node.kind)
+        if join_name is None:
+            message = f"unsupported {self.dialect} join kind: {node.kind}"
+            raise UnsupportedQueryError(message)
+        if node.natural:
+            return f"{_NATURAL_NAMES[node.kind]} {source}"
+        if node.using:
+            columns = ", ".join(self.quoting.quote(name) for name in node.using)
+            return f"{join_name} {source} USING ({columns})"
+        if node.condition is None:
+            message = f"qualified {self.dialect} join requires an ON condition"
+            raise CompilationError(message)
+        condition = self._expressions.compile(node.condition)
+        return f"{join_name} {source} ON {condition}"
+
+    def _compile_common_tables(
+        self,
+        common_tables: tuple[CommonTableNode, ...],
+    ) -> str:
+        recursive = any(common_table.recursive for common_table in common_tables)
+        if recursive:
+            self.require_recursive_common_tables()
+        keyword = "WITH RECURSIVE" if recursive else "WITH"
+        definitions = ", ".join(
+            self._compile_common_table(common_table) for common_table in common_tables
+        )
+        return f"{keyword} {definitions}"
+
+    def _compile_common_table(self, node: CommonTableNode) -> str:
+        columns = ""
+        if node.columns:
+            rendered = ", ".join(self.quoting.quote(column) for column in node.columns)
+            columns = f" ({rendered})"
+        name = self.quoting.quote(node.name)
+        return f"{name}{columns} AS ({self.compile(node.query)})"
+
+    def _append_ordering(
+        self,
+        fragments: list[str],
+        orders: tuple[OrderNode, ...],
+    ) -> None:
+        if not orders:
+            return
+        rendered = ", ".join(self._compile_order(order) for order in orders)
+        fragments.append(f"ORDER BY {rendered}")
+
+    def _append_set_ordering(
+        self,
+        fragments: list[str],
+        orders: tuple[OrderNode, ...],
+    ) -> None:
+        if not orders:
+            return
+        rendered = ", ".join(self._compile_set_order(order) for order in orders)
+        fragments.append(f"ORDER BY {rendered}")
+
+    def locking(self, node: LockNode) -> str:
+        """How this dialect holds the rows a statement reads.
+
+        A dialect that cannot hold rows at all says so, because returning
+        them unlocked would answer a question nobody asked.
+        """
+        strength = self.lock_strength_sql(node.strength)
+        clauses = [f"FOR {strength}"]
+        if node.tables:
+            names = ", ".join(self.quoting.quote(table) for table in node.tables)
+            clauses.append(f"OF {names}")
+        wait = _LOCK_WAITS.get(node.wait)
+        if wait is not None:
+            clauses.append(wait)
+        return " ".join(clauses)
+
+    def lock_strength_sql(self, strength: LockStrength) -> str:
+        """What this dialect calls a lock of this strength."""
+        name = _LOCK_STRENGTHS.get(strength)
+        if name is None:
+            message = f"unsupported {self.dialect} lock strength: {strength}"
+            raise UnsupportedQueryError(message)
+        return name
+
+    def _compile_order(self, node: OrderNode) -> str:
+        return self._ordered(self._expressions.compile(node.expression), node)
+
+    def _compile_set_order(self, node: OrderNode) -> str:
+        """A set operation orders by what it returned, not by where it came from.
+
+        Its operands may read different tables, so a table-qualified name means
+        nothing once they are combined and a database refuses it. Only a column
+        the operation selected can be named here.
+        """
+        if not isinstance(node.expression, FieldNode):
+            message = (
+                f"a {self.dialect} set operation can only be ordered by a "
+                f"column it selected"
+            )
+            raise UnsupportedQueryError(message)
+        return self._ordered(self.quoting.quote(node.expression.name), node)
+
+    def _ordered(self, expression: str, node: OrderNode) -> str:
+        direction = _ORDER_DIRECTIONS.get(node.direction)
+        if direction is None:
+            message = f"unsupported {self.dialect} order direction: {node.direction}"
+            raise UnsupportedQueryError(message)
+        if node.nulls is None:
+            return f"{expression} {direction}"
+        return self.null_ordered(expression, direction, node.nulls)
+
+    def null_ordered(
+        self,
+        expression: str,
+        direction: str,
+        nulls: NullOrder,
+    ) -> str:
+        """Where this dialect puts nulls when it is told where to put them."""
+        placement = _NULL_ORDERS.get(nulls)
+        if placement is None:
+            message = f"unsupported {self.dialect} null order: {nulls}"
+            raise UnsupportedQueryError(message)
+        return f"{expression} {direction} NULLS {placement}"
+
+
+def _is_plain_compound_operand(node: SelectNode) -> bool:
+    return not (
+        node.common_tables
+        or node.orders
+        or node.limit is not None
+        or node.offset is not None
+    )
+
+
+__all__ = ("QueryRenderer",)

pyoq/query/rendering/sources.py

@@ -0,0 +1,66 @@
+"""Shared query-source rendering."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+from pyoq.query.select_nodes import (
+    JsonElementsSourceNode,
+    OrderNode,
+    QueryNode,
+    SourceNode,
+    SubquerySourceNode,
+    TableSourceNode,
+)
+
+QueryTextRenderer = Callable[[QueryNode], str]
+OrderTextRenderer = Callable[[OrderNode], str]
+JsonElementsTextRenderer = Callable[[JsonElementsSourceNode], str]
+
+
+class SourceRenderer:
+    __slots__ = (
+        "_quoting",
+        "_render_elements",
+        "_render_query",
+        "_require_lateral",
+    )
+
+    def __init__(
+        self,
+        render_query: QueryTextRenderer,
+        quoting: IdentifierQuoting,
+        require_lateral: Callable[[], None],
+        render_elements: JsonElementsTextRenderer,
+    ) -> None:
+        self._render_query = render_query
+        self._quoting = quoting
+        self._require_lateral = require_lateral
+        self._render_elements = render_elements
+
+    def compile(self, node: SourceNode) -> str:
+        if isinstance(node, TableSourceNode):
+            return self._compile_table(node)
+        if isinstance(node, JsonElementsSourceNode):
+            return self._render_elements(node)
+        if isinstance(node, SubquerySourceNode):
+            query = self._render_query(node.query)
+            if node.lateral:
+                self._require_lateral()
+            lateral = "LATERAL " if node.lateral else ""
+            return f"{lateral}({query}) AS {self._quoting.quote(node.alias)}"
+        return self._quoting.quote(node.name)
+
+    def _compile_table(self, node: TableSourceNode) -> str:
+        table = self._quoting.qualified(
+            node.name,
+            schema=node.schema,
+            catalog=node.catalog,
+        )
+        if node.alias is None:
+            return table
+        return f"{table} AS {self._quoting.quote(node.alias)}"
+
+
+__all__ = ("JsonElementsTextRenderer", "QueryTextRenderer", "SourceRenderer")

pyoq/query/rendering/writes.py

@@ -0,0 +1,176 @@
+"""Shared write statement rendering with dialect hooks."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from pyoq.errors import CompilationError
+from pyoq.query.execution import StatementKind
+from pyoq.query.nodes import ExpressionNode
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+from pyoq.query.rendering.projections import ExpressionText, compile_projections
+from pyoq.query.select_nodes import ProjectionNode
+from pyoq.query.write_nodes import (
+    AssignmentNode,
+    CallNode,
+    ConflictAction,
+    ConflictNode,
+    DeleteNode,
+    InsertNode,
+    UpdateNode,
+    WriteNode,
+    WriteTargetNode,
+)
+
+
+class WriteRenderer(ABC):
+    __slots__ = ("_expressions",)
+
+    def __init__(self, expressions: ExpressionText) -> None:
+        self._expressions = expressions
+
+    @property
+    @abstractmethod
+    def quoting(self) -> IdentifierQuoting: ...
+
+    def qualified_target(self, node: WriteTargetNode) -> str:
+        return self.quoting.qualified(
+            node.name,
+            schema=node.schema,
+            catalog=node.catalog,
+        )
+
+    @abstractmethod
+    def require_returning(self) -> None: ...
+
+    @abstractmethod
+    def require_conflict_resolution(self) -> None: ...
+
+    def compile(self, node: WriteNode) -> tuple[str, StatementKind]:
+        if isinstance(node, InsertNode):
+            return self._compile_insert(node), StatementKind.INSERT
+        if isinstance(node, UpdateNode):
+            return self._compile_update(node), StatementKind.UPDATE
+        return self._compile_delete(node), StatementKind.DELETE
+
+    def compile_call(self, node: CallNode) -> str:
+        """How this dialect runs a stored procedure.
+
+        A dialect that keeps no procedures says so, because there is nothing
+        for it to run and nothing to fall back on.
+        """
+        arguments = ", ".join(
+            self._expressions.compile(argument) for argument in node.arguments
+        )
+        name = self._expressions.routine_name(node.name, node.schema, node.catalog)
+        return f"CALL {name}({arguments})"
+
+    def _compile_insert(self, node: InsertNode) -> str:
+        if not node.rows:
+            message = "INSERT requires at least one row of values"
+            raise CompilationError(message)
+        columns = ", ".join(self.quoting.quote(column) for column in node.columns)
+        fragments = [
+            "INSERT INTO",
+            self.qualified_target(node.target),
+            f"({columns})",
+            "VALUES",
+            ", ".join(self._compile_row(row) for row in node.rows),
+        ]
+        alias = self.insert_row_alias(node)
+        if alias is not None:
+            fragments.append(f"AS {self.quoting.quote(alias)}")
+        if node.conflict is not None:
+            fragments.append(self.render_conflict(node.conflict))
+        self._append_returning(fragments, node.returning)
+        return " ".join(fragments)
+
+    def _compile_update(self, node: UpdateNode) -> str:
+        if not node.assignments:
+            message = "UPDATE requires at least one assignment"
+            raise CompilationError(message)
+        assignments = ", ".join(
+            self._compile_assignment(assignment) for assignment in node.assignments
+        )
+        fragments = ["UPDATE", self.qualified_target(node.target), "SET", assignments]
+        self._append_scope(fragments, node.condition, node.unconditional, "UPDATE")
+        self._append_returning(fragments, node.returning)
+        return " ".join(fragments)
+
+    def _compile_delete(self, node: DeleteNode) -> str:
+        fragments = ["DELETE FROM", self.qualified_target(node.target)]
+        self._append_scope(fragments, node.condition, node.unconditional, "DELETE")
+        self._append_returning(fragments, node.returning)
+        return " ".join(fragments)
+
+    def insert_row_alias(self, node: InsertNode) -> str | None:
+        del node
+        return None
+
+    def compile_assignment(self, node: AssignmentNode) -> str:
+        return self._compile_assignment(node)
+
+    def render_conflict(self, node: ConflictNode) -> str:
+        self.require_conflict_resolution()
+        if node.action is ConflictAction.UPDATE and not node.targets:
+            message = "conflict resolution that updates requires a conflict target"
+            raise CompilationError(message)
+        fragments = ["ON CONFLICT"]
+        if node.targets:
+            targets = ", ".join(self.quoting.quote(target) for target in node.targets)
+            fragments.append(f"({targets})")
+        if node.action is ConflictAction.NOTHING:
+            fragments.append("DO NOTHING")
+            return " ".join(fragments)
+        if not node.assignments:
+            message = "conflict resolution that updates requires an assignment"
+            raise CompilationError(message)
+        assignments = ", ".join(
+            self._compile_assignment(assignment) for assignment in node.assignments
+        )
+        fragments.extend(("DO UPDATE SET", assignments))
+        if node.condition is not None:
+            fragments.append("WHERE")
+            fragments.append(self._expressions.compile(node.condition))
+        return " ".join(fragments)
+
+    def _compile_assignment(self, node: AssignmentNode) -> str:
+        value = self._expressions.compile(node.value)
+        return f"{self.quoting.quote(node.column)} = {value}"
+
+    def _compile_row(self, row: tuple[ExpressionNode, ...]) -> str:
+        rendered = ", ".join(self._expressions.compile(value) for value in row)
+        return f"({rendered})"
+
+    def _append_scope(
+        self,
+        fragments: list[str],
+        condition: ExpressionNode | None,
+        unconditional: bool,
+        clause: str,
+    ) -> None:
+        if condition is not None:
+            fragments.append("WHERE")
+            fragments.append(self._expressions.compile(condition))
+            return
+        if not unconditional:
+            message = (
+                f"{clause} without a WHERE condition must opt in through all_rows()"
+            )
+            raise CompilationError(message)
+
+    def _append_returning(
+        self,
+        fragments: list[str],
+        returning: tuple[ProjectionNode, ...],
+    ) -> None:
+        if not returning:
+            return
+        self.require_returning()
+        fragments.append("RETURNING")
+        fragments.append(
+            compile_projections(self._expressions, returning, self.quoting)
+        )
+
+
+__all__ = ("WriteRenderer",)