fastapi-custom-responses 0.0.11__py3-none-any.whl

fastapi_custom_responses/__init__.py

@@ -0,0 +1,2 @@
+from .errors import EXCEPTION_HANDLERS, ErrorResponse, ErrorResponseModel
+from .responses import PaginatedResponse, PaginationMeta, Response

fastapi_custom_responses/errors.py

@@ -0,0 +1,120 @@
+import logging
+from http import HTTPStatus
+from typing import Callable
+
+from fastapi import Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from fastapi_custom_responses.responses import Response
+
+logger = logging.getLogger(__name__)
+
+ERROR_MESSAGES: dict[int, str] = {
+    HTTPStatus.UNAUTHORIZED: "Authentication required",
+    HTTPStatus.FORBIDDEN: "You don't have permission to perform this action",
+    HTTPStatus.NOT_FOUND: "Resource not found",
+    HTTPStatus.BAD_REQUEST: "Invalid request",
+    HTTPStatus.INTERNAL_SERVER_ERROR: "An unexpected error occurred",
+}
+
+
+class ErrorResponseModel(BaseModel):
+    """Pydantic model for error response schema. Use this in FastAPI's `responses` parameter to document the error response schema."""
+
+    success: bool
+    error: str
+
+
+class ErrorResponse(Exception):
+    """Standard error response that includes error message."""
+
+    def __init__(self, error: str, status_code: int = HTTPStatus.BAD_REQUEST) -> None:
+        """Initialize error response with message and status code.
+
+        Args:
+            error: Error message to return
+            status_code: HTTP status code for the response
+        """
+
+        self.error = error
+        self.status_code = status_code
+
+        super().__init__(error)
+
+    @classmethod
+    def from_status_code(cls, status_code: int) -> "ErrorResponse":
+        """Create an error response from a status code.
+
+        Args:
+            status_code: HTTP status code to get error message for
+
+        Returns:
+            ErrorResponse with the appropriate error message for the status code
+        """
+
+        return cls(
+            error=ERROR_MESSAGES.get(status_code, ERROR_MESSAGES[HTTPStatus.INTERNAL_SERVER_ERROR]),
+            status_code=status_code,
+        )
+
+
+def _validation_exception_handler(_: Request, exc: RequestValidationError) -> JSONResponse:
+    """Handle validation errors from pydantic models."""
+
+    logger.exception(exc)
+
+    response = Response(success=False, error=ERROR_MESSAGES[HTTPStatus.BAD_REQUEST])
+
+    return JSONResponse(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        content=response.model_dump(mode="json"),
+    )
+
+
+def _value_error_handler(_: Request, exc: ValueError) -> JSONResponse:
+    """Handle value errors, e.g., Pydantic validation errors."""
+
+    logger.exception(exc)
+
+    response = Response(success=False, error=str(exc))
+
+    return JSONResponse(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        content=response.model_dump(mode="json"),
+    )
+
+
+def _error_response_handler(_: Request, exc: ErrorResponse) -> JSONResponse:
+    """Convert ErrorResponse exceptions to proper JSONResponse objects."""
+
+    logger.info("ErrorResponse: %s - %s", exc.status_code, exc.error)
+
+    response = Response(success=False, error=exc.error)
+
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=response.model_dump(mode="json"),
+    )
+
+
+def _general_exception_handler(_: Request, exc: Exception) -> JSONResponse:
+    """Handle all unhandled exceptions."""
+
+    logger.exception(exc)
+
+    response = Response(success=False, error=ERROR_MESSAGES[HTTPStatus.INTERNAL_SERVER_ERROR])
+
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content=response.model_dump(mode="json"),
+    )
+
+
+EXCEPTION_HANDLERS: dict[type[Exception], Callable[[Request, Exception], JSONResponse]] = {
+    RequestValidationError: _value_error_handler,
+    ValueError: _value_error_handler,
+    ErrorResponse: _error_response_handler,
+    Exception: _general_exception_handler,
+}

fastapi_custom_responses/responses.py

@@ -0,0 +1,25 @@
+from typing import Any
+
+from pydantic_super_model import SuperModel
+
+
+class Response[T](SuperModel):
+    """Response model."""
+
+    success: bool
+    data: T | None = None
+    error: str | None = None
+
+
+class PaginationMeta(SuperModel):
+    """Pagination metadata model."""
+
+    offset: int
+    limit: int
+    total: int
+
+
+class PaginatedResponse[T: Any](Response[list[T]]):
+    """Paginated response model."""
+
+    meta: PaginationMeta

fastapi_custom_responses-0.0.11.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: fastapi-custom-responses
+Version: 0.0.11
+Summary: FastAPI Custom Responses
+License: MIT License
+         
+         Copyright (c) 2025 KRYSTAL
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+License-File: LICENSE
+Author: Julien Kmec
+Author-email: me@julien.dev
+Requires-Python: >=3.11,<3.15
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: dev
+Requires-Dist: black (>=24.3.0,<25.0.0) ; extra == "dev"
+Requires-Dist: fastapi[standard] (>=0.115.14)
+Requires-Dist: isort (>=5.12.0,<6.0.0) ; extra == "dev"
+Requires-Dist: pydantic (>=2.10.6)
+Requires-Dist: pydantic-super-model (>=1.1.2)
+Requires-Dist: pylint (>=3.0.1,<4.0.0) ; extra == "dev"
+Description-Content-Type: text/markdown
+
+# FastAPI Custom Responses
+
+Provides normalized response objects and error handling
+
+## Example
+
+```py
+from http import HTTPStatus
+from fastapi_custom_responses import EXCEPTION_HANDLERS, ErrorResponse, ErrorResponseModel, Response
+from fastapi import APIRouter, FastAPI, Request
+
+# Initialize FastAPI
+router = APIRouter()
+
+app = FastAPI(
+    title="API",
+    description="My API",
+    version="1.0.0",
+    exception_handlers=EXCEPTION_HANDLERS, # Use error handler from library
+)
+
+# Define data model
+class Data(Response):
+    example: str
+
+# Routes
+@router.get(
+    "/",
+    response_model=Response[Data],
+    responses={
+        400: {"model": ErrorResponseModel, "description": "Bad request"},
+        500: {"model": ErrorResponseModel, "description": "Internal server error"},
+    },
+)
+async def index(_: Request) -> Response[Data]:
+    """Index route."""
+
+    return Response(
+        success=True,
+        data=Data(example="hello"),
+    )
+
+@router.get(
+    "/return-error",
+    response_model=Response[Data],
+    responses={
+        HTTPStatus.FORBIDDEN: {
+            "description": "User belongs to a different organization",
+            "model": ErrorResponseModel,
+            "content": {
+                "application/json": {
+                    "example": {
+                        "success": False,
+                        "error": "User belongs to a different organization",
+                    },
+                },
+            },
+        },
+    },
+)
+async def error_route(_: Request) -> Response:
+    """Error route."""
+
+    raise ErrorResponse(error="Your request is invalid.", status_code=HTTPStatus.BAD_REQUEST)
+```

fastapi_custom_responses-0.0.11.dist-info/RECORD

@@ -0,0 +1,7 @@
+fastapi_custom_responses/__init__.py,sha256=zi9Dki562lstWxGcx5qQulI12x4YNHXij2r4j6kPnfU,141
+fastapi_custom_responses/errors.py,sha256=LuzUfo432BkO4stbKo57lS_npYypczFohWr1lomHwD0,3665
+fastapi_custom_responses/responses.py,sha256=IFWAEyI-UQQ8hgMQraAoUX7ehe_joB1oEo63hBLEcZo,437
+fastapi_custom_responses-0.0.11.dist-info/METADATA,sha256=0wqgmeRE-bTQlUiAdwAya_H3sSvdBhR6YkJoUFUZ1Gs,3752
+fastapi_custom_responses-0.0.11.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+fastapi_custom_responses-0.0.11.dist-info/licenses/LICENSE,sha256=QhnxalVFkRcaDnRpKtlGMBA0V_riuWAFEauYASyBTmI,1064
+fastapi_custom_responses-0.0.11.dist-info/RECORD,,

fastapi_custom_responses-0.0.11.dist-info/WHEEL

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

fastapi_custom_responses-0.0.11.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KRYSTAL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.