pyoq-sql 1.0.2__py3-none-any.whl

pyoq/fastapi/dependencies.py

@@ -0,0 +1,167 @@
+"""Typed dependencies a route asks for.
+
+Each one is a factory, so a route names the database it wants and gets back
+something with a type rather than whatever was on the application object.
+
+Asking twice for the same thing gives back the same dependency. FastAPI matches
+an override by identity, so a factory that built a new function every call could
+never be overridden, and a test would quietly keep talking to the real database.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable, Generator
+from functools import cache
+from typing import TYPE_CHECKING
+
+from fastapi import Request
+from pyoq.diagnostics.scoped import AsyncScopedOperations, ScopedOperations
+from pyoq.errors import OperationUnavailableError
+from pyoq.fastapi.lifespan import databases_of
+from pyoq.query.execution import QueryOperations
+from pyoq.query.execution.aio import AsyncQueryOperations
+from pyoq.serving import (
+    DEFAULT,
+    SupportsAsyncTransaction,
+    SupportsTransaction,
+)
+
+# FastAPI resolves a dependency's annotations when the route is built, so the
+# names in them have to exist at run time rather than only for a checker.
+if TYPE_CHECKING:
+    from pyoq.diagnostics.budget import QueryBudget, QueryScope
+
+
+@cache
+def database(
+    name: str = DEFAULT,
+    /,
+) -> Callable[[Request], QueryOperations]:
+    """The database itself, for a route that runs no transaction of its own."""
+
+    def dependency(request: Request) -> QueryOperations:
+        return databases_of(request.app).synchronous(name)
+
+    return dependency
+
+
+@cache
+def async_database(
+    name: str = DEFAULT,
+    /,
+) -> Callable[[Request], AsyncQueryOperations]:
+    def dependency(request: Request) -> AsyncQueryOperations:
+        return databases_of(request.app).asynchronous(name)
+
+    return dependency
+
+
+@cache
+def transaction(
+    name: str = DEFAULT,
+    /,
+) -> Callable[[Request], Generator[QueryOperations]]:
+    """One transaction for the whole request, ended by how the request ended.
+
+    A route that returns commits. A route that raises rolls back, and so does a
+    request the client gave up on, because a dependency is torn down either way
+    and the transaction sees what tore it down.
+    """
+
+    def dependency(request: Request) -> Generator[QueryOperations]:
+        operations = databases_of(request.app).synchronous(name)
+        with _transactional(operations, name).transaction() as active:
+            yield active
+
+    return dependency
+
+
+@cache
+def async_transaction(
+    name: str = DEFAULT,
+    /,
+) -> Callable[[Request], AsyncGenerator[AsyncQueryOperations]]:
+    async def dependency(
+        request: Request,
+    ) -> AsyncGenerator[AsyncQueryOperations]:
+        operations = databases_of(request.app).asynchronous(name)
+        async with _async_transactional(operations, name).transaction() as active:
+            yield active
+
+    return dependency
+
+
+@cache
+def scoped(
+    budget: QueryBudget,
+    /,
+    name: str = DEFAULT,
+) -> Callable[[Request], QueryOperations]:
+    """A database that counts what this request runs, and refuses beyond it.
+
+    The scope belongs to the request, so one request cannot spend another's
+    budget. A statement the budget refuses never reaches the database.
+    """
+
+    def dependency(request: Request) -> QueryOperations:
+        return ScopedOperations(
+            databases_of(request.app).synchronous(name), _scope(budget)
+        )
+
+    return dependency
+
+
+@cache
+def async_scoped(
+    budget: QueryBudget,
+    /,
+    name: str = DEFAULT,
+) -> Callable[[Request], AsyncQueryOperations]:
+    def dependency(request: Request) -> AsyncQueryOperations:
+        return AsyncScopedOperations(
+            databases_of(request.app).asynchronous(name), _scope(budget)
+        )
+
+    return dependency
+
+
+def _scope(budget: QueryBudget) -> QueryScope:
+    from pyoq.diagnostics.budget import QueryScope
+
+    return QueryScope(budget)
+
+
+def _transactional(
+    operations: QueryOperations,
+    name: str,
+) -> SupportsTransaction:
+    if not isinstance(operations, SupportsTransaction):
+        raise _no_transactions(name)
+    return operations
+
+
+def _async_transactional(
+    operations: AsyncQueryOperations,
+    name: str,
+) -> SupportsAsyncTransaction:
+    if not isinstance(operations, SupportsAsyncTransaction):
+        raise _no_transactions(name)
+    return operations
+
+
+def _no_transactions(name: str) -> OperationUnavailableError:
+    message = (
+        f"the database named {name!r} opens no transactions of its own, so a "
+        f"request transaction cannot be started against it"
+    )
+    return OperationUnavailableError(message)
+
+
+__all__ = (
+    "async_database",
+    "async_scoped",
+    "async_transaction",
+    "database",
+    "scoped",
+    "transaction",
+)

pyoq/fastapi/lifespan.py

@@ -0,0 +1,119 @@
+"""Opening the databases once, and giving them back once.
+
+A pool opened per request is a pool that is never warm and never bounded. The
+application owns them for as long as it runs, which is what a lifespan is for.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import TYPE_CHECKING
+
+from pyoq.errors import PyOQError
+from pyoq.serving import AsyncDatabase, Databases, SyncDatabase
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping
+
+    from fastapi import FastAPI
+
+STATE_ATTRIBUTE = "pyoq_databases"
+
+
+def database_lifespan(
+    *,
+    synchronous: Mapping[str, Callable[[], SyncDatabase]] | None = None,
+    asynchronous: Mapping[str, Callable[[], Awaitable[AsyncDatabase]]] | None = None,
+) -> Callable[[FastAPI], AbstractAsyncContextManager[None]]:
+    """A lifespan that opens every named database and closes every one it opened.
+
+    A database that fails to open takes the application down, and the ones
+    already open are given back first. Starting up halfway and serving requests
+    against a partly opened application is worse than not starting.
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
+        opened_sync: dict[str, SyncDatabase] = {}
+        opened_async: dict[str, AsyncDatabase] = {}
+        try:
+            _open_synchronous(synchronous or {}, opened_sync)
+            await _open_asynchronous(asynchronous or {}, opened_async)
+        except BaseException:
+            await _close_all(opened_sync, opened_async)
+            raise
+        setattr(app.state, STATE_ATTRIBUTE, Databases(opened_sync, opened_async))
+        try:
+            yield
+        finally:
+            await _close_all(opened_sync, opened_async)
+
+    return lifespan
+
+
+def _open_synchronous(
+    factories: Mapping[str, Callable[[], SyncDatabase]],
+    opened: dict[str, SyncDatabase],
+) -> None:
+    for name, factory in factories.items():
+        opened[name] = factory()
+
+
+async def _open_asynchronous(
+    factories: Mapping[str, Callable[[], Awaitable[AsyncDatabase]]],
+    opened: dict[str, AsyncDatabase],
+) -> None:
+    for name, factory in factories.items():
+        opened[name] = await factory()
+
+
+async def _close_all(
+    synchronous: dict[str, SyncDatabase],
+    asynchronous: dict[str, AsyncDatabase],
+) -> None:
+    """Give every database back, even when one of them refuses.
+
+    Stopping at the first failure would leave the rest open, and the process is
+    on its way out either way. The failures are collected so none is silent.
+    """
+    failures: list[BaseException] = []
+    for waiting in reversed(list(asynchronous.values())):
+        await _closed_async(waiting, failures)
+    for immediate in reversed(list(synchronous.values())):
+        _closed(immediate, failures)
+    synchronous.clear()
+    asynchronous.clear()
+    if failures:
+        raise BaseExceptionGroup("closing databases failed", failures)
+
+
+def _closed(database: SyncDatabase, failures: list[BaseException]) -> None:
+    try:
+        database.close()
+    except PyOQError as error:
+        failures.append(error)
+
+
+async def _closed_async(
+    database: AsyncDatabase,
+    failures: list[BaseException],
+) -> None:
+    try:
+        await database.close()
+    except PyOQError as error:
+        failures.append(error)
+
+
+def databases_of(app: FastAPI, /) -> Databases:
+    """What the lifespan opened, or a clear word about it not having run."""
+    found = getattr(app.state, STATE_ATTRIBUTE, None)
+    if not isinstance(found, Databases):
+        message = (
+            "no PyOQ databases are open; give the application the lifespan "
+            "returned by database_lifespan()"
+        )
+        raise LookupError(message)
+    return found
+
+
+__all__ = ("STATE_ATTRIBUTE", "database_lifespan", "databases_of")

pyoq/fetching/__init__.py

@@ -0,0 +1,55 @@
+"""Carrying out a fetch plan against a database."""
+
+from pyoq.fetching.collections import decode_collection, hydrate_collection
+from pyoq.fetching.execution import (
+    AsyncFetchExecutor,
+    FetchAssembly,
+    FetchedRow,
+    FetchExecutor,
+)
+from pyoq.fetching.joined import join_condition, projection_layout
+from pyoq.fetching.nesting import collection_for
+from pyoq.fetching.plans import (
+    DeferredRelation,
+    FetchColumn,
+    FetchStatement,
+    JoinedRelation,
+    NestedJoin,
+    NestedRelation,
+    RelationBlock,
+    batch_statement,
+    columns_of,
+    root_statement,
+)
+from pyoq.fetching.select_in import (
+    KeyColumn,
+    batch_conditions,
+    key_condition,
+    select_in_conditions,
+)
+
+__all__ = (
+    "AsyncFetchExecutor",
+    "DeferredRelation",
+    "FetchAssembly",
+    "FetchColumn",
+    "FetchExecutor",
+    "FetchStatement",
+    "FetchedRow",
+    "JoinedRelation",
+    "KeyColumn",
+    "NestedJoin",
+    "NestedRelation",
+    "RelationBlock",
+    "batch_conditions",
+    "batch_statement",
+    "collection_for",
+    "columns_of",
+    "decode_collection",
+    "hydrate_collection",
+    "join_condition",
+    "key_condition",
+    "projection_layout",
+    "root_statement",
+    "select_in_conditions",
+)

pyoq/fetching/collections.py

@@ -0,0 +1,136 @@
+"""Reading a nested collection back into rows.
+
+The value a collection returns is JSON, and what a driver hands over differs:
+two of the three return it as text and one has already decoded it. Both arrive
+here, and neither is trusted to hold what it promised.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from itertools import zip_longest
+from typing import cast
+
+from pyoq.errors import CollectionDecodeError
+from pyoq.hydration.plan import RowConstructor
+from pyoq.query.decoding import decode_value
+from pyoq.relations import RelationValue
+
+_MISSING = object()
+
+
+def decode_collection(
+    payload: object,
+    keys: Sequence[str],
+    /,
+    types: tuple[type[object] | None, ...] = (),
+) -> tuple[tuple[object, ...], ...]:
+    """Read one collection into a row of values per element.
+
+    Values come back in the order the keys are given, so a caller reads them
+    the same way it reads any other row rather than by looking names up.
+
+    JSON spells a date as a string and a decimal as a number, so a caller that
+    says what its columns hold gets them back as that, the same as it would from
+    a column read directly. A caller that says nothing gets what JSON spelled.
+    """
+    _require_keys(keys)
+    elements = _elements(payload)
+    rows = tuple(_row(element, keys, index) for index, element in enumerate(elements))
+    if not types:
+        return rows
+    return tuple(_decoded(row, types) for row in rows)
+
+
+def _elements(payload: object) -> list[object]:
+    value = _parsed(payload)
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        message = (
+            f"a collection must hold a list of rows, and this holds "
+            f"{type(value).__name__}"
+        )
+        raise CollectionDecodeError(message)
+    return cast("list[object]", value)
+
+
+def _parsed(payload: object) -> object:
+    """One driver returns text and another returns what it already decoded."""
+    if payload is None:
+        return None
+    if isinstance(payload, (str, bytes, bytearray)):
+        return _loaded(payload)
+    return payload
+
+
+def _loaded(payload: str | bytes | bytearray) -> object:
+    try:
+        return json.loads(payload)
+    except ValueError as error:
+        message = f"a collection did not hold readable JSON: {error}"
+        raise CollectionDecodeError(message) from error
+
+
+def _row(
+    element: object,
+    keys: Sequence[str],
+    index: int,
+) -> tuple[object, ...]:
+    if not isinstance(element, dict):
+        message = (
+            f"row {index} of a collection must be an object, and this is "
+            f"{type(element).__name__}"
+        )
+        raise CollectionDecodeError(message)
+    entries = cast("dict[str, object]", element)
+    return tuple(_value(entries, key, index) for key in keys)
+
+
+def _value(entries: dict[str, object], key: str, index: int) -> object:
+    value = entries.get(key, _MISSING)
+    if value is _MISSING:
+        message = f"row {index} of a collection has no {key!r}"
+        raise CollectionDecodeError(message)
+    return value
+
+
+def _require_keys(keys: Sequence[str]) -> None:
+    if not keys:
+        message = "a collection is read by naming at least one value"
+        raise CollectionDecodeError(message)
+    if len(set(keys)) != len(keys):
+        message = "a collection cannot be read by one name twice"
+        raise CollectionDecodeError(message)
+
+
+def _decoded(
+    row: tuple[object, ...],
+    types: tuple[type[object] | None, ...],
+) -> tuple[object, ...]:
+    return tuple(
+        decode_value(value, target)
+        for value, target in zip_longest(row, types[: len(row)])
+    )
+
+
+def hydrate_collection(
+    payload: object,
+    keys: Sequence[str],
+    construct: RowConstructor,
+    /,
+    types: tuple[type[object] | None, ...] = (),
+) -> RelationValue[object]:
+    """Read a collection into built rows, loaded and ready.
+
+    A collection that came back empty is a loaded relation holding nothing,
+    which is not the same as a relation nobody fetched.
+    """
+    rows = tuple(
+        construct(values, {}) for values in decode_collection(payload, keys, types)
+    )
+    return RelationValue.loaded(rows)
+
+
+__all__ = ("decode_collection", "hydrate_collection")