Old way of customization

Old way of customizing pagination

Page.with_custom_options and Page.with_params methods are now deprecated. They will be removed in the next major release.

Please use CustomizedPage instead.

To customize pagination, you should use new CustomizedPage annotated-like class. It allows you to change default pagination in mypy compatible way.

The main issue with old Page.with_custom_options and Page.with_params methods was that they were not mypy compatible. It means that you could not use them with mypy type checking, because they return new class objects and mypy does not support such ways.

Customization

First, let's import all necessary components:

from typing import Optional, TypeVar

from fastapi_pagination import Page, Params
from fastapi_pagination.customization import (
    CustomizedPage,
    UseAdditionalFields,
    UseExcludedFields,
    UseFieldsAliases,
    UseIncludeTotal,
    UseModelConfig,
    UseName,
    UseOptionalParams,
    UseParams,
    UseParamsFields,
)

T = TypeVar("T")

Now we can customize our page.

Change name

If you want to change default name of page class, you should use UseName customizer:

IntPage = CustomizedPage[
    Page[int],
    UseName("IntPage"),  # (1)
]

Now your class will be names 'IntPage' instead of 'CustomizedPage'.

Note

Everytime you customize page, name of the class will be changed to your-class-name + "Customized". In order to change it, you should use UseName customizer.

Change total behavior

By default, cursor-based page don't include total count of items, and offset-based page include it. If you want to change this behavior, you should use UseIncludeTotal customizer:

PageNoTotal = CustomizedPage[
    Page[T],
    UseIncludeTotal(False),  # (1)
]

Now when you will paginate using PageNoTotal class, it will not include total count of items.

Change params default values

If you want to change default values of pagination parameters, you should use UseParamsFields customizer:

BigPage = CustomizedPage[
    Page[T],
    UseParamsFields(size=500),  # (1)
]

Now when size parameter is not provided, it will be equal to 500.

Make params fields optional

If you want to change type of pagination parameters, you should use UseParams customizer:

PageOptionalParams = CustomizedPage[
    Page[T],
    UseOptionalParams(),  # (1)
]

Now all pagination parameters will be optional.

Change fields names

If you want use another name of field rather than default, you should use UseFieldsAliases customizer:

PageWithCount = CustomizedPage[
    Page[T],
    UseFieldsAliases(total="count"),  # (1)
]

Now total field will be serialized as count.

Exclude fields

If you want to exclude some fields from serialization, you should use UseExcludedFields customizer:

PageWithoutTotal = CustomizedPage[
    Page[T],
    UseExcludedFields("total"),  # (1)
]

Now total field will not be serialized.

Change pydantic model config

If you want to change pydantic model config, you should use UseModelConfig customizer:

PageStrLower = CustomizedPage[
    Page[T],
    UseModelConfig(anystr_lower=True),  # (1)
]

Now Page class will have anystr_lower set to True.

Change page params type

If you want to change type of page parameters, you should use UseParams customizer:

class MyParams(Params): ...  # your magic here


PageWithMyParams = CustomizedPage[
    Page[T],
    UseParams(MyParams),  # (1)
]

Now Page.__params_type__ attribute will be point to MyParams class.

Combine multiple customizers

You can use multiple customizers at once, just pass them as to regular Annotated:

CustomPage = CustomizedPage[
    Page[T],
    UseName("CustomPage"),
    UseIncludeTotal(False),
    UseOptionalParams(),
]  # (1)

Now CustomPage will have CustomPage name, no total count of items, all params optional.