fastapi-toolsets 4.1.3__tar.gz → 5.0.0b1__tar.gz

{fastapi_toolsets-4.1.3 → fastapi_toolsets-5.0.0b1}/PKG-INFO

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

{fastapi_toolsets-4.1.3 → fastapi_toolsets-5.0.0b1}/pyproject.toml

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

{fastapi_toolsets-4.1.3 → fastapi_toolsets-5.0.0b1}/src/fastapi_toolsets/__init__.py

@@ -7,18 +7,21 @@ Example usage:
     from fastapi import FastAPI, Depends
     from fastapi_toolsets.exceptions import init_exceptions_handlers
     from fastapi_toolsets.crud import CrudFactory
-    from fastapi_toolsets.db import create_db_dependency
+    from fastapi_toolsets.db import Database
     from fastapi_toolsets.schemas import Response
 
+    db = Database("postgresql+asyncpg://postgres:postgres@localhost/app")
+
     app = FastAPI()
+    db.install(app)
     init_exceptions_handlers(app)
 
     UserCrud = CrudFactory(User)
 
     @app.get("/users/{user_id}", response_model=Response[dict])
-    async def get_user(user_id: int, session = Depends(get_db)):
+    async def get_user(user_id: int, session = Depends(db)):
         user = await UserCrud.get(session, [User.id == user_id])
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "4.1.3"
+__version__ = "5.0.0b1"

{fastapi_toolsets-4.1.3 → fastapi_toolsets-5.0.0b1}/src/fastapi_toolsets/crud/factory.py

@@ -22,7 +22,7 @@ from sqlalchemy.orm import DeclarativeBase, QueryableAttribute, selectinload
 from sqlalchemy.sql.base import ExecutableOption
 from sqlalchemy.sql.roles import WhereHavingRole
 
-from ..db import get_transaction
+from ..db import transaction
 from ..exceptions import InvalidOrderFieldError, NotFoundError
 from ..schemas import (
     CursorPaginatedResponse,
@@ -716,7 +716,7 @@ class AsyncCrud(Generic[ModelType]):
         Returns:
             Created model instance, or ``Response[schema]`` when ``schema`` is given.
         """
-        async with get_transaction(session):
+        async with transaction(session):
             m2m_exclude = cls._m2m_schema_fields()
             data = (
                 obj.model_dump(exclude=m2m_exclude) if m2m_exclude else obj.model_dump()
@@ -1067,7 +1067,7 @@ class AsyncCrud(Generic[ModelType]):
         Raises:
             NotFoundError: If no record found
         """
-        async with get_transaction(session):
+        async with transaction(session):
             m2m_exclude = cls._m2m_schema_fields()
 
             # Eagerly load M2M relationships that will be updated so that
@@ -1127,7 +1127,7 @@ class AsyncCrud(Generic[ModelType]):
         Returns:
             Model instance
         """
-        async with get_transaction(session):
+        async with transaction(session):
             values = obj.model_dump(exclude_unset=True)
             q = insert(cls.model).values(**values)
             if set_:
@@ -1189,7 +1189,7 @@ class AsyncCrud(Generic[ModelType]):
         Returns:
             ``None``, or ``Response[None]`` when ``return_response=True``.
         """
-        async with get_transaction(session):
+        async with transaction(session):
             result = await session.execute(select(cls.model).where(and_(*filters)))
             objects = result.scalars().all()
             for obj in objects:

fastapi_toolsets-5.0.0b1/src/fastapi_toolsets/db/__init__.py

@@ -0,0 +1,18 @@
+"""Database package: the ``Database`` facade plus PostgreSQL power-tools."""
+
+from .core import Database, transaction
+from .locks import LockMode, advisory_lock, lock_tables
+from .m2m import m2m_add, m2m_remove, m2m_set
+from .watch import wait_for_row_change
+
+__all__ = [
+    "Database",
+    "LockMode",
+    "advisory_lock",
+    "lock_tables",
+    "m2m_add",
+    "m2m_remove",
+    "m2m_set",
+    "transaction",
+    "wait_for_row_change",
+]

fastapi_toolsets-5.0.0b1/src/fastapi_toolsets/db/core.py

@@ -0,0 +1,315 @@
+"""The ``Database`` facade: session lifecycle, dependency, middleware, transactions."""
+
+from collections.abc import AsyncGenerator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import Any
+
+from sqlalchemy import exc as sa_exc
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+from starlette.requests import Request
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from ..exceptions import PoolExhaustedError
+from .locks import LockMode, lock_tables
+
+
+@asynccontextmanager
+async def transaction(
+    session: AsyncSession,
+) -> AsyncGenerator[AsyncSession, None]:
+    """Run a block inside a savepoint-aware transaction.
+
+    If *session* is already in a transaction, a nested transaction (savepoint)
+    is opened so the block can roll back independently. Otherwise a top-level
+    transaction is started. Commits on clean exit, rolls back on exception.
+
+    Args:
+        session: AsyncSession instance.
+
+    Yields:
+        The session within the transaction context.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import transaction
+
+        async with transaction(session):
+            session.add(model)
+        ```
+    """
+    if session.in_transaction():
+        async with session.begin_nested():
+            yield session
+    else:
+        async with session.begin():
+            yield session
+
+
+class _CommitOnResponseMiddleware:
+    """Commit the request's DB session before the response is sent."""
+
+    def __init__(self, app: ASGIApp, *, state_attr: str) -> None:
+        self.app = app
+        self.state_attr = state_attr
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                # ``scope["state"]`` is the same dict ``request.state`` writes
+                # to, so this is the session stashed by the dependency.
+                state = scope.get("state")
+                session = state.get(self.state_attr) if state else None
+                if session is not None and session.in_transaction():
+                    await session.commit()
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+
+class Database:
+    """One object that owns the engine, sessions, dependency, and middleware.
+
+    Provide exactly one of *url* (the facade builds and disposes the engine) or
+    *engine* (an engine you own, e.g. for Alembic or ``event.listen``, left
+    untouched).
+
+    Args:
+        url: Database connection URL (e.g. ``"postgresql+asyncpg://..."``).
+        engine: An existing :class:`AsyncEngine` to reuse instead of *url*.
+        session_class: Session class for the sessionmaker (e.g. ``EventSession``).
+        expire_on_commit: Expire attributes after commit. Defaults to ``False``.
+        autoflush: Autoflush the session before queries. Defaults to ``True``.
+        **engine_options: Extra keyword arguments forwarded to
+            :func:`create_async_engine` (URL mode only, e.g. ``pool_size``,
+            ``echo``, ``connect_args``).
+
+    Raises:
+        TypeError: If neither or both of *url* and *engine* are given, or if
+            *engine_options* are passed together with *engine*.
+
+    Example:
+        ```python
+        from fastapi import Depends, FastAPI
+        from fastapi_toolsets.db import Database
+
+        db = Database("postgresql+asyncpg://postgres:postgres@localhost/app")
+
+        app = FastAPI()
+        db.install(app)
+
+        @app.get("/users/{user_id}")
+        async def get_user(user_id: int, session=Depends(db)):
+            return await UserCrud.get(session, [User.id == user_id])
+        ```
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        *,
+        engine: AsyncEngine | None = None,
+        session_class: type[AsyncSession] = AsyncSession,
+        expire_on_commit: bool = False,
+        autoflush: bool = True,
+        **engine_options: Any,
+    ) -> None:
+        if (url is None) == (engine is None):
+            raise TypeError(
+                "Database requires exactly one of 'url' or 'engine' "
+                "(got both or neither)."
+            )
+        if engine is not None and engine_options:
+            raise TypeError(
+                "engine_options are only valid in URL mode; configure the "
+                "engine you pass via 'engine=' yourself."
+            )
+
+        if engine is not None:
+            self._owns_engine = False
+            self.engine: AsyncEngine = engine
+        else:
+            assert url is not None  # guaranteed by the XOR check above
+            self._owns_engine = True
+            self.engine = create_async_engine(url, **engine_options)
+        self._sessionmaker: async_sessionmaker[AsyncSession] = async_sessionmaker(
+            self.engine,
+            class_=session_class,
+            expire_on_commit=expire_on_commit,
+            autoflush=autoflush,
+        )
+        # Private, per-instance state attribute; cannot collide with another
+        # Database or be mismatched against the middleware.
+        self._state_attr = f"_ft_db_session_{id(self):x}"
+        self._middleware_installed = False
+        self._disposed = False
+
+    async def _dispose(self) -> None:
+        """Dispose the engine once, only if we own it (idempotent)."""
+        if self._owns_engine and not self._disposed:
+            self._disposed = True
+            await self.engine.dispose()
+
+    @asynccontextmanager
+    async def lifespan(self, app: Any) -> AsyncGenerator[None, None]:
+        """Dispose the engine on shutdown; use as ``FastAPI(lifespan=db.lifespan)``.
+
+        Args:
+            app: The ASGI application (unused; required by the lifespan protocol).
+
+        Yields:
+            Control to the application for its lifetime.
+
+        Example:
+            ```python
+            app = FastAPI(lifespan=db.lifespan)
+            ```
+        """
+        try:
+            yield
+        finally:
+            await self._dispose()
+
+    def install(self, app: Any) -> None:
+        """Wire the commit middleware and engine disposal onto *app*.
+
+        Args:
+            app: The FastAPI/Starlette application to wire.
+
+        Example:
+            ```python
+            @asynccontextmanager
+            async def lifespan(app):
+                ...  # your startup
+                yield
+                ...  # your shutdown
+
+            app = FastAPI(lifespan=lifespan)
+            db.install(app)
+            ```
+        """
+        app.add_middleware(_CommitOnResponseMiddleware, state_attr=self._state_attr)
+        self._middleware_installed = True
+
+        inner_lifespan = app.router.lifespan_context
+
+        @asynccontextmanager
+        async def _composed(app_: Any) -> AsyncGenerator[None, None]:
+            async with self.lifespan(app_):
+                async with inner_lifespan(app_):
+                    yield
+
+        app.router.lifespan_context = _composed
+
+    @asynccontextmanager
+    async def _open(self) -> AsyncGenerator[AsyncSession, None]:
+        """Open a session and eagerly acquire a connection (fail-fast on pool)."""
+        async with self._sessionmaker() as session:
+            try:
+                await session.connection()
+            except sa_exc.TimeoutError as e:
+                raise PoolExhaustedError() from e
+            yield session
+
+    async def __call__(self, request: Request) -> AsyncGenerator[AsyncSession, None]:
+        """FastAPI dependency: yield a session and commit once at the right time.
+
+        Args:
+            request: The incoming request (injected by FastAPI).
+
+        Yields:
+            An AsyncSession for the duration of the request.
+
+        Example:
+            ```python
+            @app.get("/users/{user_id}")
+            async def get_user(user_id: int, session=Depends(db)):
+                return await UserCrud.get(session, [User.id == user_id])
+            ```
+        """
+        async with self._open() as session:
+            setattr(request.state, self._state_attr, session)
+            yield session
+            if not self._middleware_installed and session.in_transaction():
+                await session.commit()
+
+    @asynccontextmanager
+    async def session(self) -> AsyncGenerator[AsyncSession, None]:
+        """Open a session outside request handlers (background tasks, CLI, tests).
+
+        Commits on clean exit, rolls back on exception.
+
+        Yields:
+            An AsyncSession ready for database operations.
+
+        Example:
+            ```python
+            async with db.session() as session:
+                user = await UserCrud.get(session, [User.id == 1])
+            ```
+        """
+        async with self._open() as session:
+            yield session
+            if session.in_transaction():
+                await session.commit()
+
+    @asynccontextmanager
+    async def begin(self) -> AsyncGenerator[AsyncSession, None]:
+        """Open a session already inside a transaction (sugar for the common case).
+
+        Equivalent to ``session()`` + :func:`transaction`. Commits on clean exit,
+        rolls back on exception.
+
+        Yields:
+            An AsyncSession open within a transaction.
+
+        Example:
+            ```python
+            async with db.begin() as session:
+                session.add(User(name="ada"))
+            ```
+        """
+        async with self.session() as session, transaction(session):
+            yield session
+
+    def lock_tables(
+        self,
+        tables: list[type[DeclarativeBase]],
+        *,
+        mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
+        timeout: str = "5s",
+    ) -> AbstractAsyncContextManager[AsyncSession]:
+        """Lock PostgreSQL tables for the duration of a dedicated transaction.
+
+        Opens its own session from the facade's sessionmaker, changes are
+        committed when the context exits.
+
+        Args:
+            tables: List of SQLAlchemy model classes to lock.
+            mode: Lock mode (default: ``SHARE UPDATE EXCLUSIVE``).
+            timeout: Lock timeout (default: ``"5s"``).
+
+        Yields:
+            The dedicated session, open within the locked transaction.
+
+        Raises:
+            LockTimeoutError: If the lock cannot be acquired within *timeout*.
+            PoolExhaustedError: If the connection pool is exhausted.
+
+        Example:
+            ```python
+            async with db.lock_tables([User, Account]) as session:
+                user = await UserCrud.get(session, [User.id == 1])
+                user.balance += 100
+            ```
+        """
+        return lock_tables(self._sessionmaker, tables, mode=mode, timeout=timeout)

fastapi_toolsets-5.0.0b1/src/fastapi_toolsets/db/locks.py

@@ -0,0 +1,185 @@
+"""PostgreSQL locking helpers: table locks and advisory locks."""
+
+from collections.abc import AsyncGenerator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from enum import Enum
+from typing import TypeVar
+
+import asyncpg
+from sqlalchemy import exc as sa_exc
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+from ..exceptions import LockTimeoutError, PoolExhaustedError
+
+_SessionT = TypeVar("_SessionT", bound=AsyncSession)
+
+
+def _is_lock_not_available(e: sa_exc.DBAPIError) -> bool:
+    return e.orig is not None and isinstance(
+        e.orig.__cause__, asyncpg.exceptions.LockNotAvailableError
+    )
+
+
+class LockMode(str, Enum):
+    """PostgreSQL table lock modes.
+
+    See: https://www.postgresql.org/docs/current/explicit-locking.html
+    """
+
+    ACCESS_SHARE = "ACCESS SHARE"
+    ROW_SHARE = "ROW SHARE"
+    ROW_EXCLUSIVE = "ROW EXCLUSIVE"
+    SHARE_UPDATE_EXCLUSIVE = "SHARE UPDATE EXCLUSIVE"
+    SHARE = "SHARE"
+    SHARE_ROW_EXCLUSIVE = "SHARE ROW EXCLUSIVE"
+    EXCLUSIVE = "EXCLUSIVE"
+    ACCESS_EXCLUSIVE = "ACCESS EXCLUSIVE"
+
+
+def lock_tables(
+    session_maker: async_sessionmaker[_SessionT],
+    tables: list[type[DeclarativeBase]],
+    *,
+    mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
+    timeout: str = "5s",
+) -> AbstractAsyncContextManager[_SessionT]:
+    """Lock PostgreSQL tables for the duration of a transaction.
+
+    Prefer the method on a :class:`Database` instance; use this
+    directly only when you manage your own session factory.
+
+    Args:
+        session_maker: Async session factory used to create the dedicated
+            session.
+        tables: List of SQLAlchemy model classes to lock.
+        mode: Lock mode (default: SHARE UPDATE EXCLUSIVE).
+        timeout: Lock timeout (default: "5s").
+
+    Yields:
+        The dedicated session, open within the locked transaction.
+
+    Raises:
+        LockTimeoutError: If the lock cannot be acquired within *timeout*.
+        PoolExhaustedError: If the connection pool is exhausted.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import lock_tables
+
+        async with lock_tables(session_maker, [User, Account]) as session:
+            user = await UserCrud.get(session, [User.id == 1])
+            user.balance += 100
+        ```
+    """
+    table_names = ",".join(table.__tablename__ for table in tables)
+
+    @asynccontextmanager
+    async def _lock() -> AsyncGenerator[_SessionT, None]:
+        async with session_maker() as session:
+            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()
+                raise
+
+    return _lock()
+
+
+@asynccontextmanager
+async def advisory_lock(
+    session: AsyncSession,
+    key: int | tuple[int, int],
+    *,
+    shared: bool = False,
+    nowait: bool = False,
+    timeout: str | None = None,
+) -> AsyncGenerator[bool, None]:
+    """Acquire a PostgreSQL session-level 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.
+        timeout: Maximum wait time (e.g. ``"5s"``, ``"500ms"``). Raises ``DBAPIError``
+            if exceeded. Ignored when *nowait* is ``True``.
+
+    Yields:
+        ``True`` if the lock was acquired, ``False`` if *nowait* is ``True`` and the lock
+        is already held.
+
+    Raises:
+        LockTimeoutError: If *timeout* is set and the lock cannot be acquired in time.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import advisory_lock
+
+        async with advisory_lock(session, 42):
+            ...
+
+        async with advisory_lock(session, 42, nowait=True) as acquired:
+            if not acquired:
+                raise HTTPException(409, "Resource is locked")
+
+        async with advisory_lock(session, 42, timeout="5s"):
+            ...
+
+        async with advisory_lock(session, (1, user_id), shared=True):
+            ...
+        ```
+    """
+    suffix = "_shared" if shared else ""
+    acquire_fn = f"{'pg_try_advisory_lock' if nowait else 'pg_advisory_lock'}{suffix}"
+    release_fn = f"pg_advisory_unlock{suffix}"
+
+    if isinstance(key, tuple):
+        k1, k2 = key
+        args = "CAST(:k1 AS integer), CAST(:k2 AS integer)"
+        params: dict[str, int] = {"k1": k1, "k2": k2}
+    else:
+        args = ":k"
+        params = {"k": key}
+
+    acquire_sql = text(f"SELECT {acquire_fn}({args})")
+    release_sql = text(f"SELECT {release_fn}({args})")
+
+    # Lock management runs raw SQL on the caller's session. Guard it with
+    # ``no_autoflush`` so acquiring or releasing the lock never flushes the
+    # caller's pending ORM changes; SQLAlchemy 2.1 autoflushes on raw
+    # ``text()`` too, where 2.0 did not.
+    try:
+        with session.no_autoflush:
+            if timeout is not None and not nowait:
+                await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
+            result = await session.execute(acquire_sql, params)
+    except sa_exc.DBAPIError as e:
+        if _is_lock_not_available(e):
+            raise LockTimeoutError(
+                f"Advisory lock {key!r} could not be acquired within {timeout}."
+            ) from e
+        raise  # pragma: no cover
+    acquired = result.scalar() if nowait else True
+    try:
+        yield acquired
+    finally:
+        if acquired:
+            with session.no_autoflush:
+                await session.execute(release_sql, params)