Skip to content

Paginated Module Reference

Deprecated

The fastcrud.paginated module is deprecated as of version 0.18.0 and will be removed in the next major version. Please import pagination utilities directly from fastcrud instead:

# Old (deprecated)
from fastcrud.paginated import PaginatedListResponse, PaginatedRequestQuery

# New (recommended)
from fastcrud import PaginatedListResponse, PaginatedRequestQuery

paginated is a utility module for offset pagination related functions. The functionality has been moved to the core module for better organization.

Core Pagination Module

The pagination utilities are now consolidated in a single core module:

Pagination Module

Pagination utilities for FastCRUD.

This module consolidates all pagination-related functionality including: - Pagination parameter schemas - Pagination response formatting - Offset calculation helpers - Dynamic response model creation

CursorPaginatedRequestQuery

Bases: BaseModel

Pydantic model for cursor-based pagination query parameters.

This model encapsulates all query parameters used for cursor-based pagination in endpoints. It can be used with FastAPI's Depends() to inject these parameters into endpoints, making it easy to reuse in custom endpoints.

Cursor-based pagination is ideal for large datasets and infinite scrolling features, as it provides consistent results even when data is being modified.

Attributes:

Name Type Description
cursor Optional[int]

Cursor value for pagination (typically the ID of the last item from previous page)
limit Optional[int]

Maximum number of items to return per page
sort_column Optional[str]

Column name to sort by (defaults to 'id')
sort_order Optional[str]

Sort order, either 'asc' or 'desc' (defaults to 'asc')
Example 
from typing import Annotated
from fastapi import Depends
from fastcrud import CursorPaginatedRequestQuery

async def custom_cursor_endpoint(
    query: Annotated[CursorPaginatedRequestQuery, Depends()]
):
    # Use query.cursor, query.limit, query.sort_column, query.sort_order
    pass
Source code in fastcrud/core/pagination.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
class CursorPaginatedRequestQuery(BaseModel):
    """
    Pydantic model for cursor-based pagination query parameters.

    This model encapsulates all query parameters used for cursor-based pagination
    in endpoints. It can be used with FastAPI's Depends() to inject these parameters
    into endpoints, making it easy to reuse in custom endpoints.

    Cursor-based pagination is ideal for large datasets and infinite scrolling
    features, as it provides consistent results even when data is being modified.

    Attributes:
        cursor: Cursor value for pagination (typically the ID of the last item from previous page)
        limit: Maximum number of items to return per page
        sort_column: Column name to sort by (defaults to 'id')
        sort_order: Sort order, either 'asc' or 'desc' (defaults to 'asc')

    Example:
        ```python
        from typing import Annotated
        from fastapi import Depends
        from fastcrud import CursorPaginatedRequestQuery

        async def custom_cursor_endpoint(
            query: Annotated[CursorPaginatedRequestQuery, Depends()]
        ):
            # Use query.cursor, query.limit, query.sort_column, query.sort_order
            pass
        ```
    """

    cursor: Optional[int] = Field(
        None,
        description="Cursor value for pagination (typically the ID of the last item from previous page)",
    )
    limit: Optional[int] = Field(
        100, description="Maximum number of items to return per page", gt=0, le=1000
    )
    sort_column: Optional[str] = Field("id", description="Column name to sort by")
    sort_order: Optional[str] = Field(
        "asc",
        description="Sort order: 'asc' for ascending, 'desc' for descending",
        pattern="^(asc|desc)$",
    )

    model_config = {"populate_by_name": True}

PaginatedRequestQuery

Bases: BaseModel

Pydantic model for paginated query parameters.

This model encapsulates all query parameters used for pagination and sorting in read_items endpoints. It can be used with FastAPI's Depends() to inject these parameters into endpoints, making it easy to reuse in custom endpoints.

Supports two pagination modes: - Page-based: Using 'page' and 'items_per_page' (or 'itemsPerPage' alias) - Offset-based: Using 'offset' and 'limit'

Attributes:

Name Type Description
offset Optional[int]

Offset for unpaginated queries (used with limit)
limit Optional[int]

Limit for unpaginated queries (used with offset)
page Optional[int]

Page number for paginated queries
items_per_page Optional[int]

Number of items per page for paginated queries
sort Optional[str]

Sort results by one or more fields. Format: 'field1,-field2' where '-' prefix indicates descending order. Example: 'name' (ascending), '-age' (descending), 'name,-age' (name ascending, then age descending).
Example 
from typing import Annotated
from fastapi import Depends
from fastcrud import PaginatedRequestQuery

async def custom_endpoint(
    query: Annotated[PaginatedRequestQuery, Depends()]
):
    # Use query.page, query.items_per_page, query.sort, etc.
    pass
Source code in fastcrud/core/pagination.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
class PaginatedRequestQuery(BaseModel):
    """
    Pydantic model for paginated query parameters.

    This model encapsulates all query parameters used for pagination and sorting
    in read_items endpoints. It can be used with FastAPI's Depends() to inject
    these parameters into endpoints, making it easy to reuse in custom endpoints.

    Supports two pagination modes:
    - Page-based: Using 'page' and 'items_per_page' (or 'itemsPerPage' alias)
    - Offset-based: Using 'offset' and 'limit'

    Attributes:
        offset: Offset for unpaginated queries (used with limit)
        limit: Limit for unpaginated queries (used with offset)
        page: Page number for paginated queries
        items_per_page: Number of items per page for paginated queries
        sort: Sort results by one or more fields. Format: 'field1,-field2' where '-' prefix
              indicates descending order. Example: 'name' (ascending), '-age' (descending),
              'name,-age' (name ascending, then age descending).

    Example:
        ```python
        from typing import Annotated
        from fastapi import Depends
        from fastcrud import PaginatedRequestQuery

        async def custom_endpoint(
            query: Annotated[PaginatedRequestQuery, Depends()]
        ):
            # Use query.page, query.items_per_page, query.sort, etc.
            pass
        ```
    """

    offset: Optional[int] = Field(None, description="Offset for unpaginated queries")
    limit: Optional[int] = Field(None, description="Limit for unpaginated queries")
    page: Optional[int] = Field(None, alias="page", description="Page number")
    items_per_page: Optional[int] = Field(
        None, alias="itemsPerPage", description="Number of items per page"
    )
    sort: Optional[str] = Field(
        None,
        description="Sort results by one or more fields. Format: 'field1,-field2' where '-' prefix indicates descending order. Example: 'name' (ascending), '-age' (descending), 'name,-age' (name ascending, then age descending).",
    )

    model_config = {"populate_by_name": True}

compute_offset(page, items_per_page)

Calculate the offset for pagination based on the given page number and items per page.

The offset represents the starting point in a dataset for the items on a given page. For example, if each page displays 10 items and you want to display page 3, the offset will be 20, meaning the display should start with the 21st item.

Parameters:

Name Type Description Default
page int

The current page number. Page numbers should start from 1.

 required
items_per_page int

The number of items to be displayed on each page.

 required

Returns:

Type Description
int

The calculated offset.

Examples:

>>> compute_offset(1, 10)
0
>>> compute_offset(3, 10)
20
Source code in fastcrud/core/pagination.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def compute_offset(page: int, items_per_page: int) -> int:
    """Calculate the offset for pagination based on the given page number and items per page.

    The offset represents the starting point in a dataset for the items on a given page.
    For example, if each page displays 10 items and you want to display page 3, the offset will be 20,
    meaning the display should start with the 21st item.

    Args:
        page: The current page number. Page numbers should start from 1.
        items_per_page: The number of items to be displayed on each page.

    Returns:
        The calculated offset.

    Examples:
        >>> compute_offset(1, 10)
        0
        >>> compute_offset(3, 10)
        20
    """
    return (page - 1) * items_per_page

create_list_response(schema, response_key='data')

Creates a dynamic ListResponse model with the specified response key.

Source code in fastcrud/core/pagination.py 
175
176
177
178
179
def create_list_response(
    schema: Type[SchemaType], response_key: str = "data"
) -> Type[BaseModel]:
    """Creates a dynamic ListResponse model with the specified response key."""
    return create_model("DynamicListResponse", **{response_key: (list[schema], ...)})  # type: ignore

create_paginated_response(schema, response_key='data')

Creates a dynamic PaginatedResponse model with the specified response key.

Source code in fastcrud/core/pagination.py 
182
183
184
185
186
187
188
189
190
191
192
193
def create_paginated_response(
    schema: Type[SchemaType], response_key: str = "data"
) -> Type[BaseModel]:
    """Creates a dynamic PaginatedResponse model with the specified response key."""
    fields = {
        response_key: (list[schema], ...),  # type: ignore
        "total_count": (int, ...),
        "has_more": (bool, ...),
        "page": (Optional[int], None),
        "items_per_page": (Optional[int], None),
    }
    return create_model("DynamicPaginatedResponse", **fields)  # type: ignore

paginated_response(crud_data, page, items_per_page, multi_response_key='data')

Create a paginated response based on the provided data and pagination parameters.

Parameters:

Name Type Description Default
crud_data dict

Data to be paginated, including the list of items and total count.

 required
page int

Current page number.

 required
items_per_page int

Number of items per page.

 required
multi_response_key str

Key to use for the items list in the response (defaults to "data").

 'data'

Returns:

Type Description
dict[str, Any]

A structured paginated response dict containing the list of items, total count, pagination flags, and numbers.
Note

The function does not actually paginate the data but formats the response to indicate pagination metadata.

Source code in fastcrud/core/pagination.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def paginated_response(
    crud_data: dict,
    page: int,
    items_per_page: int,
    multi_response_key: str = "data",
) -> dict[str, Any]:
    """Create a paginated response based on the provided data and pagination parameters.

    Args:
        crud_data: Data to be paginated, including the list of items and total count.
        page: Current page number.
        items_per_page: Number of items per page.
        multi_response_key: Key to use for the items list in the response (defaults to "data").

    Returns:
        A structured paginated response dict containing the list of items, total count, pagination flags, and numbers.

    Note:
        The function does not actually paginate the data but formats the response to indicate pagination metadata.
    """
    items = crud_data.get(multi_response_key, [])
    total_count = crud_data.get("total_count", 0)

    response = {
        multi_response_key: items,
        "total_count": total_count,
        "has_more": (page * items_per_page) < total_count,
        "page": page,
        "items_per_page": items_per_page,
    }

    return response

Backward Compatibility

For backward compatibility, the original imports still work but will issue deprecation warnings:

Backward compatibility module for paginated utilities.

.. deprecated:: 0.19.0 The fastcrud.paginated module is deprecated and will be removed in the next major version. Please import pagination utilities directly from fastcrud instead:

.. code-block:: python

   # Old (deprecated)
   from fastcrud.paginated import PaginatedListResponse, PaginatedRequestQuery

   # New (recommended)
   from fastcrud import PaginatedListResponse, PaginatedRequestQuery