Metadata-Version: 2.4
Name: fast-paginate
Version: 0.1.0
Summary: Pagination for FastAPI
Author-email: Sahil Sheoran <sahilsheoran24@gmail.com>
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pydantic>=2.13.4
Requires-Dist: sqlalchemy>=2.0.51
Dynamic: license-file

# Fast Paginate

A lightweight pagination library for **FastAPI** with **SQLAlchemy 2.x**.

Simple, dependency-friendly page number pagination without unnecessary complexity.

---

## Features

- FastAPI dependency injection support
- Async SQLAlchemy 2.x
- Page number pagination
- Automatic pagination metadata
- Next & Previous page URLs
- Generic Pydantic v2 response models
- Lightweight and easy to integrate

---

## Requirements

- Python 3.12+
- FastAPI
- Pydantic v2
- SQLAlchemy 2.x

---

## Installation

```bash
pip install fast-paginate
```

---

## Quick Start

```python
from typing import Annotated

from fastapi import APIRouter, Depends, Request
from sqlalchemy.ext.asyncio import AsyncSession

from fast_paginate import (
    Paginate,
    ApiPaginateResponse,
    paginate,
)

router = APIRouter()


@router.get(
    "/users",
    response_model=ApiPaginateResponse[list[UserOut]],
)
async def list_users(
    request: Request,
    pagination: Annotated[Paginate, Depends()],
    session: AsyncSession = Depends(get_async_db),
):

    total, users = await paginate(
        session=session,
        model=User,
        limit=pagination.limit,
        offset=pagination.offset,
    )

    return pagination.get_paginated_response(
        total=total,
        data=users,
        request=request,
    )
```

---

# Example Response

```json
{
  "status": "success",
  "message": "All Records are Retrieved Successfully",
  "data": [
    {
      "id": 1,
      "name": "John"
    }
  ],
  "meta": {
    "total_pages": 10,
    "total_records": 196,
    "current_page": 2,
    "page_size": 20,
    "next": "http://localhost:8000/users?page=3&page_size=20",
    "previous": "http://localhost:8000/users?page=1&page_size=20"
  }
}
```

---

# Pagination Parameters

| Parameter   | Type | Default      | Description      |
|-------------|------|--------------|------------------|
| page        | int  | 1            |                  |
| page_size   | int  | 20           | Records per page |

Example:

```
GET /users?page=2&page_size=20
```

---

# API Reference

## Paginate

Dependency class responsible for calculating pagination values.

```python
pagination = Annotated[Paginate, Depends()]
```

Available attributes:

```python
pagination.limit
pagination.offset
```

---

## paginate()

Fetches paginated records from SQLAlchemy.

```python
total, items = await paginate(
    session=session,
    model=User,
    limit=20,
    offset=40,
)
```

Returns

```python
(total_records, items)
```

---

## ApiPaginateResponse

Generic response model.

```python
ApiPaginateResponse[list[UserOut]]
```

Produces

```python
{
    "status": "...",
    "message": "...",
    "data": [...],
    "meta": {...}
}
```

---

## get_paginated_response()

Builds the final API response.

```python
return pagination.get_paginated_response(
    total=total,
    data=users,
    request=request,
)
```

---

# Roadmap

Future plans include:

- Cursor Pagination
- Offset Pagination
- Sync SQLAlchemy support
- Custom response messages
- Custom page parameter names

---

# Dependencies

- FastAPI
- Pydantic v2
- SQLAlchemy 2.x

---

# License

MIT License
