pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/choices.py

@@ -0,0 +1,185 @@
+"""Choosing one value out of several.
+
+Every construct here answers the same question with different rules for what
+counts as an answer: the first branch whose condition holds, the first
+argument that is not null, the widest, the narrowest. The type of the answer
+is the type of what was offered, so a chosen value stays as usable as the
+column it came from.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, TypeVar, overload
+
+from pyoq.query.expressions import (
+    ComputedExpression,
+    Expression,
+    family_for_value,
+    operand,
+    require_boolean,
+)
+from pyoq.query.nodes import CaseNode, FunctionName, FunctionNode, ScalarFamily
+
+if TYPE_CHECKING:
+    from pyoq.query.nodes import ExpressionNode
+
+Value = TypeVar("Value")
+
+
+class CaseBuilder:
+    """A case with no branches yet, which is not a value until it has one."""
+
+    __slots__ = ()
+
+    @overload
+    def when(
+        self,
+        condition: Expression[bool],
+        result: Expression[Value],
+        /,
+    ) -> CaseBranches[Value]: ...
+
+    @overload
+    def when(
+        self,
+        condition: Expression[bool],
+        result: Value,
+        /,
+    ) -> CaseBranches[Value]: ...
+
+    def when(
+        self,
+        condition: Expression[bool],
+        result: Expression[Value] | Value,
+        /,
+    ) -> CaseBranches[Value]:
+        require_boolean(condition, "case branch")
+        family = _family_of(result)
+        return CaseBranches(((condition.node, operand(result, family)),), family)
+
+
+class CaseBranches(Generic[Value]):
+    """Branches gathered so far, with the type the whole case will answer."""
+
+    __slots__ = ("_branches", "_family")
+
+    def __init__(
+        self,
+        branches: tuple[tuple[ExpressionNode, ExpressionNode], ...],
+        family: ScalarFamily,
+    ) -> None:
+        self._branches = branches
+        self._family = family
+
+    def when(
+        self,
+        condition: Expression[bool],
+        result: Expression[Value] | Value,
+        /,
+    ) -> CaseBranches[Value]:
+        require_boolean(condition, "case branch")
+        branch = (condition.node, operand(result, self._family))
+        return CaseBranches((*self._branches, branch), self._family)
+
+    def otherwise(
+        self,
+        result: Expression[Value] | Value,
+        /,
+    ) -> ComputedExpression[Value]:
+        """The value for rows no branch claimed, which makes the case total."""
+        node = CaseNode(self._branches, operand(result, self._family))
+        return ComputedExpression[Value](node, self._family)
+
+    def end(self) -> ComputedExpression[Value | None]:
+        """Close without an else, so unclaimed rows answer null."""
+        return ComputedExpression[Value | None](CaseNode(self._branches), self._family)
+
+
+def case() -> CaseBuilder:
+    """Start a case, whose type is fixed by the result of its first branch."""
+    return CaseBuilder()
+
+
+@overload
+def coalesce(
+    first: Expression[Value | None],
+    fallback: Value,
+    /,
+) -> ComputedExpression[Value]: ...
+
+
+@overload
+def coalesce(
+    first: Expression[Value],
+    /,
+    *rest: Expression[Value] | Value,
+) -> ComputedExpression[Value]: ...
+
+
+def coalesce(
+    first: Expression[Value] | Expression[Value | None],
+    /,
+    *rest: object,
+) -> ComputedExpression[Value]:
+    """The first argument that is not null."""
+    return _choosing(FunctionName.COALESCE, first, rest, least_arguments=2)
+
+
+def nullif(
+    first: Expression[Value],
+    other: Expression[Value] | Value,
+    /,
+) -> ComputedExpression[Value | None]:
+    """The first argument, unless it equals the second, in which case null."""
+    chosen = _choosing(FunctionName.NULLIF, first, (other,), least_arguments=2)
+    return ComputedExpression[Value | None](chosen.node, chosen.family)
+
+
+def greatest(
+    first: Expression[Value],
+    /,
+    *rest: Expression[Value] | Value,
+) -> ComputedExpression[Value]:
+    """The widest of its arguments."""
+    return _choosing(FunctionName.GREATEST, first, rest, least_arguments=2)
+
+
+def least(
+    first: Expression[Value],
+    /,
+    *rest: Expression[Value] | Value,
+) -> ComputedExpression[Value]:
+    """The narrowest of its arguments."""
+    return _choosing(FunctionName.LEAST, first, rest, least_arguments=2)
+
+
+def _choosing(
+    name: FunctionName,
+    first: Expression[Value] | Expression[Value | None],
+    rest: tuple[object, ...],
+    *,
+    least_arguments: int,
+) -> ComputedExpression[Value]:
+    if len(rest) + 1 < least_arguments:
+        message = f"{name.value} needs at least {least_arguments} arguments"
+        raise TypeError(message)
+    family = first.family
+    arguments = (first.node, *(operand(value, family) for value in rest))
+    return ComputedExpression[Value](FunctionNode(name, arguments), family)
+
+
+def _family_of(value: object) -> ScalarFamily:
+    if isinstance(value, Expression):
+        return value.family
+    return family_for_value(value)
+
+
+__all__ = (
+    "CaseBranches",
+    "CaseBuilder",
+    "case",
+    "coalesce",
+    "greatest",
+    "least",
+    "nullif",
+)

pyoq/query/decoding.py

@@ -0,0 +1,360 @@
+"""Giving a column back as the type it was declared to hold.
+
+A driver answers with what its own protocol carries, which is not always what a
+column was declared to be: SQLite hands back a float for a decimal and a string
+for a date. A descriptor that says `Decimal` and yields a float is a promise the
+runtime does not keep, and money is the usual casualty.
+
+The declared type travels with the column, so the row can be given back as the
+row was described. A column with no declared type is left exactly as the driver
+answered.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal, InvalidOperation
+from enum import Enum
+from typing import TYPE_CHECKING, cast, get_origin
+from uuid import UUID
+
+from pyoq.errors import QueryExecutionError
+from pyoq.query.nodes import FieldNode, ScalarFamily
+from pyoq.query.results import result_descriptor
+from pyoq.query.select_nodes import SelectNode, SetNode
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+from pyoq.query.select_nodes import ProjectionNode
+
+_SECONDS = "seconds"
+_ONE_DAY = timedelta(days=1)
+_MILLION = 1_000_000
+_MINUTE = 60
+
+
+def projected_types(node: object, /) -> tuple[type[object] | None, ...]:
+    """The type each projected column was declared to hold, in order.
+
+    A set operation takes its columns from the first query in it, which is where
+    a database takes their names from too.
+    """
+    projections = _projections(node)
+    return tuple(_declared(projection) for projection in projections)
+
+
+def decode_rows(
+    rows: Sequence[object],
+    types: tuple[type[object] | None, ...],
+    /,
+) -> list[object]:
+    """Every row given back as it was described.
+
+    A statement whose columns declared nothing is handed straight back, so a
+    caller that never said what it wanted pays nothing for the question.
+    """
+    if not types or not any(types):
+        return list(rows)
+    return [_decode_row(row, types) for row in rows]
+
+
+def decode_row(row: object, types: tuple[type[object] | None, ...], /) -> object:
+    """One row given back as it was described."""
+    if not types or not any(types):
+        return row
+    return _decode_row(row, types)
+
+
+def decode_value(value: object, target: type[object] | None, /) -> object:
+    """One value, as the type it was declared to hold."""
+    if target is None or value is None or type(value) is target:
+        return value
+    decoder = _decoder(target)
+    if decoder is None:
+        return value
+    try:
+        return decoder(value)
+    except (ArithmeticError, TypeError, ValueError, InvalidOperation) as error:
+        message = (
+            f"a {type(value).__name__} came back for a column declared "
+            f"{target.__name__}, and could not be read as one"
+        )
+        raise QueryExecutionError(message) from error
+
+
+def _decode_row(
+    row: object,
+    types: tuple[type[object] | None, ...],
+) -> object:
+    """A row of the width it was described as, decoded column by column.
+
+    Both callers above have already turned away a statement that named no
+    types. A statement that projected a different number of columns than the
+    database answered with is
+    refused, because a star widens with the table and reading the old columns
+    out of a wider row would answer with values from the wrong ones.
+    """
+    if not isinstance(row, tuple):
+        return row
+    # A driver answers with a tuple of driver values, and what those are is the
+    # question this is here to settle, so there is nothing narrower to say.
+    values = cast("tuple[object, ...]", row)
+    if len(values) != len(types):
+        message = (
+            f"the database answered with {len(values)} columns where the "
+            f"statement projected {len(types)}; a generated package that no "
+            f"longer matches its schema reads a row by the wrong columns, so "
+            f"regenerate it"
+        )
+        raise QueryExecutionError(message)
+    return _decoded(values, types)
+
+
+def _decoded(
+    values: tuple[object, ...],
+    types: tuple[type[object] | None, ...],
+) -> tuple[object, ...]:
+    decoded: list[object] = []
+    for index, target in enumerate(types):
+        decoded.append(decode_value(values[index], target))
+    return tuple(decoded)
+
+
+def _projections(node: object) -> tuple[ProjectionNode, ...]:
+    while isinstance(node, SetNode):
+        node = node.left
+    if isinstance(node, SelectNode):
+        return node.projections
+    returning: tuple[ProjectionNode, ...] | None = getattr(node, "returning", None)
+    return returning if isinstance(returning, tuple) else ()
+
+
+def _declared(projection: ProjectionNode) -> type[object] | None:
+    """What reads this projection back, for the two that say what they hold.
+
+    A column says what it holds, and an expression that carries a value
+    through says whatever that value was declared to be. An expression that
+    computes something new says nothing, so it is read back as its family
+    where that family names one Python type: a predicate is a boolean whether
+    a driver answers with one or with a one, and text is text whether a driver
+    kept it as text.
+    """
+    expression = projection.expression
+    answers = result_descriptor(expression)
+    if isinstance(expression, FieldNode):
+        return _decodable(answers.declared, answers.family)
+    if answers.declared is not None and _decoder(answers.declared) is not None:
+        return answers.declared
+    return _COMPUTED_TYPES.get(answers.family)
+
+
+def _decodable(
+    declared: type[object] | None,
+    family: ScalarFamily,
+) -> type[object] | None:
+    """What reads a value back, which its declared type may not name.
+
+    A column holding any JSON is declared as a union of everything JSON can
+    be, and a union is not a type a decoder can be found under. The family
+    says JSON on its own, so it answers where the declared type cannot.
+    """
+    if declared is not None and _decoder(declared) is not None:
+        return declared
+    return _FAMILY_TYPES.get(family)
+
+
+def _decoder(target: type[object]) -> Callable[[object], object] | None:
+    """What reads a value back as this type, if anything does.
+
+    A column can be declared as a parameterised type, and what decodes one is
+    decided by what it is, not by what it holds. A generated enumeration is
+    its own decoder, because calling it is what turns a stored value into a
+    member of it.
+    """
+    origin = get_origin(target) or target
+    decoder = _DECODERS.get(origin)
+    if decoder is not None:
+        return decoder
+    if isinstance(origin, type) and issubclass(origin, Enum):
+        return origin
+    return None
+
+
+def _to_decimal(value: object) -> Decimal:
+    if isinstance(value, float):
+        return Decimal(str(value))
+    if isinstance(value, (int, str)):
+        return Decimal(value)
+    message = f"cannot read {type(value).__name__} as a decimal"
+    raise TypeError(message)
+
+
+def _to_datetime(value: object) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str):
+        return datetime.fromisoformat(value)
+    message = f"cannot read {type(value).__name__} as a datetime"
+    raise TypeError(message)
+
+
+def _to_date(value: object) -> date:
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    if isinstance(value, str):
+        return date.fromisoformat(value)
+    message = f"cannot read {type(value).__name__} as a date"
+    raise TypeError(message)
+
+
+def _to_time(value: object) -> time:
+    """MySQL's `TIME` is a signed duration, and its driver answers with one.
+
+    A duration inside a single forward day names a clock time and is read as
+    one. Anything outside that does not, so it is refused rather than folded
+    into a time it does not mean.
+    """
+    if isinstance(value, time):
+        return value
+    if isinstance(value, timedelta):
+        return _clock_time(value)
+    if isinstance(value, str):
+        return time.fromisoformat(value)
+    message = f"cannot read {type(value).__name__} as a time"
+    raise TypeError(message)
+
+
+def _clock_time(value: timedelta) -> time:
+    if not timedelta(0) <= value < _ONE_DAY:
+        message = f"{value} is not a time of day"
+        raise ValueError(message)
+    seconds, microseconds = divmod(value // timedelta(microseconds=1), _MILLION)
+    minutes, second = divmod(seconds, _MINUTE)
+    hour, minute = divmod(minutes, _MINUTE)
+    return time(hour, minute, second, microseconds)
+
+
+def _to_timedelta(value: object) -> timedelta:
+    if isinstance(value, timedelta):
+        return value
+    if isinstance(value, (int, float)):
+        return timedelta(**{_SECONDS: value})
+    message = f"cannot read {type(value).__name__} as an interval"
+    raise TypeError(message)
+
+
+def _to_uuid(value: object) -> UUID:
+    if isinstance(value, UUID):
+        return value
+    if isinstance(value, str):
+        return UUID(value)
+    if isinstance(value, bytes):
+        return UUID(bytes=value)
+    message = f"cannot read {type(value).__name__} as a uuid"
+    raise TypeError(message)
+
+
+def _to_bytes(value: object) -> bytes:
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value)
+    if isinstance(value, memoryview):
+        return value.tobytes()
+    if isinstance(value, str):
+        return value.encode()
+    message = f"cannot read {type(value).__name__} as bytes"
+    raise TypeError(message)
+
+
+def _to_bool(value: object) -> bool:
+    if isinstance(value, (bool, int)):
+        return bool(value)
+    message = f"cannot read {type(value).__name__} as a boolean"
+    raise TypeError(message)
+
+
+def _to_int(value: object) -> int:
+    if isinstance(value, (int, float, str)):
+        return int(value)
+    message = f"cannot read {type(value).__name__} as an integer"
+    raise TypeError(message)
+
+
+def _to_float(value: object) -> float:
+    if isinstance(value, (int, float, str, Decimal)):
+        return float(value)
+    message = f"cannot read {type(value).__name__} as a float"
+    raise TypeError(message)
+
+
+def _to_text(value: object) -> str:
+    """A driver that answers with bytes for a text column says which encoding."""
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value).decode()
+    if isinstance(value, memoryview):
+        return value.tobytes().decode()
+    return str(value)
+
+
+def _to_tuple(value: object) -> tuple[object, ...]:
+    """An array column is declared as a tuple, and a driver answers with a list."""
+    if isinstance(value, tuple):
+        return cast("tuple[object, ...]", value)
+    if isinstance(value, list):
+        return tuple(cast("list[object]", value))
+    message = f"cannot read {type(value).__name__} as an array"
+    raise TypeError(message)
+
+
+def _to_json(value: object) -> object:
+    """A driver that has no JSON of its own answers with the text of it."""
+    if isinstance(value, (str, bytes, bytearray)):
+        return json.loads(value)
+    return value
+
+
+_FAMILY_TYPES: dict[ScalarFamily, type[object]] = {ScalarFamily.JSON: dict}
+"""The type that reads a column back, where no declared type can name one.
+
+A column that declared nothing is left as it came, because a caller that
+never said what it wanted pays nothing for the question. Only JSON is here,
+because a column holding any JSON is declared as a union no decoder is found
+under.
+"""
+
+_COMPUTED_TYPES: dict[ScalarFamily, type[object]] = {
+    ScalarFamily.BOOLEAN: bool,
+    ScalarFamily.STRING: str,
+    ScalarFamily.JSON: dict,
+}
+"""What reads an expression back, which has no declared type to consult.
+
+A predicate is a boolean whether a driver answers with one or with a one, and
+text is text whether a driver kept it as text or handed back the number it
+looked like. A numeric family names three Python types, so it is absent: what
+a driver answered with is the only thing that says which.
+"""
+
+_DECODERS: dict[type[object], Callable[[object], object]] = {
+    Decimal: _to_decimal,
+    datetime: _to_datetime,
+    date: _to_date,
+    time: _to_time,
+    timedelta: _to_timedelta,
+    UUID: _to_uuid,
+    bytes: _to_bytes,
+    bool: _to_bool,
+    int: _to_int,
+    float: _to_float,
+    str: _to_text,
+    list: _to_json,
+    dict: _to_json,
+    tuple: _to_tuple,
+}
+
+
+__all__ = ("decode_row", "decode_rows", "decode_value", "projected_types")

pyoq/query/documents.py

@@ -0,0 +1,56 @@
+"""Building a JSON value out of the values around it.
+
+Reading inside a document is asked of the document, so those questions are
+methods on the value itself. Building one starts from values that are not
+documents yet, so it starts here.
+
+Every dialect writes these under its own name, and each one carries the name
+it uses, so a document built here is the same document on all of them.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyoq.query.expressions import (
+    ComputedExpression,
+    family_for_value,
+    operand,
+)
+from pyoq.query.nodes import JsonBuild, JsonBuildNode, ScalarFamily
+from pyoq.schema.models import JsonValue
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from pyoq.query.nodes import ExpressionNode
+
+
+def json_object(members: Mapping[str, object], /) -> ComputedExpression[JsonValue]:
+    """A JSON object with these members, in the order they are written.
+
+    A mapping rather than alternating arguments, because a member and its
+    value belong together and nothing else keeps them paired.
+    """
+    arguments: list[ExpressionNode] = []
+    for name, value in members.items():
+        arguments.append(operand(name, ScalarFamily.STRING))
+        arguments.append(_value(value))
+    return ComputedExpression[JsonValue](
+        JsonBuildNode(JsonBuild.OBJECT, tuple(arguments)), ScalarFamily.JSON
+    )
+
+
+def json_array(*values: object) -> ComputedExpression[JsonValue]:
+    """A JSON array holding these values, in the order they are written."""
+    return ComputedExpression[JsonValue](
+        JsonBuildNode(JsonBuild.ARRAY, tuple(_value(value) for value in values)),
+        ScalarFamily.JSON,
+    )
+
+
+def _value(value: object) -> ExpressionNode:
+    return operand(value, family_for_value(value))
+
+
+__all__ = ("json_array", "json_object")

pyoq/query/execution/__init__.py

@@ -0,0 +1,63 @@
+"""Database-neutral execution results."""
+
+from pyoq.query.execution.batch import (
+    BulkChunk,
+    BulkPlan,
+    BulkResult,
+    OperationBudget,
+    WriteProvider,
+)
+from pyoq.query.execution.binding_style import ParameterStyle
+from pyoq.query.execution.compilation import CompiledQuery
+from pyoq.query.execution.context import CompilationContext
+from pyoq.query.execution.control import CancellationToken, ExecutionControl
+from pyoq.query.execution.operations import (
+    DatabaseCursor,
+    QueryOperations,
+    fetch_all,
+)
+from pyoq.query.execution.planning import BulkPlanner
+from pyoq.query.execution.pooling import (
+    ConnectionFactory,
+    ConnectionLease,
+    ConnectionPool,
+    PoolPolicy,
+    PoolStats,
+)
+from pyoq.query.execution.results import ExecuteResult, StatementKind
+from pyoq.query.execution.streaming import (
+    CursorSession,
+    RowStream,
+    StreamPolicy,
+    StreamResource,
+)
+from pyoq.query.execution.transactions import TransactionState
+
+__all__ = (
+    "BulkChunk",
+    "BulkPlan",
+    "BulkPlanner",
+    "BulkResult",
+    "CancellationToken",
+    "CompilationContext",
+    "CompiledQuery",
+    "ConnectionFactory",
+    "ConnectionLease",
+    "ConnectionPool",
+    "CursorSession",
+    "DatabaseCursor",
+    "ExecuteResult",
+    "ExecutionControl",
+    "OperationBudget",
+    "ParameterStyle",
+    "PoolPolicy",
+    "PoolStats",
+    "QueryOperations",
+    "RowStream",
+    "StatementKind",
+    "StreamPolicy",
+    "StreamResource",
+    "TransactionState",
+    "WriteProvider",
+    "fetch_all",
+)

pyoq/query/execution/aio/__init__.py

@@ -0,0 +1,31 @@
+"""Dialect-neutral asynchronous execution."""
+
+from pyoq.query.execution.aio.operations import (
+    AsyncDatabaseCursor,
+    AsyncQueryOperations,
+    fetch_all,
+)
+from pyoq.query.execution.aio.pooling import (
+    AsyncConnectionFactory,
+    AsyncConnectionLease,
+    AsyncConnectionPool,
+)
+from pyoq.query.execution.aio.streaming import (
+    AsyncCursorSession,
+    AsyncRowStream,
+    AsyncStreamResource,
+)
+from pyoq.query.execution.aio.transactions import AsyncTransactionState
+
+__all__ = (
+    "AsyncConnectionFactory",
+    "AsyncConnectionLease",
+    "AsyncConnectionPool",
+    "AsyncCursorSession",
+    "AsyncDatabaseCursor",
+    "AsyncQueryOperations",
+    "AsyncRowStream",
+    "AsyncStreamResource",
+    "AsyncTransactionState",
+    "fetch_all",
+)