fastapi-pagination

To implement basic pagination for in-memory data (like lists), follow these steps:

1. Import Page, add_pagination, and paginate from fastapi_pagination.
2. Call add_pagination(app) on your FastAPI application instance to enable pagination support.
3. Use Page[YourModel] as the return type annotation for your endpoint.
4. Call paginate(your_data_list) within the endpoint to return the paginated response.

Warning: Using the default paginate function on database queries will load all data into memory. For database integrations, use the specific extension modules provided by the library.

from fastapi import FastAPI
from pydantic import BaseModel, Field

# import all you need from fastapi-pagination
from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()  # create FastAPI app
add_pagination(app)  # important! add pagination to your app


class UserOut(BaseModel):  # define your model
    name: str = Field(..., example="Steve")
    surname: str = Field(..., example="Rogers")


users = [  # create some data
    UserOut(name="Steve", surname="Rogers"),
    # ...
]


# req: GET /users
@app.get("/users")
async def get_users() -> Page[UserOut]:
    # use Page[UserOut] as return type annotation
    return paginate(users)  # use paginate function to paginate your data

To implement pagination in a FastAPI application, follow these steps:

1. Initialize the plugin: Call add_pagination(app) on your FastAPI application instance. This sets up the necessary dependency injection for pagination parameters.
2. Define your response model: Use the Page[T] generic type from fastapi_pagination as the return type annotation for your endpoint, where T is your schema (e.g., UserOut).
3. Return paginated data: Use the paginate() function to wrap your data source (list, query, etc.).

Example implementation:

from fastapi import FastAPI
from fastapi_pagination import Page, add_pagination, paginate
from pydantic import BaseModel

app = FastAPI()

class UserOut(BaseModel):
    name: str
    email: str

users = [
    UserOut(name="Alice", email="alice@example.com"),
    UserOut(name="Bob", email="bob@example.com"),
]

@app.get("/users", response_model=Page[UserOut])
async def get_users():
    return paginate(users)

add_pagination(app)

To enable pagination in a FastAPI application, you need to perform three main steps:

1. Initialize pagination: Call add_pagination(app) on your FastAPI instance. This automatically handles the dependency injection for pagination parameters (like page and size) for all routes.
2. Annotate return types: Use Page[T] (where T is your data type) as the return type annotation for your route handlers.
3. Paginate data: Use the paginate() function inside your route handler, passing in the collection you want to paginate.

Warning: The paginate() function is designed for data that is already loaded into memory. If you are using a database or an ORM, use the specific pagination methods provided by that database/ORM instead to avoid loading the entire dataset into memory.

from fastapi import FastAPI
from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()
add_pagination(app)

# req: GET /users?page=2&size=10
@app.get("/users")
async def get_users() -> Page[int]:
    return paginate([*range(100)])

You can change the default field names of a Page object during serialization using the UseFieldAliases customizer. This is useful when your API needs to follow a specific naming convention (e.g., changing items to content or size to pageSize).

To implement this, wrap your Page[T] type in a CustomizedPage and pass an instance of UseFieldAliases to it, specifying the mapping for the fields you wish to rename.

Supported fields for aliasing:

• items
• size
• page
• pages
• total

from typing import TypeVar
from fastapi import FastAPI
from fastapi_pagination import Page, add_pagination, paginate
from fastapi_pagination.customization import CustomizedPage, UseFieldsAliases

app = FastAPI()
add_pagination(app)

T = TypeVar("T")

# Define a custom Page type with aliased field names
CustomPage = CustomizedPage[
    Page[T],
    UseFieldsAliases(
        items="content",
        size="pageSize",
        page="pageNumber",
        pages="totalPages",
        total="totalElements",
    ),
]

@app.get("/nums")
async def get_nums() -> CustomPage[int]:
    return paginate(range(1_000))

By default, pagination parameters like size and page might be required depending on your Params class definition. The UseOptionalParams customizer allows you to make these fields optional. This enables users to omit certain parameters (e.g., requesting GET /nums instead of GET /nums?size=5&page=1) to select all available items or use default behaviors when parameters are missing.

from typing import TypeVar

from fastapi import FastAPI
from fastapi_pagination import Page, add_pagination, paginate
from fastapi_pagination.customization import CustomizedPage, UseOptionalParams

app = FastAPI()
add_pagination(app)

T = TypeVar("T")

# Define a CustomPage type using the UseOptionalParams customizer
CustomPage = CustomizedPage[
    Page[T],
    UseOptionalParams()
]

# req: GET /nums?size=5&page=1
# req: GET /nums
@app.get("/nums")
async def get_nums() -> CustomPage[int]:
    return paginate(range(100))

Cursor-Based pagination uses a unique identifier (a cursor) to track the current position in the dataset. This is the most efficient method for large datasets and provides consistent results even if the underlying data changes. However, it is more complex to implement and requires a unique, sequential field to serve as the cursor.

To use it, configure the page type using set_page(CursorPage[T]) and the parameters using set_params(CursorParams(size=N)). When using SQLAlchemy, use the paginate function from fastapi_pagination.ext.sqlalchemy.

from pydantic import BaseModel
from sqlalchemy import create_engine, select
from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column

from fastapi_pagination import set_params, set_page
from fastapi_pagination.cursor import CursorPage, CursorParams
from fastapi_pagination.ext.sqlalchemy import paginate

engine = create_engine("sqlite:///:memory:")

class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)

    name: Mapped[str] = mapped_column()
    age: Mapped[int] = mapped_column()


class UserOut(BaseModel):
    id: int
    name: str
    age: int


with engine.begin() as conn:
    Base.metadata.drop_all(conn)
    Base.metadata.create_all(conn)

with Session(engine) as session:
    session.add_all(
        [
            User(name="John", age=25),
            User(name="Jane", age=30),
            User(name="Bob", age=20),
        ],
    )
    session.commit()

set_page(CursorPage[UserOut])
set_params(CursorParams(size=10))

page = paginate(session, select(User).order_by(User.id))
print(page.model_dump_json(indent=4))