🕸️ 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

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.

{
  "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

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