pyoq-sql 1.0.0__py3-none-any.whl

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

pyoq/dsl/context.py

@@ -0,0 +1,326 @@
+"""The entry point that ties a query to a database.
+
+PyOQ's builders describe a statement and never reach a database, which is what
+makes them safe to share, cache, and test. A context does not change that: it
+holds the operations to run against and hands back builders that carry it, so a
+chain can end in a fetch instead of being passed to an executor.
+
+The unattached builders are still there and still cannot execute. Anything built
+with them runs through `fetch` or `execute` here.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar, TypeVarTuple, cast, overload
+
+from pyoq.dsl.labels import labels_of
+from pyoq.dsl.queries import BoundSelect
+from pyoq.dsl.result import Result
+from pyoq.dsl.writes import BoundDelete, BoundInsert, BoundUpdate
+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 import QueryOperations
+    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, ...])
+Values = TypeVarTuple("Values")
+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 DslContext:
+    """A database to build against."""
+
+    __slots__ = ("_operations",)
+    _operations: QueryOperations
+
+    def __init__(self, operations: QueryOperations) -> 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) -> QueryOperations:
+        return self._operations
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        /,
+    ) -> BoundSelect[tuple[Value1]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        /,
+    ) -> BoundSelect[tuple[Value1, Value2]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        value3: Expression[Value3] | Projection[Value3],
+        /,
+    ) -> BoundSelect[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],
+        /,
+    ) -> BoundSelect[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],
+        /,
+    ) -> BoundSelect[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],
+        /,
+    ) -> BoundSelect[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],
+        /,
+    ) -> BoundSelect[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],
+        /,
+    ) -> BoundSelect[
+        tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8]
+    ]: ...
+
+    @overload
+    def select(
+        self,
+        value1: object,
+        value2: object,
+        value3: object,
+        value4: object,
+        value5: object,
+        value6: object,
+        value7: object,
+        value8: object,
+        /,
+        *values: object,
+    ) -> BoundSelect[tuple[object, ...]]:
+        """Wider than the overloads above name, where the element types stop.
+
+        A query is still a query past eight projections, and matching no
+        overload would take the whole chain down with it rather than just the
+        tuple. Past here a projection is checked when it is turned into one,
+        and the row is `object` per column, which is what is still known.
+        """
+
+    def select(  # type: ignore[misc]
+        self,
+        *values: object,
+    ) -> BoundSelect[tuple[object, ...]]:
+        # `select` declares typed overloads for callers; this is the single
+        # implementation behind them, reached variadically. The overloads above
+        # are what a caller sees, and they carry the types across.
+        build = cast("Callable[..., SelectQuery[tuple[object, ...]]]", select)
+        return BoundSelect(self._operations, build(*values))
+
+    def select_from(self, table: ColumnedTable, /) -> BoundSelect[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 BoundSelect(self._operations, select_from(table))
+
+    @overload
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+    ) -> BoundInsert[Value1]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+    ) -> BoundInsert[Value1, Value2]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+    ) -> BoundInsert[Value1, Value2, Value3]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+        column4: Expression[Value4],
+    ) -> BoundInsert[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],
+    ) -> BoundInsert[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],
+    ) -> BoundInsert[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],
+    ) -> BoundInsert[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],
+    ) -> BoundInsert[
+        Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8
+    ]: ...
+
+    def insert_into(  # type: ignore[misc]
+        self,
+        table: TableLike,
+        /,
+        *columns: object,
+    ) -> BoundInsert[*tuple[object, ...]]:
+        build = cast("Callable[..., InsertStatement[*tuple[object, ...]]]", insert_into)
+        return BoundInsert(self._operations, build(table, *columns))
+
+    def update(self, table: TableLike, /) -> BoundUpdate:
+        return BoundUpdate(self._operations, update(table))
+
+    def delete_from(self, table: TableLike, /) -> BoundDelete:
+        return BoundDelete(self._operations, delete_from(table))
+
+    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(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__ = ("DslContext",)