Tutorial

Welcome to the python-ipernity-api wiki! This is a tutorial for python-ipernity-api.

Ipernity API keys

In order to user Ipernity API, you must apply a API key.

Before you want to use python-ipernity-api package, API keys should be set first. There are two ways available:

• use set_keys to set API keys each time you use this packages.

import ipernity_api

ipernity_api.set_keys(api_key="Your API key", api_secret="Your API secret")

• or provide a ipernity_keys.py setting module with the keys information, This module should be located in your ipernity_api directory or available from your PYTHON_PATH

API_KEY = "Your API key"
API_SECRET = "Your API secret"

Authentication

If you want to access specified user's data, authentication required.

By far, python-ipernity-api support OAuth authentication on ipernity.com.

An example to use OAuthAuthHandler

First, you must specified the permission for access the user's data.

Here is the possible type and value:

• doc: the requested permission for photos/videos/docs. (read/write/delete).
• blog: the requested permission for articles. (read/write/delete).
• network: the requested permission for the contacts (read/write/delete).
• profile: the requested permission for the user's profile (read/write).

Permission is a dict, which can combine different category and permission together.

perms = {'doc': 'delete',
         'blog': 'delete',
         'network': 'delete', }

Then, get an auth handler

OAuthAuthHandler is the class that handling the OAuth authentication.

from ipernity_api import *
auth_handler = OAuthAuthHandler(perms=perms)

If you have a web application, and need callback url to determine when authentication is done, you could give an additional url to callback:

callback = 'http://your_website/callback'
auth_handler = OAuthAuthHandler(perms=perms, callback=callback)

Guide user to authentication in given url

Get Ipernity authentication url:

auth_url = auth_handler.get_auth_url()

Then redirect user to visit auth_url in browser, this would go to ipernity.com page.

How to determine when authentication is done.

• If callback given, ipernity.com would redirect to callback url after user agree the terms.
• Otherwise, need user to confirm authentication is done.

Verify the OAuth Handler.

When you know user has finished authentication, you can verify Auth Handler by verify:

auth_handler.verify()

Use Auth Handler

In order to use given Auth Handler, need to call set_auth_handler to take effect.

set_auth_handler(auth_handler)

python-ipernity-api would use this handler as default auth handler in later request.

Import/Export Auth Handler

Export to file

fpath = '/tmp/tmp-ipernity-auth-handler'
auth_handler.save(fpath)

Import from file

auth_handler = AuthHandler.load(fpath)
set_auth_handler(auth_handler)

GET request Cache

python-ipernity-api has a simple builtin cache mechanism for GET request.

This mechanism can avoid send the same request to server in short time, which would speed up request process time. But there is also a chance to get outdate data from the cache.

Use at your own risk. default is disabled.

enable cache

enable_cache()

disable cache

disable_cache()

Play with ipernity objects

Retrieve a user

• by specified user id

user = User.get(id='USERID')

• get login user by auth handler

user = auth_handler.getUser()

Manager docs

For ipernity.com, Doc represent ont only photos but also videos.

fetch docs of user

docs = user.getDocs()

# can get info about result
print docs.info['total']  # total num of docs
print docs.info['page']  # page index
print docs.info['pages']  # total pages

upload a doc

Upload.file(file='example.jpg', title='example')

# or if you want to get upload Doc Objects
ticket = Upload.file(file='example2.jpg')
doc = ticket.getDoc()

add a comment to the doc

doc.comments_add(content="Your comments")

# get comments of the doc
comments = doc.comments_getList()

add tags to the doc

tags = ['tag1', 'tag2']
doc.tags_add(keywords=tags)

edit photo info

doc.edit(title="new title", description="new desc")

replace doc with new file

# need pro account
doc.replace(file='new_file.jpg')

delete a photo

doc.delete()

Albums

get all albums of the user

albums = user.getAlbums()

create a album

album = Album.create(title="new album", cover=doc)

play with album

# add a doc to album
album.docs_add(doc=doc)

# add docs
album.docs_add(docs=[doc1, doc2])

# list docs of album
docs = album.docs_getList()