responseapi 1.0.0__py3-none-any.whl

responseapi/__init__.py

@@ -0,0 +1,31 @@
+from responseapi._exceptions.api_exception import APIException
+from responseapi._interceptors.handlers import (
+    api_exception_handler,
+    http_exception_handler,
+    register_exception_handlers,
+    unhandled_exception_handler,
+    validation_exception_handler,
+)
+from responseapi._schemas.response_schema import (
+    CustomErrorResponseSchema,
+    CustomSuccessResponseSchema,
+)
+from responseapi._services.response_service import APIResponse
+
+__all__ = [
+    "APIException",
+    "APIResponse",
+    "CustomErrorResponseSchema",
+    "CustomSuccessResponseSchema",
+    "api_exception_handler",
+    "http_exception_handler",
+    "register_exception_handlers",
+    "unhandled_exception_handler",
+    "validation_exception_handler",
+]
+
+
+def __getattr__(name: str):
+    if name in __all__:
+        return globals()[name]
+    raise AttributeError(f"module {__name__} has no attribute {name}")

responseapi/_exceptions/__init__.py

@@ -0,0 +1,3 @@
+from responseapi._exceptions.api_exception import APIException
+
+__all__ = ["APIException"]

responseapi/_exceptions/api_exception.py

@@ -0,0 +1,36 @@
+from typing import Any, Mapping
+
+from fastapi import status
+
+
+class APIException(Exception):
+    """Custom API Exception for domain-level errors.
+
+    This exception mirrors FastAPI's ``HTTPException`` style but is a plain
+    ``Exception`` that you can raise from your business logic.
+
+    Parameters
+    ----------
+    error:
+        Human-readable error message that will be exposed to the client.
+    errors:
+        Optional extra error data (e.g., validation errors) placed under
+        an ``errors`` key in the JSON response.
+    status_code:
+        HTTP status code to return. Defaults to ``400 Bad Request``.
+    headers:
+        Optional extra HTTP headers to include in the response.
+    """
+
+    def __init__(
+        self,
+        error: str = "An error occurred",
+        errors: Any = None,
+        status_code: int = status.HTTP_400_BAD_REQUEST,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(error)
+        self.error = error
+        self.errors = errors
+        self.status_code = status_code
+        self.headers = headers

responseapi/_interceptors/__init__.py

@@ -0,0 +1,15 @@
+from responseapi._interceptors.handlers import (
+    api_exception_handler,
+    http_exception_handler,
+    register_exception_handlers,
+    unhandled_exception_handler,
+    validation_exception_handler,
+)
+
+__all__ = [
+    "api_exception_handler",
+    "http_exception_handler",
+    "validation_exception_handler",
+    "unhandled_exception_handler",
+    "register_exception_handlers",
+]

responseapi/_interceptors/handlers.py

@@ -0,0 +1,66 @@
+from fastapi import FastAPI, Request, status
+from fastapi.exceptions import HTTPException, RequestValidationError
+from fastapi.responses import JSONResponse
+
+from responseapi._exceptions.api_exception import APIException
+from responseapi._services.response_service import APIResponse
+
+
+async def api_exception_handler(_: Request, exc: APIException) -> JSONResponse:
+    """
+    Handles Domain-level APIExceptions cleanly
+    """
+    return APIResponse.error(
+        error=exc.error,
+        errors=exc.errors,
+        status_code=exc.status_code,
+        headers=getattr(exc, "headers", None),
+    )
+
+
+async def http_exception_handler(_: Request, exc: HTTPException) -> JSONResponse:
+    """
+    Handles HTTPExceptions cleanly
+    """
+    return APIResponse.error(
+        error=str(exc.detail) if hasattr(exc, "detail") else str(exc),
+        errors=getattr(exc, "errors", None),
+        status_code=exc.status_code,
+        headers=getattr(exc, "headers", None),
+    )
+
+
+async def validation_exception_handler(
+    _: Request, exc: RequestValidationError
+) -> JSONResponse:
+    """
+    Handles ValidationExceptions cleanly
+    """
+    return APIResponse.error(
+        error="Validation error",
+        errors=exc.errors(),
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+    )
+
+
+async def unhandled_exception_handler(_: Request, exc: Exception) -> JSONResponse:
+    """
+    Handles unhandled exceptions cleanly
+    """
+    return APIResponse.error(
+        error="Internal server error",
+        errors=str(exc),
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+    )
+
+
+def register_exception_handlers(app: FastAPI, include_unhandled: bool = True) -> None:
+    """
+    Hook all responseapi exception interceptors in the FastAPI lifecycle
+    """
+    app.add_exception_handler(APIException, api_exception_handler)
+    app.add_exception_handler(HTTPException, http_exception_handler)
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+
+    if include_unhandled:
+        app.add_exception_handler(Exception, unhandled_exception_handler)

responseapi/_schemas/__init__.py

@@ -0,0 +1,6 @@
+from responseapi._schemas.response_schema import (
+    CustomErrorResponseSchema,
+    CustomSuccessResponseSchema,
+)
+
+__all__ = ["CustomSuccessResponseSchema", "CustomErrorResponseSchema"]

responseapi/_schemas/response_schema.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import field
+from typing import Generic, List, Optional, TypeVar, Union
+
+from dataclasses import dataclass
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class CustomSuccessResponseSchema(Generic[T]):
+    """Custom success response schema for API endpoints.
+
+    Attributes
+    ----------
+    success: bool
+        Indicates the request succeeded.
+    data: Optional[Union[T, List[T]]]
+        The payload returned by the endpoint. Can be a single object or a list.
+    message: Optional[str]
+        Human‑readable description of the result.
+    """
+
+    success: bool = field(default=True)
+    data: Optional[Union[T, List[T]]] = field(default=None)
+    message: Optional[str] = field(default=None)
+
+
+@dataclass(slots=True)
+class CustomErrorResponseSchema(Generic[T]):
+    """Custom error response schema for API endpoints.
+
+    Attributes
+    ----------
+    success: bool
+        Always ``False`` for error responses.
+    errors: Optional[Union[T, List[T]]]
+        Detailed error information.
+    error: Optional[str]
+        Short error message.
+    """
+
+    success: bool = field(default=False)
+    errors: Optional[Union[T, List[T]]] = field(default=None)
+    error: Optional[str] = field(default=None)

responseapi/_services/__init__.py

@@ -0,0 +1,3 @@
+from responseapi._services.response_service import APIResponse
+
+__all__ = ["APIResponse"]

responseapi/_services/response_service.py

@@ -0,0 +1,64 @@
+from typing import Any
+
+from fastapi import status
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse
+
+
+class APIResponse:
+    """
+    Factory class for constructing standardized API JSON responses.
+    """
+
+    @staticmethod
+    def success(
+        data: Any = None,
+        message: str = "Operation completed successfully",
+        status_code: int = status.HTTP_200_OK,
+        headers: dict[str, str] | None = None,
+    ) -> JSONResponse:
+        """
+        Generates a standard HTTP success response
+        """
+
+        if status_code == status.HTTP_204_NO_CONTENT:
+            return JSONResponse(
+                status_code=status_code,
+                content=None,
+                headers=headers,
+            )
+
+        payload = {
+            "success": True,
+            "message": message,
+            "data": jsonable_encoder(data),
+        }
+
+        return JSONResponse(
+            content=payload,
+            status_code=status_code,
+            headers=headers,
+        )
+
+    @staticmethod
+    def error(
+        error: str = "An error occurred",
+        errors: Any = None,
+        status_code: int = status.HTTP_400_BAD_REQUEST,
+        headers: dict[str, str] | None = None,
+    ) -> JSONResponse:
+        """
+        Generates a standard HTTP error response
+        """
+
+        payload = {
+            "success": False,
+            "error": error,
+            "errors": jsonable_encoder(errors),
+        }
+
+        return JSONResponse(
+            content=payload,
+            status_code=status_code,
+            headers=headers,
+        )

responseapi/py.typed

@@ -0,0 +1 @@
+

responseapi-1.0.0.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: responseapi
+Version: 1.0.0
+Summary: A clean, production-grade standardized response envelope framework for FastAPI applications.
+Author-email: Dev Raj Khadka <devrajkhadka941@gmail.com>, Aryan Tamang <aryantamangcs@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-design,exception-handler,fastapi,jsonresponse,middleware,openapi,pydantic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# responseapi
+
+[![PyPI version](https://img.shields.io/pypi/v/responseapi.svg)](https://pypi.org/project/responseapi/)
+[![Python Version](https://img.shields.io/pypi/pyversions/responseapi.svg)](https://pypi.org/project/responseapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A clean, production-grade standardized response envelope framework for **FastAPI** applications.
+
+---
+
+## 📌 Features
+
+- **Standardized Response Format**: Enforces unified JSON response envelopes for both success and error responses across your API.
+- **Automated Exception Handling**: Seamlessly intercepts domain-level `APIException`, FastAPI `HTTPException`, `RequestValidationError`, and unhandled server errors.
+- **Pydantic & OpenAPI Integration**: Generic models (`APISuccessResponseModel`, `CustomSuccessResponseSchema`, `CustomErrorResponseSchema`) for type safety and automatic OpenAPI schema generation.
+- **Structured Logging**: Built-in exception logging using `loguru`.
+- **Zero Boilerplate**: Simple registration via `register_exception_handlers(app)`.
+
+---
+
+## 🚀 Installation
+
+Install via `pip`:
+
+```bash
+pip install responseapi
+```
+
+Or using `uv`:
+
+```bash
+uv add responseapi
+```
+
+Or using `poetry`:
+
+```bash
+poetry add responseapi
+```
+
+---
+
+## 💡 Quickstart
+
+```python
+from fastapi import FastAPI
+from responseapi import (
+    APIResponse,
+    APIException,
+    register_exception_handlers,
+)
+
+app = FastAPI(title="My API")
+
+# Register standardized exception handlers
+register_exception_handlers(app)
+
+@app.get("/users/{user_id}")
+def get_user(user_id: int):
+    if user_id <= 0:
+        raise APIException(
+            error="User not found",
+            errors={"user_id": "Must be a positive integer"},
+            status_code=404,
+        )
+
+    return APIResponse.success(
+        data={"user_id": user_id, "username": "johndoe"},
+        message="User details retrieved successfully",
+    )
+```
+
+---
+
+## 📦 Response Envelopes
+
+### 1. Success Response Structure (`HTTP 200 OK`)
+
+```json
+{
+  "success": true,
+  "message": "User details retrieved successfully",
+  "data": {
+    "user_id": 1,
+    "username": "johndoe"
+  }
+}
+```
+
+### 2. Error Response Structure (`HTTP 400 / 404 / 422 / 500`)
+
+```json
+{
+  "success": false,
+  "error": "User not found",
+  "errors": {
+    "user_id": "Must be a positive integer"
+  }
+}
+```
+
+---
+
+## 📖 API Reference
+
+### `APIResponse`
+
+Factory class to return standardized `JSONResponse` objects:
+
+- `APIResponse.success(data=None, message="Operation completed successfully", status_code=200, headers=None)`
+- `APIResponse.error(error="An error occurred", errors=None, status_code=400, headers=None)`
+
+### `APIException`
+
+Custom domain exception for raising controlled errors:
+
+```python
+raise APIException(
+    error="Insufficient funds",
+    errors={"balance": 10.0, "required": 50.0},
+    status_code=400
+)
+```
+
+### `register_exception_handlers(app: FastAPI, include_unhandled: bool = True)`
+
+Registers error handlers for:
+- `APIException` -> Returns `APIResponse.error(...)`
+- `HTTPException` -> Returns `APIResponse.error(...)`
+- `RequestValidationError` -> Returns validation errors formatted with status `422`
+- `Exception` (optional) -> Catches unhandled errors and returns status `500`
+
+### Pydantic Models & Schemas
+
+- `APISuccessResponseModel[T]`: Pydantic generic model for standard success envelopes.
+- `CustomSuccessResponseSchema[T]`: Pydantic generic schema for success payloads.
+- `CustomErrorResponseSchema[T]`: Pydantic generic schema for error payloads.
+
+---
+
+## 🛠️ Deploying / Publishing to PyPI
+
+Follow these instructions to build and publish `responseapi` to **PyPI** (Python Package Index).
+
+### 1. Prerequisites
+
+Ensure you have a PyPI account registered at [pypi.org](https://pypi.org) and an API token or Trusted Publisher configuration set up.
+
+### 2. Build the Package
+
+You can build the package using `uv` or standard Python `build`:
+
+#### Using `uv`:
+```bash
+uv build
+```
+
+#### Using `build`:
+```bash
+pip install build twine
+python -m build
+```
+
+This generates distribution archives in the `dist/` directory:
+- `dist/responseapi-1.0.0-py3-none-any.whl` (Wheel)
+- `dist/responseapi-1.0.0.tar.gz` (Source distribution)
+
+### 3. Upload to PyPI
+
+#### Option A: Using `uv publish`
+
+Set your API token and publish:
+
+```bash
+uv publish --token <your-pypi-token>
+```
+
+Or publish to **TestPyPI** first to verify:
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/ --token <your-testpypi-token>
+```
+
+#### Option B: Using `twine`
+
+```bash
+twine check dist/*
+twine upload dist/* -u __token__ -p <your-pypi-token>
+```
+
+### 4. Automated Publishing via GitHub Actions (Recommended)
+
+This project includes a `.github/workflows/publish.yml` GitHub Actions workflow.
+
+1. Go to your GitHub repository **Settings > Secrets and variables > Actions**.
+2. Create a secret named `PYPI_API_TOKEN` containing your PyPI API token.
+3. Push a new release or git tag (e.g., `git tag v1.0.0 && git push origin v1.0.0`).
+4. GitHub Actions will automatically test, build, and publish the package to PyPI!
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

responseapi-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+responseapi/__init__.py,sha256=JGIhKp6f3cyrj4yiEcFunX9Dn1r4uOrdRWsl3dn1bBE,892
+responseapi/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+responseapi/_exceptions/__init__.py,sha256=u71rvrTpfEONlbnPTowqcXdtlK2R-Ld0JUhTPqsKba0,91
+responseapi/_exceptions/api_exception.py,sha256=GFdQAjPCcm_dsBNQo4OpmoESQCm7qCxhY-_TDTI4Npw,1087
+responseapi/_interceptors/__init__.py,sha256=YgSRaXq5XTHGY29Yu4ViELMAnCg1Dq9VqD_w_Jw1Etk,386
+responseapi/_interceptors/handlers.py,sha256=oF8H3toM7UANh83z8FYA-JtRm4KaFqd2uoa2ts5Tp_w,2091
+responseapi/_schemas/__init__.py,sha256=yhw6LUWBOkihsPVWDXitiKXN8o64eGlW3wGXmHcKQaA,189
+responseapi/_schemas/response_schema.py,sha256=h0P6JDCbUNu_LnfmVffhnvfazdwEELi4gkGdMOTADNE,1261
+responseapi/_services/__init__.py,sha256=7RttsGHBoc6VNrrF1cjFW7tPJIUp6o3AZAeBziDqUWQ,90
+responseapi/_services/response_service.py,sha256=4SVYNWrW0rfmvX3D9-cJtUWfFxUwJWpxlKMICyZEzFs,1610
+responseapi-1.0.0.dist-info/METADATA,sha256=kt99qfQZl-8kS_4hUTA-TavnHSBri8OBSK-esBU7jYQ,6239
+responseapi-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+responseapi-1.0.0.dist-info/licenses/LICENSE,sha256=623cFq2VY_6DALSkVetrK2FurEfXkiSz9_z3Lk7rjQM,1076
+responseapi-1.0.0.dist-info/RECORD,,

responseapi-1.0.0.dist-info/WHEEL

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

responseapi-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 responseapi Authors
+
+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.