<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>
</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
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:
<div align="center">
<img alt="app-example" src="https://raw.githubusercontent.com/uriyyo/fastapi-pagination/main/docs/img/example.png">
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/uriyyo/fastapi-pagination",
"name": "fastapi-pagination",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Yurii Karabas",
"author_email": "1998uriyyo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/83/4d/6e695098ce33b3394cf26b335ca4ec6407f9421cfdf9ad6a38775580db21/fastapi_pagination-0.12.34.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n<img alt=\"logo\" src=\"https://raw.githubusercontent.com/uriyyo/fastapi-pagination/main/docs/img/logo.png\">\n</h1>\n\n<div align=\"center\">\n<img alt=\"license\" src=\"https://img.shields.io/badge/License-MIT-lightgrey\">\n<img alt=\"test\" src=\"https://github.com/uriyyo/fastapi-pagination/workflows/Test/badge.svg\">\n<img alt=\"codecov\" src=\"https://codecov.io/gh/uriyyo/fastapi-pagination/branch/main/graph/badge.svg?token=QqIqDQ7FZi\">\n<a href=\"https://pepy.tech/project/fastapi-pagination\"><img alt=\"downloads\" src=\"https://pepy.tech/badge/fastapi-pagination\"></a>\n<a href=\"https://pypi.org/project/fastapi-pagination\"><img alt=\"pypi\" src=\"https://img.shields.io/pypi/v/fastapi-pagination\"></a>\n</div>\n\n## Introduction\n\n`fastapi-pagination` is a Python library designed to simplify pagination in FastAPI applications. \nIt provides a set of utility functions and data models to help you paginate your database queries \nand return paginated responses to your clients.\n\nWith `fastapi-pagination`, you can easily define pagination parameters in your FastAPI endpoint functions,\nand use them to generate paginated responses that include the requested subset of your data.\nThe library supports a variety of pagination strategies, including cursor-based pagination and page-based pagination.\n\n`fastapi-pagination` is built on top of the popular `fastapi` library, and it works with a wide range \nof SQL and NoSQL databases frameworks. It also supports async/await syntax and is compatible with Python 3.8 and higher.\n\nFeatures:\n\n* Simplifies pagination in FastAPI applications.\n* Supports a variety of pagination strategies, including cursor-based pagination and page-based pagination\n* Works with a wide range of SQL and NoSQL databases frameworks, including `SQLAlchemy`, `Tortoise ORM`, and `PyMongo`.\n* Supports async/await syntax.\n* Compatible with Python 3.8 and higher.\n\n----\n\nFor more information on how to use fastapi-pagination, please refer to the \n[official documentation](https://uriyyo-fastapi-pagination.netlify.app/).\n\n---\n\n## Installation\n\n```bash\npip install fastapi-pagination\n```\n\n## Quickstart\n\nAll you need to do is to use `Page` class as a return type for your endpoint and call `paginate` function\non data you want to paginate.\n\n```py\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel, Field\n\n# import all you need from fastapi-pagination\nfrom fastapi_pagination import Page, add_pagination, paginate\n\napp = FastAPI() # create FastAPI app\nadd_pagination(app) # important! add pagination to your app\n\n\nclass UserOut(BaseModel): # define your model\n name: str = Field(..., example=\"Steve\")\n surname: str = Field(..., example=\"Rogers\")\n\n\nusers = [ # create some data\n UserOut(name=\"Steve\", surname=\"Rogers\"),\n # ...\n]\n\n\n# req: GET /users\n@app.get(\"/users\")\nasync def get_users() -> Page[UserOut]:\n # use Page[UserOut] as return type annotation\n return paginate(users) # use paginate function to paginate your data\n```\n\nPlease, be careful when you work with databases, because default `paginate` will require to load all data in memory.\n\nFor instance, if you use `SQLAlchemy` you can use `paginate` from `fastapi_pagination.ext.sqlalchemy` module.\n\n```python\nfrom sqlalchemy import select\nfrom fastapi_pagination.ext.sqlalchemy import paginate\n\n\n@app.get(\"/users\")\ndef get_users(db: Session = Depends(get_db)) -> Page[UserOut]:\n return paginate(db, select(User).order_by(User.created_at))\n```\n\n---\n\nCode from `Quickstart` will generate OpenAPI schema as bellow:\n\n<div align=\"center\">\n<img alt=\"app-example\" src=\"https://raw.githubusercontent.com/uriyyo/fastapi-pagination/main/docs/img/example.png\">\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "FastAPI pagination",
"version": "0.12.34",
"project_urls": {
"Homepage": "https://github.com/uriyyo/fastapi-pagination",
"Repository": "https://github.com/uriyyo/fastapi-pagination"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "72f3a0a1e7efd88dba07743665d1f6f88008c9a1e174458581ecaa53b8699a7c",
"md5": "7dc91ce14bd1cc015a27445e165fa5c7",
"sha256": "089d1078aae1784395b4dbd923d0c8246641ddcc291c5ec6d92a30edb92ecbdd"
},
"downloads": -1,
"filename": "fastapi_pagination-0.12.34-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7dc91ce14bd1cc015a27445e165fa5c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 43308,
"upload_time": "2024-12-21T15:38:23",
"upload_time_iso_8601": "2024-12-21T15:38:23.493771Z",
"url": "https://files.pythonhosted.org/packages/72/f3/a0a1e7efd88dba07743665d1f6f88008c9a1e174458581ecaa53b8699a7c/fastapi_pagination-0.12.34-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "834d6e695098ce33b3394cf26b335ca4ec6407f9421cfdf9ad6a38775580db21",
"md5": "b41f50b466e54c92f5ebd7f7c5df4056",
"sha256": "05ee8c0bc572072160f7f30900bfd87869e1880c87bc5797922fec2e49e65f11"
},
"downloads": -1,
"filename": "fastapi_pagination-0.12.34.tar.gz",
"has_sig": false,
"md5_digest": "b41f50b466e54c92f5ebd7f7c5df4056",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 26901,
"upload_time": "2024-12-21T15:38:25",
"upload_time_iso_8601": "2024-12-21T15:38:25.842500Z",
"url": "https://files.pythonhosted.org/packages/83/4d/6e695098ce33b3394cf26b335ca4ec6407f9421cfdf9ad6a38775580db21/fastapi_pagination-0.12.34.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-21 15:38:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uriyyo",
"github_project": "fastapi-pagination",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fastapi-pagination"
}
JSON
