pypaginate
Advanced pagination, filtering, and search toolkit for Python
Get Started in 5 Minutes
Install pypaginate and optional dependencies for your use case.
uv add pypaginate[all]
Learn the basics with our step-by-step quickstart guide.
Build your first paginated API with FastAPI and SQLAlchemy.
Why pypaginate?
Offset-based pagination (page/limit)
Cursor-based (keyset) for large datasets
In-memory for Python collections
20 operators (eq, gte, contains, between, regex, etc.)
Dot notation for nested fields
Type-safe with mypy strict
Full-text with fuzzy matching
Accent-insensitive search
SQL and in-memory engines
Multi-column sorting
Custom sort key functions
Bidirectional support
Native FastAPI support
SQLAlchemy 2.0+ (async/sync)
Framework-agnostic core
100% type coverage
90%+ test coverage
Clean architecture
Quick Example
from pypaginate import paginate, OffsetParams
from pypaginate.adapters.sqlalchemy import SQLAlchemyBackend
from sqlalchemy import select
async def list_users(session, page: int = 1, limit: int = 20):
params = OffsetParams(page=page, limit=limit)
stmt = select(User).order_by(User.created_at.desc())
backend = SQLAlchemyBackend(session)
page = await paginate(stmt, params, backend=backend)
return {
"items": page.items,
"total": page.total,
"page": page.page,
"pages": page.pages,
}
from pypaginate import paginate, OffsetParams
users = [
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25},
{"name": "Charlie", "age": 35},
]
page = paginate(users, OffsetParams(page=1, limit=2))
print(page.items) # [Alice, Bob]
print(page.total) # 3
from pypaginate import FilterSpec, And
from pypaginate.filtering import FilterEngine
engine = FilterEngine()
users = [
{"name": "Alice", "age": 30, "status": "active"},
{"name": "Bob", "age": 25, "status": "inactive"},
{"name": "Charlie", "age": 35, "status": "active"},
]
# Filter for active users aged 30+
filtered = engine.apply(users, And(
FilterSpec(field="age", operator="gte", value=30),
FilterSpec(field="status", value="active"),
))
# Result: [Alice, Charlie]
Learn More
Learn offset, cursor, and in-memory pagination strategies.
Filter data with 20 typed operators and nested And/Or groups.
Add full-text and fuzzy search capabilities.
Complete API documentation.