pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/aggregates.py

@@ -0,0 +1,172 @@
+"""Typed aggregate expressions."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TypeAlias, TypeVar, cast, overload
+
+from pyoq.errors import ExpressionTypeError
+from pyoq.query.expressions import ComputedExpression, Expression
+from pyoq.query.nodes import AggregateName, AggregateNode, ScalarFamily
+from pyoq.query.raw import NodeProvider
+from pyoq.query.windows import Window, WindowSpecification, looking_through
+from pyoq.schema.models import JsonValue
+
+Value = TypeVar("Value")
+
+
+class AggregateExpression(ComputedExpression[Value]):
+    __slots__ = ()
+
+    def over(self, window: WindowSpecification | None = None, /) -> Window[Value]:
+        """This aggregate computed per row over its window, not per group.
+
+        The rows stay as they are and each one is given the aggregate of the
+        window around it, so a running total sits beside the row it counts.
+        """
+        return Window[Value](looking_through(self.node, window), self.family)
+
+
+SumResult: TypeAlias = (
+    AggregateExpression[int | None]
+    | AggregateExpression[float | None]
+    | AggregateExpression[Decimal | None]
+)
+AverageResult: TypeAlias = (
+    AggregateExpression[float | None] | AggregateExpression[Decimal | None]
+)
+
+
+def count(
+    expression: Expression[Value] | None = None,
+    /,
+    *,
+    distinct: bool = False,
+) -> AggregateExpression[int]:
+    arguments = () if expression is None else (expression.node,)
+    if distinct and expression is None:
+        message = "distinct count requires an expression"
+        raise ValueError(message)
+    return AggregateExpression(
+        AggregateNode(AggregateName.COUNT, arguments, distinct=distinct),
+        ScalarFamily.NUMERIC,
+    )
+
+
+@overload
+def sum_(expression: Expression[int], /) -> AggregateExpression[int | None]: ...
+
+
+@overload
+def sum_(expression: Expression[float], /) -> AggregateExpression[float | None]: ...
+
+
+@overload
+def sum_(
+    expression: Expression[Decimal],
+    /,
+) -> AggregateExpression[Decimal | None]: ...
+
+
+def sum_(expression: object, /) -> SumResult:
+    typed_expression = _require_expression(expression)
+    _require_numeric(typed_expression)
+    return cast(
+        SumResult,
+        AggregateExpression(
+            AggregateNode(AggregateName.SUM, (typed_expression.node,)),
+            ScalarFamily.NUMERIC,
+        ),
+    )
+
+
+@overload
+def average(expression: Expression[int], /) -> AggregateExpression[float | None]: ...
+
+
+@overload
+def average(expression: Expression[float], /) -> AggregateExpression[float | None]: ...
+
+
+@overload
+def average(
+    expression: Expression[Decimal],
+    /,
+) -> AggregateExpression[Decimal | None]: ...
+
+
+def average(expression: object, /) -> AverageResult:
+    typed_expression = _require_expression(expression)
+    _require_numeric(typed_expression)
+    return cast(
+        AverageResult,
+        AggregateExpression(
+            AggregateNode(AggregateName.AVERAGE, (typed_expression.node,)),
+            ScalarFamily.NUMERIC,
+        ),
+    )
+
+
+def minimum(expression: Expression[Value], /) -> AggregateExpression[Value | None]:
+    return AggregateExpression(
+        AggregateNode(AggregateName.MINIMUM, (expression.node,)),
+        expression.family,
+    )
+
+
+def maximum(expression: Expression[Value], /) -> AggregateExpression[Value | None]:
+    return AggregateExpression(
+        AggregateNode(AggregateName.MAXIMUM, (expression.node,)),
+        expression.family,
+    )
+
+
+def json_agg(expression: NodeProvider, /) -> AggregateExpression[JsonValue]:
+    """The rows of a group gathered into one JSON array.
+
+    Only PostgreSQL and SQLite keep the order the rows were read in. MySQL
+    gathers them in whatever order it reached them.
+    """
+    return AggregateExpression[JsonValue](
+        AggregateNode(AggregateName.JSON_ARRAY_AGG, (expression.node,)),
+        ScalarFamily.JSON,
+    )
+
+
+def json_object_agg(
+    member: Expression[str],
+    value: NodeProvider,
+    /,
+) -> AggregateExpression[JsonValue]:
+    """The rows of a group gathered into one JSON object, named by a column."""
+    return AggregateExpression[JsonValue](
+        AggregateNode(AggregateName.JSON_OBJECT_AGG, (member.node, value.node)),
+        ScalarFamily.JSON,
+    )
+
+
+def _require_numeric(expression: Expression[object]) -> None:
+    if expression.family is not ScalarFamily.NUMERIC:
+        message = "aggregate requires a numeric expression"
+        raise ExpressionTypeError(message)
+
+
+def _require_expression(value: object) -> Expression[object]:
+    if isinstance(value, Expression):
+        return cast(Expression[object], value)
+    message = "aggregate requires a typed expression"
+    raise TypeError(message)
+
+
+__all__ = (
+    "AggregateExpression",
+    "AggregateName",
+    "AggregateNode",
+    "average",
+    "count",
+    "json_agg",
+    "json_object_agg",
+    "maximum",
+    "minimum",
+    "sum_",
+)

pyoq/query/arrays.py

@@ -0,0 +1,65 @@
+"""Building an array out of the values around it.
+
+Asking about an array is asked of the array, so those questions are methods
+on the value itself. Building one starts from values that are not an array
+yet, so it starts here.
+
+Only PostgreSQL keeps arrays as a type of their own. The other dialects
+refuse an array before the statement reaches them rather than storing one
+under a name that does not mean the same thing.
+"""
+
+from __future__ import annotations
+
+from types import GenericAlias
+from typing import TypeVar, cast
+
+from pyoq.errors import QueryValidationError
+from pyoq.query.expressions import (
+    ComputedExpression,
+    Expression,
+    family_for_value,
+    operand,
+)
+from pyoq.query.nodes import ArrayConstructNode, ExpressionNode, ScalarFamily
+
+Element = TypeVar("Element")
+
+
+def array_of(*values: Element) -> ComputedExpression[tuple[Element, ...]]:
+    """An array holding these values, in the order they are written.
+
+    At least one value, because an array built from none has no element type
+    and a database will not store a value whose type it cannot name.
+    """
+    if not values:
+        message = "an array is built from at least one value, which gives it a type"
+        raise QueryValidationError(message)
+    elements: tuple[ExpressionNode, ...] = tuple(
+        operand(value, family_for_value(value)) for value in values
+    )
+    return ComputedExpression[tuple[Element, ...]](
+        ArrayConstructNode(elements, _element_type(values)), ScalarFamily.OTHER
+    )
+
+
+def _element_type(values: tuple[object, ...]) -> type[object] | None:
+    """What an array of these values holds, where they all hold one thing.
+
+    A column of an array is declared as a tuple of its element type, and an
+    array built here is declared the same way, so both read back alike. The
+    tuple type is built rather than written, which is the one place a checker
+    cannot see the type being made, so it is named here.
+
+    Values of more than one type, or values that are expressions, say nothing
+    about the element type, and the family speaks for them instead.
+    """
+    if any(isinstance(value, Expression) for value in values):
+        return None
+    held = {type(value) for value in values}
+    if len(held) != 1:
+        return None
+    return cast("type[object]", GenericAlias(tuple, (held.pop(), Ellipsis)))
+
+
+__all__ = ("array_of",)

pyoq/query/binding.py

@@ -0,0 +1,52 @@
+"""Bound parameter accounting for query and write structures."""
+
+from __future__ import annotations
+
+from pyoq.query.nodes import (
+    AggregateNode,
+    BinaryNode,
+    BoundValueNode,
+    ExpressionNode,
+    ExtractNode,
+    FunctionNode,
+    RawNode,
+    UnaryNode,
+    VariadicNode,
+)
+from pyoq.query.select_nodes import ProjectionNode
+
+
+def bound_value_count(node: ExpressionNode) -> int:
+    direct = 1 if isinstance(node, BoundValueNode) else 0
+    return direct + sum(bound_value_count(child) for child in _children(node))
+
+
+def row_bound_value_count(row: tuple[ExpressionNode, ...]) -> int:
+    return sum(bound_value_count(value) for value in row)
+
+
+def projection_bound_value_count(projections: tuple[ProjectionNode, ...]) -> int:
+    return sum(bound_value_count(node.expression) for node in projections)
+
+
+def _children(node: ExpressionNode) -> tuple[ExpressionNode, ...]:
+    if isinstance(node, UnaryNode):
+        return (node.operand,)
+    if isinstance(node, BinaryNode):
+        return (node.left, node.right)
+    if isinstance(node, VariadicNode):
+        return node.operands
+    if isinstance(node, (FunctionNode, AggregateNode)):
+        return node.arguments
+    if isinstance(node, ExtractNode):
+        return (node.expression,)
+    if isinstance(node, RawNode):
+        return tuple(part for part in node.parts if not isinstance(part, str))
+    return ()
+
+
+__all__ = (
+    "bound_value_count",
+    "projection_bound_value_count",
+    "row_bound_value_count",
+)

pyoq/query/capabilities.py

@@ -0,0 +1,317 @@
+"""What each dialect can be asked for, one operation at a time.
+
+A broad name like JSON or windows says nothing about which questions a
+dialect will answer. This says it for each operation: written by the dialect
+itself, written by PyOQ out of what the dialect has, or refused before the
+statement reaches a server.
+
+This is the one place that claim is made. The documentation is written from
+it and a contract compiles every row against every dialect, so a claim here
+that is not true stops the test suite rather than reaching a caller.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from types import MappingProxyType
+
+from pyoq.config import DatabaseDialect
+from pyoq.query.nodes import ScalarFamily
+
+
+class Support(StrEnum):
+    """How a dialect answers one operation."""
+
+    NATIVE = "native"
+    """The dialect has it, and PyOQ writes what the dialect calls it."""
+
+    EMULATED = "emulated"
+    """The dialect lacks it, and PyOQ writes it out of what the dialect has."""
+
+    REJECTED = "rejected"
+    """No dialect support, refused while the query is compiled."""
+
+
+class Operation(StrEnum):
+    """One thing a caller can ask for, named at the grain support is decided."""
+
+    WINDOW_ROW_NUMBER = "window: row number"
+    WINDOW_RANK = "window: rank"
+    WINDOW_DENSE_RANK = "window: dense rank"
+    WINDOW_PERCENT_RANK = "window: percent rank"
+    WINDOW_CUME_DIST = "window: cumulative distribution"
+    WINDOW_NTILE = "window: ntile"
+    WINDOW_LAG = "window: lag"
+    WINDOW_LEAD = "window: lead"
+    WINDOW_FIRST_VALUE = "window: first value"
+    WINDOW_LAST_VALUE = "window: last value"
+    WINDOW_NTH_VALUE = "window: nth value"
+    WINDOW_AGGREGATE = "window: an aggregate over a window"
+    WINDOW_PARTITION = "window: partition by"
+    WINDOW_ORDER = "window: order by"
+    WINDOW_FRAME_ROWS = "window frame: rows"
+    WINDOW_FRAME_RANGE = "window frame: range"
+    WINDOW_FRAME_GROUPS = "window frame: groups"
+    WINDOW_FRAME_EXCLUDE = "window frame: exclude"
+    WINDOW_NAMED = "window: declared by name"
+
+    JSON_VALUE = "json: read a value"
+    JSON_TEXT = "json: read text"
+    JSON_LENGTH = "json: how long an array is"
+    JSON_EXISTS = "json: whether a path is there"
+    JSON_CONTAINS = "json: whether it holds a value"
+    JSON_SET = "json: set"
+    JSON_INSERT = "json: insert"
+    JSON_REPLACE = "json: replace"
+    JSON_MERGE = "json: merge all the way down"
+    JSON_CONCAT = "json: write over members, one level"
+    JSON_REMOVE = "json: remove"
+    JSON_OBJECT = "json: build an object"
+    JSON_ARRAY = "json: build an array"
+    JSON_KEYS = "json: name the members"
+    JSON_AGG = "json: gather rows into an array"
+    JSON_OBJECT_AGG = "json: gather rows into an object"
+    JSON_ELEMENTS = "json: read an array as rows"
+
+    ARRAY_HAS = "array: holds a value"
+    ARRAY_LACKS = "array: holds a value nowhere"
+    ARRAY_CONTAINS_ALL = "array: holds every value"
+    ARRAY_CONTAINED_BY = "array: is among"
+    ARRAY_OVERLAPS = "array: shares a value"
+    ARRAY_APPEND = "array: append"
+    ARRAY_PREPEND = "array: prepend"
+    ARRAY_CONCAT = "array: concatenate"
+    ARRAY_REMOVE = "array: without a value"
+    ARRAY_REPLACE = "array: replace a value"
+    ARRAY_ELEMENT = "array: one element"
+    ARRAY_LENGTH = "array: how many elements"
+    ARRAY_LENGTH_ALONG = "array: how many along a dimension"
+    ARRAY_DIMENSIONS = "array: how many dimensions"
+    ARRAY_CONSTRUCT = "array: built from values"
+
+    LOCK_FOR_UPDATE = "lock: for update"
+    LOCK_FOR_SHARE = "lock: for share"
+    LOCK_NOWAIT = "lock: fail rather than wait"
+    LOCK_SKIP_LOCKED = "lock: skip what is locked"
+    LOCK_OF_TABLES = "lock: named tables"
+    LOCK_OF_FIELDS = "lock: named fields"
+
+    QUERY_LATERAL = "query: lateral source"
+    QUERY_RECURSIVE = "query: recursive common table"
+    QUERY_ROW_VALUE = "query: row value"
+    QUERY_CAST = "query: cast"
+    QUERY_NULL_ORDERING = "query: nulls first or last"
+    QUERY_RIGHT_JOIN = "query: right join"
+    QUERY_FULL_JOIN = "query: full join"
+
+    ROUTINE_PROCEDURE = "routine: run a stored procedure"
+    ROUTINE_FUNCTION = "routine: ask a function by name"
+    ROUTINE_MANY_RESULT_SETS = "routine: more than one result set"
+
+
+_P = DatabaseDialect.POSTGRES
+_M = DatabaseDialect.MYSQL
+_S = DatabaseDialect.SQLITE
+
+_N = Support.NATIVE
+_E = Support.EMULATED
+_R = Support.REJECTED
+
+
+@dataclass(frozen=True, slots=True)
+class OperationSupport:
+    """One operation: what each dialect does, what it reads back, what runs it.
+
+    ``reads_back_as`` is the kind of value the operation answers with, which
+    is what decides how a driver's answer is read back. It is none where the
+    operation answers with rows rather than with a value.
+
+    ``evidence`` names the dialect-neutral contract that executes it against
+    every server that claims it, so a row points at the run that proves it
+    rather than at a compiled string.
+    """
+
+    dialects: Mapping[DatabaseDialect, Support]
+    reads_back_as: ScalarFamily | None
+    evidence: str
+
+
+def _row(
+    postgres: Support,
+    mysql: Support,
+    sqlite: Support,
+    reads_back_as: ScalarFamily | None,
+    evidence: str,
+) -> OperationSupport:
+    return OperationSupport(
+        MappingProxyType({_P: postgres, _M: mysql, _S: sqlite}),
+        reads_back_as,
+        evidence,
+    )
+
+
+SUPPORT: Mapping[Operation, OperationSupport] = MappingProxyType(
+    {
+        Operation.WINDOW_ROW_NUMBER: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_RANK: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_DENSE_RANK: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_PERCENT_RANK: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_CUME_DIST: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_NTILE: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_LAG: _row(_N, _N, _N, ScalarFamily.NUMERIC, "window_contract"),
+        Operation.WINDOW_LEAD: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_FIRST_VALUE: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_LAST_VALUE: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_NTH_VALUE: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_AGGREGATE: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_PARTITION: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_ORDER: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_FRAME_ROWS: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_FRAME_RANGE: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_FRAME_GROUPS: _row(
+            _N, _R, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_FRAME_EXCLUDE: _row(
+            _N, _R, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.WINDOW_NAMED: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "window_contract"
+        ),
+        Operation.JSON_VALUE: _row(_N, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_TEXT: _row(_N, _N, _N, ScalarFamily.STRING, "json_contract"),
+        Operation.JSON_LENGTH: _row(_N, _N, _N, ScalarFamily.NUMERIC, "json_contract"),
+        Operation.JSON_EXISTS: _row(_N, _N, _N, ScalarFamily.BOOLEAN, "json_contract"),
+        Operation.JSON_CONTAINS: _row(
+            _N, _N, _R, ScalarFamily.BOOLEAN, "json_contract"
+        ),
+        Operation.JSON_SET: _row(_N, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_INSERT: _row(_E, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_REPLACE: _row(_N, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_MERGE: _row(_R, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_CONCAT: _row(_N, _R, _R, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_REMOVE: _row(_N, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_OBJECT: _row(_N, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_ARRAY: _row(_N, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_KEYS: _row(_E, _N, _E, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_AGG: _row(_N, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_OBJECT_AGG: _row(_N, _N, _N, ScalarFamily.JSON, "json_contract"),
+        Operation.JSON_ELEMENTS: _row(_N, _N, _N, ScalarFamily.STRING, "json_contract"),
+        Operation.ARRAY_HAS: _row(_N, _R, _R, ScalarFamily.BOOLEAN, "array_contract"),
+        Operation.ARRAY_LACKS: _row(_N, _R, _R, ScalarFamily.BOOLEAN, "array_contract"),
+        Operation.ARRAY_CONTAINS_ALL: _row(
+            _N, _R, _R, ScalarFamily.BOOLEAN, "array_contract"
+        ),
+        Operation.ARRAY_CONTAINED_BY: _row(
+            _N, _R, _R, ScalarFamily.BOOLEAN, "array_contract"
+        ),
+        Operation.ARRAY_OVERLAPS: _row(
+            _N, _R, _R, ScalarFamily.BOOLEAN, "array_contract"
+        ),
+        Operation.ARRAY_APPEND: _row(_N, _R, _R, ScalarFamily.OTHER, "array_contract"),
+        Operation.ARRAY_PREPEND: _row(_N, _R, _R, ScalarFamily.OTHER, "array_contract"),
+        Operation.ARRAY_CONCAT: _row(_N, _R, _R, ScalarFamily.OTHER, "array_contract"),
+        Operation.ARRAY_REMOVE: _row(_N, _R, _R, ScalarFamily.OTHER, "array_contract"),
+        Operation.ARRAY_REPLACE: _row(_N, _R, _R, ScalarFamily.OTHER, "array_contract"),
+        Operation.ARRAY_ELEMENT: _row(_N, _R, _R, ScalarFamily.OTHER, "array_contract"),
+        Operation.ARRAY_LENGTH: _row(
+            _N, _R, _R, ScalarFamily.NUMERIC, "array_contract"
+        ),
+        Operation.ARRAY_LENGTH_ALONG: _row(
+            _N, _R, _R, ScalarFamily.NUMERIC, "array_contract"
+        ),
+        Operation.ARRAY_DIMENSIONS: _row(
+            _N, _R, _R, ScalarFamily.NUMERIC, "array_contract"
+        ),
+        Operation.ARRAY_CONSTRUCT: _row(
+            _N, _R, _R, ScalarFamily.OTHER, "array_contract"
+        ),
+        Operation.LOCK_FOR_UPDATE: _row(
+            _N, _N, _R, ScalarFamily.NUMERIC, "locking_contract"
+        ),
+        Operation.LOCK_FOR_SHARE: _row(
+            _N, _N, _R, ScalarFamily.NUMERIC, "locking_contract"
+        ),
+        Operation.LOCK_NOWAIT: _row(
+            _N, _N, _R, ScalarFamily.NUMERIC, "locking_contract"
+        ),
+        Operation.LOCK_SKIP_LOCKED: _row(
+            _N, _N, _R, ScalarFamily.NUMERIC, "locking_contract"
+        ),
+        Operation.LOCK_OF_TABLES: _row(
+            _N, _N, _R, ScalarFamily.NUMERIC, "locking_contract"
+        ),
+        Operation.LOCK_OF_FIELDS: _row(
+            _N, _N, _R, ScalarFamily.NUMERIC, "locking_contract"
+        ),
+        Operation.QUERY_LATERAL: _row(
+            _N, _N, _R, ScalarFamily.NUMERIC, "lateral_contract"
+        ),
+        Operation.QUERY_RECURSIVE: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "recursion_contract"
+        ),
+        Operation.QUERY_ROW_VALUE: _row(
+            _N, _N, _N, ScalarFamily.BOOLEAN, "row_value_contract"
+        ),
+        Operation.QUERY_CAST: _row(_N, _N, _N, ScalarFamily.STRING, "cast_contract"),
+        Operation.QUERY_NULL_ORDERING: _row(
+            _N, _E, _N, ScalarFamily.NUMERIC, "null_order_contract"
+        ),
+        Operation.QUERY_RIGHT_JOIN: _row(
+            _N, _N, _R, ScalarFamily.NUMERIC, "joined_contract"
+        ),
+        Operation.QUERY_FULL_JOIN: _row(
+            _N, _R, _R, ScalarFamily.NUMERIC, "joined_contract"
+        ),
+        Operation.ROUTINE_PROCEDURE: _row(_N, _N, _R, None, "routine_contract"),
+        Operation.ROUTINE_FUNCTION: _row(
+            _N, _N, _N, ScalarFamily.NUMERIC, "routine_contract"
+        ),
+        Operation.ROUTINE_MANY_RESULT_SETS: _row(_R, _R, _R, None, "routine_contract"),
+    }
+)
+"""Every operation, and how each dialect answers it.
+
+Measured against running servers rather than read from documentation. A row
+that says rejected is refused while the query is compiled, so a caller finds
+out while writing rather than in production.
+"""
+
+
+def support_for(operation: Operation, dialect: DatabaseDialect, /) -> Support:
+    """How that dialect answers that operation."""
+    return SUPPORT[operation].dialects[dialect]
+
+
+__all__ = ("SUPPORT", "Operation", "OperationSupport", "Support", "support_for")

pyoq/query/casts.py

@@ -0,0 +1,73 @@
+"""Asking the database for a value as another type.
+
+A cast is the one computed expression that declares what it answers with, so
+it is also the one the row decoder can honour. The Python type given here
+decides three things at once: the SQL each dialect emits, the family the
+expression carries, and what reads the value back.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from typing import TypeVar
+from uuid import UUID
+
+from pyoq.query.expressions import ComputedExpression
+from pyoq.query.fields import family_for_type
+from pyoq.query.nodes import CastNode
+from pyoq.query.raw import NodeProvider
+from pyoq.schema.models import TypeKind
+
+Target = TypeVar("Target")
+
+_TARGET_KINDS: dict[type[object], TypeKind] = {
+    bool: TypeKind.BOOLEAN,
+    int: TypeKind.INTEGER,
+    float: TypeKind.DOUBLE,
+    Decimal: TypeKind.DECIMAL,
+    str: TypeKind.STRING,
+    bytes: TypeKind.BINARY,
+    date: TypeKind.DATE,
+    time: TypeKind.TIME,
+    datetime: TypeKind.DATETIME,
+    timedelta: TypeKind.INTERVAL,
+    UUID: TypeKind.UUID,
+    dict: TypeKind.JSON,
+    list: TypeKind.JSON,
+}
+"""The database type each Python type asks for, which a dialect then names."""
+
+
+def cast(
+    expression: NodeProvider,
+    target: type[Target],
+    /,
+) -> ComputedExpression[Target]:
+    """`expression` as `target`, computed by the database.
+
+    A target no database type answers to is refused here rather than at
+    compilation, so it is reported where it was written.
+    """
+    kind_for_target(target)
+    return ComputedExpression[Target](
+        CastNode(expression.node, target), family_for_type(target)
+    )
+
+
+def kind_for_target(target: type[object], /) -> TypeKind:
+    """The database type a Python type asks for, or a refusal naming it.
+
+    `datetime` is settled first because it is also a `date`, and asking for
+    one is not asking for the other.
+    """
+    if target is datetime:
+        return TypeKind.DATETIME
+    for value_type, kind in _TARGET_KINDS.items():
+        if issubclass(target, value_type):
+            return kind
+    message = f"{getattr(target, '__name__', target)} is not a cast target"
+    raise TypeError(message)
+
+
+__all__ = ("cast", "kind_for_target")