sqlakit 0.11.1__tar.gz → 0.13.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.11.1
+Version: 0.13.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -22,7 +22,7 @@ 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'
+Requires-Dist: jinja2sql>=0.12.0 ; extra == 'sql'
 Requires-Python: >=3.11
 Project-URL: Repository, https://github.com/antonrh/sqlakit
 Project-URL: Documentation, https://github.com/antonrh/sqlakit

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.11.1"
+version = "0.13.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -47,7 +47,7 @@ Documentation = "https://github.com/antonrh/sqlakit"
 
 [project.optional-dependencies]
 asyncio = ["sqlalchemy[asyncio]>=2.0.22"]
-sql = ["jinja2sql>=0.11.0"]
+sql = ["jinja2sql>=0.12.0"]
 debug = ["sqlparse>=0.6.0"]
 
 [build-system]
@@ -183,7 +183,7 @@ skip = "./.venv,./site,./uv.lock,./.git,./debugserver/node_modules,./debugserver
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.79",
+    "ty>=0.0.80",
     "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
@@ -194,7 +194,7 @@ dev = [
     "httpx>=0.28.1",
     "httpx2>=2.10.0",
     "sqlmodel>=0.0.39",
-    "jinja2sql>=0.11.0",
+    "jinja2sql>=0.12.0",
     "pydantic>=2.13.4",
     "sqlparse>=0.6.0",
     "rich>=15.0.0",

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.11.1"
+version = "0.13.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -41,7 +41,7 @@ asyncio = [
     "sqlalchemy[asyncio]>=2.0.22",
 ]
 sql = [
-    "jinja2sql>=0.11.0",
+    "jinja2sql>=0.12.0",
 ]
 debug = [
     "sqlparse>=0.6.0",
@@ -61,7 +61,7 @@ default-groups = ["dev", "docs"]
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.79",
+    "ty>=0.0.80",
     "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
@@ -72,7 +72,7 @@ dev = [
     "httpx>=0.28.1",
     "httpx2>=2.10.0",
     "sqlmodel>=0.0.39",
-    "jinja2sql>=0.11.0",
+    "jinja2sql>=0.12.0",
     "pydantic>=2.13.4",
     "sqlparse>=0.6.0",
     "rich>=15.0.0",

{sqlakit-0.11.1 → sqlakit-0.13.0}/sqlakit/__init__.py

@@ -60,6 +60,7 @@ from .types import (
     SessionArgs,
     TemplatesLike,
     UrlParts,
+    ValidationArgs,
 )
 
 __all__ = [
@@ -122,6 +123,7 @@ __all__ = [
     "UnknownOrderFieldError",
     "UnorderedPageError",
     "UrlParts",
+    "ValidationArgs",
     "db",
     "import_models",
     "import_string",

{sqlakit-0.11.1 → sqlakit-0.13.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.13.0}/sqlakit/_sql.py

@@ -42,7 +42,13 @@ else:
     except ImportError:  # pragma: no cover - pydantic is installed in CI
         BaseModel = TypeAdapter = None
 
-__all__ = ["BaseSQLQuery", "Templates", "require_pydantic", "templates_of"]
+__all__ = [
+    "BaseSQLQuery",
+    "Filter",
+    "Templates",
+    "require_pydantic",
+    "templates_of",
+]
 
 _preparer: ContextVar[Any] = ContextVar("sqlakit.identifier_preparer")
 """The preparer of the database a template is rendering for."""
@@ -57,6 +63,38 @@ PathLike = str | Path
 """Where templates are looked for: one directory, or several."""
 
 
+class Filter:
+    """A template filter, registered the way jinja2sql registers one.
+
+    ```python
+    Templates("app/sql", filters={"in_span": Filter(in_span, bind=True)})
+    ```
+
+    ``bind=True`` calls the filter with a jinja2sql `Binder` as its first
+    argument, so a filter writing SQL of its own binds the values through it:
+
+    ```python
+    def in_span(binder, span):
+        start, end = span
+        return binder.raw(
+            f"BETWEEN {binder.bind('span', start)} AND {binder.bind('span', end)}"
+        )
+    ```
+
+    A plain function needs none of this and goes in as it is: whatever it
+    returns is bound as one more value of the statement.
+    """
+
+    __slots__ = ("bind", "func")
+
+    def __init__(self, func: Callable[..., Any], *, bind: bool = False) -> None:
+        self.func = func
+        self.bind = bind
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.func!r}, bind={self.bind})"
+
+
 class Templates:
     """The directory a database's SQL templates live in, and how they render.
 
@@ -70,6 +108,10 @@ class Templates:
     development server wants and a production one does not. ``filters`` and
     ``globals`` are handed to the Jinja environment, and are refused if they have
     to be awaited: rendering makes a string, in both APIs.
+
+    A filter is a plain function, whose return value is bound as one more value
+    of the statement. `Filter(func, bind=True)` registers one that writes SQL of
+    its own instead, and is handed a binder for the values inside it.
     """
 
     def __init__(
@@ -77,7 +119,7 @@ class Templates:
         path: PathLike | Sequence[PathLike] = (),
         *,
         auto_reload: bool = False,
-        filters: Mapping[str, Callable[..., Any]] | None = None,
+        filters: Mapping[str, Callable[..., Any] | Filter] | None = None,
         globals: Mapping[str, Any] | None = None,  # noqa: A002
     ) -> None:
         self.paths = (
@@ -87,7 +129,8 @@ class Templates:
         self.filters = dict(filters or {})
         self.globals = dict(globals or {})
         for name, value in (*self.filters.items(), *self.globals.items()):
-            if iscoroutinefunction(value):
+            called = value.func if isinstance(value, Filter) else value
+            if iscoroutinefunction(called):
                 raise AsyncFilterError(name)
 
     def __repr__(self) -> str:
@@ -109,17 +152,15 @@ class Templates:
             autoescape=True,
         )
         environment.globals.update(self.globals)
-        # Always named parameters: what comes back is handed to `text()`,
-        # which reads `:name` and nothing else. The driver's own style is
-        # SQLAlchemy's business, and a template that picked one would be wrong
-        # on the next database.
+        # Named parameters: `text()` reads `:name` and nothing else.
         renderer = jinja2sql(environment, param_style=_placeholder)
-        # Ours rather than jinja2sql's: the preparer of the database in hand
-        # knows both how it quotes and when it has to, which is the difference
-        # between `"name"` and `name` on Oracle.
+        # Ours quotes through the dialect's preparer, jinja2sql's through one char.
         renderer.register_filter("identifier", _identifier)
         for name, filter_ in self.filters.items():
-            renderer.register_filter(name, filter_)
+            if isinstance(filter_, Filter):
+                renderer.register_filter(name, filter_.func, bind=filter_.bind)
+            else:
+                renderer.register_filter(name, filter_)
         return renderer
 
     def render(
@@ -152,8 +193,7 @@ class Templates:
                     raise TemplateNotFoundError(source, self.paths) from None
         finally:
             _preparer.reset(token)
-        # Always a mapping: the parameters are named, and only a positional
-        # style would hand back a sequence.
+        # Named parameters come back as a mapping, positional ones as a sequence.
         return sql, cast("Mapping[str, Any]", params)
 
     def check(self) -> None:
@@ -188,6 +228,7 @@ class BaseSQLQuery(Generic[RowT, DatabaseT]):
         inline: bool = False,
         type_: type[Any] | None = None,
         scalar: bool = False,
+        validation: Mapping[str, Any] | None = None,
     ) -> None:
         self.db = db
         self.source = source
@@ -195,6 +236,7 @@ class BaseSQLQuery(Generic[RowT, DatabaseT]):
         self.inline = inline
         self.type = type_
         self.scalar = scalar
+        self.validation = dict(validation or {})
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.source!r})"
@@ -237,6 +279,7 @@ class BaseSQLQuery(Generic[RowT, DatabaseT]):
             "inline": self.inline,
             "type_": self.type,
             "scalar": self.scalar,
+            "validation": self.validation,
             **changes,
         }
         return query(self.db, self.source, self.context, **arguments)
@@ -245,12 +288,17 @@ class BaseSQLQuery(Generic[RowT, DatabaseT]):
         if self.type is None:
             return rows
         adapter = _adapter(self.type)
-        return [adapter.validate_python(_as_python(row, self.type)) for row in rows]
+        return [
+            adapter.validate_python(_as_python(row, self.type), **self.validation)
+            for row in rows
+        ]
 
     def _shaped_one(self, row: Any) -> Any:  # noqa: ANN401
         if self.type is None or row is None:
             return row
-        return _adapter(self.type).validate_python(_as_python(row, self.type))
+        return _adapter(self.type).validate_python(
+            _as_python(row, self.type), **self.validation
+        )
 
     def _executable(self, *, size: int | None = None) -> Executable:
         if size is None:

{sqlakit-0.11.1 → sqlakit-0.13.0}/sqlakit/asyncio/sql.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, TypeVar, cast
 
 import sqlalchemy as sa
+from typing_extensions import Unpack
 
 from sqlakit._sql import (
     BaseSQLQuery,
+    Filter,
     Templates,
     require_pydantic,
     templates_of,
@@ -18,9 +20,11 @@ if TYPE_CHECKING:
     from sqlalchemy.ext.asyncio import AsyncConnection
     from sqlalchemy.sql import Executable
 
+    from sqlakit.types import ValidationArgs
+
     from ._db import Database
 
-__all__ = ["SQL", "SQLQuery", "SQLRows", "Templates"]
+__all__ = ["SQL", "Filter", "SQLQuery", "SQLRows", "Templates"]
 
 RowT = TypeVar("RowT")
 OtherT = TypeVar("OtherT")
@@ -189,11 +193,13 @@ class SQLQuery(SQLRows[sa.Row[Any]]):
     same way and carry no further say, so each is asked once.
     """
 
-    def typed(self, type_: type[OtherT], /) -> SQLRows[OtherT]:
+    def typed(
+        self, type_: type[OtherT], /, **validation: Unpack[ValidationArgs]
+    ) -> SQLRows[OtherT]:
         """Read the rows as this type, one row at a time.
 
         ```python
-        await db.sql("reports/by_team.sql", since=since).typed(TeamReport).all()
+        db.sql("reports/by_team.sql", since=since).typed(TeamReport).all()
         ```
 
         The type says what one row becomes, and the terminal decides the container.
@@ -202,12 +208,21 @@ class SQLQuery(SQLRows[sa.Row[Any]]):
         from columns is given the whole row, and anything else is given the
         first column, so `SELECT count(*)` with `typed(int)` reads as an `int`.
 
+        Keyword arguments go to pydantic's `validate_python`, `context` and
+        `strict` among them:
+
+        ```python
+        db.sql("reports/by_team.sql").typed(TeamReport, context={"tz": tz}).all()
+        ```
+
         Raises:
             MissingDependencyError: if pydantic is not installed.
 
         """
         require_pydantic()
-        return cast("SQLRows[OtherT]", self._as(SQLRows, type_=type_))
+        return cast(
+            "SQLRows[OtherT]", 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.11.1 → sqlakit-0.13.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.13.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",
@@ -275,7 +286,15 @@ def _sqlakit_transaction(
 ) -> Iterator[None]:
     with ExitStack() as stack:
         for block in _rolled_back(sqlakit_db, _asked_for(request)):
+            if hasattr(block, "__aenter__"):
+                pytest.fail(
+                    f"`{request.node.name}` runs on an async database, whose "
+                    "blocks are awaited. Write the test as `async def`.",
+                    pytrace=False,
+                )
             stack.enter_context(block)
+        if _hidden(request):
+            stack.enter_context(sqlakit_db.unbound())
         with _reported(request, sqlakit_db):
             yield
 
@@ -288,7 +307,14 @@ async def _sqlakit_async_transaction(
 ) -> AsyncIterator[None]:
     async with AsyncExitStack() as stack:
         for block in _rolled_back(sqlakit_db, _asked_for(request)):
-            await stack.enter_async_context(block)
+            # A synchronous database under a test that awaits something else,
+            # a handler it runs in a worker thread among them.
+            if hasattr(block, "__aenter__"):
+                await stack.enter_async_context(block)
+            else:
+                stack.enter_context(block)
+        if _hidden(request):
+            stack.enter_context(sqlakit_db.unbound())
         with _reported(request, sqlakit_db):
             yield
 
@@ -385,6 +411,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.1 → sqlakit-0.13.0}/sqlakit/sql.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, TypeVar, cast
 
 import sqlalchemy as sa
+from typing_extensions import Unpack
 
 from ._sql import (
     BaseSQLQuery,
+    Filter,
     Templates,
     require_pydantic,
     templates_of,
@@ -18,8 +20,9 @@ if TYPE_CHECKING:
     from sqlalchemy.sql import Executable
 
     from ._db import Database
+    from .types import ValidationArgs
 
-__all__ = ["SQL", "SQLQuery", "SQLRows", "Templates"]
+__all__ = ["SQL", "Filter", "SQLQuery", "SQLRows", "Templates"]
 
 RowT = TypeVar("RowT")
 OtherT = TypeVar("OtherT")
@@ -178,7 +181,9 @@ class SQLQuery(SQLRows[sa.Row[Any]]):
     same way and carry no further say, so each is asked once.
     """
 
-    def typed(self, type_: type[OtherT], /) -> SQLRows[OtherT]:
+    def typed(
+        self, type_: type[OtherT], /, **validation: Unpack[ValidationArgs]
+    ) -> SQLRows[OtherT]:
         """Read the rows as this type, one row at a time.
 
         ```python
@@ -191,12 +196,21 @@ class SQLQuery(SQLRows[sa.Row[Any]]):
         from columns is given the whole row, and anything else is given the
         first column, so `SELECT count(*)` with `typed(int)` reads as an `int`.
 
+        Keyword arguments go to pydantic's `validate_python`, `context` and
+        `strict` among them:
+
+        ```python
+        db.sql("reports/by_team.sql").typed(TeamReport, context={"tz": tz}).all()
+        ```
+
         Raises:
             MissingDependencyError: if pydantic is not installed.
 
         """
         require_pydantic()
-        return cast("SQLRows[OtherT]", self._as(SQLRows, type_=type_))
+        return cast(
+            "SQLRows[OtherT]", 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.11.1 → sqlakit-0.13.0}/sqlakit/types.py

@@ -21,6 +21,7 @@ __all__ = [
     "SessionArgs",
     "TemplatesLike",
     "UrlParts",
+    "ValidationArgs",
 ]
 
 # Quoted, so importing this module never reaches `Templates` and the
@@ -66,6 +67,22 @@ class EngineArgs(TypedDict, total=False, extra_items=Any):
     use_insertmanyvalues: bool
 
 
+class ValidationArgs(TypedDict, total=False, extra_items=Any):
+    """Keyword arguments accepted by [`pydantic.TypeAdapter.validate_python`](https://docs.pydantic.dev/latest/api/type_adapter/#pydantic.type_adapter.TypeAdapter.validate_python).
+
+    `typed()` hands them to pydantic for every row it reads. A keyword a later
+    pydantic adds is allowed too.
+    """
+
+    strict: bool | None
+    extra: Literal["allow", "ignore", "forbid"] | None
+    from_attributes: bool | None
+    context: Any
+    experimental_allow_partial: bool | Literal["off", "on", "trailing-strings"]
+    by_alias: bool | None
+    by_name: bool | None
+
+
 class SessionArgs(TypedDict, total=False, extra_items=Any):
     """Keyword arguments accepted by `sqlalchemy.orm.sessionmaker`.