pypaginate.adapters.fastapi

FastAPI integration — Annotated dependency types.

Usage:

from pypaginate.adapters.fastapi import OffsetDep, CursorDep
from pypaginate.adapters.fastapi import FilterDep, FilterField
from pypaginate.adapters.fastapi import SortDep, SearchDep

Submodules

Attributes

`CursorDep`	Annotated type for cursor pagination dependency.
`OffsetDep`	Annotated type for offset pagination dependency.

Classes

`FilterDep`	Base class for declarative filter dependencies.
`SearchDep`	Parse search query parameters into SearchSpec.
`SortDep`	Parse sort query parameter into SortSpec list.

Functions

FilterField(→ Any)

Declare a filter field with operator metadata.

Package Contents

class pypaginate.adapters.fastapi.FilterDep(/, **data: Any)

Bases: pydantic.BaseModel

Base class for declarative filter dependencies.

Subclass this and define fields with FilterField(). Non-None fields are converted to FilterSpec via to_specs(). Pipeline auto-detects this via the to_specs method.

to_specs() → list[pypaginate.domain.specs.FilterSpec]: Convert non-None fields to FilterSpec list.

model_config: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pypaginate.adapters.fastapi.SearchDep(/, **data: Any)

Bases: pydantic.BaseModel

Parse search query parameters into SearchSpec.

Query params: q (search text), search_fields (comma-separated).

to_spec() → pypaginate.domain.specs.SearchSpec | None: Convert to SearchSpec, or None if no query.

model_config: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pypaginate.adapters.fastapi.SortDep(/, **data: Any)

Bases: pydantic.BaseModel

Parse sort query parameter into SortSpec list.

Format: name,-age (comma-separated, - prefix = DESC).

to_specs() → list[pypaginate.domain.specs.SortSpec]: Convert sort string to SortSpec list.

model_config: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pypaginate.adapters.fastapi.FilterField(default: Any = None, *, operator: str = 'eq', field: str | None = None, **kwargs: Any) → Any

Declare a filter field with operator metadata.

Parameters:

default – Default value (None means not applied).
operator – Filter operator name (eq, gte, contains, etc.).
field – Target field name (defaults to the attribute name).

pypaginate.adapters.fastapi.CursorDep

Annotated type for cursor pagination dependency.

Usage:

@app.get("/users/scroll")
async def scroll(params: CursorDep) -> CursorPage[User]:
    return await paginate(query, params, backend=backend)

pypaginate.adapters.fastapi.OffsetDep

Annotated type for offset pagination dependency.

Usage:

@app.get("/users")
async def get_users(params: OffsetDep) -> OffsetPage[User]:
    return paginate(users, params)