Unpaginate

Chain calls of paginated APIs

Introduction

API endpoints are often paginated, meaning that you must chain requests to get the content in full. Unpaginate provides a decorator to make that task easy:

>>> from unpaginate import unpaginate

>>> @unpaginate
... def get_cities(pagination, country):
...     return requests.post(
...         "https://api.example.org/cities",
...         json={"country": country, "page": pagination.page},
...     ).json()["items"]

Calling the decorated function allows to iterate over all items of all pages:

>>> iterator = get_cities("France")  # the 'pagination' parameter is added by the decorator
>>> iterator
<generator object get_cities ...>

>>> next(iterator)
'Paris'
>>> next(iterator)
'Lyon'
>>> next(iterator)
'Marseille'

All pagination schemes are supported:

Tip

It's not just API calls! All functions can be decorated with unpaginate!

The requests module is used for illustrative purposes only.

Installation

Install Unpaginate with pip:

$ python -m pip install unpaginate

Python version support

As a general rule, all Python versions that are both released and still officially supported are supported by unpaginate and tested against.

If you have other use cases or find issues with some Python versions, feel free to open a ticket!

Status of the project

Unpaginate is currently in alpha: the API may change in future releases. Changes are well detailed in the changelog, and the version numbering follow semver.