loom-kernel 2.10.0__tar.gz → 2.11.0__tar.gz

{loom_kernel-2.10.0 → loom_kernel-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.10.0
+Version: 2.11.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-2.10.0 → loom_kernel-2.11.0}/pyproject.toml

@@ -224,6 +224,7 @@ mcp-tests = [
 dev = [
     "aiocache>=0.12,<1.0",
     "aiosqlite>=0.20.0",
+    "asyncpg>=0.30",
     # Declared, not merely transitive: one cache test pins what the key renderer
     # cannot separate inside an object msgspec expands itself, and an attrs class
     # is the only such object the stdlib can build.
@@ -477,6 +478,7 @@ prerelease_ignore = [
     "ci/.*",
     "test/.*",
     "build/.*",
+    "dependabot/.*",
 ]
 release_ignore = [
     "wip/.*",
@@ -485,4 +487,5 @@ release_ignore = [
     "ci/.*",
     "test/.*",
     "build/.*",
+    "dependabot/.*",
 ]

{loom_kernel-2.10.0 → loom_kernel-2.11.0}/src/loom/core/repository/sqlalchemy/__init__.py

@@ -13,6 +13,7 @@ from loom.core.repository.sqlalchemy.registry import (
 )
 from loom.core.repository.sqlalchemy.repository import RepositorySQLAlchemy, with_session_scope
 from loom.core.repository.sqlalchemy.session_manager import SessionManager
+from loom.core.repository.sqlalchemy.session_settings import SessionSettings
 from loom.core.repository.sqlalchemy.transactional import SupportsPostCommit, transactional
 
 __all__ = [
@@ -24,6 +25,7 @@ __all__ = [
     "Projection",
     "RepositorySQLAlchemy",
     "SessionManager",
+    "SessionSettings",
     "SupportsPostCommit",
     "TimestampMixin",
     "SQLAlchemyDefaultRepositoryBuilder",

{loom_kernel-2.10.0 → loom_kernel-2.11.0}/src/loom/core/repository/sqlalchemy/session_manager.py

@@ -5,14 +5,20 @@ from contextlib import asynccontextmanager
 from typing import Any
 
 from sqlalchemy import event
+from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import (
     AsyncEngine,
     AsyncSession,
     async_sessionmaker,
     create_async_engine,
 )
+from sqlalchemy.orm import Session
 
 from loom.core.logger import get_logger
+from loom.core.repository.sqlalchemy.session_settings import (
+    SessionSettings,
+    install_session_settings,
+)
 from loom.core.tracing import get_trace_id
 
 
@@ -25,6 +31,7 @@ class SessionManager:
         config: Mapping[str, Any],
         *,
         inject_trace_id: bool = True,
+        session_settings: SessionSettings | None = None,
         **engine_kwargs: object,
     ) -> SessionManager:
         """Build a session manager from a resolved SQLAlchemy config mapping.
@@ -34,6 +41,8 @@ class SessionManager:
                 optional pool tuning keys.
             inject_trace_id: When ``True``, prefixes SQL statements with the
                 active trace id when available.
+            session_settings: Optional provider of transaction-local Postgres
+                settings; see :meth:`SessionManager.__init__` for the contract.
             **engine_kwargs: Additional keyword arguments forwarded to the
                 async engine constructor.
 
@@ -41,7 +50,8 @@ class SessionManager:
             A configured :class:`SessionManager`.
 
         Raises:
-            ValueError: If ``url`` is missing or empty.
+            ValueError: If ``url`` is missing or empty, or if ``session_settings``
+                is given and ``url`` is not a Postgres URL.
         """
         url = config.get("url")
         if not url:
@@ -56,6 +66,7 @@ class SessionManager:
             pool_recycle=_optional_int(config.get("pool_recycle"), 1800),
             connect_args=dict(config.get("connect_args") or {}),
             inject_trace_id=inject_trace_id,
+            session_settings=session_settings,
             **engine_kwargs,
         )
 
@@ -71,6 +82,7 @@ class SessionManager:
         pool_recycle: int | None = 1800,
         connect_args: dict[str, object] | None = None,
         inject_trace_id: bool = True,
+        session_settings: SessionSettings | None = None,
         **engine_kwargs: object,
     ) -> None:
         """Create a session manager backed by an async SQLAlchemy engine.
@@ -88,8 +100,32 @@ class SessionManager:
                 ``/* trace_id=<id> */`` comment when a trace identifier is active
                 in the current async context.  Visible in database slow-query logs
                 and ``pg_stat_activity``.  Defaults to ``True``.
+            session_settings: When given, a callable that returns the settings for
+                the transaction about to start, or ``None`` to apply none. Each
+                outer transaction then begins with one ``SELECT`` that calls
+                ``set_config(key, value, true)`` once per entry, with keys and
+                values bound as parameters. The settings are local to the
+                transaction, so the connection returns to the pool clean. Postgres
+                only, and incompatible with ``isolation_level="AUTOCOMMIT"``, which
+                would discard the settings after each statement; when ``None``,
+                the manager behaves exactly as it does without this option.
             **engine_kwargs: Additional keyword arguments forwarded to ``create_async_engine``.
+
+        Raises:
+            ValueError: If ``session_settings`` is given and ``url`` is not a
+                Postgres URL, or the engine is configured with
+                ``isolation_level="AUTOCOMMIT"``.
         """
+        if session_settings is not None:
+            backend = make_url(url).get_backend_name()
+            if backend != "postgresql":
+                raise ValueError(
+                    f"session_settings requires a postgresql URL, got backend {backend!r}"
+                )
+            if _autocommit(engine_kwargs):
+                raise ValueError(
+                    "session_settings is incompatible with isolation_level='AUTOCOMMIT'"
+                )
         engine_config: dict[str, object] = {
             "echo": echo,
             "pool_pre_ping": pool_pre_ping,
@@ -108,10 +144,16 @@ class SessionManager:
 
         self._log = get_logger(__name__).bind(module="session_manager")
         self._engine = create_async_engine(url, **engine_config)
+        factory_kwargs: dict[str, Any] = {}
+        if session_settings is not None:
+            session_class = type("SettingsSession", (Session,), {})
+            install_session_settings(session_class, session_settings)
+            factory_kwargs["sync_session_class"] = session_class
         self._session_factory = async_sessionmaker(
             bind=self._engine,
             class_=AsyncSession,
             expire_on_commit=False,
+            **factory_kwargs,
         )
         if inject_trace_id:
             _register_trace_id_listener(self._engine)
@@ -120,6 +162,7 @@ class SessionManager:
             backend=self._engine.url.get_backend_name(),
             driver=self._engine.url.get_driver_name(),
             inject_trace_id=inject_trace_id,
+            session_settings=session_settings is not None,
         )
 
     @asynccontextmanager
@@ -181,6 +224,17 @@ def _register_trace_id_listener(async_engine: AsyncEngine) -> None:
         return statement, parameters
 
 
+def _autocommit(engine_kwargs: Mapping[str, object]) -> bool:
+    execution_options = engine_kwargs.get("execution_options")
+    levels = (
+        engine_kwargs.get("isolation_level"),
+        execution_options.get("isolation_level")
+        if isinstance(execution_options, Mapping)
+        else None,
+    )
+    return any(isinstance(level, str) and level.upper() == "AUTOCOMMIT" for level in levels)
+
+
 def _optional_int(value: Any, default: int) -> int:
     if value is None:
         return default

loom_kernel-2.11.0/src/loom/core/repository/sqlalchemy/session_settings.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from sqlalchemy import TextClause, event, text
+from sqlalchemy.orm import Session
+
+SessionSettings = Callable[[], Mapping[str, str] | None]
+"""Returns the settings to apply to the transaction about to start, or ``None`` to apply none.
+
+loom does not interpret the keys or values. A product returns, for example, the tenant
+and the subject of the current request, and writes its Postgres policies against
+``current_setting(key, true)``.
+"""
+
+_KEY = re.compile(r"[A-Za-z_]\w*\.[A-Za-z_]\w*")
+
+
+def settings_statement(
+    values: Mapping[str, str] | None,
+) -> tuple[TextClause, dict[str, str]] | None:
+    """Build the one statement that sets *values* for the current transaction.
+
+    Every key and value is bound as a parameter: the compiled SQL carries only
+    placeholders. Keys must be application-prefixed identifiers, ``prefix.name``,
+    which is what Postgres requires of a custom setting.
+
+    Args:
+        values: The settings to apply, or ``None``.
+
+    Returns:
+        The ``SELECT set_config(...)`` clause with its parameters, or ``None``
+        when there is nothing to set.
+
+    Raises:
+        ValueError: If a key is not a string of the form ``prefix.name``.
+        TypeError: If a value is not a ``str``.
+    """
+    if not values:
+        return None
+    calls: list[str] = []
+    params: dict[str, str] = {}
+    for index, (key, value) in enumerate(values.items()):
+        if not isinstance(key, str) or _KEY.fullmatch(key) is None:
+            raise ValueError(
+                f"session setting key must be a str of the form 'prefix.name', got {key!r}"
+            )
+        if not isinstance(value, str):
+            raise TypeError(
+                f"session setting value for {key!r} must be str, got {type(value).__name__}"
+            )
+        calls.append(f"set_config(:k{index}, :v{index}, true)")
+        params[f"k{index}"] = key
+        params[f"v{index}"] = value
+    return text("SELECT " + ", ".join(calls)), params
+
+
+def install_session_settings(session_class: type[Session], provider: SessionSettings) -> None:
+    """Apply *provider*'s settings at the start of every outer transaction of *session_class*.
+
+    The listener runs once per outer transaction and not for savepoints. A provider
+    that raises, an invalid key, or a non-``str`` value fails the transaction before
+    its first product statement reaches the database, and invalidates its connection,
+    so the session refuses further statements until it is rolled back.
+
+    Args:
+        session_class: The synchronous ``Session`` subclass the listener is bound to.
+        provider: The settings provider called at the start of each transaction.
+    """
+
+    @event.listens_for(session_class, "after_begin")
+    def _apply_session_settings(_session: Session, transaction: Any, connection: Any) -> None:
+        if transaction.nested:
+            return
+        try:
+            statement = settings_statement(provider())
+            if statement is not None:
+                connection.execute(*statement)
+        except BaseException:
+            connection.invalidate()
+            raise