pyoq-sql 1.0.2__py3-none-any.whl

pyoq/dsl/queries.py

@@ -0,0 +1,339 @@
+"""Queries that know which database they belong to.
+
+PyOQ's builders never reach a database, and that stays true: everything here
+wraps one of those builders together with the operations it will run against.
+The builder is still the only place a query is described, and unwrapping one
+with `query` gives back something that cannot execute.
+"""
+
+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 import QueryOperations
+    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 BoundQuery(Generic[ResultRow]):
+    """A query and the database it will run against."""
+
+    __slots__ = ("_operations", "_query")
+    _operations: QueryOperations
+    _query: Query[ResultRow]
+
+    def __init__(
+        self,
+        operations: QueryOperations,
+        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) -> BoundQuery[ResultRow]:
+        return self._with(self._query.order_by(*terms))
+
+    def limit(self, value: int, /) -> BoundQuery[ResultRow]:
+        return self._with(self._query.limit(value))
+
+    def offset(self, value: int, /) -> BoundQuery[ResultRow]:
+        return self._with(self._query.offset(value))
+
+    def union(self, other: Query[ResultRow], /) -> BoundQuery[ResultRow]:
+        return self._with(self._query.union(other))
+
+    def union_all(self, other: Query[ResultRow], /) -> BoundQuery[ResultRow]:
+        return self._with(self._query.union_all(other))
+
+    def intersect(self, other: Query[ResultRow], /) -> BoundQuery[ResultRow]:
+        return self._with(self._query.intersect(other))
+
+    def except_(self, other: Query[ResultRow], /) -> BoundQuery[ResultRow]:
+        return self._with(self._query.except_(other))
+
+    def fetch_all(self) -> Result[ResultRow]:
+        """Every row, with the names they came back under."""
+        rows = tuple(self._operations.many(self._query))
+        return Result(rows, _labels(self._query))
+
+    def fetch_one(self) -> Row[ResultRow]:
+        """Exactly one row, because that is what the caller said to expect."""
+        return Row(self._operations.one(self._query), _labels(self._query))
+
+    def fetch_optional(self) -> Row[ResultRow] | None:
+        row = self._operations.one_or_none(self._query)
+        return None if row is None else Row(row, _labels(self._query))
+
+    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 = self.fetch_optional()
+        return None if row is None else row.into(factory)
+
+    def fetch_value(
+        self: BoundQuery[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 self._operations.scalar(self._query)
+
+    def _with(self, query: Query[ResultRow]) -> BoundQuery[ResultRow]:
+        return BoundQuery(self._operations, query)
+
+
+class BoundSelect(BoundQuery[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, /) -> BoundSelect[ResultRow]:
+        return self._select(self.query.distinct(enabled))
+
+    def from_(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.from_(source))
+
+    def join(self, source: SourceBase | TableLike, /) -> BoundJoinStep[ResultRow]:
+        """An inner join, qualified by the clause that follows it."""
+        return BoundJoinStep(self._select, self.query.join(source))
+
+    def inner_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundJoinStep[ResultRow]:
+        return BoundJoinStep(self._select, self.query.inner_join(source))
+
+    def left_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundJoinStep[ResultRow]:
+        return BoundJoinStep(self._select, self.query.left_join(source))
+
+    def right_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundJoinStep[ResultRow]:
+        return BoundJoinStep(self._select, self.query.right_join(source))
+
+    def full_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundJoinStep[ResultRow]:
+        return BoundJoinStep(self._select, self.query.full_join(source))
+
+    def semi_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundSemiJoinStep[ResultRow]:
+        """Rows that have a match, without bringing the match back."""
+        return BoundSemiJoinStep(self._select, self.query.semi_join(source))
+
+    def anti_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundSemiJoinStep[ResultRow]:
+        """Rows that have no match."""
+        return BoundSemiJoinStep(self._select, self.query.anti_join(source))
+
+    def cross_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.cross_join(source))
+
+    def natural_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.natural_join(source))
+
+    def natural_left_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.natural_left_join(source))
+
+    def natural_right_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.natural_right_join(source))
+
+    def natural_full_join(
+        self,
+        source: SourceBase | TableLike,
+        /,
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.natural_full_join(source))
+
+    def where(
+        self,
+        condition: Expression[bool],
+        /,
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.where(condition))
+
+    def group_by(self, *expressions: object) -> BoundSelect[ResultRow]:
+        return self._select(self.query.group_by(*expressions))
+
+    def having(
+        self,
+        condition: Expression[bool],
+        /,
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.having(condition))
+
+    def with_(
+        self,
+        *common_tables: CommonTable[object],
+    ) -> BoundSelect[ResultRow]:
+        return self._select(self.query.with_(*common_tables))
+
+    def order_by(self, *terms: object) -> BoundSelect[ResultRow]:
+        return self._select(self.query.order_by(*terms))
+
+    def limit(self, value: int, /) -> BoundSelect[ResultRow]:
+        return self._select(self.query.limit(value))
+
+    def offset(self, value: int, /) -> BoundSelect[ResultRow]:
+        return self._select(self.query.offset(value))
+
+    def _select(self, query: SelectQuery[ResultRow]) -> BoundSelect[ResultRow]:
+        return BoundSelect(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, ...]:
+    """The name each column came back under, where it has one.
+
+    A set operation takes its names from the first query in it, which is the
+    rule the databases themselves follow.
+    """
+    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 BoundJoinStep(Generic[ResultRow]):
+    """A bound join waiting to be told how the two tables line up."""
+
+    __slots__ = ("_bind", "_step")
+    _bind: Callable[[SelectQuery[ResultRow]], BoundSelect[ResultRow]]
+    _step: JoinStep[ResultRow]
+
+    def __init__(
+        self,
+        bind: Callable[[SelectQuery[ResultRow]], BoundSelect[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], /) -> BoundSelect[ResultRow]:
+        """The predicate the rows are matched by."""
+        return self._bind(self._step.on(condition))
+
+    def using(self, *columns: str | ColumnReference) -> BoundSelect[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],
+        /,
+    ) -> BoundSelect[ResultRow]:
+        """Matched on the foreign key the schema already declares."""
+        return self._bind(self._step.on_key(relation))
+
+
+class BoundSemiJoinStep(Generic[ResultRow]):
+    """A bound semi or anti join waiting for its predicate."""
+
+    __slots__ = ("_bind", "_step")
+    _bind: Callable[[SelectQuery[ResultRow]], BoundSelect[ResultRow]]
+    _step: SemiJoinStep[ResultRow]
+
+    def __init__(
+        self,
+        bind: Callable[[SelectQuery[ResultRow]], BoundSelect[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], /) -> BoundSelect[ResultRow]:
+        """The predicate a row is matched by."""
+        return self._bind(self._step.on(condition))
+
+
+__all__ = ("BoundQuery", "BoundSelect")

pyoq/dsl/result.py

@@ -0,0 +1,164 @@
+"""What a fetched query hands back.
+
+Rows arrive as typed tuples. This wraps them so the shape a caller wants is
+asked for at the end of the chain rather than assembled around it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, TypeVar, cast
+
+from pyoq.errors import MultipleResultsError, NoResultError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+
+Values = TypeVar("Values", bound=tuple[object, ...])
+Mapped = TypeVar("Mapped")
+
+
+class Row(tuple[object, ...], Generic[Values]):
+    """One row, and the names it came back under.
+
+    A tuple in every way a caller already relies on: it unpacks, indexes,
+    compares, and iterates. What it adds is the same question the many-row
+    result answers, which is the shape the caller wants it in.
+    """
+
+    _labels: tuple[str | None, ...]
+
+    def __new__(
+        cls,
+        values: Values,
+        labels: tuple[str | None, ...] = (),
+    ) -> Row[Values]:
+        row = super().__new__(cls, values)
+        row._labels = labels
+        return row
+
+    @property
+    def labels(self) -> tuple[str | None, ...]:
+        """One entry per column, None where the query gave it no name."""
+        return self._labels
+
+    def to_tuple(self) -> Values:
+        """The row as the tuple it was typed as."""
+        return cast("Values", tuple(self))
+
+    def to_list(self) -> list[object]:
+        return list(self)
+
+    def to_dict(self) -> dict[str, object]:
+        """Keyed by the names it came back under.
+
+        Every column has to have a name. An expression that was never given
+        one has nothing to key on, and inventing a name would invent a fact.
+        """
+        return dict(zip(_named(self._labels), self, strict=True))
+
+    def into(self, factory: Callable[..., Mapped], /) -> Mapped:
+        """Spread across a constructor, in the order it was selected."""
+        return factory(*self)
+
+
+class Result(Generic[Values]):
+    """The rows a query returned, and the labels they came back under."""
+
+    __slots__ = ("_labels", "_rows")
+    _rows: tuple[Values, ...]
+    _labels: tuple[str | None, ...]
+
+    def __init__(
+        self,
+        rows: tuple[Values, ...],
+        labels: tuple[str | None, ...] = (),
+    ) -> None:
+        object.__setattr__(self, "_rows", rows)
+        object.__setattr__(self, "_labels", labels)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = f"{type(self).__name__} is immutable"
+        raise AttributeError(message, name, value)
+
+    def __iter__(self) -> Iterator[Values]:
+        return iter(self._rows)
+
+    def __len__(self) -> int:
+        return len(self._rows)
+
+    def __bool__(self) -> bool:
+        return bool(self._rows)
+
+    def __repr__(self) -> str:
+        return f"Result({len(self._rows)} rows)"
+
+    @property
+    def labels(self) -> tuple[str | None, ...]:
+        """One entry per column, None where the query gave it no name."""
+        return self._labels
+
+    def to_list(self) -> list[Values]:
+        return list(self._rows)
+
+    def to_tuple(self) -> tuple[Values, ...]:
+        return self._rows
+
+    def map(self, mapper: Callable[[Values], Mapped], /) -> list[Mapped]:
+        """One value per row, built by whatever the caller passes."""
+        return [mapper(row) for row in self._rows]
+
+    def into(self, factory: Callable[..., Mapped], /) -> list[Mapped]:
+        """Each row spread across a constructor, in the order it was selected.
+
+        A dataclass, a named tuple, or any callable taking that many arguments
+        works, because the projection order is the argument order.
+        """
+        return [factory(*row) for row in self._rows]
+
+    def to_dicts(self) -> list[dict[str, object]]:
+        """Rows keyed by the names they came back under.
+
+        Every column has to have a name. An expression that was never given one
+        has nothing to key on, and inventing a name would be inventing a fact.
+        """
+        names = _named(self._labels)
+        return [dict(zip(names, row, strict=True)) for row in self._rows]
+
+    def to_dict(self) -> dict[str, object]:
+        """Exactly one row, keyed by the names it came back under.
+
+        The plural reads every row. This one says the caller expected a single
+        row, and reports it either way rather than quietly taking the first.
+        """
+        return self.one().to_dict()
+
+    def first(self) -> Row[Values] | None:
+        """The row at the front, keyed the way every row here is."""
+        if not self._rows:
+            return None
+        return Row(self._rows[0], self._labels)
+
+    def one(self) -> Row[Values]:
+        """Exactly one row, because that is what the caller said to expect."""
+        if len(self._rows) == 1:
+            return Row(self._rows[0], self._labels)
+        if not self._rows:
+            message = "query returned no rows"
+            raise NoResultError(message)
+        message = "query returned more than one row"
+        raise MultipleResultsError(message)
+
+
+def _named(labels: tuple[str | None, ...]) -> tuple[str, ...]:
+    """Every label, or a refusal naming the columns that have none."""
+    unnamed = [position for position, label in enumerate(labels) if label is None]
+    if unnamed or not labels:
+        message = (
+            "every column needs a name to build a mapping; "
+            f"columns without one: {unnamed or 'all of them'}"
+        )
+        raise ValueError(message)
+    return tuple(label for label in labels if label is not None)
+
+
+__all__ = ("Result",)