https://github.com/uriyyo/fastapi-pagination

FastAPI pagination 📖
https://github.com/uriyyo/fastapi-pagination

fastapi fastapi-pagination fastapi-sqlalchemy gino pagination

Last synced: 28 days ago
JSON representation

FastAPI pagination 📖

• Host: GitHub
• URL: https://github.com/uriyyo/fastapi-pagination
• Owner: uriyyo
• License: mit
• Created: 2020-11-06T18:05:12.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2024-05-21T03:46:05.000Z (6 months ago)
• Last Synced: 2024-05-21T08:33:47.923Z (6 months ago)
• Topics: fastapi, fastapi-pagination, fastapi-sqlalchemy, gino, pagination
• Language: Python
• Homepage: https://uriyyo-fastapi-pagination.netlify.app/
• Size: 4.53 MB
• Stars: 1,045
• Watchers: 10
• Forks: 120
• Open Issues: 19
• Metadata Files:
  • Readme: README.md
  • Contributing: docs/contributing.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-fastapi - FastAPI Pagination - Pagination for FastAPI. (Third-Party Extensions / Utils)
• awesome-fastapi - FastAPI Pagination - Pagination for FastAPI. (Third-Party Extensions / Utils)

README

        




















## 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

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

class UserOut(BaseModel):  # define your model

    name: str = Field(..., example="Steve")

    surname: str = Field(..., example="Rogers")

users = [  # create some data

    UserOut(name="Steve", surname="Rogers"),

    # ...

]

# req: GET /users

@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

```

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.

```python

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: