sqlakit 0.12.0__tar.gz → 0.13.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.12.0
+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.12.0 → sqlakit-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.12.0"
+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.12.0 → sqlakit-0.13.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.12.0"
+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.12.0 → 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.12.0 → 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.12.0 → 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.12.0 → sqlakit-0.13.0}/sqlakit/pytest_plugin.py

@@ -286,6 +286,12 @@ 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())
@@ -301,7 +307,12 @@ 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):

{sqlakit-0.12.0 → 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.12.0 → 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`.