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