maxclient 4.0.2

Authentication

MaxClient uses MAX api’s, so a valid max OAuth2 username/token pair is needed to make any requests. To authenticate a maxlient and leave it ready to use, create a maxclient instance, specifying both Max server url and Oauth2 Server URL:

>>> from maxclient import MaxClient
>>> client = MaxClient('http://max.server.com', oauth_server='http://oauth.server.com')

Once you have the client instance, you can authenticate it using the username/token pair:

>>> client.setActor('user.name')
>>> client.setToken('NLfIgUgBgODd4sdAgDsFgdAffFigfBf0')

If you don’t have the token for your username, maxclient can grab it for you, providing the password from which the token was generated originally:

>>> client.login(username='user.name', password='password')

client.login becomes interactive if username or password are not provided, so you can use it on cli scripts:

client.login()
>>> Username: user.name
>>> Password: *********

Usage

There are two versions of the client, one is rpc-like and the other one is rest-ish. The default one (rpc) one implements a method for every api endpoint available on max, for example:

>>> client.addUser('user.name')
>>> client.getUser('user.name')

rpc-client returns responses with 3 value in a tuple, in the form:

(True, 201, {})

Where the first value is wether the request did finish succesfully, the second the response code of the request, and the third the response content. Response content may be a dict or list loaded from a json, or None if no valid json response found

Note that not all endpoints may be implemented in the rpc-client, as a different method is needed for every endpoint. For parameters of every method, see code in client.py

RESt-ish client

The rest-ish client is an attempt to make a generic wrapper for max api, so you can easily access all available endpoints with a unique client, and without the need for updating it constantly. The authentication is like in the rpc client, you just have to import it from a different location:

>>> from maxclient.rest import MaxClient

To use this client, you have to know how max apis works and how they are structured, as the access to the api is implemented by mimicking url access, for example. To access the endpoint to add a user, as described on max documentation, you have to make a POST request to /people/{username}. To make this with maxclient:

>>> maxclient.people['user.name'].post()

Where people is a resource collection (a fixed name on the endpoint url), and ‘user.name’ is a resource item (a variable name on the endpoint url). So, resource collections are accessed as attributes, and resource items as dict-like accessors. Both resource items and resource collections can contain each other:

>>> maxclient.people['user.name'].activities.get()

The last part of the command, indicates the method which will be used to access the endpoint. Resource items and collection objects are lazy, so any action will be executed until a method executed on top of a resource.

Named parameters passed to the client will be passed as json when doing .post() and .put() requests. So if we execute:

>>> maxclient.people['user.name'].post(displayName='User Name')

a json will be generated from kwargs and sent in the request body:

{
    "displayName": "User Name"
}

if you want you can prepare a dict with all params that need to be in that json, and pass it through the data argument, and the result will be the same. if data argument is present, all other kwargs are ignored:

>>> params = dict(displayName='User Name')
>>> maxclient.people['user.name'].post(data=params)

Some endpoints methods have defined some sensible defaults. You can view the defaults defined in defaults.py, or inspect them by code:

>>> maxclient.people['user.name'].defaults('post')
{'object': {'objectType': 'note'}}

This defaults are used as a base which is updated using the kwargs provided. I this way, when we make this request:

>>> maxclient.people['user.name'].post(generator='Twitter')

The data that will be send in the request body will be a combination of the defaults and kwargs:

{
    "object": {
        "objectType": "note"
    }
    "generator": "Twitter"
}

You can pass kwargs in the form key_subkey, and will be interpreted as nested keys. So you can do things like:

>>> maxclient.people['user.name'].post(generator='Twitter', object_content='Hello world')

That results in the following request body:

{
    "object": {
        "objectType": "note",
        "content": "Hellow World"
    }
    "generator": "Twitter"
}

If your requests needs query string parameters, you must feed them trough the qs argument as a dict, and the key-value pairs will be urlencoded to a querystring, for example, to limit the results of the request with a ?limit01:

>>> maxclient.people['carles.bruguera'].activities.get(qs={'limit': 1})

And the last thing, if you need to upload a file, feed the file object or stream object trough the file_upload param as follows. Feed the raw open file, WITHOUT reading it, we need the object not the content of the file:

>>> avatar = open('/path/to/avatar.png', 'rb')
>>> maxclient.people['carles.bruguera'].avatar.post(upload_file=avatar)

Maxclient will respond with the parsed json response of max when the request succedded, and will raise an RequestError exception in any other case, which message will indicate the reason of the error.

For more information on max see:

https://github.com/UPCnet/max https://github.com/UPCnet/maxserver.devel

4.0.2 (2014-05-28)

• Merge branch ‘develop’ of github.com:UPCnet/maxclient into develop [Carles Bruguera]

• Save last response status [Carles Bruguera]

• Configure max instance to log tracebacks on exceptions [Carles Bruguera]

4.0.1 (2014-05-07)

• Updated resources [Carles Bruguera]

• Identify filesystem resources based on presence of files in request [Carles Bruguera]

• Don’t return on try [Carles Bruguera]

• Allow multiple upload_files specifying id [Carles Bruguera]

• include json data as json_data in multipart paylod [Carles Bruguera]

• Allow ResourceItems in ResourceItems [Carles Bruguera]

• Don’t treat list content on data param as dicts (…) [Carles Bruguera]

• Update defaults and resources list [Carles Bruguera]

4.0.0 (2014-04-15)

• Fix wrong default [Carles Bruguera]

• Add some defaults [Carles Bruguera]

• Update resources from max [Carles Bruguera]

• Include http response code on exception [Carles Bruguera]

• Add defaults for posting a conversation message [Carles Bruguera]

• Use a app wrapper for requests on wsgi client [Carles Bruguera]

• Add wsgi version of maxclient [sunbit]

• Fetch oauth server from max info endpoint if not provided [sunbit]

• Add license [Victor Fernandez de Alba]

3.6.3 (2014-03-25)

• Updated use case HEAD returning 404 and returning as it’s not implemented when in fact, it is but simply the resource does not exist. [Victor Fernandez de Alba]

3.6.2 (2014-03-24)

• Separate common features into BaseClient [Carles Bruguera]

• Default for contexts [Victor Fernandez de Alba]

• Update resources [Carles Bruguera]

• Update resources [Carles Bruguera]

• Updated resources from max [Carles Bruguera]

• Wrapper for user [Carles Bruguera]

• SYntax fix [Carles Bruguera]

• upload file base on file object, not content [Carles Bruguera]

• Add support to file uploads [Carles Bruguera]

• Add support for dict-based query strings [Carles Bruguera]

• Document variable pass syntax [Carles Bruguera]

• Move helper methods to utils.py [Carles Bruguera]

• expand key.subkey and key_subkey dict keys as nested dicts [Carles Bruguera]

• Make dict updates recursive [Carles Bruguera]

• Add defaults definition system [Carles Bruguera]

• Add debug method for raw requests [Carles Bruguera]

• Wrap non-hashes {hash} variables into hashes [Carles Bruguera]

• Typo [Carles Bruguera]

• Documentation [Carles Bruguera]

• Catch bad gateway errors [Carles Bruguera]

• Update resources definitions [Carles Bruguera]

• First version of generic rest-like maxclient [Carles Bruguera]

• Add getUser endpoint wrapper [Carles Bruguera]

• Better bad password error [Carles Bruguera]

3.6.1 (2014-02-24)

• Add both endpoints wrappers, grant and revoke [Victor Fernandez de Alba]

• Add security grant role wrapper [Victor Fernandez de Alba]

3.6 (2014-01-20)

• Added get_context, grant permission, revoke permission [Victor Fernandez de Alba]

3.5.3 (2013-10-29)

• Methods to manage context tags [Carles Bruguera]

3.5.2 (2013-10-08)

• Fix bug that returned None when max returned [] [Carles Bruguera]

3.5.1 (2013-10-03)

• Added mod operation for context [Carles Bruguera]

3.5 (2013-09-13)

• Update Manifest [Victor Fernandez de Alba]

• New wraper for conversation tokens endpoint. [Victor Fernandez de Alba]

• Added wrapper for post activity as a context endpoint [Victor Fernandez de Alba]

• Added new method for identify current actor [Victor Fernandez de Alba]

• Update sensible defaults for maxclient [Victor Fernandez de Alba]

3.4.1 (2013-08-02)

• Added wrapper for upload users avatar [Victor Fernandez de Alba]

3.4 (2013-07-25)

• Add more verbose errors [Victor Fernandez de Alba]

• Updated minor version to match the MAX minor version [Victor Fernandez de Alba]

3.3.3 (2013-07-10)

• Fix latter endpoint added and better handling for delete operations. [Victor Fernandez de Alba]

• Merge branch ‘master’ of github.com:UPCnet/maxclient [Victor Fernandez de Alba]

• Add new endpoint wrapper [Victor Fernandez de Alba]

• Better propagation of the information about what happened [Victor Fernandez de Alba]

3.3.2 (2013-07-01)

• Added endpoint wrapper for returning the subscirbers for a given context

• Added endpoint wrapper for unsubscribing a user from a context

3.3.1 (2013-06-04)

• Added fallback to work with osiris oauth servers and legacy ones

3.3 (2013-06-04)

• Updated to 3.3 MAX

3.0 (2013-04-15)

• Updated to latest implementations

1.0 (Unreleased)

• Initial version