pagination

class litestar.pagination.AbstractAsyncClassicPaginator

Bases: ABC, Generic[T]

Base paginator class for async classic pagination.

Implement this class to return paginated result sets using the classic pagination scheme.

abstractmethod async get_total(page_size: int) → int

Return the total number of records.

Parameters:

page_size – Maximal number of records to return.

Returns:

An integer.

abstractmethod async get_items(page_size: int, current_page: int) → list[T]

Return a list of items of the given size ‘page_size’ correlating with ‘current_page’.

Parameters:

• page_size – Maximal number of records to return.

• current_page – The current page of results to return.

Returns:

A list of items.

async __call__(page_size: int, current_page: int) → ClassicPagination[T]

Return a paginated result set.

Parameters:

• page_size – Maximal number of records to return.

• current_page – The current page of results to return.

Returns:

A paginated result set.

class litestar.pagination.AbstractAsyncCursorPaginator

Bases: ABC, Generic[C, T]

Base paginator class for async cursor pagination.

Implement this class to return paginated result sets using the cursor pagination scheme.

abstractmethod async get_items(cursor: C | None, results_per_page: int) → tuple[list[T], C | None]

Return a list of items of the size ‘results_per_page’ following the given cursor, if any,

Parameters:

• cursor – A unique identifier that acts as the ‘cursor’ after which results should be given.

• results_per_page – A maximal number of results to return.

Returns:

A tuple containing the result set and a new cursor that marks the last record retrieved. The new cursor can be used to ask for the ‘next_cursor’ batch of results.

async __call__(cursor: C | None, results_per_page: int) → CursorPagination[C, T]

Return a paginated result set given an optional cursor (unique ID) and a maximal number of results to return.

Parameters:

• cursor – A unique identifier that acts as the ‘cursor’ after which results should be given.

• results_per_page – A maximal number of results to return.

Returns:

A paginated result set.

class litestar.pagination.AbstractAsyncOffsetPaginator

Bases: ABC, Generic[T]

Base paginator class for limit / offset pagination.

Implement this class to return paginated result sets using the limit / offset pagination scheme.

abstractmethod async get_total() → int

Return the total number of records.

Returns:

An integer.

abstractmethod async get_items(limit: int, offset: int) → list[T]

Return a list of items of the given size ‘limit’ starting from position ‘offset’.

Parameters:

• limit – Maximal number of records to return.

• offset – Starting position within the result set (assume index 0 as starting position).

Returns:

A list of items.

async __call__(limit: int, offset: int) → OffsetPagination[T]

Return a paginated result set.

Parameters:

• limit – Maximal number of records to return.

• offset – Starting position within the result set (assume index 0 as starting position).

Returns:

A paginated result set.

class litestar.pagination.AbstractSyncClassicPaginator

Bases: ABC, Generic[T]

Base paginator class for sync classic pagination.

Implement this class to return paginated result sets using the classic pagination scheme.

abstractmethod get_total(page_size: int) → int

Return the total number of records.

Parameters:

page_size – Maximal number of records to return.

Returns:

An integer.

abstractmethod get_items(page_size: int, current_page: int) → list[T]

Return a list of items of the given size ‘page_size’ correlating with ‘current_page’.

Parameters:

• page_size – Maximal number of records to return.

• current_page – The current page of results to return.

Returns:

A list of items.

__call__(page_size: int, current_page: int) → ClassicPagination[T]

Return a paginated result set.

Parameters:

• page_size – Maximal number of records to return.

• current_page – The current page of results to return.

Returns:

A paginated result set.

class litestar.pagination.AbstractSyncCursorPaginator

Bases: ABC, Generic[C, T]

Base paginator class for sync cursor pagination.

Implement this class to return paginated result sets using the cursor pagination scheme.

abstractmethod get_items(cursor: C | None, results_per_page: int) → tuple[list[T], C | None]

Return a list of items of the size ‘results_per_page’ following the given cursor, if any,

Parameters:

• cursor – A unique identifier that acts as the ‘cursor’ after which results should be given.

• results_per_page – A maximal number of results to return.

Returns:

A tuple containing the result set and a new cursor that marks the last record retrieved. The new cursor can be used to ask for the ‘next_cursor’ batch of results.

__call__(cursor: C | None, results_per_page: int) → CursorPagination[C, T]

Return a paginated result set given an optional cursor (unique ID) and a maximal number of results to return.

Parameters:

• cursor – A unique identifier that acts as the ‘cursor’ after which results should be given.

• results_per_page – A maximal number of results to return.

Returns:

A paginated result set.

class litestar.pagination.AbstractSyncOffsetPaginator

Bases: ABC, Generic[T]

Base paginator class for limit / offset pagination.

Implement this class to return paginated result sets using the limit / offset pagination scheme.

abstractmethod get_total() → int

Return the total number of records.

Returns:

An integer.

abstractmethod get_items(limit: int, offset: int) → list[T]

Return a list of items of the given size ‘limit’ starting from position ‘offset’.

Parameters:

• limit – Maximal number of records to return.

• offset – Starting position within the result set (assume index 0 as starting position).

Returns:

A list of items.

__call__(limit: int, offset: int) → OffsetPagination[T]

Return a paginated result set.

Parameters:

• limit – Maximal number of records to return.

• offset – Starting position within the result set (assume index 0 as starting position).

Returns:

A paginated result set.

class litestar.pagination.ClassicPagination

Bases: Generic[T]

Container for data returned using limit/offset pagination.

items: list[T]

List of data being sent as part of the response.

page_size: int

Number of items per page.

current_page: int

Current page number.

total_pages: int

Total number of pages.

__init__(items: list[T], page_size: int, current_page: int, total_pages: int) → None

class litestar.pagination.CursorPagination

Bases: Generic[C, T]

Container for data returned using cursor pagination.

items: list[T]

List of data being sent as part of the response.

results_per_page: int

Maximal number of items to send.

cursor: C | None

Unique ID, designating the last identifier in the given data set.

This value can be used to request the “next” batch of records.

__init__(items: list[T], results_per_page: int, cursor: C | None) → None

class litestar.pagination.OffsetPagination

Bases: Generic[T]

Container for data returned using limit/offset pagination.

items: Sequence[T]

List of data being sent as part of the response.

limit: int

Maximal number of items to send.

offset: int

Offset from the beginning of the query.

Identical to an index.

total: int

Total number of items.

__init__(items: Sequence[T], limit: int, offset: int, total: int) → None