Skip to main content

pypaginate.adapters.fastapi.dependencies

FastAPI pagination dependencies — parse query params into pypaginate specs.

These are plain FastAPI dependency callables (and ready-made Annotated aliases) that turn the request query string into the package's flat dataclasses::

from pypaginate.adapters.fastapi import OffsetDep, SortDep, SearchDep

@app.get("/users") def list_users(params: OffsetDep, sort: SortDep, search: SearchDep): ...

Invalid page/limit/cursor combinations are reported as HTTP 422 responses.

offset_params​

def offset_params(
    page: Annotated[int, Query(ge=1, description="1-based page number")] = 1,
    limit: Annotated[int,
                     Query(ge=1, le=MAX_LIMIT, description="Page size")] = 20
) -> OffsetParams

Resolve offset params (?page=&limit=) from the request query.

cursor_params​

def cursor_params(
    limit: Annotated[int,
                     Query(ge=1, le=MAX_LIMIT, description="Page size")] = 20,
    after: Annotated[str | None,
                     Query(description="Cursor to page forward")] = None,
    before: Annotated[str | None,
                      Query(description="Cursor to page backward")] = None
) -> CursorParams

Resolve cursor params (?limit=&after=&before=) from the request query.

parse_sort​

def parse_sort(value: str | None) -> list[SortSpec]

Parse a name,-age sort string into an ordered SortSpec list.

sort_params​

def sort_params(
    sort: Annotated[
        str | None,
        Query(
            description="Comma-separated sort keys; '-' prefix = descending"),
    ] = None
) -> list[SortSpec]

Resolve sort keys (?sort=name,-age) into a SortSpec list.

def parse_search(query: str | None, fields_csv: str) -> SearchSpec | None

Parse a query plus comma-separated fields into a SearchSpec (or None).

search_params​

def search_params(
    q: Annotated[str | None,
                 Query(description="Free-text search query")] = None,
    search_fields: Annotated[
        str, Query(description="Comma-separated search fields")] = ""
) -> SearchSpec | None

Resolve search params (?q=&search_fields=) into a SearchSpec.