pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/results.py

@@ -0,0 +1,459 @@
+"""What an expression answers with, in one place.
+
+Three facts, one home: the kind of value it is, the Python type it holds where
+that can be known, and whether it may answer with nothing. They are derived
+from the same tree by the same walk, so nothing holds two answers to one of
+them, and nothing above this decides any of them again.
+
+A family says what kind of value an expression is. This says the rest: which
+Python type it is where that can be known, and whether it may answer with no
+value at all. All three are derived from the same tree, so there is one answer
+to what an expression results in rather than one per layer that wants to know.
+
+Without it a caller is promised a Decimal by the type checker and handed a
+float by the driver, which is the promise the decoder exists to keep.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import date, time, timedelta
+from decimal import Decimal
+from typing import TypeAlias, get_args, get_origin
+
+from pyoq.query.nodes import (
+    AggregateName,
+    AggregateNode,
+    ArrayConstructNode,
+    ArrayDimensionsNode,
+    ArrayElementNode,
+    ArrayLengthNode,
+    ArrayNode,
+    ArrayOperation,
+    BinaryNode,
+    BinaryOperator,
+    BoundValueNode,
+    CaseNode,
+    CastNode,
+    CollectionNode,
+    ExistsNode,
+    ExpressionNode,
+    ExtractNode,
+    FieldNode,
+    FunctionName,
+    FunctionNode,
+    JsonBuildNode,
+    JsonContainsNode,
+    JsonKeysNode,
+    JsonNode,
+    JsonOperation,
+    JsonWriteNode,
+    RawNode,
+    RowValueNode,
+    ScalarFamily,
+    UnaryNode,
+    UnaryOperator,
+    VariadicNode,
+    VendorFunctionNode,
+    WindowFunctionNode,
+    WindowName,
+    WindowNode,
+)
+from pyoq.schema.models import TypeKind
+
+_NUMERIC_KINDS = frozenset(
+    {
+        TypeKind.BIG_INTEGER,
+        TypeKind.DECIMAL,
+        TypeKind.DOUBLE,
+        TypeKind.INTEGER,
+        TypeKind.REAL,
+        TypeKind.SMALL_INTEGER,
+    }
+)
+_TEMPORAL_KINDS = frozenset(
+    {TypeKind.DATE, TypeKind.DATETIME, TypeKind.INTERVAL, TypeKind.TIME}
+)
+
+
+def family_for_kind(kind: TypeKind, /) -> ScalarFamily:
+    """What kind of value a column declared with this SQL type holds.
+
+    The companion to `family_for_type`: one reads a Python type and this reads
+    a schema's own. Both answer the same question, so they live together and a
+    kind gains a family in one place rather than in each layer that asks.
+    """
+    if kind is TypeKind.BOOLEAN:
+        return ScalarFamily.BOOLEAN
+    if kind in _NUMERIC_KINDS:
+        return ScalarFamily.NUMERIC
+    if kind in {TypeKind.STRING, TypeKind.ENUM}:
+        return ScalarFamily.STRING
+    if kind is TypeKind.BINARY:
+        return ScalarFamily.BINARY
+    if kind in _TEMPORAL_KINDS:
+        return ScalarFamily.TEMPORAL
+    if kind is TypeKind.JSON:
+        return ScalarFamily.JSON
+    return ScalarFamily.OTHER
+
+
+def family_for_type(value_type: type[object]) -> ScalarFamily:
+    """What kind of value a column of this type holds.
+
+    A column that holds a collection is written with what it holds, so the
+    type given here may be a parameterised one. What decides the family is
+    what it is a collection of, which is the type it is written from.
+    """
+    written = get_origin(value_type) or value_type
+    if not isinstance(written, type):
+        return ScalarFamily.OTHER
+    return _family_of(written)
+
+
+def _family_of(value_type: type[object]) -> ScalarFamily:
+    if issubclass(value_type, bool):
+        return ScalarFamily.BOOLEAN
+    if issubclass(value_type, (int, float, Decimal)):
+        return ScalarFamily.NUMERIC
+    if issubclass(value_type, str):
+        return ScalarFamily.STRING
+    if issubclass(value_type, bytes):
+        return ScalarFamily.BINARY
+    if issubclass(value_type, (date, time, timedelta)):
+        return ScalarFamily.TEMPORAL
+    if issubclass(value_type, (list, dict)):
+        return ScalarFamily.JSON
+    return ScalarFamily.OTHER
+
+
+def expression_family(node: ExpressionNode) -> ScalarFamily:
+    """What kind of value this node answers with."""
+    if isinstance(node, (BoundValueNode, FieldNode, RawNode, VendorFunctionNode)):
+        return node.family
+    if isinstance(node, UnaryNode):
+        if node.operator is UnaryOperator.NEGATE:
+            return expression_family(node.operand)
+        return ScalarFamily.BOOLEAN
+    if isinstance(node, BinaryNode):
+        return _binary_family(node)
+    if isinstance(node, VariadicNode):
+        return ScalarFamily.BOOLEAN
+    if isinstance(node, FunctionNode):
+        if node.name in _CHOOSING:
+            return expression_family(node.arguments[0])
+        return _function_family(node.name)
+    if isinstance(node, ExtractNode):
+        return ScalarFamily.NUMERIC
+    if isinstance(node, RowValueNode):
+        return ScalarFamily.OTHER
+    if isinstance(node, _Shaped):
+        return _shaped_family(node)
+    return _borrowed_family(node)
+
+
+_ARRAY_ANSWERS_AN_ARRAY = frozenset(
+    {
+        ArrayOperation.APPEND,
+        ArrayOperation.PREPEND,
+        ArrayOperation.CONCAT,
+        ArrayOperation.REMOVE,
+        ArrayOperation.REPLACE,
+    }
+)
+"""The ways of asking about an array that answer with another array."""
+
+
+def _shaped_family(node: _Shaped) -> ScalarFamily:
+    """The kinds whose family their own shape decides, not what is inside."""
+    if isinstance(node, JsonNode):
+        return _JSON_FAMILIES[node.operation]
+    if isinstance(node, (JsonWriteNode, JsonBuildNode, JsonKeysNode)):
+        return ScalarFamily.JSON
+    if isinstance(node, JsonContainsNode):
+        return ScalarFamily.BOOLEAN
+    if isinstance(node, ArrayNode):
+        return (
+            ScalarFamily.OTHER
+            if node.operation in _ARRAY_ANSWERS_AN_ARRAY
+            else ScalarFamily.BOOLEAN
+        )
+    if isinstance(node, (ArrayLengthNode, ArrayDimensionsNode)):
+        return ScalarFamily.NUMERIC
+    if isinstance(node, ArrayConstructNode):
+        return ScalarFamily.OTHER
+    return ScalarFamily.OTHER
+
+
+_JSON_AGGREGATES = frozenset(
+    {AggregateName.JSON_ARRAY_AGG, AggregateName.JSON_OBJECT_AGG}
+)
+"""Aggregates that gather rows into a JSON value rather than a number."""
+
+
+def _borrowed_family(node: _Borrowing) -> ScalarFamily:
+    """The kinds that take their family from something inside them."""
+    if isinstance(node, CollectionNode):
+        return ScalarFamily.JSON
+    if isinstance(node, ExistsNode):
+        return ScalarFamily.BOOLEAN
+    if isinstance(node, CaseNode):
+        return expression_family(node.branches[0][1])
+    if isinstance(node, CastNode):
+        return family_for_type(node.value_type)
+    if isinstance(node, WindowNode):
+        return expression_family(node.expression)
+    if isinstance(node, WindowFunctionNode):
+        return _window_family(node)
+    if node.name in {AggregateName.MINIMUM, AggregateName.MAXIMUM}:
+        return expression_family(node.arguments[0])
+    if node.name in _JSON_AGGREGATES:
+        return ScalarFamily.JSON
+    return ScalarFamily.NUMERIC
+
+
+_Shaped: TypeAlias = (
+    JsonNode
+    | JsonWriteNode
+    | JsonBuildNode
+    | JsonKeysNode
+    | JsonContainsNode
+    | ArrayNode
+    | ArrayLengthNode
+    | ArrayElementNode
+    | ArrayConstructNode
+    | ArrayDimensionsNode
+)
+
+_Borrowing: TypeAlias = (
+    CollectionNode
+    | ExistsNode
+    | CaseNode
+    | CastNode
+    | WindowNode
+    | WindowFunctionNode
+    | AggregateNode
+)
+
+
+_JSON_FAMILIES: Mapping[JsonOperation, ScalarFamily] = {
+    JsonOperation.VALUE: ScalarFamily.JSON,
+    JsonOperation.TEXT: ScalarFamily.STRING,
+    JsonOperation.LENGTH: ScalarFamily.NUMERIC,
+    JsonOperation.EXISTS: ScalarFamily.BOOLEAN,
+    JsonOperation.REMOVE: ScalarFamily.JSON,
+}
+"""What each question about a JSON value answers with."""
+
+
+_NAVIGATING_WINDOWS = frozenset(
+    {
+        WindowName.LAG,
+        WindowName.LEAD,
+        WindowName.FIRST_VALUE,
+        WindowName.LAST_VALUE,
+        WindowName.NTH_VALUE,
+    }
+)
+"""Windows that answer with a value already in the window."""
+
+
+def _window_family(node: WindowFunctionNode) -> ScalarFamily:
+    """A position is a number; a neighbour's value is whatever that value is."""
+    if node.name in _NAVIGATING_WINDOWS:
+        return expression_family(node.arguments[0])
+    return ScalarFamily.NUMERIC
+
+
+def _binary_family(node: BinaryNode) -> ScalarFamily:
+    boolean_operators = {
+        BinaryOperator.EQUAL,
+        BinaryOperator.NOT_EQUAL,
+        BinaryOperator.LESS_THAN,
+        BinaryOperator.LESS_OR_EQUAL,
+        BinaryOperator.GREATER_THAN,
+        BinaryOperator.GREATER_OR_EQUAL,
+        BinaryOperator.IS_DISTINCT_FROM,
+        BinaryOperator.IS_NOT_DISTINCT_FROM,
+        BinaryOperator.LIKE,
+        BinaryOperator.NOT_LIKE,
+    }
+    if node.operator in boolean_operators:
+        return ScalarFamily.BOOLEAN
+    if node.operator is BinaryOperator.CONCAT:
+        return ScalarFamily.STRING
+    families = {expression_family(node.left), expression_family(node.right)}
+    if ScalarFamily.TEMPORAL in families:
+        return ScalarFamily.TEMPORAL
+    return ScalarFamily.NUMERIC
+
+
+_CHOOSING = frozenset(
+    {
+        FunctionName.COALESCE,
+        FunctionName.NULLIF,
+        FunctionName.GREATEST,
+        FunctionName.LEAST,
+    }
+)
+
+
+def _function_family(name: FunctionName) -> ScalarFamily:
+    if name in {FunctionName.LOWER, FunctionName.UPPER}:
+        return ScalarFamily.STRING
+    if name is FunctionName.LENGTH:
+        return ScalarFamily.NUMERIC
+    return ScalarFamily.BOOLEAN
+
+
+_CARRYING_FUNCTIONS = frozenset(
+    {
+        FunctionName.COALESCE,
+        FunctionName.NULLIF,
+        FunctionName.GREATEST,
+        FunctionName.LEAST,
+    }
+)
+"""Functions that answer with one of the values they were given."""
+
+_CARRYING_AGGREGATES = frozenset({AggregateName.MINIMUM, AggregateName.MAXIMUM})
+
+_CARRYING_WINDOWS = frozenset(
+    {
+        WindowName.LAG,
+        WindowName.LEAD,
+        WindowName.FIRST_VALUE,
+        WindowName.LAST_VALUE,
+        WindowName.NTH_VALUE,
+    }
+)
+"""Windows that answer with a value one of their rows already held."""
+
+
+def declared_type(node: ExpressionNode, /) -> type[object] | None:
+    """The Python type this answers with, where the tree knows one.
+
+    A node that carries a value through answers with whatever that value was
+    declared to be. A node that computes something new answers with nothing
+    here, and its family speaks for it instead.
+    """
+    if isinstance(node, (FieldNode, CastNode)):
+        return node.value_type
+    if isinstance(node, CaseNode):
+        return declared_type(node.branches[0][1])
+    if isinstance(node, WindowNode):
+        return declared_type(node.expression)
+    if isinstance(node, ArrayElementNode):
+        return _element_type(declared_type(node.expression))
+    if isinstance(node, ArrayConstructNode):
+        return node.element_type
+    if isinstance(node, VendorFunctionNode):
+        return node.value_type
+    if isinstance(node, ArrayNode) and node.operation in _ARRAY_ANSWERS_AN_ARRAY:
+        return declared_type(node.expression)
+    return _carried(node)
+
+
+def _carried(node: ExpressionNode) -> type[object] | None:
+    """The kinds that answer with one of their own arguments."""
+    if isinstance(node, FunctionNode) and node.name in _CARRYING_FUNCTIONS:
+        return declared_type(node.arguments[0])
+    if isinstance(node, AggregateNode) and node.name in _CARRYING_AGGREGATES:
+        return declared_type(node.arguments[0])
+    if isinstance(node, WindowFunctionNode) and node.name in _CARRYING_WINDOWS:
+        return declared_type(node.arguments[0])
+    return None
+
+
+def _element_type(array_type: type[object] | None) -> type[object] | None:
+    """What one element of an array was declared to hold.
+
+    An array column is declared as a tuple of its element type, so the element
+    type is inside it. A bare tuple says nothing about what it holds.
+    """
+    if array_type is None or get_origin(array_type) is not tuple:
+        return None
+    arguments = get_args(array_type)
+    return arguments[0] if arguments else None
+
+
+_NEVER_NULL_AGGREGATES = frozenset({AggregateName.COUNT})
+"""Aggregates that answer with a value even where there are no rows."""
+
+
+@dataclass(frozen=True, slots=True)
+class ResultDescriptor:
+    """Everything one expression answers with, derived from the tree once.
+
+    ``family`` is the kind of value, which every expression has. ``declared``
+    is the Python type where the tree knows one, and is none where an
+    expression computes something the tree cannot name. ``nullable`` is
+    whether it may answer with no value.
+    """
+
+    family: ScalarFamily
+    declared: type[object] | None
+    nullable: bool
+
+
+def result_descriptor(node: ExpressionNode, /) -> ResultDescriptor:
+    """What this expression answers with, which one place decides."""
+    return ResultDescriptor(
+        expression_family(node), declared_type(node), nullable(node)
+    )
+
+
+def nullable(node: ExpressionNode, /) -> bool:
+    """Whether this may answer with no value at all.
+
+    A column says so itself. Everything else says so through what it reads:
+    a value carried through is as nullable as the value was, and a question
+    answered about rows that may not be there is nullable whatever it reads.
+    """
+    if isinstance(node, FieldNode):
+        return node.nullable
+    if isinstance(node, BoundValueNode):
+        return node.value is None
+    if isinstance(node, (ExistsNode, RowValueNode)):
+        return False
+    if isinstance(node, AggregateNode):
+        return node.name not in _NEVER_NULL_AGGREGATES
+    if isinstance(node, WindowFunctionNode):
+        return node.name in _CARRYING_WINDOWS
+    return _nullable_through(node)
+
+
+def _nullable_through(node: ExpressionNode) -> bool:
+    """The kinds that are nullable because what they read is."""
+    if isinstance(node, (CastNode, WindowNode)):
+        return nullable(node.expression)
+    if isinstance(node, UnaryNode):
+        return nullable(node.operand)
+    if isinstance(node, BinaryNode):
+        return nullable(node.left) or nullable(node.right)
+    if isinstance(node, CaseNode):
+        return _nullable_case(node)
+    if isinstance(node, FunctionNode) and node.name is FunctionName.COALESCE:
+        return nullable(node.arguments[-1])
+    return True
+
+
+def _nullable_case(node: CaseNode) -> bool:
+    """A case answers with null where no branch holds and none was given."""
+    if node.otherwise is None:
+        return True
+    return any(nullable(result) for _, result in node.branches) or nullable(
+        node.otherwise
+    )
+
+
+__all__ = (
+    "ResultDescriptor",
+    "declared_type",
+    "expression_family",
+    "family_for_kind",
+    "family_for_type",
+    "nullable",
+    "result_descriptor",
+)

pyoq/query/routines.py

@@ -0,0 +1,196 @@
+"""Running a stored procedure.
+
+A procedure is invoked rather than selected from, and it may answer with rows
+or with nothing at all, so it is a statement rather than an expression. A
+stored function is a function and is declared with `vendor_function` instead.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING, Generic, Literal, TypeVar, cast, overload
+
+from pyoq.errors import QueryValidationError
+from pyoq.query.expressions import ComputedExpression, Expression
+from pyoq.query.nodes import FieldNode
+from pyoq.query.results import family_for_type
+from pyoq.query.select_nodes import ProjectionNode
+from pyoq.query.values import bind
+from pyoq.query.vendor import checked_routine_name, checked_routine_qualifier
+from pyoq.query.write_nodes import CallNode
+
+if TYPE_CHECKING:
+    from pyoq.query.nodes import ExpressionNode
+    from pyoq.query.raw import NodeProvider
+
+ResultRow = TypeVar("ResultRow")
+Value1 = TypeVar("Value1")
+Value2 = TypeVar("Value2")
+Value3 = TypeVar("Value3")
+Value4 = TypeVar("Value4")
+Value5 = TypeVar("Value5")
+Value6 = TypeVar("Value6")
+
+
+class Call(Generic[ResultRow]):
+    """A procedure asked to run, and whatever it answers with.
+
+    A procedure's rows are described by the expressions passed to returning,
+    so their tuple type and runtime decoder come from the same declarations.
+    """
+
+    __slots__ = ("_node",)
+
+    def __init__(self, node: CallNode) -> None:
+        self._node = node
+
+    @property
+    def node(self) -> CallNode:
+        return self._node
+
+    @overload
+    def returning(self, value1: Expression[Value1], /) -> Call[tuple[Value1]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        /,
+    ) -> Call[tuple[Value1, Value2]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        /,
+    ) -> Call[tuple[Value1, Value2, Value3]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        /,
+    ) -> Call[tuple[Value1, Value2, Value3, Value4]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        /,
+    ) -> Call[tuple[Value1, Value2, Value3, Value4, Value5]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        value6: Expression[Value6],
+        /,
+    ) -> Call[tuple[Value1, Value2, Value3, Value4, Value5, Value6]]: ...
+
+    def returning(  # type: ignore[misc]
+        self,
+        *columns: Expression[object],
+    ) -> Call[object]:
+        """Say what the rows this answers with hold.
+
+        Naming the columns supplies both the tuple type and runtime decoder.
+        """
+        if not columns:
+            message = "a procedure returning rows names at least one column"
+            raise QueryValidationError(message)
+        return Call[object](
+            replace(
+                self._node,
+                returning=tuple(ProjectionNode(column.node) for column in columns),
+            )
+        )
+
+
+def argument(value: object, /) -> NodeProvider:
+    """A routine argument, whether it was given as an expression or a value.
+
+    Generated call surfaces take either, because a caller passing a literal
+    should not have to say so, and a value still travels bound.
+    """
+    if isinstance(value, Expression):
+        return cast("Expression[object]", value)
+    return bind(value)
+
+
+@overload
+def routine_output(
+    value_type: type[ResultRow],
+    name: str,
+    /,
+    *,
+    nullable: Literal[False],
+) -> ComputedExpression[ResultRow]: ...
+
+
+@overload
+def routine_output(
+    value_type: type[ResultRow],
+    name: str,
+    /,
+    *,
+    nullable: Literal[True],
+) -> ComputedExpression[ResultRow | None]: ...
+
+
+def routine_output(
+    value_type: type[ResultRow],
+    name: str,
+    /,
+    *,
+    nullable: bool,
+) -> ComputedExpression[ResultRow] | ComputedExpression[ResultRow | None]:
+    """Describe a reflected routine output without losing its nullability."""
+    family = family_for_type(value_type)
+    expression: ComputedExpression[ResultRow] | ComputedExpression[ResultRow | None]
+    expression = ComputedExpression(
+        FieldNode(name, family=family, value_type=value_type, nullable=nullable),
+        family,
+    )
+    return expression
+
+
+def call(
+    name: str,
+    /,
+    *arguments: NodeProvider,
+    schema: str | None = None,
+    catalog: str | None = None,
+) -> Call[tuple[object, ...]]:
+    """Run a stored procedure, with its arguments bound like any other value.
+
+    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. Saying
+    which schema keeps it is what makes the call reach that one rather than
+    whichever the search path finds first.
+    """
+    nodes: tuple[ExpressionNode, ...] = tuple(argument.node for argument in arguments)
+    return Call[tuple[object, ...]](
+        CallNode(
+            checked_routine_name(name),
+            checked_routine_qualifier(schema, "routine schema"),
+            checked_routine_qualifier(catalog, "routine catalog"),
+            nodes,
+        )
+    )
+
+
+__all__ = ("Call", "argument", "call", "routine_output")