fastapi-toolsets 0.1.0__py3-none-any.whl

fastapi_toolsets/crud.py

@@ -0,0 +1,378 @@
+"""Generic async CRUD operations for SQLAlchemy models."""
+
+from collections.abc import Sequence
+from typing import Any, ClassVar, Generic, Self, TypeVar, cast
+
+from pydantic import BaseModel
+from sqlalchemy import and_, func, select
+from sqlalchemy import delete as sql_delete
+from sqlalchemy.dialects.postgresql import insert
+from sqlalchemy.exc import NoResultFound
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.sql.roles import WhereHavingRole
+
+from .db import get_transaction
+from .exceptions import NotFoundError
+
+__all__ = [
+    "AsyncCrud",
+    "CrudFactory",
+]
+
+ModelType = TypeVar("ModelType", bound=DeclarativeBase)
+
+
+class AsyncCrud(Generic[ModelType]):
+    """Generic async CRUD operations for SQLAlchemy models.
+
+    Subclass this and set the `model` class variable, or use `CrudFactory`.
+
+    Example:
+        class UserCrud(AsyncCrud[User]):
+            model = User
+
+        # Or use the factory:
+        UserCrud = CrudFactory(User)
+
+        # Then use it:
+        user = await UserCrud.get(session, [User.id == 1])
+        users = await UserCrud.get_multi(session, limit=10)
+    """
+
+    model: ClassVar[type[DeclarativeBase]]
+
+    @classmethod
+    async def create(
+        cls: type[Self],
+        session: AsyncSession,
+        obj: BaseModel,
+    ) -> ModelType:
+        """Create a new record in the database.
+
+        Args:
+            session: DB async session
+            obj: Pydantic model with data to create
+
+        Returns:
+            Created model instance
+        """
+        async with get_transaction(session):
+            db_model = cls.model(**obj.model_dump())
+            session.add(db_model)
+        await session.refresh(db_model)
+        return cast(ModelType, db_model)
+
+    @classmethod
+    async def get(
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any],
+        *,
+        with_for_update: bool = False,
+        load_options: list[Any] | None = None,
+    ) -> ModelType:
+        """Get exactly one record. Raises NotFoundError if not found.
+
+        Args:
+            session: DB async session
+            filters: List of SQLAlchemy filter conditions
+            with_for_update: Lock the row for update
+            load_options: SQLAlchemy loader options (e.g., selectinload)
+
+        Returns:
+            Model instance
+
+        Raises:
+            NotFoundError: If no record found
+            MultipleResultsFound: If more than one record found
+        """
+        q = select(cls.model).where(and_(*filters))
+        if load_options:
+            q = q.options(*load_options)
+        if with_for_update:
+            q = q.with_for_update()
+        result = await session.execute(q)
+        item = result.unique().scalar_one_or_none()
+        if not item:
+            raise NotFoundError()
+        return cast(ModelType, item)
+
+    @classmethod
+    async def first(
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any] | None = None,
+        *,
+        load_options: list[Any] | None = None,
+    ) -> ModelType | None:
+        """Get the first matching record, or None.
+
+        Args:
+            session: DB async session
+            filters: List of SQLAlchemy filter conditions
+            load_options: SQLAlchemy loader options
+
+        Returns:
+            Model instance or None
+        """
+        q = select(cls.model)
+        if filters:
+            q = q.where(and_(*filters))
+        if load_options:
+            q = q.options(*load_options)
+        result = await session.execute(q)
+        return cast(ModelType | None, result.unique().scalars().first())
+
+    @classmethod
+    async def get_multi(
+        cls: type[Self],
+        session: AsyncSession,
+        *,
+        filters: list[Any] | None = None,
+        load_options: list[Any] | None = None,
+        order_by: Any | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> Sequence[ModelType]:
+        """Get multiple records from the database.
+
+        Args:
+            session: DB async session
+            filters: List of SQLAlchemy filter conditions
+            load_options: SQLAlchemy loader options
+            order_by: Column or list of columns to order by
+            limit: Max number of rows to return
+            offset: Rows to skip
+
+        Returns:
+            List of model instances
+        """
+        q = select(cls.model)
+        if filters:
+            q = q.where(and_(*filters))
+        if load_options:
+            q = q.options(*load_options)
+        if order_by is not None:
+            q = q.order_by(order_by)
+        if offset is not None:
+            q = q.offset(offset)
+        if limit is not None:
+            q = q.limit(limit)
+        result = await session.execute(q)
+        return cast(Sequence[ModelType], result.unique().scalars().all())
+
+    @classmethod
+    async def update(
+        cls: type[Self],
+        session: AsyncSession,
+        obj: BaseModel,
+        filters: list[Any],
+        *,
+        exclude_unset: bool = True,
+        exclude_none: bool = False,
+    ) -> ModelType:
+        """Update a record in the database.
+
+        Args:
+            session: DB async session
+            obj: Pydantic model with update data
+            filters: List of SQLAlchemy filter conditions
+            exclude_unset: Exclude fields not explicitly set in the schema
+            exclude_none: Exclude fields with None value
+
+        Returns:
+            Updated model instance
+
+        Raises:
+            NotFoundError: If no record found
+        """
+        async with get_transaction(session):
+            db_model = await cls.get(session=session, filters=filters)
+            values = obj.model_dump(
+                exclude_unset=exclude_unset, exclude_none=exclude_none
+            )
+            for key, value in values.items():
+                setattr(db_model, key, value)
+        await session.refresh(db_model)
+        return db_model
+
+    @classmethod
+    async def upsert(
+        cls: type[Self],
+        session: AsyncSession,
+        obj: BaseModel,
+        index_elements: list[str],
+        *,
+        set_: BaseModel | None = None,
+        where: WhereHavingRole | None = None,
+    ) -> ModelType | None:
+        """Create or update a record (PostgreSQL only).
+
+        Uses INSERT ... ON CONFLICT for atomic upsert.
+
+        Args:
+            session: DB async session
+            obj: Pydantic model with data
+            index_elements: Columns for ON CONFLICT (unique constraint)
+            set_: Pydantic model for ON CONFLICT DO UPDATE SET
+            where: WHERE clause for ON CONFLICT DO UPDATE
+
+        Returns:
+            Model instance
+        """
+        async with get_transaction(session):
+            values = obj.model_dump(exclude_unset=True)
+            q = insert(cls.model).values(**values)
+            if set_:
+                q = q.on_conflict_do_update(
+                    index_elements=index_elements,
+                    set_=set_.model_dump(exclude_unset=True),
+                    where=where,
+                )
+            else:
+                q = q.on_conflict_do_nothing(index_elements=index_elements)
+            q = q.returning(cls.model)
+            result = await session.execute(q)
+            try:
+                db_model = result.unique().scalar_one()
+            except NoResultFound:
+                db_model = await cls.first(
+                    session=session,
+                    filters=[getattr(cls.model, k) == v for k, v in values.items()],
+                )
+        return cast(ModelType | None, db_model)
+
+    @classmethod
+    async def delete(
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any],
+    ) -> bool:
+        """Delete records from the database.
+
+        Args:
+            session: DB async session
+            filters: List of SQLAlchemy filter conditions
+
+        Returns:
+            True if deletion was executed
+        """
+        async with get_transaction(session):
+            q = sql_delete(cls.model).where(and_(*filters))
+            await session.execute(q)
+        return True
+
+    @classmethod
+    async def count(
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any] | None = None,
+    ) -> int:
+        """Count records matching the filters.
+
+        Args:
+            session: DB async session
+            filters: List of SQLAlchemy filter conditions
+
+        Returns:
+            Number of matching records
+        """
+        q = select(func.count()).select_from(cls.model)
+        if filters:
+            q = q.where(and_(*filters))
+        result = await session.execute(q)
+        return result.scalar_one()
+
+    @classmethod
+    async def exists(
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any],
+    ) -> bool:
+        """Check if a record exists.
+
+        Args:
+            session: DB async session
+            filters: List of SQLAlchemy filter conditions
+
+        Returns:
+            True if at least one record matches
+        """
+        q = select(cls.model).where(and_(*filters)).exists().select()
+        result = await session.execute(q)
+        return bool(result.scalar())
+
+    @classmethod
+    async def paginate(
+        cls: type[Self],
+        session: AsyncSession,
+        *,
+        filters: list[Any] | None = None,
+        load_options: list[Any] | None = None,
+        order_by: Any | None = None,
+        page: int = 1,
+        items_per_page: int = 20,
+    ) -> dict[str, Any]:
+        """Get paginated results with metadata.
+
+        Args:
+            session: DB async session
+            filters: List of SQLAlchemy filter conditions
+            load_options: SQLAlchemy loader options
+            order_by: Column or list of columns to order by
+            page: Page number (1-indexed)
+            items_per_page: Number of items per page
+
+        Returns:
+            Dict with 'data' and 'pagination' keys
+        """
+        filters = filters or []
+        offset = (page - 1) * items_per_page
+
+        items = await cls.get_multi(
+            session,
+            filters=filters,
+            load_options=load_options,
+            order_by=order_by,
+            limit=items_per_page,
+            offset=offset,
+        )
+
+        total_count = await cls.count(session, filters=filters)
+
+        return {
+            "data": items,
+            "pagination": {
+                "total_count": total_count,
+                "items_per_page": items_per_page,
+                "page": page,
+                "has_more": page * items_per_page < total_count,
+            },
+        }
+
+
+def CrudFactory(
+    model: type[ModelType],
+) -> type[AsyncCrud[ModelType]]:
+    """Create a CRUD class for a specific model.
+
+    Args:
+        model: SQLAlchemy model class
+
+    Returns:
+        AsyncCrud subclass bound to the model
+
+    Example:
+        from fastapi_toolsets.crud import CrudFactory
+        from myapp.models import User, Post
+
+        UserCrud = CrudFactory(User)
+        PostCrud = CrudFactory(Post)
+
+        # Usage
+        user = await UserCrud.get(session, [User.id == 1])
+        posts = await PostCrud.get_multi(session, filters=[Post.user_id == user.id])
+    """
+    cls = type(f"Async{model.__name__}Crud", (AsyncCrud,), {"model": model})
+    return cast(type[AsyncCrud[ModelType]], cls)

fastapi_toolsets/db.py

@@ -0,0 +1,175 @@
+"""Database utilities: sessions, transactions, and locks."""
+
+from collections.abc import AsyncGenerator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from enum import Enum
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+__all__ = [
+    "LockMode",
+    "create_db_context",
+    "create_db_dependency",
+    "lock_tables",
+    "get_transaction",
+]
+
+
+def create_db_dependency(
+    session_maker: async_sessionmaker[AsyncSession],
+) -> Callable[[], AsyncGenerator[AsyncSession, None]]:
+    """Create a FastAPI dependency for database sessions.
+
+    Creates a dependency function that yields a session and auto-commits
+    if a transaction is active when the request completes.
+
+    Args:
+        session_maker: Async session factory from create_session_factory()
+
+    Returns:
+        An async generator function usable with FastAPI's Depends()
+
+    Example:
+        from fastapi import Depends
+        from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+        from fastapi_toolsets.db import create_db_dependency
+
+        engine = create_async_engine("postgresql+asyncpg://...")
+        SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+        get_db = create_db_dependency(SessionLocal)
+
+        @app.get("/users")
+        async def list_users(session: AsyncSession = Depends(get_db)):
+            ...
+    """
+
+    async def get_db() -> AsyncGenerator[AsyncSession, None]:
+        async with session_maker() as session:
+            yield session
+            if session.in_transaction():
+                await session.commit()
+
+    return get_db
+
+
+def create_db_context(
+    session_maker: async_sessionmaker[AsyncSession],
+) -> Callable[[], AbstractAsyncContextManager[AsyncSession]]:
+    """Create a context manager for database sessions.
+
+    Creates a context manager for use outside of FastAPI request handlers,
+    such as in background tasks, CLI commands, or tests.
+
+    Args:
+        session_maker: Async session factory from create_session_factory()
+
+    Returns:
+        An async context manager function
+
+    Example:
+        from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+        from fastapi_toolsets.db import create_db_context
+
+        engine = create_async_engine("postgresql+asyncpg://...")
+        SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+        get_db_context = create_db_context(SessionLocal)
+
+        async def background_task():
+            async with get_db_context() as session:
+                user = await UserCrud.get(session, [User.id == 1])
+                ...
+    """
+    get_db = create_db_dependency(session_maker)
+    return asynccontextmanager(get_db)
+
+
+@asynccontextmanager
+async def get_transaction(
+    session: AsyncSession,
+) -> AsyncGenerator[AsyncSession, None]:
+    """Get a transaction context, handling nested transactions.
+
+    If already in a transaction, creates a savepoint (nested transaction).
+    Otherwise, starts a new transaction.
+
+    Args:
+        session: AsyncSession instance
+
+    Yields:
+        The session within the transaction context
+
+    Example:
+        async with get_transaction(session):
+            session.add(model)
+            # Auto-commits on exit, rolls back on exception
+    """
+    if session.in_transaction():
+        async with session.begin_nested():
+            yield session
+    else:
+        async with session.begin():
+            yield session
+
+
+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"
+
+
+@asynccontextmanager
+async def lock_tables(
+    session: AsyncSession,
+    tables: list[type[DeclarativeBase]],
+    *,
+    mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
+    timeout: str = "5s",
+) -> AsyncGenerator[AsyncSession, None]:
+    """Lock PostgreSQL tables for the duration of a transaction.
+
+    Acquires table-level locks that are held until the transaction ends.
+    Useful for preventing concurrent modifications during critical operations.
+
+    Args:
+        session: AsyncSession instance
+        tables: List of SQLAlchemy model classes to lock
+        mode: Lock mode (default: SHARE UPDATE EXCLUSIVE)
+        timeout: Lock timeout (default: "5s")
+
+    Yields:
+        The session with locked tables
+
+    Raises:
+        SQLAlchemyError: If lock cannot be acquired within timeout
+
+    Example:
+        from fastapi_toolsets.db import lock_tables, LockMode
+
+        async with lock_tables(session, [User, Account]):
+            # Tables are locked with SHARE UPDATE EXCLUSIVE mode
+            user = await UserCrud.get(session, [User.id == 1])
+            user.balance += 100
+
+        # With custom lock mode
+        async with lock_tables(session, [Order], mode=LockMode.EXCLUSIVE):
+            # Exclusive lock - no other transactions can access
+            await process_order(session, order_id)
+    """
+    table_names = ",".join(table.__tablename__ for table in tables)
+
+    async with get_transaction(session):
+        await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
+        await session.execute(text(f"LOCK {table_names} IN {mode.value} MODE"))
+        yield session

fastapi_toolsets/exceptions/__init__.py

@@ -0,0 +1,19 @@
+from .exceptions import (
+    ApiException,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    UnauthorizedError,
+    generate_error_responses,
+)
+from .handler import init_exceptions_handlers
+
+__all__ = [
+    "init_exceptions_handlers",
+    "generate_error_responses",
+    "ApiException",
+    "ConflictError",
+    "ForbiddenError",
+    "NotFoundError",
+    "UnauthorizedError",
+]