Metadata-Version: 2.1
Name: fastapi-pagination
Version: 0.12.23
Summary: FastAPI pagination
Home-page: https://github.com/uriyyo/fastapi-pagination
License: MIT
Author: Yurii Karabas
Author-email: 1998uriyyo@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Provides-Extra: all
Provides-Extra: asyncpg
Provides-Extra: beanie
Provides-Extra: bunnet
Provides-Extra: databases
Provides-Extra: django
Provides-Extra: mongoengine
Provides-Extra: motor
Provides-Extra: orm
Provides-Extra: ormar
Provides-Extra: piccolo
Provides-Extra: scylla-driver
Provides-Extra: sqlalchemy
Provides-Extra: sqlmodel
Provides-Extra: tortoise
Requires-Dist: SQLAlchemy (>=1.3.20) ; extra == "sqlalchemy" or extra == "asyncpg" or extra == "all"
Requires-Dist: asyncpg (>=0.24.0) ; extra == "asyncpg" or extra == "all"
Requires-Dist: beanie (>=1.25.0) ; extra == "beanie" or extra == "all"
Requires-Dist: bunnet (>=1.1.0,<2.0.0) ; extra == "bunnet" or extra == "all"
Requires-Dist: databases (>=0.6.0) ; extra == "databases" or extra == "orm" or extra == "django" or extra == "all"
Requires-Dist: django (<5.0.0) ; extra == "django" or extra == "all"
Requires-Dist: fastapi (>=0.93.0)
Requires-Dist: mongoengine (>=0.23.1,<0.29.0) ; extra == "mongoengine" or extra == "all"
Requires-Dist: motor (>=2.5.1,<4.0.0) ; extra == "motor" or extra == "all"
Requires-Dist: orm (>=0.3.1) ; extra == "orm" or extra == "all"
Requires-Dist: ormar (>=0.11.2) ; extra == "ormar" or extra == "all"
Requires-Dist: piccolo (>=0.89,<0.122) ; extra == "piccolo" or extra == "all"
Requires-Dist: pony (>=0.7.16,<0.8.0) ; extra == "all"
Requires-Dist: pydantic (>=1.9.1)
Requires-Dist: scylla-driver (>=3.25.6,<4.0.0) ; extra == "scylla-driver" or extra == "all"
Requires-Dist: sqlakeyset (>=2.0.1680321678,<3.0.0) ; extra == "sqlmodel" or extra == "sqlalchemy" or extra == "all"
Requires-Dist: sqlmodel (>=0.0.8,<0.0.15) ; extra == "sqlmodel" or extra == "all"
Requires-Dist: tortoise-orm (>=0.16.18,<0.21.0) ; extra == "tortoise" or extra == "all"
Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
Project-URL: Repository, https://github.com/uriyyo/fastapi-pagination
Description-Content-Type: text/markdown

<h1 align="center">
<img alt="logo" src="https://raw.githubusercontent.com/uriyyo/fastapi-pagination/main/docs/img/logo.png">
</h1>

<div align="center">
<img alt="license" src="https://img.shields.io/badge/License-MIT-lightgrey">
<img alt="test" src="https://github.com/uriyyo/fastapi-pagination/workflows/Test/badge.svg">
<img alt="codecov" src="https://codecov.io/gh/uriyyo/fastapi-pagination/branch/main/graph/badge.svg?token=QqIqDQ7FZi">
<a href="https://pepy.tech/project/fastapi-pagination"><img alt="downloads" src="https://pepy.tech/badge/fastapi-pagination"></a>
<a href="https://pypi.org/project/fastapi-pagination"><img alt="pypi" src="https://img.shields.io/pypi/v/fastapi-pagination"></a>
<img alt="black" src="https://img.shields.io/badge/code%20style-black-000000.svg">
</div>

## Introduction

`fastapi-pagination` is a Python library designed to simplify pagination in FastAPI applications. 
It provides a set of utility functions and data models to help you paginate your database queries 
and return paginated responses to your clients.

With `fastapi-pagination`, you can easily define pagination parameters in your FastAPI endpoint functions,
and use them to generate paginated responses that include the requested subset of your data.
The library supports a variety of pagination strategies, including cursor-based pagination and page-based pagination.

`fastapi-pagination` is built on top of the popular `fastapi` library, and it works with a wide range 
of SQL and NoSQL databases frameworks. It also supports async/await syntax and is compatible with Python 3.8 and higher.

Features:
* Simplifies pagination in FastAPI applications.
* Supports a variety of pagination strategies, including cursor-based pagination and page-based pagination
* Works with a wide range of SQL and NoSQL databases frameworks, including `SQLAlchemy`, `Tortoise ORM`, and `PyMongo`.
* Supports async/await syntax.
* Compatible with Python 3.8 and higher.

----

For more information on how to use fastapi-pagination, please refer to the 
[official documentation](https://uriyyo-fastapi-pagination.netlify.app/).

---

## Installation

```bash
pip install fastapi-pagination
```

## Quickstart

All you need to do is to use `Page` class as a return type for your endpoint and call `paginate` function
on data you want to paginate.

```py
from fastapi import FastAPI
from pydantic import BaseModel, Field

# import all you need from fastapi-pagination
from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()  # create FastAPI app


class UserOut(BaseModel):  # define your model
    name: str = Field(..., example="Steve")
    surname: str = Field(..., example="Rogers")


users = [  # create some data
    # ...
]


@app.get('/users')  
async def get_users() -> Page[UserOut]:  # use Page[UserOut] as return type annotation
    return paginate(users)  # use paginate function to paginate your data


add_pagination(app)  # important! add pagination to your app
```

Please, be careful when you work with databases, because default `paginate` will require to load all data in memory.

For instance, if you use `SQLAlchemy` you can use `paginate` from `fastapi_pagination.ext.sqlalchemy` module.

```py
from sqlalchemy import select
from fastapi_pagination.ext.sqlalchemy import paginate


@app.get('/users')
def get_users(db: Session = Depends(get_db)) -> Page[UserOut]:
    return paginate(db, select(User).order_by(User.created_at))
```

---

Code from `Quickstart` will generate OpenAPI schema as bellow:

<div align="center">
<img alt="app-example" src="https://raw.githubusercontent.com/uriyyo/fastapi-pagination/main/docs/img/example.png">
</div>

