Metadata-Version: 2.3
Name: paginate-fastapi
Version: 0.1.0
Summary: A simple and efficient pagination library for FastAPI applications
License: MIT
Keywords: fastapi,sqlmodel,pagination,async,filtering,sorting
Author: Ritvik Dayal
Author-email: ritvikr1605@gmail.com
Requires-Python: >=3.11
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: dev
Requires-Dist: aiosqlite (>=0.20.0) ; extra == "dev"
Requires-Dist: black (>=24.1.0) ; extra == "dev"
Requires-Dist: fastapi (>=0.100.0)
Requires-Dist: fastapi[all] (>=0.100.0) ; extra == "dev"
Requires-Dist: httpx (>=0.27.0) ; extra == "dev"
Requires-Dist: mypy (>=1.8.0) ; extra == "dev"
Requires-Dist: pre-commit (>=4.1.0,<5.0.0)
Requires-Dist: pydantic (>=2.0.0)
Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
Requires-Dist: pytest-asyncio (>=0.23.0) ; extra == "dev"
Requires-Dist: pytest-cov (>=4.1.0) ; extra == "dev"
Requires-Dist: ruff (>=0.9.7,<0.10.0) ; extra == "dev"
Requires-Dist: sqlmodel (>=0.0.8)
Project-URL: Documentation, https://github.com/ritvikdayal/paginate-fastapi#readme
Project-URL: Homepage, https://github.com/ritvikdayal/paginate-fastapi
Project-URL: Issues, https://github.com/ritvikdayal/paginate-fastapi/issues
Project-URL: Repository, https://github.com/ritvikdayal/paginate-fastapi.git
Description-Content-Type: text/markdown

# Paginate FastAPI

[![PyPI version](https://badge.fury.io/py/paginate-fastapi.svg)](https://badge.fury.io/py/paginate-fastapi)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](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.

