sqlakit 0.11.0__tar.gz → 0.12.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.11.0
+Version: 0.12.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -19,6 +19,7 @@ Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: sqlalchemy>=2.0.22
+Requires-Dist: typing-extensions>=4.13
 Requires-Dist: sqlalchemy[asyncio]>=2.0.22 ; extra == 'asyncio'
 Requires-Dist: sqlparse>=0.6.0 ; extra == 'debug'
 Requires-Dist: jinja2sql>=0.11.0 ; extra == 'sql'

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.11.0"
+version = "0.12.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -26,7 +26,10 @@ classifiers = [
     "Typing :: Typed",
 ]
 requires-python = ">=3.11"
-dependencies = ["sqlalchemy>=2.0.22"]
+dependencies = [
+    "sqlalchemy>=2.0.22",
+    "typing-extensions>=4.13",
+]
 
 [[project.authors]]
 name = "Anton Ruhlov"
@@ -180,8 +183,8 @@ skip = "./.venv,./site,./uv.lock,./.git,./debugserver/node_modules,./debugserver
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.75",
-    "ruff>=0.16.5",
+    "ty>=0.0.79",
+    "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
     "trio>=0.34.0",
@@ -208,5 +211,5 @@ docs = [
     "mkdocs>=1.6.1,<2",
     "mkdocs-material>=9.7.7",
     "mkdocstrings[python]>=1.0.6",
-    "ruff>=0.16.3",
+    "ruff>=0.16.6",
 ]

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.11.0"
+version = "0.12.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -23,6 +23,7 @@ classifiers = [
 requires-python = ">=3.11"
 dependencies = [
     "sqlalchemy>=2.0.22",
+    "typing-extensions>=4.13",
 ]
 
 [project.scripts]
@@ -60,8 +61,8 @@ default-groups = ["dev", "docs"]
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.75",
-    "ruff>=0.16.5",
+    "ty>=0.0.79",
+    "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
     "trio>=0.34.0",
@@ -88,7 +89,7 @@ docs = [
     "mkdocs>=1.6.1,<2",
     "mkdocs-material>=9.7.7",
     "mkdocstrings[python]>=1.0.6",
-    "ruff>=0.16.3",
+    "ruff>=0.16.6",
 ]
 
 [tool.pytest.ini_options]

{sqlakit-0.11.0 → 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)
@@ -479,9 +490,12 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         """
         return (self._name,)
 
-    def __getitem__(self, alias: str) -> Self:
+    def __getitem__(self, alias: str) -> Any:  # noqa: ANN401
         """Return this database, under the name it carries.
 
+        `Any` rather than `Self`, so a registry can narrow it to the databases
+        it holds.
+
         Raises:
             UnknownDatabaseError: if the alias is another database's.
 
@@ -503,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."""
@@ -863,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.0 → 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.0 → 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.
 

{sqlakit-0.11.0 → sqlakit-0.12.0}/sqlakit/types.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal, TypeAlias, TypedDict
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias
+
+from typing_extensions import TypedDict
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
@@ -27,8 +29,11 @@ TemplatesLike: TypeAlias = "str | Path | Sequence[str | Path] | Templates"
 """Where a database's SQL templates are: a path, several, or the object."""
 
 
-class EngineArgs(TypedDict, total=False):
-    """Keyword arguments accepted by [`sqlalchemy.create_engine`](https://docs.sqlalchemy.org/en/20/core/engines.html#sqlalchemy.create_engine)."""
+class EngineArgs(TypedDict, total=False, extra_items=Any):
+    """Keyword arguments accepted by [`sqlalchemy.create_engine`](https://docs.sqlalchemy.org/en/20/core/engines.html#sqlalchemy.create_engine).
+
+    The portable ones are listed. A dialect keyword is allowed too.
+    """
 
     connect_args: dict[str, Any]
     echo: bool | Literal["debug"]
@@ -61,10 +66,11 @@ class EngineArgs(TypedDict, total=False):
     use_insertmanyvalues: bool
 
 
-class SessionArgs(TypedDict, total=False):
+class SessionArgs(TypedDict, total=False, extra_items=Any):
     """Keyword arguments accepted by `sqlalchemy.orm.sessionmaker`.
 
-    No ``bind``: sessions bind to the connection of the surrounding block.
+    No ``bind``: sessions bind to the connection of the surrounding block. A
+    keyword this list does not have is allowed too.
     """
 
     autobegin: bool