Metadata-Version: 2.5
Name: fastresponse
Version: 1.0.0
Summary: A clean, production-grade standardized response envelope framework for FastAPI applications.
Project-URL: Homepage, https://github.com/Blackroot-Corporation/FastResponse
Project-URL: Documentation, https://github.com/Blackroot-Corporation/FastResponse#readme
Project-URL: Repository, https://github.com/Blackroot-Corporation/FastResponse
Project-URL: Issues, https://github.com/Blackroot-Corporation/FastResponse/issues
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

# FastResponse

[![PyPI version](https://img.shields.io/pypi/v/fastresponse.svg)](https://pypi.org/project/fastresponse/)
[![Python Version](https://img.shields.io/pypi/pyversions/fastresponse.svg)](https://pypi.org/project/fastresponse/)
[![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.
- **Zero Boilerplate**: Simple registration via `register_exception_handlers(app)`.

---

## 🚀 Installation

Install via `pip`:

```bash
pip install fastresponse
```

Or using `uv`:

```bash
uv add fastresponse
```

Or using `poetry`:

```bash
poetry add fastresponse
```

---

## 💡 Quickstart

```python
from fastapi import FastAPI
from fastresponse 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"
  }
}
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).
