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

pip install fast-paginate

Quick Start

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

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

Example:

GET /users?page=2&page_size=20

API Reference

Paginate

Dependency class responsible for calculating pagination values.

pagination = Annotated[Paginate, Depends()]

Available attributes:

pagination.limit
pagination.offset

paginate()

Fetches paginated records from SQLAlchemy.

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

Returns

(total_records, items)

ApiPaginateResponse

Generic response model.

ApiPaginateResponse[list[UserOut]]

Produces

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

get_paginated_response()

Builds the final API response.

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