sqlakit 0.22.10__tar.gz → 0.22.12__tar.gz

{sqlakit-0.22.10 → sqlakit-0.22.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.22.10
+Version: 0.22.12
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -387,7 +388,7 @@ there is nothing to await.
 ## `FastAPI` integration
 
 ```python
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
@@ -400,7 +401,7 @@ db = Database("postgresql+psycopg://localhost/app")
 
 
 @asynccontextmanager
-async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
     yield
     await db.dispose()  # close the pool on shutdown
 

{sqlakit-0.22.10 → sqlakit-0.22.12}/README.md

@@ -356,7 +356,7 @@ there is nothing to await.
 ## `FastAPI` integration
 
 ```python
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
@@ -369,7 +369,7 @@ db = Database("postgresql+psycopg://localhost/app")
 
 
 @asynccontextmanager
-async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
     yield
     await db.dispose()  # close the pool on shutdown
 

{sqlakit-0.22.10 → sqlakit-0.22.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.22.10"
+version = "0.22.12"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -21,6 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Database",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
@@ -178,7 +179,7 @@ skip = "./.venv,./site,./uv.lock,./.git"
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.84",
+    "ty>=0.0.87",
     "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",

{sqlakit-0.22.10 → sqlakit-0.22.12}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.22.10"
+version = "0.22.12"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -16,6 +16,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Database",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
@@ -54,7 +55,7 @@ default-groups = ["dev", "docs"]
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.84",
+    "ty>=0.0.87",
     "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/_base.py

@@ -5,7 +5,7 @@ import inspect
 import random
 import threading
 import time
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Generator, Mapping
 from contextlib import ExitStack, contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass, replace
@@ -56,7 +56,7 @@ from .exceptions import (
 
 if TYPE_CHECKING:
     import logging
-    from collections.abc import Iterator, Sequence
+    from collections.abc import Sequence
     from os import PathLike
 
     from sqlalchemy.engine import Engine
@@ -232,6 +232,9 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
     """
 
     _engine: Any = None  # narrowed by the subclass
+    # The database to work on instead of this one, or None. Every public member
+    # checks it first, so a database without one pays one attribute read.
+    _override: Any = None
 
     def __init__(
         self,
@@ -299,6 +302,7 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         self._listened: Any = None
         self._listening_lock = threading.Lock()
         self._name = alias or DEFAULT_ALIAS
+        self._override = None
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.url.render_as_string()!r})"
@@ -332,6 +336,8 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
             MissingSessionError: if no connection is bound.
 
         """
+        if self._override is not None:
+            return self._override.session
         try:
             scope = self._scope.get()
         except LookupError:
@@ -358,7 +364,7 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         skip_queries_from: Sequence[str | PathLike[str]] = (),
         into: Recording | None = None,
         send_to: Callable[[Recording], object] | None = None,
-    ) -> Iterator[Recording]:
+    ) -> Generator[Recording]:
         """Record the statements of this block, and what they add up to.
 
         ```python
@@ -384,6 +390,18 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         after. `with` is right on either side, awaited or not: it listens, it does
         not run anything.
         """
+        if self._override is not None:
+            with self._override.recording(
+                label,
+                logger=logger,
+                echo=echo,
+                stacks=stacks,
+                skip_queries_from=skip_queries_from,
+                into=into,
+                send_to=send_to,
+            ) as recording:
+                yield recording
+            return
         recording = Recording(label=label) if into is None else into
         self._listen()
         recordings = self._recordings.set((*self._recordings.get(), recording))
@@ -412,7 +430,7 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         *,
         at_most: int | None = None,
         duplicates: bool = True,
-    ) -> Iterator[Recording]:
+    ) -> Generator[Recording]:
         """Assert what the block asks of this database.
 
         ```python
@@ -507,6 +525,8 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
 
         False under ``connect()`` and ``autocommit()``, which open none.
         """
+        if self._override is not None:
+            return self._override.in_transaction()
         return self._outer.get(None) is not None
 
     @property
@@ -542,11 +562,13 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         this is False in a block that has only run statements on the
         connection. Reading it opens nothing.
         """
+        if self._override is not None:
+            return self._override.in_session()
         scope = self._scope.get(None)
         return scope is not None and scope.session is not None
 
     @contextmanager
-    def unbound(self) -> Iterator[None]:
+    def unbound(self) -> Generator[None]:
         """Hide the block open around this one, for the code inside to open its own.
 
         A test opens a transaction for the whole test, so code that reaches for
@@ -563,6 +585,10 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         A block opened inside still joins the transaction around it, and rolls
         back with it.
         """
+        if self._override is not None:
+            with self._override.unbound():
+                yield
+            return
         scope = self._scope.get(None)
         if scope is None:
             yield
@@ -617,9 +643,24 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         outer = self._outer_to_join()
         return outer, savepoint or rollback or bool(outer and outer.savepoint)
 
-    def _stand_in(self) -> Any:  # noqa: ANN401
-        """Return the database to open blocks on instead of this one, or None."""
-        return None
+    @contextmanager
+    def override(self, db: Self) -> Generator[Self]:
+        """Use another database in place of this one until the block ends.
+
+        ```python
+        with Database(TEST_URL) as test_db, db.override(test_db):
+            create_user("ada")  # runs on test_db
+        ```
+
+        Every thread sees it. The database stays open when the block ends, so
+        close it yourself.
+        """
+        before = self._override
+        self._override = None if db is self else db
+        try:
+            yield db
+        finally:
+            self._override = before
 
     def _outer_to_join(self) -> _Outer[ConnectionT] | None:
         """Return the outer transaction new blocks join, if there is one."""
@@ -816,6 +857,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         self._default: DatabaseT | None = None
         self._aliased: dict[str, DatabaseT] = {}
         self._overridden: dict[str, DatabaseT] = {}
+        self._override = None
         self._routers: tuple[Any, ...] = ()
         self._using: ContextVar[str | None] = ContextVar(
             f"{type(self).__name__}.using", default=None
@@ -824,7 +866,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
     def __repr__(self) -> str:
         if self._built_its_own:
             return super().__repr__()
-        held = self._stand_in()
+        held = self._override
         if held is None:
             return f"{type(self).__name__}(unconfigured)"
         return f"{type(self).__name__}({held!r})"
@@ -884,6 +926,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
             if self.is_configured:
                 raise DefaultAliasError
             self._default = self._named(alias, db)
+            self._follow_default()
             return
         if alias in self._aliased:
             raise AliasInUseError(alias)
@@ -901,7 +944,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         into: Recording | None = None,
         send_to: Callable[[Recording], object] | None = None,
         using: str | DatabaseT | Sequence[str | DatabaseT] | None = None,
-    ) -> Iterator[Recording]:
+    ) -> Generator[Recording]:
         """Record every database this registry has, not the default one alone.
 
         ```python
@@ -953,7 +996,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
                     send_to(together)
 
     @contextmanager
-    def unbound(self) -> Iterator[None]:
+    def unbound(self) -> Generator[None]:
         """Hide the block open on every database this registry holds."""
         with ExitStack() as stack:
             for alias in self.aliases:
@@ -981,7 +1024,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         db: DatabaseT,
         *,
         alias: str = DEFAULT_ALIAS,
-    ) -> Iterator[DatabaseT]:
+    ) -> Generator[DatabaseT]:
         """Use another database under an alias until the block ends.
 
         ```python
@@ -995,6 +1038,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         before = self._overridden.get(alias)
         named = getattr(db, "_name", None)
         self._overridden[alias] = self._named(alias, db)
+        self._follow_default()
         try:
             yield db
         finally:
@@ -1002,13 +1046,14 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
                 del self._overridden[alias]
             else:
                 self._overridden[alias] = before
+            self._follow_default()
             if named is not None:
                 db._name = named  # noqa: SLF001
 
-    def _stand_in(self) -> DatabaseT | None:
-        """Return the database the default alias leads to, if not this registry."""
+    def _follow_default(self) -> None:
+        """Work on the database the default alias leads to, unless it is this one."""
         held = self._overridden.get(DEFAULT_ALIAS, self._default)
-        return None if held is self else held
+        self._override = None if held is self else held
 
     def using(self, target: str | DatabaseT) -> _Using:
         """Return that database, standing in for the default one.
@@ -1130,7 +1175,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
     @property
     def is_configured(self) -> bool:
         """Whether this registry has a default database to reach."""
-        return "url" in self.__dict__ or self._stand_in() is not None
+        return "url" in self.__dict__ or self._override is not None
 
     @property
     def _built_its_own(self) -> bool:
@@ -1138,38 +1183,13 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         return "url" in self.__dict__
 
     if not TYPE_CHECKING:
-        # Hidden from type checkers, which keep reading these off `Database`
-        # and its asyncio twin, signatures and all.
-        def _proxy(name: str, *, attribute: bool = False) -> Any:  # noqa: ANN401, N805
-            """Proxy to the database this registry holds, or call its own.
-
-            A registry handed a default, or overridden for a block, proxies to
-            that database. One that `configure` built calls what it inherits,
-            which `super()` reaches.
-            """
-
-            def reach(self: Any, *args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
-                held = self._stand_in()
-                found = (
-                    getattr(held, name) if held is not None else getattr(super(), name)
-                )
-                return found if attribute else found(*args, **kwargs)
-
-            return property(reach) if attribute else reach
-
-        connection = _proxy("connection", attribute=True)
-        engine = _proxy("engine", attribute=True)
-        session = _proxy("session", attribute=True)
-        sql = _proxy("sql", attribute=True)
-        assert_queries = _proxy("assert_queries")
-        in_session = _proxy("in_session")
-        in_transaction = _proxy("in_transaction")
-        ping = _proxy("ping")
-        provisioned_tables = _proxy("provisioned_tables")
-        query = _proxy("query")
-        del _proxy
-        # `connect`, `autocommit`, `session_factory` and `transaction` are not
-        # proxied: the ones inherited look `_stand_in` up as the block opens.
+        # Hidden from type checkers, which read it off `Database`.
+        @property
+        def sql(self) -> Any:  # noqa: ANN401
+            """The templates of the default database, wherever it was built."""
+            if self._built_its_own or self._override is None:
+                return super().sql
+            return self._override.sql
 
     @overload
     def configure(

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/_db.py

@@ -29,7 +29,7 @@ from ._base import (
 from .exceptions import TransactionRolledBackError
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator, Sequence
+    from collections.abc import Callable, Generator, Sequence
     from types import TracebackType
 
     from sqlalchemy.engine import Engine
@@ -98,6 +98,8 @@ class Database(BaseDatabase[sa.Connection, Session]):
     @property
     def engine(self) -> Engine:
         """The underlying engine, created on first access."""
+        if self._override is not None:
+            return self._override.engine
         if self._engine is None:
             with self._engine_lock:
                 # Two threads reaching this at once would each build one, and
@@ -122,6 +124,8 @@ class Database(BaseDatabase[sa.Connection, Session]):
             MissingConnectionError: if no connection is bound.
 
         """
+        if self._override is not None:
+            return self._override.connection
         return self._reused(self._current_scope())
 
     def _create_session(self, connection: sa.Connection) -> Session:
@@ -147,9 +151,9 @@ class Database(BaseDatabase[sa.Connection, Session]):
         return cast("sa.Connection", scope.connection)
 
     @contextmanager
-    def connect(self) -> Iterator[sa.Connection]:
+    def connect(self) -> Generator[sa.Connection]:
         """Open a connection and bind it, or reuse the one already bound."""
-        elsewhere = self._stand_in()
+        elsewhere = self._override
         if elsewhere is not None:
             with elsewhere.connect() as connection:
                 yield connection
@@ -194,9 +198,9 @@ class Database(BaseDatabase[sa.Connection, Session]):
         return autocommit
 
     @contextmanager
-    def _autocommit(self) -> Iterator[sa.Connection]:
+    def _autocommit(self) -> Generator[sa.Connection]:
         """Open a connection in ``AUTOCOMMIT`` and bind it, or join the outer one."""
-        elsewhere = self._stand_in()
+        elsewhere = self._override
         if elsewhere is not None:
             with elsewhere.autocommit() as connection:
                 yield connection
@@ -324,14 +328,14 @@ class Database(BaseDatabase[sa.Connection, Session]):
         return transaction
 
     @contextmanager
-    def session_factory(self) -> Iterator[Session]:
+    def session_factory(self) -> Generator[Session]:
         """Open a session for the block, and bind it.
 
         The session arrives at once, the connection on its first query or
         flush, as ``sessionmaker()`` does it. Inside another block it runs on
         the connection already bound.
         """
-        elsewhere = self._stand_in()
+        elsewhere = self._override
         if elsewhere is not None:
             with elsewhere.session_factory() as session:
                 yield session
@@ -361,7 +365,7 @@ class Database(BaseDatabase[sa.Connection, Session]):
         *,
         commit: bool = False,
         autocommit: bool = False,
-    ) -> Iterator[sa.Connection]:
+    ) -> Generator[sa.Connection]:
         """Bind ``connection`` for the block, ending the session it opened.
 
         ``commit`` keeps that session's work. Closing a session that isolates
@@ -385,7 +389,7 @@ class Database(BaseDatabase[sa.Connection, Session]):
         metadata: sa.MetaData,
         *,
         tables: Sequence[sa.Table] | None = None,
-    ) -> Iterator[None]:
+    ) -> Generator[None]:
         """Create these tables here, and drop them when the block ends.
 
         A test session opens this once, around everything that needs a schema:
@@ -400,6 +404,10 @@ class Database(BaseDatabase[sa.Connection, Session]):
         Every table of the metadata unless ``tables`` names fewer, as a second
         database wants.
         """
+        if self._override is not None:
+            with self._override.provisioned_tables(metadata, tables=tables):
+                yield
+            return
         with self.transaction() as connection:
             metadata.create_all(connection, tables=tables)
         try:
@@ -410,6 +418,8 @@ class Database(BaseDatabase[sa.Connection, Session]):
 
     def ping(self) -> bool:
         """Whether the database answers."""
+        if self._override is not None:
+            return self._override.ping()
         try:
             with self.engine.connect() as connection:
                 connection.execute(sa.text("SELECT 1"))
@@ -487,7 +497,7 @@ class Transaction(ContextDecorator, AbstractContextManager["sa.Connection"]):
 
     def __enter__(self) -> sa.Connection:
         stack = ExitStack()
-        elsewhere = self.db._stand_in()  # noqa: SLF001
+        elsewhere = self.db._override  # noqa: SLF001
         if elsewhere is not None:
             connection = stack.enter_context(
                 elsewhere.transaction(

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/_model.py

@@ -53,7 +53,7 @@ DatabaseT = TypeVar("DatabaseT", bound="BaseDatabase[Any, Any]")
 class DatabaseSource(Protocol):
     """The registry an alias is looked up in: the importable one, or a stand-in."""
 
-    def __getitem__(self, alias: str) -> BaseDatabase[Any, Any]: ...
+    def __getitem__(self, alias: str, /) -> BaseDatabase[Any, Any]: ...
 
 
 class DatabaseDescriptor(Generic[DatabaseT]):

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/_registry.py

@@ -8,7 +8,7 @@ from ._base import _DatabaseRegistryMixin, default_backoff, late_bound
 from ._db import Database, RetryingTransaction
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator
+    from collections.abc import Callable, Generator
 
     from ._base import RetryOn
     from ._db import Transaction
@@ -40,7 +40,7 @@ class Databases(_DatabaseRegistryMixin[Database], Database):
     def transactions(
         self,
         **arguments: Any,  # noqa: ANN401
-    ) -> Iterator[None]:
+    ) -> Generator[None]:
         """Open a transaction on every database, not the default one alone.
 
         A single database needs `transaction(rollback=True)`. A test harness

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/_sql.py

@@ -6,7 +6,7 @@ import importlib.util
 import inspect
 import itertools
 import re
-from collections.abc import Mapping, Sized
+from collections.abc import Generator, Mapping, Sized
 from contextlib import contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass, is_dataclass
@@ -49,7 +49,7 @@ from .exceptions import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Iterator, Sequence
+    from collections.abc import Callable, Iterable, Sequence
 
     from pydantic import BaseModel, TypeAdapter
     from sqlalchemy.sql import Executable
@@ -86,7 +86,7 @@ _calls_kept: ContextVar[bool] = ContextVar("sqlakit.calls_kept", default=False)
 
 
 @contextmanager
-def calls_kept() -> Iterator[None]:
+def calls_kept() -> Generator[None]:
     """Write a call that cannot be made with the values at hand as the call itself.
 
     An editor shows a template rendered with made-up values, or with none: a

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/asyncio/_db.py

@@ -37,7 +37,7 @@ from sqlakit._base import (
 from sqlakit.exceptions import MissingConnectionError, TransactionRolledBackError
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Callable, Coroutine, Sequence
+    from collections.abc import AsyncGenerator, Callable, Coroutine, Sequence
     from types import TracebackType
 
     from sqlalchemy.ext.asyncio import AsyncTransaction
@@ -102,6 +102,8 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
     @property
     def engine(self) -> AsyncEngine:
         """The underlying engine, created on first access."""
+        if self._override is not None:
+            return self._override.engine
         if self._engine is None:
             with self._engine_lock:
                 # Two threads reaching this at once would each build one, and
@@ -127,6 +129,8 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
             MissingConnectionError: if no connection is bound.
 
         """
+        if self._override is not None:
+            return self._override.connection
         scope = self._current_scope()
         if scope.connection is None:
             cell = scope.checkout
@@ -143,6 +147,8 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
 
     async def _aconnection(self) -> AsyncConnection:
         """Return the bound connection, checking it out first if lazy."""
+        if self._override is not None:
+            return await self._override._aconnection()  # noqa: SLF001
         return await self._areused(self._current_scope())
 
     def _create_session(self, connection: AsyncConnection) -> AsyncSession:
@@ -181,9 +187,9 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         return cast("AsyncConnection", scope.connection)
 
     @asynccontextmanager
-    async def connect(self) -> AsyncIterator[AsyncConnection]:
+    async def connect(self) -> AsyncGenerator[AsyncConnection]:
         """Open a connection and bind it, or reuse the one already bound."""
-        elsewhere = self._stand_in()
+        elsewhere = self._override
         if elsewhere is not None:
             async with elsewhere.connect() as connection:
                 yield connection
@@ -228,9 +234,9 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         return autocommit
 
     @asynccontextmanager
-    async def _autocommit(self) -> AsyncIterator[AsyncConnection]:
+    async def _autocommit(self) -> AsyncGenerator[AsyncConnection]:
         """Open a connection in ``AUTOCOMMIT`` and bind it, or join the outer one."""
-        elsewhere = self._stand_in()
+        elsewhere = self._override
         if elsewhere is not None:
             async with elsewhere.autocommit() as connection:
                 yield connection
@@ -358,14 +364,14 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         return transaction
 
     @asynccontextmanager
-    async def session_factory(self) -> AsyncIterator[AsyncSession]:
+    async def session_factory(self) -> AsyncGenerator[AsyncSession]:
         """Open a session for the block, and bind it.
 
         The session arrives at once, the connection on its first query or
         flush, as ``async_sessionmaker()`` does it. Inside another block it
         runs on the connection already bound.
         """
-        elsewhere = self._stand_in()
+        elsewhere = self._override
         if elsewhere is not None:
             async with elsewhere.session_factory() as session:
                 yield session
@@ -395,7 +401,7 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         *,
         commit: bool = False,
         autocommit: bool = False,
-    ) -> AsyncIterator[AsyncConnection]:
+    ) -> AsyncGenerator[AsyncConnection]:
         """Bind ``connection`` for the block, ending the session it opened.
 
         ``commit`` keeps that session's work. Closing a session that isolates
@@ -419,7 +425,7 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         metadata: sa.MetaData,
         *,
         tables: Sequence[sa.Table] | None = None,
-    ) -> AsyncIterator[None]:
+    ) -> AsyncGenerator[None]:
         """Create these tables here, and drop them when the block ends.
 
         A test session opens this once, around everything that needs a schema:
@@ -434,6 +440,10 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         Every table of the metadata unless ``tables`` names fewer, as a second
         database wants.
         """
+        if self._override is not None:
+            async with self._override.provisioned_tables(metadata, tables=tables):
+                yield
+            return
         async with self.transaction() as connection:
             await connection.run_sync(metadata.create_all, tables=tables)
         try:
@@ -444,6 +454,8 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
 
     async def ping(self) -> bool:
         """Whether the database answers."""
+        if self._override is not None:
+            return await self._override.ping()
         try:
             async with self.engine.connect() as connection:
                 await connection.execute(sa.text("SELECT 1"))
@@ -527,7 +539,7 @@ class Transaction(
 
     async def __aenter__(self) -> AsyncConnection:
         stack = AsyncExitStack()
-        elsewhere = self.db._stand_in()  # noqa: SLF001
+        elsewhere = self.db._override  # noqa: SLF001
         if elsewhere is not None:
             connection = await stack.enter_async_context(
                 elsewhere.transaction(

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/asyncio/_registry.py

@@ -9,7 +9,7 @@ from sqlakit._base import _DatabaseRegistryMixin, default_backoff, late_bound
 from ._db import Database, RetryingTransaction
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Callable
+    from collections.abc import AsyncGenerator, Callable
 
     from sqlakit._base import RetryOn
 
@@ -41,7 +41,7 @@ class Databases(_DatabaseRegistryMixin[Database], Database):
     async def transactions(
         self,
         **arguments: Any,  # noqa: ANN401
-    ) -> AsyncIterator[None]:
+    ) -> AsyncGenerator[None]:
         """Open a transaction on every database, not the default one alone.
 
         A test harness with more than one database needs this, where a single

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/asyncio/orm.py

@@ -42,10 +42,16 @@ from sqlakit._query import (
 from sqlakit.exceptions import InstanceNotFoundError
 
 from ._db import Database
-from ._registry import Databases, db
+from ._registry import db
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Iterable, Mapping, Sequence
+    from collections.abc import (
+        AsyncGenerator,
+        AsyncIterator,
+        Iterable,
+        Mapping,
+        Sequence,
+    )
 
     from sqlalchemy.engine import CursorResult, Result, ScalarResult
     from sqlalchemy.orm import InstrumentedAttribute
@@ -611,8 +617,8 @@ class QueryDescriptor(Generic[QueryT]):
     def __init__(self, query_class: type[QueryT]) -> None:
         self.query_class = query_class
 
-    # `ClassVar` cannot hold a type variable, so the base declares the query
-    # every model has and a read narrows it to the model it is read from.
+    # `QueryDescriptor(Query)` reads as a query of the model it is read from,
+    # any other query class as itself.
     @overload
     def __get__(
         self: QueryDescriptor[Query[Any]],
@@ -644,16 +650,18 @@ class ModelMixin(BaseModel[Database]):
     [`set_db`][sqlakit.asyncio.orm.ModelMixin.set_db].
     """
 
-    __db__: ClassVar[str | Database] = DEFAULT_ALIAS
-    __dbs__: ClassVar[Databases] = db
+    __db__ = DEFAULT_ALIAS
+    __dbs__ = db
 
-    query: ClassVar[QueryDescriptor[Query[Any]]] = QueryDescriptor(Query)
+    # Not annotated: a model's `query = UserQuery.as_descriptor()` would take
+    # the declared type and read as `Query[User]`.
+    query = QueryDescriptor(Query)
 
     db: ClassVar[DatabaseDescriptor[Database]] = DatabaseDescriptor()
 
     @classmethod
     @asynccontextmanager
-    async def provisioned_tables(cls, alias: str | None = None) -> AsyncIterator[None]:
+    async def provisioned_tables(cls, alias: str | None = None) -> AsyncGenerator[None]:
         """Create the tables that belong on this model's database, and drop them after.
 
         A test session opens this once, around everything that needs a schema:
@@ -668,7 +676,7 @@ class ModelMixin(BaseModel[Database]):
         With models on more than one database, name the alias, and each database
         gets the tables of the models pointed at it.
         """
-        db = cls.db if alias is None else cls.__dbs__[alias]
+        db = cls.db if alias is None else cls.dbs[alias]
         async with db.provisioned_tables(cls.metadata, tables=tables_for(cls, db)):
             yield
 

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/asyncio/sql.py

@@ -256,9 +256,7 @@ class SQLQuery(SQLRows[sa.Row[Any]]):
 
         """
         require_pydantic()
-        return cast(
-            "SQLRows[OtherT]", self._as(SQLRows, type_=type_, validation=validation)
-        )
+        return self._as(SQLRows, type_=type_, validation=validation)
 
     def scalars(self) -> SQLRows[Any]:
         """Read the first column of each row instead of whole rows.

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/orm.py

@@ -40,11 +40,11 @@ from ._query import (
     orderable,
     ordered,
 )
-from ._registry import Databases, db
+from ._registry import db
 from .exceptions import InstanceNotFoundError
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator, Mapping, Sequence
+    from collections.abc import Generator, Iterable, Iterator, Mapping, Sequence
 
     from sqlalchemy.engine import CursorResult, Result, ScalarResult
     from sqlalchemy.orm import InstrumentedAttribute
@@ -593,8 +593,8 @@ class QueryDescriptor(Generic[QueryT]):
     def __init__(self, query_class: type[QueryT]) -> None:
         self.query_class = query_class
 
-    # `ClassVar` cannot hold a type variable, so the base declares the query
-    # every model has and a read narrows it to the model it is read from.
+    # `QueryDescriptor(Query)` reads as a query of the model it is read from,
+    # any other query class as itself.
     @overload
     def __get__(
         self: QueryDescriptor[Query[Any]],
@@ -625,16 +625,18 @@ class ModelMixin(BaseModel[Database]):
     importable registry, or one set with [`set_db`][sqlakit.orm.ModelMixin.set_db].
     """
 
-    __db__: ClassVar[str | Database] = DEFAULT_ALIAS
-    __dbs__: ClassVar[Databases] = db
+    __db__ = DEFAULT_ALIAS
+    __dbs__ = db
 
-    query: ClassVar[QueryDescriptor[Query[Any]]] = QueryDescriptor(Query)
+    # Not annotated: a model's `query = UserQuery.as_descriptor()` would take
+    # the declared type and read as `Query[User]`.
+    query = QueryDescriptor(Query)
 
     db: ClassVar[DatabaseDescriptor[Database]] = DatabaseDescriptor()
 
     @classmethod
     @contextmanager
-    def provisioned_tables(cls, alias: str | None = None) -> Iterator[None]:
+    def provisioned_tables(cls, alias: str | None = None) -> Generator[None]:
         """Create the tables that belong on this model's database, and drop them after.
 
         A test session opens this once, around everything that needs a schema:
@@ -649,7 +651,7 @@ class ModelMixin(BaseModel[Database]):
         With models on more than one database, name the alias, and each database
         gets the tables of the models pointed at it.
         """
-        db = cls.db if alias is None else cls.__dbs__[alias]
+        db = cls.db if alias is None else cls.dbs[alias]
         with db.provisioned_tables(cls.metadata, tables=tables_for(cls, db)):
             yield
 

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/pytest_plugin.py

@@ -55,7 +55,7 @@ from ._registry import db as importable_db
 from .exceptions import UnknownDatabaseError
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Iterator, Sequence
+    from collections.abc import AsyncIterator, Generator, Iterator, Sequence
 
     import sqlalchemy as sa
 
@@ -346,7 +346,7 @@ def assert_queries(sqlakit_db: Any) -> AssertQueries:  # noqa: ANN401
         at_most: int | None = None,
         duplicates: bool = True,
         using: Any = None,  # noqa: ANN401
-    ) -> Iterator[Recording]:
+    ) -> Generator[Recording]:
         require_expectation(count, at_most, duplicates)
         recording = Recording()
         with ExitStack() as stack:
@@ -402,7 +402,7 @@ async def _sqlakit_async_transaction(
 
 
 @contextmanager
-def _reported(request: pytest.FixtureRequest, db: Any) -> Iterator[None]:  # noqa: ANN401
+def _reported(request: pytest.FixtureRequest, db: Any) -> Generator[None]:  # noqa: ANN401
     """Record what the test runs, for the report, when one was asked for.
 
     The recording is named after the test and filed under the file it lives in,
@@ -435,7 +435,7 @@ def _named(node: pytest.Item) -> str:
 
 
 @contextmanager
-def _entered(blocks: list[Any]) -> Iterator[None]:
+def _entered(blocks: list[Any]) -> Generator[None]:
     """Hold these blocks open, awaiting the ones that need it.
 
     An `asyncio` database builds its schema in a coroutine, and this fixture is

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/sql.py

@@ -246,9 +246,7 @@ class SQLQuery(SQLRows[sa.Row[Any]]):
 
         """
         require_pydantic()
-        return cast(
-            "SQLRows[OtherT]", self._as(SQLRows, type_=type_, validation=validation)
-        )
+        return self._as(SQLRows, type_=type_, validation=validation)
 
     def scalars(self) -> SQLRows[Any]:
         """Read the first column of each row instead of whole rows.

{sqlakit-0.22.10 → sqlakit-0.22.12}/sqlakit/testing.py

@@ -12,7 +12,7 @@ from .exceptions import UnknownDatabaseError
 from .types import AssertQueries
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Generator
 
 __all__ = ["AssertQueries", "assert_queries"]
 
@@ -24,7 +24,7 @@ def assert_queries(
     at_most: int | None = None,
     duplicates: bool = True,
     using: str | Any = None,  # noqa: ANN401
-) -> Iterator[Recording]:
+) -> Generator[Recording]:
     """Assert what the block asks of the database.
 
     ```python