pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/write_nodes.py

@@ -0,0 +1,174 @@
+"""Immutable structural nodes for write statements."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TypeAlias
+
+from pyoq.query.nodes import ExpressionNode
+from pyoq.query.select_nodes import ProjectionNode
+
+
+@dataclass(frozen=True, slots=True)
+class WriteTargetNode:
+    name: str
+    schema: str | None = None
+    catalog: str | None = None
+    columns: tuple[str, ...] = ()
+    """Every column the table declares, where the table declares them.
+
+    Names rather than descriptors, because a node is data. It is what lets a
+    write return the whole row without the caller listing it.
+    """
+
+    def __post_init__(self) -> None:
+        _require_identifier(self.name, "table")
+        _require_optional_identifier(self.schema, "schema")
+        _require_optional_identifier(self.catalog, "catalog")
+        for column in self.columns:
+            _require_identifier(column, "column")
+
+
+@dataclass(frozen=True, slots=True)
+class AssignmentNode:
+    column: str
+    value: ExpressionNode
+
+    def __post_init__(self) -> None:
+        _require_identifier(self.column, "column")
+
+
+class ConflictAction(StrEnum):
+    NOTHING = "nothing"
+    UPDATE = "update"
+
+
+@dataclass(frozen=True, slots=True)
+class ConflictNode:
+    action: ConflictAction
+    targets: tuple[str, ...] = ()
+    assignments: tuple[AssignmentNode, ...] = ()
+    condition: ExpressionNode | None = None
+
+    def __post_init__(self) -> None:
+        for target in self.targets:
+            _require_identifier(target, "conflict target")
+        if len(set(self.targets)) != len(self.targets):
+            message = "conflict targets must be unique"
+            raise ValueError(message)
+        _require_unique_columns(self.assignments)
+        if self.action is ConflictAction.NOTHING:
+            _require_no_conflict_update(self.assignments, self.condition)
+
+
+@dataclass(frozen=True, slots=True)
+class InsertNode:
+    target: WriteTargetNode
+    columns: tuple[str, ...]
+    rows: tuple[tuple[ExpressionNode, ...], ...] = ()
+    returning: tuple[ProjectionNode, ...] = ()
+    conflict: ConflictNode | None = None
+
+    def __post_init__(self) -> None:
+        _require_insert_columns(self.columns)
+        if any(len(row) != len(self.columns) for row in self.rows):
+            message = "INSERT row values must match the selected column count"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class UpdateNode:
+    target: WriteTargetNode
+    assignments: tuple[AssignmentNode, ...] = ()
+    condition: ExpressionNode | None = None
+    returning: tuple[ProjectionNode, ...] = ()
+    unconditional: bool = False
+
+    def __post_init__(self) -> None:
+        _require_unique_columns(self.assignments)
+
+
+@dataclass(frozen=True, slots=True)
+class DeleteNode:
+    target: WriteTargetNode
+    condition: ExpressionNode | None = None
+    returning: tuple[ProjectionNode, ...] = ()
+    unconditional: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class CallNode:
+    """A stored procedure asked to run.
+
+    A procedure is invoked rather than selected from, and it may answer with
+    rows or with nothing at all. The name is written into the SQL rather than
+    bound, because no database takes a routine name as a parameter, so it is
+    held to being a name.
+    """
+
+    name: str
+    schema: str | None = None
+    catalog: str | None = None
+    """Where the procedure is kept, held apart so each part is quoted as itself."""
+
+    arguments: tuple[ExpressionNode, ...] = ()
+    returning: tuple[ProjectionNode, ...] = ()
+    """What its rows hold, which a schema does not describe.
+
+    The same shape a write's returning clause carries, so one rule reads a
+    row back whichever statement produced it.
+    """
+
+
+WriteNode: TypeAlias = InsertNode | UpdateNode | DeleteNode
+
+
+def _require_no_conflict_update(
+    assignments: tuple[AssignmentNode, ...],
+    condition: ExpressionNode | None,
+) -> None:
+    if assignments or condition is not None:
+        message = "conflict resolution that does nothing cannot assign or filter"
+        raise ValueError(message)
+
+
+def _require_unique_columns(assignments: tuple[AssignmentNode, ...]) -> None:
+    columns = tuple(assignment.column for assignment in assignments)
+    if len(set(columns)) != len(columns):
+        message = "UPDATE assigns the same column more than once"
+        raise ValueError(message)
+
+
+def _require_insert_columns(columns: tuple[str, ...]) -> None:
+    if not columns:
+        message = "INSERT requires at least one column"
+        raise ValueError(message)
+    for column in columns:
+        _require_identifier(column, "column")
+    if len(set(columns)) != len(columns):
+        message = "INSERT columns must be unique"
+        raise ValueError(message)
+
+
+def _require_identifier(value: str, label: str) -> None:
+    if not value or "\x00" in value:
+        message = f"{label} identifier cannot be empty or contain a null character"
+        raise ValueError(message)
+
+
+def _require_optional_identifier(value: str | None, label: str) -> None:
+    if value is not None:
+        _require_identifier(value, label)
+
+
+__all__ = (
+    "AssignmentNode",
+    "ConflictAction",
+    "ConflictNode",
+    "DeleteNode",
+    "InsertNode",
+    "UpdateNode",
+    "WriteNode",
+    "WriteTargetNode",
+)