events.py
161 lines
| 5.3 KiB
| text/x-python
|
PythonLexer
|
r15605 | """Infrastructure for registering and firing callbacks on application events. | ||
|
r15599 | |||
Unlike :mod:`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. | ||||
|
r15606 | |||
.. note:: | ||||
This API is experimental in IPython 2.0, and may be revised in future versions. | ||||
|
r15599 | """ | ||
|
r15597 | |||
|
r23996 | from backcall import callback_prototype | ||
|
r23982 | |||
|
r15605 | class EventManager(object): | ||
|
r15599 | """Manage a collection of events and a sequence of callbacks for each. | ||
This is attached to :class:`~IPython.core.interactiveshell.InteractiveShell` | ||||
|
r15609 | instances as an ``events`` attribute. | ||
|
r15606 | |||
.. note:: | ||||
This API is experimental in IPython 2.0, and may be revised in future versions. | ||||
|
r15599 | """ | ||
|
r15605 | def __init__(self, shell, available_events): | ||
|
r15599 | """Initialise the :class:`CallbackManager`. | ||
Parameters | ||||
---------- | ||||
shell | ||||
The :class:`~IPython.core.interactiveshell.InteractiveShell` instance | ||||
available_callbacks | ||||
An iterable of names for callback events. | ||||
""" | ||||
|
r15597 | self.shell = shell | ||
|
r15605 | self.callbacks = {n:[] for n in available_events} | ||
|
r15597 | |||
|
r15605 | def register(self, event, function): | ||
|
r23997 | """Register a new event callback. | ||
|
r15599 | |||
Parameters | ||||
---------- | ||||
|
r15605 | event : str | ||
|
r15599 | 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 | ||||
|
r15605 | If ``event`` is not one of the known events. | ||
|
r15599 | """ | ||
|
r15597 | if not callable(function): | ||
raise TypeError('Need a callable, got %r' % function) | ||||
|
r23997 | callback_proto = available_events.get(event) | ||
|
r26114 | if function not in self.callbacks[event]: | ||
self.callbacks[event].append(callback_proto.adapt(function)) | ||||
|
r15597 | |||
|
r15605 | def unregister(self, event, function): | ||
|
r15599 | """Remove a callback from the given event.""" | ||
|
r23997 | if function in self.callbacks[event]: | ||
return self.callbacks[event].remove(function) | ||||
# Remove callback in case ``function`` was adapted by `backcall`. | ||||
for callback in self.callbacks[event]: | ||||
|
r24005 | try: | ||
if callback.__wrapped__ is function: | ||||
return self.callbacks[event].remove(callback) | ||||
except AttributeError: | ||||
pass | ||||
|
r23997 | |||
raise ValueError('Function {!r} is not registered as a {} callback'.format(function, event)) | ||||
|
r15605 | def trigger(self, event, *args, **kwargs): | ||
"""Call callbacks for ``event``. | ||||
|
r15599 | |||
Any additional arguments are passed to all callbacks registered for this | ||||
event. Exceptions raised by callbacks are caught, and a message printed. | ||||
""" | ||||
|
r22317 | for func in self.callbacks[event][:]: | ||
|
r15597 | try: | ||
func(*args, **kwargs) | ||||
|
r24961 | except (Exception, KeyboardInterrupt): | ||
|
r15605 | print("Error in callback {} (for {}):".format(func, event)) | ||
|
r15597 | self.shell.showtraceback() | ||
|
r15599 | # event_name -> prototype mapping | ||
|
r15605 | available_events = {} | ||
|
r15599 | |||
|
r23997 | def _define_event(callback_function): | ||
callback_proto = callback_prototype(callback_function) | ||||
available_events[callback_function.__name__] = callback_proto | ||||
|
r15597 | return callback_proto | ||
|
r15599 | # ------------------------------------------------------------------------------ | ||
# Callback prototypes | ||||
# | ||||
# No-op functions which describe the names of available events and the | ||||
# signatures of callbacks for those events. | ||||
# ------------------------------------------------------------------------------ | ||||
|
r15609 | @_define_event | ||
|
r23997 | def pre_execute(): | ||
|
r15597 | """Fires before code is executed in response to user/frontend action. | ||
|
r15627 | This includes comm and widget messages and silent execution, as well as user | ||
|
r23982 | code cells. | ||
""" | ||||
|
r15597 | pass | ||
|
r15609 | @_define_event | ||
|
r23997 | def pre_run_cell(info): | ||
|
r23982 | """Fires before user-entered code runs. | ||
|
r15597 | |||
|
r23982 | Parameters | ||
---------- | ||||
|
r23997 | info : :class:`~IPython.core.interactiveshell.ExecutionInfo` | ||
An object containing information used for the code execution. | ||||
|
r23982 | """ | ||
|
r15602 | pass | ||
|
r15609 | @_define_event | ||
|
r23997 | def post_execute(): | ||
|
r23982 | """Fires after code is executed in response to user/frontend action. | ||
|
r23909 | |||
This includes comm and widget messages and silent execution, as well as user | ||||
code cells. | ||||
""" | ||||
pass | ||||
@_define_event | ||||
|
r23982 | def post_run_cell(result): | ||
"""Fires after user-entered code runs. | ||||
|
r23909 | |||
Parameters | ||||
---------- | ||||
result : :class:`~IPython.core.interactiveshell.ExecutionResult` | ||||
|
r23982 | The object which will be returned as the execution result. | ||
|
r23909 | """ | ||
pass | ||||
@_define_event | ||||
|
r15612 | def shell_initialized(ip): | ||
|
r15602 | """Fires after initialisation of :class:`~IPython.core.interactiveshell.InteractiveShell`. | ||
This is before extensions and startup scripts are loaded, so it can only be | ||||
set by subclassing. | ||||
|
r15604 | |||
Parameters | ||||
---------- | ||||
ip : :class:`~IPython.core.interactiveshell.InteractiveShell` | ||||
The newly initialised shell. | ||||
|
r15602 | """ | ||
pass | ||||