Metadata-Version: 2.4
Name: protogrid
Version: 1.0.0
Summary: A lightweight and standardized API response utility for Python web API frameworks.
Author-email: Matrixxboy <matrix.utsav.lankapati@gmail.com>
Maintainer-email: Matrixxboy <matrix.utsav.lankapati@gmail.com>
License: MIT
Project-URL: Homepage, https://twomportal.vercel.app/protogrid/home
Project-URL: Documentation, https://twomportal.vercel.app/protogrid/docs
Project-URL: Source, https://github.com/Matrixxboy/protogrid
Project-URL: Issues, https://github.com/Matrixxboy/protogrid/issues
Project-URL: Changelog, https://github.com/Matrixxboy/protogrid/releases
Keywords: api,response,standardized,pagination,fastapi,flask,metadata,error-handling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Framework :: Flask
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 🕸️ Protogrid

**Standardized, Type-Safe API Responses for Python.**

Protogrid is a lightweight library designed to enforce a consistent JSON structure across your services. It automates pagination logic, error formatting, and metadata injection so you can focus on your business logic.

## 🚀 Quick Start

```python
from protogrid import make_response

user_data = {
    "user_id": 123,
    "name": "Alice"
}

return make_response(
    status=200,
    message="Request processed successfully",
    payload=user_data,
    page=1,
    limit=10,
    total_items=100,
    include_meta=True
)

```

## 📦 Response Structure

Protogrid ensures every response follows a predictable schema, making life easier for frontend consumers.

```json
{
  "success": true,
  "message": "Request processed successfully",
  "http_code": 200,
  "payload": {
    "user_id": 123,
    "name": "Alice"
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total_items": 100,
    "total_pages": 10,
    "has_next": true,
    "has_prev": false
  },
  "error": null,
  "meta": {
    "timestamp": "2026-02-13T15:58:20.000Z",
    "request_id": "req_123e4567-e89b-12d3-a456-426614174000"
  }
}

```

## ✨ Why Protogrid?

* **Consistency**: Eliminates "snowflake" responses; your API always speaks the same language.
* **Zero Math**: Automatic calculation of `total_pages`, `has_next`, and `has_prev`.
* **Framework Agnostic**: Works seamlessly with **FastAPI, Flask, Django**, or even standalone scripts.
* **Type Safety**: Built-in support for `APIStatus` enums and type-hinted payloads.
* **Traceability**: Automatically includes `request_id` and ISO timestamps for easier debugging.

## 🛠️ Installation & Links

| Resource | Link |
| --- | --- |
| **Source Code** | [GitHub Repository](https://github.com/Matrixxboy/protogrid) |
| **Documentation** | [Full Docs](https://github.com/Matrixxboy/protogrid) |
| **Latest Version** | `v1.0.0` (Stable) |

> **Note on v1.0.0**: This release resolves "Status Swallowing" issues, ensuring that internal error states no longer mask the actual HTTP status codes.
