Pagination#

This module contains all code related to automatic pagination.

The pagination module contains the pagination algorithms (both regular and iterative)

that make use of PaginationStrategies.

The preprocess and strategies modules implement the currently supported

PaginationStrategies: LegacyStrategy and ShallowStrategy.

The utils module contains some generic functions that are useful in the context of

pagination.

subgrounds.pagination.paginate(schema, doc, pagination_strategy)#

Evaluates a PaginationStrategy against a document based upon a schema.

Produces a stream of :class:`Document`s until pagination is completed. Documents are

executed outside the this function and data is transfered via the generator scheme.

Parameters:

  • schema (SchemaMeta) -- The GraphQL schema on which the request document is based

  • doc (Document) -- The request document

Returns:

The response data as a JSON dictionary

Return type:

dict[str, Any]

exception subgrounds.pagination.PaginationError(message, strategy)#
class subgrounds.pagination.PaginationNode(node_idx, filter_field, first_value, skip_value, filter_value, filter_value_type, key_path, inner=<factory>)#

Class representing the pagination config for a single GraphQL list field.

node_idx#

Index of PaginationNode, used to label pagination arguments for this node.

Type:

int

filter_field#

Name of the node's filter field, e.g.: if filter_name is timestamp_gt, then filter_field is timestamp

Type:

str

first_value#

Initial value of the first argument

Type:

int

skip_value#

Initial value of the skip argument

Type:

int

filter_value#

Initial value of the filter argument (i.e.: where: {filter: FILTER_VALUE})

Type:

Any

filter_value_type#

Type of the filter value

Type:

subgrounds.schema.TypeRef.T

key_path#

Location in the list field to which this pagination node refers to in the initial query

Type:

list[str]

inner#

Nested pagination nodes (if any).

Type:

list[subgrounds.pagination.preprocess.PaginationNode]

get_vardefs()#

Returns a list of variable definitions corresponding to this pagination node's pagination arguments as well as the variable definitions related to any nested pagination nodes.

Returns:

_description_

Return type:

list[subgrounds.query.VariableDefinition]

class subgrounds.pagination.PaginationStrategy(*args, **kwargs)#
step(page_data=None)#

Returns the new query document and its variables which will be executed to get the next page of data.

If this is the first query made as part of the pagination strategy, then

page_data will be None.

If pagination should be interupted (e.g.: if enough entities have been queried), then this method should raise a StopPagination exception.

Parameters:

page_data (Optional[dict[str, Any]]) -- The previous query's response data. If this is the first query (i.e.: the first page of data), then it will be None. Defaults to None.

Returns:

A tuple (doc, vars) where doc is the query document that will be

executed to fetch the next page of data and vars are the variables for that document.

Return type:

tuple

class subgrounds.pagination.SkipStrategy(schema, document)#
This strategy always raises a SkipPagination

when constructed or if somehow step is called.

This is the default if None is passed to the strategy (default for non-subgraphs).