Skip to main content

Paginate FastAPI

PyPI version License: MIT Python 3.11+

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": "john.doe@example.com",
            "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.

Metadata

Release files for paginate-fastapi 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for paginate-fastapi 1.0.2
File Size Uploaded Provenance Actions
paginate_fastapi-1.0.2.tar.gz 7.6 kB With provenance Details for paginate_fastapi-1.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for paginate-fastapi 1.0.2
File Interpreter ABI Platform Actions
paginate_fastapi-1.0.2-py3-none-any.whl Python 3 none any Details for paginate_fastapi-1.0.2-py3-none-any.whl

Total release size: 16.7 kB

Release files / paginate_fastapi-1.0.2.tar.gz

Download URL paginate_fastapi-1.0.2.tar.gz
Size 7.6 kB
Tags Source
SHA-256 checksum
How to use checksums
172836a5261766fbb3fabe4d61b0185a52c1cc01df601e2f41a81ef958d444e8
BLAKE2b-256 checksum
How to use checksums
0f7c10b8951ff4b853d60140a470f54086de19ae3824426aa29ff25e6113426e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 23, 2025.

Transparency log

Release files / paginate_fastapi-1.0.2-py3-none-any.whl

Download URL paginate_fastapi-1.0.2-py3-none-any.whl
Size 9.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
27f9c6c2912ca2d34069ba72270571018b696b6f7e4867dac880917ced73ae23
BLAKE2b-256 checksum
How to use checksums
6778f4b4b14a72ac44fd4bed7287d0fd8b2a134ac2d19faaaa710f5e2b35d554
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 23, 2025.

Transparency log

Security for paginate-fastapi 1.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for paginate_fastapi-1.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 23, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page