pyoq-sql 1.0.2__py3-none-any.whl

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

pyoq/dsl/entry.py

@@ -0,0 +1,37 @@
+"""Choosing a context from the database it is given.
+
+There is one name for this because there is one question being asked. Whether
+the fetches are awaited follows from the database, not from a second spelling.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, overload
+
+from pyoq.dsl.aio.context import AsyncDslContext
+from pyoq.dsl.context import DslContext
+from pyoq.query.execution.aio import AsyncQueryOperations
+
+if TYPE_CHECKING:
+    from pyoq.query.execution import QueryOperations
+
+
+@overload
+def using(operations: QueryOperations, /) -> DslContext: ...
+
+
+@overload
+def using(operations: AsyncQueryOperations, /) -> AsyncDslContext: ...
+
+
+def using(
+    operations: QueryOperations | AsyncQueryOperations,
+    /,
+) -> DslContext | AsyncDslContext:
+    """A context over any database PyOQ can run statements against."""
+    if isinstance(operations, AsyncQueryOperations):
+        return AsyncDslContext(operations)
+    return DslContext(operations)
+
+
+__all__ = ("using",)

pyoq/dsl/labels.py

@@ -0,0 +1,36 @@
+"""The name a column comes back under.
+
+Queries and writes both project through the same node, so the rule for naming a
+column lives here rather than once in each place that needs it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyoq.query.nodes import FieldNode
+
+if TYPE_CHECKING:
+    from pyoq.query.select_nodes import ProjectionNode
+
+
+def labels_of(
+    projections: tuple[ProjectionNode, ...],
+    /,
+) -> tuple[str | None, ...]:
+    return tuple(_label(projection) for projection in projections)
+
+
+def _label(projection: ProjectionNode) -> str | None:
+    """An alias if the query gave one, otherwise the column's own name.
+
+    Anything else has no name to report, and inventing one would report a fact
+    the database never stated.
+    """
+    if projection.alias is not None:
+        return projection.alias
+    expression = projection.expression
+    return expression.name if isinstance(expression, FieldNode) else None
+
+
+__all__ = ("labels_of",)