Module: kernel.multiengine

Inheritance diagram for IPython.kernel.multiengine:

Adapt the IPython ControllerServer to IMultiEngine.

This module provides classes that adapt a ControllerService to the IMultiEngine interface. This interface is a basic interactive interface for working with a set of engines where it is desired to have explicit access to each registered engine.

The classes here are exposed to the network in files like:




class IPython.kernel.multiengine.IEngineMultiplexer(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: zope.interface.Interface

Interface to multiple engines implementing IEngineCore/Serialized/Queued.

This class simply acts as a multiplexer of methods that are in the various IEngines* interfaces. Thus the methods here are jut like those in the IEngine* interfaces, but with an extra first argument, targets. The targets argument can have the following forms:

  • targets = 10 # Engines are indexed by ints
  • targets = [0,1,2,3] # A list of ints
  • targets = ‘all’ # A string to indicate all targets

If targets is bad in any way, an InvalidEngineID will be raised. This includes engines not being registered.

All IEngineMultiplexer multiplexer methods must return a Deferred to a list with length equal to the number of targets. The elements of the list will correspond to the return of the corresponding IEngine method.

Failures are aggressive, meaning that if an action fails for any target, the overall action will fail immediately with that Failure.

targets : int, list of ints, or ‘all’

Engine ids the action will apply to.


Deferred to a list of results for each engine.


If the targets argument is bad or engines aren’t registered.


If there are no engines registered and targets=’all’

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.IFullMultiEngine(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: IPython.kernel.multiengine.IMultiEngine, IPython.kernel.multiengine.IMultiEngineCoordinator, IPython.kernel.multiengine.IMultiEngineExtras

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.IFullSynchronousMultiEngine(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: IPython.kernel.multiengine.ISynchronousMultiEngine, IPython.kernel.multiengine.ISynchronousMultiEngineCoordinator, IPython.kernel.multiengine.ISynchronousMultiEngineExtras

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.IMultiEngine(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: IPython.kernel.multiengine.IEngineMultiplexer

A controller that exposes an explicit interface to all of its engines.

This is the primary inteface for interactive usage.

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.IMultiEngineCoordinator(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: zope.interface.Interface

Methods that work on multiple engines explicitly.

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.IMultiEngineExtras(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: zope.interface.Interface

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.ISynchronousEngineMultiplexer(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: zope.interface.Interface

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.ISynchronousMultiEngine(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: IPython.kernel.multiengine.ISynchronousEngineMultiplexer

Synchronous, two-phase version of IMultiEngine.

Methods in this interface are identical to those of IMultiEngine, but they take one additional argument:

execute(lines, targets=’all’) -> execute(lines, targets=’all, block=True)

block : boolean

Should the method return a deferred to a deferredID or the actual result. If block=False a deferred to a deferredID is returned and the user must call get_pending_deferred at a later point. If block=True, a deferred to the actual result comes back.

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.ISynchronousMultiEngineCoordinator(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: IPython.kernel.multiengine.IMultiEngineCoordinator

Methods that work on multiple engines explicitly.

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.ISynchronousMultiEngineExtras(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: IPython.kernel.multiengine.IMultiEngineExtras

static __init__(name, bases=(), attrs=None, __doc__=None, __module__=None)


class IPython.kernel.multiengine.MultiEngine(controller)

Bases: IPython.kernel.controllerservice.ControllerAdapterBase

The representation of a ControllerService as a IMultiEngine.

Although it is not implemented currently, this class would be where a client/notification API is implemented. It could inherit from something like results.NotifierParent and then use the notify method to send notifications.

del_properties(keys, targets='all')

Parse the targets argument into a list of valid engine objects.

targets : int, list of ints or ‘all’

The targets argument to be parsed.


List of engine objects.


If targets is not valid or if an engine is not registered.

execute(lines, targets='all')
get_properties(keys=None, targets='all')
get_result(i=None, targets='all')
has_properties(keys, targets='all')
kill(controller=False, targets='all')
pull(keys, targets='all')
pull_function(keys, targets='all')
pull_serialized(keys, targets='all')
push(ns, targets='all')
push_function(ns, targets='all')
push_serialized(namespace, targets='all')
set_properties(properties, targets='all')


class IPython.kernel.multiengine.SynchronousMultiEngine(multiengine)

Bases: IPython.kernel.pendingdeferred.PendingDeferredManager

Adapt an IMultiEngine -> ISynchronousMultiEngine

Warning, this class uses a decorator that currently uses **kwargs. Because of this block must be passed as a kwarg, not positionally.

clear_properties(pdm, *args, **kwargs)
clear_queue(pdm, *args, **kwargs)
del_properties(pdm, *args, **kwargs)
execute(pdm, *args, **kwargs)

Return a list of registered engine ids.

Never use the two phase block/non-block stuff for this.

get_properties(pdm, *args, **kwargs)
get_result(pdm, *args, **kwargs)
has_properties(pdm, *args, **kwargs)
keys(pdm, *args, **kwargs)
kill(pdm, *args, **kwargs)
pull(pdm, *args, **kwargs)
pull_function(pdm, *args, **kwargs)
pull_serialized(pdm, *args, **kwargs)
push(pdm, *args, **kwargs)
push_function(pdm, *args, **kwargs)
push_serialized(pdm, *args, **kwargs)
queue_status(pdm, *args, **kwargs)
reset(pdm, *args, **kwargs)
set_properties(pdm, *args, **kwargs)