Show More
@@ -0,0 +1,132 b'' | |||
|
1 | .. _defining_magics: | |
|
2 | ||
|
3 | Defining custom magics | |
|
4 | ====================== | |
|
5 | ||
|
6 | There are two main ways to define your own magic functions: from standalone | |
|
7 | functions and by inheriting from a base class provided by IPython: | |
|
8 | :class:`IPython.core.magic.Magics`. Below we show code you can place in a file | |
|
9 | that you load from your configuration, such as any file in the ``startup`` | |
|
10 | subdirectory of your default IPython profile. | |
|
11 | ||
|
12 | First, let us see the simplest case. The following shows how to create a line | |
|
13 | magic, a cell one and one that works in both modes, using just plain functions: | |
|
14 | ||
|
15 | .. sourcecode:: python | |
|
16 | ||
|
17 | from IPython.core.magic import (register_line_magic, register_cell_magic, | |
|
18 | register_line_cell_magic) | |
|
19 | ||
|
20 | @register_line_magic | |
|
21 | def lmagic(line): | |
|
22 | "my line magic" | |
|
23 | return line | |
|
24 | ||
|
25 | @register_cell_magic | |
|
26 | def cmagic(line, cell): | |
|
27 | "my cell magic" | |
|
28 | return line, cell | |
|
29 | ||
|
30 | @register_line_cell_magic | |
|
31 | def lcmagic(line, cell=None): | |
|
32 | "Magic that works both as %lcmagic and as %%lcmagic" | |
|
33 | if cell is None: | |
|
34 | print("Called as line magic") | |
|
35 | return line | |
|
36 | else: | |
|
37 | print("Called as cell magic") | |
|
38 | return line, cell | |
|
39 | ||
|
40 | # We delete these to avoid name conflicts for automagic to work | |
|
41 | del lmagic, lcmagic | |
|
42 | ||
|
43 | ||
|
44 | You can also create magics of all three kinds by inheriting from the | |
|
45 | :class:`IPython.core.magic.Magics` class. This lets you create magics that can | |
|
46 | potentially hold state in between calls, and that have full access to the main | |
|
47 | IPython object: | |
|
48 | ||
|
49 | .. sourcecode:: python | |
|
50 | ||
|
51 | # This code can be put in any Python module, it does not require IPython | |
|
52 | # itself to be running already. It only creates the magics subclass but | |
|
53 | # doesn't instantiate it yet. | |
|
54 | from __future__ import print_function | |
|
55 | from IPython.core.magic import (Magics, magics_class, line_magic, | |
|
56 | cell_magic, line_cell_magic) | |
|
57 | ||
|
58 | # The class MUST call this class decorator at creation time | |
|
59 | @magics_class | |
|
60 | class MyMagics(Magics): | |
|
61 | ||
|
62 | @line_magic | |
|
63 | def lmagic(self, line): | |
|
64 | "my line magic" | |
|
65 | print("Full access to the main IPython object:", self.shell) | |
|
66 | print("Variables in the user namespace:", list(self.shell.user_ns.keys())) | |
|
67 | return line | |
|
68 | ||
|
69 | @cell_magic | |
|
70 | def cmagic(self, line, cell): | |
|
71 | "my cell magic" | |
|
72 | return line, cell | |
|
73 | ||
|
74 | @line_cell_magic | |
|
75 | def lcmagic(self, line, cell=None): | |
|
76 | "Magic that works both as %lcmagic and as %%lcmagic" | |
|
77 | if cell is None: | |
|
78 | print("Called as line magic") | |
|
79 | return line | |
|
80 | else: | |
|
81 | print("Called as cell magic") | |
|
82 | return line, cell | |
|
83 | ||
|
84 | ||
|
85 | # In order to actually use these magics, you must register them with a | |
|
86 | # running IPython. This code must be placed in a file that is loaded once | |
|
87 | # IPython is up and running: | |
|
88 | ip = get_ipython() | |
|
89 | # You can register the class itself without instantiating it. IPython will | |
|
90 | # call the default constructor on it. | |
|
91 | ip.register_magics(MyMagics) | |
|
92 | ||
|
93 | If you want to create a class with a different constructor that holds | |
|
94 | additional state, then you should always call the parent constructor and | |
|
95 | instantiate the class yourself before registration: | |
|
96 | ||
|
97 | .. sourcecode:: python | |
|
98 | ||
|
99 | @magics_class | |
|
100 | class StatefulMagics(Magics): | |
|
101 | "Magics that hold additional state" | |
|
102 | ||
|
103 | def __init__(self, shell, data): | |
|
104 | # You must call the parent constructor | |
|
105 | super(StatefulMagics, self).__init__(shell) | |
|
106 | self.data = data | |
|
107 | ||
|
108 | # etc... | |
|
109 | ||
|
110 | # This class must then be registered with a manually created instance, | |
|
111 | # since its constructor has different arguments from the default: | |
|
112 | ip = get_ipython() | |
|
113 | magics = StatefulMagics(ip, some_data) | |
|
114 | ip.register_magics(magics) | |
|
115 | ||
|
116 | ||
|
117 | In earlier versions, IPython had an API for the creation of line magics (cell | |
|
118 | magics did not exist at the time) that required you to create functions with a | |
|
119 | method-looking signature and to manually pass both the function and the name. | |
|
120 | While this API is no longer recommended, it remains indefinitely supported for | |
|
121 | backwards compatibility purposes. With the old API, you'd create a magic as | |
|
122 | follows: | |
|
123 | ||
|
124 | .. sourcecode:: python | |
|
125 | ||
|
126 | def func(self, line): | |
|
127 | print("Line magic called with line:", line) | |
|
128 | print("IPython object:", self.shell) | |
|
129 | ||
|
130 | ip = get_ipython() | |
|
131 | # Declare this function as the magic %mycommand | |
|
132 | ip.define_magic('mycommand', func) |
@@ -27,5 +27,6 b' Extending and integrating with IPython' | |||
|
27 | 27 | |
|
28 | 28 | extensions/index |
|
29 | 29 | integrating |
|
30 | custommagics | |
|
30 | 31 | inputtransforms |
|
31 | 32 | callbacks |
@@ -145,139 +145,6 b' use it:' | |||
|
145 | 145 | |
|
146 | 146 | /home/fperez/ipython |
|
147 | 147 | |
|
148 | .. _defining_magics: | |
|
149 | ||
|
150 | Defining your own magics | |
|
151 | ++++++++++++++++++++++++ | |
|
152 | ||
|
153 | There are two main ways to define your own magic functions: from standalone | |
|
154 | functions and by inheriting from a base class provided by IPython: | |
|
155 | :class:`IPython.core.magic.Magics`. Below we show code you can place in a file | |
|
156 | that you load from your configuration, such as any file in the ``startup`` | |
|
157 | subdirectory of your default IPython profile. | |
|
158 | ||
|
159 | First, let us see the simplest case. The following shows how to create a line | |
|
160 | magic, a cell one and one that works in both modes, using just plain functions: | |
|
161 | ||
|
162 | .. sourcecode:: python | |
|
163 | ||
|
164 | from IPython.core.magic import (register_line_magic, register_cell_magic, | |
|
165 | register_line_cell_magic) | |
|
166 | ||
|
167 | @register_line_magic | |
|
168 | def lmagic(line): | |
|
169 | "my line magic" | |
|
170 | return line | |
|
171 | ||
|
172 | @register_cell_magic | |
|
173 | def cmagic(line, cell): | |
|
174 | "my cell magic" | |
|
175 | return line, cell | |
|
176 | ||
|
177 | @register_line_cell_magic | |
|
178 | def lcmagic(line, cell=None): | |
|
179 | "Magic that works both as %lcmagic and as %%lcmagic" | |
|
180 | if cell is None: | |
|
181 | print("Called as line magic") | |
|
182 | return line | |
|
183 | else: | |
|
184 | print("Called as cell magic") | |
|
185 | return line, cell | |
|
186 | ||
|
187 | # We delete these to avoid name conflicts for automagic to work | |
|
188 | del lmagic, lcmagic | |
|
189 | ||
|
190 | ||
|
191 | You can also create magics of all three kinds by inheriting from the | |
|
192 | :class:`IPython.core.magic.Magics` class. This lets you create magics that can | |
|
193 | potentially hold state in between calls, and that have full access to the main | |
|
194 | IPython object: | |
|
195 | ||
|
196 | .. sourcecode:: python | |
|
197 | ||
|
198 | # This code can be put in any Python module, it does not require IPython | |
|
199 | # itself to be running already. It only creates the magics subclass but | |
|
200 | # doesn't instantiate it yet. | |
|
201 | from __future__ import print_function | |
|
202 | from IPython.core.magic import (Magics, magics_class, line_magic, | |
|
203 | cell_magic, line_cell_magic) | |
|
204 | ||
|
205 | # The class MUST call this class decorator at creation time | |
|
206 | @magics_class | |
|
207 | class MyMagics(Magics): | |
|
208 | ||
|
209 | @line_magic | |
|
210 | def lmagic(self, line): | |
|
211 | "my line magic" | |
|
212 | print("Full access to the main IPython object:", self.shell) | |
|
213 | print("Variables in the user namespace:", list(self.shell.user_ns.keys())) | |
|
214 | return line | |
|
215 | ||
|
216 | @cell_magic | |
|
217 | def cmagic(self, line, cell): | |
|
218 | "my cell magic" | |
|
219 | return line, cell | |
|
220 | ||
|
221 | @line_cell_magic | |
|
222 | def lcmagic(self, line, cell=None): | |
|
223 | "Magic that works both as %lcmagic and as %%lcmagic" | |
|
224 | if cell is None: | |
|
225 | print("Called as line magic") | |
|
226 | return line | |
|
227 | else: | |
|
228 | print("Called as cell magic") | |
|
229 | return line, cell | |
|
230 | ||
|
231 | ||
|
232 | # In order to actually use these magics, you must register them with a | |
|
233 | # running IPython. This code must be placed in a file that is loaded once | |
|
234 | # IPython is up and running: | |
|
235 | ip = get_ipython() | |
|
236 | # You can register the class itself without instantiating it. IPython will | |
|
237 | # call the default constructor on it. | |
|
238 | ip.register_magics(MyMagics) | |
|
239 | ||
|
240 | If you want to create a class with a different constructor that holds | |
|
241 | additional state, then you should always call the parent constructor and | |
|
242 | instantiate the class yourself before registration: | |
|
243 | ||
|
244 | .. sourcecode:: python | |
|
245 | ||
|
246 | @magics_class | |
|
247 | class StatefulMagics(Magics): | |
|
248 | "Magics that hold additional state" | |
|
249 | ||
|
250 | def __init__(self, shell, data): | |
|
251 | # You must call the parent constructor | |
|
252 | super(StatefulMagics, self).__init__(shell) | |
|
253 | self.data = data | |
|
254 | ||
|
255 | # etc... | |
|
256 | ||
|
257 | # This class must then be registered with a manually created instance, | |
|
258 | # since its constructor has different arguments from the default: | |
|
259 | ip = get_ipython() | |
|
260 | magics = StatefulMagics(ip, some_data) | |
|
261 | ip.register_magics(magics) | |
|
262 | ||
|
263 | ||
|
264 | In earlier versions, IPython had an API for the creation of line magics (cell | |
|
265 | magics did not exist at the time) that required you to create functions with a | |
|
266 | method-looking signature and to manually pass both the function and the name. | |
|
267 | While this API is no longer recommended, it remains indefinitely supported for | |
|
268 | backwards compatibility purposes. With the old API, you'd create a magic as | |
|
269 | follows: | |
|
270 | ||
|
271 | .. sourcecode:: python | |
|
272 | ||
|
273 | def func(self, line): | |
|
274 | print("Line magic called with line:", line) | |
|
275 | print("IPython object:", self.shell) | |
|
276 | ||
|
277 | ip = get_ipython() | |
|
278 | # Declare this function as the magic %mycommand | |
|
279 | ip.define_magic('mycommand', func) | |
|
280 | ||
|
281 | 148 | Type ``%magic`` for more information, including a list of all available magic |
|
282 | 149 | functions at any time and their docstrings. You can also type |
|
283 | 150 | ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for |
@@ -287,6 +154,11 b' function you are interested in.' | |||
|
287 | 154 | The API documentation for the :mod:`IPython.core.magic` module contains the full |
|
288 | 155 | docstrings of all currently available magic commands. |
|
289 | 156 | |
|
157 | .. seealso:: | |
|
158 | ||
|
159 | :ref:`defining_magics` | |
|
160 | How to define and register additional magic functions | |
|
161 | ||
|
290 | 162 | |
|
291 | 163 | Access to the standard Python help |
|
292 | 164 | ---------------------------------- |
General Comments 0
You need to be logged in to leave comments.
Login now