pyoq-sql 1.0.2__py3-none-any.whl

pyoq/dsl/aio/queries.py

@@ -0,0 +1,335 @@
+"""The asynchronous counterpart of a query bound to its database.
+
+Only the ending differs. A chain is built the same way and describes the same
+statement; the fetch at the end is awaited because the database is.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from pyoq.dsl.labels import labels_of
+from pyoq.dsl.result import Result, Row
+from pyoq.query.select import JoinStep, Query, SelectQuery, SemiJoinStep
+from pyoq.query.select_nodes import SelectNode, SetNode
+
+if TYPE_CHECKING:
+    from pyoq.descriptors import RelationshipDescriptor
+    from pyoq.query.execution.aio import AsyncQueryOperations
+    from pyoq.query.expressions import Expression
+    from pyoq.query.sources import CommonTable, SourceBase, TableLike
+    from pyoq.query.writes import ColumnReference
+
+ResultRow = TypeVar("ResultRow", bound=tuple[object, ...])
+Mapped = TypeVar("Mapped")
+ScalarValue = TypeVar("ScalarValue")
+
+
+class AsyncBoundQuery(Generic[ResultRow]):
+    """A query and the database it will run against."""
+
+    __slots__ = ("_operations", "_query")
+    _operations: AsyncQueryOperations
+    _query: Query[ResultRow]
+
+    def __init__(
+        self,
+        operations: AsyncQueryOperations,
+        query: Query[ResultRow],
+    ) -> None:
+        object.__setattr__(self, "_operations", operations)
+        object.__setattr__(self, "_query", query)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = f"{type(self).__name__} is immutable"
+        raise AttributeError(message, name, value)
+
+    @property
+    def query(self) -> Query[ResultRow]:
+        """The query on its own, which cannot reach a database."""
+        return self._query
+
+    def order_by(self, *terms: object) -> AsyncBoundQuery[ResultRow]:
+        return self._with(self._query.order_by(*terms))
+
+    def limit(self, value: int, /) -> AsyncBoundQuery[ResultRow]:
+        return self._with(self._query.limit(value))
+
+    def offset(self, value: int, /) -> AsyncBoundQuery[ResultRow]:
+        return self._with(self._query.offset(value))
+
+    def union(self, other: Query[ResultRow], /) -> AsyncBoundQuery[ResultRow]:
+        return self._with(self._query.union(other))
+
+    def union_all(self, other: Query[ResultRow], /) -> AsyncBoundQuery[ResultRow]:
+        return self._with(self._query.union_all(other))
+
+    def intersect(self, other: Query[ResultRow], /) -> AsyncBoundQuery[ResultRow]:
+        return self._with(self._query.intersect(other))
+
+    def except_(self, other: Query[ResultRow], /) -> AsyncBoundQuery[ResultRow]:
+        return self._with(self._query.except_(other))
+
+    async def fetch_all(self) -> Result[ResultRow]:
+        rows = tuple(await self._operations.many(self._query))
+        return Result(rows, _labels(self._query))
+
+    async def fetch_one(self) -> Row[ResultRow]:
+        """Exactly one row, because that is what the caller said to expect."""
+        return Row(await self._operations.one(self._query), _labels(self._query))
+
+    async def fetch_optional(self) -> Row[ResultRow] | None:
+        row = await self._operations.one_or_none(self._query)
+        return None if row is None else Row(row, _labels(self._query))
+
+    async def fetch_optional_into(
+        self,
+        factory: Callable[..., Mapped],
+        /,
+    ) -> Mapped | None:
+        """One row built by the caller's own type, or nothing.
+
+        The row and the many-row result both take a factory inline.
+        A row that may be missing had to be tested for first, which
+        is the one shape that could not be asked for in the chain.
+        """
+        row = await self.fetch_optional()
+        return None if row is None else row.into(factory)
+
+    async def fetch_value(
+        self: AsyncBoundQuery[tuple[ScalarValue]],
+        /,
+    ) -> ScalarValue:
+        """The single column of the single row.
+
+        Only a query that selected one column can answer this, which is why the
+        annotation says so rather than a check at run time.
+        """
+        return await self._operations.scalar(self._query)
+
+    def _with(self, query: Query[ResultRow]) -> AsyncBoundQuery[ResultRow]:
+        return AsyncBoundQuery(self._operations, query)
+
+
+class AsyncBoundSelect(AsyncBoundQuery[ResultRow], Generic[ResultRow]):
+    """A SELECT that knows its database, with the builder's own shape kept."""
+
+    __slots__ = ()
+
+    @property
+    def query(self) -> SelectQuery[ResultRow]:
+        return _as_select(self._query)
+
+    def distinct(self, enabled: bool = True, /) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.distinct(enabled))
+
+    def from_(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.from_(source))
+
+    def join(self, source: SourceBase | TableLike, /) -> AsyncBoundJoinStep[ResultRow]:
+        """An inner join, qualified by the clause that follows it."""
+        return AsyncBoundJoinStep(self._select, self.query.join(source))
+
+    def inner_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundJoinStep[ResultRow]:
+        return AsyncBoundJoinStep(self._select, self.query.inner_join(source))
+
+    def left_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundJoinStep[ResultRow]:
+        return AsyncBoundJoinStep(self._select, self.query.left_join(source))
+
+    def right_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundJoinStep[ResultRow]:
+        return AsyncBoundJoinStep(self._select, self.query.right_join(source))
+
+    def full_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundJoinStep[ResultRow]:
+        return AsyncBoundJoinStep(self._select, self.query.full_join(source))
+
+    def semi_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundSemiJoinStep[ResultRow]:
+        """Rows that have a match, without bringing the match back."""
+        return AsyncBoundSemiJoinStep(self._select, self.query.semi_join(source))
+
+    def anti_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundSemiJoinStep[ResultRow]:
+        """Rows that have no match."""
+        return AsyncBoundSemiJoinStep(self._select, self.query.anti_join(source))
+
+    def cross_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.cross_join(source))
+
+    def natural_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.natural_join(source))
+
+    def natural_left_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.natural_left_join(source))
+
+    def natural_right_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.natural_right_join(source))
+
+    def natural_full_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.natural_full_join(source))
+
+    def where(
+        self,
+        condition: Expression[bool],
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.where(condition))
+
+    def group_by(self, *expressions: object) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.group_by(*expressions))
+
+    def having(
+        self,
+        condition: Expression[bool],
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.having(condition))
+
+    def with_(
+        self,
+        *common_tables: CommonTable[object],
+    ) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.with_(*common_tables))
+
+    def order_by(self, *terms: object) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.order_by(*terms))
+
+    def limit(self, value: int, /) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.limit(value))
+
+    def offset(self, value: int, /) -> AsyncBoundSelect[ResultRow]:
+        return self._select(self.query.offset(value))
+
+    def _select(
+        self,
+        query: SelectQuery[ResultRow],
+    ) -> AsyncBoundSelect[ResultRow]:
+        return AsyncBoundSelect(self._operations, query)
+
+
+def _as_select(query: Query[ResultRow]) -> SelectQuery[ResultRow]:
+    if not isinstance(query, SelectQuery):
+        message = "the query is no longer a SELECT"
+        raise TypeError(message)
+    return query
+
+
+def _labels(query: Query[ResultRow]) -> tuple[str | None, ...]:
+    """A set operation takes its names from the first query in it."""
+    select = _first_select(query.node)
+    return () if select is None else labels_of(select.projections)
+
+
+def _first_select(node: object) -> SelectNode | None:
+    while isinstance(node, SetNode):
+        node = node.left
+    return node if isinstance(node, SelectNode) else None
+
+
+class AsyncBoundJoinStep(Generic[ResultRow]):
+    """A bound join waiting to be told how the two tables line up."""
+
+    __slots__ = ("_bind", "_step")
+    _bind: Callable[[SelectQuery[ResultRow]], AsyncBoundSelect[ResultRow]]
+    _step: JoinStep[ResultRow]
+
+    def __init__(
+        self,
+        bind: Callable[[SelectQuery[ResultRow]], AsyncBoundSelect[ResultRow]],
+        step: JoinStep[ResultRow],
+    ) -> None:
+        object.__setattr__(self, "_bind", bind)
+        object.__setattr__(self, "_step", step)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = "join steps are immutable"
+        raise AttributeError(message, name, value)
+
+    def on(self, condition: Expression[bool], /) -> AsyncBoundSelect[ResultRow]:
+        """The predicate the rows are matched by."""
+        return self._bind(self._step.on(condition))
+
+    def using(self, *columns: str | ColumnReference) -> AsyncBoundSelect[ResultRow]:
+        """Matched on columns both tables name the same way."""
+        return self._bind(self._step.using(*columns))
+
+    def on_key(
+        self,
+        relation: RelationshipDescriptor[object, object],
+        /,
+    ) -> AsyncBoundSelect[ResultRow]:
+        """Matched on the foreign key the schema already declares."""
+        return self._bind(self._step.on_key(relation))
+
+
+class AsyncBoundSemiJoinStep(Generic[ResultRow]):
+    """A bound semi or anti join waiting for its predicate."""
+
+    __slots__ = ("_bind", "_step")
+    _bind: Callable[[SelectQuery[ResultRow]], AsyncBoundSelect[ResultRow]]
+    _step: SemiJoinStep[ResultRow]
+
+    def __init__(
+        self,
+        bind: Callable[[SelectQuery[ResultRow]], AsyncBoundSelect[ResultRow]],
+        step: SemiJoinStep[ResultRow],
+    ) -> None:
+        object.__setattr__(self, "_bind", bind)
+        object.__setattr__(self, "_step", step)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = "join steps are immutable"
+        raise AttributeError(message, name, value)
+
+    def on(self, condition: Expression[bool], /) -> AsyncBoundSelect[ResultRow]:
+        """The predicate a row is matched by."""
+        return self._bind(self._step.on(condition))
+
+
+__all__ = ("AsyncBoundQuery", "AsyncBoundSelect")

pyoq/dsl/aio/writes.py

@@ -0,0 +1,368 @@
+"""The asynchronous counterpart of a write bound to its database."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, TypeVar, TypeVarTuple, cast, overload
+
+from pyoq.dsl.labels import labels_of
+from pyoq.dsl.result import Result, Row
+from pyoq.query.write_nodes import WriteNode
+from pyoq.query.writes import (
+    ConflictUpdate,
+    DeleteStatement,
+    InsertStatement,
+    MutationStatement,
+    ReturningStatement,
+    UpdateStatement,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+    from pyoq.query.execution.aio import AsyncQueryOperations
+    from pyoq.query.expressions import Expression
+    from pyoq.query.writes import ColumnReference
+
+Values = TypeVarTuple("Values")
+Mutation = TypeVar("Mutation", bound=MutationStatement[WriteNode])
+ResultRow = TypeVar("ResultRow", bound=tuple[object, ...])
+Mapped = TypeVar("Mapped")
+ScalarValue = TypeVar("ScalarValue")
+Value1 = TypeVar("Value1")
+Value2 = TypeVar("Value2")
+Value3 = TypeVar("Value3")
+Value4 = TypeVar("Value4")
+Value5 = TypeVar("Value5")
+Value6 = TypeVar("Value6")
+Value7 = TypeVar("Value7")
+Value8 = TypeVar("Value8")
+AssignedValue = TypeVar("AssignedValue")
+
+
+class AsyncBoundReturning(Generic[ResultRow]):
+    """Rows a write handed back, read the way a query's rows are read."""
+
+    __slots__ = ("_operations", "_statement")
+    _operations: AsyncQueryOperations
+    _statement: ReturningStatement[ResultRow]
+
+    def __init__(
+        self,
+        operations: AsyncQueryOperations,
+        statement: ReturningStatement[ResultRow],
+    ) -> None:
+        object.__setattr__(self, "_operations", operations)
+        object.__setattr__(self, "_statement", statement)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = f"{type(self).__name__} is immutable"
+        raise AttributeError(message, name, value)
+
+    @property
+    def statement(self) -> ReturningStatement[ResultRow]:
+        return self._statement
+
+    async def fetch_all(self) -> Result[ResultRow]:
+        rows = tuple(await self._operations.many(self._statement))
+        return Result(rows, labels_of(self._statement.node.returning))
+
+    async def fetch_one(self) -> Row[ResultRow]:
+        """Exactly one row, because that is what the caller said to expect."""
+        return Row(
+            await self._operations.one(self._statement),
+            labels_of(self._statement.node.returning),
+        )
+
+    async def fetch_optional(self) -> Row[ResultRow] | None:
+        row = await self._operations.one_or_none(self._statement)
+        return (
+            None if row is None else Row(row, labels_of(self._statement.node.returning))
+        )
+
+    async def fetch_optional_into(
+        self,
+        factory: Callable[..., Mapped],
+        /,
+    ) -> Mapped | None:
+        """One row built by the caller's own type, or nothing.
+
+        The row and the many-row result both take a factory inline.
+        A row that may be missing had to be tested for first, which
+        is the one shape that could not be asked for in the chain.
+        """
+        row = await self.fetch_optional()
+        return None if row is None else row.into(factory)
+
+    async def fetch_value(
+        self: AsyncBoundReturning[tuple[ScalarValue]],
+        /,
+    ) -> ScalarValue:
+        return await self._operations.scalar(self._statement)
+
+
+class AsyncBoundMutation(Generic[Mutation]):
+    """What every bound write can do, whatever it is writing."""
+
+    __slots__ = ("_operations", "_statement")
+    _operations: AsyncQueryOperations
+    _statement: Mutation
+
+    def __init__(
+        self,
+        operations: AsyncQueryOperations,
+        statement: Mutation,
+    ) -> None:
+        object.__setattr__(self, "_operations", operations)
+        object.__setattr__(self, "_statement", statement)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = f"{type(self).__name__} is immutable"
+        raise AttributeError(message, name, value)
+
+    @property
+    def statement(self) -> Mutation:
+        """The statement on its own, which cannot reach a database."""
+        return self._statement
+
+    async def execute(self) -> int:
+        """How many rows the database says it wrote."""
+        written = await self._operations.execute(self._statement)
+        return written.rows_affected
+
+    def returning_all(self) -> AsyncBoundReturning[tuple[object, ...]]:
+        """Every column the table declares, without listing them."""
+        return AsyncBoundReturning(self._operations, self._statement.returning_all())
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        /,
+    ) -> AsyncBoundReturning[tuple[Value1]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        /,
+    ) -> AsyncBoundReturning[tuple[Value1, Value2]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        /,
+    ) -> AsyncBoundReturning[tuple[Value1, Value2, Value3]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        /,
+    ) -> AsyncBoundReturning[tuple[Value1, Value2, Value3, Value4]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        /,
+    ) -> AsyncBoundReturning[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],
+        /,
+    ) -> AsyncBoundReturning[tuple[Value1, Value2, Value3, Value4, Value5, Value6]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        value6: Expression[Value6],
+        value7: Expression[Value7],
+        /,
+    ) -> AsyncBoundReturning[
+        tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7]
+    ]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        value6: Expression[Value6],
+        value7: Expression[Value7],
+        value8: Expression[Value8],
+        /,
+    ) -> AsyncBoundReturning[
+        tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8]
+    ]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: object,
+        value2: object,
+        value3: object,
+        value4: object,
+        value5: object,
+        value6: object,
+        value7: object,
+        value8: object,
+        /,
+        *values: object,
+    ) -> AsyncBoundReturning[tuple[object, ...]]:
+        """Wider than the overloads above name, where the types stop.
+
+        A statement is still a statement past eight returned columns,
+        and matching no overload would take the whole chain down with
+        it rather than just the tuple.
+        """
+
+    def returning(  # type: ignore[misc]
+        self,
+        *values: object,
+    ) -> AsyncBoundReturning[tuple[object, ...]]:
+        # The builder declares typed overloads for callers; this is the one
+        # implementation behind them, reached variadically.
+        build = cast(
+            "Callable[..., ReturningStatement[tuple[object, ...]]]",
+            self._statement.returning,
+        )
+        return AsyncBoundReturning(self._operations, build(*values))
+
+
+class AsyncBoundInsert(
+    AsyncBoundMutation[InsertStatement[*Values]],
+    Generic[*Values],
+):
+    """An INSERT and the database it will run against."""
+
+    __slots__ = ()
+
+    def values(self, *values: *Values) -> AsyncBoundInsert[*Values]:
+        return AsyncBoundInsert(self._operations, self._statement.values(*values))
+
+    def values_many(self, rows: Iterable[object], /) -> AsyncBoundInsert[*Values]:
+        return AsyncBoundInsert(self._operations, self._statement.values_many(rows))
+
+    def on_conflict_do_nothing(
+        self,
+        *columns: ColumnReference,
+    ) -> AsyncBoundInsert[*Values]:
+        return AsyncBoundInsert(
+            self._operations,
+            self._statement.on_conflict_do_nothing(*columns),
+        )
+
+    def on_conflict_do_update(
+        self,
+        *columns: ColumnReference,
+    ) -> AsyncBoundConflictUpdate[*Values]:
+        return AsyncBoundConflictUpdate(
+            self._operations,
+            self._statement.on_conflict_do_update(*columns),
+        )
+
+
+class AsyncBoundConflictUpdate(
+    AsyncBoundMutation[ConflictUpdate[*Values]],
+    Generic[*Values],
+):
+    """The SET and WHERE that belong to a conflict clause."""
+
+    __slots__ = ()
+
+    def set(
+        self,
+        column: Expression[AssignedValue],
+        value: AssignedValue | Expression[AssignedValue],
+        /,
+    ) -> AsyncBoundConflictUpdate[*Values]:
+        return AsyncBoundConflictUpdate(
+            self._operations, self._statement.set(column, value)
+        )
+
+    def where(
+        self,
+        condition: Expression[bool],
+        /,
+    ) -> AsyncBoundConflictUpdate[*Values]:
+        return AsyncBoundConflictUpdate(
+            self._operations, self._statement.where(condition)
+        )
+
+
+class AsyncBoundUpdate(AsyncBoundMutation[UpdateStatement]):
+    """An UPDATE, which has to say which rows it means."""
+
+    __slots__ = ()
+
+    def set(
+        self,
+        column: Expression[AssignedValue],
+        value: AssignedValue | Expression[AssignedValue],
+        /,
+    ) -> AsyncBoundUpdate:
+        return AsyncBoundUpdate(self._operations, self._statement.set(column, value))
+
+    def set_values(
+        self,
+        values: object,
+        /,
+        *columns: ColumnReference,
+    ) -> AsyncBoundUpdate:
+        return AsyncBoundUpdate(
+            self._operations, self._statement.set_values(values, *columns)
+        )
+
+    def where(self, condition: Expression[bool], /) -> AsyncBoundUpdate:
+        return AsyncBoundUpdate(self._operations, self._statement.where(condition))
+
+    def all_rows(self) -> AsyncBoundUpdate:
+        return AsyncBoundUpdate(self._operations, self._statement.all_rows())
+
+
+class AsyncBoundDelete(AsyncBoundMutation[DeleteStatement]):
+    """A DELETE, which has to say which rows it means."""
+
+    __slots__ = ()
+
+    def where(self, condition: Expression[bool], /) -> AsyncBoundDelete:
+        return AsyncBoundDelete(self._operations, self._statement.where(condition))
+
+    def all_rows(self) -> AsyncBoundDelete:
+        return AsyncBoundDelete(self._operations, self._statement.all_rows())
+
+
+__all__ = (
+    "AsyncBoundConflictUpdate",
+    "AsyncBoundDelete",
+    "AsyncBoundInsert",
+    "AsyncBoundMutation",
+    "AsyncBoundReturning",
+    "AsyncBoundUpdate",
+)