Python API

Databench module., path=None, name=None, info=None, **kwargs)[source]

Run a single analysis.

  • 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.


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'});


# in Python
def 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 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.

  • 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

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.

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

return value from frontend emit function

Return type:



Default handler for “connected” action.

Overwrite to add behavior.


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.


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.


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.


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.

  • 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.

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



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

Key-value data store.

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

  • 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 to changes in the datastore with a callback.

Parameters:callback – Function with signature ({key: value}) => None.

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 and delete instance.









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.

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



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

Return type:str

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

Return type:str


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

Unit test wrapper for an analysis.

  • 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.

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


import databench
import tornado.testing

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

    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."""

    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.assertIn(('data', {'light': 'red'}), test.emitted_messages)
trigger(action_name, message='__nomessagetoken__', **kwargs)[source]

Trigger an on callback.

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