simple-module-db 0.0.32__tar.gz → 0.0.34__tar.gz

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_db
-Version: 0.0.32
+Version: 0.0.34
 Summary: Per-module SQLModel Base, async session, standard mixins (Audit, SoftDelete, MultiTenant, Versioned) for simple_module
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -25,7 +25,7 @@ Requires-Dist: aiosqlite>=0.20
 Requires-Dist: alembic>=1.14
 Requires-Dist: asyncpg>=0.30
 Requires-Dist: psycopg2-binary>=2.9
-Requires-Dist: simple-module-core==0.0.32
+Requires-Dist: simple-module-core==0.0.34
 Requires-Dist: sqlalchemy[asyncio]>=2.0
 Requires-Dist: sqlmodel>=0.0.22
 Description-Content-Type: text/markdown
@@ -43,7 +43,8 @@ pip install simple_module_db
 ## What it provides
 
 - `create_module_base("<module_name>")` — a module-scoped declarative `Base` with its own `MetaData`. All modules share the host's single schema, so `__tablename__` should be prefixed with the module name (e.g. `users_user`) to avoid collisions.
-- Per-request async session (`get_db`) with an auto-commit-on-flush hook — `after_flush` commits if there are pending writes, rolls back otherwise.
+- Per-request `RequestSession` (`get_db`) that commits pending writes before the response and rolls back read-only requests.
+- `session.on_commit(callback)` for synchronous or asynchronous cache refreshes that must only run after a successful request commit.
 - Mixins in `simple_module_db.mixins`: `AuditMixin` (created_at/updated_at), `SoftDeleteMixin` (auto-filtered unless `stmt.execution_options(include_deleted=True)`), `MultiTenantMixin`, `VersionedMixin`.
 - `DatabaseState` container used by the framework to avoid global mutable state.
 
@@ -66,12 +67,13 @@ class Order(Base, AuditMixin, SoftDeleteMixin, table=True):
 In a service:
 
 ```python
-from simple_module_db import get_db
+from simple_module_db import RequestSession, get_db
 
-async def create_order(session = Depends(get_db), ...):
+async def create_order(session: RequestSession = Depends(get_db), ...):
     order = Order(customer_id=..., total_cents=...)
     session.add(order)
-    await session.flush()   # assigns order.id; auto-commit happens after the request
+    await session.flush()   # assigns order.id; commit happens before the response
+    session.on_commit(order_cache.refresh)
     return order
 ```
 

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/README.md

@@ -11,7 +11,8 @@ pip install simple_module_db
 ## What it provides
 
 - `create_module_base("<module_name>")` — a module-scoped declarative `Base` with its own `MetaData`. All modules share the host's single schema, so `__tablename__` should be prefixed with the module name (e.g. `users_user`) to avoid collisions.
-- Per-request async session (`get_db`) with an auto-commit-on-flush hook — `after_flush` commits if there are pending writes, rolls back otherwise.
+- Per-request `RequestSession` (`get_db`) that commits pending writes before the response and rolls back read-only requests.
+- `session.on_commit(callback)` for synchronous or asynchronous cache refreshes that must only run after a successful request commit.
 - Mixins in `simple_module_db.mixins`: `AuditMixin` (created_at/updated_at), `SoftDeleteMixin` (auto-filtered unless `stmt.execution_options(include_deleted=True)`), `MultiTenantMixin`, `VersionedMixin`.
 - `DatabaseState` container used by the framework to avoid global mutable state.
 
@@ -34,12 +35,13 @@ class Order(Base, AuditMixin, SoftDeleteMixin, table=True):
 In a service:
 
 ```python
-from simple_module_db import get_db
+from simple_module_db import RequestSession, get_db
 
-async def create_order(session = Depends(get_db), ...):
+async def create_order(session: RequestSession = Depends(get_db), ...):
     order = Order(customer_id=..., total_cents=...)
     session.add(order)
-    await session.flush()   # assigns order.id; auto-commit happens after the request
+    await session.flush()   # assigns order.id; commit happens before the response
+    session.on_commit(order_cache.refresh)
     return order
 ```
 

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_db"
-version = "0.0.32"
+version = "0.0.34"
 description = "Per-module SQLModel Base, async session, standard mixins (Audit, SoftDelete, MultiTenant, Versioned) for simple_module"
 readme = "README.md"
 license = "MIT"
@@ -28,7 +28,7 @@ dependencies = [
     # The async app code goes through asyncpg; migration env.py rewrites the
     # URL to +psycopg2 because Alembic's online migrations are sync-only.
     "psycopg2-binary>=2.9",
-    "simple_module_core==0.0.32",
+    "simple_module_core==0.0.34",
     "sqlalchemy[asyncio]>=2.0",
     "sqlmodel>=0.0.22",
 ]

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/simple_module_db/__init__.py

@@ -2,6 +2,7 @@
 
 from simple_module_db.audit import AuditRecord
 from simple_module_db.base import create_module_base
+from simple_module_db.callbacks import OnCommitCallback
 from simple_module_db.deps import get_db
 from simple_module_db.listeners import TenantIsolationError, current_tenant_id
 from simple_module_db.migrations import (
@@ -13,7 +14,7 @@ from simple_module_db.migrations import (
 from simple_module_db.mixins import AuditMixin, MultiTenantMixin, SoftDeleteMixin, VersionedMixin
 from simple_module_db.provider import DatabaseProvider, detect_provider
 from simple_module_db.search import LIKE_ESCAPE_CHAR, like_contains_pattern, like_prefix_pattern
-from simple_module_db.session import DatabaseState, init_db
+from simple_module_db.session import DatabaseState, RequestSession, init_db
 from simple_module_db.transaction import CommitBeforeResponseMiddleware, finalize_session
 
 __all__ = [
@@ -24,6 +25,8 @@ __all__ = [
     "DatabaseProvider",
     "DatabaseState",
     "MultiTenantMixin",
+    "OnCommitCallback",
+    "RequestSession",
     "SoftDeleteMixin",
     "TenantIsolationError",
     "VersionedMixin",

simple_module_db-0.0.34/simple_module_db/callbacks.py

@@ -0,0 +1,47 @@
+"""Post-commit callbacks for framework-managed database sessions."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+type OnCommitCallback = Callable[[], Awaitable[None] | None]
+
+_CALLBACKS_KEY = "sm_db_on_commit_callbacks"
+logger = logging.getLogger("simple_module.db")
+
+
+def register_on_commit(session: AsyncSession, callback: OnCommitCallback) -> None:
+    """Queue ``callback`` for this session's next successful finalization."""
+    if not callable(callback):
+        raise TypeError("on_commit callback must be callable")
+    callbacks = session.info.setdefault(_CALLBACKS_KEY, [])
+    callbacks.append(callback)
+
+
+def discard_on_commit_callbacks(session: AsyncSession) -> None:
+    """Discard callbacks belonging to a transaction that did not commit."""
+    session.info.pop(_CALLBACKS_KEY, None)
+
+
+async def run_on_commit_callbacks(session: AsyncSession) -> None:
+    """Run and remove queued callbacks after a successful commit.
+
+    The transaction is already durable, so callback failures are logged and do
+    not turn a successful database mutation into a misleading failed response.
+    Remaining callbacks still run.
+    """
+    callbacks: list[OnCommitCallback] = session.info.pop(_CALLBACKS_KEY, [])
+    for callback in callbacks:
+        try:
+            result = callback()
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            logger.exception(
+                "db.session.on_commit_failed",
+                extra={"operation": "on_commit_failed"},
+            )

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/simple_module_db/deps.py

@@ -6,8 +6,8 @@ import time
 from collections.abc import AsyncGenerator
 
 from fastapi import Request
-from sqlalchemy.ext.asyncio import AsyncSession
 
+from simple_module_db.session import RequestSession
 from simple_module_db.transaction import (
     SESSION_START_KEY,
     finalize_session,
@@ -16,7 +16,7 @@ from simple_module_db.transaction import (
 )
 
 
-async def get_db(request: Request) -> AsyncGenerator[AsyncSession, None]:
+async def get_db(request: Request) -> AsyncGenerator[RequestSession, None]:
     """Yield an async database session, auto-closing on exit.
 
     Commits only when the session has pending writes (``new``, ``dirty``,
@@ -34,7 +34,7 @@ async def get_db(request: Request) -> AsyncGenerator[AsyncSession, None]:
     Usage in FastAPI endpoints::
 
         @router.get("/items")
-        async def list_items(db: AsyncSession = Depends(get_db)):
+        async def list_items(db: RequestSession = Depends(get_db)):
             ...
     """
     factory = request.app.state.sm.db.session_factory

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/simple_module_db/session.py

@@ -13,15 +13,28 @@ from sqlalchemy.ext.asyncio import (
 )
 from sqlalchemy.orm import Session
 
+from simple_module_db.callbacks import OnCommitCallback, register_on_commit
 from simple_module_db.provider import DatabaseProvider, detect_provider
 
 
+class RequestSession(AsyncSession):
+    """Async session with hooks for the request-owned transaction."""
+
+    def on_commit(self, callback: OnCommitCallback) -> None:
+        """Run ``callback`` after this request's next successful commit.
+
+        Callbacks may be synchronous or asynchronous. They are discarded when
+        the request rolls back or has no writes.
+        """
+        register_on_commit(self, callback)
+
+
 @dataclass
 class DatabaseState:
     """Holds all database state for a single application instance."""
 
     engine: AsyncEngine
-    session_factory: async_sessionmaker[AsyncSession]
+    session_factory: async_sessionmaker[RequestSession]
     sync_session_class: type[Session] = field(repr=False, default=Session)
     audit_callback: Callable | None = field(default=None, repr=False)
     _listeners_registered: bool = field(default=False, repr=False)
@@ -67,7 +80,10 @@ def init_db(
     # Scoped Session subclass so event listeners only fire for this engine's sessions
     scoped_session_class = type("ScopedSession", (Session,), {})
     session_factory = async_sessionmaker(
-        engine, expire_on_commit=False, sync_session_class=scoped_session_class
+        engine,
+        class_=RequestSession,
+        expire_on_commit=False,
+        sync_session_class=scoped_session_class,
     )
 
     return DatabaseState(

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/simple_module_db/transaction.py

@@ -31,6 +31,10 @@ import time
 
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from simple_module_db.callbacks import (
+    discard_on_commit_callbacks,
+    run_on_commit_callbacks,
+)
 from simple_module_db.listeners import SESSION_HAS_WRITES_KEY
 
 logger = logging.getLogger("simple_module.db")
@@ -97,6 +101,7 @@ async def finalize_session(session: AsyncSession) -> None:
         if session.info.get(_FINALIZED_KEY):
             return
         _settle(session)
+        discard_on_commit_callbacks(session)
         await session.rollback()
         logger.debug(
             "db.session.read_only",
@@ -106,6 +111,7 @@ async def finalize_session(session: AsyncSession) -> None:
     try:
         await session.commit()
     except Exception:
+        discard_on_commit_callbacks(session)
         await session.rollback()
         raise
     finally:
@@ -116,10 +122,12 @@ async def finalize_session(session: AsyncSession) -> None:
         "db.session.commit",
         extra={"operation": "commit", "db_duration_ms": _elapsed_ms(session)},
     )
+    await run_on_commit_callbacks(session)
 
 
 async def rollback_session(session: AsyncSession) -> None:
     """Roll ``session`` back and drop its pending work. Idempotent."""
+    discard_on_commit_callbacks(session)
     if session.info.get(_FINALIZED_KEY) and not _has_pending(session):
         return
     _settle(session)

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/tests/test_session.py

@@ -6,7 +6,7 @@ import contextlib
 from unittest.mock import MagicMock
 
 from simple_module_db.deps import get_db
-from simple_module_db.session import DatabaseState, init_db
+from simple_module_db.session import DatabaseState, RequestSession, init_db
 from sqlalchemy.ext.asyncio import AsyncSession
 
 
@@ -58,6 +58,7 @@ class TestGetDbDependency:
             gen = get_db(mock_request)
             session = await gen.__anext__()
             assert isinstance(session, AsyncSession)
+            assert isinstance(session, RequestSession)
 
             with contextlib.suppress(StopAsyncIteration):
                 await gen.__anext__()

{simple_module_db-0.0.32 → simple_module_db-0.0.34}/tests/test_transaction.py

@@ -20,6 +20,7 @@ import pytest
 from _models import _TxnBase, _TxnThing
 from fastapi import BackgroundTasks, Depends, FastAPI
 from fastapi.responses import StreamingResponse
+from simple_module_db import OnCommitCallback, RequestSession
 from simple_module_db.deps import get_db
 from simple_module_db.listeners import register_listeners
 from simple_module_db.session import init_db
@@ -28,7 +29,12 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import select
 
 
-def _build_app(db_state, *, with_middleware: bool = True) -> FastAPI:
+def _build_app(
+    db_state,
+    *,
+    with_middleware: bool = True,
+    on_commit: OnCommitCallback | None = None,
+) -> FastAPI:
     """A miniature host: create flushes only, read opens its own session."""
     app = FastAPI()
     if with_middleware:
@@ -36,12 +42,14 @@ def _build_app(db_state, *, with_middleware: bool = True) -> FastAPI:
     app.state.sm = SimpleNamespace(db=db_state)
 
     @app.post("/things", status_code=201)
-    async def create(name: str, db: AsyncSession = Depends(get_db)):
+    async def create(name: str, db: RequestSession = Depends(get_db)):
         # Deliberately no commit() — get_db owns the unit of work, which is
         # exactly the pattern the framework documents for service code.
         thing = _TxnThing(name=name)
         db.add(thing)
         await db.flush()
+        if on_commit is not None:
+            db.on_commit(on_commit)
         return {"id": thing.id}
 
     @app.get("/things/{thing_id}")
@@ -54,9 +62,11 @@ def _build_app(db_state, *, with_middleware: bool = True) -> FastAPI:
         return {"found": True, "name": found.name}
 
     @app.post("/boom", status_code=201)
-    async def boom(db: AsyncSession = Depends(get_db)):
+    async def boom(db: RequestSession = Depends(get_db)):
         db.add(_TxnThing(name="doomed"))
         await db.flush()
+        if on_commit is not None:
+            db.on_commit(on_commit)
         raise RuntimeError("endpoint blew up after writing")
 
     return app
@@ -131,11 +141,54 @@ class TestCommitBeforeResponse:
             "row was not committed by the time the response left the server"
         )
 
-    async def test_endpoint_exception_still_rolls_back(self, db_state):
-        """The middleware must not turn a failed request's writes into a commit."""
-        async with await _client(_build_app(db_state)) as client:
+    async def test_on_commit_runs_after_the_write_is_durable(self, db_state):
+        """A cache refresh can only observe state committed in another session."""
+        observed: list[list[str]] = []
+
+        async def refresh_cache():
+            async with db_state.session_factory() as other:
+                rows = (await other.execute(select(_TxnThing))).scalars().all()
+                observed.append([row.name for row in rows])
+
+        async with await _client(_build_app(db_state, on_commit=refresh_cache)) as client:
+            assert (await client.post("/things", params={"name": "committed"})).status_code == 201
+
+        assert observed == [["committed"]]
+
+    async def test_on_commit_failure_does_not_skip_later_callbacks(self, db_state):
+        """The commit is durable, so callback errors are logged rather than returned as 500s."""
+        called: list[bool] = []
+        app = _build_app(db_state)
+
+        @app.post("/callback-errors", status_code=201)
+        async def callback_errors(db: RequestSession = Depends(get_db)):
+            db.add(_TxnThing(name="durable-despite-cache-error"))
+            await db.flush()
+
+            def fail_refresh():
+                raise RuntimeError("cache unavailable")
+
+            db.on_commit(fail_refresh)
+            db.on_commit(lambda: called.append(True))
+            return {"ok": True}
+
+        async with await _client(app) as client:
+            response = await client.post("/callback-errors")
+
+        assert response.status_code == 201
+        assert called == [True]
+        async with db_state.session_factory() as session:
+            names = [row.name for row in (await session.execute(select(_TxnThing))).scalars()]
+        assert names == ["durable-despite-cache-error"]
+
+    async def test_endpoint_exception_rolls_back_without_on_commit(self, db_state):
+        """Callbacks for work discarded by an endpoint failure never run."""
+        called: list[bool] = []
+        app = _build_app(db_state, on_commit=lambda: called.append(True))
+        async with await _client(app) as client:
             assert (await client.post("/boom")).status_code == 500
 
+        assert called == []
         async with db_state.session_factory() as session:
             assert (await session.execute(select(_TxnThing))).scalars().all() == []
 
@@ -154,11 +207,14 @@ class TestCommitBeforeResponse:
 
         monkeypatch.setattr(AsyncSession, "commit", explode)
 
-        async with await _client(_build_app(db_state)) as client:
+        called: list[bool] = []
+        app = _build_app(db_state, on_commit=lambda: called.append(True))
+        async with await _client(app) as client:
             response = await client.post("/things", params={"name": "nope"})
 
         assert response.status_code == 500
         assert response.json() == {"detail": "Internal Server Error"}
+        assert called == []
 
         monkeypatch.undo()
         async with db_state.session_factory() as session:
@@ -216,10 +272,16 @@ class TestCommitBeforeResponse:
     async def test_still_commits_without_the_middleware(self, db_state):
         """get_db keeps its own fallback finalize, so the dependency works
         standalone — in a WebSocket handler, or a test that builds no stack."""
-        app = _build_app(db_state, with_middleware=False)
+        called: list[bool] = []
+        app = _build_app(
+            db_state,
+            with_middleware=False,
+            on_commit=lambda: called.append(True),
+        )
         async with await _client(app) as client:
             assert (await client.post("/things", params={"name": "solo"})).status_code == 201
 
+        assert called == [True]
         async with db_state.session_factory() as session:
             names = [t.name for t in (await session.execute(select(_TxnThing))).scalars().all()]
         assert names == ["solo"]