paginate-fastapi 0.1.0__py3-none-any.whl

paginate_fastapi-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Ritvik Dayal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

paginate_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+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.
+

paginate_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pagination/__init__.py,sha256=Lr6iRikRx03cnFaV6n5e9s1yDAEOracpxbx6ImOA-v4,827
+pagination/middleware.py,sha256=7PAzExzv55gBrZQORuJJORd1VTas8b-Oed-jm3eLquA,6261
+pagination/models.py,sha256=nSASwuG-rlrti2RWI4Oj6epDiYGV0qCQmcijqGfMRbU,3248
+paginate_fastapi-0.1.0.dist-info/LICENSE,sha256=04BsGfNMsEqA705-GhDsFirDIQyWUiCWJFx0h2ss6yE,1079
+paginate_fastapi-0.1.0.dist-info/METADATA,sha256=TMdNZICsznUU2JXVHSeOeYNg_KTLAqP0TFXnVRR3QeU,5387
+paginate_fastapi-0.1.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+paginate_fastapi-0.1.0.dist-info/RECORD,,

paginate_fastapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pagination/__init__.py

@@ -0,0 +1,31 @@
+"""
+FastAPI SQLModel Pagination Library
+
+A library for adding pagination, filtering, and sorting capabilities
+to FastAPI applications using SQLModel.
+
+Example:
+    from fastapi import FastAPI, Depends
+    from pagination import PaginationMiddleware, PaginationParams
+
+    app = FastAPI()
+    paginator = PaginationMiddleware(get_session)
+
+    @app.get("/items/")
+    async def get_items(
+        pagination: PaginationParams = Depends(),
+        paginator: PaginationMiddleware = Depends(lambda: paginator),
+    ):
+        return await paginator.paginate(Item, pagination)
+"""
+
+from .middleware import PaginationMiddleware
+from .models import FilterOperator, PageResponse, PaginationParams, SortOrder
+
+__all__ = [
+    "FilterOperator",
+    "PageResponse",
+    "PaginationMiddleware",
+    "PaginationParams",
+    "SortOrder",
+]

pagination/middleware.py

@@ -0,0 +1,182 @@
+"""
+Pagination middleware for FastAPI applications.
+
+This module provides the core pagination functionality, including:
+- Async session handling
+- Query building with filters
+- Sorting implementation
+- Pagination calculation
+
+The middleware can be used with any SQLModel-based FastAPI application
+to add pagination, filtering, and sorting capabilities.
+"""
+
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager
+
+from sqlalchemy import asc, desc
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.sql import Select
+from sqlmodel import SQLModel, func, select
+
+from .models import FilterOperator, PageResponse, PaginationParams, SortOrder
+
+
+class PaginationMiddleware:
+    """
+    Middleware for handling pagination in FastAPI applications.
+
+    This class provides methods to paginate SQLModel queries with
+    support for filtering and sorting. It handles both async context
+    managers and async generators for database sessions.
+
+    Attributes:
+        session_maker: Callable that provides database sessions
+        default_page_size: Default number of items per page
+    """
+
+    def __init__(
+        self,
+        session_maker: Callable[[], AsyncSession | AsyncGenerator[AsyncSession, None]],
+        default_page_size: int = 10,
+    ):
+        """
+        Initialize the pagination middleware.
+
+        Args:
+            session_maker: Function that returns a database session
+            default_page_size: Default number of items per page
+        """
+        self.session_maker = session_maker
+        self.default_page_size = default_page_size
+
+    @asynccontextmanager
+    async def get_session(self) -> AsyncGenerator[AsyncSession, None]:
+        """
+        Get a database session using the session maker.
+
+        This method handles both async context managers and async generators,
+        making it compatible with FastAPI dependency injection.
+
+        Yields:
+            AsyncSession: Database session
+        """
+        session_factory = self.session_maker()
+        if hasattr(session_factory, "__aenter__"):
+            async with session_factory as session:
+                yield session
+        else:
+            try:
+                session = await anext(session_factory)
+                yield session
+            finally:
+                try:
+                    await session_factory.aclose()
+                except RuntimeError as ex:
+                    if "already closed" not in str(ex):
+                        raise ex
+
+    def _apply_filter(
+        self, query: Select, model: type[SQLModel], params: PaginationParams
+    ) -> Select:
+        """
+        Apply filter conditions to the query.
+
+        Args:
+            query: Base SQLAlchemy select query
+            model: SQLModel class to query
+            params: Pagination parameters containing filter settings
+
+        Returns:
+            Select: Query with filters applied
+        """
+        if not all([params.filter_field, params.filter_operator, params.filter_value is not None]):
+            return query
+
+        field = getattr(model, params.filter_field)
+
+        filter_map = {
+            FilterOperator.EQ: lambda f, v: f == v,
+            FilterOperator.NEQ: lambda f, v: f != v,
+            FilterOperator.GT: lambda f, v: f > v,
+            FilterOperator.LT: lambda f, v: f < v,
+            FilterOperator.GTE: lambda f, v: f >= v,
+            FilterOperator.LTE: lambda f, v: f <= v,
+            FilterOperator.LIKE: lambda f, v: f.like(f"%{v}%"),
+            FilterOperator.ILIKE: lambda f, v: f.ilike(f"%{v}%"),
+            FilterOperator.IN: lambda f, v: f.in_(v),
+            FilterOperator.NOT_IN: lambda f, v: ~f.in_(v),
+        }
+
+        filter_func = filter_map[params.filter_operator]
+        return query.where(filter_func(field, params.filter_value))
+
+    def _apply_sort(self, query: Select, model: type[SQLModel], params: PaginationParams) -> Select:
+        """
+        Apply sorting to the query.
+
+        Args:
+            query: Base SQLAlchemy select query
+            model: SQLModel class to query
+            params: Pagination parameters containing sort settings
+
+        Returns:
+            Select: Query with sorting applied
+        """
+        if not params.sort_by:
+            return query
+
+        field = getattr(model, params.sort_by)
+        return query.order_by(desc(field) if params.sort_order == SortOrder.DESC else asc(field))
+
+    async def paginate(
+        self, model: type[SQLModel], params: PaginationParams | None = None
+    ) -> PageResponse:
+        """
+        Paginate a SQLModel query with optional filtering and sorting.
+
+        This method handles the complete pagination process:
+        1. Builds the base query
+        2. Applies any filters
+        3. Applies sorting
+        4. Calculates total count
+        5. Applies pagination
+        6. Returns formatted response
+
+        Args:
+            model: SQLModel class to paginate
+            params: Pagination, filtering, and sorting parameters
+
+        Returns:
+            PageResponse: Paginated results with metadata
+        """
+        if params is None:
+            params = PaginationParams(page_size=self.default_page_size)
+
+        async with self.get_session() as session:
+            # Build query
+            query = select(model)
+            query = self._apply_filter(query, model, params)
+            query = self._apply_sort(query, model, params)
+
+            # Get total count
+            count_query = select(func.count()).select_from(query.subquery())
+            total = (await session.execute(count_query)).scalar() or 0
+
+            # Apply pagination
+            query = query.offset(params.offset).limit(params.page_size)
+            result = await session.execute(query)
+            items = result.scalars().all()
+
+            # Calculate pagination metadata
+            pages = (total + params.page_size - 1) // params.page_size if total > 0 else 0
+
+            return PageResponse(
+                items=items,
+                total=total,
+                page=params.page,
+                page_size=params.page_size,
+                pages=pages,
+                has_next=params.page < pages,
+                has_previous=params.page > 1,
+            )

pagination/models.py

@@ -0,0 +1,122 @@
+"""
+Models for the pagination library.
+
+This module contains the core data models used for pagination, filtering, and sorting.
+It defines the parameters that can be used to control pagination behavior and the
+structure of pagination responses.
+"""
+
+from collections.abc import Sequence
+from enum import Enum
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+T = TypeVar("T")
+
+
+class SortOrder(str, Enum):
+    """
+    Enumeration for sort order direction.
+
+    Attributes:
+        ASC: Ascending order (A to Z, 1 to 9)
+        DESC: Descending order (Z to A, 9 to 1)
+    """
+
+    ASC = "asc"
+    DESC = "desc"
+
+
+class FilterOperator(str, Enum):
+    """
+    Enumeration for filter operations.
+
+    Attributes:
+        EQ: Equals (=)
+        NEQ: Not equals (!=)
+        GT: Greater than (>)
+        LT: Less than (<)
+        GTE: Greater than or equal (>=)
+        LTE: Less than or equal (<=)
+        LIKE: SQL LIKE pattern matching
+        ILIKE: Case-insensitive LIKE pattern matching
+        IN: Value in list
+        NOT_IN: Value not in list
+    """
+
+    EQ = "eq"  # equals
+    NEQ = "neq"  # not equals
+    GT = "gt"  # greater than
+    LT = "lt"  # less than
+    GTE = "gte"  # greater than or equal
+    LTE = "lte"  # less than or equal
+    LIKE = "like"  # LIKE operator
+    ILIKE = "ilike"  # ILIKE operator
+    IN = "in"  # IN operator
+    NOT_IN = "not_in"  # NOT IN operator
+
+
+class PaginationParams(BaseModel):
+    """
+    Parameters for pagination, filtering, and sorting.
+
+    This model can be used directly as a FastAPI dependency to receive
+    pagination parameters from query strings.
+
+    Attributes:
+        page: Current page number (1-based)
+        page_size: Number of items per page
+        sort_by: Field name to sort by
+        sort_order: Sort direction (asc/desc)
+        filter_field: Field name to filter on
+        filter_operator: Filter operation to apply
+        filter_value: Value to filter by
+    """
+
+    page: int = Field(default=1, gt=0)
+    page_size: int = Field(default=10, gt=0)
+    sort_by: str | None = None
+    sort_order: SortOrder = SortOrder.ASC
+    filter_field: str | None = None
+    filter_operator: FilterOperator | None = None
+    filter_value: Any | None = None
+
+    model_config = ConfigDict(from_attributes=True)
+
+    @property
+    def offset(self) -> int:
+        """
+        Calculate the SQL offset for the current page.
+
+        Returns:
+            int: Number of items to skip
+        """
+        return (self.page - 1) * self.page_size
+
+
+class PageResponse(BaseModel, Generic[T]):
+    """
+    Generic response model for paginated results.
+
+    Type parameter T represents the model type being paginated.
+
+    Attributes:
+        items: Sequence of items for the current page
+        total: Total number of items across all pages
+        page: Current page number
+        page_size: Number of items per page
+        pages: Total number of pages
+        has_next: Whether there is a next page
+        has_previous: Whether there is a previous page
+    """
+
+    items: Sequence[T]
+    total: int
+    page: int
+    page_size: int
+    pages: int
+    has_next: bool
+    has_previous: bool
+
+    model_config = ConfigDict(from_attributes=True)