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.

abstract 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.

abstract 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.

abstract async get_items(cursor: C | None, results_per_page: int) tuple[list[T], Optional[C]]#

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.

abstract async get_total() int#

Return the total number of records.

Returns:

An integer.

abstract 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.

abstract get_total(page_size: int) int#

Return the total number of records.

Parameters:

page_size – Maximal number of records to return.

Returns:

An integer.

abstract 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.

abstract get_items(cursor: C | None, results_per_page: int) tuple[list[T], Optional[C]]#

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.

abstract get_total() int#

Return the total number of records.

Returns:

An integer.

abstract 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: List[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: List[T], limit: int, offset: int, total: int) None#