##// END OF EJS Templates
FIX: bare functions in callback registry on bogus unregister...
Thomas A Caswell -
Show More
@@ -1,157 +1,160 b''
1 """Infrastructure for registering and firing callbacks on application events.
1 """Infrastructure for registering and firing callbacks on application events.
2
2
3 Unlike :mod:`IPython.core.hooks`, which lets end users set single functions to
3 Unlike :mod:`IPython.core.hooks`, which lets end users set single functions to
4 be called at specific times, or a collection of alternative methods to try,
4 be called at specific times, or a collection of alternative methods to try,
5 callbacks are designed to be used by extension authors. A number of callbacks
5 callbacks are designed to be used by extension authors. A number of callbacks
6 can be registered for the same event without needing to be aware of one another.
6 can be registered for the same event without needing to be aware of one another.
7
7
8 The functions defined in this module are no-ops indicating the names of available
8 The functions defined in this module are no-ops indicating the names of available
9 events and the arguments which will be passed to them.
9 events and the arguments which will be passed to them.
10
10
11 .. note::
11 .. note::
12
12
13 This API is experimental in IPython 2.0, and may be revised in future versions.
13 This API is experimental in IPython 2.0, and may be revised in future versions.
14 """
14 """
15
15
16 from backcall import callback_prototype
16 from backcall import callback_prototype
17
17
18
18
19 class EventManager(object):
19 class EventManager(object):
20 """Manage a collection of events and a sequence of callbacks for each.
20 """Manage a collection of events and a sequence of callbacks for each.
21
21
22 This is attached to :class:`~IPython.core.interactiveshell.InteractiveShell`
22 This is attached to :class:`~IPython.core.interactiveshell.InteractiveShell`
23 instances as an ``events`` attribute.
23 instances as an ``events`` attribute.
24
24
25 .. note::
25 .. note::
26
26
27 This API is experimental in IPython 2.0, and may be revised in future versions.
27 This API is experimental in IPython 2.0, and may be revised in future versions.
28 """
28 """
29 def __init__(self, shell, available_events):
29 def __init__(self, shell, available_events):
30 """Initialise the :class:`CallbackManager`.
30 """Initialise the :class:`CallbackManager`.
31
31
32 Parameters
32 Parameters
33 ----------
33 ----------
34 shell
34 shell
35 The :class:`~IPython.core.interactiveshell.InteractiveShell` instance
35 The :class:`~IPython.core.interactiveshell.InteractiveShell` instance
36 available_callbacks
36 available_callbacks
37 An iterable of names for callback events.
37 An iterable of names for callback events.
38 """
38 """
39 self.shell = shell
39 self.shell = shell
40 self.callbacks = {n:[] for n in available_events}
40 self.callbacks = {n:[] for n in available_events}
41
41
42 def register(self, event, function):
42 def register(self, event, function):
43 """Register a new event callback.
43 """Register a new event callback.
44
44
45 Parameters
45 Parameters
46 ----------
46 ----------
47 event : str
47 event : str
48 The event for which to register this callback.
48 The event for which to register this callback.
49 function : callable
49 function : callable
50 A function to be called on the given event. It should take the same
50 A function to be called on the given event. It should take the same
51 parameters as the appropriate callback prototype.
51 parameters as the appropriate callback prototype.
52
52
53 Raises
53 Raises
54 ------
54 ------
55 TypeError
55 TypeError
56 If ``function`` is not callable.
56 If ``function`` is not callable.
57 KeyError
57 KeyError
58 If ``event`` is not one of the known events.
58 If ``event`` is not one of the known events.
59 """
59 """
60 if not callable(function):
60 if not callable(function):
61 raise TypeError('Need a callable, got %r' % function)
61 raise TypeError('Need a callable, got %r' % function)
62 callback_proto = available_events.get(event)
62 callback_proto = available_events.get(event)
63 self.callbacks[event].append(callback_proto.adapt(function))
63 self.callbacks[event].append(callback_proto.adapt(function))
64
64
65 def unregister(self, event, function):
65 def unregister(self, event, function):
66 """Remove a callback from the given event."""
66 """Remove a callback from the given event."""
67 if function in self.callbacks[event]:
67 if function in self.callbacks[event]:
68 return self.callbacks[event].remove(function)
68 return self.callbacks[event].remove(function)
69
69
70 # Remove callback in case ``function`` was adapted by `backcall`.
70 # Remove callback in case ``function`` was adapted by `backcall`.
71 for callback in self.callbacks[event]:
71 for callback in self.callbacks[event]:
72 try:
72 if callback.__wrapped__ is function:
73 if callback.__wrapped__ is function:
73 return self.callbacks[event].remove(callback)
74 return self.callbacks[event].remove(callback)
75 except AttributeError:
76 pass
74
77
75 raise ValueError('Function {!r} is not registered as a {} callback'.format(function, event))
78 raise ValueError('Function {!r} is not registered as a {} callback'.format(function, event))
76
79
77 def trigger(self, event, *args, **kwargs):
80 def trigger(self, event, *args, **kwargs):
78 """Call callbacks for ``event``.
81 """Call callbacks for ``event``.
79
82
80 Any additional arguments are passed to all callbacks registered for this
83 Any additional arguments are passed to all callbacks registered for this
81 event. Exceptions raised by callbacks are caught, and a message printed.
84 event. Exceptions raised by callbacks are caught, and a message printed.
82 """
85 """
83 for func in self.callbacks[event][:]:
86 for func in self.callbacks[event][:]:
84 try:
87 try:
85 func(*args, **kwargs)
88 func(*args, **kwargs)
86 except Exception:
89 except Exception:
87 print("Error in callback {} (for {}):".format(func, event))
90 print("Error in callback {} (for {}):".format(func, event))
88 self.shell.showtraceback()
91 self.shell.showtraceback()
89
92
90 # event_name -> prototype mapping
93 # event_name -> prototype mapping
91 available_events = {}
94 available_events = {}
92
95
93 def _define_event(callback_function):
96 def _define_event(callback_function):
94 callback_proto = callback_prototype(callback_function)
97 callback_proto = callback_prototype(callback_function)
95 available_events[callback_function.__name__] = callback_proto
98 available_events[callback_function.__name__] = callback_proto
96 return callback_proto
99 return callback_proto
97
100
98 # ------------------------------------------------------------------------------
101 # ------------------------------------------------------------------------------
99 # Callback prototypes
102 # Callback prototypes
100 #
103 #
101 # No-op functions which describe the names of available events and the
104 # No-op functions which describe the names of available events and the
102 # signatures of callbacks for those events.
105 # signatures of callbacks for those events.
103 # ------------------------------------------------------------------------------
106 # ------------------------------------------------------------------------------
104
107
105 @_define_event
108 @_define_event
106 def pre_execute():
109 def pre_execute():
107 """Fires before code is executed in response to user/frontend action.
110 """Fires before code is executed in response to user/frontend action.
108
111
109 This includes comm and widget messages and silent execution, as well as user
112 This includes comm and widget messages and silent execution, as well as user
110 code cells.
113 code cells.
111 """
114 """
112 pass
115 pass
113
116
114 @_define_event
117 @_define_event
115 def pre_run_cell(info):
118 def pre_run_cell(info):
116 """Fires before user-entered code runs.
119 """Fires before user-entered code runs.
117
120
118 Parameters
121 Parameters
119 ----------
122 ----------
120 info : :class:`~IPython.core.interactiveshell.ExecutionInfo`
123 info : :class:`~IPython.core.interactiveshell.ExecutionInfo`
121 An object containing information used for the code execution.
124 An object containing information used for the code execution.
122 """
125 """
123 pass
126 pass
124
127
125 @_define_event
128 @_define_event
126 def post_execute():
129 def post_execute():
127 """Fires after code is executed in response to user/frontend action.
130 """Fires after code is executed in response to user/frontend action.
128
131
129 This includes comm and widget messages and silent execution, as well as user
132 This includes comm and widget messages and silent execution, as well as user
130 code cells.
133 code cells.
131 """
134 """
132 pass
135 pass
133
136
134 @_define_event
137 @_define_event
135 def post_run_cell(result):
138 def post_run_cell(result):
136 """Fires after user-entered code runs.
139 """Fires after user-entered code runs.
137
140
138 Parameters
141 Parameters
139 ----------
142 ----------
140 result : :class:`~IPython.core.interactiveshell.ExecutionResult`
143 result : :class:`~IPython.core.interactiveshell.ExecutionResult`
141 The object which will be returned as the execution result.
144 The object which will be returned as the execution result.
142 """
145 """
143 pass
146 pass
144
147
145 @_define_event
148 @_define_event
146 def shell_initialized(ip):
149 def shell_initialized(ip):
147 """Fires after initialisation of :class:`~IPython.core.interactiveshell.InteractiveShell`.
150 """Fires after initialisation of :class:`~IPython.core.interactiveshell.InteractiveShell`.
148
151
149 This is before extensions and startup scripts are loaded, so it can only be
152 This is before extensions and startup scripts are loaded, so it can only be
150 set by subclassing.
153 set by subclassing.
151
154
152 Parameters
155 Parameters
153 ----------
156 ----------
154 ip : :class:`~IPython.core.interactiveshell.InteractiveShell`
157 ip : :class:`~IPython.core.interactiveshell.InteractiveShell`
155 The newly initialised shell.
158 The newly initialised shell.
156 """
159 """
157 pass
160 pass
General Comments 0
You need to be logged in to leave comments. Login now