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

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

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

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

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

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

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

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.3}/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.3"

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.3}/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.3}/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.3}/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.3}/src/fastapi_toolsets/models/watched.py

@@ -155,11 +155,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(
@@ -190,6 +193,19 @@ 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)
@@ -302,29 +318,21 @@ class EventSession(AsyncSession):
 
         # 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)
+            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)
-                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)
+                continue
+            await _dispatch(obj, ModelEvent.DELETE, None)
 
         # 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)
+            await _dispatch(obj, ModelEvent.UPDATE, changes)
 
     async def rollback(self) -> None:
         await super().rollback()

{fastapi_toolsets-5.1.2 → fastapi_toolsets-5.1.3}/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