sqlakit 0.1.0__tar.gz → 0.2.0__tar.gz

{sqlakit-0.1.0 → sqlakit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.1.0
+Version: 0.2.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Dist: sqlalchemy[asyncio]>=2.0.43
+Requires-Dist: sqlalchemy[asyncio]>=2.0.22
 Requires-Dist: sqlparse>=0.6.0 ; extra == 'debug'
 Requires-Dist: jinja2sql>=0.11.0 ; extra == 'sql'
 Requires-Python: >=3.11
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 # SQLAKit
 
-SQLAKit removes the boilerplate from `SQLAlchemy` applications. It manages
+`SQLAKit` removes the boilerplate from `SQLAlchemy` applications. It manages
 sessions and transactions for you, and adds a query builder with pagination
 built in, `SQL` templates, an optional `Active Record` layer, debugging and
 testing tools, etc. It supports both sync and async APIs and works with any
@@ -65,7 +65,7 @@ def get_or_create_user(email: str, name: str) -> User:
     return user
 ```
 
-Both functions use the same session without passing it around. The
+Both functions use the same session, and you don't pass it between them. The
 `@db.transaction` decorator opens it, and commits when the function returns.
 
 Outside a block there is no session: `db.session` raises `MissingSessionError`
@@ -92,8 +92,8 @@ with db.autocommit():  # AUTOCOMMIT, no transaction held open
 Templates are `Jinja` files, so they can hold anything from a one-line query to
 a report with window functions or a recursive CTE.
 [jinja2sql](https://github.com/antonrh/jinja2sql) turns every `{{ name }}` into
-a bound parameter (`:name__1`), so values never end up in the SQL text and
-there is no way to inject anything. Requires the `sqlakit[sql]` extra.
+a bound parameter (`:name__1`), so values never reach the SQL text and there
+is no way to inject anything. Requires the `sqlakit[sql]` extra.
 
 ### From a file
 
@@ -125,8 +125,8 @@ db.sql("reports/by_team.sql", since=since).typed(TeamReport).all()
 `templates=` sets the directory to load templates from, and `typed()` sets the
 type each row is returned as.
 
-The template name is added to the SQL as a comment, so a slow query log shows
-right away which file a query came from.
+`SQLAKit` adds the template name to the SQL as a comment, so a slow query log
+shows the source file of each query right away.
 
 ### From a string
 
@@ -150,8 +150,8 @@ db.query(User).where(User.is_active).order_by(User.name).all()
 ### Ordering by a string
 
 `order_by` accepts a `field.direction` string, for example straight from a
-query parameter. The field name is checked against the model before any SQL is
-built, so an unknown field never reaches the database. Instead you get
+query parameter. `SQLAKit` checks the field name against the model before it
+builds any SQL, so an unknown field never reaches the database. Instead you get
 `UnknownOrderFieldError`, and its message lists the fields the model allows:
 
 ```python
@@ -173,7 +173,7 @@ page.has_next
 ### Cursor pagination
 
 `cursor_page()` continues from a cursor, so it stays fast at any depth. There
-is no total; instead you get cursors to the next and previous pages:
+is no total. Instead you get cursors to the next and previous pages:
 
 ```python
 feed = db.query(User).order_by("created_at.desc").cursor_page(limit=20)
@@ -223,8 +223,8 @@ entirely.
 
 ## Testing
 
-A test runs inside a transaction that is rolled back at the end, so nothing
-the code under test writes is actually committed. `assert_queries` checks how
+A test runs inside a transaction that rolls back at the end, so nothing the
+code under test writes is actually committed. `assert_queries` checks how
 many statements a block runs:
 
 ```python
@@ -249,7 +249,7 @@ record.milliseconds
 record.duplicates
 ```
 
-With `logger=` one line is logged at the end of the block. The log level
+With `logger=` `SQLAKit` logs one line at the end of the block. The log level
 depends on the numbers: more statements and more repeats mean a higher level.
 
 With `echo=True` the block prints each statement, formatted and with repeats
@@ -394,8 +394,8 @@ Use the `Database` from `sqlakit.asyncio` here. With the sync one the block
 closes before the async handler runs, and the handler fails with
 `MissingConnectionError`.
 
-There is nothing to open at startup: the engine is created on first use. On
-shutdown, `dispose()` closes the pool.
+There is nothing to open at startup: `SQLAKit` creates the engine on first use.
+On shutdown, `dispose()` closes the pool.
 
 ## Documentation
 

{sqlakit-0.1.0 → sqlakit-0.2.0}/README.md

@@ -1,6 +1,6 @@
 # SQLAKit
 
-SQLAKit removes the boilerplate from `SQLAlchemy` applications. It manages
+`SQLAKit` removes the boilerplate from `SQLAlchemy` applications. It manages
 sessions and transactions for you, and adds a query builder with pagination
 built in, `SQL` templates, an optional `Active Record` layer, debugging and
 testing tools, etc. It supports both sync and async APIs and works with any
@@ -35,7 +35,7 @@ def get_or_create_user(email: str, name: str) -> User:
     return user
 ```
 
-Both functions use the same session without passing it around. The
+Both functions use the same session, and you don't pass it between them. The
 `@db.transaction` decorator opens it, and commits when the function returns.
 
 Outside a block there is no session: `db.session` raises `MissingSessionError`
@@ -62,8 +62,8 @@ with db.autocommit():  # AUTOCOMMIT, no transaction held open
 Templates are `Jinja` files, so they can hold anything from a one-line query to
 a report with window functions or a recursive CTE.
 [jinja2sql](https://github.com/antonrh/jinja2sql) turns every `{{ name }}` into
-a bound parameter (`:name__1`), so values never end up in the SQL text and
-there is no way to inject anything. Requires the `sqlakit[sql]` extra.
+a bound parameter (`:name__1`), so values never reach the SQL text and there
+is no way to inject anything. Requires the `sqlakit[sql]` extra.
 
 ### From a file
 
@@ -95,8 +95,8 @@ db.sql("reports/by_team.sql", since=since).typed(TeamReport).all()
 `templates=` sets the directory to load templates from, and `typed()` sets the
 type each row is returned as.
 
-The template name is added to the SQL as a comment, so a slow query log shows
-right away which file a query came from.
+`SQLAKit` adds the template name to the SQL as a comment, so a slow query log
+shows the source file of each query right away.
 
 ### From a string
 
@@ -120,8 +120,8 @@ db.query(User).where(User.is_active).order_by(User.name).all()
 ### Ordering by a string
 
 `order_by` accepts a `field.direction` string, for example straight from a
-query parameter. The field name is checked against the model before any SQL is
-built, so an unknown field never reaches the database. Instead you get
+query parameter. `SQLAKit` checks the field name against the model before it
+builds any SQL, so an unknown field never reaches the database. Instead you get
 `UnknownOrderFieldError`, and its message lists the fields the model allows:
 
 ```python
@@ -143,7 +143,7 @@ page.has_next
 ### Cursor pagination
 
 `cursor_page()` continues from a cursor, so it stays fast at any depth. There
-is no total; instead you get cursors to the next and previous pages:
+is no total. Instead you get cursors to the next and previous pages:
 
 ```python
 feed = db.query(User).order_by("created_at.desc").cursor_page(limit=20)
@@ -193,8 +193,8 @@ entirely.
 
 ## Testing
 
-A test runs inside a transaction that is rolled back at the end, so nothing
-the code under test writes is actually committed. `assert_queries` checks how
+A test runs inside a transaction that rolls back at the end, so nothing the
+code under test writes is actually committed. `assert_queries` checks how
 many statements a block runs:
 
 ```python
@@ -219,7 +219,7 @@ record.milliseconds
 record.duplicates
 ```
 
-With `logger=` one line is logged at the end of the block. The log level
+With `logger=` `SQLAKit` logs one line at the end of the block. The log level
 depends on the numbers: more statements and more repeats mean a higher level.
 
 With `echo=True` the block prints each statement, formatted and with repeats
@@ -364,8 +364,8 @@ Use the `Database` from `sqlakit.asyncio` here. With the sync one the block
 closes before the async handler runs, and the handler fails with
 `MissingConnectionError`.
 
-There is nothing to open at startup: the engine is created on first use. On
-shutdown, `dispose()` closes the pool.
+There is nothing to open at startup: `SQLAKit` creates the engine on first use.
+On shutdown, `dispose()` closes the pool.
 
 ## Documentation
 

{sqlakit-0.1.0 → sqlakit-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.1.0"
+version = "0.2.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -26,7 +26,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 requires-python = ">=3.11"
-dependencies = ["sqlalchemy[asyncio]>=2.0.43"]
+dependencies = ["sqlalchemy[asyncio]>=2.0.22"]
 
 [[project.authors]]
 name = "Anton Ruhlov"

{sqlakit-0.1.0 → sqlakit-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.1.0"
+version = "0.2.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -22,7 +22,7 @@ classifiers = [
 ]
 requires-python = ">=3.11"
 dependencies = [
-    "sqlalchemy[asyncio]>=2.0.43",
+    "sqlalchemy[asyncio]>=2.0.22",
 ]
 
 [project.urls]
@@ -79,17 +79,12 @@ docs = [
     "mkdocs>=1.6.1,<2",
     "mkdocs-material>=9.7.7",
     "mkdocstrings[python]>=1.0.6",
-    # mkdocstrings lays out long signatures with it, and leaves them on one
-    # line without it, so the built site would differ from a local build.
     "ruff>=0.16.3",
 ]
 
 [tool.pytest.ini_options]
 filterwarnings = [
     "error",
-    # Python 3.13 made `sqlite3.Connection` warn when the garbage collector
-    # finalises it instead of a `close()`. The tests build throwaway databases
-    # by the dozen and let them go, so this says nothing about the code.
     "ignore:unclosed database:ResourceWarning",
 ]
 # `pytester` runs the conftest the docs show, in a session of its own.

{sqlakit-0.1.0 → sqlakit-0.2.0}/sqlakit/_base.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import asyncio
+import inspect
 import random
 import threading
 import time
@@ -7,6 +9,7 @@ from collections.abc import Callable, Mapping
 from contextlib import ExitStack, contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
+from functools import cache
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -93,6 +96,45 @@ ConnectionT = TypeVar("ConnectionT")
 SessionT = TypeVar("SessionT")
 
 
+class _Lazy(Generic[ConnectionT]):
+    """A connection checkout that has not happened yet.
+
+    A lazy ``session_factory()`` block binds one instead of a connection.
+    ``get`` and ``aget`` check out once, and cache what they opened.
+    """
+
+    __slots__ = ("_alock", "_lock", "connection", "open")
+
+    def __init__(self, open: Callable[[], Any]) -> None:  # noqa: A002
+        self.open = open
+        self.connection: ConnectionT | None = None
+        self._lock = threading.Lock()
+        self._alock: asyncio.Lock | None = None
+
+    def get(self) -> ConnectionT:
+        """Materialize the connection, once, and return it."""
+        with self._lock:
+            if self.connection is None:
+                self.connection = self.open()
+        return self.connection
+
+    async def aget(self) -> ConnectionT:
+        """Materialize the connection, once, awaited."""
+        if self.connection is not None:
+            return self.connection
+        # `asyncio` because the async engine is asyncio-only, and on the cell
+        # rather than the database, which outlives any one loop.
+        if self._alock is None:
+            self._alock = asyncio.Lock()
+        async with self._alock:
+            if self.connection is None:
+                connection = self.open()
+                if inspect.isawaitable(connection):
+                    connection = await connection
+                self.connection = connection
+        return self.connection
+
+
 @dataclass(slots=True)
 class _Scope(Generic[ConnectionT, SessionT]):
     """The connection bound to a context, and the session opened on top of it.
@@ -100,10 +142,16 @@ class _Scope(Generic[ConnectionT, SessionT]):
     The context variable holds this object, not the session, so a session
     opened later, including in a task that copies the context, still
     belongs to the block that bound the connection.
+
+    A lazy ``session_factory()`` block binds a ``checkout`` and no connection.
+    The connection lands here once something uses it.
     """
 
-    connection: ConnectionT
+    connection: ConnectionT | None
     session: SessionT | None = None
+    checkout: _Lazy[ConnectionT] | None = None
+    autocommit: bool = False
+    """Whether the connection is in ``AUTOCOMMIT``, where no transaction runs."""
 
 
 @dataclass(slots=True)
@@ -196,16 +244,15 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.url.render_as_string()!r})"
 
-    @property
-    def connection(self) -> ConnectionT:
-        """The connection bound to the current context.
+    def _current_scope(self) -> _Scope[ConnectionT, SessionT]:
+        """Return the scope bound to the current context.
 
         Raises:
-            MissingConnectionError: if no connection is bound.
+            MissingConnectionError: if no block is open.
 
         """
         try:
-            return self._scope.get().connection
+            return self._scope.get()
         except LookupError:
             raise MissingConnectionError from None
 
@@ -226,7 +273,12 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         except LookupError:
             raise MissingSessionError from None
         if scope.session is None:
-            scope.session = self._create_session(scope.connection)
+            if scope.connection is None and scope.checkout is not None:
+                scope.session = self._lazy_session(scope.checkout)
+            else:
+                scope.session = self._create_session(
+                    cast("ConnectionT", scope.connection)
+                )
         return scope.session
 
     @contextmanager
@@ -386,6 +438,9 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
     def _create_session(self, connection: ConnectionT) -> SessionT:
         raise NotImplementedError  # pragma: no cover - the subclass has it
 
+    def _lazy_session(self, cell: _Lazy[ConnectionT]) -> SessionT:
+        raise NotImplementedError  # pragma: no cover - the subclass has it
+
     def _session_args_for(self, connection: ConnectionT) -> dict[str, Any]:
         """How a session joins the transaction already open on ``connection``."""
         outer = self._outer.get(None)
@@ -415,31 +470,47 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         outer = self._outer_to_join()
         return outer.connection if outer is not None else None
 
-    def _connection_to_reuse(self) -> ConnectionT | None:
-        """Return the bound connection a new block reuses, if it may.
+    def _scope_to_reuse(self) -> _Scope[ConnectionT, SessionT] | None:
+        """Return the bound scope a new block reuses, if it may.
 
         One connection per context: a block that only needs a connection takes
         the one already bound, whether a transaction, ``autocommit()`` or
-        another ``connect()`` opened it. ``join_nested=False`` opts out.
+        another ``connect()`` opened it. ``join_nested=False`` opts out. The
+        caller materializes a lazy scope, awaited or not.
         """
         outer = self._outer.get(None)
         if outer is not None and not outer.join_nested:
             return None
-        scope = self._scope.get(None)
-        return scope.connection if scope is not None else None
+        return self._scope.get(None)
+
+    def _scope_to_borrow(self) -> _Scope[ConnectionT, SessionT] | None:
+        """Return the scope whose connection a transaction runs on, if it may.
+
+        ``connect()`` and ``session_factory()`` lend theirs. ``autocommit()``
+        does not: no transaction runs on an ``AUTOCOMMIT`` connection.
+        """
+        scope = self._scope_to_reuse()
+        if scope is None or scope.autocommit:
+            return None
+        return scope
 
     @contextmanager
     def _bind(
         self,
-        connection: ConnectionT,
+        connection: ConnectionT | None,
+        checkout: _Lazy[ConnectionT] | None = None,
+        *,
+        autocommit: bool = False,
     ) -> Iterator[_Scope[ConnectionT, SessionT]]:
         """Bind a scope holding ``connection`` to the current context.
 
         Every block gets a scope, and so a session, of its own. Ending that
         session is left to the caller, which knows whether it takes an
-        ``await``.
+        ``await``. A lazy block passes ``checkout`` instead of a connection.
         """
-        scope = _Scope[ConnectionT, SessionT](connection)
+        scope = _Scope[ConnectionT, SessionT](
+            connection, checkout=checkout, autocommit=autocommit
+        )
         token = self._scope.set(scope)
         try:
             yield scope
@@ -911,6 +982,31 @@ def url_from_config(config: DatabaseConfig) -> str | sa.URL:
     return sa.URL.create(**parts)  # ty: ignore[invalid-argument-type]
 
 
+class _LazyBind:
+    """A session that checks its connection out on first real use.
+
+    Mixed over the session class of a lazy ``session_factory()`` block, which
+    creates it unbound. ``get_bind`` checks the connection out on a flush or a
+    query, not on ``add()``.
+    """
+
+    _sqlakit_checkout: Callable[[], Any] | None = None
+    bind: Any
+
+    def get_bind(self, *args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
+        if self.bind is None and self._sqlakit_checkout is not None:
+            self.bind = self._sqlakit_checkout()
+        return super().get_bind(*args, **kwargs)  # ty: ignore[unresolved-attribute]
+
+
+@cache
+def lazy_session_class(base: type) -> type:
+    """Return ``base`` with `_LazyBind` mixed in, built once per base."""
+    if issubclass(base, _LazyBind):
+        return base
+    return type(f"Lazy{base.__name__}", (_LazyBind, base), {})
+
+
 class BaseRetryingTransaction:
     """What ``transaction()`` returns when given ``retry_on``.
 

{sqlakit-0.1.0 → sqlakit-0.2.0}/sqlakit/_db.py

@@ -20,8 +20,11 @@ from sqlalchemy.orm import Session, sessionmaker
 from ._base import (
     BaseDatabase,
     BaseRetryingTransaction,
+    _Lazy,
+    _Scope,
     default_backoff,
     fix_sqlite_transactions,
+    lazy_session_class,
 )
 from .exceptions import TransactionRolledBackError
 
@@ -110,6 +113,19 @@ class Database(BaseDatabase[sa.Connection, Session]):
         fix_sqlite_transactions(engine)
         return engine
 
+    @property
+    def connection(self) -> sa.Connection:
+        """The connection bound to the current context.
+
+        In a [`session_factory`][sqlakit.Database.session_factory] block,
+        reading it checks the connection out.
+
+        Raises:
+            MissingConnectionError: if no connection is bound.
+
+        """
+        return self._reused(self._current_scope())
+
     def _create_session(self, connection: sa.Connection) -> Session:
         if self._sessionmaker is None:
             self._sessionmaker = sessionmaker(**self.session_args)
@@ -118,12 +134,26 @@ class Database(BaseDatabase[sa.Connection, Session]):
             **self._session_args_for(connection),
         )
 
+    def _lazy_session(self, cell: _Lazy[sa.Connection]) -> Session:
+        args: dict[str, Any] = dict(self.session_args)
+        session_class = lazy_session_class(args.pop("class_", Session))
+        session = session_class(**args)
+        session._sqlakit_checkout = cell.get  # noqa: SLF001
+        return session
+
+    @staticmethod
+    def _reused(scope: _Scope[sa.Connection, Session]) -> sa.Connection:
+        """Return the scope's connection, checking it out first if lazy."""
+        if scope.connection is None and scope.checkout is not None:
+            scope.connection = scope.checkout.get()
+        return cast("sa.Connection", scope.connection)
+
     @contextmanager
     def connect(self) -> Iterator[sa.Connection]:
         """Open a connection and bind it, or reuse the one already bound."""
-        outer = self._connection_to_reuse()
-        if outer is not None:
-            with self._bound(outer) as connection:
+        reuse = self._scope_to_reuse()
+        if reuse is not None:
+            with self._bound(self._reused(reuse)) as connection:
                 yield connection
             return
         with self.engine.connect() as opened, self._bound(opened) as connection:
@@ -170,7 +200,10 @@ class Database(BaseDatabase[sa.Connection, Session]):
             return
         with self.engine.connect() as opened:
             opened.execution_options(isolation_level="AUTOCOMMIT")
-            with self._set_outer(None), self._bound(opened, commit=True) as connection:
+            with (
+                self._set_outer(None),
+                self._bound(opened, commit=True, autocommit=True) as connection,
+            ):
                 yield connection
 
     @overload
@@ -284,9 +317,29 @@ class Database(BaseDatabase[sa.Connection, Session]):
 
     @contextmanager
     def session_factory(self) -> Iterator[Session]:
-        """Open a new connection and a session on top of it, and bind both."""
-        with self.connect():
-            yield self.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.
+        """
+        reuse = self._scope_to_reuse()
+        if reuse is not None:
+            with self._bound(self._reused(reuse)):
+                yield self.session
+            return
+        # The lambda defers `self.engine` too: no engine until first use.
+        cell: _Lazy[sa.Connection] = _Lazy(lambda: self.engine.connect())  # noqa: PLW0108
+        with self._bind(None, checkout=cell) as scope:
+            try:
+                yield self.session
+            finally:
+                try:
+                    if scope.session is not None:
+                        scope.session.close()
+                finally:
+                    if cell.connection is not None:
+                        cell.connection.close()
 
     @contextmanager
     def _bound(
@@ -294,6 +347,7 @@ class Database(BaseDatabase[sa.Connection, Session]):
         connection: sa.Connection,
         *,
         commit: bool = False,
+        autocommit: bool = False,
     ) -> Iterator[sa.Connection]:
         """Bind ``connection`` for the block, ending the session it opened.
 
@@ -301,7 +355,7 @@ class Database(BaseDatabase[sa.Connection, Session]):
         itself with a savepoint rolls back to it, discarding what the blocks
         below committed.
         """
-        with self._bind(connection) as scope:
+        with self._bind(connection, autocommit=autocommit) as scope:
             done = False
             try:
                 yield connection
@@ -364,6 +418,21 @@ class Database(BaseDatabase[sa.Connection, Session]):
         self.dispose()
 
 
+def _owned(
+    connection: sa.Connection,
+    scope: _Scope[sa.Connection, Session],
+) -> tuple[Session | None, sa.Transaction | None]:
+    """Return what a borrowing block ends: a session's transaction, or its own.
+
+    A session that began one goes on using it, so that one ends through the
+    session. Anything else is the block's to end.
+    """
+    session = scope.session
+    if session is not None and session.in_transaction():
+        return session, None
+    return None, connection.get_transaction() or connection.begin()
+
+
 class Transaction(ContextDecorator, AbstractContextManager["sa.Connection"]):
     """What [`Database.transaction`][sqlakit.Database.transaction] returns.
 
@@ -410,6 +479,7 @@ class Transaction(ContextDecorator, AbstractContextManager["sa.Connection"]):
                 savepoint=self.savepoint,
                 rollback=self.rollback,
             )
+            owner: Session | None = None
             if outer is not None:
                 connection = outer.connection
                 # Without a savepoint the block only takes part in the
@@ -419,11 +489,16 @@ class Transaction(ContextDecorator, AbstractContextManager["sa.Connection"]):
                 # must not add a second one on the same connection.
                 session_savepoint = outer.session_savepoint and not savepoint
             else:
-                connection = stack.enter_context(self.db.engine.connect())
-                transaction = connection.begin()
+                borrowed = self.db._scope_to_borrow()  # noqa: SLF001
+                if borrowed is not None:
+                    connection = self.db._reused(borrowed)  # noqa: SLF001
+                    owner, transaction = _owned(connection, borrowed)
+                else:
+                    connection = stack.enter_context(self.db.engine.connect())
+                    owner, transaction = None, connection.begin()
                 session_savepoint = savepoint
             # Unwound in reverse: session, context, transaction, connection.
-            stack.push(self._finish(transaction))
+            stack.push(self._finish(transaction, owner))
             bound = stack.enter_context(
                 self.db._set_outer(  # noqa: SLF001
                     connection,
@@ -473,7 +548,11 @@ class Transaction(ContextDecorator, AbstractContextManager["sa.Connection"]):
 
         return close_session
 
-    def _finish(self, transaction: sa.Transaction | None) -> Callable[..., None]:
+    def _finish(
+        self,
+        transaction: sa.Transaction | None,
+        owner: Session | None = None,
+    ) -> Callable[..., None]:
         """Commit or roll back, unless this block only takes part in another."""
 
         def finish(
@@ -481,6 +560,14 @@ class Transaction(ContextDecorator, AbstractContextManager["sa.Connection"]):
             exc: BaseException | None,
             _traceback: object,
         ) -> None:
+            if owner is not None:
+                # The lending block's session holds the transaction. Ending it
+                # through the session leaves that session able to go on.
+                if self._keeps(exc) and not self.rollback:
+                    owner.commit()
+                else:
+                    owner.rollback()
+                return
             if transaction is None:
                 return
             if not transaction.is_active:

{sqlakit-0.1.0 → sqlakit-0.2.0}/sqlakit/_query.py

@@ -239,6 +239,9 @@ class BaseQuery(Generic[ModelT]):
         self._statement: Any = None
         self.filtered = True
         self.deleted = HIDDEN
+        # A page reads the same keyset ordering three times: for the statement
+        # and for the cursor at either end.
+        self._keyset_cache: tuple[list[_Ordering], str] | None = None
 
     def using(self, target: str | Any) -> Self:  # noqa: ANN401
         """Run this query on another database, named or handed over.
@@ -283,6 +286,7 @@ class BaseQuery(Generic[ModelT]):
         )
         query = self._copy()
         query._select = select  # noqa: SLF001 - a copy of this class
+        query._keyset_cache = None  # noqa: SLF001 - the ordering may differ
         return query
 
     def _copy(self) -> Self:
@@ -420,9 +424,9 @@ class BaseQuery(Generic[ModelT]):
     ) -> Self:
         """Order the rows, by columns or by the sort strings a request carries.
 
-        A string is `name`, `name.desc`, or `name.desc.nulls_last`. Names are looked
-        up in what the model offers, so a field nobody meant to sort by is refused
-        rather than turned into SQL:
+        A string is `name`, `name.desc`, or `name.desc.nulls_last`, and several of
+        them order by each in turn. Names are looked up in what the model offers, so
+        a field nobody meant to sort by is refused rather than turned into SQL:
 
         ```python
         User.query.order_by(request.sort).page(limit=20)
@@ -640,8 +644,7 @@ class BaseQuery(Generic[ModelT]):
         """
         self._reject_statement("cursor_page")
         self._require_ordering()
-        ordering = self._keyset_ordering()
-        ordering_key = _ordering_key(ordering)
+        ordering, ordering_key = self._keyset()
         backwards = cursor is not None and _is_backwards(cursor)
         if backwards:
             ordering = [
@@ -668,6 +671,13 @@ class BaseQuery(Generic[ModelT]):
         if not self.is_ordered:
             raise UnorderedPageError
 
+    def _keyset(self) -> tuple[list[_Ordering], str]:
+        """Return the cursor's ordering and its fingerprint, worked out once."""
+        if self._keyset_cache is None:
+            ordering = self._keyset_ordering()
+            self._keyset_cache = (ordering, _ordering_key(ordering))
+        return self._keyset_cache
+
     def _keyset_ordering(self) -> list[_Ordering]:
         """Return the ordering a cursor walks: what was asked, then the key.
 
@@ -788,14 +798,14 @@ class BaseQuery(Generic[ModelT]):
                 not carry, such as one belonging to a joined table.
 
         """
-        ordering = self._keyset_ordering()
+        ordering, ordering_key = self._keyset()
         values = []
         for item in ordering:
             value = getattr(row, item.attribute)
             if value is None:
                 raise NullCursorValueError(item.attribute)
             values.append(value)
-        return _encode(values, backwards=backwards, ordering=_ordering_key(ordering))
+        return _encode(values, backwards=backwards, ordering=ordering_key)
 
 
 def orderable(model: type[Any]) -> Mapping[str, Any]:

{sqlakit-0.1.0 → sqlakit-0.2.0}/sqlakit/_sql.py

@@ -337,7 +337,12 @@ def _statement(
         # `*/` in a name would end the comment early and leak into the SQL.
         sql = f"/* {label.replace('*/', '* /')} */\n{sql}"
     clause = sa.text(sql)
-    stray = set(clause._bindparams) - set(params)  # noqa: SLF001
+    named = {
+        element.key
+        for element in clause.get_children()
+        if isinstance(element, sa.BindParameter)
+    }
+    stray = named - set(params)
     if stray:
         raise StrayParameterError(sorted(stray), label)
     return clause.bindparams(*(_bound(name, value) for name, value in params.items()))

{sqlakit-0.1.0 → sqlakit-0.2.0}/sqlakit/asyncio/_db.py

@@ -22,14 +22,19 @@ from sqlalchemy.ext.asyncio import (
     async_sessionmaker,
     create_async_engine,
 )
+from sqlalchemy.orm import Session
+from sqlalchemy.util import await_only
 
 from sqlakit._base import (
     BaseDatabase,
     BaseRetryingTransaction,
+    _Lazy,
+    _Scope,
     default_backoff,
     fix_sqlite_transactions,
+    lazy_session_class,
 )
-from sqlakit.exceptions import TransactionRolledBackError
+from sqlakit.exceptions import MissingConnectionError, TransactionRolledBackError
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Callable, Coroutine, Sequence
@@ -112,6 +117,36 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         fix_sqlite_transactions(engine.sync_engine)
         return engine
 
+    @property
+    def connection(self) -> AsyncConnection:
+        """The connection bound to the current context.
+
+        In a [`session_factory`][sqlakit.asyncio.Database.session_factory]
+        block it raises until the session's first use: a property cannot await
+        the checkout.
+
+        Raises:
+            MissingConnectionError: if no connection is bound.
+
+        """
+        scope = self._current_scope()
+        if scope.connection is None:
+            cell = scope.checkout
+            if cell is not None and cell.connection is not None:
+                scope.connection = cell.connection
+            else:
+                message = (
+                    "No connection is open in this `session_factory()` block "
+                    "yet. Use `db.session`, or open a `connect()` block if "
+                    "you need the connection."
+                )
+                raise MissingConnectionError(message)
+        return scope.connection
+
+    async def _aconnection(self) -> AsyncConnection:
+        """Return the bound connection, checking it out first if lazy."""
+        return await self._areused(self._current_scope())
+
     def _create_session(self, connection: AsyncConnection) -> AsyncSession:
         if self._sessionmaker is None:
             self._sessionmaker = async_sessionmaker(**self.session_args)
@@ -120,12 +155,39 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
             **self._session_args_for(connection),
         )
 
+    def _lazy_session(self, cell: _Lazy[AsyncConnection]) -> AsyncSession:
+        args: dict[str, Any] = dict(self.session_args)
+        session_class = args.pop("class_", AsyncSession)
+        args["sync_session_class"] = lazy_session_class(
+            args.pop("sync_session_class", Session)
+        )
+        session = session_class(**args)
+
+        def checkout() -> sa.Connection | None:
+            # Already materialized, by a nested block: no greenlet needed.
+            connection = cell.connection
+            if connection is None:
+                connection = await_only(cell.aget())
+            return connection.sync_connection
+
+        session.sync_session._sqlakit_checkout = checkout  # noqa: SLF001
+        return session
+
+    @staticmethod
+    async def _areused(
+        scope: _Scope[AsyncConnection, AsyncSession],
+    ) -> AsyncConnection:
+        """Return the scope's connection, checking it out first if lazy."""
+        if scope.connection is None and scope.checkout is not None:
+            scope.connection = await scope.checkout.aget()
+        return cast("AsyncConnection", scope.connection)
+
     @asynccontextmanager
     async def connect(self) -> AsyncIterator[AsyncConnection]:
         """Open a connection and bind it, or reuse the one already bound."""
-        outer = self._connection_to_reuse()
-        if outer is not None:
-            async with self._bound(outer) as connection:
+        reuse = self._scope_to_reuse()
+        if reuse is not None:
+            async with self._bound(await self._areused(reuse)) as connection:
                 yield connection
             return
         async with self.engine.connect() as opened, self._bound(opened) as connection:
@@ -173,7 +235,9 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         async with self.engine.connect() as opened:
             await opened.execution_options(isolation_level="AUTOCOMMIT")
             with self._set_outer(None):
-                async with self._bound(opened, commit=True) as connection:
+                async with self._bound(
+                    opened, commit=True, autocommit=True
+                ) as connection:
                     yield connection
 
     @overload
@@ -287,9 +351,29 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
 
     @asynccontextmanager
     async def session_factory(self) -> AsyncIterator[AsyncSession]:
-        """Open a new connection and a session on top of it, and bind both."""
-        async with self.connect():
-            yield self.session
+        """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.
+        """
+        reuse = self._scope_to_reuse()
+        if reuse is not None:
+            async with self._bound(await self._areused(reuse)):
+                yield self.session
+            return
+        # The lambda defers `self.engine` too: no engine until first use.
+        cell: _Lazy[AsyncConnection] = _Lazy(lambda: self.engine.connect())  # noqa: PLW0108
+        with self._bind(None, checkout=cell) as scope:
+            try:
+                yield self.session
+            finally:
+                try:
+                    if scope.session is not None:
+                        await scope.session.close()
+                finally:
+                    if cell.connection is not None:
+                        await cell.connection.close()
 
     @asynccontextmanager
     async def _bound(
@@ -297,6 +381,7 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         connection: AsyncConnection,
         *,
         commit: bool = False,
+        autocommit: bool = False,
     ) -> AsyncIterator[AsyncConnection]:
         """Bind ``connection`` for the block, ending the session it opened.
 
@@ -304,7 +389,7 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         itself with a savepoint rolls back to it, discarding what the blocks
         below committed.
         """
-        with self._bind(connection) as scope:
+        with self._bind(connection, autocommit=autocommit) as scope:
             done = False
             try:
                 yield connection
@@ -367,6 +452,21 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
         await self.dispose()
 
 
+async def _owned(
+    connection: AsyncConnection,
+    scope: _Scope[AsyncConnection, AsyncSession],
+) -> tuple[AsyncSession | None, AsyncTransaction | None]:
+    """Return what a borrowing block ends: a session's transaction, or its own.
+
+    A session that began one goes on using it, so that one ends through the
+    session. Anything else is the block's to end.
+    """
+    session = scope.session
+    if session is not None and session.in_transaction():
+        return session, None
+    return None, connection.get_transaction() or await connection.begin()
+
+
 class Transaction(
     AsyncContextDecorator,
     AbstractAsyncContextManager["AsyncConnection"],
@@ -419,6 +519,7 @@ class Transaction(
                 savepoint=self.savepoint,
                 rollback=self.rollback,
             )
+            owner: AsyncSession | None = None
             if outer is not None:
                 connection = outer.connection
                 # Without a savepoint the block only takes part in the
@@ -428,11 +529,18 @@ class Transaction(
                 # must not add a second one on the same connection.
                 session_savepoint = outer.session_savepoint and not savepoint
             else:
-                connection = await stack.enter_async_context(self.db.engine.connect())
-                transaction = await connection.begin()
+                borrowed = self.db._scope_to_borrow()  # noqa: SLF001
+                if borrowed is not None:
+                    connection = await self.db._areused(borrowed)  # noqa: SLF001
+                    owner, transaction = await _owned(connection, borrowed)
+                else:
+                    connection = await stack.enter_async_context(
+                        self.db.engine.connect()
+                    )
+                    transaction = await connection.begin()
                 session_savepoint = savepoint
             # Unwound in reverse: session, context, transaction, connection.
-            stack.push_async_exit(self._finish(transaction))
+            stack.push_async_exit(self._finish(transaction, owner))
             bound = stack.enter_context(
                 self.db._set_outer(  # noqa: SLF001
                     connection,
@@ -485,6 +593,7 @@ class Transaction(
     def _finish(
         self,
         transaction: AsyncTransaction | None,
+        owner: AsyncSession | None = None,
     ) -> Callable[..., Coroutine[None, None, None]]:
         """Commit or roll back, unless this block only takes part in another."""
 
@@ -493,6 +602,14 @@ class Transaction(
             exc: BaseException | None,
             _traceback: object,
         ) -> None:
+            if owner is not None:
+                # The lending block's session holds the transaction. Ending it
+                # through the session leaves that session able to go on.
+                if self._keeps(exc) and not self.rollback:
+                    await owner.commit()
+                else:
+                    await owner.rollback()
+                return
             if transaction is None:
                 return
             if not transaction.is_active:

{sqlakit-0.1.0 → sqlakit-0.2.0}/sqlakit/asyncio/sql.py

@@ -179,7 +179,7 @@ class SQLRows(BaseSQLQuery[RowT, "Database"]):
         """Return this block's connection, with any pending ORM writes on it."""
         if self.db.in_session():
             await self.db.session.flush()
-        return self.db.connection
+        return await self.db._aconnection()  # noqa: SLF001
 
 
 class SQLQuery(SQLRows[sa.Row[Any]]):