voltwire-fastapi-exceptions 0.0.1__py3-none-any.whl

voltwire/fastapi/exceptions/__init__.py

@@ -0,0 +1,33 @@
+from voltwire.fastapi.exceptions.exceptions import *  # noqa: F401, F403
+from voltwire.fastapi.exceptions.middleware import (
+    ApiErrorBody,
+    DefaultExceptionHandlerSettings,
+    ExceptionHandlerSettings,
+    ExceptionMiddleware,
+    build_error_responses,
+    build_validation_handler,
+)
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "AppError",
+    "AppWarning",
+    "UnauthorizedRequestError",
+    "ForbiddenError",
+    "BadRequestError",
+    "EntityNotFoundError",
+    "EntityNotFoundWarning",
+    "ResourceConflictError",
+    "ResourceConflictWarning",
+    "UnprocessableRequestError",
+    "UnprocessableRequestWarning",
+    "UnsupportedFeatureError",
+    "DownstreamServiceError",
+    "ExceptionMiddleware",
+    "build_validation_handler",
+    "build_error_responses",
+    "ApiErrorBody",
+    "ExceptionHandlerSettings",
+    "DefaultExceptionHandlerSettings",
+]

voltwire/fastapi/exceptions/exceptions.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass
+
+from starlette import status
+
+
+@dataclass
+class AppError(Exception):
+    message: str
+    status_code: int
+
+    def __post_init__(self):
+        super().__init__()
+
+    def __str__(self):
+        return self.message
+
+
+@dataclass
+class AppWarning(AppError):  # noqa: N818 — intentionally not named *Error; these are expected conditions
+    """Raised for expected/recoverable conditions that don't warrant error-level logging."""
+
+    pass
+
+
+class UnauthorizedRequestError(AppError):
+    def __init__(self, message="Unauthorized Request"):
+        status_code = status.HTTP_401_UNAUTHORIZED
+        super().__init__(message, status_code)
+
+
+class ForbiddenError(AppWarning):
+    def __init__(self, message="Forbidden Request"):
+        status_code = status.HTTP_403_FORBIDDEN
+        super().__init__(message, status_code)
+
+
+class BadRequestError(AppError):
+    def __init__(self, message="Bad Request"):
+        status_code = status.HTTP_400_BAD_REQUEST
+        super().__init__(message, status_code)
+
+
+class EntityNotFoundError(AppError):
+    def __init__(self, message="Entity not found"):
+        status_code = status.HTTP_404_NOT_FOUND
+        super().__init__(message, status_code)
+
+class EntityNotFoundWarning(AppWarning):
+    def __init__(self, message="Entity not found"):
+        super().__init__(message, status.HTTP_404_NOT_FOUND)
+
+class ResourceConflictError(AppError):
+    def __init__(self, message="Request creates a conflict"):
+        status_code = status.HTTP_409_CONFLICT
+        super().__init__(message, status_code)
+
+class ResourceConflictWarning(AppWarning):
+    def __init__(self, message="Request creates a conflict"):
+        status_code = status.HTTP_409_CONFLICT
+        super().__init__(message, status_code)
+
+class UnprocessableRequestError(AppError):
+    def __init__(self, message="Unprocessable Request"):
+        status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
+        super().__init__(message, status_code)
+
+class UnprocessableRequestWarning(AppWarning):
+    def __init__(self, message="Unprocessable Request"):
+        status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
+        super().__init__(message, status_code)
+
+
+class UnsupportedFeatureError(AppWarning):
+    def __init__(self, message="Not implemented"):
+        status_code = status.HTTP_501_NOT_IMPLEMENTED
+        super().__init__(message, status_code)
+
+
+class DownstreamServiceError(AppError):
+    def __init__(self, message="Downstream service error"):
+        status_code = status.HTTP_502_BAD_GATEWAY
+        super().__init__(message, status_code)
+

voltwire/fastapi/exceptions/middleware.py

@@ -0,0 +1,117 @@
+import logging
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from fastapi.exceptions import RequestValidationError
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from voltwire.fastapi.exceptions.exceptions import AppError, AppWarning
+
+logger = logging.getLogger(__name__)
+
+
+class ApiErrorBody(Protocol):
+    def __init__(self, *, message: str, errors: list[str]) -> None: ...
+
+    def model_dump(self, *, mode: str = "json", exclude_none: bool = True) -> dict[str, Any]: ...
+
+
+class ExceptionHandlerSettings(Protocol):
+    production: bool
+
+
+@dataclass
+class DefaultExceptionHandlerSettings:
+    production: bool = False
+
+
+def _handle_unexpected_error(
+    request: Request, e: Exception, settings: ExceptionHandlerSettings, error_model: type[ApiErrorBody]
+) -> JSONResponse:
+    logger.exception("Internal server error occurred", extra={"path": request.url.path})
+    errors = [] if settings.production else [str(e)]
+    body = error_model(message="internal server error", errors=errors)
+    return JSONResponse(
+        content=body.model_dump(mode="json", exclude_none=True),
+        media_type="application/json",
+        status_code=500,
+    )
+
+
+def _handle_service_error(request: Request, e: AppError, error_model: type[ApiErrorBody]) -> JSONResponse:
+    if isinstance(e, AppWarning):
+        logger.warning(
+            "Expected service condition",
+            extra={"path": request.url.path, "error_type": type(e).__name__},
+        )
+    else:
+        logger.exception(
+            "Service error occurred",
+            extra={"path": request.url.path, "error_type": type(e).__name__},
+        )
+    body = error_model(message="service error", errors=[e.message])
+    response_content = body.model_dump(mode="json", exclude_none=True)
+    if not isinstance(e, AppWarning):
+        logger.error(f"AppError response - status: {e.status_code}, content: {response_content}")
+    return JSONResponse(
+        content=response_content,
+        media_type="application/json",
+        status_code=e.status_code,
+    )
+
+
+def build_validation_handler(error_model: type[ApiErrorBody]):
+    async def handle_validation_error(request: Request, exc: RequestValidationError) -> JSONResponse:
+        logger.warning(f"Validation error details: {exc.errors()}")
+        errors = []
+        for error in exc.errors():
+            location = ".".join(str(loc) for loc in error["loc"] if loc != "body")
+            message = error["msg"]
+            error_type = error.get("type", "unknown")
+            detailed_error = (
+                f"Field: {location if location else 'N/A'}, Error: {message}, Type: {error_type}, Received: "
+                f"{error.get('input', 'not provided')}"
+            )
+            errors.append(detailed_error)
+            logger.warning(detailed_error)
+        body = error_model(message="Request Validation Error", errors=errors)
+        return JSONResponse(
+            status_code=422,
+            content=body.model_dump(mode="json", exclude_none=True),
+        )
+
+    return handle_validation_error
+
+
+def build_error_responses(error_model: type[ApiErrorBody]) -> dict:
+    return {
+        401: {
+            "model": error_model,
+            "description": "Authentication data in the request is invalid",
+        },
+        403: {"model": error_model, "description": "Not authorized"},
+        404: {"model": error_model, "description": "Not found"},
+        409: {"model": error_model, "description": "Resource conflict detected"},
+        422: {
+            "model": error_model,
+            "description": "Understood the request, but can't and won't process it",
+        },
+        400: {"model": error_model, "description": "Bad request"},
+    }
+
+
+class ExceptionMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, error_model: type[ApiErrorBody], settings: ExceptionHandlerSettings | None = None):
+        super().__init__(app)
+        self._error_model = error_model
+        self._settings = settings or DefaultExceptionHandlerSettings()
+
+    async def dispatch(self, request: Request, call_next):
+        try:
+            return await call_next(request)
+        except AppError as e:
+            return _handle_service_error(request, e, self._error_model)
+        except Exception as e:
+            return _handle_unexpected_error(request, e, self._settings, self._error_model)

voltwire_fastapi_exceptions-0.0.1.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: voltwire-fastapi-exceptions
+Version: 0.0.1
+Summary: Reusable FastAPI base exceptions, ApiMessage, and a unified exception handler
+Author-email: Hermann Steidel <hsteidel.software@gmail.com>
+License-Expression: MIT
+Requires-Python: <4.0,>=3.13
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: starlette>=0.27.0
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/fastapi-exceptions.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-fastapi-exceptions
+
+Reusable exception handling for FastAPI apps: a base `AppError` hierarchy you can raise
+(and extend), plus a middleware + validation handler so that **every** error — raised before,
+during, or after the route — reaches the client as the same JSON body.
+
+**Bring your own response model.** The library never defines or imposes a response schema —
+you pass your own model down, and the handlers use only the slice they need (construct it with
+`message` + `errors`, then call `.model_dump()`). Your app keeps one model for both success and
+error responses; nothing is coupled across the boundary.
+
+## Installation
+
+```bash
+pip install voltwire-fastapi-exceptions
+# or with Poetry:
+poetry add voltwire-fastapi-exceptions
+```
+
+## Raising errors
+
+Raise an `AppError` (or a subclass) anywhere; the middleware turns it into your response
+model with the right status code.
+
+```python
+from voltwire.fastapi.exceptions import EntityNotFoundError, ForbiddenError
+
+def get_user(user_id: str):
+    user = repo.find(user_id)
+    if not user:
+        raise EntityNotFoundError(f"No user {user_id}")   # -> 404
+    if not user.active:
+        raise ForbiddenError()                            # -> 403
+    return user
+```
+
+Built-in classes: `UnauthorizedRequestError` (401), `ForbiddenError` (403),
+`BadRequestError` (400), `EntityNotFoundError` (404), `ResourceConflictError` (409),
+`UnprocessableRequestError` (422), `UnsupportedFeatureError` (501),
+`DownstreamServiceError` (502).
+
+`AppWarning` is an `AppError` subclass for **expected/recoverable** conditions — logged
+at `warning` level instead of `error`. `ForbiddenError` and `UnsupportedFeatureError` are
+warnings.
+
+### Extend them
+
+```python
+from voltwire.fastapi.exceptions import UnprocessableRequestError
+
+class DivideByZeroError(UnprocessableRequestError):
+    def __init__(self, message="Cannot divide by zero"):
+        super().__init__(message)
+```
+
+## Your response model
+
+Provide any model whose instances have a `.model_dump()` and that can be constructed with
+`message=` and `errors=` (a pydantic model with those two fields — plus whatever else you want,
+e.g. `timestamp`, `metadata` — is the common case). The library only ever sets `message` and
+`errors`; the rest come from your model's defaults. This is the `ApiErrorBody` protocol:
+
+```python
+class ApiErrorBody(Protocol):
+    def __init__(self, *, message: str, errors: list[str]) -> None: ...
+    def model_dump(self, *, mode: str = "json", exclude_none: bool = True) -> dict: ...
+```
+
+## Wiring it into your app
+
+```python
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from voltwire.fastapi.exceptions import (
+    ExceptionMiddleware,
+    DefaultExceptionHandlerSettings,
+    build_validation_handler,
+    build_error_responses,
+)
+from myapp.models import ApiMessage   # <-- YOUR model
+
+app = FastAPI(responses=build_error_responses(ApiMessage))   # OpenAPI error schemas
+
+# Catches AppError (-> its status) and any unexpected Exception (-> 500).
+app.add_middleware(
+    ExceptionMiddleware,
+    error_model=ApiMessage,
+    settings=DefaultExceptionHandlerSettings(production=is_production()),
+)
+
+# RequestValidationError is raised during request parsing, before the middleware runs,
+# so register it as an exception handler too — same body, built from your model.
+app.add_exception_handler(RequestValidationError, build_validation_handler(ApiMessage))
+```
+
+## Settings (why not read your env directly?)
+
+The middleware only needs to know one thing: **are we in production?** (In production the 500
+handler hides the raw exception string; otherwise it includes it to aid debugging.)
+
+Rather than force a settings system on you, it takes any object matching the
+`ExceptionHandlerSettings` protocol — a single `production: bool`. Use the provided
+`DefaultExceptionHandlerSettings`, or pass your own object exposing `production`.
+
+## Logging
+
+Handlers log via `logging.getLogger(__name__)` (Python's standard `logging` module) —
+`AppWarning` at `warning`, real errors at `error`/`exception`. To activate debug output:
+
+```python
+import logging
+logging.getLogger("voltwire.fastapi.exceptions").setLevel(logging.DEBUG)
+```
+
+If your app uses [loguru](https://github.com/Delgan/loguru), intercept stdlib logging once at startup:
+
+```python
+import logging
+from loguru import logger
+
+class InterceptHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        logger.opt(depth=6, exception=record.exc_info).log(
+            record.levelname, record.getMessage()
+        )
+
+logging.getLogger("voltwire.fastapi.exceptions").addHandler(InterceptHandler())
+```

voltwire_fastapi_exceptions-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+voltwire/fastapi/exceptions/__init__.py,sha256=sF8lF3J9XVyySHAX69nUcSC0iidJTL_6TWxVSAk2P6Y,868
+voltwire/fastapi/exceptions/exceptions.py,sha256=zgS4DAtqlKWXhID39neH3LAl4YCxY7PbE2zf7qlHFYc,2588
+voltwire/fastapi/exceptions/middleware.py,sha256=W8Kq9foVAc5_qaNEQQznENhL2TNOv69K8FPfMrT6cIY,4445
+voltwire/fastapi/exceptions/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+voltwire_fastapi_exceptions-0.0.1.dist-info/METADATA,sha256=vDhmjBpiugub0xFfmTtDJDWb_nKfvbBtdgBiMn8sbX0,5200
+voltwire_fastapi_exceptions-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+voltwire_fastapi_exceptions-0.0.1.dist-info/RECORD,,

voltwire_fastapi_exceptions-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any