fastapi-smart-paginator 0.1.1

Lightweight, zero-config pagination, filtering, and sorting for FastAPI + SQLAlchemy

fastapi-smart-paginator

Lightweight, zero-config pagination, filtering, and sorting for FastAPI + SQLAlchemy.

Unlike heavyweight alternatives, fastapi-smart-paginator works directly with raw SQLAlchemy queries — no magic, no hidden complexity. Just add 3 lines to any endpoint.

Features

• 📄 Pagination — Automatic PK ordering, input validation, size capping
• 🔍 Filtering — 6 comparison operators (eq, ne, gt, gte, lt, lte)
• ↕️ Sorting — Ascending/descending with field validation
• 📦 Pydantic Response Model — PaginatedResponse for auto-generated OpenAPI docs
• ✅ Type-safe — Full type hints with py.typed marker

Installation

pip install fastapi-smart-paginator

Quick Start

from fastapi import FastAPI, Depends, Query
from sqlalchemy.orm import Session

from fastapi_smart_paginator import paginate, apply_filters, apply_sorting, PaginatedResponse

app = FastAPI()

@app.get("/users", response_model=PaginatedResponse)
def list_users(
    page: int = Query(1, ge=1),
    size: int = Query(10, ge=1, le=100),
    sort_by: str | None = None,
    order: str = "asc",
    age__gte: int | None = None,
    db: Session = Depends(get_db),
):
    query = db.query(User)

    # Filter
    filters = {}
    if age__gte is not None:
        filters["age__gte"] = age__gte
    query = apply_filters(query, User, filters)

    # Sort
    query = apply_sorting(query, User, sort_by=sort_by, order=order)

    # Paginate
    return paginate(query, page=page, size=size)

Example Response

{
  "total": 150,
  "page": 2,
  "size": 10,
  "pages": 15,
  "data": [
    {"id": 11, "name": "User 011", "email": "[e-mail]", "age": 31},
    {"id": 12, "name": "User 012", "email": "[e-mail]", "age": 32}
  ]
}

API Reference

paginate(query, page=1, size=10, order_by=None)

Paginate a SQLAlchemy query.

Parameter	Type	Default	Description
query	Query	required	SQLAlchemy query
page	int	1	Page number (1-based, clamped to ≥1)
size	int	10	Items per page (clamped to 1–100)
order_by	ColumnElement | None	None	Custom ordering (auto PK if None)

Returns: PaginatedResponse

apply_filters(query, model, filters)

Apply dynamic filters using field__operator syntax.

apply_filters(query, User, {"age": 25})          # age == 25
apply_filters(query, User, {"age__gte": 18})     # age >= 18
apply_filters(query, User, {"age__lt": 65})      # age < 65
apply_filters(query, User, {"name__ne": "admin"})# name != "admin"

Supported operators: eq (default), ne, gt, gte, lt, lte

apply_sorting(query, model, sort_by=None, order="asc")

Apply sorting to a query. Raises ValueError for invalid order values.

Parameter	Type	Default	Description
sort_by	str | None	None	Column name
order	str	"asc"	"asc" or "desc" (case-insensitive)

PaginatedResponse

Pydantic model for type-safe responses with auto OpenAPI schema.

Roadmap

• created_at default ordering option
• Cursor-based pagination
• Advanced filters (in, like, between)
• Async SQLAlchemy support
• Response serializer hooks

License

MIT