pyoq-sql 1.0.0__py3-none-any.whl

pyoq/dsl/aio/context.py

@@ -0,0 +1,295 @@
+"""The asynchronous counterpart of a context to build against."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar, cast, overload
+
+from pyoq.dsl.aio.queries import AsyncBoundSelect
+from pyoq.dsl.aio.writes import AsyncBoundDelete, AsyncBoundInsert, AsyncBoundUpdate
+from pyoq.dsl.labels import labels_of
+from pyoq.dsl.result import Result
+from pyoq.query.select import SelectQuery, select, select_from
+from pyoq.query.select_nodes import SelectNode
+from pyoq.query.writes import (
+    InsertStatement,
+    ReturningStatement,
+    delete_from,
+    insert_into,
+    update,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from pyoq.query.execution.aio import AsyncQueryOperations
+    from pyoq.query.expressions import Expression
+    from pyoq.query.projections import Projection
+    from pyoq.query.routines import Call
+    from pyoq.query.select import Query
+    from pyoq.query.sources import ColumnedTable, TableLike
+
+ResultRow = TypeVar("ResultRow", bound=tuple[object, ...])
+Value1 = TypeVar("Value1")
+Value2 = TypeVar("Value2")
+Value3 = TypeVar("Value3")
+Value4 = TypeVar("Value4")
+Value5 = TypeVar("Value5")
+Value6 = TypeVar("Value6")
+Value7 = TypeVar("Value7")
+Value8 = TypeVar("Value8")
+
+
+class AsyncDslContext:
+    """A database to build against, whose fetches are awaited."""
+
+    __slots__ = ("_operations",)
+    _operations: AsyncQueryOperations
+
+    def __init__(self, operations: AsyncQueryOperations) -> None:
+        object.__setattr__(self, "_operations", operations)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = f"{type(self).__name__} is immutable"
+        raise AttributeError(message, name, value)
+
+    @property
+    def operations(self) -> AsyncQueryOperations:
+        return self._operations
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        /,
+    ) -> AsyncBoundSelect[tuple[Value1]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        /,
+    ) -> AsyncBoundSelect[tuple[Value1, Value2]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        value3: Expression[Value3] | Projection[Value3],
+        /,
+    ) -> AsyncBoundSelect[tuple[Value1, Value2, Value3]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        value3: Expression[Value3] | Projection[Value3],
+        value4: Expression[Value4] | Projection[Value4],
+        /,
+    ) -> AsyncBoundSelect[tuple[Value1, Value2, Value3, Value4]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        value3: Expression[Value3] | Projection[Value3],
+        value4: Expression[Value4] | Projection[Value4],
+        value5: Expression[Value5] | Projection[Value5],
+        /,
+    ) -> AsyncBoundSelect[tuple[Value1, Value2, Value3, Value4, Value5]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        value3: Expression[Value3] | Projection[Value3],
+        value4: Expression[Value4] | Projection[Value4],
+        value5: Expression[Value5] | Projection[Value5],
+        value6: Expression[Value6] | Projection[Value6],
+        /,
+    ) -> AsyncBoundSelect[tuple[Value1, Value2, Value3, Value4, Value5, Value6]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        value3: Expression[Value3] | Projection[Value3],
+        value4: Expression[Value4] | Projection[Value4],
+        value5: Expression[Value5] | Projection[Value5],
+        value6: Expression[Value6] | Projection[Value6],
+        value7: Expression[Value7] | Projection[Value7],
+        /,
+    ) -> AsyncBoundSelect[
+        tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7]
+    ]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        value3: Expression[Value3] | Projection[Value3],
+        value4: Expression[Value4] | Projection[Value4],
+        value5: Expression[Value5] | Projection[Value5],
+        value6: Expression[Value6] | Projection[Value6],
+        value7: Expression[Value7] | Projection[Value7],
+        value8: Expression[Value8] | Projection[Value8],
+        /,
+    ) -> AsyncBoundSelect[
+        tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8]
+    ]: ...
+
+    def select(  # type: ignore[misc]
+        self,
+        *values: object,
+    ) -> AsyncBoundSelect[tuple[object, ...]]:
+        build = cast("Callable[..., SelectQuery[tuple[object, ...]]]", select)
+        return AsyncBoundSelect(self._operations, build(*values))
+
+    def select_from(
+        self, table: ColumnedTable, /
+    ) -> AsyncBoundSelect[tuple[object, ...]]:
+        """Every column the table declares, without naming them one by one.
+
+        The columns are written into the SQL rather than left as a star, so
+        adding one later cannot silently change what a caller reads back.
+        Values arrive in declared order, which is the order the generated row
+        type takes its arguments, so `.into(TableRow)` builds it.
+        """
+        return AsyncBoundSelect(self._operations, select_from(table))
+
+    @overload
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+    ) -> AsyncBoundInsert[Value1]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+    ) -> AsyncBoundInsert[Value1, Value2]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+    ) -> AsyncBoundInsert[Value1, Value2, Value3]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+        column4: Expression[Value4],
+    ) -> AsyncBoundInsert[Value1, Value2, Value3, Value4]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+        column4: Expression[Value4],
+        column5: Expression[Value5],
+    ) -> AsyncBoundInsert[Value1, Value2, Value3, Value4, Value5]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+        column4: Expression[Value4],
+        column5: Expression[Value5],
+        column6: Expression[Value6],
+    ) -> AsyncBoundInsert[Value1, Value2, Value3, Value4, Value5, Value6]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+        column4: Expression[Value4],
+        column5: Expression[Value5],
+        column6: Expression[Value6],
+        column7: Expression[Value7],
+    ) -> AsyncBoundInsert[Value1, Value2, Value3, Value4, Value5, Value6, Value7]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+        column4: Expression[Value4],
+        column5: Expression[Value5],
+        column6: Expression[Value6],
+        column7: Expression[Value7],
+        column8: Expression[Value8],
+    ) -> AsyncBoundInsert[
+        Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8
+    ]: ...
+
+    def insert_into(  # type: ignore[misc]
+        self,
+        table: TableLike,
+        /,
+        *columns: object,
+    ) -> AsyncBoundInsert[*tuple[object, ...]]:
+        build = cast("Callable[..., InsertStatement[*tuple[object, ...]]]", insert_into)
+        return AsyncBoundInsert(self._operations, build(table, *columns))
+
+    def update(self, table: TableLike, /) -> AsyncBoundUpdate:
+        return AsyncBoundUpdate(self._operations, update(table))
+
+    def delete_from(self, table: TableLike, /) -> AsyncBoundDelete:
+        return AsyncBoundDelete(self._operations, delete_from(table))
+
+    async def fetch(
+        self,
+        query: Query[ResultRow] | ReturningStatement[ResultRow] | Call[ResultRow],
+        /,
+    ) -> Result[ResultRow]:
+        """Run something built the ordinary way, and read it the same way."""
+        rows = tuple(await self._operations.many(query))
+        return Result(rows, _labels(query))
+
+
+def _labels(
+    query: Query[ResultRow] | ReturningStatement[ResultRow] | Call[ResultRow],
+) -> tuple[str | None, ...]:
+    if isinstance(query, ReturningStatement):
+        return labels_of(query.node.returning)
+    node = query.node
+    return labels_of(node.projections) if isinstance(node, SelectNode) else ()
+
+
+__all__ = ("AsyncDslContext",)

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")