##// END OF EJS Templates
Update the main documentation with new magics API....
Fernando Perez -
Show More
@@ -100,17 +100,45 b' IPython itself, plus a lot of system-type features. They are all'
100 100 prefixed with a % character, but parameters are given without
101 101 parentheses or quotes.
102 102
103 Example: typing ``%cd mydir`` changes your working directory to 'mydir', if it
104 exists.
105
106 If you have 'automagic' enabled (as it by default), you don't need
107 to type in the % explicitly. IPython will scan its internal list of
108 magic functions and call one if it exists. With automagic on you can
109 then just type ``cd mydir`` to go to directory 'mydir'. The automagic
110 system has the lowest possible precedence in name searches, so defining
111 an identifier with the same name as an existing magic function will
112 shadow it for automagic use. You can still access the shadowed magic
113 function by explicitly using the % character at the beginning of the line.
103 Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
104 only the rest of the current line, but all lines below them as well, in the
105 current execution block. Cell magics can in fact make arbitrary modifications
106 to the input they receive, which need not even be valid Python code at all.
107 They receive the whole block as a single string.
108
109 As a line magic example, the ``%cd`` magic works just like the OS command of
110 the same name::
111
112 In [8]: %cd
113 /home/fperez
114
115 The following uses the builtin ``timeit`` in cell mode::
116
117 In [10]: %%timeit x = range(10000)
118 ...: min(x)
119 ...: max(x)
120 ...:
121 1000 loops, best of 3: 438 us per loop
122
123 In this case, ``x = range(10000)`` is called as the line argument, and the
124 block with ``min(x)`` and ``max(x)`` is called as the cell body. The
125 ``timeit`` magic receives both.
126
127 If you have 'automagic' enabled (as it by default), you don't need to type in
128 the single ``%`` explicitly for line magics; IPython will scan its internal
129 list of magic functions and call one if it exists. With automagic on you can
130 then just type ``cd mydir`` to go to directory 'mydir'::
131
132 In [9]: cd mydir
133 /home/fperez/mydir
134
135 Note that cell magics *always* require an explicit ``%%`` prefix, automagic
136 calling only works for line magics.
137
138 The automagic system has the lowest possible precedence in name searches, so
139 defining an identifier with the same name as an existing magic function will
140 shadow it for automagic use. You can still access the shadowed magic function
141 by explicitly using the ``%`` character at the beginning of the line.
114 142
115 143 An example (with automagic on) should clarify all this:
116 144
@@ -137,24 +165,141 b' An example (with automagic on) should clarify all this:'
137 165
138 166 /home/fperez/ipython
139 167
140 You can define your own magic functions to extend the system. The
141 following example defines a new magic command, %impall:
168 Defining your own magics
169 ~~~~~~~~~~~~~~~~~~~~~~~~
170
171 There are two main ways to define your own magic functions: from standalone
172 functions and by inheriting from a base class provided by IPython:
173 :class:`IPython.core.magic.Magics`. Below we show code you can place in a file
174 that you load from your configuration, such as any file in the ``startup``
175 subdirectory of your default IPython profile.
176
177 First, let us see the simplest case. The following shows how to create a line
178 magic, a cell one and one that works in both modes, using just plain functions:
142 179
143 180 .. sourcecode:: python
144 181
182 from IPython.core.magic import (register_line_magic, register_cell_magic,
183 register_line_cell_magic)
184
185 @register_line_magic
186 def lmagic(line):
187 "my line magic"
188 return line
189
190 @register_cell_magic
191 def cmagic(line, cell):
192 "my cell magic"
193 return line, cell
194
195 @register_line_cell_magic
196 def lcmagic(line, cell=None):
197 "Magic that works both as %lcmagic and as %%lcmagic"
198 if cell is None:
199 print "Called as line magic"
200 return line
201 else:
202 print "Called as cell magic"
203 return line, cell
204
205 # We delete these to avoid name conflicts for automagic to work
206 del lmagic, lcmagic
207
208
209 You can also create magics of all three kinds by inheriting from the
210 :class:`IPython.core.magic.Magics` class. This lets you create magics that can
211 potentially hold state in between calls, and that have full access to the main
212 IPython object:
213
214 .. sourcecode:: python
215
216 # This code can be put in any Python module, it does not require IPython
217 # itself to be running already. It only creates the magics subclass but
218 # doesn't instantiate it yet.
219 from IPython.core.magic import (Magics, magics_class, line_magic,
220 cell_magic, line_cell_magic)
221
222 # The class MUST call this class decorator at creation time
223 @magics_class
224 class MyMagics(Magics):
225
226 @line_magic
227 def lmagic(self, line):
228 "my line magic"
229 print "Full access to the main IPython object:", self.shell
230 print "Variables in the user namespace:", self.user_ns.keys()
231 return line
232
233 @cell_magic
234 def cmagic(self, line, cell):
235 "my cell magic"
236 return line, cell
237
238 @line_cell_magic
239 def lcmagic(self, line, cell=None):
240 "Magic that works both as %lcmagic and as %%lcmagic"
241 if cell is None:
242 print "Called as line magic"
243 return line
244 else:
245 print "Called as cell magic"
246 return line, cell
247
248
249 # In order to actually use these magics, you must register them with a
250 # running IPython. This code must be placed in a file that is loaded once
251 # IPython is up and running:
145 252 ip = get_ipython()
253 # You can register the class itself without instantiating it. IPython will
254 # call the default constructor on it.
255 ip.register_magics(MyMagics)
146 256
147 def doimp(self, arg):
148 ip = self.api
149 ip.ex("import %s; reload(%s); from %s import *" % (arg,arg,arg) )
257 If you want to create a class with a different constructor that holds
258 additional state, then you should always call the parent constructor and
259 instantiate the class yourself before registration:
150 260
151 ip.define_magic('impall', doimp)
261 .. sourcecode:: python
262
263 @magics_class
264 class StatefulMagics(Magics):
265 "Magics that hold additional state"
266
267 def __init__(self, shell, data):
268 # You must call the parent constructor
269 super(StatefulMagics, self).__init__(shell)
270 self.data = data
271
272 # etc...
273
274 # This class must then be registered with a manually created instance,
275 # since its constructor has different arguments from the default:
276 ip = get_ipython()
277 magics = StatefulMagics(ip, some_data)
278 ip.register_magics(magics)
279
280
281 In earlier versions, IPython had an API for the creation of line magics (cell
282 magics did not exist at the time) that required you to create functions with a
283 method-looking signature and to manually pass both the function and the name.
284 While this API is no longer recommended, it remains indefinitely supported for
285 backwards compatibility purposes. With the old API, you'd create a magic as
286 follows:
287
288 .. sourcecode:: python
289
290 def func(self, line):
291 print "Line magic called with line:", line
292 print "IPython object:", self.shell
293
294 ip = get_ipython()
295 # Declare this function as the magic %mycommand
296 ip.define_magic('mycommand', func)
152 297
153 298 Type ``%magic`` for more information, including a list of all available magic
154 299 functions at any time and their docstrings. You can also type
155 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for information on
156 the '?' system) to get information about any particular magic function you are
157 interested in.
300 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
301 information on the '?' system) to get information about any particular magic
302 function you are interested in.
158 303
159 304 The API documentation for the :mod:`IPython.core.magic` module contains the full
160 305 docstrings of all currently available magic commands.
@@ -35,20 +35,42 b' Magic functions'
35 35 ===============
36 36
37 37 IPython has a set of predefined 'magic functions' that you can call with a
38 command line style syntax. These include:
38 command line style syntax. There are two kinds of magics, line-oriented and
39 cell-oriented. Line magics are prefixed with the ``%`` character and work much
40 like OS command-line calls: they get as an argument the rest of the line, where
41 arguments are passed without parentheses or quotes. Cell magics are prefixed
42 with a double ``%%``, and they are functions that get as an argument not only
43 the rest of the line, but also the lines below it in a separate argument.
44
45 The following examples show how to call the builtin ``timeit`` magic, both in
46 line and cell mode::
47
48 In [1]: %timeit range(1000)
49 100000 loops, best of 3: 7.76 us per loop
50
51 In [2]: %%timeit x = range(10000)
52 ...: max(x)
53 ...:
54 1000 loops, best of 3: 223 us per loop
55
56 The builtin magics include:
39 57
40 58 - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
41 59 ``%recall``, etc.
42 - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``, etc.
60 - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``,
61 etc.
43 62 - Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
44 63
45 You can always call these using the % prefix, and if you're typing one on a line
46 by itself, you can omit even that::
64 You can always call them using the % prefix, and if you're calling a line magic
65 on a line by itself, you can omit even that (cell magics must always have the
66 ``%%`` prefix)::
47 67
48 68 run thescript.py
49
50 For more details on any magic function, call ``%somemagic?`` to read its
51 docstring. To see all the available magic functions, call ``%lsmagic``.
69
70 A more detailed explanation of the magic system can be obtained by calling
71 ``%magic``, and for more details on any magic function, call ``%somemagic?`` to
72 read its docstring. To see all the available magic functions, call
73 ``%lsmagic``.
52 74
53 75 Running and Editing
54 76 -------------------
General Comments 0
You need to be logged in to leave comments. Login now