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