Show More
@@ -1,42 +1,87 b'' | |||
|
1 | ===================== | |
|
2 | Registering callbacks | |
|
3 | ===================== | |
|
1 | .. _events: | |
|
2 | .. _callbacks: | |
|
3 | ||
|
4 | ============== | |
|
5 | IPython Events | |
|
6 | ============== | |
|
4 | 7 | |
|
5 | 8 | Extension code can register callbacks functions which will be called on specific |
|
6 | 9 | events within the IPython code. You can see the current list of available |
|
7 | 10 | callbacks, and the parameters that will be passed with each, in the callback |
|
8 | 11 | prototype functions defined in :mod:`IPython.core.callbacks`. |
|
9 | 12 | |
|
10 | 13 | To register callbacks, use :meth:`IPython.core.events.EventManager.register`. |
|
11 | 14 | For example:: |
|
12 | 15 | |
|
13 | 16 | class VarWatcher(object): |
|
14 | 17 | def __init__(self, ip): |
|
15 | 18 | self.shell = ip |
|
16 | 19 | self.last_x = None |
|
17 | 20 | |
|
18 | 21 | def pre_execute(self): |
|
19 | 22 | self.last_x = self.shell.user_ns.get('x', None) |
|
20 | 23 | |
|
21 | 24 | def post_execute(self): |
|
22 | 25 | if self.shell.user_ns.get('x', None) != self.last_x: |
|
23 | 26 | print("x changed!") |
|
24 | 27 | |
|
25 | 28 | def load_ipython_extension(ip): |
|
26 | 29 | vw = VarWatcher(ip) |
|
27 | 30 | ip.events.register('pre_execute', vw.pre_execute) |
|
28 | 31 | ip.events.register('post_execute', vw.post_execute) |
|
29 | 32 | |
|
30 | .. note:: | |
|
31 | 33 |
|
|
32 | This API is experimental in IPython 2.0, and may be revised in future versions. | |
|
34 | Events | |
|
35 | ====== | |
|
36 | ||
|
37 | These are the events IPython will emit. Callbacks will be passed no arguments, unless otherwise specified. | |
|
38 | ||
|
39 | shell_initialized | |
|
40 | ----------------- | |
|
41 | ||
|
42 | .. code-block:: python | |
|
43 | ||
|
44 | def shell_initialized(ipython): | |
|
45 | ... | |
|
46 | ||
|
47 | This event is triggered only once, at the end of setting up IPython. | |
|
48 | Extensions registered to load by default as part of configuration can use this to execute code to finalize setup. | |
|
49 | Callbacks will be passed the InteractiveShell instance. | |
|
50 | ||
|
51 | pre_run_cell | |
|
52 | ------------ | |
|
53 | ||
|
54 | ``pre_run_cell`` fires prior to interactive execution (e.g. a cell in a notebook). | |
|
55 | It can be used to note the state prior to execution, and keep track of changes. | |
|
56 | ||
|
57 | pre_execute | |
|
58 | ----------- | |
|
59 | ||
|
60 | ``pre_execute`` is like ``pre_run_cell``, but is triggered prior to *any* execution. | |
|
61 | Sometimes code can be executed by libraries, etc. which | |
|
62 | skipping the history/display mechanisms, in which cases ``pre_run_cell`` will not fire. | |
|
63 | ||
|
64 | post_run_cell | |
|
65 | ------------- | |
|
66 | ||
|
67 | ``post_run_cell`` runs after interactive execution (e.g. a cell in a notebook). | |
|
68 | It can be used to cleanup or notify or perform operations on any side effects produced during execution. | |
|
69 | For instance, the inline matplotlib backend uses this event to display any figures created but not explicitly displayed during the course of the cell. | |
|
70 | ||
|
71 | ||
|
72 | post_execute | |
|
73 | ------------ | |
|
74 | ||
|
75 | The same as ``pre_execute``, ``post_execute`` is like ``post_run_cell``, | |
|
76 | but fires for *all* executions, not just interactive ones. | |
|
77 | ||
|
33 | 78 | |
|
34 | 79 | .. seealso:: |
|
35 | 80 | |
|
36 | 81 | Module :mod:`IPython.core.hooks` |
|
37 | 82 | The older 'hooks' system allows end users to customise some parts of |
|
38 | 83 | IPython's behaviour. |
|
39 | 84 | |
|
40 | 85 | :doc:`inputtransforms` |
|
41 | 86 | By registering input transformers that don't change code, you can monitor |
|
42 | 87 | what is being executed. |
General Comments 0
You need to be logged in to leave comments.
Login now