Usage

Authentication and Authorization

So far, only desktop and web authentication are supported.

Desktop Authentication

To get an access token, do something like this:

from ipernity import IpernityAPI

iper = IpernityAPI(my_key, my_secret)
frob = iper.auth.getFrob()['auth']['frob']
url = iper.auth.auth_url({'doc': 'write'}, frob)

print('Starting web browser for authorization...')
webbrowser.open_new(url)
input('Press <Enter> after authorizing access in browser... ')

# Get access token and store it in API object
iper.auth.getToken(frob)
print('Token retrieved, you can close the browser now.')

Once the access token is generated, it can be passed to IpernityAPI’s constructor to create a pre-authorized object:

from ipernity import IpernityAPI
iper = IpernityAPI(my_key, my_secret, my_token)

See also

Web Authentication (Flask)

The following snippet illustrates the authentication procedure using an example Flask application. For a description of the process, see the Ipernity Documentation <http://www.ipernity.com/help/api/auth.web.html>. The URL for callback must be given to Ipernity on creation of the API key.

from flask import Flask, redirect, session
from ipernity import IpernityAPI

app = Flask()

# Application should redirect here when authorization is required
@app.route('/login')
def login():
    iper = IpernityAPI(my_key, my_secret, auth='web')
    return redirect(iper.auth.auth_url({'doc': 'write'}))

# Ipernity will redirect here on successful authorization
@app.route('/callback')
def callback():
    frob = request.params['frob']
    iper = IpernityAPI(my_key, my_secret, auth='web')
    token = iper.auth.getToken(frob)['auth']
    session['token'] = token

See also

Calling API methods

There are two ways of calling Ipernity API methods:

  1. The call() method.

  2. The “method property” scheme.

The difference is best shown in an example:

ip = IpernityAPI(key, secret)

# These two calls are equivalent
user_info = ip.call('user.get', userid = 4711)
user_info = ip.user.get(userid = 4711)

Note

  • All parameters should be passed as keyword arguments.

  • The response (here: user_info) is the complete parsed JSON that the API call returns. See Ipernity API output formats for more information.

  • The api_key parameter is specified in the constructor of IpernityAPI and should not be specified in API calls.

  • Requests are automatically signed by PyIpernity.

Iterating over search results

PyIpernity provides special methods to iterate smoothly over results that are distributed as multiple “pages”. These generators are:

walk_albums()

Iterates over a user’s albums.

walk_album_docs()

Iterates over documents in an album.

walk_doc_search()

Iterates over the result of a document search.

walk_docs()

Iterates over a user’s documents.

walk_data()

Generic method, called by the other walk_* methods.

Interactive mode

Added in version 0.3.0.

PyIpernity provides an interactive mode for testing. To get information about the command line options, type

$ python -m ipernity -h

at the shell prompt. If application key and secret are specified in environment variables or a configuration file, you can just start interactive mode with

$ python -m ipernity

Specifying key, secret and token

There are three ways to specify the authentication information (in order of precedence):

  1. Command line arguments:

    $ python -m ipernity -k <api-key> -s <api-secret> -t <api-token>

  2. Configuration file (default $HOME/.ipernity.ini):

    [ipernity]
api key = <api-key>
api secret = <api-secret>
api token = <api-token>

  3. Environment variables:

    IPERNITY_API_KEY=<api-key>
IPERNITY_API_SECRET=<api-secret>
IPERNITY_API_TOKEN=<api-token>

Specifying the token is optional. Some API methods can be called without a token, and you can get a token with the login command.