Python API

Databench module.

databench.run(analysis, path=None, name=None, info=None, **kwargs)[source]

Run a single analysis.

Parameters:
  • analysis (Analysis) – Analysis class to run.
  • path (str) – Path of analysis. Can be __file__.
  • name (str) – Name of the analysis.
  • info (dict) – Optional entries are version, title, readme, …
  • static (dict) – Map[url regex, root-folder] to serve static content.

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 connected(). Instance variables (which should be avoided in favor of state) should be initialized in the constructor. Some cleanup can be done in 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 class method decorated with databench.on. 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
@databench.on
def run(self, my_param):
    pass

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 Datastore scoped to the current analysis instance is created at data. You can write state updates to it with

yield self.set_state(key1=value1)

Similarly, there is a Datastore instance at class_data which is scoped to all instances of this analysis by its class name and state updates are supported with set_class_state().

Communicating with the frontend: The default is to change state with set_state() or set_class_state() and let that change propagate to all frontends. Directly calling emit() is also possible.

Variables:
  • data (Datastore) – data scoped for this instance/connection
  • class_data (Datastore) – 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.

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

connected()[source]

Default handler for “connected” action.

Overwrite to add behavior.

disconnected()[source]

Default handler for “disconnected” action.

Overwrite to add behavior.

set_state(updater=None, **kwargs)[source]

Set state in Datastore.

set_class_state(updater=None, **kwargs)[source]

Set state in class Datastore.

databench.on(f)[source]

Decorator for action handlers.

The action name is inferred from the function name.

This also decorates the method with tornado.gen.coroutine so that Future can be yielded.

databench.on_action(action)[source]

Decorator for action handlers.

Parameters:action (str) – explicit action name

This also decorates the method with tornado.gen.coroutine so that Future can be yielded.

Meta

class databench.Meta(name, analysis_class, analysis_path, extra_routes=None, cli_args=None, main_template=u'index.html', info=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.Datastore(domain, release_storage=False)[source]

Key-value data store.

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

Parameters:
  • domain (str) – 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=None, **kwargs)[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=None, **kwargs)[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) – 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 tornado.testing.gen_test and yielding Future objects (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.

Variables:
  • cli_args (list) – command line arguments
  • request_args (dict) – request arguments
  • emitted_messages (list) – all emitted (signal, message) pairs

Examples:

import databench
import tornado.testing


class Yodler(databench.Analysis):
    """A simple analysis that we want to test."""

    @databench.on
    def echo(self, key, value):
        """An action that applies the given key and value to the state."""
        yield self.set_state({key: value})


class Example(tornado.testing.AsyncTestCase):
    """Test cases for the Yodler analysis."""

    @tornado.testing.gen_test
    def test_gentest(self):
        """Demonstrating the decorator pattern for tests."""
        test = databench.testing.AnalysisTest(Yodler)
        yield test.trigger('echo', ['light', 'red'])
        self.assertIn(('data', {'light': 'red'}), test.emitted_messages)

    def test_stopwait(self):
        """Demonstrating the stop-wait-callback pattern for tests."""
        test = databench.testing.AnalysisTest(Yodler)
        test.trigger('echo', ['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