Module: core.events — IPython 5.3.0 documentation

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

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