pyoq-sql 1.0.2__py3-none-any.whl

pyoq/django/settings.py

@@ -0,0 +1,87 @@
+"""PyOQ's own settings, read from the Django project that owns them."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Final, cast
+
+from django.conf import settings
+
+from pyoq.config import Configuration, DatabaseDialect, DatabaseProfile
+from pyoq.errors import OperationUnavailableError
+
+SETTING: Final = "PYOQ"
+
+_PROFILE: Final = "django"
+
+
+def pyoq_settings() -> dict[str, object]:
+    """The project's PyOQ settings, which it has to have written itself.
+
+    There is no default output location worth guessing. A package written to
+    the wrong place is worse than being told where to put it.
+    """
+    configured: object = getattr(settings, SETTING, None)
+    if not isinstance(configured, Mapping):
+        message = (
+            f"Django settings define no {SETTING} mapping; add "
+            f'{SETTING} = {{"codegen_directory": ..., '
+            f'"codegen_package": ...}}'
+        )
+        raise OperationUnavailableError(message)
+    # Django settings carry no types of their own, so this is the one place
+    # that says what the mapping holds. Every read below re-checks the value.
+    entries = cast("Mapping[str, object]", configured)
+    return dict(entries)
+
+
+def django_configuration(dialect: DatabaseDialect, /) -> Configuration:
+    """Where generated output goes, with no database named.
+
+    The schema comes from migration files, so a profile here carries the
+    dialect and nothing that would open a connection.
+    """
+    configured = pyoq_settings()
+    return Configuration(
+        project_root=_root(configured),
+        codegen_directory=Path(_required(configured, "codegen_directory")),
+        codegen_package=_required(configured, "codegen_package"),
+        selected_profile=_PROFILE,
+        profiles=(DatabaseProfile(name=_PROFILE, dialect=dialect),),
+    )
+
+
+def codegen_after_makemigrations() -> bool:
+    """Overriding a command a project already runs has to be asked for."""
+    return bool(pyoq_settings().get("codegen_after_makemigrations", False))
+
+
+def _root(configured: dict[str, object]) -> Path:
+    named = configured.get("project_root")
+    if named is not None:
+        return Path(str(named))
+    base = getattr(settings, "BASE_DIR", None)
+    if base is None:
+        message = (
+            f"neither {SETTING}['project_root'] nor BASE_DIR is set, so there "
+            f"is nowhere to write generated code relative to"
+        )
+        raise OperationUnavailableError(message)
+    return Path(str(base))
+
+
+def _required(configured: dict[str, object], key: str) -> str:
+    value = configured.get(key)
+    if not isinstance(value, str) or not value:
+        message = f"{SETTING}[{key!r}] must be a non-empty string"
+        raise OperationUnavailableError(message)
+    return value
+
+
+__all__ = (
+    "SETTING",
+    "codegen_after_makemigrations",
+    "django_configuration",
+    "pyoq_settings",
+)

pyoq/django/timeouts.py

@@ -0,0 +1,105 @@
+"""Bounding a statement on a connection PyOQ does not own.
+
+A timeout is session state, and the session belongs to Django, so it has to be
+put back exactly as it was found. Inside a transaction the database does that
+itself; outside one, the previous value is read first and restored after.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass
+
+from django.db import DatabaseError
+from django.db.backends.base.base import BaseDatabaseWrapper
+
+MILLISECONDS = 1000
+
+
+@dataclass(frozen=True, slots=True)
+class TimeoutSetting:
+    """The session setting one backend uses to bound a statement."""
+
+    name: str
+    reads: bool = True
+    writes: bool = True
+
+    def read(self, connection: BaseDatabaseWrapper, /) -> str:
+        with connection.cursor() as cursor:
+            cursor.execute(f"SHOW {self.name}")
+            row = cursor.fetchone()
+        return "" if row is None else str(row[0])
+
+    def assign(
+        self,
+        connection: BaseDatabaseWrapper,
+        value: str,
+        /,
+        *,
+        local: bool,
+    ) -> None:
+        scope = "LOCAL " if local else ""
+        with connection.cursor() as cursor:
+            cursor.execute(f"SET {scope}{self.name} = {value}")
+
+
+POSTGRES_TIMEOUT = TimeoutSetting("statement_timeout")
+MYSQL_TIMEOUT = TimeoutSetting("@@max_execution_time", writes=False)
+
+
+@contextmanager
+def applied(
+    setting: TimeoutSetting,
+    connection: BaseDatabaseWrapper,
+    seconds: float,
+    /,
+) -> Generator[None]:
+    """Bound statements for the length of this block, and leave no trace.
+
+    Inside a transaction the setting is local, so the database restores it when
+    the transaction ends. Outside one there is nothing to restore it, so the
+    previous value is read first and put back afterwards.
+    """
+    milliseconds = max(int(seconds * MILLISECONDS), 1)
+    if connection.in_atomic_block:
+        setting.assign(connection, str(milliseconds), local=True)
+        yield
+        return
+    previous = setting.read(connection)
+    setting.assign(connection, str(milliseconds), local=False)
+    try:
+        yield
+    finally:
+        _restore(setting, connection, previous)
+
+
+def _restore(
+    setting: TimeoutSetting,
+    connection: BaseDatabaseWrapper,
+    previous: str,
+) -> None:
+    """Put the setting back without ever replacing the reason we are here.
+
+    A statement that failed can leave a connection unable to accept the next
+    one, and a restore that raised there would hide the failure that caused it.
+    Django owns the connection and will deal with it.
+    """
+    try:
+        setting.assign(connection, _quoted(previous), local=False)
+    except DatabaseError:
+        return
+
+
+def _quoted(previous: str) -> str:
+    """A read setting comes back with its unit, which has to go back quoted."""
+    return previous if previous.isdigit() else f"'{previous}'"
+
+
+__all__ = (
+    "MILLISECONDS",
+    "MYSQL_TIMEOUT",
+    "POSTGRES_TIMEOUT",
+    "TimeoutSetting",
+    "applied",
+)

pyoq/dsl/__init__.py

@@ -0,0 +1,64 @@
+"""Building a statement and running it in one chain.
+
+`using(database)` gives a context to build against. The builders in
+`pyoq.query` are unchanged and still cannot reach a database on their own.
+"""
+
+from pyoq.dsl.aio import (
+    AsyncBoundConflictUpdate,
+    AsyncBoundDelete,
+    AsyncBoundInsert,
+    AsyncBoundJoinStep,
+    AsyncBoundMutation,
+    AsyncBoundQuery,
+    AsyncBoundReturning,
+    AsyncBoundSelect,
+    AsyncBoundSemiJoinStep,
+    AsyncBoundUpdate,
+    AsyncDslContext,
+)
+from pyoq.dsl.context import DslContext
+from pyoq.dsl.entry import using
+from pyoq.dsl.queries import (
+    BoundJoinStep,
+    BoundQuery,
+    BoundSelect,
+    BoundSemiJoinStep,
+)
+from pyoq.dsl.result import Result, Row
+from pyoq.dsl.writes import (
+    BoundConflictUpdate,
+    BoundDelete,
+    BoundInsert,
+    BoundMutation,
+    BoundReturning,
+    BoundUpdate,
+)
+
+__all__ = (
+    "AsyncBoundConflictUpdate",
+    "AsyncBoundDelete",
+    "AsyncBoundInsert",
+    "AsyncBoundJoinStep",
+    "AsyncBoundMutation",
+    "AsyncBoundQuery",
+    "AsyncBoundReturning",
+    "AsyncBoundSelect",
+    "AsyncBoundSemiJoinStep",
+    "AsyncBoundUpdate",
+    "AsyncDslContext",
+    "BoundConflictUpdate",
+    "BoundDelete",
+    "BoundInsert",
+    "BoundJoinStep",
+    "BoundMutation",
+    "BoundQuery",
+    "BoundReturning",
+    "BoundSelect",
+    "BoundSemiJoinStep",
+    "BoundUpdate",
+    "DslContext",
+    "Result",
+    "Row",
+    "using",
+)

pyoq/dsl/aio/__init__.py

@@ -0,0 +1,31 @@
+"""The asynchronous counterpart of the bound builders."""
+
+from pyoq.dsl.aio.context import AsyncDslContext
+from pyoq.dsl.aio.queries import (
+    AsyncBoundJoinStep,
+    AsyncBoundQuery,
+    AsyncBoundSelect,
+    AsyncBoundSemiJoinStep,
+)
+from pyoq.dsl.aio.writes import (
+    AsyncBoundConflictUpdate,
+    AsyncBoundDelete,
+    AsyncBoundInsert,
+    AsyncBoundMutation,
+    AsyncBoundReturning,
+    AsyncBoundUpdate,
+)
+
+__all__ = (
+    "AsyncBoundConflictUpdate",
+    "AsyncBoundDelete",
+    "AsyncBoundInsert",
+    "AsyncBoundJoinStep",
+    "AsyncBoundMutation",
+    "AsyncBoundQuery",
+    "AsyncBoundReturning",
+    "AsyncBoundSelect",
+    "AsyncBoundSemiJoinStep",
+    "AsyncBoundUpdate",
+    "AsyncDslContext",
+)

pyoq/dsl/aio/context.py

@@ -0,0 +1,295 @@
+"""The asynchronous counterpart of a context to build against."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar, cast, overload
+
+from pyoq.dsl.aio.queries import AsyncBoundSelect
+from pyoq.dsl.aio.writes import AsyncBoundDelete, AsyncBoundInsert, AsyncBoundUpdate
+from pyoq.dsl.labels import labels_of
+from pyoq.dsl.result import Result
+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.aio import AsyncQueryOperations
+    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, ...])
+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 AsyncDslContext:
+    """A database to build against, whose fetches are awaited."""
+
+    __slots__ = ("_operations",)
+    _operations: AsyncQueryOperations
+
+    def __init__(self, operations: AsyncQueryOperations) -> 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) -> AsyncQueryOperations:
+        return self._operations
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        /,
+    ) -> AsyncBoundSelect[tuple[Value1]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        /,
+    ) -> AsyncBoundSelect[tuple[Value1, Value2]]: ...
+
+    @overload
+    def select(
+        self,
+        value1: Expression[Value1] | Projection[Value1],
+        value2: Expression[Value2] | Projection[Value2],
+        value3: Expression[Value3] | Projection[Value3],
+        /,
+    ) -> AsyncBoundSelect[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],
+        /,
+    ) -> AsyncBoundSelect[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],
+        /,
+    ) -> AsyncBoundSelect[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],
+        /,
+    ) -> AsyncBoundSelect[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],
+        /,
+    ) -> AsyncBoundSelect[
+        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],
+        /,
+    ) -> AsyncBoundSelect[
+        tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8]
+    ]: ...
+
+    def select(  # type: ignore[misc]
+        self,
+        *values: object,
+    ) -> AsyncBoundSelect[tuple[object, ...]]:
+        build = cast("Callable[..., SelectQuery[tuple[object, ...]]]", select)
+        return AsyncBoundSelect(self._operations, build(*values))
+
+    def select_from(
+        self, table: ColumnedTable, /
+    ) -> AsyncBoundSelect[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 AsyncBoundSelect(self._operations, select_from(table))
+
+    @overload
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+    ) -> AsyncBoundInsert[Value1]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+    ) -> AsyncBoundInsert[Value1, Value2]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+    ) -> AsyncBoundInsert[Value1, Value2, Value3]: ...
+
+    @overload
+    def insert_into(
+        self,
+        table: TableLike,
+        /,
+        column1: Expression[Value1],
+        column2: Expression[Value2],
+        column3: Expression[Value3],
+        column4: Expression[Value4],
+    ) -> AsyncBoundInsert[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],
+    ) -> AsyncBoundInsert[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],
+    ) -> AsyncBoundInsert[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],
+    ) -> AsyncBoundInsert[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],
+    ) -> AsyncBoundInsert[
+        Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8
+    ]: ...
+
+    def insert_into(  # type: ignore[misc]
+        self,
+        table: TableLike,
+        /,
+        *columns: object,
+    ) -> AsyncBoundInsert[*tuple[object, ...]]:
+        build = cast("Callable[..., InsertStatement[*tuple[object, ...]]]", insert_into)
+        return AsyncBoundInsert(self._operations, build(table, *columns))
+
+    def update(self, table: TableLike, /) -> AsyncBoundUpdate:
+        return AsyncBoundUpdate(self._operations, update(table))
+
+    def delete_from(self, table: TableLike, /) -> AsyncBoundDelete:
+        return AsyncBoundDelete(self._operations, delete_from(table))
+
+    async 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(await 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__ = ("AsyncDslContext",)