sqlakit 0.11.1__tar.gz → 0.12.0__tar.gz

{sqlakit-0.11.1 → sqlakit-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.11.1
+Version: 0.12.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov

{sqlakit-0.11.1 → sqlakit-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.11.1"
+version = "0.12.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.11.1 → sqlakit-0.12.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.11.1"
+version = "0.12.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.11.1 → sqlakit-0.12.0}/sqlakit/_base.py

@@ -8,7 +8,7 @@ import time
 from collections.abc import Callable, Mapping
 from contextlib import ExitStack, contextmanager
 from contextvars import ContextVar
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from functools import cache
 from typing import (
     TYPE_CHECKING,
@@ -39,6 +39,7 @@ from ._recording import (
 from ._routing import Router, as_router
 from .exceptions import (
     DEFAULT_ALIAS,
+    HIDDEN_BLOCK,
     REGISTERED_DEFAULT,
     AliasInUseError,
     ConflictingDatabaseUrlError,
@@ -169,6 +170,9 @@ class _Scope(Generic[ConnectionT, SessionT]):
     autocommit: bool = False
     """Whether the connection is in ``AUTOCOMMIT``, where no transaction runs."""
 
+    hidden: bool = False
+    """Whether `unbound()` hides this scope from the code running under it."""
+
 
 @dataclass(slots=True)
 class _Outer(Generic[ConnectionT]):
@@ -279,9 +283,14 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
 
         """
         try:
-            return self._scope.get()
+            scope = self._scope.get()
         except LookupError:
             raise MissingConnectionError from None
+        if scope.hidden:
+            raise MissingConnectionError(
+                HIDDEN_BLOCK.format(what="connection")
+            ) from None
+        return scope
 
     @property
     def session(self) -> SessionT:
@@ -299,6 +308,8 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
             scope = self._scope.get()
         except LookupError:
             raise MissingSessionError from None
+        if scope.hidden:
+            raise MissingSessionError(HIDDEN_BLOCK.format(what="session")) from None
         if scope.session is None:
             if scope.connection is None and scope.checkout is not None:
                 scope.session = self._lazy_session(scope.checkout)
@@ -506,6 +517,34 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         scope = self._scope.get(None)
         return scope is not None and scope.session is not None
 
+    @contextmanager
+    def unbound(self) -> Iterator[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
+        `session` without a block of its own borrows one and passes, where in
+        production it raises `MissingSessionError`. Wrap the call under test:
+
+        ```python
+        @pytest.mark.db
+        def test_the_handler_opens_a_block() -> None:
+            with db.unbound():
+                handle(event)
+        ```
+
+        A block opened inside still joins the transaction around it, and rolls
+        back with it.
+        """
+        scope = self._scope.get(None)
+        if scope is None:
+            yield
+            return
+        token = self._scope.set(replace(scope, session=None, hidden=True))
+        try:
+            yield
+        finally:
+            self._scope.reset(token)
+
     @property
     def engine(self) -> Any:  # noqa: ANN401
         """The engine underneath, which the subclass makes."""
@@ -866,6 +905,14 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
                 if debugserver is not None:
                     send_recording(together, debugserver)
 
+    @contextmanager
+    def unbound(self) -> Iterator[None]:
+        """Hide the block open on every database this registry holds."""
+        with ExitStack() as stack:
+            for alias in self.aliases:
+                stack.enter_context(BaseDatabase.unbound(self[alias]))
+            yield
+
     def _recorded(
         self, using: str | DatabaseT | Sequence[str | DatabaseT] | None
     ) -> tuple[Any, ...]:

{sqlakit-0.11.1 → sqlakit-0.12.0}/sqlakit/exceptions.py

@@ -85,6 +85,14 @@ class RetryNotSupportedError(SQLAKitError, TypeError):
         super().__init__(message)
 
 
+HIDDEN_BLOCK = (
+    "No {what} is bound: the block around this one is hidden, so the code "
+    "under it opens its own. `with db.transaction():` to write, "
+    "`with db.connect():` to read. A test hides its block with "
+    "`sqlakit_unbound`, `db(unbound=True)` or `db.unbound()`."
+)
+"""What the two errors above say under a hidden block, which a test opens."""
+
 REGISTERED_DEFAULT = (
     "This registry did not build the default database, it was registered, so "
     "the settings it was built from live on it. Read them from `db['default']`."

{sqlakit-0.11.1 → sqlakit-0.12.0}/sqlakit/pytest_plugin.py

@@ -19,13 +19,18 @@ up in, or the one they were given in person. A project with no model layer
 defines `sqlakit_db` and `sqlakit_metadata` instead.
 
 A test marked `db` runs in a transaction that rolls back, on every database.
-`using` narrows that to the ones a test works on:
+`using` narrows that to the ones a test works on, and `unbound` hides the
+test's own block from the code it calls, as production has none:
 
 ```python
 @pytest.mark.db(using="warehouse")
 @pytest.mark.db(using=["default", "warehouse"])
+@pytest.mark.db(unbound=True)
 ```
 
+`sqlakit_unbound = true` says the last one for the whole suite, and
+`db(unbound=False)` gives one test its block back.
+
 Every other test connects to nothing, and reaching for a session there raises
 `MissingSessionError` rather than opening one.
 """
@@ -66,6 +71,12 @@ def pytest_addoption(parser: pytest.Parser) -> None:
         type="bool",
         default=False,
     )
+    parser.addini(
+        "sqlakit_unbound",
+        "hide the test's own block, so the code it calls opens one as in production",
+        type="bool",
+        default=False,
+    )
     parser.addini(
         "sqlakit_skip_queries_from",
         "the queries these files run stay out of the report: a factory, a helper",
@@ -276,6 +287,8 @@ def _sqlakit_transaction(
     with ExitStack() as stack:
         for block in _rolled_back(sqlakit_db, _asked_for(request)):
             stack.enter_context(block)
+        if _hidden(request):
+            stack.enter_context(sqlakit_db.unbound())
         with _reported(request, sqlakit_db):
             yield
 
@@ -289,6 +302,8 @@ async def _sqlakit_async_transaction(
     async with AsyncExitStack() as stack:
         for block in _rolled_back(sqlakit_db, _asked_for(request)):
             await stack.enter_async_context(block)
+        if _hidden(request):
+            stack.enter_context(sqlakit_db.unbound())
         with _reported(request, sqlakit_db):
             yield
 
@@ -385,6 +400,19 @@ def _asked_for(request: pytest.FixtureRequest) -> tuple[Any, ...]:
     return tuple(using)
 
 
+def _hidden(request: pytest.FixtureRequest) -> bool:
+    """Whether the test's own block is hidden from the code it calls.
+
+    `sqlakit_unbound` says it for the suite, and `db(unbound=...)` on a test
+    says it for that one.
+    """
+    marker = request.node.get_closest_marker(MARKER)
+    asked = None if marker is None else marker.kwargs.get("unbound")
+    if asked is None:
+        return bool(request.config.getini("sqlakit_unbound"))
+    return bool(asked)
+
+
 def _rolled_back(db: Any, using: tuple[Any, ...]) -> list[Any]:  # noqa: ANN401
     """Return the blocks that undo what a test writes.