Welcome to ClefStorm’s documentation!

Apart from providing the module itself, this project comes with a test web server that you can try. The test web server is a well documented single file, and you can get the know-how from there. Please note that the test server is not included in the pypi package (e.g. it cannot be installed using pip or easy_install), but you can download the whole project repository from here: https://bitbucket.org/nagylzs/clefstorm/downloads or you can clone the project. For details, see https://bitbucket.org/nagylzs/clefstorm

Asynchronous client for Clef and Tornado.

class clefstorm.AsyncBus

Asynchronous notification bus.

This is a helper class that is used for asynchronous notifications between http requests. You can await for notifications on a set of keys, and you can send notifications for waiters of a given key. This is similar to a Condition object, with the following differences:

  • AsyncBus.waitfor does have a timeout parameter (Condition does not)
  • AsyncBus can automatically route notifications to multiple waiters using message identifiers (keys).
notify(key, message)

Notify a single waiter.

Parameters:
  • key – Key value that identifies the waiter. Should be immutable.
  • message – The message to be delivered to the waiter.
Returns:

True if the waiter was notified, False otherwise.
notifyall(key, message)

Notify all waiters. Return the number of waiters notified.

Parameters:
  • key – Key value that identifies the waiters. Should be immutable.
  • message – The message to be delivered to the waiters.
Returns:

The number of waiters notified
Type:

int
waitforkey(key, timeout=None)

Wait for notification on a single key.

Parameters:
  • key – An key to be listened to. Key should be immutable.
  • timeout – If there is no notification coming in for the given timeout, then raise a BusTimeoutError.
Returns:

A message that was sent by a notify() or notifyall() call.
waitforkeys(keys, timeout=None)

Wait for notification.

Parameters:
  • keys – An iterable that contains keys to be listened to. Keys should be immutable.
  • timeout – If there is no notification coming in for the given timeout, then raise a BusTimeoutError.
Returns:

A tuple of (key, message) that was sent by a notify() or notifyall() call.
exception clefstorm.BusTimeoutError

Raised when the waiter has been waiting for too long.

exception clefstorm.ClefAPIError

Raised when Clef API call returns an error.

class clefstorm.ClefStorm(api_key, api_password, logger=None)

Asynchronous Clef authentication client that works with tornado.

api_url = 'https://clef.io/api/v1/'
generate_button(redirect_url, state, typ='login', style=None)

Generate a Clef Wave that can be used for login, registration or connection.

Parameters:
  • redirect_url – The URL where the user’s browser should be redirected after successful authentication. This should not contain any GET parameters, nor the ? character at the end.
  • state – XSFR token - unpredictable random string that will be used against cross site forgery attacks.
  • typ – Type of the wave, can be “login”, “register” or “connect”.
  • style – A ClefWaveStyle instance.
Returns:

Javascript code for the button.
get(rel_url, params)

Get from Clef.

Parameters:
  • rel_url – URL relative to api_url
  • params – a dict of GET parameter values to be added to the GET url
Returns:

a response object
get_and_parse(rel_url, params)

Get from Clef and parse json response.

Parameters:
  • rel_url – URL relative to api_url
  • params – a dict of GET parameter values to be added to the GET url
Returns:

a data structure, parsed by json.loads from the response body.
get_info(access_token)

Get information about the logged in user.

Parameters:access_token – Access token as returned by get_token()
Returns:User information
Return type:dict
get_logged_out_clef_id(logout_token)

Exchange a logout token with a clef id that needs to be logged out.

Parameters:logout_token – The logout token, provided by the clef logout webhook callback.
Returns:A clef id that needs to be logged out.
Return type:int
get_token(code)

Exchange authorization code into an access token.

Parameters:code – Authorization code from the login GET callback.
Returns:access token
Return type:str
notify_logout(clef_id)

Notify all clients (browsers) that the user has been logged out remotely.

Parameters:clef_id – The clef id of the user that was logged out.
Returns:Number of waiters notified.
post(rel_url, params)

Post params to Clef

Parameters:
  • rel_url – URL relative to api_url
  • params – A dict of POST parameters
Returns:

a response object
post_and_parse(rel_url, params)

Post to Clef and parse json response.

Parameters:
  • rel_url – URL relative to api_url
  • params – a dict of GET parameter values to be added to the GET url
Returns:

a data structure, parsed by json.loads from the response body.
token_ttl = 3000.0
user_agent = 'ClefStorm 0.1.2'
validate_cert = True
wait_for_logout(clef_id, timeout)

Wait until a user is logged out.

Parameters:
  • clef_id – The clef id of the user who is waiting for a logout callback from Clef.
  • timeout – A datetime.timedelta instance.After the given timeout, a BusTimeoutError will be raised.
Returns:

The clef id of the user that was logged out
Return type:

int
class clefstorm.ClefWaveStyle(color='blue', style='button', custom=None, embed=None)

Represents the style of a Clef Wave.