kernel.engineservice

Module: kernel.engineservice

Inheritance diagram for IPython.kernel.engineservice:

A Twisted Service Representation of the IPython core.

The IPython Core exposed to the network is called the Engine. Its representation in Twisted in the EngineService. Interfaces and adapters are used to abstract out the details of the actual network protocol used. The EngineService is an Engine that knows nothing about the actual protocol used.

The EngineService is exposed with various network protocols in modules like:

enginepb.py enginevanilla.py

As of 12/12/06 the classes in this module have been simplified greatly. It was felt that we had over-engineered things. To improve the maintainability of the code we have taken out the ICompleteEngine interface and the completeEngine method that automatically added methods to engines.

Classes

Command

class IPython.kernel.engineservice.Command(remoteMethod, *args, **kwargs)

Bases: object

A command object that encapslates queued commands.

This class basically keeps track of a command that has been queued in a QueuedEngine. It manages the deferreds and hold the method to be called and the arguments to that method.

__init__(remoteMethod, *args, **kwargs)

Build a new Command object.

handleError(reason)

When an error has occured, relay it to self.deferred.

handleResult(result)

When the result is ready, relay it to self.deferred.

setDeferred(d)

Sets the deferred attribute of the Command.

EngineAPI

class IPython.kernel.engineservice.EngineAPI(id)

Bases: object

This is the object through which the user can edit the properties attribute of an Engine. The Engine Properties object copies all object in and out of itself. See the EngineProperties object for details.

__init__(id)

EngineService

class IPython.kernel.engineservice.EngineService(shellClass=<class 'IPython.kernel.core.interpreter.Interpreter'>, mpi=None)

Bases: object, twisted.application.service.Service

Adapt a IPython shell into a IEngine implementing Twisted Service.

__init__(shellClass=<class 'IPython.kernel.core.interpreter.Interpreter'>, mpi=None)

Create an EngineService.

shellClass: something that implements IInterpreter or core1 mpi: an mpi module that has rank and size attributes

addIDToResult(result)

clear_properties()

del_properties(keys)

execute(lines)

executeAndRaise(msg, callable, *args, **kwargs)

Call a method of self.shell and wrap any exception.

get_properties(keys=None)

get_result(i=None)

has_properties(keys)

id

keys()

Return a list of variables names in the users top level namespace.

This used to return a dict of all the keys/repr(values) in the user’s namespace. This was too much info for the ControllerService to handle so it is now just a list of keys.

kill()

pull(keys)

pull_function(keys)

pull_serialized(keys)

push(namespace)

push_function(namespace)

push_serialized(sNamespace)

reset()

set_properties(properties)

IEngineBase

class IPython.kernel.engineservice.IEngineBase(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: IPython.kernel.engineservice.IEngineCore, IPython.kernel.engineservice.IEngineSerialized, IPython.kernel.engineservice.IEngineProperties

The basic engine interface that EngineService will implement.

This exists so it is easy to specify adapters that adapt to and from the API that the basic EngineService implements.

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

IEngineCore

class IPython.kernel.engineservice.IEngineCore(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: zope.interface.Interface

The minimal required interface for the IPython Engine.

This interface provides a formal specification of the IPython core. All these methods should return deferreds regardless of what side of a network connection they are on.

In general, this class simply wraps a shell class and wraps its return values as Deferred objects. If the underlying shell class method raises an exception, this class should convert it to a twisted.failure.Failure that will be propagated along the Deferred’s errback chain.

In addition, Failures are aggressive. By this, we mean that if a method is performing multiple actions (like pulling multiple object) if any single one fails, the entire method will fail with that Failure. It is all or nothing.

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

IEngineProperties

class IPython.kernel.engineservice.IEngineProperties(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: zope.interface.Interface

Methods for access to the properties object of an Engine

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

IEngineQueued

class IPython.kernel.engineservice.IEngineQueued(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: IPython.kernel.engineservice.IEngineBase

Interface for adding a queue to an IEngineBase.

This interface extends the IEngineBase interface to add methods for managing the engine’s queue. The implicit details of this interface are that the execution of all methods declared in IEngineBase should appropriately be put through a queue before execution.

All methods should return deferreds.

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

IEngineSerialized

class IPython.kernel.engineservice.IEngineSerialized(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: zope.interface.Interface

Push/Pull methods that take Serialized objects.

All methods should return deferreds.

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

IEngineThreaded

class IPython.kernel.engineservice.IEngineThreaded(name, bases=(), attrs=None, __doc__=None, __module__=None)

Bases: zope.interface.Interface

A place holder for threaded commands.

All methods should return deferreds.

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

QueuedEngine

class IPython.kernel.engineservice.QueuedEngine(engine)

Bases: object

Adapt an IEngineBase to an IEngineQueued by wrapping it.

The resulting object will implement IEngineQueued which extends IEngineCore which extends (IEngineBase, IEngineSerialized).

This seems like the best way of handling it, but I am not sure. The other option is to have the various base interfaces be used like mix-in intefaces. The problem I have with this is adpatation is more difficult and complicated because there can be can multiple original and final Interfaces.

__init__(engine)

Create a QueuedEngine object from an engine

engine: An implementor of IEngineCore and IEngineSerialized keepUpToDate: whether to update the remote status when the

queue is empty. Defaults to False.

abortCommand(reason)

Abort current command.

This eats the Failure but first passes it onto the Deferred that the user has.

It also clear out the queue so subsequence commands don’t run.

clear_properties(this, *args, **kwargs)

clear_queue(msg='')

Clear the queue, but doesn’t cancel the currently running commmand.

del_properties(this, *args, **kwargs)

execute(this, *args, **kwargs)

finishCommand(result)

Finish currrent command.

get_properties(this, *args, **kwargs)

get_result(i=None)

has_properties(this, *args, **kwargs)

keys(this, *args, **kwargs)

kill()

properties

pull(this, *args, **kwargs)

pull_function(this, *args, **kwargs)

pull_serialized(this, *args, **kwargs)

push(this, *args, **kwargs)

push_function(this, *args, **kwargs)

push_serialized(this, *args, **kwargs)

queue_status()

register_failure_observer(obs)

reset()

runCurrentCommand()

Run current command.

saveResult(result)

Put the result in the history.

set_properties(this, *args, **kwargs)

submitCommand(cmd)

Submit command to queue.

unregister_failure_observer(obs)

StrictDict

class IPython.kernel.engineservice.StrictDict(*args, **kwargs)

Bases: dict

This is a strict copying dictionary for use as the interface to the properties of an Engine.

Important:This object copies the values you set to it, and returns copies to you when you request them. The only way to change properties os explicitly through the setitem and getitem of the dictionary interface.

Example:

>>> e = get_engine(id)
>>> L = [1,2,3]
>>> e.properties['L'] = L
>>> L == e.properties['L']
True
>>> L.append(99)
>>> L == e.properties['L']
False

Note that getitem copies, so calls to methods of objects do not affect the properties, as seen here:

>>> e.properties[1] = range(2)
>>> print e.properties[1]
[0, 1]
>>> e.properties[1].append(2)
>>> print e.properties[1]
[0, 1]

__init__(*args, **kwargs)

clear()

pop(key)

popitem()

subDict(*keys)

update(dikt)

ThreadedEngineService

class IPython.kernel.engineservice.ThreadedEngineService(shellClass=<class 'IPython.kernel.core.interpreter.Interpreter'>, mpi=None)

Bases: IPython.kernel.engineservice.EngineService

An EngineService subclass that defers execute commands to a separate thread.

ThreadedEngineService uses twisted.internet.threads.deferToThread to defer execute requests to a separate thread. GUI frontends may want to use ThreadedEngineService as the engine in an IPython.frontend.frontendbase.FrontEndBase subclass to prevent block execution from blocking the GUI thread.

__init__(shellClass=<class 'IPython.kernel.core.interpreter.Interpreter'>, mpi=None)

execute(lines)

wrapped_execute(msg, lines)

Wrap self.shell.execute to add extra information to tracebacks

Functions

IPython.kernel.engineservice.drop_engine(id)

remove an engine

IPython.kernel.engineservice.get_engine(id)

Get the Engine API object, whcih currently just provides the properties object, by ID

IPython.kernel.engineservice.queue(methodToQueue)