paginate-fastapi 1.0.2

A simple and efficient pagination library for FastAPI applications

Paginate FastAPI

A simple and efficient pagination library for FastAPI applications.

Features

• Easy-to-use pagination with FastAPI
• Async support out of the box
• Flexible filtering options
• Customizable sorting
• Type-safe with full type hints
• Compatible with FastAPI

Installation

Using Poetry

poetry add paginate-fastapi

Using Pip

pip install paginate-fastapi

Quick Start

Usage as decorator

from pagination.decorator import paginate

@router.get("/", response_model=PageResponse[YourModel])
@paginate(YourModel, lambda: get_db)
async def get_items(
    db: AsyncSession = Depends(get_db),
    pagination: PaginationParams = Depends()
):
    ...
    return { 'extra_data': 'data' }

Usage as middleware

from fastapi import FastAPI, Depends
from sqlmodel import SQLModel, Field
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from pagination import PaginationMiddleware, PaginationParams

app = FastAPI()

# Initialize your database
engine = create_async_engine("sqlite+aiosqlite:///database.db")

async def get_session() -> AsyncSession:
    async with AsyncSession(engine) as session:
        yield session

paginator = PaginationMiddleware(get_session)

# Define your model
class User(SQLModel, table=True):
    id: int = Field(primary_key=True)
    name: str
    email: str
    age: int

# Add pagination to your endpoint
@app.get("/users/")
async def get_users(
    pagination: PaginationParams = Depends(),
    paginator: PaginationMiddleware = Depends(lambda: paginator),
):
    return await paginator.paginate(User, pagination)

Sample Request and Response

curl -X GET "http://localhost:8000/users/?page=1&page_size=10"

{
    "items": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "[e-mail]",
            "age": 30
        }
    ],
    "total": 100,
    "page": 1,
    "page_size": 10,
    "pages": 10,
    "has_next": true,
    "has_previous": false
}

Sorting

# Sort by name ascending
users/?sort_by=name&sort_order=asc

# Sort by age descending
users/?sort_by=age&sort_order=desc

Filtering

# Filter users by age greater than 30
users/?filter_field=age&filter_operator=gt&filter_value=30

# Filter users by name containing "John"
users/?filter_field=name&filter_operator=like&filter_value=John

# Filter users by age in a list
users/?filter_field=age&filter_operator=in&filter_value=[25,30,35]

Available Filter Operators

• eq: Equal to
• ne: Not equal to
• gt: Greater than
• lt: Less than
• ge: Greater than or equal to
• le: Less than or equal to
• like: Contains (case-sensitive)
• ilike: Contains (case-insensitive)
• in: In list of values
• not_in: Not in list of values

Development

Setup

# Clone the repository
git clone https://github.com/ritvikdayal/paginate-fastapi.git
cd paginate-fastapi

# Install dependencies
poetry install --with dev

# Setup pre-commit hooks (optional)
make setup-hooks

Running Tests

make test

Code Quality

# Run all code quality checks
make pre-commit

# Format code only
make format

# Run linters only
make lint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.