Show More
@@ -1,42 +1,87 b'' | |||||
1 | ===================== |
|
1 | .. _events: | |
2 | Registering callbacks |
|
2 | .. _callbacks: | |
3 | ===================== |
|
3 | ||
|
4 | ============== | |||
|
5 | IPython Events | |||
|
6 | ============== | |||
4 |
|
7 | |||
5 | Extension code can register callbacks functions which will be called on specific |
|
8 | Extension code can register callbacks functions which will be called on specific | |
6 | events within the IPython code. You can see the current list of available |
|
9 | events within the IPython code. You can see the current list of available | |
7 | callbacks, and the parameters that will be passed with each, in the callback |
|
10 | callbacks, and the parameters that will be passed with each, in the callback | |
8 | prototype functions defined in :mod:`IPython.core.callbacks`. |
|
11 | prototype functions defined in :mod:`IPython.core.callbacks`. | |
9 |
|
12 | |||
10 | To register callbacks, use :meth:`IPython.core.events.EventManager.register`. |
|
13 | To register callbacks, use :meth:`IPython.core.events.EventManager.register`. | |
11 | For example:: |
|
14 | For example:: | |
12 |
|
15 | |||
13 | class VarWatcher(object): |
|
16 | class VarWatcher(object): | |
14 | def __init__(self, ip): |
|
17 | def __init__(self, ip): | |
15 | self.shell = ip |
|
18 | self.shell = ip | |
16 | self.last_x = None |
|
19 | self.last_x = None | |
17 |
|
20 | |||
18 | def pre_execute(self): |
|
21 | def pre_execute(self): | |
19 | self.last_x = self.shell.user_ns.get('x', None) |
|
22 | self.last_x = self.shell.user_ns.get('x', None) | |
20 |
|
23 | |||
21 | def post_execute(self): |
|
24 | def post_execute(self): | |
22 | if self.shell.user_ns.get('x', None) != self.last_x: |
|
25 | if self.shell.user_ns.get('x', None) != self.last_x: | |
23 | print("x changed!") |
|
26 | print("x changed!") | |
24 |
|
27 | |||
25 | def load_ipython_extension(ip): |
|
28 | def load_ipython_extension(ip): | |
26 | vw = VarWatcher(ip) |
|
29 | vw = VarWatcher(ip) | |
27 | ip.events.register('pre_execute', vw.pre_execute) |
|
30 | ip.events.register('pre_execute', vw.pre_execute) | |
28 | ip.events.register('post_execute', vw.post_execute) |
|
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 | .. seealso:: |
|
79 | .. seealso:: | |
35 |
|
80 | |||
36 | Module :mod:`IPython.core.hooks` |
|
81 | Module :mod:`IPython.core.hooks` | |
37 | The older 'hooks' system allows end users to customise some parts of |
|
82 | The older 'hooks' system allows end users to customise some parts of | |
38 | IPython's behaviour. |
|
83 | IPython's behaviour. | |
39 |
|
84 | |||
40 | :doc:`inputtransforms` |
|
85 | :doc:`inputtransforms` | |
41 | By registering input transformers that don't change code, you can monitor |
|
86 | By registering input transformers that don't change code, you can monitor | |
42 | what is being executed. |
|
87 | what is being executed. |
General Comments 0
You need to be logged in to leave comments.
Login now