Paginator#

Summary#

Classes

AutocompletePaginator(*args, **kwargs)

Paginator that attempts to get as many results as possible from an autocomplete endpoint.

IDPaginator(*args[, ids, ids_per_request])

Paginator for ID-based endpoints that only accept a limited number of IDs per request

IDRangePaginator(*args, **kwargs)

Paginate by a range of IDs instead of standard pagination parameters

JsonIDRangePaginator(request_function, ...)

JsonPaginator(request_function, ...)

JsonPaginatorMixin(request_function, ...)

Paginator mixin that returns raw response dicts instead of model objects

Paginator(request_function, model, *request_args)

Class to handle pagination of API requests, with async support

WrapperPaginator(results, *args, **kwargs)

Paginator class that wraps results that have already been fetched.

Functions

paginate_all(request_function, *args[, method])

Get all pages of a multi-page request.

Module Contents#

Classes to handle pagination of API requests

class pyinaturalist.paginator.AutocompletePaginator(*args, **kwargs)#

Bases: Paginator

Paginator that attempts to get as many results as possible from an autocomplete endpoint. This is necessary for some problematic queries for which there are many matches but not ranked with the desired match(es) first.

This works based on different rankings being returned for order_by=area. No other fields can be sorted on, and direction can’t be specified, but this can at least provide a few additional results beyond the limit of 20.

All results will be de-duplicated and returned as a single page. This may potentially be applied to other autocomplete endpoints, but so far is only needed for places.

all()#

Get all results in a single de-duplicated list

Return type:

List[TypeVar(T, bound= BaseModel)]

class pyinaturalist.paginator.IDPaginator(*args, ids=None, ids_per_request=1, **kwargs)#

Bases: Paginator

Paginator for ID-based endpoints that only accept a limited number of IDs per request

class pyinaturalist.paginator.IDRangePaginator(*args, **kwargs)#

Bases: Paginator

Paginate by a range of IDs instead of standard pagination parameters

Note

Note on pagination by ID, from the iNaturalist documentation:

The large size of the observations index prevents us from supporting the page parameter when retrieving records from large result sets. If you need to retrieve large numbers of records, use the ``per_page`` and ``id_above`` or ``id_below`` parameters instead.

class pyinaturalist.paginator.JsonIDRangePaginator(request_function, *request_args, **kwargs)#

Bases: JsonPaginatorMixin, IDRangePaginator

class pyinaturalist.paginator.JsonPaginator(request_function, *request_args, **kwargs)#

Bases: JsonPaginatorMixin, Paginator

class pyinaturalist.paginator.JsonPaginatorMixin(request_function, *request_args, **kwargs)#

Bases: object

Paginator mixin that returns raw response dicts instead of model objects

all()#
Return type:

Dict[str, Any]

pyinaturalist.paginator.MixinBase#

alias of Paginator

class pyinaturalist.paginator.Paginator(request_function, model, *request_args, limit=None, per_page=None, loop=None, **request_kwargs)#

Bases: Iterable, AsyncIterable, Generic[T]

Class to handle pagination of API requests, with async support

Parameters:

  • request_function (Callable) – API request function to paginate

  • model (Type[TypeVar(T, bound= BaseModel)]) – Model class to use for results

  • limit (Optional[int]) – Maximum number of total results to fetch

  • per_page (Optional[int]) – Maximum number of results to fetch per page

  • loop (Optional[AbstractEventLoop]) – An event loop to use to run any executors used for async iteration

  • kwargs – Original request parameters

all()#

Get all results in a single list

Return type:

List[TypeVar(T, bound= BaseModel)]

async async_all()#

Get all results in a single list (non-blocking)

Return type:

List[TypeVar(T, bound= BaseModel)]

count()#

Get the total number of results for this query, without fetching response data.

Return type:

int

Returns:

Either the total number of results, if the endpoint provides pagination info, or -1

limit(limit)#

Get at most limit results

Return type:

List[TypeVar(T, bound= BaseModel)]

next_page()#

Get the next page of results, as model objects

Return type:

List[TypeVar(T, bound= BaseModel)]

one()#

Get the first result from the query

Return type:

Optional[TypeVar(T, bound= BaseModel)]

class pyinaturalist.paginator.WrapperPaginator(results, *args, **kwargs)#

Bases: Paginator

Paginator class that wraps results that have already been fetched.

count()#

Get the total number of results for this query, without fetching response data.

Return type:

int

Returns:

Either the total number of results, if the endpoint provides pagination info, or -1

next_page()#

Get the next page of results, as model objects

pyinaturalist.paginator.paginate_all(request_function, *args, method='page', **kwargs)#

Get all pages of a multi-page request. Explicit pagination parameters will be overridden.

Return type:

Dict[str, Any]

Returns:

Response dict containing combined results, in the same format as api_func