Getting Started

Installation

$ pip install Flask-Ipernity

Ipernity Application Key

To use Flask-Ipernity, you need to create an Ipernity API key.

  • Under “Authentication method”, choose “Web”

  • Enter a callback URL. If you use Flask-Ipernity’s built-in callback, the URL is http[s]://your.server.name/ipernity/cb. Don’t worry, you can change this value later if needed.

  • Save the application key and secret to the Flask configuration in the IPERNITY_APP_KEY and IPERNITY_APP_SECRET keys.

Ipernity Authentication/Authorization

Many Ipernity API calls require authentication/authorization. This can be done in two steps:

  1. The authorize() method returns a redirect to Ipernity’s authentication page.

  2. After authorization, the Browser is redirected to the application’s callback URL (see above). By default, Flask-Ipernity adds a Blueprint with a callback view that gets an access token and stores it in the application’s session. If you set IPERNITY_CALLBACK = False, you can define your own callback.

Flask-Ipernity provides a LocalProxy variable ipernity that contains the current application’s Ipernity object. API methods can be accessed with the api property.

Example:

from flask import Flask
from flask_ipernity import Ipernity, ipernity, ipernity_auth_required

app = Flask(__name__)
app.config.update(
    IPERNITY_APP_KEY = 'XXX',
    IPERNITY_APP_SECRET = 'YYY'
    IPERNITY_PERMISSIONS = {'doc': 'read'}
)
Ipernity(app)

@app.route('/get_doc')
@ipernity_auth_required()   # You can also specify permissions here
def get_doc():
    data = ipernity.api.docs.getList()
    ...

See also

Proxying Ipernity documents

Flask-Ipernity can proxy requests to Ipernity documents if IPERNITY_PROXY_DOCS is True (which is the default). This enables a blueprint that can be accessed with with something like

<img src="{{url_for('ip_proxy.doc', doc_id=4711, label='1600')}}">

label is the one of the sizes Ipernity provides, or 'original' for the original file.

Using Flask-Ipernity with Flask-Login

With Flask-Ipernity, you can use Ipernity as an identity provider for Flask-Login. Flaks-Ipernity then provides a blueprint with views for login and logout and handles login via Ipernity authentication. To activate this behavior, set the IPERNITY_LOGIN configuration to True.

Note

When using IPERNITY_LOGIN=True, be sure to call flask_login.LoginManager.init_app() before flask_ipernity.Ipernity.init_app()!

Views marked with login_required() will then trigger Ipernity authentication. Additionally using ipernity_auth_required() is not necessary and may lead to strange behavior.

from flask import Flask
from flask_ipernity import Ipernity, ipernity
from flask_login import LoginManager, login_required

app = Flask(__name__)
app.config.update(
    IPERNITY_APP_KEY = 'XXX',
    IPERNITY_APP_SECRET = 'YYY'
    IPERNITY_LOGIN = True,
    IPERNITY_PERMISSIONS = {'doc': 'read'}
)
LoginManager(app)
Ipernity(app)

@app.route('/get_doc')
@login_required
def get_doc():
    data = ipernity.api.docs.getList()
    ...

Caching Ipernity Requests

To avoid repeated requests in a short time, the results can be cached in the Flask session. To enable caching, set the configuration option IPERNITY_CACHE_REQUESTS to True. To control the cache lifetime, set IPERNITY_CACHE_MAX_AGE to the number of seconds you want to keep the results. The default is 300s.

Note

Flask’s default session handler only has a limited amount of memory which can easyly get exhausted when using caching. To avoid overflows, you can use an advanced session handler like Flask-Session.