fast-pager

Turn your Pydantic models into filterable, sortable, paginated FastAPI query parameters — automatically.

fast-pager reads the Pydantic models you already use in your FastAPI routes and generates type-safe query parameters for filtering, sorting and pagination. Those parameters show up in your OpenAPI docs for free, and compile down to a real database query (MongoDB first, more backends later).

class User(BaseModel):
    name: str
    age: int

@app.get("/users")
async def list_users(q: FilterQuery[User] = FilterDepends(User)):
    return await db.users.find(q.to_mongo()).to_list(None)

A request to:

GET /users?name__contains=ana&age__gte=21&age__lt=65&sort=-age&limit=20

…compiles to:

{"name": {"$regex": "ana"}, "age": {"$gte": 21, "$lt": 65}}
# sort=[("age", -1)], skip=0, limit=20
# (values in `contains` filters are regex-escaped before compilation)

…and every one of those parameters is documented, validated and typed in /docs.

Built with AI

This project is designed and developed with the assistance of AI (Anthropic's Claude Code). Design documents and code are AI-generated and human-reviewed.

Status

fast-pager is under active development. The 0.1.0 release ships Stages 1–2 in full: the zero-config scalar filtering pipeline, Mongo compiler, sorting/pagination, and per-field Filterable(...) control shown above — and the documentation describes exactly the shipped API. The project is still pre-1.0: per SemVer, breaking changes bump the minor version and are called out in release notes. See the changelog for exactly what each version shipped.

Documentation

The full documentation site — getting started, tutorials, operator reference, and the design documents below — lives at fast-pager.eytanohana.com. It's built with Zensical from docs/; see docs/contributing/docs-site.md for how it's configured and how to preview it locally.

Releasing (maintainers)

Releases are fully automated. From a clean main:

./scripts/release.sh patch     # or minor / major

The script bumps the version in pyproject.toml (via uv version --bump), commits, tags v<version>, and pushes. The tag triggers release.yml, which:

1. verifies the tag matches the pyproject.toml version,
2. runs the full CI matrix,
3. builds with uv build and publishes to PyPI via Trusted Publishing (OIDC — no API tokens),
4. creates the GitHub Release with generated notes.

fast_pager.__version__ reads from package metadata, so the version lives in exactly one place.

Design documents

These are the product-design documents the implementation is built from. Read them in order:

Start with 00-overview.md.