Metadata-Version: 2.4
Name: fastapi-response-handler
Version: 0.1.0
Summary: A clean, customizable FastAPI exception handler and standardized response manager with Pydantic support.
Project-URL: Homepage, https://github.com/example/fastapi-response-handler
Project-URL: Repository, https://github.com/example/fastapi-response-handler
Author-email: Vraj Makwana <vrajhello60@gmail.com>
License-Expression: MIT
Keywords: api,exception-handler,fastapi,pydantic,response-formatter
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: fastapi>=0.95.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: httpx>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# FastAPI Response & Exception Handler (`fastapi-response-handler`)

A production-ready Python package for standardizing FastAPI exception handling and response formatting with customizable **Pydantic** schemas.

---

## 🌟 Key Features

- 🛠 **Standard Exception Handlers**: Intercept `HTTPException`, `ServerException`, `AppException`, `RequestValidationError`, and uncaught `Exception`.
- 📐 **Customizable Pydantic Schemas**: Easily define your own Pydantic models for success and error responses.
- ⚡️ **Flexible Registration**: Works with manual `app.add_exception_handler(...)` or one-line `register_exception_handlers(app)`.
- 📦 **Prebuilt Exception Hierarchy**: Built-in exception classes (`ServerException`, `NotFoundException`, `UnauthorizedException`, `BadRequestException`, `ForbiddenException`).
- 🎯 **Clean Utilities**: Dynamic `success_response(...)` and `error_response(...)` helpers.

---

## 🚀 Quick Start

### 1. Installation

Install via pip in editable mode or from PyPI:
```bash
pip install fastapi-response-handler
```
*(or locally: `pip install -e ./fastapi_response_handler`)*

---

### 2. Standard Usage (Manual Registration)

As requested, you can add exception handlers line-by-line:

```python
from fastapi import FastAPI, HTTPException
from fastapi_response_handler import (
    http_exception_handler,
    server_exception_handler,
    ServerException,
    success_response
)

app = FastAPI()

# Register Handlers
app.add_exception_handler(HTTPException, http_exception_handler)
app.add_exception_handler(ServerException, server_exception_handler)

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    if item_id == 0:
        raise HTTPException(status_code=400, detail="Item ID cannot be zero")
    elif item_id < 0:
        raise ServerException(message="Database error occurred", status_code=500)
    
    return success_response(msg="Item fetched successfully", data={"item_id": item_id})
```

---

### 3. One-Line Auto Registration

Alternatively, register all handlers (including Pydantic validation errors and uncaught exceptions) in a single line:

```python
from fastapi import FastAPI
from fastapi_response_handler import register_exception_handlers

app = FastAPI()
register_exception_handlers(app)
```

---

## 🎨 Custom Pydantic Response Formats

You can customize response structures globally using your own **Pydantic** models:

```python
from pydantic import BaseModel
from typing import Optional, Any
from fastapi_response_handler import configure_response_schemas

# Define your custom error structure
class MyCustomErrorResponse(BaseModel):
    code: int
    message: str
    details: Optional[Any] = None

# Define your custom success structure
class MyCustomSuccessResponse(BaseModel):
    code: int
    message: str
    result: Optional[Any] = None

# Configure globally
configure_response_schemas(
    error_schema=MyCustomErrorResponse,
    success_schema=MyCustomSuccessResponse
)
```

Now, every raised exception or `success_response` call will automatically match your custom structure!

---

## 🏛 Available Built-in Exceptions

- `AppException(message, status_code, data)`
- `ServerException(message, status_code, data)` *(Default status: 500)*
- `NotFoundException(message, data)` *(Default status: 404)*
- `UnauthorizedException(message, data)` *(Default status: 401)*
- `ForbiddenException(message, data)` *(Default status: 403)*
- `BadRequestException(message, data)` *(Default status: 400)*
- `ValidationException(message, data)` *(Default status: 422)*
