starlette_jsonapi.pagination module

class starlette_jsonapi.pagination.BasePagination(request, data, **kwargs)

Bases: object

Base class used to easily add pagination support for resources. This class is agnostic about the pagination strategy, and can be effectively subclassed to accommodate for any variant.

Implementation will require overriding the following methods:

Parameters

  • request (Request) –

  • data (Sequence) –

__init__(request, data, **kwargs)

Constructs a paginator object with Starlette support.

Parameters

  • request (Request) –

  • data (Sequence) –

data

Data before pagination

request

The Starlette HTTP request object

process_query_params()

Parse the request to store the pagination parameters for later usage. Should be implemented in subclasses.

slice_data(params=None)

This method should be implemented in subclasses in order to accommodate for different ORM’s and optimize database operations.

Parameters

params (Optional[dict]) –

Return type

Sequence

get_pagination(params=None)

Slice the queryset according to the pagination rules, and create pagination links

Parameters

params (Optional[dict]) –

Return type

Pagination

Create a dict of pagination helper links

Parameters

params (Optional[dict]) –

Return type

Dict[str, Optional[str]]

class starlette_jsonapi.pagination.BasePageNumberPagination(*args, **kwargs)

Bases: BasePagination

Base class for accommodating the page number pagination strategy using the standard parameters under the JSON:API format:

  • page[number]

  • page[size]

Implementation will require overriding the following methods:

page_number_param = 'page[number]'

The query parameter corresponding to the page number.

page_size_param = 'page[size]'

The query parameter corresponding to the page size.

default_page_number = 1

The default page number. Used if no client configured value is found.

default_page_size = 50

The default page size. Used if no client configured value is found.

max_page_size = 100

The maximum allowed page size. Can override client configured values.

__init__(*args, **kwargs)
page_size

Processed page size, initially default_page_size

page_number

Processed page number, initially default_page_number

process_query_params()

Process HTTP query parameters to set page_number and page_size.

Helper method used to easily generate a link with pagination details for this strategy.

Parameters

  • page_number (int) –

  • page_size (int) –

Return type

str

Create a dict of pagination helper links

Parameters

params (Optional[dict]) –

Return type

Dict[str, Optional[str]]

get_pagination(params=None)

Slice the queryset according to the pagination rules, and create pagination links

Parameters

params (Optional[dict]) –

Return type

Pagination

slice_data(params=None)

This method should be implemented in subclasses in order to accommodate for different ORM’s and optimize database operations.

Parameters

params (Optional[dict]) –

Return type

Sequence

data

Data before pagination

request

The Starlette HTTP request object

class starlette_jsonapi.pagination.BaseOffsetPagination(*args, **kwargs)

Bases: BasePagination

Base class for accommodating the offset pagination strategy using the standard parameters under the JSON:API format

  • page[offset]

  • page[size]

Implementation will require overriding the following methods:

page_offset_param = 'page[offset]'

The query parameter corresponding to the page offset.

page_size_param = 'page[size]'

The query parameter corresponding to the page size.

default_page_offset = 0

The default page offset. Used if no client configured value is found.

default_page_size = 50

The default page size. Used if no client configured value is found.

max_page_size = 100

The maximum allowed page size. Can override client configured values.

__init__(*args, **kwargs)
page_size

Processed page size, initially default_page_size

page_offset

Processed page offset, initially default_page_offset

process_query_params()

Process HTTP query parameters to set page_offset and page_size.

Helper method used to easily generate a link with pagination details for this strategy.

Parameters

  • page_offset (int) –

  • page_size (int) –

Return type

str

Create a dict of pagination helper links

Parameters

params (Optional[dict]) –

Return type

Dict[str, Optional[str]]

get_pagination(params=None)

Slice the queryset according to the pagination rules, and create pagination links

Parameters

params (Optional[dict]) –

Return type

Pagination

slice_data(params=None)

This method should be implemented in subclasses in order to accommodate for different ORM’s and optimize database operations.

Parameters

params (Optional[dict]) –

Return type

Sequence

data

Data before pagination

request

The Starlette HTTP request object

class starlette_jsonapi.pagination.BaseCursorPagination(*args, **kwargs)

Bases: BasePagination

Base class for accommodating the cursor pagination strategy using the standard parameters under the JSON:API format

  • page[after]

  • page[before]

  • page[size]

Implementation will require overriding the following methods:

page_after_param = 'page[after]'

The query parameter corresponding to the page after.

page_before_param = 'page[before]'

The query parameter corresponding to the page before.

page_size_param = 'page[size]'

The query parameter corresponding to the page size.

default_page_after = 0

The default page after. Used if no client configured value is found.

default_page_before = None

The default page before. Used if no client configured value is found.

default_page_size = 50

The default page size. Used if no client configured value is found.

max_page_size = 100

The maximum allowed page size. Can override client configured values.

__init__(*args, **kwargs)
page_size

Processed page size, initially default_page_size

page_after

Processed page after, initially default_page_after

page_before

Processed page before, initially default_page_before

process_query_params()

Process HTTP query parameters to set page_after, page_before and page_size.

Helper method used to easily generate a link with pagination details for this strategy.

Parameters

  • page_size (int) –

  • page_after (Optional[Union[str, int]]) –

  • page_before (Optional[Union[str, int]]) –

Return type

str

Create a dict of pagination helper links

Parameters

params (Optional[dict]) –

Return type

Dict[str, Optional[str]]

get_pagination(params=None)

Slice the queryset according to the pagination rules, and create pagination links

Parameters

params (Optional[dict]) –

Return type

Pagination

slice_data(params=None)

This method should be implemented in subclasses in order to accommodate for different ORM’s and optimize database operations.

Parameters

params (Optional[dict]) –

Return type

Sequence

data

Data before pagination

request

The Starlette HTTP request object

class starlette_jsonapi.pagination.Pagination(data, links)

Bases: tuple

Represents the result of a pagination strategy.

Parameters

  • data (Sequence) –

  • links (Dict[str, Optional[str]]) –

property data

Sequence of items representing a single page

Dictionary of pagination links