General concepts

This chapter introduces some general concepts and functions of the Python G-Node Client such as session management, configuration files and cache handling.

Creating a Session

The following code example demonstrates how to create a new session object. First a dictionary containing all connection parameters is created, which is later passed, along with other parameters, to the constructor of the Session class.

from gnodeclient.session import Session

options = {
    "location": "http://predata.g-node.org",
    "username": "user",
    "password": "secret",
    "cache_dir": "~/.gnodeclient/cache"
}

s = Session(options, file_name="~/gnodeclient/conf", persist_options=True)
s.close()

Let’s take a closer look on the connection parameters in the options dictionary:

location:The is the base url of the G-Node REST API installation. username:The user to login with. password:The password used for authentication. cach_dir:This is the location, that will be used by the client to store cached objects. If this is not provided, the client will choose an appropriate system dependent location (e.g. ~/.cache/gnodeclient on Linux).

The two other parameters passed to the constructor are both related to the configuration of the client. The parameter file_name sets the path to the configuration file, that stores the given connection parameters and provides defaults if they are not set. If this parameter is None, the location will be chosen by the client. If persist_options set to is True (default is False) the provided options will be stored in the configuration file (except for password).

Assuming that a configuration file exists, it can be used to complement missing connection parameters:

s = Session({"password": "secret"}, file_name="~/gnodeclient/conf")

In the above example the location, username and cache_dir are retrieved from the file ~/gnodeclient/conf and then used to establish the session.

The Global Session Object

For all use-cases where only one single session object is needed one can use the functions create() and close() of the gnodeclient.session module. Both functions operate on a global session object. The subsequent example illustrates the use of them:

from gnodeclient import session

s1 = session.create(location="http://predata.g-node.org", username="user", password="secret", persist_options=True)
s2 = session.create()
id(s1) == id(s2)           # is True

session.close()

The first call in line 3 creates the global session object and returns it. The same object is then returned again by the second call of session.create(). In the last line the global session is closed and destroyed, thus invalidating both session objects.

Caching

The Python G-Node Client performs caching of remote objects. Since the cache management is completely handled by the client, there is not much to learn about it for the user. However, for some operations it is very useful to have some knowledge about how caching is used in order to understand the behaviour of the client.

Here some general rules:

• The method Session.select() always queries the remote server for its results.
• The method Session.get() always returns results from the cache (if present) unless it is invoked with refresh True. In this case it will fetch data from the server if a newer version of the requested object is available.
• For performance reasons all lazy loaded objects are always retrieved from the cache and are only requested from the server when the object is missing from the cache.

There are mainly two methods, that give the user some control over the cache:

block = s.get(block.location, refresh=True, recursive=True)
# .. further operations

s.clear_cache()
# .. further operations

In line one, the Session.get() method is invoked with both parameters refresh and recursive set to True. This causes the block object to be updated and furthermore ensures that all its descendants are now present in the cache with their most recent version. Another way of making sure that only the most recent versions are used is to purge every cached object. This is shown in line 4 of the above example.

Session Reference

The session module defines the main programming interface of the G-Node Client. It provides the Session class which defines all methods, that are necessary to access the G-Node REST API. Further the module defines the functions crate() and close(): both functions operate on a global, application wide session object.

class gnodeclient.session.Session(options, file_name, persist_options=False)

The session class defines all basic methods, that are necessary to access the the G-Node REST API.

close()

Close all connections and opened files used by the session.

delete(entity)

Delete an object from the G-Node service.

Parameters:entity (object) – The entity to delete.

get(location, refresh=False, recursive=False)

Get a specific object from the G-Node service. The object to obtain is specified by its location.

Parameters:

• location (str) – The location of the object.
• refresh (bool) – If True and if the object was previously cached, check if it has changed.
• recursive (bool) – If True, load all child objects recursively to the cache.

Returns:

The requested object (Neo or odML).

options

Read only property for accessing all used options.

Returns:All currently used options. Return type:Configuration

permissions(entity, permissions=None)

Set or get permissions of an object from the G-Node service.

The permissions object, that is passed as a second parameter contains the following information:

{
    "safety_level": 1, # 1-private, 2-friendly, 3-public
    "shared_with": {
        "bob": 1, # 1-read-only
        "jeff", 2 # 2-read-write
    }
}

Parameters:

• entity (object) – The entity to get or set permissions from/to.
• permissions (dict) – new permissions to apply.

Returns:

actual object permissions

Return type:

dict (see above)

select(model_name, raw_filters=None)

Obtain a list of objects from a certain kind from the G-Node service. In addition a set of filters can be applied in order to reduce the returned results.

Parameters:

• model_name (str) – The name of the model e.g. ‘block’ or ‘spike’.
• raw_filters (dict) – A set of filters as used by the G-Node REST API e.g. {‘name_icontains’: ‘foo’}

Returns:

A list of objects.

Return type:

list

set(entity, avoid_collisions=False)

Save a modified or created object on the G-Node service.

Parameters:

• entity (object) – The object to store (Neo or odML).
• avoid_collisions (bool) – If true, check if the modified object collide with changes on the server.

Returns:

The saved entity.

Return type:

object

gnodeclient.session.create(username=None, password=None, location=None, file_name=None, persist_options=False)

Creates and returns a main session object. Multiple calls will return always the same object unless close() was not called.

gnodeclient.session.close()

Close the main session object.