pyoq-sql 1.0.2__py3-none-any.whl

pyoq/runtime/selection.py

@@ -0,0 +1,73 @@
+"""Runtime engine selection."""
+
+from collections.abc import Callable
+from enum import StrEnum
+from importlib import import_module
+from typing import Protocol, cast
+from warnings import warn
+
+from pyoq.errors import NativeRuntimeUnavailableError, RuntimeSelectionError
+
+
+class RuntimeEngine(StrEnum):
+    NATIVE = "native"
+    PYTHON = "python"
+
+
+class RuntimeBackend(Protocol):
+    def runtime_marker(self) -> str: ...
+
+    def fingerprint_fragments(self, fragments: list[bytes]) -> int: ...
+
+    def group_integer_keys(
+        self,
+        keys: list[int | None],
+    ) -> list[tuple[int, int]]: ...
+
+
+NativeLoader = Callable[[], RuntimeBackend]
+
+
+def select_runtime(
+    preference: str | None,
+    native_loader: NativeLoader | None = None,
+) -> RuntimeEngine:
+    normalized_preference = (preference or "auto").lower()
+    if normalized_preference == RuntimeEngine.PYTHON:
+        return RuntimeEngine.PYTHON
+    if normalized_preference not in {"auto", RuntimeEngine.NATIVE}:
+        message = "PYOQ_RUNTIME must be 'auto', 'native', or 'python'"
+        raise RuntimeSelectionError(message)
+
+    loader = native_loader or load_native_runtime
+    try:
+        native_runtime = loader()
+    except ImportError as error:
+        return _handle_missing_native(normalized_preference, error)
+
+    if native_runtime.runtime_marker() != RuntimeEngine.NATIVE:
+        message = "The loaded PyOQ native module failed its identity check"
+        raise NativeRuntimeUnavailableError(message)
+    return RuntimeEngine.NATIVE
+
+
+def load_native_runtime() -> RuntimeBackend:
+    return cast(RuntimeBackend, import_module("pyoq._native"))
+
+
+def load_python_runtime() -> RuntimeBackend:
+    return cast(RuntimeBackend, import_module("pyoq.runtime.python"))
+
+
+def _handle_missing_native(
+    preference: str,
+    error: ImportError,
+) -> RuntimeEngine:
+    message = (
+        "The PyOQ native runtime is unavailable. Install a supported wheel or "
+        "set PYOQ_RUNTIME=python to select the slower fallback explicitly."
+    )
+    if preference == RuntimeEngine.NATIVE:
+        raise NativeRuntimeUnavailableError(message) from error
+    warn(message, RuntimeWarning, stacklevel=3)
+    return RuntimeEngine.PYTHON

pyoq/sanic/__init__.py

@@ -0,0 +1,32 @@
+"""Running PyOQ inside a Sanic application."""
+
+from pyoq.sanic.scope import (
+    attach_request_budget,
+    attach_synchronous_request_budget,
+    budgeted_of,
+    database_of,
+    synchronous_budgeted_of,
+    synchronous_database_of,
+    synchronous_transaction,
+    transaction,
+)
+from pyoq.sanic.workers import WorkerDatabases, attach_databases, databases_of
+from pyoq.serving import DEFAULT, AsyncDatabase, Databases, SyncDatabase
+
+__all__ = (
+    "DEFAULT",
+    "AsyncDatabase",
+    "Databases",
+    "SyncDatabase",
+    "WorkerDatabases",
+    "attach_databases",
+    "attach_request_budget",
+    "attach_synchronous_request_budget",
+    "budgeted_of",
+    "database_of",
+    "databases_of",
+    "synchronous_budgeted_of",
+    "synchronous_database_of",
+    "synchronous_transaction",
+    "transaction",
+)

pyoq/sanic/scope.py

@@ -0,0 +1,197 @@
+"""What one request holds, and what ends it.
+
+A transaction is scoped to the handler's own block rather than to a pair of
+middlewares. A server that is told the client has gone cancels the task it
+called the application on, and nothing after the handler runs, response
+middleware included. A transaction ended there would keep its connection for as
+long as the worker lives, inside an open transaction, holding whatever it
+locked. A block the handler enters is ended by Python itself, so cancellation
+reaches it like any other exception.
+
+A budget holds nothing, so it is still attached once and read per request.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager, contextmanager
+from typing import TYPE_CHECKING, TypeVar
+
+from pyoq.diagnostics.scoped import AsyncScopedOperations, ScopedOperations
+from pyoq.errors import OperationUnavailableError
+from pyoq.sanic.workers import databases_of
+from pyoq.serving import DEFAULT, SupportsAsyncTransaction, SupportsTransaction
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Awaitable, Callable, Generator
+
+    from sanic.config import Config
+
+    from pyoq.diagnostics.budget import QueryBudget
+    from pyoq.query.execution import QueryOperations
+    from pyoq.query.execution.aio import AsyncQueryOperations
+    from sanic import Request, Sanic
+
+ConfigType = TypeVar("ConfigType", bound="Config")
+ContextType = TypeVar("ContextType")
+
+SCOPE_ATTRIBUTE = "pyoq_scope"
+
+
+@asynccontextmanager
+async def transaction(
+    request: Request,
+    /,
+    name: str = DEFAULT,
+) -> AsyncGenerator[AsyncQueryOperations]:
+    """One transaction for as long as the block runs.
+
+    Leaving the block normally commits. Leaving it any other way rolls back: a
+    handler that raised, and a request the server abandoned, which reaches the
+    block as a cancellation like anything else would.
+    """
+    operations = databases_of(request.app).asynchronous(name)
+    async with _transactional(operations, name).transaction() as active:
+        yield active
+
+
+@contextmanager
+def synchronous_transaction(
+    request: Request,
+    /,
+    name: str = DEFAULT,
+) -> Generator[QueryOperations]:
+    """The same, for a database that is not awaited."""
+    operations = databases_of(request.app).synchronous(name)
+    with _synchronous(operations, name).transaction() as active:
+        yield active
+
+
+def database_of(request: Request, /, name: str = DEFAULT) -> AsyncQueryOperations:
+    """The worker's database, for a request that runs no transaction."""
+    return databases_of(request.app).asynchronous(name)
+
+
+def synchronous_database_of(
+    request: Request,
+    /,
+    name: str = DEFAULT,
+) -> QueryOperations:
+    return databases_of(request.app).synchronous(name)
+
+
+def attach_request_budget(
+    app: Sanic[ConfigType, ContextType],
+    budget: QueryBudget,
+    /,
+    name: str = DEFAULT,
+) -> None:
+    """A budget per request, so one request cannot spend another's.
+
+    A budget holds no connection, so nothing is left behind when a request ends
+    early and one middleware is enough.
+    """
+
+    async def open_scope(request: Request) -> None:
+        from pyoq.diagnostics.budget import QueryScope
+
+        operations = databases_of(request.app).asynchronous(name)
+        counted = AsyncScopedOperations(operations, QueryScope(budget))
+        setattr(request.ctx, SCOPE_ATTRIBUTE, counted)
+
+    _on_request(app, open_scope)
+
+
+def attach_synchronous_request_budget(
+    app: Sanic[ConfigType, ContextType],
+    budget: QueryBudget,
+    /,
+    name: str = DEFAULT,
+) -> None:
+    """The same, for a database that is not awaited."""
+
+    async def open_scope(request: Request) -> None:
+        from pyoq.diagnostics.budget import QueryScope
+
+        operations = databases_of(request.app).synchronous(name)
+        setattr(
+            request.ctx,
+            SCOPE_ATTRIBUTE,
+            ScopedOperations(operations, QueryScope(budget)),
+        )
+
+    _on_request(app, open_scope)
+
+
+def budgeted_of(request: Request, /) -> AsyncQueryOperations:
+    """The database this request may use, counting as it goes."""
+    counted = getattr(request.ctx, SCOPE_ATTRIBUTE, None)
+    if not isinstance(counted, AsyncScopedOperations):
+        raise _no_budget()
+    return counted
+
+
+def synchronous_budgeted_of(request: Request, /) -> QueryOperations:
+    counted = getattr(request.ctx, SCOPE_ATTRIBUTE, None)
+    if not isinstance(counted, ScopedOperations):
+        raise _no_budget()
+    return counted
+
+
+def _no_budget() -> LookupError:
+    message = (
+        "this request holds no PyOQ budget; call attach_request_budget(app, "
+        "budget) to give it one"
+    )
+    return LookupError(message)
+
+
+def _on_request(
+    app: Sanic[ConfigType, ContextType],
+    middleware: Callable[[Request], Awaitable[None]],
+) -> None:
+    """Sanic leaves the request parameter of its middleware type free.
+
+    That makes the registration read as partly unknown to a checker even though
+    the callable is fully typed where it is written. This is the one place that
+    says so.
+    """
+    app.register_middleware(middleware, "request")  # type: ignore[arg-type]  # pyright: ignore[reportUnknownMemberType, reportArgumentType]
+
+
+def _transactional(
+    operations: AsyncQueryOperations,
+    name: str,
+) -> SupportsAsyncTransaction:
+    if not isinstance(operations, SupportsAsyncTransaction):
+        raise _no_transactions(name)
+    return operations
+
+
+def _synchronous(
+    operations: QueryOperations,
+    name: str,
+) -> SupportsTransaction:
+    if not isinstance(operations, SupportsTransaction):
+        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__ = (
+    "SCOPE_ATTRIBUTE",
+    "attach_request_budget",
+    "attach_synchronous_request_budget",
+    "budgeted_of",
+    "database_of",
+    "synchronous_budgeted_of",
+    "synchronous_database_of",
+    "synchronous_transaction",
+    "transaction",
+)

pyoq/sanic/workers.py

@@ -0,0 +1,129 @@
+"""Opening a database in the worker that will use it.
+
+Sanic starts its workers by forking. A connection made before that fork is
+inherited by every worker at once, and two processes talking over one socket
+corrupt each other's results. So the pool is opened from the listener that runs
+inside each worker, and never from the one that runs in the main process.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeAlias, TypeVar
+
+from pyoq.errors import PyOQError
+from pyoq.serving import AsyncDatabase, Databases, SyncDatabase
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from sanic.config import Config
+
+from collections.abc import Awaitable, Callable, Coroutine
+
+from sanic import Sanic
+
+ConfigType = TypeVar("ConfigType", bound="Config")
+ContextType = TypeVar("ContextType")
+
+Listener: TypeAlias = Callable[
+    ["Sanic[ConfigType, ContextType]"], Coroutine[object, object, None]
+]
+
+CONTEXT_ATTRIBUTE = "pyoq_databases"
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerDatabases(Generic[ConfigType, ContextType]):
+    """The two listeners an attachment registered.
+
+    They are handed back so an application can run them itself, and so what
+    they do can be checked without asking Sanic what it was told.
+    """
+
+    open: Listener[ConfigType, ContextType]
+    close: Listener[ConfigType, ContextType]
+
+
+def attach_databases(
+    app: Sanic[ConfigType, ContextType],
+    /,
+    *,
+    synchronous: Mapping[str, Callable[[], SyncDatabase]] | None = None,
+    asynchronous: Mapping[str, Callable[[], Awaitable[AsyncDatabase]]] | None = None,
+) -> WorkerDatabases[ConfigType, ContextType]:
+    """Give every worker its own databases, opened and closed with the server.
+
+    `before_server_start` runs once inside each worker after the fork, which is
+    the earliest point a connection can be made without being shared.
+    """
+
+    async def open_databases(running: Sanic[ConfigType, ContextType]) -> None:
+        opened_sync: dict[str, SyncDatabase] = {}
+        opened_async: dict[str, AsyncDatabase] = {}
+        try:
+            for name, build in (synchronous or {}).items():
+                opened_sync[name] = build()
+            for name, build_async in (asynchronous or {}).items():
+                opened_async[name] = await build_async()
+        except BaseException:
+            await _close_all(opened_sync, opened_async)
+            raise
+        setattr(
+            running.ctx,
+            CONTEXT_ATTRIBUTE,
+            Databases(opened_sync, opened_async),
+        )
+
+    async def close_databases(running: Sanic[ConfigType, ContextType]) -> None:
+        held = getattr(running.ctx, CONTEXT_ATTRIBUTE, None)
+        if not isinstance(held, Databases):
+            return
+        delattr(running.ctx, CONTEXT_ATTRIBUTE)
+        await _close_all(*held.opened)
+
+    app.before_server_start(open_databases)
+    app.before_server_stop(close_databases)
+    return WorkerDatabases(open_databases, close_databases)
+
+
+async def _close_all(
+    synchronous: dict[str, SyncDatabase],
+    asynchronous: dict[str, AsyncDatabase],
+) -> None:
+    """Give every database back, even when one of them refuses."""
+    failures: list[BaseException] = []
+    for waiting in reversed(list(asynchronous.values())):
+        try:
+            await waiting.close()
+        except PyOQError as error:
+            failures.append(error)
+    for immediate in reversed(list(synchronous.values())):
+        try:
+            immediate.close()
+        except PyOQError as error:
+            failures.append(error)
+    synchronous.clear()
+    asynchronous.clear()
+    if failures:
+        raise BaseExceptionGroup("closing databases failed", failures)
+
+
+def databases_of(app: Sanic[ConfigType, ContextType], /) -> Databases:
+    """What this worker opened, or a clear word about it not having run."""
+    held = getattr(app.ctx, CONTEXT_ATTRIBUTE, None)
+    if not isinstance(held, Databases):
+        message = (
+            "no PyOQ databases are open in this worker; call "
+            "attach_databases(app) before the server starts"
+        )
+        raise LookupError(message)
+    return held
+
+
+__all__ = (
+    "CONTEXT_ATTRIBUTE",
+    "WorkerDatabases",
+    "attach_databases",
+    "databases_of",
+)

pyoq/schema/__init__.py

@@ -0,0 +1,108 @@
+"""Public database schema interface."""
+
+from pyoq.schema.models import (
+    SCHEMA_FORMAT_VERSION,
+    Capability,
+    CapabilitySet,
+    Catalog,
+    CheckConstraint,
+    Column,
+    Domain,
+    EnumType,
+    GeneratedKind,
+    GeneratedValue,
+    Identifier,
+    Index,
+    IndexTerm,
+    JsonScalar,
+    JsonValue,
+    Key,
+    KeyKind,
+    MetadataEntry,
+    ObjectReference,
+    ParameterMode,
+    ReferentialAction,
+    Relation,
+    Routine,
+    RoutineKind,
+    RoutineParameter,
+    Schema,
+    SchemaSnapshot,
+    SqlExpression,
+    SqlType,
+    Table,
+    TypeKind,
+    View,
+)
+from pyoq.schema.mysql import (
+    MySQLConnectionProvider,
+    MySQLConnectionSettings,
+    MySQLSchemaInspector,
+    MySQLSchemaSource,
+    mysql_type,
+)
+from pyoq.schema.postgres import (
+    PostgresConnectionProvider,
+    PostgresSchemaInspector,
+    PostgresSchemaSource,
+    postgres_type,
+)
+from pyoq.schema.registry import (
+    DialectRoutingSchemaSource,
+    SchemaSourceFactory,
+    schema_source_for,
+    supported_dialects,
+)
+from pyoq.schema.source import SchemaSource
+from pyoq.schema.sqlite import SQLiteSchemaInspector, SQLiteSchemaSource
+
+__all__ = (
+    "SCHEMA_FORMAT_VERSION",
+    "Capability",
+    "CapabilitySet",
+    "Catalog",
+    "CheckConstraint",
+    "Column",
+    "DialectRoutingSchemaSource",
+    "Domain",
+    "EnumType",
+    "GeneratedKind",
+    "GeneratedValue",
+    "Identifier",
+    "Index",
+    "IndexTerm",
+    "JsonScalar",
+    "JsonValue",
+    "Key",
+    "KeyKind",
+    "MetadataEntry",
+    "MySQLConnectionProvider",
+    "MySQLConnectionSettings",
+    "MySQLSchemaInspector",
+    "MySQLSchemaSource",
+    "ObjectReference",
+    "ParameterMode",
+    "PostgresConnectionProvider",
+    "PostgresSchemaInspector",
+    "PostgresSchemaSource",
+    "ReferentialAction",
+    "Relation",
+    "Routine",
+    "RoutineKind",
+    "RoutineParameter",
+    "SQLiteSchemaInspector",
+    "SQLiteSchemaSource",
+    "Schema",
+    "SchemaSnapshot",
+    "SchemaSource",
+    "SchemaSourceFactory",
+    "SqlExpression",
+    "SqlType",
+    "Table",
+    "TypeKind",
+    "View",
+    "mysql_type",
+    "postgres_type",
+    "schema_source_for",
+    "supported_dialects",
+)