Paginate FastAPI
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 tone: Not equal togt: Greater thanlt: Less thange: Greater than or equal tole: Less than or equal tolike: Contains (case-sensitive)ilike: Contains (case-insensitive)in: In list of valuesnot_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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.