Python API

Analysis

class databench.Analysis[source]

Databench’s analysis class.

This contains the analysis code. Every browser connection corresponds to an instance of this class.

Initialization: All initializations should be done in on_connected(). Instance variables (which should be avoided in favor of data) should be initialized in the constructor. Some cleanup can be done in on_disconnected().

Arguments/Parameters: Command line arguments are available at cli_args and the parameters of the HTTP GET request at request_args. request_args is a dictionary of all arguments. Each value of the dictionary is a list of given values for this key even if this key only appeared once in the url (see urllib.parse.parse_qs).

Actions: are captured by specifying a class method starting with on_ followed by the action name. To capture the action run that is emitted with the JavaScript code

// on the JavaScript frontend
d.emit('run', {my_param: 'helloworld'});

use

# in Python
def on_run(self, my_param):

in Python. Lists are treated as positional arguments and objects as keyword arguments to the function call. If the message is neither of type list nor dict (for example a plain string or float), the function will be called with that as its first parameter.

Writing to a datastore: By default, a DatastoreLegacy scoped to the current analysis instance is created at data. You can write key-value pairs to it with

self.data[key] = value

Similarly, there is a class_data DatastoreLegacy which is scoped to all instances of this analysis by its class name.

Communicating with the frontend: The default is to change state by changing and entry in data or class_data and let that change propagate to the frontend. Directly calling emit() is also possible.

Outgoing messages: changes to the datastore are emitted to the frontend and this path should usually not be modified. However, databench does provide access to emit() method and to methods that modify a value for a key before it is send out with data_<key>(value) methods.

Variables:
  • data (DatastoreLegacy) – data scoped for this instance/connection
  • class_data (DatastoreLegacy) – data scoped across all instances
  • cli_args (list) – command line arguments
  • request_args (dict) – request arguments
init_datastores()[source]

Initialize datastores for this analysis instance.

This creates instances of Datastore at data and class_data with the datastore domains being the current id and the class name of this analysis respectively.

Overwrite this method to use other datastore backends.

set_emit_fn(emit_fn)[source]

Sets what the emit function for this analysis will be.

emit(signal, message=u'__nomessagetoken__')[source]

Emit a signal to the frontend.

Parameters:
  • signal (str) – name of the signal
  • message – message to send
Returns:

return value from frontend emit function

Return type:

tornado.concurrent.Future

on_connected()[source]

Default handlers for the “connected” action.

Overwrite to add behavior.

New in version 0.7: Previously, most of this functionality was in on_connect().

on_disconnected()[source]

Default handler for “disconnected” action.

Overwrite to add behavior.

databench.on(action)[source]

Decorator for action handlers.

This also decorates the method with tornado.gen.coroutine so that `~tornado.concurrent.Future`s can be `yield`ed.

The decorated object will have a code() to retrieve its source code.

The action name can be given explicitely or can be inferred from the function name.

Meta

class databench.Meta(name, analysis_class, analysis_path, extra_routes, cli_args=None)[source]

Meta class referencing an analysis.

Parameters:
  • name (str) – Name of this analysis.
  • analysis_class (databench.Analysis) – Object that should be instantiated for every new websocket connection.
  • analysis_path (str) – Path of the analysis class.
  • extra_routes (list) – [(route, handler, data), …]
  • cli_args (list) – Arguments from the command line.
static run_process(*args, **kwargs)[source]

Executes an action in the analysis with the given message.

It also handles the start and stop signals in the case that message is a dict with a key __process_id.

Parameters:
  • action_name (str) – Name of the action to trigger.
  • message – Message.
  • callback – A callback function when done (e.g. stop in tests).
Return type:

tornado.concurrent.Future

Datastore

class databench.DatastoreLegacy(domain, release_storage=False)[source]

Key-value data store.

An in-memory and in-process (not persistent) key-value store.

Parameters:
  • domain – A namespace for the key values. This can be an analysis instance id for data local to an analysis instance or the name of an analysis class for data that is shared across instances of the same analysis.
  • release_storage (bool) – Release storage when the last datastore for a domain closes.
on_change(callback)[source]

Subscribe to changes in the datastore with a callback.

Deprecated. Use subscribe() instead.

Parameters:callback – Function that takes in a key and a value.
subscribe(callback)[source]

Subscribe to changes in the datastore with a callback.

Parameters:callback – Function that takes in a key and a value.
trigger_all_change_callbacks()[source]

Trigger all callbacks that were set with on_change().

set(key, value)[source]

Set value at key and return a Future

Return type:tornado.concurrent.Future
update(key_value_pairs)[source]

Similar to dict.update().

Parameters:key_value_pairs (dict) – A dictionary of key value pairs to update.
init(key_value_pairs)[source]

Initialize datastore.

Only sets values for keys that are not in the datastore already.

Parameters:key_value_pairs (dict) – A set of key value pairs to use to initialize the datastore.
close()[source]

Close and delete instance.

class databench.Datastore(domain, release_storage=False)[source]

Key-value data store.

An in-memory and in-process (not persistent) key-value store.

Parameters:
  • domain – A namespace for the key values. This can be an analysis instance id for data local to an analysis instance or the name of an analysis class for data that is shared across instances of the same analysis.
  • release_storage (bool) – Release storage when the last datastore for a domain closes.
subscribe(callback)[source]

Subscribe to changes in the datastore with a callback.

Parameters:callback – Function with signature ({key: value}) => None.
trigger_all_callbacks(callbacks=None)[source]

Trigger callbacks for all keys on all or a subset of subscribers.

Parameters:callbacks (Iterable) – list of callbacks or none for all subscribed
Return type:Iterable[tornado.concurrent.Future]
get(key, default=None)[source]

Return entry at key.

Return a default value if the key is not present.

set(key, value)[source]

Set a value at key and return a Future.

Return type:Iterable[tornado.concurrent.Future]
set_state(updater)[source]

Update the datastore.

Parameters:updater (func|dict) – (state) => state_change or dict state_change
Return type:Iterable[tornado.concurrent.Future]
init(key_value_pairs)[source]

Initialize datastore.

Only sets values for keys that are not in the datastore already.

Parameters:key_value_pairs (dict) – A set of key value pairs to use to initialize the datastore.
Return type:Iterable[tornado.concurrent.Future]
close()[source]

Close and delete instance.

keys()[source]

Keys.

values()[source]

Values.

items()[source]

Items.

Utils

databench.utils.json_encoder_default(obj)[source]

Handle more data types than the default JSON encoder.

Specifically, it treats a set and a numpy array like a list.

Example usage: json.dumps(obj, default=json_encoder_default)

databench.utils.fig_to_src(figure, image_format='png', dpi=80)[source]

Convert a matplotlib figure to an inline HTML image.

Parameters:
  • figure (matplotlib.Figure) – Figure to display.
  • image_format (str) – png (default) or svg
  • dpi (int) – dots-per-inch for raster graphics.
Return type:

str

databench.utils.png_to_src(png)[source]

Convert a PNG string to a format that can be passed into a src.

Return type:str
databench.utils.svg_to_src(svg)[source]

Convert an SVG string to a format that can be passed into a src.

Return type:str

Testing

class databench.testing.AnalysisTest(analysis, cli_args=None, request_args=None, meta=None)[source]

Unit test wrapper for an analysis.

Parameters:
  • analysis (databench.Analysis) – The analysis to test.
  • cli_args (str) – Command line interface arguments.
  • request_args (str) – Request arguments.
  • meta – An object with a run_process attribute.

Trigger actions using the trigger method. All outgoing messages to the frontend are captured in emitted_messages.

There are two main options for constructing tests: decorating with gen_test and yield ing futures (block until future is done) or to use wait and stop in callbacks. For detailed information on ioloops within the Tornado testing framework, please consult tornado.testing.

Examples:

from databench.testing import AnalysisTest
from databench.tests.analyses.parameters.analysis import Parameters
import tornado.testing


class Example(tornado.testing.AsyncTestCase):
    @tornado.testing.gen_test
    def test_gentest(self):
        test = AnalysisTest(Parameters())
        yield test.trigger('test_data', ['light', 'red'])
        self.assertIn(('data', {'light': 'red'}), test.emitted_messages)

    def test_stopwait(self):
        test = AnalysisTest(Parameters())
        test.trigger('test_data', ['light', 'red'], callback=self.stop)
        self.wait()
        self.assertIn(('data', {'light': 'red'}), test.emitted_messages)
trigger(action_name, message='__nomessagetoken__', **kwargs)[source]

Trigger an on callback.

Parameters:
  • action_name (str) – Name of the action to trigger.
  • message – Message.
  • callback – A callback function when done (e.g. stop in tests).
Return type:

tornado.concurrent.Future