pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/nodes.py

@@ -0,0 +1,750 @@
+"""Immutable query expression nodes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, Protocol, TypeAlias, Union, runtime_checkable
+
+if TYPE_CHECKING:
+    from pyoq.query.select_nodes import OrderNode, QueryNode
+
+
+_ROW_VALUE_WIDTH = 2
+
+
+@runtime_checkable
+class NodeProvider(Protocol):
+    """Anything that can stand in an expression tree.
+
+    It lives here because both the expression layer and the raw templates
+    above it need the same idea, and one of them cannot import the other.
+    """
+
+    @property
+    def node(self) -> ExpressionNode: ...
+
+
+class ScalarFamily(StrEnum):
+    BOOLEAN = "boolean"
+    NUMERIC = "numeric"
+    STRING = "string"
+    BINARY = "binary"
+    TEMPORAL = "temporal"
+    JSON = "json"
+    OTHER = "other"
+    NULL = "null"
+
+
+class UnaryOperator(StrEnum):
+    NOT = "not"
+    NEGATE = "negate"
+    IS_NULL = "is-null"
+    IS_NOT_NULL = "is-not-null"
+    IS_TRUE = "is-true"
+    IS_FALSE = "is-false"
+
+
+class BinaryOperator(StrEnum):
+    EQUAL = "equal"
+    NOT_EQUAL = "not-equal"
+    LESS_THAN = "less-than"
+    LESS_OR_EQUAL = "less-or-equal"
+    GREATER_THAN = "greater-than"
+    GREATER_OR_EQUAL = "greater-or-equal"
+    IS_DISTINCT_FROM = "is-distinct-from"
+    IS_NOT_DISTINCT_FROM = "is-not-distinct-from"
+    ADD = "add"
+    SUBTRACT = "subtract"
+    MULTIPLY = "multiply"
+    DIVIDE = "divide"
+    MODULO = "modulo"
+    CONCAT = "concat"
+    LIKE = "like"
+    NOT_LIKE = "not-like"
+
+
+class VariadicOperator(StrEnum):
+    AND = "and"
+    OR = "or"
+    IN = "in"
+    NOT_IN = "not-in"
+    BETWEEN = "between"
+    NOT_BETWEEN = "not-between"
+
+
+class FunctionName(StrEnum):
+    LOWER = "lower"
+    UPPER = "upper"
+    LENGTH = "length"
+    CONTAINS = "contains"
+    STARTS_WITH = "starts-with"
+    ENDS_WITH = "ends-with"
+    COALESCE = "coalesce"
+    NULLIF = "nullif"
+    GREATEST = "greatest"
+    LEAST = "least"
+
+
+class AggregateName(StrEnum):
+    COUNT = "count"
+    SUM = "sum"
+    AVERAGE = "average"
+    MINIMUM = "minimum"
+    MAXIMUM = "maximum"
+    JSON_ARRAY_AGG = "json-array-agg"
+    JSON_OBJECT_AGG = "json-object-agg"
+
+
+class DatePart(StrEnum):
+    YEAR = "year"
+    MONTH = "month"
+    DAY = "day"
+    HOUR = "hour"
+    MINUTE = "minute"
+    SECOND = "second"
+
+
+@dataclass(frozen=True, slots=True)
+class BoundValueNode:
+    value: object
+    family: ScalarFamily
+    sensitive: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class FieldNode:
+    name: str
+    table: str | None = None
+    schema: str | None = None
+    catalog: str | None = None
+    family: ScalarFamily = ScalarFamily.OTHER
+    # What the column was declared to hold, which a family cannot say: an
+    # integer, a float, and a decimal are all one family and three types.
+    value_type: type[object] | None = None
+    # Whether the column may hold no value, which decides whether anything
+    # read through it may answer with none.
+    nullable: bool = True
+
+    def __post_init__(self) -> None:
+        _require_identifier(self.name, "field")
+        _require_optional_identifier(self.table, "table")
+        _require_optional_identifier(self.schema, "schema")
+        _require_optional_identifier(self.catalog, "catalog")
+
+
+@dataclass(frozen=True, slots=True)
+class UnaryNode:
+    operator: UnaryOperator
+    operand: ExpressionNode
+
+
+@dataclass(frozen=True, slots=True)
+class BinaryNode:
+    operator: BinaryOperator
+    left: ExpressionNode
+    right: ExpressionNode
+
+
+@dataclass(frozen=True, slots=True)
+class VariadicNode:
+    operator: VariadicOperator
+    operands: tuple[ExpressionNode, ...]
+
+    def __post_init__(self) -> None:
+        if not self.operands:
+            message = "variadic expression requires at least one operand"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionNode:
+    name: FunctionName
+    arguments: tuple[ExpressionNode, ...]
+
+    def __post_init__(self) -> None:
+        if not self.arguments:
+            message = "function expression requires at least one argument"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractNode:
+    part: DatePart
+    expression: ExpressionNode
+
+
+_AGGREGATE_ARITY = {AggregateName.JSON_OBJECT_AGG: 2}
+"""Aggregates that read more than the one value the rest of them read."""
+
+
+@dataclass(frozen=True, slots=True)
+class AggregateNode:
+    name: AggregateName
+    arguments: tuple[ExpressionNode, ...]
+    distinct: bool = False
+
+    def __post_init__(self) -> None:
+        if self.name is AggregateName.COUNT:
+            if len(self.arguments) > 1:
+                message = "count aggregate accepts at most one argument"
+                raise ValueError(message)
+        elif len(self.arguments) != _AGGREGATE_ARITY.get(self.name, 1):
+            message = "aggregate requires exactly one argument"
+            raise ValueError(message)
+        if self.distinct and not self.arguments:
+            message = "distinct aggregate requires an argument"
+            raise ValueError(message)
+
+
+RawPart: TypeAlias = Union[str, "ExpressionNode"]
+
+
+@dataclass(frozen=True, slots=True)
+class RawNode:
+    parts: tuple[RawPart, ...]
+    family: ScalarFamily = ScalarFamily.OTHER
+
+    def __post_init__(self) -> None:
+        if not self.parts or not any(
+            isinstance(part, str) and part for part in self.parts
+        ):
+            message = "raw expression requires structural SQL text"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class CollectionEntry:
+    """One named value each row of a collection carries."""
+
+    key: str
+    expression: ExpressionNode
+
+    def __post_init__(self) -> None:
+        if not self.key:
+            message = "a collection entry needs a key"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class CollectionOrderNode:
+    expression: ExpressionNode
+    descending: bool = False
+
+
+def _require_bounded_collection(
+    limit: int | None,
+    orders: tuple[CollectionOrderNode, ...],
+) -> None:
+    """A limit takes the first rows, so something has to say which are first."""
+    if limit is None:
+        return
+    if limit < 1:
+        message = "a collection carries at least one row or is not limited"
+        raise ValueError(message)
+    if not orders:
+        message = "a limited collection is ordered, so the rows it keeps are known"
+        raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class CollectionJoinNode:
+    """A table a collection reads alongside the one the relation names.
+
+    A collection is still the rows of one relation. A join widens what each of
+    those rows carries and does not change which rows there are, so it is a
+    left join: an inner one would drop a row whose join matched nothing, which
+    is a row the collection was asked for going missing. A row that matched
+    nothing carries null for what the join would have added.
+    """
+
+    table: str
+    condition: ExpressionNode
+    schema: str | None = None
+    catalog: str | None = None
+    alias: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.table:
+            message = "a collection join needs a table to read"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class CollectionNode:
+    """A related table's rows, gathered into one value beside their parent.
+
+    The condition correlates the collection with the row it belongs to, so it
+    reads columns of both tables. The relation names one table, and a join
+    widens what each of its rows carries without changing which rows there
+    are, so a collection stays the rows of one relation.
+
+    ``limit`` bounds how many rows the collection carries. The rows are chosen
+    by the order, so a limit without one would take an arbitrary few, and it
+    is refused here rather than left to the dialect to decide. That is also
+    why a dialect that cannot order inside a collection cannot carry a limited
+    one: the order refusal already covers both.
+    """
+
+    table: str
+    entries: tuple[CollectionEntry, ...]
+    condition: ExpressionNode
+    orders: tuple[CollectionOrderNode, ...] = ()
+    schema: str | None = None
+    catalog: str | None = None
+    alias: str | None = None
+    joins: tuple[CollectionJoinNode, ...] = ()
+    limit: int | None = None
+
+    def __post_init__(self) -> None:
+        if not self.table:
+            message = "a collection needs a table to read"
+            raise ValueError(message)
+        if not self.entries:
+            message = "a collection needs at least one value per row"
+            raise ValueError(message)
+        _require_bounded_collection(self.limit, self.orders)
+        keys = tuple(entry.key for entry in self.entries)
+        if len(set(keys)) != len(keys):
+            message = "a collection cannot carry one key twice"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class VendorFunctionNode:
+    """A function this database has that PyOQ does not name itself.
+
+    The name is written into the SQL rather than bound, so it is checked to
+    be an identifier and nothing else. The arguments are expressions and
+    travel the way every other expression does.
+
+    ``dialects`` is the databases the function exists on. Empty means the
+    caller did not say, and it is written wherever it is asked for.
+    """
+
+    name: str
+    arguments: tuple[ExpressionNode, ...]
+    family: ScalarFamily
+    dialects: frozenset[str] = frozenset()
+    # Where the routine is kept, held apart so each part is quoted as itself
+    # rather than flattened into a name a dot could be part of.
+    schema: str | None = None
+    catalog: str | None = None
+    # What the caller declared it answers with, which a family cannot say and
+    # which is what reads the value back as the type it was promised to be.
+    value_type: type[object] | None = None
+
+
+class ArrayOperation(StrEnum):
+    """What is being asked of an array and one other thing."""
+
+    HAS = "has"
+    LACKS = "lacks"
+    CONTAINS = "contains"
+    CONTAINED_BY = "contained-by"
+    OVERLAPS = "overlaps"
+    APPEND = "append"
+    PREPEND = "prepend"
+    CONCAT = "concat"
+    REMOVE = "remove"
+    REPLACE = "replace"
+
+
+_ARRAY_ARITY = {ArrayOperation.REPLACE: 2}
+"""Operations that read more than the one value the rest of them read."""
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayNode:
+    """An array asked about against something else."""
+
+    operation: ArrayOperation
+    expression: ExpressionNode
+    operands: tuple[ExpressionNode, ...]
+
+    def __post_init__(self) -> None:
+        if len(self.operands) != _ARRAY_ARITY.get(self.operation, 1):
+            message = "array operation was given the wrong number of values"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayElementNode:
+    """One element of an array, counted the way the value it reads back is.
+
+    A column of an array is read back as a tuple, and a tuple counts from
+    zero, so this does too. SQL counts arrays from one, which is a difference
+    written out here rather than left for a caller to remember.
+    """
+
+    expression: ExpressionNode
+    indexes: tuple[ExpressionNode, ...]
+
+    def __post_init__(self) -> None:
+        if not self.indexes:
+            message = "an element of an array is read at a position"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayLengthNode:
+    """How many elements an array holds, in one dimension or in all of them."""
+
+    expression: ExpressionNode
+    dimension: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayConstructNode:
+    """An array built out of the values around it."""
+
+    elements: tuple[ExpressionNode, ...] = ()
+    # What one element holds, where every element holds the same thing.
+    element_type: type[object] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayDimensionsNode:
+    """How many dimensions an array has, which an empty array does not say."""
+
+    expression: ExpressionNode
+
+
+class JsonOperation(StrEnum):
+    """What is being asked of a JSON value at a path."""
+
+    VALUE = "value"
+    TEXT = "text"
+    LENGTH = "length"
+    EXISTS = "exists"
+    REMOVE = "remove"
+
+
+@dataclass(frozen=True, slots=True)
+class JsonNode:
+    """Reading inside a JSON value, by a path each dialect spells its own way.
+
+    The path is steps rather than text, because the three dialects do not
+    agree on how a path is written and one of them reads another's spelling
+    as a key that is simply absent. Steps are a string for a member and an
+    integer for an element.
+    """
+
+    operation: JsonOperation
+    expression: ExpressionNode
+    path: tuple[str | int, ...] = ()
+
+
+class JsonBuild(StrEnum):
+    """Whether a JSON value is being built as an object or as an array."""
+
+    OBJECT = "object"
+    ARRAY = "array"
+
+
+@dataclass(frozen=True, slots=True)
+class JsonBuildNode:
+    """A JSON value built out of the values around it.
+
+    An object reads its arguments as alternating members and values, so it
+    takes an even number of them and every other one names a member.
+    """
+
+    kind: JsonBuild
+    arguments: tuple[ExpressionNode, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.kind is JsonBuild.OBJECT and len(self.arguments) % 2:
+            message = "a JSON object is built from members and their values"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class JsonKeysNode:
+    """The members an object has, as a JSON array of their names.
+
+    The dialects do not agree on the order the names come back in, because
+    each one stores an object the way it stores an object.
+    """
+
+    expression: ExpressionNode
+
+
+class JsonWrite(StrEnum):
+    """How a value is put into a JSON document."""
+
+    SET = "set"
+    INSERT = "insert"
+    REPLACE = "replace"
+    MERGE = "merge"
+    """Merge-patch: a null removes a member, and objects merge all the way down."""
+
+    CONCAT = "concat"
+    """One level only: a member is replaced whole, and a null is kept as one."""
+
+
+@dataclass(frozen=True, slots=True)
+class JsonWriteNode:
+    """A JSON document with something written into it.
+
+    The answer is a new document; nothing is changed in place, because an
+    expression cannot change anything. A merge has no path, because it is
+    written over the whole document.
+    """
+
+    operation: JsonWrite
+    expression: ExpressionNode
+    value: ExpressionNode
+    path: tuple[str | int, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.operation is JsonWrite.MERGE and self.path:
+            message = "a merge is written over the whole document, not at a path"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class JsonContainsNode:
+    """Whether one JSON value holds another, which is not a question of path."""
+
+    expression: ExpressionNode
+    value: ExpressionNode
+
+
+@dataclass(frozen=True, slots=True)
+class RowValueNode:
+    """Several values compared as one, the way a composite key is.
+
+    A row of one value is that value, and SQL reads it as one, so a row
+    value is only a row value from two columns up.
+    """
+
+    expressions: tuple[ExpressionNode, ...]
+
+    def __post_init__(self) -> None:
+        if len(self.expressions) < _ROW_VALUE_WIDTH:
+            message = "a row value needs at least two expressions"
+            raise ValueError(message)
+
+
+class FrameKind(StrEnum):
+    """What a frame counts: rows, values, or peer groups."""
+
+    ROWS = "rows"
+    RANGE = "range"
+    GROUPS = "groups"
+
+
+class FrameBound(StrEnum):
+    """Where a frame starts or ends, relative to the row being measured."""
+
+    UNBOUNDED_PRECEDING = "unbounded-preceding"
+    PRECEDING = "preceding"
+    CURRENT_ROW = "current-row"
+    FOLLOWING = "following"
+    UNBOUNDED_FOLLOWING = "unbounded-following"
+
+
+class FrameExclusion(StrEnum):
+    """Which rows a frame leaves out even though it reaches them."""
+
+    CURRENT_ROW = "current-row"
+    GROUP = "group"
+    TIES = "ties"
+    NO_OTHERS = "no-others"
+
+
+@dataclass(frozen=True, slots=True)
+class FrameBoundNode:
+    """One edge of a frame, and how far from the row it sits."""
+
+    bound: FrameBound
+    offset: ExpressionNode | None = None
+
+    def __post_init__(self) -> None:
+        counted = self.bound in {FrameBound.PRECEDING, FrameBound.FOLLOWING}
+        if counted != (self.offset is not None):
+            message = "a counted frame edge needs a distance and no other does"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class FrameNode:
+    """The rows a window function reads, narrower than the whole partition."""
+
+    kind: FrameKind
+    start: FrameBoundNode
+    end: FrameBoundNode | None = None
+    exclusion: FrameExclusion | None = None
+
+
+class WindowName(StrEnum):
+    ROW_NUMBER = "row-number"
+    RANK = "rank"
+    DENSE_RANK = "dense-rank"
+    PERCENT_RANK = "percent-rank"
+    CUME_DIST = "cume-dist"
+    NTILE = "ntile"
+    LAG = "lag"
+    LEAD = "lead"
+    FIRST_VALUE = "first-value"
+    LAST_VALUE = "last-value"
+    NTH_VALUE = "nth-value"
+
+
+@dataclass(frozen=True, slots=True)
+class WindowFunctionNode:
+    """A function that only means anything with a window behind it."""
+
+    name: WindowName
+    arguments: tuple[ExpressionNode, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class WindowSpecificationNode:
+    """What a row is measured against: its partition, in its order.
+
+    The rows a window covers are named the way a query names them, so the
+    order terms here are the same ones an ORDER BY is built from.
+    """
+
+    partition_by: tuple[ExpressionNode, ...] = ()
+    order_by: tuple[OrderNode, ...] = ()
+    frame: FrameNode | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class WindowReferenceNode:
+    """A window the query declared once under a name."""
+
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class NamedWindowNode:
+    """A window written once in a query and looked through by several rows."""
+
+    name: str
+    specification: WindowSpecificationNode
+
+
+EVERY_ROW = WindowSpecificationNode()
+"""The window a function reads before anything narrows it."""
+
+
+@dataclass(frozen=True, slots=True)
+class WindowNode:
+    """A function and the window it looks through, spelled out or named."""
+
+    expression: ExpressionNode
+    window: WindowSpecificationNode | WindowReferenceNode = EVERY_ROW
+
+
+@dataclass(frozen=True, slots=True)
+class CastNode:
+    """A value asked for as another type, by the database rather than Python.
+
+    The Python type is the one fact stored. What SQL names it is a dialect
+    question, and what reads it back is a decoding question, and both are
+    answered from here rather than repeated alongside it.
+    """
+
+    expression: ExpressionNode
+    value_type: type[object]
+
+
+@dataclass(frozen=True, slots=True)
+class CaseNode:
+    """One value chosen from several, by the first condition that holds.
+
+    The branches are ordered, because SQL reads them in order and so does a
+    reader. A case with no branches chooses nothing and is not a value.
+    """
+
+    branches: tuple[tuple[ExpressionNode, ExpressionNode], ...]
+    otherwise: ExpressionNode | None = None
+
+    def __post_init__(self) -> None:
+        if not self.branches:
+            message = "case expression requires at least one branch"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class ExistsNode:
+    """Whether a query returns anything at all.
+
+    The query is held rather than a source, because what EXISTS asks about is
+    a whole statement. The import is type only, so an expression may contain a
+    query without the node layers depending on each other at runtime.
+    """
+
+    query: QueryNode
+    negated: bool = False
+
+
+ExpressionNode = (
+    BoundValueNode
+    | FieldNode
+    | UnaryNode
+    | BinaryNode
+    | VariadicNode
+    | FunctionNode
+    | ExtractNode
+    | AggregateNode
+    | CaseNode
+    | CastNode
+    | VendorFunctionNode
+    | ArrayNode
+    | ArrayElementNode
+    | ArrayLengthNode
+    | ArrayConstructNode
+    | ArrayDimensionsNode
+    | JsonContainsNode
+    | JsonWriteNode
+    | JsonNode
+    | JsonBuildNode
+    | JsonKeysNode
+    | RowValueNode
+    | WindowFunctionNode
+    | WindowNode
+    | CollectionNode
+    | ExistsNode
+    | RawNode
+)
+
+
+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__ = (
+    "AggregateName",
+    "AggregateNode",
+    "BinaryNode",
+    "BinaryOperator",
+    "BoundValueNode",
+    "CollectionEntry",
+    "CollectionNode",
+    "CollectionOrderNode",
+    "DatePart",
+    "ExpressionNode",
+    "ExtractNode",
+    "FieldNode",
+    "FunctionName",
+    "FunctionNode",
+    "RawNode",
+    "RawPart",
+    "ScalarFamily",
+    "UnaryNode",
+    "UnaryOperator",
+    "VariadicNode",
+    "VariadicOperator",
+)