fastapi-toolsets 0.1.0__py3-none-any.whl

fastapi_toolsets/exceptions/exceptions.py

@@ -0,0 +1,166 @@
+"""Custom exceptions with standardized API error responses."""
+
+from typing import Any, ClassVar
+
+from ..schemas import ApiError, ErrorResponse, ResponseStatus
+
+
+class ApiException(Exception):
+    """Base exception for API errors with structured response.
+
+    Subclass this to create custom API exceptions with consistent error format.
+    The exception handler will use api_error to generate the response.
+
+    Example:
+        class CustomError(ApiException):
+            api_error = ApiError(
+                code=400,
+                msg="Bad Request",
+                desc="The request was invalid.",
+                err_code="CUSTOM-400",
+            )
+    """
+
+    api_error: ClassVar[ApiError]
+
+    def __init__(self, detail: str | None = None):
+        """Initialize the exception.
+
+        Args:
+            detail: Optional override for the error message
+        """
+        super().__init__(detail or self.api_error.msg)
+
+
+class UnauthorizedError(ApiException):
+    """HTTP 401 - User is not authenticated."""
+
+    api_error = ApiError(
+        code=401,
+        msg="Unauthorized",
+        desc="Authentication credentials were missing or invalid.",
+        err_code="AUTH-401",
+    )
+
+
+class ForbiddenError(ApiException):
+    """HTTP 403 - User lacks required permissions."""
+
+    api_error = ApiError(
+        code=403,
+        msg="Forbidden",
+        desc="You do not have permission to access this resource.",
+        err_code="AUTH-403",
+    )
+
+
+class NotFoundError(ApiException):
+    """HTTP 404 - Resource not found."""
+
+    api_error = ApiError(
+        code=404,
+        msg="Not Found",
+        desc="The requested resource was not found.",
+        err_code="RES-404",
+    )
+
+
+class ConflictError(ApiException):
+    """HTTP 409 - Resource conflict."""
+
+    api_error = ApiError(
+        code=409,
+        msg="Conflict",
+        desc="The request conflicts with the current state of the resource.",
+        err_code="RES-409",
+    )
+
+
+class InsufficientRolesError(ForbiddenError):
+    """User does not have the required roles."""
+
+    api_error = ApiError(
+        code=403,
+        msg="Insufficient Roles",
+        desc="You do not have the required roles to access this resource.",
+        err_code="RBAC-403",
+    )
+
+    def __init__(self, required_roles: list[str], user_roles: set[str] | None = None):
+        self.required_roles = required_roles
+        self.user_roles = user_roles
+
+        desc = f"Required roles: {', '.join(required_roles)}"
+        if user_roles is not None:
+            desc += f". User has: {', '.join(user_roles) if user_roles else 'no roles'}"
+
+        super().__init__(desc)
+
+
+class UserNotFoundError(NotFoundError):
+    """User was not found."""
+
+    api_error = ApiError(
+        code=404,
+        msg="User Not Found",
+        desc="The requested user was not found.",
+        err_code="USER-404",
+    )
+
+
+class RoleNotFoundError(NotFoundError):
+    """Role was not found."""
+
+    api_error = ApiError(
+        code=404,
+        msg="Role Not Found",
+        desc="The requested role was not found.",
+        err_code="ROLE-404",
+    )
+
+
+def generate_error_responses(
+    *errors: type[ApiException],
+) -> dict[int | str, dict[str, Any]]:
+    """Generate OpenAPI response documentation for exceptions.
+
+    Use this to document possible error responses for an endpoint.
+
+    Args:
+        *errors: Exception classes that inherit from ApiException
+
+    Returns:
+        Dict suitable for FastAPI's responses parameter
+
+    Example:
+        from fastapi_toolsets.exceptions import generate_error_responses, UnauthorizedError, ForbiddenError
+
+        @app.get(
+            "/admin",
+            responses=generate_error_responses(UnauthorizedError, ForbiddenError)
+        )
+        async def admin_endpoint():
+            ...
+    """
+    responses: dict[int | str, dict[str, Any]] = {}
+
+    for error in errors:
+        api_error = error.api_error
+
+        responses[api_error.code] = {
+            "model": ErrorResponse,
+            "description": api_error.msg,
+            "content": {
+                "application/json": {
+                    "example": {
+                        "data": None,
+                        "status": ResponseStatus.FAIL.value,
+                        "message": api_error.msg,
+                        "description": api_error.desc,
+                        "error_code": api_error.err_code,
+                    }
+                }
+            },
+        }
+
+    return responses

fastapi_toolsets/exceptions/handler.py

@@ -0,0 +1,169 @@
+"""Exception handlers for FastAPI applications."""
+
+from typing import Any
+
+from fastapi import FastAPI, Request, Response, status
+from fastapi.exceptions import RequestValidationError, ResponseValidationError
+from fastapi.openapi.utils import get_openapi
+from fastapi.responses import JSONResponse
+
+from ..schemas import ResponseStatus
+from .exceptions import ApiException
+
+
+def init_exceptions_handlers(app: FastAPI) -> FastAPI:
+    _register_exception_handlers(app)
+    app.openapi = lambda: _custom_openapi(app)  # type: ignore[method-assign]
+    return app
+
+
+def _register_exception_handlers(app: FastAPI) -> None:
+    """Register all exception handlers on a FastAPI application.
+
+    Args:
+        app: FastAPI application instance
+
+    Example:
+        from fastapi import FastAPI
+        from fastapi_toolsets.exceptions import init_exceptions_handlers
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+    """
+
+    @app.exception_handler(ApiException)
+    async def api_exception_handler(request: Request, exc: ApiException) -> Response:
+        """Handle custom API exceptions with structured response."""
+        api_error = exc.api_error
+
+        return JSONResponse(
+            status_code=api_error.code,
+            content={
+                "data": None,
+                "status": ResponseStatus.FAIL.value,
+                "message": api_error.msg,
+                "description": api_error.desc,
+                "error_code": api_error.err_code,
+            },
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def request_validation_handler(
+        request: Request, exc: RequestValidationError
+    ) -> Response:
+        """Handle Pydantic request validation errors (422)."""
+        return _format_validation_error(exc)
+
+    @app.exception_handler(ResponseValidationError)
+    async def response_validation_handler(
+        request: Request, exc: ResponseValidationError
+    ) -> Response:
+        """Handle Pydantic response validation errors (422)."""
+        return _format_validation_error(exc)
+
+    @app.exception_handler(Exception)
+    async def generic_exception_handler(request: Request, exc: Exception) -> Response:
+        """Handle all unhandled exceptions with a generic 500 response."""
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "data": None,
+                "status": ResponseStatus.FAIL.value,
+                "message": "Internal Server Error",
+                "description": "An unexpected error occurred. Please try again later.",
+                "error_code": "SERVER-500",
+            },
+        )
+
+
+def _format_validation_error(
+    exc: RequestValidationError | ResponseValidationError,
+) -> JSONResponse:
+    """Format validation errors into a structured response."""
+    errors = exc.errors()
+    formatted_errors = []
+
+    for error in errors:
+        field_path = ".".join(
+            str(loc)
+            for loc in error["loc"]
+            if loc not in ("body", "query", "path", "header", "cookie")
+        )
+        formatted_errors.append(
+            {
+                "field": field_path or "root",
+                "message": error.get("msg", ""),
+                "type": error.get("type", ""),
+            }
+        )
+
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content={
+            "data": {"errors": formatted_errors},
+            "status": ResponseStatus.FAIL.value,
+            "message": "Validation Error",
+            "description": f"{len(formatted_errors)} validation error(s) detected",
+            "error_code": "VAL-422",
+        },
+    )
+
+
+def _custom_openapi(app: FastAPI) -> dict[str, Any]:
+    """Generate custom OpenAPI schema with standardized error format.
+
+    Replaces default 422 validation error responses with the custom format.
+
+    Args:
+        app: FastAPI application instance
+
+    Returns:
+        OpenAPI schema dict
+
+    Example:
+        from fastapi import FastAPI
+        from fastapi_toolsets.exceptions import init_exceptions_handlers
+
+        app = FastAPI()
+        init_exceptions_handlers(app)  # Automatically sets custom OpenAPI
+    """
+    if app.openapi_schema:
+        return app.openapi_schema
+
+    openapi_schema = get_openapi(
+        title=app.title,
+        version=app.version,
+        openapi_version=app.openapi_version,
+        description=app.description,
+        routes=app.routes,
+    )
+
+    for path_data in openapi_schema.get("paths", {}).values():
+        for operation in path_data.values():
+            if isinstance(operation, dict) and "responses" in operation:
+                if "422" in operation["responses"]:
+                    operation["responses"]["422"] = {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "example": {
+                                    "data": {
+                                        "errors": [
+                                            {
+                                                "field": "field_name",
+                                                "message": "value is not valid",
+                                                "type": "value_error",
+                                            }
+                                        ]
+                                    },
+                                    "status": ResponseStatus.FAIL.value,
+                                    "message": "Validation Error",
+                                    "description": "1 validation error(s) detected",
+                                    "error_code": "VAL-422",
+                                }
+                            }
+                        },
+                    }
+
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema

fastapi_toolsets/fixtures/__init__.py

@@ -0,0 +1,17 @@
+from .fixtures import (
+    Context,
+    FixtureRegistry,
+    LoadStrategy,
+    load_fixtures,
+    load_fixtures_by_context,
+)
+from .pytest_plugin import register_fixtures
+
+__all__ = [
+    "Context",
+    "FixtureRegistry",
+    "LoadStrategy",
+    "load_fixtures",
+    "load_fixtures_by_context",
+    "register_fixtures",
+]

fastapi_toolsets/fixtures/fixtures.py

@@ -0,0 +1,321 @@
+"""Fixture system with dependency management and context support."""
+
+import logging
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, cast
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+
+from ..db import get_transaction
+
+logger = logging.getLogger(__name__)
+
+
+class LoadStrategy(str, Enum):
+    """Strategy for loading fixtures into the database."""
+
+    INSERT = "insert"
+    """Insert new records. Fails if record already exists."""
+
+    MERGE = "merge"
+    """Insert or update based on primary key (SQLAlchemy merge)."""
+
+    SKIP_EXISTING = "skip_existing"
+    """Insert only if record doesn't exist (based on primary key)."""
+
+
+class Context(str, Enum):
+    """Predefined fixture contexts."""
+
+    BASE = "base"
+    """Base fixtures loaded in all environments."""
+
+    PRODUCTION = "production"
+    """Production-only fixtures."""
+
+    DEVELOPMENT = "development"
+    """Development fixtures."""
+
+    TESTING = "testing"
+    """Test fixtures."""
+
+
+@dataclass
+class Fixture:
+    """A fixture definition with metadata."""
+
+    name: str
+    func: Callable[[], Sequence[DeclarativeBase]]
+    depends_on: list[str] = field(default_factory=list)
+    contexts: list[str] = field(default_factory=lambda: [Context.BASE])
+
+
+class FixtureRegistry:
+    """Registry for managing fixtures with dependencies.
+
+    Example:
+        from fastapi_toolsets.fixtures import FixtureRegistry, Context
+
+        fixtures = FixtureRegistry()
+
+        @fixtures.register
+        def roles():
+            return [
+                Role(id=1, name="admin"),
+                Role(id=2, name="user"),
+            ]
+
+        @fixtures.register(depends_on=["roles"])
+        def users():
+            return [
+                User(id=1, username="admin", role_id=1),
+            ]
+
+        @fixtures.register(depends_on=["users"], contexts=[Context.TESTING])
+        def test_data():
+            return [
+                Post(id=1, title="Test", user_id=1),
+            ]
+    """
+
+    def __init__(self) -> None:
+        self._fixtures: dict[str, Fixture] = {}
+
+    def register(
+        self,
+        func: Callable[[], Sequence[DeclarativeBase]] | None = None,
+        *,
+        name: str | None = None,
+        depends_on: list[str] | None = None,
+        contexts: list[str | Context] | None = None,
+    ) -> Callable[..., Any]:
+        """Register a fixture function.
+
+        Can be used as a decorator with or without arguments.
+
+        Args:
+            func: Fixture function returning list of model instances
+            name: Fixture name (defaults to function name)
+            depends_on: List of fixture names this depends on
+            contexts: List of contexts this fixture belongs to
+
+        Example:
+            @fixtures.register
+            def roles():
+                return [Role(id=1, name="admin")]
+
+            @fixtures.register(depends_on=["roles"], contexts=[Context.TESTING])
+            def test_users():
+                return [User(id=1, username="test", role_id=1)]
+        """
+
+        def decorator(
+            fn: Callable[[], Sequence[DeclarativeBase]],
+        ) -> Callable[[], Sequence[DeclarativeBase]]:
+            fixture_name = name or cast(Any, fn).__name__
+            fixture_contexts = [
+                c.value if isinstance(c, Context) else c
+                for c in (contexts or [Context.BASE])
+            ]
+
+            self._fixtures[fixture_name] = Fixture(
+                name=fixture_name,
+                func=fn,
+                depends_on=depends_on or [],
+                contexts=fixture_contexts,
+            )
+            return fn
+
+        if func is not None:
+            return decorator(func)
+        return decorator
+
+    def get(self, name: str) -> Fixture:
+        """Get a fixture by name."""
+        if name not in self._fixtures:
+            raise KeyError(f"Fixture '{name}' not found")
+        return self._fixtures[name]
+
+    def get_all(self) -> list[Fixture]:
+        """Get all registered fixtures."""
+        return list(self._fixtures.values())
+
+    def get_by_context(self, *contexts: str | Context) -> list[Fixture]:
+        """Get fixtures for specific contexts."""
+        context_values = {c.value if isinstance(c, Context) else c for c in contexts}
+        return [f for f in self._fixtures.values() if set(f.contexts) & context_values]
+
+    def resolve_dependencies(self, *names: str) -> list[str]:
+        """Resolve fixture dependencies in topological order.
+
+        Args:
+            *names: Fixture names to resolve
+
+        Returns:
+            List of fixture names in load order (dependencies first)
+
+        Raises:
+            KeyError: If a fixture is not found
+            ValueError: If circular dependency detected
+        """
+        resolved: list[str] = []
+        seen: set[str] = set()
+        visiting: set[str] = set()
+
+        def visit(name: str) -> None:
+            if name in resolved:
+                return
+            if name in visiting:
+                raise ValueError(f"Circular dependency detected: {name}")
+
+            visiting.add(name)
+            fixture = self.get(name)
+
+            for dep in fixture.depends_on:
+                visit(dep)
+
+            visiting.remove(name)
+            resolved.append(name)
+            seen.add(name)
+
+        for name in names:
+            visit(name)
+
+        return resolved
+
+    def resolve_context_dependencies(self, *contexts: str | Context) -> list[str]:
+        """Resolve all fixtures for contexts with dependencies.
+
+        Args:
+            *contexts: Contexts to load
+
+        Returns:
+            List of fixture names in load order
+        """
+        context_fixtures = self.get_by_context(*contexts)
+        names = [f.name for f in context_fixtures]
+
+        all_deps: set[str] = set()
+        for name in names:
+            deps = self.resolve_dependencies(name)
+            all_deps.update(deps)
+
+        return self.resolve_dependencies(*all_deps)
+
+
+async def load_fixtures(
+    session: AsyncSession,
+    registry: FixtureRegistry,
+    *names: str,
+    strategy: LoadStrategy = LoadStrategy.MERGE,
+) -> dict[str, list[DeclarativeBase]]:
+    """Load specific fixtures by name with dependencies.
+
+    Args:
+        session: Database session
+        registry: Fixture registry
+        *names: Fixture names to load (dependencies auto-resolved)
+        strategy: How to handle existing records
+
+    Returns:
+        Dict mapping fixture names to loaded instances
+
+    Example:
+        # Loads 'roles' first (dependency), then 'users'
+        result = await load_fixtures(session, fixtures, "users")
+        print(result["users"])  # [User(...), ...]
+    """
+    ordered = registry.resolve_dependencies(*names)
+    return await _load_ordered(session, registry, ordered, strategy)
+
+
+async def load_fixtures_by_context(
+    session: AsyncSession,
+    registry: FixtureRegistry,
+    *contexts: str | Context,
+    strategy: LoadStrategy = LoadStrategy.MERGE,
+) -> dict[str, list[DeclarativeBase]]:
+    """Load all fixtures for specific contexts.
+
+    Args:
+        session: Database session
+        registry: Fixture registry
+        *contexts: Contexts to load (e.g., Context.BASE, Context.TESTING)
+        strategy: How to handle existing records
+
+    Returns:
+        Dict mapping fixture names to loaded instances
+
+    Example:
+        # Load base + testing fixtures
+        await load_fixtures_by_context(
+            session, fixtures,
+            Context.BASE, Context.TESTING
+        )
+    """
+    ordered = registry.resolve_context_dependencies(*contexts)
+    return await _load_ordered(session, registry, ordered, strategy)
+
+
+async def _load_ordered(
+    session: AsyncSession,
+    registry: FixtureRegistry,
+    ordered_names: list[str],
+    strategy: LoadStrategy,
+) -> dict[str, list[DeclarativeBase]]:
+    """Load fixtures in order."""
+    results: dict[str, list[DeclarativeBase]] = {}
+
+    for name in ordered_names:
+        fixture = registry.get(name)
+        instances = list(fixture.func())
+
+        if not instances:
+            results[name] = []
+            continue
+
+        model_name = type(instances[0]).__name__
+        loaded: list[DeclarativeBase] = []
+
+        async with get_transaction(session):
+            for instance in instances:
+                if strategy == LoadStrategy.INSERT:
+                    session.add(instance)
+                    loaded.append(instance)
+
+                elif strategy == LoadStrategy.MERGE:
+                    merged = await session.merge(instance)
+                    loaded.append(merged)
+
+                elif strategy == LoadStrategy.SKIP_EXISTING:
+                    pk = _get_primary_key(instance)
+                    if pk is not None:
+                        existing = await session.get(type(instance), pk)
+                        if existing is None:
+                            session.add(instance)
+                            loaded.append(instance)
+                    else:
+                        session.add(instance)
+                        loaded.append(instance)
+
+        results[name] = loaded
+        logger.info(f"Loaded fixture '{name}': {len(loaded)} {model_name}(s)")
+
+    return results
+
+
+def _get_primary_key(instance: DeclarativeBase) -> Any | None:
+    """Get the primary key value of a model instance."""
+    mapper = instance.__class__.__mapper__
+    pk_cols = mapper.primary_key
+
+    if len(pk_cols) == 1:
+        return getattr(instance, pk_cols[0].name, None)
+
+    pk_values = tuple(getattr(instance, col.name, None) for col in pk_cols)
+    if all(v is not None for v in pk_values):
+        return pk_values
+    return None