##// END OF EJS Templates
DOC: add a note in %profile about %prun
Paul Ivanov -
Show More
@@ -1,648 +1,654 b''
1 """Implementation of basic magic functions.
1 """Implementation of basic magic functions.
2 """
2 """
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Copyright (c) 2012 The IPython Development Team.
4 # Copyright (c) 2012 The IPython Development Team.
5 #
5 #
6 # Distributed under the terms of the Modified BSD License.
6 # Distributed under the terms of the Modified BSD License.
7 #
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10
10
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12 # Imports
12 # Imports
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 from __future__ import print_function
14 from __future__ import print_function
15
15
16 # Stdlib
16 # Stdlib
17 import io
17 import io
18 import json
18 import json
19 import sys
19 import sys
20 from pprint import pformat
20 from pprint import pformat
21
21
22 # Our own packages
22 # Our own packages
23 from IPython.core import magic_arguments, page
23 from IPython.core import magic_arguments, page
24 from IPython.core.error import UsageError
24 from IPython.core.error import UsageError
25 from IPython.core.magic import Magics, magics_class, line_magic, magic_escapes
25 from IPython.core.magic import Magics, magics_class, line_magic, magic_escapes
26 from IPython.utils.text import format_screen, dedent, indent
26 from IPython.utils.text import format_screen, dedent, indent
27 from IPython.testing.skipdoctest import skip_doctest
27 from IPython.testing.skipdoctest import skip_doctest
28 from IPython.utils.ipstruct import Struct
28 from IPython.utils.ipstruct import Struct
29 from IPython.utils.path import unquote_filename
29 from IPython.utils.path import unquote_filename
30 from IPython.utils.py3compat import unicode_type
30 from IPython.utils.py3compat import unicode_type
31 from IPython.utils.warn import warn, error
31 from IPython.utils.warn import warn, error
32
32
33 #-----------------------------------------------------------------------------
33 #-----------------------------------------------------------------------------
34 # Magics class implementation
34 # Magics class implementation
35 #-----------------------------------------------------------------------------
35 #-----------------------------------------------------------------------------
36
36
37 class MagicsDisplay(object):
37 class MagicsDisplay(object):
38 def __init__(self, magics_manager):
38 def __init__(self, magics_manager):
39 self.magics_manager = magics_manager
39 self.magics_manager = magics_manager
40
40
41 def _lsmagic(self):
41 def _lsmagic(self):
42 """The main implementation of the %lsmagic"""
42 """The main implementation of the %lsmagic"""
43 mesc = magic_escapes['line']
43 mesc = magic_escapes['line']
44 cesc = magic_escapes['cell']
44 cesc = magic_escapes['cell']
45 mman = self.magics_manager
45 mman = self.magics_manager
46 magics = mman.lsmagic()
46 magics = mman.lsmagic()
47 out = ['Available line magics:',
47 out = ['Available line magics:',
48 mesc + (' '+mesc).join(sorted(magics['line'])),
48 mesc + (' '+mesc).join(sorted(magics['line'])),
49 '',
49 '',
50 'Available cell magics:',
50 'Available cell magics:',
51 cesc + (' '+cesc).join(sorted(magics['cell'])),
51 cesc + (' '+cesc).join(sorted(magics['cell'])),
52 '',
52 '',
53 mman.auto_status()]
53 mman.auto_status()]
54 return '\n'.join(out)
54 return '\n'.join(out)
55
55
56 def _repr_pretty_(self, p, cycle):
56 def _repr_pretty_(self, p, cycle):
57 p.text(self._lsmagic())
57 p.text(self._lsmagic())
58
58
59 def __str__(self):
59 def __str__(self):
60 return self._lsmagic()
60 return self._lsmagic()
61
61
62 def _jsonable(self):
62 def _jsonable(self):
63 """turn magics dict into jsonable dict of the same structure
63 """turn magics dict into jsonable dict of the same structure
64
64
65 replaces object instances with their class names as strings
65 replaces object instances with their class names as strings
66 """
66 """
67 magic_dict = {}
67 magic_dict = {}
68 mman = self.magics_manager
68 mman = self.magics_manager
69 magics = mman.lsmagic()
69 magics = mman.lsmagic()
70 for key, subdict in magics.items():
70 for key, subdict in magics.items():
71 d = {}
71 d = {}
72 magic_dict[key] = d
72 magic_dict[key] = d
73 for name, obj in subdict.items():
73 for name, obj in subdict.items():
74 try:
74 try:
75 classname = obj.__self__.__class__.__name__
75 classname = obj.__self__.__class__.__name__
76 except AttributeError:
76 except AttributeError:
77 classname = 'Other'
77 classname = 'Other'
78
78
79 d[name] = classname
79 d[name] = classname
80 return magic_dict
80 return magic_dict
81
81
82 def _repr_json_(self):
82 def _repr_json_(self):
83 return json.dumps(self._jsonable())
83 return json.dumps(self._jsonable())
84
84
85
85
86 @magics_class
86 @magics_class
87 class BasicMagics(Magics):
87 class BasicMagics(Magics):
88 """Magics that provide central IPython functionality.
88 """Magics that provide central IPython functionality.
89
89
90 These are various magics that don't fit into specific categories but that
90 These are various magics that don't fit into specific categories but that
91 are all part of the base 'IPython experience'."""
91 are all part of the base 'IPython experience'."""
92
92
93 @magic_arguments.magic_arguments()
93 @magic_arguments.magic_arguments()
94 @magic_arguments.argument(
94 @magic_arguments.argument(
95 '-l', '--line', action='store_true',
95 '-l', '--line', action='store_true',
96 help="""Create a line magic alias."""
96 help="""Create a line magic alias."""
97 )
97 )
98 @magic_arguments.argument(
98 @magic_arguments.argument(
99 '-c', '--cell', action='store_true',
99 '-c', '--cell', action='store_true',
100 help="""Create a cell magic alias."""
100 help="""Create a cell magic alias."""
101 )
101 )
102 @magic_arguments.argument(
102 @magic_arguments.argument(
103 'name',
103 'name',
104 help="""Name of the magic to be created."""
104 help="""Name of the magic to be created."""
105 )
105 )
106 @magic_arguments.argument(
106 @magic_arguments.argument(
107 'target',
107 'target',
108 help="""Name of the existing line or cell magic."""
108 help="""Name of the existing line or cell magic."""
109 )
109 )
110 @line_magic
110 @line_magic
111 def alias_magic(self, line=''):
111 def alias_magic(self, line=''):
112 """Create an alias for an existing line or cell magic.
112 """Create an alias for an existing line or cell magic.
113
113
114 Examples
114 Examples
115 --------
115 --------
116 ::
116 ::
117
117
118 In [1]: %alias_magic t timeit
118 In [1]: %alias_magic t timeit
119 Created `%t` as an alias for `%timeit`.
119 Created `%t` as an alias for `%timeit`.
120 Created `%%t` as an alias for `%%timeit`.
120 Created `%%t` as an alias for `%%timeit`.
121
121
122 In [2]: %t -n1 pass
122 In [2]: %t -n1 pass
123 1 loops, best of 3: 954 ns per loop
123 1 loops, best of 3: 954 ns per loop
124
124
125 In [3]: %%t -n1
125 In [3]: %%t -n1
126 ...: pass
126 ...: pass
127 ...:
127 ...:
128 1 loops, best of 3: 954 ns per loop
128 1 loops, best of 3: 954 ns per loop
129
129
130 In [4]: %alias_magic --cell whereami pwd
130 In [4]: %alias_magic --cell whereami pwd
131 UsageError: Cell magic function `%%pwd` not found.
131 UsageError: Cell magic function `%%pwd` not found.
132 In [5]: %alias_magic --line whereami pwd
132 In [5]: %alias_magic --line whereami pwd
133 Created `%whereami` as an alias for `%pwd`.
133 Created `%whereami` as an alias for `%pwd`.
134
134
135 In [6]: %whereami
135 In [6]: %whereami
136 Out[6]: u'/home/testuser'
136 Out[6]: u'/home/testuser'
137 """
137 """
138 args = magic_arguments.parse_argstring(self.alias_magic, line)
138 args = magic_arguments.parse_argstring(self.alias_magic, line)
139 shell = self.shell
139 shell = self.shell
140 mman = self.shell.magics_manager
140 mman = self.shell.magics_manager
141 escs = ''.join(magic_escapes.values())
141 escs = ''.join(magic_escapes.values())
142
142
143 target = args.target.lstrip(escs)
143 target = args.target.lstrip(escs)
144 name = args.name.lstrip(escs)
144 name = args.name.lstrip(escs)
145
145
146 # Find the requested magics.
146 # Find the requested magics.
147 m_line = shell.find_magic(target, 'line')
147 m_line = shell.find_magic(target, 'line')
148 m_cell = shell.find_magic(target, 'cell')
148 m_cell = shell.find_magic(target, 'cell')
149 if args.line and m_line is None:
149 if args.line and m_line is None:
150 raise UsageError('Line magic function `%s%s` not found.' %
150 raise UsageError('Line magic function `%s%s` not found.' %
151 (magic_escapes['line'], target))
151 (magic_escapes['line'], target))
152 if args.cell and m_cell is None:
152 if args.cell and m_cell is None:
153 raise UsageError('Cell magic function `%s%s` not found.' %
153 raise UsageError('Cell magic function `%s%s` not found.' %
154 (magic_escapes['cell'], target))
154 (magic_escapes['cell'], target))
155
155
156 # If --line and --cell are not specified, default to the ones
156 # If --line and --cell are not specified, default to the ones
157 # that are available.
157 # that are available.
158 if not args.line and not args.cell:
158 if not args.line and not args.cell:
159 if not m_line and not m_cell:
159 if not m_line and not m_cell:
160 raise UsageError(
160 raise UsageError(
161 'No line or cell magic with name `%s` found.' % target
161 'No line or cell magic with name `%s` found.' % target
162 )
162 )
163 args.line = bool(m_line)
163 args.line = bool(m_line)
164 args.cell = bool(m_cell)
164 args.cell = bool(m_cell)
165
165
166 if args.line:
166 if args.line:
167 mman.register_alias(name, target, 'line')
167 mman.register_alias(name, target, 'line')
168 print('Created `%s%s` as an alias for `%s%s`.' % (
168 print('Created `%s%s` as an alias for `%s%s`.' % (
169 magic_escapes['line'], name,
169 magic_escapes['line'], name,
170 magic_escapes['line'], target))
170 magic_escapes['line'], target))
171
171
172 if args.cell:
172 if args.cell:
173 mman.register_alias(name, target, 'cell')
173 mman.register_alias(name, target, 'cell')
174 print('Created `%s%s` as an alias for `%s%s`.' % (
174 print('Created `%s%s` as an alias for `%s%s`.' % (
175 magic_escapes['cell'], name,
175 magic_escapes['cell'], name,
176 magic_escapes['cell'], target))
176 magic_escapes['cell'], target))
177
177
178 @line_magic
178 @line_magic
179 def lsmagic(self, parameter_s=''):
179 def lsmagic(self, parameter_s=''):
180 """List currently available magic functions."""
180 """List currently available magic functions."""
181 return MagicsDisplay(self.shell.magics_manager)
181 return MagicsDisplay(self.shell.magics_manager)
182
182
183 def _magic_docs(self, brief=False, rest=False):
183 def _magic_docs(self, brief=False, rest=False):
184 """Return docstrings from magic functions."""
184 """Return docstrings from magic functions."""
185 mman = self.shell.magics_manager
185 mman = self.shell.magics_manager
186 docs = mman.lsmagic_docs(brief, missing='No documentation')
186 docs = mman.lsmagic_docs(brief, missing='No documentation')
187
187
188 if rest:
188 if rest:
189 format_string = '**%s%s**::\n\n%s\n\n'
189 format_string = '**%s%s**::\n\n%s\n\n'
190 else:
190 else:
191 format_string = '%s%s:\n%s\n'
191 format_string = '%s%s:\n%s\n'
192
192
193 return ''.join(
193 return ''.join(
194 [format_string % (magic_escapes['line'], fname,
194 [format_string % (magic_escapes['line'], fname,
195 indent(dedent(fndoc)))
195 indent(dedent(fndoc)))
196 for fname, fndoc in sorted(docs['line'].items())]
196 for fname, fndoc in sorted(docs['line'].items())]
197 +
197 +
198 [format_string % (magic_escapes['cell'], fname,
198 [format_string % (magic_escapes['cell'], fname,
199 indent(dedent(fndoc)))
199 indent(dedent(fndoc)))
200 for fname, fndoc in sorted(docs['cell'].items())]
200 for fname, fndoc in sorted(docs['cell'].items())]
201 )
201 )
202
202
203 @line_magic
203 @line_magic
204 def magic(self, parameter_s=''):
204 def magic(self, parameter_s=''):
205 """Print information about the magic function system.
205 """Print information about the magic function system.
206
206
207 Supported formats: -latex, -brief, -rest
207 Supported formats: -latex, -brief, -rest
208 """
208 """
209
209
210 mode = ''
210 mode = ''
211 try:
211 try:
212 mode = parameter_s.split()[0][1:]
212 mode = parameter_s.split()[0][1:]
213 if mode == 'rest':
213 if mode == 'rest':
214 rest_docs = []
214 rest_docs = []
215 except IndexError:
215 except IndexError:
216 pass
216 pass
217
217
218 brief = (mode == 'brief')
218 brief = (mode == 'brief')
219 rest = (mode == 'rest')
219 rest = (mode == 'rest')
220 magic_docs = self._magic_docs(brief, rest)
220 magic_docs = self._magic_docs(brief, rest)
221
221
222 if mode == 'latex':
222 if mode == 'latex':
223 print(self.format_latex(magic_docs))
223 print(self.format_latex(magic_docs))
224 return
224 return
225 else:
225 else:
226 magic_docs = format_screen(magic_docs)
226 magic_docs = format_screen(magic_docs)
227
227
228 out = ["""
228 out = ["""
229 IPython's 'magic' functions
229 IPython's 'magic' functions
230 ===========================
230 ===========================
231
231
232 The magic function system provides a series of functions which allow you to
232 The magic function system provides a series of functions which allow you to
233 control the behavior of IPython itself, plus a lot of system-type
233 control the behavior of IPython itself, plus a lot of system-type
234 features. There are two kinds of magics, line-oriented and cell-oriented.
234 features. There are two kinds of magics, line-oriented and cell-oriented.
235
235
236 Line magics are prefixed with the % character and work much like OS
236 Line magics are prefixed with the % character and work much like OS
237 command-line calls: they get as an argument the rest of the line, where
237 command-line calls: they get as an argument the rest of the line, where
238 arguments are passed without parentheses or quotes. For example, this will
238 arguments are passed without parentheses or quotes. For example, this will
239 time the given statement::
239 time the given statement::
240
240
241 %timeit range(1000)
241 %timeit range(1000)
242
242
243 Cell magics are prefixed with a double %%, and they are functions that get as
243 Cell magics are prefixed with a double %%, and they are functions that get as
244 an argument not only the rest of the line, but also the lines below it in a
244 an argument not only the rest of the line, but also the lines below it in a
245 separate argument. These magics are called with two arguments: the rest of the
245 separate argument. These magics are called with two arguments: the rest of the
246 call line and the body of the cell, consisting of the lines below the first.
246 call line and the body of the cell, consisting of the lines below the first.
247 For example::
247 For example::
248
248
249 %%timeit x = numpy.random.randn((100, 100))
249 %%timeit x = numpy.random.randn((100, 100))
250 numpy.linalg.svd(x)
250 numpy.linalg.svd(x)
251
251
252 will time the execution of the numpy svd routine, running the assignment of x
252 will time the execution of the numpy svd routine, running the assignment of x
253 as part of the setup phase, which is not timed.
253 as part of the setup phase, which is not timed.
254
254
255 In a line-oriented client (the terminal or Qt console IPython), starting a new
255 In a line-oriented client (the terminal or Qt console IPython), starting a new
256 input with %% will automatically enter cell mode, and IPython will continue
256 input with %% will automatically enter cell mode, and IPython will continue
257 reading input until a blank line is given. In the notebook, simply type the
257 reading input until a blank line is given. In the notebook, simply type the
258 whole cell as one entity, but keep in mind that the %% escape can only be at
258 whole cell as one entity, but keep in mind that the %% escape can only be at
259 the very start of the cell.
259 the very start of the cell.
260
260
261 NOTE: If you have 'automagic' enabled (via the command line option or with the
261 NOTE: If you have 'automagic' enabled (via the command line option or with the
262 %automagic function), you don't need to type in the % explicitly for line
262 %automagic function), you don't need to type in the % explicitly for line
263 magics; cell magics always require an explicit '%%' escape. By default,
263 magics; cell magics always require an explicit '%%' escape. By default,
264 IPython ships with automagic on, so you should only rarely need the % escape.
264 IPython ships with automagic on, so you should only rarely need the % escape.
265
265
266 Example: typing '%cd mydir' (without the quotes) changes you working directory
266 Example: typing '%cd mydir' (without the quotes) changes you working directory
267 to 'mydir', if it exists.
267 to 'mydir', if it exists.
268
268
269 For a list of the available magic functions, use %lsmagic. For a description
269 For a list of the available magic functions, use %lsmagic. For a description
270 of any of them, type %magic_name?, e.g. '%cd?'.
270 of any of them, type %magic_name?, e.g. '%cd?'.
271
271
272 Currently the magic system has the following functions:""",
272 Currently the magic system has the following functions:""",
273 magic_docs,
273 magic_docs,
274 "Summary of magic functions (from %slsmagic):" % magic_escapes['line'],
274 "Summary of magic functions (from %slsmagic):" % magic_escapes['line'],
275 str(self.lsmagic()),
275 str(self.lsmagic()),
276 ]
276 ]
277 page.page('\n'.join(out))
277 page.page('\n'.join(out))
278
278
279
279
280 @line_magic
280 @line_magic
281 def page(self, parameter_s=''):
281 def page(self, parameter_s=''):
282 """Pretty print the object and display it through a pager.
282 """Pretty print the object and display it through a pager.
283
283
284 %page [options] OBJECT
284 %page [options] OBJECT
285
285
286 If no object is given, use _ (last output).
286 If no object is given, use _ (last output).
287
287
288 Options:
288 Options:
289
289
290 -r: page str(object), don't pretty-print it."""
290 -r: page str(object), don't pretty-print it."""
291
291
292 # After a function contributed by Olivier Aubert, slightly modified.
292 # After a function contributed by Olivier Aubert, slightly modified.
293
293
294 # Process options/args
294 # Process options/args
295 opts, args = self.parse_options(parameter_s, 'r')
295 opts, args = self.parse_options(parameter_s, 'r')
296 raw = 'r' in opts
296 raw = 'r' in opts
297
297
298 oname = args and args or '_'
298 oname = args and args or '_'
299 info = self.shell._ofind(oname)
299 info = self.shell._ofind(oname)
300 if info['found']:
300 if info['found']:
301 txt = (raw and str or pformat)( info['obj'] )
301 txt = (raw and str or pformat)( info['obj'] )
302 page.page(txt)
302 page.page(txt)
303 else:
303 else:
304 print('Object `%s` not found' % oname)
304 print('Object `%s` not found' % oname)
305
305
306 @line_magic
306 @line_magic
307 def profile(self, parameter_s=''):
307 def profile(self, parameter_s=''):
308 """Print your currently active IPython profile."""
308 """Print your currently active IPython profile.
309
310 See Also
311 --------
312 prun : run code using the Python profiler
313 (:class:`~IPython.core.magics.execution.ExecutionMagics.prun`)
314 """
309 from IPython.core.application import BaseIPythonApplication
315 from IPython.core.application import BaseIPythonApplication
310 if BaseIPythonApplication.initialized():
316 if BaseIPythonApplication.initialized():
311 print(BaseIPythonApplication.instance().profile)
317 print(BaseIPythonApplication.instance().profile)
312 else:
318 else:
313 error("profile is an application-level value, but you don't appear to be in an IPython application")
319 error("profile is an application-level value, but you don't appear to be in an IPython application")
314
320
315 @line_magic
321 @line_magic
316 def pprint(self, parameter_s=''):
322 def pprint(self, parameter_s=''):
317 """Toggle pretty printing on/off."""
323 """Toggle pretty printing on/off."""
318 ptformatter = self.shell.display_formatter.formatters['text/plain']
324 ptformatter = self.shell.display_formatter.formatters['text/plain']
319 ptformatter.pprint = bool(1 - ptformatter.pprint)
325 ptformatter.pprint = bool(1 - ptformatter.pprint)
320 print('Pretty printing has been turned',
326 print('Pretty printing has been turned',
321 ['OFF','ON'][ptformatter.pprint])
327 ['OFF','ON'][ptformatter.pprint])
322
328
323 @line_magic
329 @line_magic
324 def colors(self, parameter_s=''):
330 def colors(self, parameter_s=''):
325 """Switch color scheme for prompts, info system and exception handlers.
331 """Switch color scheme for prompts, info system and exception handlers.
326
332
327 Currently implemented schemes: NoColor, Linux, LightBG.
333 Currently implemented schemes: NoColor, Linux, LightBG.
328
334
329 Color scheme names are not case-sensitive.
335 Color scheme names are not case-sensitive.
330
336
331 Examples
337 Examples
332 --------
338 --------
333 To get a plain black and white terminal::
339 To get a plain black and white terminal::
334
340
335 %colors nocolor
341 %colors nocolor
336 """
342 """
337 def color_switch_err(name):
343 def color_switch_err(name):
338 warn('Error changing %s color schemes.\n%s' %
344 warn('Error changing %s color schemes.\n%s' %
339 (name, sys.exc_info()[1]))
345 (name, sys.exc_info()[1]))
340
346
341
347
342 new_scheme = parameter_s.strip()
348 new_scheme = parameter_s.strip()
343 if not new_scheme:
349 if not new_scheme:
344 raise UsageError(
350 raise UsageError(
345 "%colors: you must specify a color scheme. See '%colors?'")
351 "%colors: you must specify a color scheme. See '%colors?'")
346 # local shortcut
352 # local shortcut
347 shell = self.shell
353 shell = self.shell
348
354
349 import IPython.utils.rlineimpl as readline
355 import IPython.utils.rlineimpl as readline
350
356
351 if not shell.colors_force and \
357 if not shell.colors_force and \
352 not readline.have_readline and \
358 not readline.have_readline and \
353 (sys.platform == "win32" or sys.platform == "cli"):
359 (sys.platform == "win32" or sys.platform == "cli"):
354 msg = """\
360 msg = """\
355 Proper color support under MS Windows requires the pyreadline library.
361 Proper color support under MS Windows requires the pyreadline library.
356 You can find it at:
362 You can find it at:
357 http://ipython.org/pyreadline.html
363 http://ipython.org/pyreadline.html
358 Gary's readline needs the ctypes module, from:
364 Gary's readline needs the ctypes module, from:
359 http://starship.python.net/crew/theller/ctypes
365 http://starship.python.net/crew/theller/ctypes
360 (Note that ctypes is already part of Python versions 2.5 and newer).
366 (Note that ctypes is already part of Python versions 2.5 and newer).
361
367
362 Defaulting color scheme to 'NoColor'"""
368 Defaulting color scheme to 'NoColor'"""
363 new_scheme = 'NoColor'
369 new_scheme = 'NoColor'
364 warn(msg)
370 warn(msg)
365
371
366 # readline option is 0
372 # readline option is 0
367 if not shell.colors_force and not shell.has_readline:
373 if not shell.colors_force and not shell.has_readline:
368 new_scheme = 'NoColor'
374 new_scheme = 'NoColor'
369
375
370 # Set prompt colors
376 # Set prompt colors
371 try:
377 try:
372 shell.prompt_manager.color_scheme = new_scheme
378 shell.prompt_manager.color_scheme = new_scheme
373 except:
379 except:
374 color_switch_err('prompt')
380 color_switch_err('prompt')
375 else:
381 else:
376 shell.colors = \
382 shell.colors = \
377 shell.prompt_manager.color_scheme_table.active_scheme_name
383 shell.prompt_manager.color_scheme_table.active_scheme_name
378 # Set exception colors
384 # Set exception colors
379 try:
385 try:
380 shell.InteractiveTB.set_colors(scheme = new_scheme)
386 shell.InteractiveTB.set_colors(scheme = new_scheme)
381 shell.SyntaxTB.set_colors(scheme = new_scheme)
387 shell.SyntaxTB.set_colors(scheme = new_scheme)
382 except:
388 except:
383 color_switch_err('exception')
389 color_switch_err('exception')
384
390
385 # Set info (for 'object?') colors
391 # Set info (for 'object?') colors
386 if shell.color_info:
392 if shell.color_info:
387 try:
393 try:
388 shell.inspector.set_active_scheme(new_scheme)
394 shell.inspector.set_active_scheme(new_scheme)
389 except:
395 except:
390 color_switch_err('object inspector')
396 color_switch_err('object inspector')
391 else:
397 else:
392 shell.inspector.set_active_scheme('NoColor')
398 shell.inspector.set_active_scheme('NoColor')
393
399
394 @line_magic
400 @line_magic
395 def xmode(self, parameter_s=''):
401 def xmode(self, parameter_s=''):
396 """Switch modes for the exception handlers.
402 """Switch modes for the exception handlers.
397
403
398 Valid modes: Plain, Context and Verbose.
404 Valid modes: Plain, Context and Verbose.
399
405
400 If called without arguments, acts as a toggle."""
406 If called without arguments, acts as a toggle."""
401
407
402 def xmode_switch_err(name):
408 def xmode_switch_err(name):
403 warn('Error changing %s exception modes.\n%s' %
409 warn('Error changing %s exception modes.\n%s' %
404 (name,sys.exc_info()[1]))
410 (name,sys.exc_info()[1]))
405
411
406 shell = self.shell
412 shell = self.shell
407 new_mode = parameter_s.strip().capitalize()
413 new_mode = parameter_s.strip().capitalize()
408 try:
414 try:
409 shell.InteractiveTB.set_mode(mode=new_mode)
415 shell.InteractiveTB.set_mode(mode=new_mode)
410 print('Exception reporting mode:',shell.InteractiveTB.mode)
416 print('Exception reporting mode:',shell.InteractiveTB.mode)
411 except:
417 except:
412 xmode_switch_err('user')
418 xmode_switch_err('user')
413
419
414 @line_magic
420 @line_magic
415 def quickref(self,arg):
421 def quickref(self,arg):
416 """ Show a quick reference sheet """
422 """ Show a quick reference sheet """
417 from IPython.core.usage import quick_reference
423 from IPython.core.usage import quick_reference
418 qr = quick_reference + self._magic_docs(brief=True)
424 qr = quick_reference + self._magic_docs(brief=True)
419 page.page(qr)
425 page.page(qr)
420
426
421 @line_magic
427 @line_magic
422 def doctest_mode(self, parameter_s=''):
428 def doctest_mode(self, parameter_s=''):
423 """Toggle doctest mode on and off.
429 """Toggle doctest mode on and off.
424
430
425 This mode is intended to make IPython behave as much as possible like a
431 This mode is intended to make IPython behave as much as possible like a
426 plain Python shell, from the perspective of how its prompts, exceptions
432 plain Python shell, from the perspective of how its prompts, exceptions
427 and output look. This makes it easy to copy and paste parts of a
433 and output look. This makes it easy to copy and paste parts of a
428 session into doctests. It does so by:
434 session into doctests. It does so by:
429
435
430 - Changing the prompts to the classic ``>>>`` ones.
436 - Changing the prompts to the classic ``>>>`` ones.
431 - Changing the exception reporting mode to 'Plain'.
437 - Changing the exception reporting mode to 'Plain'.
432 - Disabling pretty-printing of output.
438 - Disabling pretty-printing of output.
433
439
434 Note that IPython also supports the pasting of code snippets that have
440 Note that IPython also supports the pasting of code snippets that have
435 leading '>>>' and '...' prompts in them. This means that you can paste
441 leading '>>>' and '...' prompts in them. This means that you can paste
436 doctests from files or docstrings (even if they have leading
442 doctests from files or docstrings (even if they have leading
437 whitespace), and the code will execute correctly. You can then use
443 whitespace), and the code will execute correctly. You can then use
438 '%history -t' to see the translated history; this will give you the
444 '%history -t' to see the translated history; this will give you the
439 input after removal of all the leading prompts and whitespace, which
445 input after removal of all the leading prompts and whitespace, which
440 can be pasted back into an editor.
446 can be pasted back into an editor.
441
447
442 With these features, you can switch into this mode easily whenever you
448 With these features, you can switch into this mode easily whenever you
443 need to do testing and changes to doctests, without having to leave
449 need to do testing and changes to doctests, without having to leave
444 your existing IPython session.
450 your existing IPython session.
445 """
451 """
446
452
447 # Shorthands
453 # Shorthands
448 shell = self.shell
454 shell = self.shell
449 pm = shell.prompt_manager
455 pm = shell.prompt_manager
450 meta = shell.meta
456 meta = shell.meta
451 disp_formatter = self.shell.display_formatter
457 disp_formatter = self.shell.display_formatter
452 ptformatter = disp_formatter.formatters['text/plain']
458 ptformatter = disp_formatter.formatters['text/plain']
453 # dstore is a data store kept in the instance metadata bag to track any
459 # dstore is a data store kept in the instance metadata bag to track any
454 # changes we make, so we can undo them later.
460 # changes we make, so we can undo them later.
455 dstore = meta.setdefault('doctest_mode',Struct())
461 dstore = meta.setdefault('doctest_mode',Struct())
456 save_dstore = dstore.setdefault
462 save_dstore = dstore.setdefault
457
463
458 # save a few values we'll need to recover later
464 # save a few values we'll need to recover later
459 mode = save_dstore('mode',False)
465 mode = save_dstore('mode',False)
460 save_dstore('rc_pprint',ptformatter.pprint)
466 save_dstore('rc_pprint',ptformatter.pprint)
461 save_dstore('xmode',shell.InteractiveTB.mode)
467 save_dstore('xmode',shell.InteractiveTB.mode)
462 save_dstore('rc_separate_out',shell.separate_out)
468 save_dstore('rc_separate_out',shell.separate_out)
463 save_dstore('rc_separate_out2',shell.separate_out2)
469 save_dstore('rc_separate_out2',shell.separate_out2)
464 save_dstore('rc_prompts_pad_left',pm.justify)
470 save_dstore('rc_prompts_pad_left',pm.justify)
465 save_dstore('rc_separate_in',shell.separate_in)
471 save_dstore('rc_separate_in',shell.separate_in)
466 save_dstore('rc_active_types',disp_formatter.active_types)
472 save_dstore('rc_active_types',disp_formatter.active_types)
467 save_dstore('prompt_templates',(pm.in_template, pm.in2_template, pm.out_template))
473 save_dstore('prompt_templates',(pm.in_template, pm.in2_template, pm.out_template))
468
474
469 if mode == False:
475 if mode == False:
470 # turn on
476 # turn on
471 pm.in_template = '>>> '
477 pm.in_template = '>>> '
472 pm.in2_template = '... '
478 pm.in2_template = '... '
473 pm.out_template = ''
479 pm.out_template = ''
474
480
475 # Prompt separators like plain python
481 # Prompt separators like plain python
476 shell.separate_in = ''
482 shell.separate_in = ''
477 shell.separate_out = ''
483 shell.separate_out = ''
478 shell.separate_out2 = ''
484 shell.separate_out2 = ''
479
485
480 pm.justify = False
486 pm.justify = False
481
487
482 ptformatter.pprint = False
488 ptformatter.pprint = False
483 disp_formatter.active_types = ['text/plain']
489 disp_formatter.active_types = ['text/plain']
484
490
485 shell.magic('xmode Plain')
491 shell.magic('xmode Plain')
486 else:
492 else:
487 # turn off
493 # turn off
488 pm.in_template, pm.in2_template, pm.out_template = dstore.prompt_templates
494 pm.in_template, pm.in2_template, pm.out_template = dstore.prompt_templates
489
495
490 shell.separate_in = dstore.rc_separate_in
496 shell.separate_in = dstore.rc_separate_in
491
497
492 shell.separate_out = dstore.rc_separate_out
498 shell.separate_out = dstore.rc_separate_out
493 shell.separate_out2 = dstore.rc_separate_out2
499 shell.separate_out2 = dstore.rc_separate_out2
494
500
495 pm.justify = dstore.rc_prompts_pad_left
501 pm.justify = dstore.rc_prompts_pad_left
496
502
497 ptformatter.pprint = dstore.rc_pprint
503 ptformatter.pprint = dstore.rc_pprint
498 disp_formatter.active_types = dstore.rc_active_types
504 disp_formatter.active_types = dstore.rc_active_types
499
505
500 shell.magic('xmode ' + dstore.xmode)
506 shell.magic('xmode ' + dstore.xmode)
501
507
502 # Store new mode and inform
508 # Store new mode and inform
503 dstore.mode = bool(1-int(mode))
509 dstore.mode = bool(1-int(mode))
504 mode_label = ['OFF','ON'][dstore.mode]
510 mode_label = ['OFF','ON'][dstore.mode]
505 print('Doctest mode is:', mode_label)
511 print('Doctest mode is:', mode_label)
506
512
507 @line_magic
513 @line_magic
508 def gui(self, parameter_s=''):
514 def gui(self, parameter_s=''):
509 """Enable or disable IPython GUI event loop integration.
515 """Enable or disable IPython GUI event loop integration.
510
516
511 %gui [GUINAME]
517 %gui [GUINAME]
512
518
513 This magic replaces IPython's threaded shells that were activated
519 This magic replaces IPython's threaded shells that were activated
514 using the (pylab/wthread/etc.) command line flags. GUI toolkits
520 using the (pylab/wthread/etc.) command line flags. GUI toolkits
515 can now be enabled at runtime and keyboard
521 can now be enabled at runtime and keyboard
516 interrupts should work without any problems. The following toolkits
522 interrupts should work without any problems. The following toolkits
517 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
523 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
518
524
519 %gui wx # enable wxPython event loop integration
525 %gui wx # enable wxPython event loop integration
520 %gui qt4|qt # enable PyQt4 event loop integration
526 %gui qt4|qt # enable PyQt4 event loop integration
521 %gui gtk # enable PyGTK event loop integration
527 %gui gtk # enable PyGTK event loop integration
522 %gui gtk3 # enable Gtk3 event loop integration
528 %gui gtk3 # enable Gtk3 event loop integration
523 %gui tk # enable Tk event loop integration
529 %gui tk # enable Tk event loop integration
524 %gui osx # enable Cocoa event loop integration
530 %gui osx # enable Cocoa event loop integration
525 # (requires %matplotlib 1.1)
531 # (requires %matplotlib 1.1)
526 %gui # disable all event loop integration
532 %gui # disable all event loop integration
527
533
528 WARNING: after any of these has been called you can simply create
534 WARNING: after any of these has been called you can simply create
529 an application object, but DO NOT start the event loop yourself, as
535 an application object, but DO NOT start the event loop yourself, as
530 we have already handled that.
536 we have already handled that.
531 """
537 """
532 opts, arg = self.parse_options(parameter_s, '')
538 opts, arg = self.parse_options(parameter_s, '')
533 if arg=='': arg = None
539 if arg=='': arg = None
534 try:
540 try:
535 return self.shell.enable_gui(arg)
541 return self.shell.enable_gui(arg)
536 except Exception as e:
542 except Exception as e:
537 # print simple error message, rather than traceback if we can't
543 # print simple error message, rather than traceback if we can't
538 # hook up the GUI
544 # hook up the GUI
539 error(str(e))
545 error(str(e))
540
546
541 @skip_doctest
547 @skip_doctest
542 @line_magic
548 @line_magic
543 def precision(self, s=''):
549 def precision(self, s=''):
544 """Set floating point precision for pretty printing.
550 """Set floating point precision for pretty printing.
545
551
546 Can set either integer precision or a format string.
552 Can set either integer precision or a format string.
547
553
548 If numpy has been imported and precision is an int,
554 If numpy has been imported and precision is an int,
549 numpy display precision will also be set, via ``numpy.set_printoptions``.
555 numpy display precision will also be set, via ``numpy.set_printoptions``.
550
556
551 If no argument is given, defaults will be restored.
557 If no argument is given, defaults will be restored.
552
558
553 Examples
559 Examples
554 --------
560 --------
555 ::
561 ::
556
562
557 In [1]: from math import pi
563 In [1]: from math import pi
558
564
559 In [2]: %precision 3
565 In [2]: %precision 3
560 Out[2]: u'%.3f'
566 Out[2]: u'%.3f'
561
567
562 In [3]: pi
568 In [3]: pi
563 Out[3]: 3.142
569 Out[3]: 3.142
564
570
565 In [4]: %precision %i
571 In [4]: %precision %i
566 Out[4]: u'%i'
572 Out[4]: u'%i'
567
573
568 In [5]: pi
574 In [5]: pi
569 Out[5]: 3
575 Out[5]: 3
570
576
571 In [6]: %precision %e
577 In [6]: %precision %e
572 Out[6]: u'%e'
578 Out[6]: u'%e'
573
579
574 In [7]: pi**10
580 In [7]: pi**10
575 Out[7]: 9.364805e+04
581 Out[7]: 9.364805e+04
576
582
577 In [8]: %precision
583 In [8]: %precision
578 Out[8]: u'%r'
584 Out[8]: u'%r'
579
585
580 In [9]: pi**10
586 In [9]: pi**10
581 Out[9]: 93648.047476082982
587 Out[9]: 93648.047476082982
582 """
588 """
583 ptformatter = self.shell.display_formatter.formatters['text/plain']
589 ptformatter = self.shell.display_formatter.formatters['text/plain']
584 ptformatter.float_precision = s
590 ptformatter.float_precision = s
585 return ptformatter.float_format
591 return ptformatter.float_format
586
592
587 @magic_arguments.magic_arguments()
593 @magic_arguments.magic_arguments()
588 @magic_arguments.argument(
594 @magic_arguments.argument(
589 '-e', '--export', action='store_true', default=False,
595 '-e', '--export', action='store_true', default=False,
590 help='Export IPython history as a notebook. The filename argument '
596 help='Export IPython history as a notebook. The filename argument '
591 'is used to specify the notebook name and format. For example '
597 'is used to specify the notebook name and format. For example '
592 'a filename of notebook.ipynb will result in a notebook name '
598 'a filename of notebook.ipynb will result in a notebook name '
593 'of "notebook" and a format of "json". Likewise using a ".py" '
599 'of "notebook" and a format of "json". Likewise using a ".py" '
594 'file extension will write the notebook as a Python script'
600 'file extension will write the notebook as a Python script'
595 )
601 )
596 @magic_arguments.argument(
602 @magic_arguments.argument(
597 '-f', '--format',
603 '-f', '--format',
598 help='Convert an existing IPython notebook to a new format. This option '
604 help='Convert an existing IPython notebook to a new format. This option '
599 'specifies the new format and can have the values: json, py. '
605 'specifies the new format and can have the values: json, py. '
600 'The target filename is chosen automatically based on the new '
606 'The target filename is chosen automatically based on the new '
601 'format. The filename argument gives the name of the source file.'
607 'format. The filename argument gives the name of the source file.'
602 )
608 )
603 @magic_arguments.argument(
609 @magic_arguments.argument(
604 'filename', type=unicode_type,
610 'filename', type=unicode_type,
605 help='Notebook name or filename'
611 help='Notebook name or filename'
606 )
612 )
607 @line_magic
613 @line_magic
608 def notebook(self, s):
614 def notebook(self, s):
609 """Export and convert IPython notebooks.
615 """Export and convert IPython notebooks.
610
616
611 This function can export the current IPython history to a notebook file
617 This function can export the current IPython history to a notebook file
612 or can convert an existing notebook file into a different format. For
618 or can convert an existing notebook file into a different format. For
613 example, to export the history to "foo.ipynb" do "%notebook -e foo.ipynb".
619 example, to export the history to "foo.ipynb" do "%notebook -e foo.ipynb".
614 To export the history to "foo.py" do "%notebook -e foo.py". To convert
620 To export the history to "foo.py" do "%notebook -e foo.py". To convert
615 "foo.ipynb" to "foo.json" do "%notebook -f json foo.ipynb". Possible
621 "foo.ipynb" to "foo.json" do "%notebook -f json foo.ipynb". Possible
616 formats include (json/ipynb, py).
622 formats include (json/ipynb, py).
617 """
623 """
618 args = magic_arguments.parse_argstring(self.notebook, s)
624 args = magic_arguments.parse_argstring(self.notebook, s)
619
625
620 from IPython.nbformat import current
626 from IPython.nbformat import current
621 args.filename = unquote_filename(args.filename)
627 args.filename = unquote_filename(args.filename)
622 if args.export:
628 if args.export:
623 fname, name, format = current.parse_filename(args.filename)
629 fname, name, format = current.parse_filename(args.filename)
624 cells = []
630 cells = []
625 hist = list(self.shell.history_manager.get_range())
631 hist = list(self.shell.history_manager.get_range())
626 for session, prompt_number, input in hist[:-1]:
632 for session, prompt_number, input in hist[:-1]:
627 cells.append(current.new_code_cell(prompt_number=prompt_number,
633 cells.append(current.new_code_cell(prompt_number=prompt_number,
628 input=input))
634 input=input))
629 worksheet = current.new_worksheet(cells=cells)
635 worksheet = current.new_worksheet(cells=cells)
630 nb = current.new_notebook(name=name,worksheets=[worksheet])
636 nb = current.new_notebook(name=name,worksheets=[worksheet])
631 with io.open(fname, 'w', encoding='utf-8') as f:
637 with io.open(fname, 'w', encoding='utf-8') as f:
632 current.write(nb, f, format);
638 current.write(nb, f, format);
633 elif args.format is not None:
639 elif args.format is not None:
634 old_fname, old_name, old_format = current.parse_filename(args.filename)
640 old_fname, old_name, old_format = current.parse_filename(args.filename)
635 new_format = args.format
641 new_format = args.format
636 if new_format == u'xml':
642 if new_format == u'xml':
637 raise ValueError('Notebooks cannot be written as xml.')
643 raise ValueError('Notebooks cannot be written as xml.')
638 elif new_format == u'ipynb' or new_format == u'json':
644 elif new_format == u'ipynb' or new_format == u'json':
639 new_fname = old_name + u'.ipynb'
645 new_fname = old_name + u'.ipynb'
640 new_format = u'json'
646 new_format = u'json'
641 elif new_format == u'py':
647 elif new_format == u'py':
642 new_fname = old_name + u'.py'
648 new_fname = old_name + u'.py'
643 else:
649 else:
644 raise ValueError('Invalid notebook format: %s' % new_format)
650 raise ValueError('Invalid notebook format: %s' % new_format)
645 with io.open(old_fname, 'r', encoding='utf-8') as f:
651 with io.open(old_fname, 'r', encoding='utf-8') as f:
646 nb = current.read(f, old_format)
652 nb = current.read(f, old_format)
647 with io.open(new_fname, 'w', encoding='utf-8') as f:
653 with io.open(new_fname, 'w', encoding='utf-8') as f:
648 current.write(nb, f, new_format)
654 current.write(nb, f, new_format)
General Comments 0
You need to be logged in to leave comments. Login now