Note

This documentation is for a development version of IPython. There may be significant differences from the latest stable release (1.2.1).

Module: core.events

Infrastructure for registering and firing callbacks on application events.

Unlike IPython.core.hooks, which lets end users set single functions to be called at specific times, or a collection of alternative methods to try, callbacks are designed to be used by extension authors. A number of callbacks can be registered for the same event without needing to be aware of one another.

The functions defined in this module are no-ops indicating the names of available events and the arguments which will be passed to them.

Note

This API is experimental in IPython 2.0, and may be revised in future versions.

1 Class

class IPython.core.events.EventManager(shell, available_events)

Bases: object

Manage a collection of events and a sequence of callbacks for each.

This is attached to InteractiveShell instances as an events attribute.

Note

This API is experimental in IPython 2.0, and may be revised in future versions.

__init__(shell, available_events)

Initialise the CallbackManager.

Parameters:

shell

The InteractiveShell instance

available_callbacks

An iterable of names for callback events.

register(event, function)

Register a new event callback

Parameters:

event : str

The event for which to register this callback.

function : callable

A function to be called on the given event. It should take the same parameters as the appropriate callback prototype.

Raises:

TypeError

If function is not callable.

KeyError

If event is not one of the known events.

reset(event)

Clear all callbacks for the given event.

reset_all()

Clear all callbacks for all events.

trigger(event, *args, **kwargs)

Call callbacks for event.

Any additional arguments are passed to all callbacks registered for this event. Exceptions raised by callbacks are caught, and a message printed.

unregister(event, function)

Remove a callback from the given event.

5 Functions

IPython.core.events.pre_execute()

Fires before code is executed in response to user/frontend action.

This includes comm and widget messages and silent execution, as well as user code cells.

IPython.core.events.pre_run_cell()

Fires before user-entered code runs.

IPython.core.events.post_execute()

Fires after code is executed in response to user/frontend action.

This includes comm and widget messages and silent execution, as well as user code cells.

IPython.core.events.post_run_cell()

Fires after user-entered code runs.

IPython.core.events.shell_initialized(ip)

Fires after initialisation of InteractiveShell.

This is before extensions and startup scripts are loaded, so it can only be set by subclassing.

Parameters:

ip : InteractiveShell

The newly initialised shell.