fastapi-toolsets 5.1.2__tar.gz → 5.1.4__tar.gz

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-toolsets
-Version: 5.1.2
+Version: 5.1.4
 Summary: Production-ready utilities for FastAPI applications
 Keywords: fastapi,sqlalchemy,postgresql
 Author: d3vyce

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "5.1.2"
+version = "5.1.4"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "5.1.2"
+version = "5.1.4"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/src/fastapi_toolsets/__init__.py

@@ -24,4 +24,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "5.1.2"
+__version__ = "5.1.4"

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/src/fastapi_toolsets/crud/factory.py

@@ -386,13 +386,29 @@ class AsyncCrud(Generic[ModelType]):
             own_filters=own_filters,
         )
 
+    @classmethod
+    def _resolve_search_fields(
+        cls: type[Self],
+        search_fields: Sequence[SearchFieldType] | None,
+    ) -> Sequence[SearchFieldType] | None:
+        """Return search_fields if given, otherwise fall back to the class-level default."""
+        return search_fields if search_fields is not None else cls.searchable_fields
+
+    @classmethod
+    def _resolve_order_fields(
+        cls: type[Self],
+        order_fields: Sequence[OrderFieldType] | None,
+    ) -> Sequence[OrderFieldType] | None:
+        """Return order_fields if given, otherwise fall back to the class-level default."""
+        return order_fields if order_fields is not None else cls.order_fields
+
     @classmethod
     def _resolve_search_columns(
         cls: type[Self],
         search_fields: Sequence[SearchFieldType] | None,
     ) -> list[str] | None:
         """Return search column keys, or None if no searchable fields configured."""
-        fields = search_fields if search_fields is not None else cls.searchable_fields
+        fields = cls._resolve_search_fields(search_fields)
         if not fields:
             return None
         return search_field_keys(fields)
@@ -403,7 +419,7 @@ class AsyncCrud(Generic[ModelType]):
         order_fields: Sequence[OrderFieldType] | None,
     ) -> list[str] | None:
         """Return sort column keys, or None if no order fields configured."""
-        fields = order_fields if order_fields is not None else cls.order_fields
+        fields = cls._resolve_order_fields(order_fields)
         if not fields:
             return None
         return sorted(facet_keys(fields))
@@ -482,9 +498,7 @@ class AsyncCrud(Generic[ModelType]):
         order_field_map: dict[str, OrderFieldType] | None = None
         order_valid_keys: list[str] | None = None
         if order:
-            resolved_order = (
-                order_fields if order_fields is not None else cls.order_fields
-            )
+            resolved_order = cls._resolve_order_fields(order_fields)
             if resolved_order:
                 keys = facet_keys(resolved_order)
                 order_field_map = dict(zip(keys, resolved_order))
@@ -510,8 +524,21 @@ class AsyncCrud(Generic[ModelType]):
                     ]
                 )
 
+        fixed: dict[str, Any] = {
+            **pagination_fixed,
+            "search_fields": (cls._resolve_search_fields(search_fields) or [])
+            if search
+            else [],
+            "facet_fields": (cls._resolve_facet_fields(facet_fields) or [])
+            if filter
+            else [],
+            "order_fields": (cls._resolve_order_fields(order_fields) or [])
+            if order
+            else [],
+        }
+
         async def dependency(**kwargs: Any) -> dict[str, Any]:
-            result: dict[str, Any] = dict(pagination_fixed)
+            result: dict[str, Any] = dict(fixed)
             for name in pagination_param_names:
                 result[name] = kwargs[name]
 

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/src/fastapi_toolsets/db/core.py

@@ -295,21 +295,27 @@ class Database:
         self,
         tables: list[type[DeclarativeBase]],
         *,
+        session: AsyncSession | None = None,
         mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
         timeout: str = "5s",
     ) -> AbstractAsyncContextManager[AsyncSession]:
-        """Lock PostgreSQL tables for the duration of a dedicated transaction.
+        """Lock PostgreSQL tables for the duration of a transaction.
 
-        Opens its own session from the facade's sessionmaker, changes are
-        committed when the context exits.
+        Without *session*, a dedicated session is opened from the facade's
+        sessionmaker and committed at block exit. That is a **second**
+        connection, and the block must not touch the request session under a
+        conflicting mode. Pass ``session=`` to lock on the request's own
+        transaction instead: one connection, and the block may use it freely.
 
         Args:
             tables: List of SQLAlchemy model classes to lock.
+            session: Existing session whose transaction takes the lock. That
+                transaction holds the lock until it ends.
             mode: Lock mode (default: ``SHARE UPDATE EXCLUSIVE``).
             timeout: Lock timeout (default: ``"5s"``).
 
         Yields:
-            The dedicated session, open within the locked transaction.
+            The session holding the lock: the dedicated one, or *session*.
 
         Raises:
             LockTimeoutError: If the lock cannot be acquired within *timeout*.
@@ -320,6 +326,18 @@ class Database:
             async with db.lock_tables([User, Account]) as session:
                 user = await UserCrud.get(session, [User.id == 1])
                 user.balance += 100
+
+
+            @app.post("/transfer")
+            async def transfer(session=Depends(db)):
+                async with db.lock_tables([Account], session=session):
+                    ...  # same session, same connection
             ```
         """
-        return lock_tables(self._sessionmaker, tables, mode=mode, timeout=timeout)
+        return lock_tables(
+            None if session is not None else self._sessionmaker,
+            tables,
+            session=session,
+            mode=mode,
+            timeout=timeout,
+        )

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/src/fastapi_toolsets/db/locks.py

@@ -39,9 +39,10 @@ class LockMode(str, Enum):
 
 
 def lock_tables(
-    session_maker: async_sessionmaker[_SessionT],
+    session_maker: async_sessionmaker[_SessionT] | None,
     tables: list[type[DeclarativeBase]],
     *,
+    session: _SessionT | None = None,
     mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
     timeout: str = "5s",
 ) -> AbstractAsyncContextManager[_SessionT]:
@@ -50,20 +51,31 @@ def lock_tables(
     Prefer the method on a :class:`Database` instance; use this
     directly only when you manage your own session factory.
 
+    Pass exactly one of *session_maker*, which opens a dedicated session and
+    commits it at block exit, or *session*, which locks on a transaction you
+    already own and so needs only one connection.
+
     Args:
-        session_maker: Async session factory used to create the dedicated
-            session.
+        session_maker: Async session factory for the dedicated session.
+            ``None`` when *session* is given.
         tables: List of SQLAlchemy model classes to lock.
+        session: Existing session whose transaction takes the lock.
         mode: Lock mode (default: SHARE UPDATE EXCLUSIVE).
         timeout: Lock timeout (default: "5s").
 
     Yields:
-        The dedicated session, open within the locked transaction.
+        The session holding the lock: the dedicated one, or *session* itself.
 
     Raises:
+        TypeError: If neither or both of *session_maker* and *session* are given.
         LockTimeoutError: If the lock cannot be acquired within *timeout*.
         PoolExhaustedError: If the connection pool is exhausted.
 
+    Note:
+        With *session*, nothing is committed or rolled back for you: the lock
+        is held until the caller's transaction ends, pending ORM changes flush
+        as it is taken, and ``lock_timeout`` stays set on that transaction.
+
     Example:
         ```python
         from fastapi_toolsets.db import lock_tables
@@ -74,32 +86,53 @@ def lock_tables(
         ```
     """
     table_names = ",".join(table.__tablename__ for table in tables)
+    set_timeout = text(f"SET LOCAL lock_timeout='{timeout}'")
+    acquire = text(f"LOCK {table_names} IN {mode.value} MODE")
+
+    def _translate(e: BaseException) -> None:
+        if isinstance(e, sa_exc.TimeoutError):
+            raise PoolExhaustedError(
+                f"Connection pool exhausted while locking '{table_names}'. "
+            ) from e
+        if isinstance(e, sa_exc.DBAPIError) and _is_lock_not_available(e):
+            raise LockTimeoutError(
+                f"Lock on '{table_names}' could not be acquired within {timeout}."
+            ) from e
 
     @asynccontextmanager
-    async def _lock() -> AsyncGenerator[_SessionT, None]:
-        async with session_maker() as session:
+    async def _lock_dedicated(
+        maker: async_sessionmaker[_SessionT],
+    ) -> AsyncGenerator[_SessionT, None]:
+        async with maker() as dedicated:
             try:
-                await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
-                await session.execute(text(f"LOCK {table_names} IN {mode.value} MODE"))
-                yield session
-                await session.commit()
-            except sa_exc.TimeoutError as e:
-                await session.rollback()
-                raise PoolExhaustedError(
-                    f"Connection pool exhausted while locking '{table_names}'. "
-                ) from e
-            except sa_exc.DBAPIError as e:
-                await session.rollback()
-                if _is_lock_not_available(e):
-                    raise LockTimeoutError(
-                        f"Lock on '{table_names}' could not be acquired within {timeout}."
-                    ) from e
-                raise  # pragma: no cover
-            except BaseException:
-                await session.rollback()
+                await dedicated.execute(set_timeout)
+                await dedicated.execute(acquire)
+                yield dedicated
+                await dedicated.commit()
+            except BaseException as e:
+                await dedicated.rollback()
+                _translate(e)
                 raise
 
-    return _lock()
+    @asynccontextmanager
+    async def _lock_caller(caller: _SessionT) -> AsyncGenerator[_SessionT, None]:
+        try:
+            with caller.no_autoflush:
+                await caller.execute(set_timeout)
+            async with caller.begin_nested():
+                await caller.execute(acquire)
+        except BaseException as e:
+            _translate(e)
+            raise
+        yield caller
+
+    if session_maker is not None and session is None:
+        return _lock_dedicated(session_maker)
+    if session is not None and session_maker is None:
+        return _lock_caller(session)
+    raise TypeError(
+        "lock_tables() requires exactly one of 'session_maker' or 'session'."
+    )
 
 
 @asynccontextmanager
@@ -109,15 +142,17 @@ async def advisory_lock(
     *,
     shared: bool = False,
     nowait: bool = False,
+    xact: bool = False,
     timeout: str | None = None,
 ) -> AsyncGenerator[bool, None]:
-    """Acquire a PostgreSQL session-level advisory lock.
+    """Acquire a PostgreSQL advisory lock.
 
     Args:
         session: AsyncSession instance.
         key: Lock key, either a single ``int`` (bigint) or a ``(int, int)`` pair for namespacing.
         shared: Acquire a shared lock (multiple holders allowed). Default is exclusive.
         nowait: Return ``False`` immediately if the lock is unavailable instead of waiting.
+        xact: Hold the lock until the caller's transaction ends.
         timeout: Maximum wait time (e.g. ``"5s"``, ``"500ms"``). Raises ``DBAPIError``
             if exceeded. Ignored when *nowait* is ``True``.
 
@@ -144,10 +179,14 @@ async def advisory_lock(
 
         async with advisory_lock(session, (1, user_id), shared=True):
             ...
+
+        async with advisory_lock(session, (team_id, question_id), xact=True):
+            ...  # held until the request's transaction commits
         ```
     """
     suffix = "_shared" if shared else ""
-    acquire_fn = f"{'pg_try_advisory_lock' if nowait else 'pg_advisory_lock'}{suffix}"
+    scope = "_xact" if xact else ""
+    acquire_fn = f"pg_{'try_' if nowait else ''}advisory{scope}_lock{suffix}"
     release_fn = f"pg_advisory_unlock{suffix}"
 
     if isinstance(key, tuple):
@@ -180,6 +219,6 @@ async def advisory_lock(
     try:
         yield acquired
     finally:
-        if acquired:
+        if acquired and not xact:
             with session.no_autoflush:
                 await session.execute(release_sql, params)

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/src/fastapi_toolsets/models/watched.py

@@ -1,13 +1,15 @@
 """Field-change monitoring via SQLAlchemy session events."""
 
 import inspect
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
 from enum import Enum
 from typing import Any
 
 from sqlalchemy import event, select, tuple_
 from sqlalchemy import inspect as sa_inspect
-from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.ext.asyncio import AsyncSession, AsyncSessionTransaction
+from sqlalchemy.ext.asyncio import async_session as _async_session
 from sqlalchemy.orm import selectinload
 from sqlalchemy.orm.attributes import set_committed_value as _sa_set_committed_value
 
@@ -25,9 +27,11 @@ class ModelEvent(str, Enum):
 
 
 _CALLBACK_ERROR_MSG = "Event callback raised an unhandled exception"
+_RELOAD_TRANSACTION_ERROR_MSG = "Closing the post-commit reload transaction failed"
 _SESSION_CREATES = "_ft_creates"
 _SESSION_DELETES = "_ft_deletes"
 _SESSION_UPDATES = "_ft_updates"
+_SESSION_PRELOADED = "_ft_preloaded"
 _DEFERRED_STRATEGY_KEY = (("deferred", True), ("instrument", True))
 _EVENT_HANDLERS: dict[tuple[type, ModelEvent], list[Callable[..., Any]]] = {}
 _HANDLER_CACHE: dict[tuple[type, ModelEvent], list[Callable[..., Any]]] = {}
@@ -126,12 +130,24 @@ def _upsert_changes(
         pending[key] = (obj, changes)
 
 
+def _dispatches(session: Any) -> bool:
+    """True when *session* is driven by an :class:`EventSession`."""
+    return isinstance(_async_session(session), EventSession)
+
+
 @event.listens_for(AsyncSession.sync_session_class, "after_flush")
 def _after_flush(session: Any, flush_context: Any) -> None:
+    if _dispatches(session):
+        _collect(session)
+
+
+def _collect(session: Any) -> None:
+    """Record the flushed changes that the next commit will dispatch."""
     # New objects: capture reference. Attributes will be refreshed after commit.
     for obj in session.new:
         if _get_handlers(type(obj), ModelEvent.CREATE):
             session.info.setdefault(_SESSION_CREATES, []).append(obj)
+            _record_loaded_relationships(session, obj)
 
     # Deleted objects: snapshot now while attributes are still loaded.
     for obj in session.deleted:
@@ -155,11 +171,14 @@ def _after_flush(session: Any, flush_context: Any) -> None:
         )
         for field, attr_state in attrs:
             history = attr_state.history
-            if history.has_changes() and history.deleted:
-                changes[field] = {
-                    "old": history.deleted[0],
-                    "new": history.added[0] if history.added else None,
-                }
+            if not history.has_changes():
+                continue
+            change: dict[str, Any] = {
+                "new": history.added[0] if history.added else None
+            }
+            if history.deleted:
+                change["old"] = history.deleted[0]
+            changes[field] = change
 
         if changes:
             _upsert_changes(
@@ -167,6 +186,7 @@ def _after_flush(session: Any, flush_context: Any) -> None:
                 obj,
                 changes,
             )
+            _record_loaded_relationships(session, obj)
 
 
 @event.listens_for(AsyncSession.sync_session_class, "after_rollback")
@@ -176,6 +196,7 @@ def _after_rollback(session: Any) -> None:
     session.info.pop(_SESSION_CREATES, None)
     session.info.pop(_SESSION_DELETES, None)
     session.info.pop(_SESSION_UPDATES, None)
+    session.info.pop(_SESSION_PRELOADED, None)
 
 
 async def _invoke_callback(
@@ -190,9 +211,24 @@ async def _invoke_callback(
         await result
 
 
+async def _dispatch(
+    obj: Any,
+    event_type: ModelEvent,
+    changes: dict[str, dict[str, Any]] | None,
+) -> None:
+    """Run every handler for *obj*, isolating a failure to the handler that raised."""
+    for handler in _get_handlers(type(obj), event_type):
+        try:
+            await _invoke_callback(handler, obj, event_type, changes)
+        except Exception as exc:
+            _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
+
+
 def _loaded_relationships(obj: Any) -> set[str]:
     """Relationship keys currently loaded on *obj*."""
-    state = sa_inspect(obj)
+    state = sa_inspect(obj, raiseerr=False)
+    if state is None:
+        return set()
     unloaded = state.unloaded
     return {
         rel.key
@@ -201,11 +237,38 @@ def _loaded_relationships(obj: Any) -> set[str]:
     }
 
 
+def _record_loaded_relationships(session: Any, obj: Any) -> None:
+    """Merge the relationships loaded on *obj* into the session's record."""
+    store: dict[int, set[str]] = session.info.setdefault(_SESSION_PRELOADED, {})
+    store.setdefault(id(obj), set()).update(_loaded_relationships(obj))
+
+
 def _snapshot_loaded_relationships(session: Any) -> dict[int, set[str]]:
-    """Record loaded relationships for the tracked objects, keyed by ``id``."""
+    """Loaded relationships for the tracked objects, keyed by ``id``."""
+    snapshot = {
+        key: set(value)
+        for key, value in session.info.get(_SESSION_PRELOADED, {}).items()
+    }
     objs = list(session.info.get(_SESSION_CREATES, []))
     objs += [obj for obj, _ in session.info.get(_SESSION_UPDATES, {}).values()]
-    return {id(obj): _loaded_relationships(obj) for obj in objs}
+    for obj in objs:
+        snapshot.setdefault(id(obj), set()).update(_loaded_relationships(obj))
+    return snapshot
+
+
+@contextmanager
+def _suspended_trans_ctx(session: AsyncSession) -> Iterator[None]:
+    """Allow post-commit SQL while an outer ``session.begin()`` block is open."""
+    sync_session = session.sync_session
+    ctx = getattr(sync_session, "_trans_context_manager", None)
+    if ctx is None:
+        yield
+        return
+    sync_session._trans_context_manager = None
+    try:
+        yield
+    finally:
+        sync_session._trans_context_manager = ctx
 
 
 async def _batch_reload(
@@ -231,13 +294,47 @@ async def _batch_reload(
     await session.execute(q)
 
 
+class _EventSessionTransaction(AsyncSessionTransaction):
+    """Transaction context manager that dispatches on a real commit."""
+
+    __slots__ = ()
+
+    async def __aexit__(self, type_: object, value: object, traceback: object) -> None:
+        session = self.session
+        commits = (
+            type_ is None
+            and not self.nested
+            and isinstance(session, EventSession)
+            and self.is_active
+        )
+        preloaded = _snapshot_loaded_relationships(session) if commits else {}
+        await super().__aexit__(type_, value, traceback)
+        if commits:
+            await session._dispatch_pending(preloaded)
+
+
 class EventSession(AsyncSession):
     """AsyncSession subclass that dispatches lifecycle callbacks after commit."""
 
+    def begin(self) -> AsyncSessionTransaction:
+        """Return a transaction context manager that dispatches on commit."""
+        return _EventSessionTransaction(self)
+
+    def begin_nested(self) -> AsyncSessionTransaction:
+        """Return a savepoint context manager; events wait for the real commit."""
+        return _EventSessionTransaction(self, nested=True)
+
     async def commit(self) -> None:
         preloaded = _snapshot_loaded_relationships(self)
         await super().commit()
-
+        await self._dispatch_pending(preloaded)
+
+    async def _dispatch_pending(self, preloaded: dict[int, set[str]]) -> None:
+        """Run the callbacks collected for the transaction that just committed."""
+        # The commit itself flushes, so objects first collected there are only
+        # recorded now; merge them into the pre-commit snapshot.
+        for key, value in self.info.pop(_SESSION_PRELOADED, {}).items():
+            preloaded.setdefault(key, set()).update(value)
         creates: list[Any] = self.info.pop(_SESSION_CREATES, [])
         deletes: list[tuple[Any, dict[str, Any]]] = self.info.pop(_SESSION_DELETES, [])
         field_changes: dict[int, tuple[Any, dict[str, dict[str, Any]]]] = self.info.pop(
@@ -294,40 +391,49 @@ class EventSession(AsyncSession):
             update_items.append((obj, changes))
             objs_by_type.setdefault(type(obj), []).append(obj)
 
-        for model, objs in objs_by_type.items():
-            try:
-                await _batch_reload(self, model, objs, preloaded)
-            except Exception as exc:
-                _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
-
-        # Dispatch CREATE callbacks.
-        for obj in create_items:
-            try:
-                for handler in _get_handlers(type(obj), ModelEvent.CREATE):
-                    await _invoke_callback(handler, obj, ModelEvent.CREATE, None)
-            except Exception as exc:
-                _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
-
-        # Dispatch DELETE callbacks (restore snapshot; row is gone).
-        for obj, snapshot in deletes:
-            try:
-                for key, value in snapshot.items():
-                    _sa_set_committed_value(obj, key, value)
-                for handler in _get_handlers(type(obj), ModelEvent.DELETE):
-                    await _invoke_callback(handler, obj, ModelEvent.DELETE, None)
-            except Exception as exc:
-                _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
-
-        # Dispatch UPDATE callbacks.
-        for obj, changes in update_items:
-            try:
-                for handler in _get_handlers(type(obj), ModelEvent.UPDATE):
-                    await _invoke_callback(handler, obj, ModelEvent.UPDATE, changes)
-            except Exception as exc:
-                _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
+        with _suspended_trans_ctx(self):
+            had_transaction = self.in_transaction()
+            for model, objs in objs_by_type.items():
+                try:
+                    await _batch_reload(self, model, objs, preloaded)
+                except Exception as exc:
+                    _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
+            if not had_transaction and self.in_transaction():
+                await self._end_reload_transaction()
+
+            # Dispatch CREATE callbacks.
+            for obj in create_items:
+                await _dispatch(obj, ModelEvent.CREATE, None)
+
+            # Dispatch DELETE callbacks (restore snapshot; row is gone).
+            for obj, snapshot in deletes:
+                try:
+                    for key, value in snapshot.items():
+                        _sa_set_committed_value(obj, key, value)
+                except Exception as exc:
+                    _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
+                    continue
+                await _dispatch(obj, ModelEvent.DELETE, None)
+
+            # Dispatch UPDATE callbacks.
+            for obj, changes in update_items:
+                await _dispatch(obj, ModelEvent.UPDATE, changes)
+
+    async def _end_reload_transaction(self) -> None:
+        """Commit the read-only transaction the reload opened, keeping state loaded."""
+        sync_session = self.sync_session
+        expire_on_commit = sync_session.expire_on_commit
+        sync_session.expire_on_commit = False
+        try:
+            await super().commit()
+        except Exception as exc:
+            _logger.error(_RELOAD_TRANSACTION_ERROR_MSG, exc_info=exc)
+        finally:
+            sync_session.expire_on_commit = expire_on_commit
 
     async def rollback(self) -> None:
         await super().rollback()
         self.info.pop(_SESSION_CREATES, None)
         self.info.pop(_SESSION_DELETES, None)
         self.info.pop(_SESSION_UPDATES, None)
+        self.info.pop(_SESSION_PRELOADED, None)

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.4}/src/fastapi_toolsets/pytest/utils.py

@@ -4,6 +4,7 @@ import os
 from collections.abc import AsyncGenerator, Callable
 from contextlib import asynccontextmanager
 from typing import Any
+from weakref import WeakKeyDictionary
 
 from httpx import ASGITransport, AsyncClient
 from sqlalchemy import text
@@ -18,6 +19,47 @@ from sqlalchemy.orm import DeclarativeBase
 from ..db.testing import cleanup_tables, create_database
 from ..models.watched import EventSession
 
+_MISSING = object()
+_BASE = object()
+
+_override_layers: WeakKeyDictionary[Any, dict[Any, list[tuple[Any, Any]]]] = (
+    WeakKeyDictionary()
+)
+
+
+def _push_overrides(app: Any, overrides: dict[Any, Any], owner: Any) -> None:
+    """Register *overrides* for *owner* and apply them to *app*."""
+    layers = _override_layers.setdefault(app, {})
+    for key, override in overrides.items():
+        if key not in layers:
+            layers[key] = [(_BASE, app.dependency_overrides.get(key, _MISSING))]
+        layers[key].append((owner, override))
+        app.dependency_overrides[key] = override
+
+
+def _pop_overrides(app: Any, overrides: dict[Any, Any], owner: Any) -> None:
+    """Drop *owner*'s layer and re-apply whichever layer is now on top."""
+    layers = _override_layers.get(app)
+    if layers is None:
+        return
+    for key in overrides:
+        stack = layers.get(key)
+        if stack is None:
+            continue
+        for index, (token, _) in enumerate(stack):
+            if token is owner:
+                del stack[index]
+                break
+        _, current = stack[-1]
+        if current is _MISSING:
+            app.dependency_overrides.pop(key, None)
+        else:
+            app.dependency_overrides[key] = current
+        if len(stack) == 1:
+            del layers[key]
+    if not layers:
+        del _override_layers[app]
+
 
 def _get_xdist_worker(default_test_db: str) -> str:
     """Return the pytest-xdist worker name, or *default_test_db* when not running under xdist.
@@ -168,7 +210,7 @@ async def create_async_client(
         base_url: Base URL for requests. Defaults to "http://test".
         dependency_overrides: Optional mapping of original dependencies to
             their test replacements. Applied via ``app.dependency_overrides``
-            before yielding and cleaned up after.
+            before yielding and restored to their previous state after.
         **kwargs: Additional keyword arguments forwarded to
             :class:`httpx.AsyncClient` (e.g. ``headers``, ``cookies``,
             ``auth``, ``timeout``).
@@ -214,19 +256,20 @@ async def create_async_client(
                 yield c
         ```
     """
-    if dependency_overrides:
-        app.dependency_overrides.update(dependency_overrides)
+    overrides = dependency_overrides or {}
+    owner = object()
 
     transport = ASGITransport(app=app)
     try:
+        if overrides:
+            _push_overrides(app, overrides, owner)
         async with AsyncClient(
             transport=transport, base_url=base_url, **kwargs
         ) as client:
             yield client
     finally:
-        if dependency_overrides:
-            for key in dependency_overrides:
-                app.dependency_overrides.pop(key, None)
+        if overrides:
+            _pop_overrides(app, overrides, owner)
 
 
 @asynccontextmanager