fastapi-toolsets 4.1.0__tar.gz → 4.1.2__tar.gz

{fastapi_toolsets-4.1.0 → fastapi_toolsets-4.1.2}/PKG-INFO

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

{fastapi_toolsets-4.1.0 → fastapi_toolsets-4.1.2}/pyproject.toml

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

{fastapi_toolsets-4.1.0 → fastapi_toolsets-4.1.2}/src/fastapi_toolsets/__init__.py

@@ -21,4 +21,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "4.1.0"
+__version__ = "4.1.2"

{fastapi_toolsets-4.1.0 → fastapi_toolsets-4.1.2}/src/fastapi_toolsets/db.py

@@ -6,13 +6,22 @@ from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from enum import Enum
 from typing import Any, TypeVar, cast
 
+import asyncpg
 from sqlalchemy import Table, delete, text, tuple_
+from sqlalchemy import exc as sa_exc
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase, QueryableAttribute
 from sqlalchemy.orm.relationships import RelationshipProperty
 
-from .exceptions import NotFoundError
+from .exceptions import LockTimeoutError, NotFoundError, PoolExhaustedError
+
+
+def _is_lock_not_available(e: sa_exc.DBAPIError) -> bool:
+    return e.orig is not None and isinstance(
+        e.orig.__cause__, asyncpg.exceptions.LockNotAvailableError
+    )
+
 
 __all__ = [
     "LockMode",
@@ -65,7 +74,10 @@ def create_db_dependency(
 
     async def get_db() -> AsyncGenerator[_SessionT, None]:
         async with session_maker() as session:
-            await session.connection()
+            try:
+                await session.connection()
+            except sa_exc.TimeoutError as e:
+                raise PoolExhaustedError() from e
             yield session
             if session.in_transaction():
                 await session.commit()
@@ -198,6 +210,18 @@ def lock_tables(
                 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
@@ -229,8 +253,7 @@ async def advisory_lock(
         is already held.
 
     Raises:
-        sqlalchemy.exc.DBAPIError: If *timeout* is set and the lock cannot be acquired
-            in time.
+        LockTimeoutError: If *timeout* is set and the lock cannot be acquired in time.
 
     Example:
         ```python
@@ -268,7 +291,14 @@ async def advisory_lock(
     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)
+    try:
+        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

{fastapi_toolsets-4.1.0 → fastapi_toolsets-4.1.2}/src/fastapi_toolsets/exceptions/__init__.py

@@ -8,8 +8,10 @@ from .exceptions import (
     InvalidFacetFilterError,
     InvalidOrderFieldError,
     InvalidSearchColumnError,
+    LockTimeoutError,
     NoSearchableFieldsError,
     NotFoundError,
+    PoolExhaustedError,
     UnauthorizedError,
     UnsupportedFacetTypeError,
     generate_error_responses,
@@ -26,8 +28,10 @@ __all__ = [
     "InvalidFacetFilterError",
     "InvalidOrderFieldError",
     "InvalidSearchColumnError",
+    "LockTimeoutError",
     "NoSearchableFieldsError",
     "NotFoundError",
+    "PoolExhaustedError",
     "UnauthorizedError",
     "UnsupportedFacetTypeError",
 ]

{fastapi_toolsets-4.1.0 → fastapi_toolsets-4.1.2}/src/fastapi_toolsets/exceptions/exceptions.py

@@ -223,6 +223,35 @@ class InvalidOrderFieldError(ApiException):
         )
 
 
+class PoolExhaustedError(ApiException):
+    """HTTP 503 - Database connection pool is exhausted."""
+
+    api_error = ApiError(
+        code=503,
+        msg="Service Unavailable",
+        desc=(
+            "The database connection pool is exhausted. "
+            "Too many concurrent requests are holding connections. "
+            "Retry shortly or contact support if the issue persists."
+        ),
+        err_code="DB-503-POOL",
+    )
+
+
+class LockTimeoutError(ApiException):
+    """HTTP 503 - A database lock could not be acquired within the timeout."""
+
+    api_error = ApiError(
+        code=503,
+        msg="Service Unavailable",
+        desc=(
+            "A database lock could not be acquired within the allowed timeout. "
+            "The resource is under heavy contention. Retry shortly."
+        ),
+        err_code="DB-503-LOCK",
+    )
+
+
 def generate_error_responses(
     *errors: type[ApiException],
 ) -> dict[int | str, dict[str, Any]]:

{fastapi_toolsets-4.1.0 → fastapi_toolsets-4.1.2}/src/fastapi_toolsets/pytest/utils.py

@@ -7,7 +7,7 @@ from typing import Any
 
 from httpx import ASGITransport, AsyncClient
 from sqlalchemy import text
-from sqlalchemy.engine import make_url
+from sqlalchemy.engine import URL, make_url
 from sqlalchemy.ext.asyncio import (
     AsyncSession,
     async_sessionmaker,
@@ -63,6 +63,8 @@ def worker_database_url(database_url: str, default_test_db: str) -> str:
 async def create_worker_database(
     database_url: str,
     default_test_db: str = "test_db",
+    *,
+    server_url: str | None = None,
 ) -> AsyncGenerator[str, None]:
     """Create and drop a per-worker database for pytest-xdist isolation.
 
@@ -74,10 +76,13 @@ async def create_worker_database(
     name (e.g. ``_gw0``).  Otherwise it is suffixed with *default_test_db*.
 
     Args:
-        database_url: Original database connection URL (used as the server
-            connection and as the base for the worker database name).
+        database_url: Original database connection URL (used as the base for
+            the worker database name).
         default_test_db: Suffix appended to the database name when
             ``PYTEST_XDIST_WORKER`` is not set. Defaults to ``"test_db"``.
+        server_url: URL used for server-level DDL (must point to an existing
+            database on the same server).  Defaults to *database_url* with the
+            database omitted, letting asyncpg fall back to the username.
 
     Yields:
         The worker-specific database URL.
@@ -86,7 +91,7 @@ async def create_worker_database(
         ```python
         from fastapi_toolsets.pytest import create_worker_database, create_db_session
 
-        DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/test_db"
+        DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/myapp"
 
         @pytest.fixture(scope="session")
         async def worker_db_url():
@@ -107,11 +112,21 @@ async def create_worker_database(
     worker_db_name = make_url(worker_url).database
     assert worker_db_name is not None
 
-    engine = create_async_engine(database_url, isolation_level="AUTOCOMMIT")
+    _parsed = make_url(database_url)
+    _server_url = server_url or URL.create(
+        drivername=_parsed.drivername,
+        username=_parsed.username,
+        password=_parsed.password,
+        host=_parsed.host,
+        port=_parsed.port,
+        query=_parsed.query,
+    ).render_as_string(hide_password=False)
+
+    engine = create_async_engine(_server_url, isolation_level="AUTOCOMMIT")
     try:
         async with engine.connect() as conn:
             await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
-        await create_database(db_name=worker_db_name, server_url=database_url)
+        await create_database(db_name=worker_db_name, server_url=_server_url)
 
         yield worker_url
 
@@ -126,6 +141,7 @@ async def create_async_client(
     app: Any,
     base_url: str = "http://test",
     dependency_overrides: dict[Callable[..., Any], Callable[..., Any]] | None = None,
+    **kwargs: Any,
 ) -> AsyncGenerator[AsyncClient, None]:
     """Create an async httpx client for testing FastAPI applications.
 
@@ -135,6 +151,9 @@ async def create_async_client(
         dependency_overrides: Optional mapping of original dependencies to
             their test replacements. Applied via ``app.dependency_overrides``
             before yielding and cleaned up after.
+        **kwargs: Additional keyword arguments forwarded to
+            :class:`httpx.AsyncClient` (e.g. ``headers``, ``cookies``,
+            ``auth``, ``timeout``).
 
     Yields:
         An AsyncClient configured for the app.
@@ -182,7 +201,9 @@ async def create_async_client(
 
     transport = ASGITransport(app=app)
     try:
-        async with AsyncClient(transport=transport, base_url=base_url) as client:
+        async with AsyncClient(
+            transport=transport, base_url=base_url, **kwargs
+        ) as client:
             yield client
     finally:
         if dependency_overrides:
@@ -199,6 +220,8 @@ async def create_db_session(
     expire_on_commit: bool = False,
     drop_tables: bool = True,
     cleanup: bool = False,
+    engine_kwargs: dict[str, Any] | None = None,
+    session_kwargs: dict[str, Any] | None = None,
 ) -> AsyncGenerator[AsyncSession, None]:
     """Create a database session for testing.
 
@@ -213,6 +236,12 @@ async def create_db_session(
         drop_tables: Drop tables after test. Defaults to True.
         cleanup: Truncate all tables after test using
             :func:`cleanup_tables`. Defaults to False.
+        engine_kwargs: Additional keyword arguments forwarded to
+            :func:`sqlalchemy.ext.asyncio.create_async_engine`
+            (e.g. ``pool_size``, ``connect_args``).
+        session_kwargs: Additional keyword arguments forwarded to
+            :class:`sqlalchemy.ext.asyncio.async_sessionmaker`
+            (e.g. ``autoflush``, ``class_``).
 
     Yields:
         An AsyncSession ready for database operations.
@@ -237,15 +266,17 @@ async def create_db_session(
             await db_session.commit()
         ```
     """
-    engine = create_async_engine(database_url, echo=echo)
+    engine = create_async_engine(database_url, echo=echo, **(engine_kwargs or {}))
 
     try:
-        # Create tables
         async with engine.begin() as conn:
             await conn.run_sync(base.metadata.create_all)
 
         session_maker = async_sessionmaker(
-            engine, expire_on_commit=expire_on_commit, class_=EventSession
+            engine,
+            expire_on_commit=expire_on_commit,
+            class_=EventSession,
+            **(session_kwargs or {}),
         )
         async with session_maker() as session:
             yield session