Skip to content

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).

Shipped and installable

Everything on this site describes the shipped 0.1.0 API — install it from PyPI and it works as documented. fast-pager is still pre-1.0: per SemVer, breaking changes bump the minor version and are called out in the Changelog.

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.

Why fast-pager

  • Zero-config, safe by default

    Point FilterDepends at a model and get a sensible, safe set of query parameters immediately — no schema duplication, no hand-written filter class. Dangerous operators like regex are opt-in, never free.

  • Honest OpenAPI docs

    Every generated parameter is typed, validated and documented in /docs for free. The docs cannot drift from behavior because both are generated from the same Pydantic model.

  • Progressive disclosure

    Start with zero-config FilterQuery[Model]. Add Annotated[T, Filterable(...)] when you want to curate operators. Graduate to a FilterSet for decoupling and multiple views per model — every path yields the same uniform query object, so call sites never need to change.

  • Backend-agnostic core

    Filtering, sorting and pagination compile to a plain, inspectable AST. Mongo is the first backend adapter; the model→params→AST pipeline itself imports no database code.

  • One convention: field__op

    name__contains=ana, age__gte=21, sort=-age. The Django-style double-underscore convention is familiar, and because the whole parameter surface is pre-generated from the model, there is no request-time string parsing to get wrong.

  • One dependency, one call

    The 80% case is FilterDepends(User) and q.to_mongo(). No ORM, no query DSL to learn — you get back a plain query dict (or an AST, if you want full control).

See it in action

  • Getting Started

    Install fast-pager and wire up your first filterable endpoint.

  • Tutorial

    Learn the field__op convention, then sorting, limit and offset.

  • Operator Reference

    Every scalar type and the operators it exposes, safe vs. full tier.

  • Design Documents

    The full product design this implementation is built from.

Project status

fast-pager is under active development. The 0.1.0 release ships Stages 1–2 in full — zero-config scalar filtering, the Mongo compiler, sorting and pagination, and per-field Filterable(...) control. See the README for the current state and the Changelog for what each version shipped.