README.md

Pluvo Python

Python library to access the Pluvo REST API.

Authentication using client credentials

To access the methods that need authentication with client credentials, for instance getting data for a specific user:

from pluvo import Pluvo

pluvo = Pluvo(client_id='client_id', client_secret='client_secret')

user = pluvo.get_user(1)

Authentication using token

To access methods that need a token to authenticate.

from pluvo import Pluvo

pluvo = Pluvo(token='token')

user = pluvo.get_user(1)

API list endpoints

Methods for API endpoints that return a list will return a PluvoGenerator instance. The first page of the results is immediately retrieved. The length of the instance will be the total number of items. The instance implements an iterator, fetching more pages as nessecary.

See this example with a total of 50 courses in Pluvo.

from pluvo import Pluvo

pluvo = Pluvo(client_id='client_id', client_secret='client_secret')

# Only the first 20 courses and the total number of courses are retrieved.
courses = pluvo.get_courses()

# No extra request is done.
len(courses)  # 50

# Two more pages are retrieved.
list(courses)  # [...]

Altering page size

The default page size of 20 can be changed when instantiating the Pluvo object.

from pluvo import Pluvo

pluvo = Pluvo(
    client_id='client_id', client_secret='client_secret', page_size=50)

API errors

When an API error is encountered an PluvoAPIException is raised.

from pluvo import Pluvo, PluvoAPIException

# Not authenticated.
pluvo = Pluvo(client_id='invalid', client_secret='invalid')

try:
    pluvo.get_course(1)
except PluvoAPIException as e:
    e.message  # 'Provided client_id or client_secret are invalid.'
    e.status_code  # 403
    str(e)  # 'HTTP status 403 - Provided client_id or client_secret are invalid.'

General errors

All errors thrown by the library that are not a result of an API error will be PluvoException errors. This is also the base class for PluvoAPIException.