# Paginate FastAPI
[](https://badge.fury.io/py/paginate-fastapi)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
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
```bash
poetry add paginate-fastapi
```
### Using Pip
```bash
pip install paginate-fastapi
```
## Quick Start
```python
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
```bash
curl -X GET "http://localhost:8000/users/?page=1&page_size=10"
```
```json
{
"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
```bash
# Sort by name ascending
users/?sort_by=name&sort_order=asc
# Sort by age descending
users/?sort_by=age&sort_order=desc
```
### Filtering
```bash
# 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
```bash
# 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
```bash
make test
```
### Code Quality
```bash
# 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](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "paginate-fastapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "fastapi, sqlmodel, pagination, async, filtering, sorting",
"author": "Ritvik Dayal",
"author_email": "ritvikr1605@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a8/26/a5d197f7dc04730e753816439bc1ca649186316dec9904b4d22b741940d7/paginate_fastapi-0.1.0.tar.gz",
"platform": null,
"description": "# Paginate FastAPI\n\n[](https://badge.fury.io/py/paginate-fastapi)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\nA simple and efficient pagination library for FastAPI applications.\n\n## Features\n\n- Easy-to-use pagination with FastAPI\n- Async support out of the box\n- Flexible filtering options\n- Customizable sorting\n- Type-safe with full type hints\n- Compatible with FastAPI\n\n## Installation\n\n### Using Poetry\n```bash\npoetry add paginate-fastapi\n```\n\n### Using Pip\n```bash\npip install paginate-fastapi\n```\n\n## Quick Start\n\n```python\nfrom fastapi import FastAPI, Depends\nfrom sqlmodel import SQLModel, Field\nfrom sqlalchemy.ext.asyncio import AsyncSession, create_async_engine\nfrom pagination import PaginationMiddleware, PaginationParams\n\napp = FastAPI()\n\n# Initialize your database\nengine = create_async_engine(\"sqlite+aiosqlite:///database.db\")\n\nasync def get_session() -> AsyncSession:\n async with AsyncSession(engine) as session:\n yield session\n\npaginator = PaginationMiddleware(get_session)\n\n# Define your model\nclass User(SQLModel, table=True):\n id: int = Field(primary_key=True)\n name: str\n email: str\n age: int\n\n# Add pagination to your endpoint\n@app.get(\"/users/\")\nasync def get_users(\n pagination: PaginationParams = Depends(),\n paginator: PaginationMiddleware = Depends(lambda: paginator),\n):\n return await paginator.paginate(User, pagination)\n```\n\n### Sample Request and Response\n\n```bash\ncurl -X GET \"http://localhost:8000/users/?page=1&page_size=10\"\n```\n\n```json\n{\n \"items\": [\n {\n \"id\": 1,\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"age\": 30\n }\n ],\n \"total\": 100,\n \"page\": 1,\n \"page_size\": 10,\n \"pages\": 10,\n \"has_next\": true,\n \"has_previous\": false\n}\n```\n\n### Sorting\n\n```bash\n# Sort by name ascending\nusers/?sort_by=name&sort_order=asc\n\n# Sort by age descending\nusers/?sort_by=age&sort_order=desc\n```\n\n### Filtering\n\n```bash\n# Filter users by age greater than 30\nusers/?filter_field=age&filter_operator=gt&filter_value=30\n\n# Filter users by name containing \"John\"\nusers/?filter_field=name&filter_operator=like&filter_value=John\n\n# Filter users by age in a list\nusers/?filter_field=age&filter_operator=in&filter_value=[25,30,35]\n```\n\n### Available Filter Operators\n\n- `eq`: Equal to\n- `ne`: Not equal to\n- `gt`: Greater than\n- `lt`: Less than\n- `ge`: Greater than or equal to\n- `le`: Less than or equal to\n- `like`: Contains (case-sensitive)\n- `ilike`: Contains (case-insensitive)\n- `in`: In list of values\n- `not_in`: Not in list of values\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/ritvikdayal/paginate-fastapi.git\ncd paginate-fastapi\n\n# Install dependencies\npoetry install --with dev\n\n# Setup pre-commit hooks (optional)\nmake setup-hooks\n```\n\n### Running Tests\n\n```bash\nmake test\n```\n\n### Code Quality\n\n```bash\n# Run all code quality checks\nmake pre-commit\n\n# Format code only\nmake format\n\n# Run linters only\nmake lint\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple and efficient pagination library for FastAPI applications",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/ritvikdayal/paginate-fastapi#readme",
"Homepage": "https://github.com/ritvikdayal/paginate-fastapi",
"Issues": "https://github.com/ritvikdayal/paginate-fastapi/issues",
"Repository": "https://github.com/ritvikdayal/paginate-fastapi.git"
},
"split_keywords": [
"fastapi",
" sqlmodel",
" pagination",
" async",
" filtering",
" sorting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "44b2bd7d0cdd1ae19335d8646d15a354900e8cd9fb2e85ebc0b56a727ac7e378",
"md5": "ddffda0bf4a531e1847ab44441b1e6d0",
"sha256": "e154d69219e92c9e7e7859575941c72f9b9cceb5a136263ec977ac49ae7bfd95"
},
"downloads": -1,
"filename": "paginate_fastapi-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ddffda0bf4a531e1847ab44441b1e6d0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 7540,
"upload_time": "2025-02-22T12:11:38",
"upload_time_iso_8601": "2025-02-22T12:11:38.963175Z",
"url": "https://files.pythonhosted.org/packages/44/b2/bd7d0cdd1ae19335d8646d15a354900e8cd9fb2e85ebc0b56a727ac7e378/paginate_fastapi-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a826a5d197f7dc04730e753816439bc1ca649186316dec9904b4d22b741940d7",
"md5": "e9602b42261c0ad891414a04f2dd841e",
"sha256": "3e7d86da4e37fb551d0b5bca0c39af06135e3dc471cfada53853c0298049bd3d"
},
"downloads": -1,
"filename": "paginate_fastapi-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e9602b42261c0ad891414a04f2dd841e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 6637,
"upload_time": "2025-02-22T12:11:41",
"upload_time_iso_8601": "2025-02-22T12:11:41.302921Z",
"url": "https://files.pythonhosted.org/packages/a8/26/a5d197f7dc04730e753816439bc1ca649186316dec9904b4d22b741940d7/paginate_fastapi-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-22 12:11:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ritvikdayal",
"github_project": "paginate-fastapi#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "paginate-fastapi"
}
JSON
