sqlalchemy-foundation-kit 0.2.0__tar.gz → 0.2.1__tar.gz

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.1](https://github.com/bedrock-python/sqlalchemy-foundation-kit/compare/sqlalchemy-foundation-kit-v0.2.0...sqlalchemy-foundation-kit-v0.2.1) (2026-09-06)
+
+
+### Bug Fixes
+
+* the defects the agents page turned up ([#21](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/21)) ([9548c72](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/9548c72670696dd68e0eeec1f0ae4ad896fa62d6))
+
 ## [0.2.0](https://github.com/bedrock-python/sqlalchemy-foundation-kit/compare/sqlalchemy-foundation-kit-v0.1.0...sqlalchemy-foundation-kit-v0.2.0) (2026-08-28)
 
 

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlalchemy-foundation-kit
-Version: 0.2.0
+Version: 0.2.1
 Summary: Foundation layer for SQLAlchemy-based services with UoW, session management, and observability
 Project-URL: Repository, https://github.com/bedrock-python/sqlalchemy-foundation-kit
 Project-URL: Documentation, https://bedrock-python.github.io/sqlalchemy-foundation-kit/
@@ -219,6 +219,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: asyncpg<1.0.0,>=0.30.0
 Requires-Dist: pydantic<3.0.0,>=2.5.0
 Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.35
 Provides-Extra: all
@@ -279,7 +280,15 @@ Description-Content-Type: text/markdown
 - **Observability** — Prometheus connection-pool metrics and OpenTelemetry tracing
 - **DI integration** — Ready-to-use providers for [`dishka`](https://github.com/reagento/dishka) and `dependency-injector`
 
-Only `sqlalchemy[asyncio]` and `pydantic` are required by default — everything else is an opt-in extra.
+Only `sqlalchemy[asyncio]`, `pydantic` and `asyncpg` are required by default — everything else is an opt-in extra.
+
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/)** instead of the
+> whole site: the public API surface, the session-lifetime and transaction-ownership rules that
+> break code when they are broken, the mistakes models actually make with a Unit of Work, and a
+> map of which page to fetch for the rest. Every docs page is also served as raw Markdown at its
+> own URL, and a **Copy page** button at the top of each one hands it straight to a chat window.
 
 ## Key Features
 
@@ -425,12 +434,14 @@ async def main():
         user = UserDB(id=uuid4(), email="user@example.com", username="user")
         session.add(user)
         # Auto-commit on exit
+
+    await session_manager.aclose()
 ```
 
 ### 4. Unit of Work Pattern
 
 ```python
-from unit_of_work_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
+from sqlalchemy_foundation_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
 
 # Define your transaction with repositories
 class MyTransaction(AsyncSQLAlchemyUowTransaction):
@@ -619,6 +630,8 @@ graph LR
 
 Full documentation is available at [https://bedrock-python.github.io/sqlalchemy-foundation-kit/](https://bedrock-python.github.io/sqlalchemy-foundation-kit/)
 
+- [For AI agents](https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/) — the whole library on one page, for a coding assistant
+
 ## License
 
 This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/README.md

@@ -29,7 +29,15 @@
 - **Observability** — Prometheus connection-pool metrics and OpenTelemetry tracing
 - **DI integration** — Ready-to-use providers for [`dishka`](https://github.com/reagento/dishka) and `dependency-injector`
 
-Only `sqlalchemy[asyncio]` and `pydantic` are required by default — everything else is an opt-in extra.
+Only `sqlalchemy[asyncio]`, `pydantic` and `asyncpg` are required by default — everything else is an opt-in extra.
+
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/)** instead of the
+> whole site: the public API surface, the session-lifetime and transaction-ownership rules that
+> break code when they are broken, the mistakes models actually make with a Unit of Work, and a
+> map of which page to fetch for the rest. Every docs page is also served as raw Markdown at its
+> own URL, and a **Copy page** button at the top of each one hands it straight to a chat window.
 
 ## Key Features
 
@@ -175,12 +183,14 @@ async def main():
         user = UserDB(id=uuid4(), email="user@example.com", username="user")
         session.add(user)
         # Auto-commit on exit
+
+    await session_manager.aclose()
 ```
 
 ### 4. Unit of Work Pattern
 
 ```python
-from unit_of_work_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
+from sqlalchemy_foundation_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
 
 # Define your transaction with repositories
 class MyTransaction(AsyncSQLAlchemyUowTransaction):
@@ -369,6 +379,8 @@ graph LR
 
 Full documentation is available at [https://bedrock-python.github.io/sqlalchemy-foundation-kit/](https://bedrock-python.github.io/sqlalchemy-foundation-kit/)
 
+- [For AI agents](https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/) — the whole library on one page, for a coding assistant
+
 ## License
 
 This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/pyproject.toml

@@ -31,6 +31,7 @@ classifiers = [
 dependencies = [
     "sqlalchemy[asyncio]>=2.0.35,<3.0.0",
     "pydantic>=2.5.0,<3.0.0",
+    "asyncpg>=0.30.0,<1.0.0",
 ]
 
 [project.urls]
@@ -130,6 +131,10 @@ warn_unreachable = true
 [tool.ruff]
 line-length = 120
 target-version = "py311"
+# The Markdown guides hold fragments -- a keyword argument on its own, a body
+# without its def -- that read as code to a formatter and come out as
+# something else. ruff 0.16 formats fenced Python in Markdown by default.
+extend-exclude = ["*.md"]
 
 [tool.ruff.lint]
 select = ["F", "E", "W", "I", "B", "N", "S", "C4", "DTZ", "SIM", "TRY", "PERF", "RUF", "UP", "ANN", "T20", "PTH", "PLC", "PLE", "PLW"]

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/sqlalchemy_foundation_kit/__init__.py

@@ -64,7 +64,7 @@ from .uow import (
 try:
     __version__ = version("sqlalchemy-foundation-kit")
 except PackageNotFoundError:  # pragma: no cover
-    __version__ = "0.2.0"
+    __version__ = "0.2.1"
 
 __all__ = [  # noqa: RUF022
     # Base ORM

sqlalchemy_foundation_kit-0.2.1/sqlalchemy_foundation_kit/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/sqlalchemy_foundation_kit/base/_optional.py

@@ -11,7 +11,7 @@ def require_optional(module_name: str, extra_name: str) -> types.ModuleType:
 
     Args:
         module_name: Name of the module to import (e.g., "orjson", "opentelemetry").
-        extra_name: Name of the pip extra that provides this dependency (e.g., "json", "telemetry").
+        extra_name: Name of the pip extra that provides this dependency (e.g., "orjson", "telemetry").
 
     Returns:
         The imported module.
@@ -20,7 +20,7 @@ def require_optional(module_name: str, extra_name: str) -> types.ModuleType:
         ImportError: If the module is not installed, with installation instructions.
 
     Examples:
-        >>> orjson = require_optional("orjson", "json")
+        >>> orjson = require_optional("orjson", "orjson")
         >>> from opentelemetry import trace
         # or
         >>> otel = require_optional("opentelemetry", "telemetry")

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/sqlalchemy_foundation_kit/base/serialization.py

@@ -57,7 +57,7 @@ def _json_serializer(obj: object) -> str:
         >>> _json_serializer({"key": "value"})
         '{"key":"value"}'
     """
-    orjson = require_optional("orjson", "json")
+    orjson = require_optional("orjson", "orjson")
 
     try:
         return orjson.dumps(obj, default=_default_json_encoder).decode("utf-8")  # type: ignore[no-any-return]
@@ -82,7 +82,7 @@ def configure_orjson_serialization() -> dict[str, object]:
         >>> "json_deserializer" in config
         True
     """
-    orjson = require_optional("orjson", "json")
+    orjson = require_optional("orjson", "orjson")
 
     return {
         "json_serializer": _json_serializer,

sqlalchemy_foundation_kit-0.2.1/sqlalchemy_foundation_kit/contrib/dependency_injector/_deps.py

@@ -0,0 +1,59 @@
+"""Shared dependency-injector dependency helpers.
+
+Centralizes the dependency-injector import boilerplate and availability check so each
+module doesn't have to repeat it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+
+def check_dependency_injector() -> None:
+    """Raise ImportError if dependency-injector is not installed.
+
+    Raises:
+        ImportError: If dependency-injector is not available.
+    """
+    if not HAS_DEPENDENCY_INJECTOR:
+        raise ImportError(
+            "dependency-injector is required for containers. "
+            "Install it with: pip install 'sqlalchemy-foundation-kit[dependency-injector]'"
+        )
+
+
+class _MissingDependencyInjector:
+    """Stand-in for a dependency-injector name, raising the intended ImportError on first use.
+
+    ``BaseDIContainer`` subclasses ``containers.DeclarativeContainer`` and the container
+    modules build ``providers.*`` in their class bodies, which runs before any check a
+    base class could perform. Without this, importing them without dependency-injector
+    installed fails with ``AttributeError: 'NoneType' object has no attribute
+    'DeclarativeContainer'`` instead of the message that says what to install.
+    """
+
+    def __getattr__(self, name: str) -> NoReturn:
+        check_dependency_injector()
+        raise AttributeError(name)  # pragma: no cover - unreachable, check raises
+
+    def __call__(self, *args: Any, **kwargs: Any) -> NoReturn:
+        check_dependency_injector()
+        raise TypeError("dependency-injector is not installed")  # pragma: no cover - unreachable
+
+
+try:
+    from dependency_injector import containers, providers
+
+    HAS_DEPENDENCY_INJECTOR = True
+except ImportError:
+    HAS_DEPENDENCY_INJECTOR = False
+    containers = _MissingDependencyInjector()  # type: ignore[misc,assignment]
+    providers = _MissingDependencyInjector()  # type: ignore[misc,assignment]
+
+
+__all__ = [
+    "HAS_DEPENDENCY_INJECTOR",
+    "check_dependency_injector",
+    "containers",
+    "providers",
+]

sqlalchemy_foundation_kit-0.2.1/sqlalchemy_foundation_kit/contrib/di/_deps.py

@@ -0,0 +1,53 @@
+"""Shared dishka dependency helpers.
+
+Centralizes the dishka import boilerplate and availability check so each
+provider module doesn't have to repeat it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+
+def check_dishka() -> None:
+    """Raise ImportError if dishka is not installed.
+
+    Raises:
+        ImportError: If dishka is not available.
+    """
+    if not HAS_DISHKA:
+        raise ImportError(
+            "dishka is required for providers. Install it with: pip install 'sqlalchemy-foundation-kit[dishka]'"
+        )
+
+
+class _MissingDishka:
+    """Stand-in for a dishka name, raising the intended ImportError on first use.
+
+    Provider modules read ``Scope.APP`` and apply ``@provide`` in their class bodies,
+    which runs before any check a base class could perform. Without this, importing
+    them without dishka installed fails with ``AttributeError: 'NoneType' object has
+    no attribute 'APP'`` instead of the message that says what to install.
+    """
+
+    def __getattr__(self, name: str) -> NoReturn:
+        check_dishka()
+        raise AttributeError(name)  # pragma: no cover - unreachable, check_dishka raises
+
+    def __call__(self, *args: Any, **kwargs: Any) -> NoReturn:
+        check_dishka()
+        raise TypeError("dishka is not installed")  # pragma: no cover - unreachable
+
+
+try:
+    from dishka import Provider, Scope, provide
+
+    HAS_DISHKA = True
+except ImportError:
+    HAS_DISHKA = False
+    Provider = object  # type: ignore[misc,assignment]
+    Scope = _MissingDishka()  # type: ignore[misc,assignment]
+    provide = _MissingDishka()  # type: ignore[misc,assignment]
+
+
+__all__ = ["HAS_DISHKA", "Provider", "Scope", "check_dishka", "provide"]

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/sqlalchemy_foundation_kit/session/locks.py

@@ -1,5 +1,7 @@
 """PostgreSQL advisory locks (async)."""
 
+import hashlib
+
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -15,6 +17,10 @@ async def try_advisory_xact_lock(session: AsyncSession, key: str | int) -> bool:
     at transaction end. String keys are hashed to integers. The key is then
     truncated to signed 64-bit as Postgres expects.
 
+    A string key produces the same lock in every process, on every host and in
+    every release of the library, so two replicas of a service asking for
+    ``"nightly-rollup"`` contend for one lock.
+
     Args:
         session: SQLAlchemy AsyncSession within an active transaction.
         key: Lock identifier (string or integer). Strings are hashed to integers.
@@ -31,7 +37,7 @@ async def try_advisory_xact_lock(session: AsyncSession, key: str | int) -> bool:
         ...             await session.commit()
     """
     # Convert string keys to integers via hashing
-    int_key = hash(key) if isinstance(key, str) else key
+    int_key = _hash_lock_key(key) if isinstance(key, str) else key
 
     result = await session.execute(
         text("SELECT pg_try_advisory_xact_lock(:k)"),
@@ -40,6 +46,28 @@ async def try_advisory_xact_lock(session: AsyncSession, key: str | int) -> bool:
     return bool(result.scalar())
 
 
+def _hash_lock_key(key: str) -> int:
+    """Hash a string lock key into the PostgreSQL bigint range, reproducibly.
+
+    Python's built-in ``hash()`` is unusable here: string hashing is salted per
+    interpreter, so the same key becomes a different lock in every process and two
+    replicas of the same service lock nothing against each other. BLAKE2b is
+    deterministic, so the key is stable across processes, hosts and restarts.
+
+    Args:
+        key: Lock identifier.
+
+    Returns:
+        A signed 64-bit integer suitable for ``pg_try_advisory_xact_lock``.
+
+    Examples:
+        >>> _hash_lock_key("nightly-rollup") == _hash_lock_key("nightly-rollup")
+        True
+    """
+    digest = hashlib.blake2b(key.encode("utf-8"), digest_size=8).digest()
+    return int.from_bytes(digest, byteorder="big", signed=True)
+
+
 def _to_signed64(key: int) -> int:
     """Wrap integer to PostgreSQL signed 64-bit bigint range.
 

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/sqlalchemy_foundation_kit/session/manager.py

@@ -238,15 +238,18 @@ class AsyncSessionManager(Generic[SessionT]):
         """Get a new database session with automatic transaction management.
 
         Args:
-            isolation_level: Optional isolation level for the transaction.
+            isolation_level: Optional isolation level for the transaction, in the
+                PostgreSQL spelling (``"SERIALIZABLE"``, ``"REPEATABLE READ"``, …).
+                It is applied to the connection this transaction runs on, so it
+                affects only this transaction and not the engine.
 
         Yields:
             Managed async session with active transaction.
         """
         self._ensure_not_closed()
-        options = {"isolation_level": isolation_level} if isolation_level else {}
-        async with (
-            self._session_maker(execution_options=options) as session,
-            session.begin(),
-        ):
+        async with self._session_maker() as session, session.begin():
+            if isolation_level is not None:
+                # begin() has not provisioned a connection yet, so this call is the one
+                # that checks it out -- the only moment the level can still be set.
+                await session.connection(execution_options={"isolation_level": isolation_level})
             yield session

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.2.1}/sqlalchemy_foundation_kit/uow/sqlalchemy.py

@@ -74,10 +74,15 @@ async def apply_isolation_level(
 ) -> None:
     """Apply isolation level to an async session's connection.
 
-    **Implementation Detail**:
-    We use ``run_sync()`` because SQLAlchemy's ``execution_options()`` is a
-    synchronous method that configures the underlying DBAPI connection object.
-    We must bridge from async context to sync method via ``run_sync()``.
+    The level has to reach the connection *before* the connection begins its
+    transaction — PostgreSQL cannot change the isolation level of a transaction that
+    is already running, and SQLAlchemy raises ``InvalidRequestError`` if you try. So
+    the level is handed to the ``session.connection()`` call that checks the
+    connection out, which applies it and only then begins.
+
+    Call this on a session that has not yet talked to the database. It starts the
+    session's transaction as a side effect, so a caller that wants to own the
+    transaction should join the one already open rather than call ``session.begin()``.
 
     This is a DRY utility to eliminate duplication of isolation level application
     logic across ``transaction()``, ``managed_session()``, and ``query()`` methods.
@@ -103,9 +108,32 @@ async def apply_isolation_level(
     """
     normalized = normalize_isolation_level(isolation_level)
     if normalized is not None:
-        conn = await session.connection()
-        # run_sync bridges async → sync for DBAPI-level configuration
-        await conn.run_sync(lambda c: c.execution_options(isolation_level=normalized))
+        await session.connection(execution_options={"isolation_level": normalized})
+
+
+@asynccontextmanager
+async def _owned_transaction(session: AsyncSession) -> AsyncIterator[None]:
+    """Run a block inside a transaction, committing on success and rolling back on failure.
+
+    ``session.begin()`` refuses to start a second transaction, and applying an isolation
+    level has to check a connection out — which begins one. So the transaction is only
+    started here when the session does not already have one, and the commit/rollback is
+    driven explicitly instead of by the ``session.begin()`` context manager.
+    """
+    if not session.in_transaction():
+        await session.begin()
+
+    try:
+        yield
+    except BaseException:
+        await session.rollback()
+        raise
+
+    try:
+        await session.commit()
+    except BaseException:
+        await session.rollback()
+        raise
 
 
 class AsyncSQLAlchemyUowTransaction(AsyncUowTransaction):
@@ -181,13 +209,14 @@ class PostgresAdvisoryLockMixin:
 
     session: AsyncSession  # Type annotation for protocol compliance
 
-    async def try_advisory_lock(self, key: int) -> bool:
+    async def try_advisory_lock(self, key: str | int) -> bool:
         """Acquire a Postgres transaction-scoped advisory lock.
 
         Delegates to :func:`try_advisory_xact_lock` for actual locking logic.
 
         Args:
-            key: Integer lock key.
+            key: Lock key. An integer is used as-is; a string is hashed to one
+                reproducibly, so the same string is the same lock in every process.
 
         Returns:
             True if lock was acquired, False if already held by another session.
@@ -301,7 +330,7 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
         if flush_before_commit is None:
             flush_before_commit = self._flush_before_commit
 
-        async with self.open_session(isolation_level) as session, session.begin():
+        async with self.open_session(isolation_level) as session, _owned_transaction(session):
             uow = self._transaction_factory(session)
             yield uow
             if flush_before_commit:
@@ -390,8 +419,10 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
             rollback when the session closes.
         """
         async with self.open_session(isolation_level) as session:
-            # Start transaction WITHOUT context manager - no auto-commit
-            await session.begin()
+            # Start transaction WITHOUT context manager - no auto-commit.
+            # An isolation level, if one was asked for, has already begun it.
+            if not session.in_transaction():
+                await session.begin()
             try:
                 uow = self._transaction_factory(session)
                 yield uow, session

sqlalchemy_foundation_kit-0.2.0/sqlalchemy_foundation_kit/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"  # x-release-please-version

sqlalchemy_foundation_kit-0.2.0/sqlalchemy_foundation_kit/contrib/dependency_injector/_deps.py

@@ -1,37 +0,0 @@
-"""Shared dependency-injector dependency helpers.
-
-Centralizes the dependency-injector import boilerplate and availability check so each
-module doesn't have to repeat it.
-"""
-
-from __future__ import annotations
-
-try:
-    from dependency_injector import containers, providers
-
-    HAS_DEPENDENCY_INJECTOR = True
-except ImportError:
-    HAS_DEPENDENCY_INJECTOR = False
-    containers = None  # type: ignore[misc,assignment]
-    providers = None  # type: ignore[misc,assignment]
-
-
-def check_dependency_injector() -> None:
-    """Raise ImportError if dependency-injector is not installed.
-
-    Raises:
-        ImportError: If dependency-injector is not available.
-    """
-    if not HAS_DEPENDENCY_INJECTOR:
-        raise ImportError(
-            "dependency-injector is required for containers. "
-            "Install it with: pip install 'sqlalchemy-foundation-kit[dependency-injector]'"
-        )
-
-
-__all__ = [
-    "HAS_DEPENDENCY_INJECTOR",
-    "check_dependency_injector",
-    "containers",
-    "providers",
-]

sqlalchemy_foundation_kit-0.2.0/sqlalchemy_foundation_kit/contrib/di/_deps.py

@@ -1,32 +0,0 @@
-"""Shared dishka dependency helpers.
-
-Centralizes the dishka import boilerplate and availability check so each
-provider module doesn't have to repeat it.
-"""
-
-from __future__ import annotations
-
-try:
-    from dishka import Provider, Scope, provide
-
-    HAS_DISHKA = True
-except ImportError:
-    HAS_DISHKA = False
-    Provider = object  # type: ignore[misc,assignment]
-    Scope = None  # type: ignore[misc,assignment]
-    provide = None  # type: ignore[misc,assignment]
-
-
-def check_dishka() -> None:
-    """Raise ImportError if dishka is not installed.
-
-    Raises:
-        ImportError: If dishka is not available.
-    """
-    if not HAS_DISHKA:
-        raise ImportError(
-            "dishka is required for providers. Install it with: pip install 'sqlalchemy-foundation-kit[dishka]'"
-        )
-
-
-__all__ = ["HAS_DISHKA", "Provider", "Scope", "check_dishka", "provide"]