##// END OF EJS Templates
Fix doctest for %config magic with new PromptManager configurable.
Thomas Kluyver -
Show More
@@ -1,3680 +1,3681 b''
1 1 # encoding: utf-8
2 2 """Magic functions for InteractiveShell.
3 3 """
4 4
5 5 #-----------------------------------------------------------------------------
6 6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 7 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
8 8 # Copyright (C) 2008-2011 The IPython Development Team
9 9
10 10 # Distributed under the terms of the BSD License. The full license is in
11 11 # the file COPYING, distributed as part of this software.
12 12 #-----------------------------------------------------------------------------
13 13
14 14 #-----------------------------------------------------------------------------
15 15 # Imports
16 16 #-----------------------------------------------------------------------------
17 17
18 18 import __builtin__ as builtin_mod
19 19 import __future__
20 20 import bdb
21 21 import inspect
22 22 import imp
23 23 import os
24 24 import sys
25 25 import shutil
26 26 import re
27 27 import time
28 28 from StringIO import StringIO
29 29 from getopt import getopt,GetoptError
30 30 from pprint import pformat
31 31 from xmlrpclib import ServerProxy
32 32
33 33 # cProfile was added in Python2.5
34 34 try:
35 35 import cProfile as profile
36 36 import pstats
37 37 except ImportError:
38 38 # profile isn't bundled by default in Debian for license reasons
39 39 try:
40 40 import profile,pstats
41 41 except ImportError:
42 42 profile = pstats = None
43 43
44 44 import IPython
45 45 from IPython.core import debugger, oinspect
46 46 from IPython.core.error import TryNext
47 47 from IPython.core.error import UsageError
48 48 from IPython.core.fakemodule import FakeModule
49 49 from IPython.core.profiledir import ProfileDir
50 50 from IPython.core.macro import Macro
51 51 from IPython.core import magic_arguments, page
52 52 from IPython.core.prefilter import ESC_MAGIC
53 53 from IPython.core.pylabtools import mpl_runner
54 54 from IPython.testing.skipdoctest import skip_doctest
55 55 from IPython.utils import py3compat
56 56 from IPython.utils.io import file_read, nlprint
57 57 from IPython.utils.module_paths import find_mod
58 58 from IPython.utils.path import get_py_filename, unquote_filename
59 59 from IPython.utils.process import arg_split, abbrev_cwd
60 60 from IPython.utils.terminal import set_term_title
61 61 from IPython.utils.text import LSString, SList, format_screen
62 62 from IPython.utils.timing import clock, clock2
63 63 from IPython.utils.warn import warn, error
64 64 from IPython.utils.ipstruct import Struct
65 65 from IPython.config.application import Application
66 66
67 67 #-----------------------------------------------------------------------------
68 68 # Utility functions
69 69 #-----------------------------------------------------------------------------
70 70
71 71 def on_off(tag):
72 72 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
73 73 return ['OFF','ON'][tag]
74 74
75 75 class Bunch: pass
76 76
77 77 def compress_dhist(dh):
78 78 head, tail = dh[:-10], dh[-10:]
79 79
80 80 newhead = []
81 81 done = set()
82 82 for h in head:
83 83 if h in done:
84 84 continue
85 85 newhead.append(h)
86 86 done.add(h)
87 87
88 88 return newhead + tail
89 89
90 90 def needs_local_scope(func):
91 91 """Decorator to mark magic functions which need to local scope to run."""
92 92 func.needs_local_scope = True
93 93 return func
94 94
95 95
96 96 # Used for exception handling in magic_edit
97 97 class MacroToEdit(ValueError): pass
98 98
99 99 #***************************************************************************
100 100 # Main class implementing Magic functionality
101 101
102 102 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
103 103 # on construction of the main InteractiveShell object. Something odd is going
104 104 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
105 105 # eventually this needs to be clarified.
106 106 # BG: This is because InteractiveShell inherits from this, but is itself a
107 107 # Configurable. This messes up the MRO in some way. The fix is that we need to
108 108 # make Magic a configurable that InteractiveShell does not subclass.
109 109
110 110 class Magic:
111 111 """Magic functions for InteractiveShell.
112 112
113 113 Shell functions which can be reached as %function_name. All magic
114 114 functions should accept a string, which they can parse for their own
115 115 needs. This can make some functions easier to type, eg `%cd ../`
116 116 vs. `%cd("../")`
117 117
118 118 ALL definitions MUST begin with the prefix magic_. The user won't need it
119 119 at the command line, but it is is needed in the definition. """
120 120
121 121 # class globals
122 122 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
123 123 'Automagic is ON, % prefix NOT needed for magic functions.']
124 124
125 125
126 126 configurables = None
127 127 #......................................................................
128 128 # some utility functions
129 129
130 130 def __init__(self,shell):
131 131
132 132 self.options_table = {}
133 133 if profile is None:
134 134 self.magic_prun = self.profile_missing_notice
135 135 self.shell = shell
136 136 if self.configurables is None:
137 137 self.configurables = []
138 138
139 139 # namespace for holding state we may need
140 140 self._magic_state = Bunch()
141 141
142 142 def profile_missing_notice(self, *args, **kwargs):
143 143 error("""\
144 144 The profile module could not be found. It has been removed from the standard
145 145 python packages because of its non-free license. To use profiling, install the
146 146 python-profiler package from non-free.""")
147 147
148 148 def default_option(self,fn,optstr):
149 149 """Make an entry in the options_table for fn, with value optstr"""
150 150
151 151 if fn not in self.lsmagic():
152 152 error("%s is not a magic function" % fn)
153 153 self.options_table[fn] = optstr
154 154
155 155 def lsmagic(self):
156 156 """Return a list of currently available magic functions.
157 157
158 158 Gives a list of the bare names after mangling (['ls','cd', ...], not
159 159 ['magic_ls','magic_cd',...]"""
160 160
161 161 # FIXME. This needs a cleanup, in the way the magics list is built.
162 162
163 163 # magics in class definition
164 164 class_magic = lambda fn: fn.startswith('magic_') and \
165 165 callable(Magic.__dict__[fn])
166 166 # in instance namespace (run-time user additions)
167 167 inst_magic = lambda fn: fn.startswith('magic_') and \
168 168 callable(self.__dict__[fn])
169 169 # and bound magics by user (so they can access self):
170 170 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
171 171 callable(self.__class__.__dict__[fn])
172 172 magics = filter(class_magic,Magic.__dict__.keys()) + \
173 173 filter(inst_magic,self.__dict__.keys()) + \
174 174 filter(inst_bound_magic,self.__class__.__dict__.keys())
175 175 out = []
176 176 for fn in set(magics):
177 177 out.append(fn.replace('magic_','',1))
178 178 out.sort()
179 179 return out
180 180
181 181 def extract_input_lines(self, range_str, raw=False):
182 182 """Return as a string a set of input history slices.
183 183
184 184 Inputs:
185 185
186 186 - range_str: the set of slices is given as a string, like
187 187 "~5/6-~4/2 4:8 9", since this function is for use by magic functions
188 188 which get their arguments as strings. The number before the / is the
189 189 session number: ~n goes n back from the current session.
190 190
191 191 Optional inputs:
192 192
193 193 - raw(False): by default, the processed input is used. If this is
194 194 true, the raw input history is used instead.
195 195
196 196 Note that slices can be called with two notations:
197 197
198 198 N:M -> standard python form, means including items N...(M-1).
199 199
200 200 N-M -> include items N..M (closed endpoint)."""
201 201 lines = self.shell.history_manager.\
202 202 get_range_by_str(range_str, raw=raw)
203 203 return "\n".join(x for _, _, x in lines)
204 204
205 205 def arg_err(self,func):
206 206 """Print docstring if incorrect arguments were passed"""
207 207 print 'Error in arguments:'
208 208 print oinspect.getdoc(func)
209 209
210 210 def format_latex(self,strng):
211 211 """Format a string for latex inclusion."""
212 212
213 213 # Characters that need to be escaped for latex:
214 214 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
215 215 # Magic command names as headers:
216 216 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
217 217 re.MULTILINE)
218 218 # Magic commands
219 219 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
220 220 re.MULTILINE)
221 221 # Paragraph continue
222 222 par_re = re.compile(r'\\$',re.MULTILINE)
223 223
224 224 # The "\n" symbol
225 225 newline_re = re.compile(r'\\n')
226 226
227 227 # Now build the string for output:
228 228 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
229 229 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
230 230 strng)
231 231 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
232 232 strng = par_re.sub(r'\\\\',strng)
233 233 strng = escape_re.sub(r'\\\1',strng)
234 234 strng = newline_re.sub(r'\\textbackslash{}n',strng)
235 235 return strng
236 236
237 237 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
238 238 """Parse options passed to an argument string.
239 239
240 240 The interface is similar to that of getopt(), but it returns back a
241 241 Struct with the options as keys and the stripped argument string still
242 242 as a string.
243 243
244 244 arg_str is quoted as a true sys.argv vector by using shlex.split.
245 245 This allows us to easily expand variables, glob files, quote
246 246 arguments, etc.
247 247
248 248 Options:
249 249 -mode: default 'string'. If given as 'list', the argument string is
250 250 returned as a list (split on whitespace) instead of a string.
251 251
252 252 -list_all: put all option values in lists. Normally only options
253 253 appearing more than once are put in a list.
254 254
255 255 -posix (True): whether to split the input line in POSIX mode or not,
256 256 as per the conventions outlined in the shlex module from the
257 257 standard library."""
258 258
259 259 # inject default options at the beginning of the input line
260 260 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
261 261 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
262 262
263 263 mode = kw.get('mode','string')
264 264 if mode not in ['string','list']:
265 265 raise ValueError,'incorrect mode given: %s' % mode
266 266 # Get options
267 267 list_all = kw.get('list_all',0)
268 268 posix = kw.get('posix', os.name == 'posix')
269 269
270 270 # Check if we have more than one argument to warrant extra processing:
271 271 odict = {} # Dictionary with options
272 272 args = arg_str.split()
273 273 if len(args) >= 1:
274 274 # If the list of inputs only has 0 or 1 thing in it, there's no
275 275 # need to look for options
276 276 argv = arg_split(arg_str,posix)
277 277 # Do regular option processing
278 278 try:
279 279 opts,args = getopt(argv,opt_str,*long_opts)
280 280 except GetoptError,e:
281 281 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
282 282 " ".join(long_opts)))
283 283 for o,a in opts:
284 284 if o.startswith('--'):
285 285 o = o[2:]
286 286 else:
287 287 o = o[1:]
288 288 try:
289 289 odict[o].append(a)
290 290 except AttributeError:
291 291 odict[o] = [odict[o],a]
292 292 except KeyError:
293 293 if list_all:
294 294 odict[o] = [a]
295 295 else:
296 296 odict[o] = a
297 297
298 298 # Prepare opts,args for return
299 299 opts = Struct(odict)
300 300 if mode == 'string':
301 301 args = ' '.join(args)
302 302
303 303 return opts,args
304 304
305 305 #......................................................................
306 306 # And now the actual magic functions
307 307
308 308 # Functions for IPython shell work (vars,funcs, config, etc)
309 309 def magic_lsmagic(self, parameter_s = ''):
310 310 """List currently available magic functions."""
311 311 mesc = ESC_MAGIC
312 312 print 'Available magic functions:\n'+mesc+\
313 313 (' '+mesc).join(self.lsmagic())
314 314 print '\n' + Magic.auto_status[self.shell.automagic]
315 315 return None
316 316
317 317 def magic_magic(self, parameter_s = ''):
318 318 """Print information about the magic function system.
319 319
320 320 Supported formats: -latex, -brief, -rest
321 321 """
322 322
323 323 mode = ''
324 324 try:
325 325 if parameter_s.split()[0] == '-latex':
326 326 mode = 'latex'
327 327 if parameter_s.split()[0] == '-brief':
328 328 mode = 'brief'
329 329 if parameter_s.split()[0] == '-rest':
330 330 mode = 'rest'
331 331 rest_docs = []
332 332 except:
333 333 pass
334 334
335 335 magic_docs = []
336 336 for fname in self.lsmagic():
337 337 mname = 'magic_' + fname
338 338 for space in (Magic,self,self.__class__):
339 339 try:
340 340 fn = space.__dict__[mname]
341 341 except KeyError:
342 342 pass
343 343 else:
344 344 break
345 345 if mode == 'brief':
346 346 # only first line
347 347 if fn.__doc__:
348 348 fndoc = fn.__doc__.split('\n',1)[0]
349 349 else:
350 350 fndoc = 'No documentation'
351 351 else:
352 352 if fn.__doc__:
353 353 fndoc = fn.__doc__.rstrip()
354 354 else:
355 355 fndoc = 'No documentation'
356 356
357 357
358 358 if mode == 'rest':
359 359 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
360 360 fname,fndoc))
361 361
362 362 else:
363 363 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
364 364 fname,fndoc))
365 365
366 366 magic_docs = ''.join(magic_docs)
367 367
368 368 if mode == 'rest':
369 369 return "".join(rest_docs)
370 370
371 371 if mode == 'latex':
372 372 print self.format_latex(magic_docs)
373 373 return
374 374 else:
375 375 magic_docs = format_screen(magic_docs)
376 376 if mode == 'brief':
377 377 return magic_docs
378 378
379 379 outmsg = """
380 380 IPython's 'magic' functions
381 381 ===========================
382 382
383 383 The magic function system provides a series of functions which allow you to
384 384 control the behavior of IPython itself, plus a lot of system-type
385 385 features. All these functions are prefixed with a % character, but parameters
386 386 are given without parentheses or quotes.
387 387
388 388 NOTE: If you have 'automagic' enabled (via the command line option or with the
389 389 %automagic function), you don't need to type in the % explicitly. By default,
390 390 IPython ships with automagic on, so you should only rarely need the % escape.
391 391
392 392 Example: typing '%cd mydir' (without the quotes) changes you working directory
393 393 to 'mydir', if it exists.
394 394
395 395 For a list of the available magic functions, use %lsmagic. For a description
396 396 of any of them, type %magic_name?, e.g. '%cd?'.
397 397
398 398 Currently the magic system has the following functions:\n"""
399 399
400 400 mesc = ESC_MAGIC
401 401 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
402 402 "\n\n%s%s\n\n%s" % (outmsg,
403 403 magic_docs,mesc,mesc,
404 404 (' '+mesc).join(self.lsmagic()),
405 405 Magic.auto_status[self.shell.automagic] ) )
406 406 page.page(outmsg)
407 407
408 408 def magic_automagic(self, parameter_s = ''):
409 409 """Make magic functions callable without having to type the initial %.
410 410
411 411 Without argumentsl toggles on/off (when off, you must call it as
412 412 %automagic, of course). With arguments it sets the value, and you can
413 413 use any of (case insensitive):
414 414
415 415 - on,1,True: to activate
416 416
417 417 - off,0,False: to deactivate.
418 418
419 419 Note that magic functions have lowest priority, so if there's a
420 420 variable whose name collides with that of a magic fn, automagic won't
421 421 work for that function (you get the variable instead). However, if you
422 422 delete the variable (del var), the previously shadowed magic function
423 423 becomes visible to automagic again."""
424 424
425 425 arg = parameter_s.lower()
426 426 if parameter_s in ('on','1','true'):
427 427 self.shell.automagic = True
428 428 elif parameter_s in ('off','0','false'):
429 429 self.shell.automagic = False
430 430 else:
431 431 self.shell.automagic = not self.shell.automagic
432 432 print '\n' + Magic.auto_status[self.shell.automagic]
433 433
434 434 @skip_doctest
435 435 def magic_autocall(self, parameter_s = ''):
436 436 """Make functions callable without having to type parentheses.
437 437
438 438 Usage:
439 439
440 440 %autocall [mode]
441 441
442 442 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
443 443 value is toggled on and off (remembering the previous state).
444 444
445 445 In more detail, these values mean:
446 446
447 447 0 -> fully disabled
448 448
449 449 1 -> active, but do not apply if there are no arguments on the line.
450 450
451 451 In this mode, you get:
452 452
453 453 In [1]: callable
454 454 Out[1]: <built-in function callable>
455 455
456 456 In [2]: callable 'hello'
457 457 ------> callable('hello')
458 458 Out[2]: False
459 459
460 460 2 -> Active always. Even if no arguments are present, the callable
461 461 object is called:
462 462
463 463 In [2]: float
464 464 ------> float()
465 465 Out[2]: 0.0
466 466
467 467 Note that even with autocall off, you can still use '/' at the start of
468 468 a line to treat the first argument on the command line as a function
469 469 and add parentheses to it:
470 470
471 471 In [8]: /str 43
472 472 ------> str(43)
473 473 Out[8]: '43'
474 474
475 475 # all-random (note for auto-testing)
476 476 """
477 477
478 478 if parameter_s:
479 479 arg = int(parameter_s)
480 480 else:
481 481 arg = 'toggle'
482 482
483 483 if not arg in (0,1,2,'toggle'):
484 484 error('Valid modes: (0->Off, 1->Smart, 2->Full')
485 485 return
486 486
487 487 if arg in (0,1,2):
488 488 self.shell.autocall = arg
489 489 else: # toggle
490 490 if self.shell.autocall:
491 491 self._magic_state.autocall_save = self.shell.autocall
492 492 self.shell.autocall = 0
493 493 else:
494 494 try:
495 495 self.shell.autocall = self._magic_state.autocall_save
496 496 except AttributeError:
497 497 self.shell.autocall = self._magic_state.autocall_save = 1
498 498
499 499 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
500 500
501 501
502 502 def magic_page(self, parameter_s=''):
503 503 """Pretty print the object and display it through a pager.
504 504
505 505 %page [options] OBJECT
506 506
507 507 If no object is given, use _ (last output).
508 508
509 509 Options:
510 510
511 511 -r: page str(object), don't pretty-print it."""
512 512
513 513 # After a function contributed by Olivier Aubert, slightly modified.
514 514
515 515 # Process options/args
516 516 opts,args = self.parse_options(parameter_s,'r')
517 517 raw = 'r' in opts
518 518
519 519 oname = args and args or '_'
520 520 info = self._ofind(oname)
521 521 if info['found']:
522 522 txt = (raw and str or pformat)( info['obj'] )
523 523 page.page(txt)
524 524 else:
525 525 print 'Object `%s` not found' % oname
526 526
527 527 def magic_profile(self, parameter_s=''):
528 528 """Print your currently active IPython profile."""
529 529 from IPython.core.application import BaseIPythonApplication
530 530 if BaseIPythonApplication.initialized():
531 531 print BaseIPythonApplication.instance().profile
532 532 else:
533 533 error("profile is an application-level value, but you don't appear to be in an IPython application")
534 534
535 535 def magic_pinfo(self, parameter_s='', namespaces=None):
536 536 """Provide detailed information about an object.
537 537
538 538 '%pinfo object' is just a synonym for object? or ?object."""
539 539
540 540 #print 'pinfo par: <%s>' % parameter_s # dbg
541 541
542 542
543 543 # detail_level: 0 -> obj? , 1 -> obj??
544 544 detail_level = 0
545 545 # We need to detect if we got called as 'pinfo pinfo foo', which can
546 546 # happen if the user types 'pinfo foo?' at the cmd line.
547 547 pinfo,qmark1,oname,qmark2 = \
548 548 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
549 549 if pinfo or qmark1 or qmark2:
550 550 detail_level = 1
551 551 if "*" in oname:
552 552 self.magic_psearch(oname)
553 553 else:
554 554 self.shell._inspect('pinfo', oname, detail_level=detail_level,
555 555 namespaces=namespaces)
556 556
557 557 def magic_pinfo2(self, parameter_s='', namespaces=None):
558 558 """Provide extra detailed information about an object.
559 559
560 560 '%pinfo2 object' is just a synonym for object?? or ??object."""
561 561 self.shell._inspect('pinfo', parameter_s, detail_level=1,
562 562 namespaces=namespaces)
563 563
564 564 @skip_doctest
565 565 def magic_pdef(self, parameter_s='', namespaces=None):
566 566 """Print the definition header for any callable object.
567 567
568 568 If the object is a class, print the constructor information.
569 569
570 570 Examples
571 571 --------
572 572 ::
573 573
574 574 In [3]: %pdef urllib.urlopen
575 575 urllib.urlopen(url, data=None, proxies=None)
576 576 """
577 577 self._inspect('pdef',parameter_s, namespaces)
578 578
579 579 def magic_pdoc(self, parameter_s='', namespaces=None):
580 580 """Print the docstring for an object.
581 581
582 582 If the given object is a class, it will print both the class and the
583 583 constructor docstrings."""
584 584 self._inspect('pdoc',parameter_s, namespaces)
585 585
586 586 def magic_psource(self, parameter_s='', namespaces=None):
587 587 """Print (or run through pager) the source code for an object."""
588 588 self._inspect('psource',parameter_s, namespaces)
589 589
590 590 def magic_pfile(self, parameter_s=''):
591 591 """Print (or run through pager) the file where an object is defined.
592 592
593 593 The file opens at the line where the object definition begins. IPython
594 594 will honor the environment variable PAGER if set, and otherwise will
595 595 do its best to print the file in a convenient form.
596 596
597 597 If the given argument is not an object currently defined, IPython will
598 598 try to interpret it as a filename (automatically adding a .py extension
599 599 if needed). You can thus use %pfile as a syntax highlighting code
600 600 viewer."""
601 601
602 602 # first interpret argument as an object name
603 603 out = self._inspect('pfile',parameter_s)
604 604 # if not, try the input as a filename
605 605 if out == 'not found':
606 606 try:
607 607 filename = get_py_filename(parameter_s)
608 608 except IOError,msg:
609 609 print msg
610 610 return
611 611 page.page(self.shell.inspector.format(file(filename).read()))
612 612
613 613 def magic_psearch(self, parameter_s=''):
614 614 """Search for object in namespaces by wildcard.
615 615
616 616 %psearch [options] PATTERN [OBJECT TYPE]
617 617
618 618 Note: ? can be used as a synonym for %psearch, at the beginning or at
619 619 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
620 620 rest of the command line must be unchanged (options come first), so
621 621 for example the following forms are equivalent
622 622
623 623 %psearch -i a* function
624 624 -i a* function?
625 625 ?-i a* function
626 626
627 627 Arguments:
628 628
629 629 PATTERN
630 630
631 631 where PATTERN is a string containing * as a wildcard similar to its
632 632 use in a shell. The pattern is matched in all namespaces on the
633 633 search path. By default objects starting with a single _ are not
634 634 matched, many IPython generated objects have a single
635 635 underscore. The default is case insensitive matching. Matching is
636 636 also done on the attributes of objects and not only on the objects
637 637 in a module.
638 638
639 639 [OBJECT TYPE]
640 640
641 641 Is the name of a python type from the types module. The name is
642 642 given in lowercase without the ending type, ex. StringType is
643 643 written string. By adding a type here only objects matching the
644 644 given type are matched. Using all here makes the pattern match all
645 645 types (this is the default).
646 646
647 647 Options:
648 648
649 649 -a: makes the pattern match even objects whose names start with a
650 650 single underscore. These names are normally ommitted from the
651 651 search.
652 652
653 653 -i/-c: make the pattern case insensitive/sensitive. If neither of
654 654 these options are given, the default is read from your configuration
655 655 file, with the option ``InteractiveShell.wildcards_case_sensitive``.
656 656 If this option is not specified in your configuration file, IPython's
657 657 internal default is to do a case sensitive search.
658 658
659 659 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
660 660 specifiy can be searched in any of the following namespaces:
661 661 'builtin', 'user', 'user_global','internal', 'alias', where
662 662 'builtin' and 'user' are the search defaults. Note that you should
663 663 not use quotes when specifying namespaces.
664 664
665 665 'Builtin' contains the python module builtin, 'user' contains all
666 666 user data, 'alias' only contain the shell aliases and no python
667 667 objects, 'internal' contains objects used by IPython. The
668 668 'user_global' namespace is only used by embedded IPython instances,
669 669 and it contains module-level globals. You can add namespaces to the
670 670 search with -s or exclude them with -e (these options can be given
671 671 more than once).
672 672
673 673 Examples:
674 674
675 675 %psearch a* -> objects beginning with an a
676 676 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
677 677 %psearch a* function -> all functions beginning with an a
678 678 %psearch re.e* -> objects beginning with an e in module re
679 679 %psearch r*.e* -> objects that start with e in modules starting in r
680 680 %psearch r*.* string -> all strings in modules beginning with r
681 681
682 682 Case sensitve search:
683 683
684 684 %psearch -c a* list all object beginning with lower case a
685 685
686 686 Show objects beginning with a single _:
687 687
688 688 %psearch -a _* list objects beginning with a single underscore"""
689 689 try:
690 690 parameter_s.encode('ascii')
691 691 except UnicodeEncodeError:
692 692 print 'Python identifiers can only contain ascii characters.'
693 693 return
694 694
695 695 # default namespaces to be searched
696 696 def_search = ['user','builtin']
697 697
698 698 # Process options/args
699 699 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
700 700 opt = opts.get
701 701 shell = self.shell
702 702 psearch = shell.inspector.psearch
703 703
704 704 # select case options
705 705 if opts.has_key('i'):
706 706 ignore_case = True
707 707 elif opts.has_key('c'):
708 708 ignore_case = False
709 709 else:
710 710 ignore_case = not shell.wildcards_case_sensitive
711 711
712 712 # Build list of namespaces to search from user options
713 713 def_search.extend(opt('s',[]))
714 714 ns_exclude = ns_exclude=opt('e',[])
715 715 ns_search = [nm for nm in def_search if nm not in ns_exclude]
716 716
717 717 # Call the actual search
718 718 try:
719 719 psearch(args,shell.ns_table,ns_search,
720 720 show_all=opt('a'),ignore_case=ignore_case)
721 721 except:
722 722 shell.showtraceback()
723 723
724 724 @skip_doctest
725 725 def magic_who_ls(self, parameter_s=''):
726 726 """Return a sorted list of all interactive variables.
727 727
728 728 If arguments are given, only variables of types matching these
729 729 arguments are returned.
730 730
731 731 Examples
732 732 --------
733 733
734 734 Define two variables and list them with who_ls::
735 735
736 736 In [1]: alpha = 123
737 737
738 738 In [2]: beta = 'test'
739 739
740 740 In [3]: %who_ls
741 741 Out[3]: ['alpha', 'beta']
742 742
743 743 In [4]: %who_ls int
744 744 Out[4]: ['alpha']
745 745
746 746 In [5]: %who_ls str
747 747 Out[5]: ['beta']
748 748 """
749 749
750 750 user_ns = self.shell.user_ns
751 751 user_ns_hidden = self.shell.user_ns_hidden
752 752 out = [ i for i in user_ns
753 753 if not i.startswith('_') \
754 754 and not i in user_ns_hidden ]
755 755
756 756 typelist = parameter_s.split()
757 757 if typelist:
758 758 typeset = set(typelist)
759 759 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
760 760
761 761 out.sort()
762 762 return out
763 763
764 764 @skip_doctest
765 765 def magic_who(self, parameter_s=''):
766 766 """Print all interactive variables, with some minimal formatting.
767 767
768 768 If any arguments are given, only variables whose type matches one of
769 769 these are printed. For example:
770 770
771 771 %who function str
772 772
773 773 will only list functions and strings, excluding all other types of
774 774 variables. To find the proper type names, simply use type(var) at a
775 775 command line to see how python prints type names. For example:
776 776
777 777 In [1]: type('hello')\\
778 778 Out[1]: <type 'str'>
779 779
780 780 indicates that the type name for strings is 'str'.
781 781
782 782 %who always excludes executed names loaded through your configuration
783 783 file and things which are internal to IPython.
784 784
785 785 This is deliberate, as typically you may load many modules and the
786 786 purpose of %who is to show you only what you've manually defined.
787 787
788 788 Examples
789 789 --------
790 790
791 791 Define two variables and list them with who::
792 792
793 793 In [1]: alpha = 123
794 794
795 795 In [2]: beta = 'test'
796 796
797 797 In [3]: %who
798 798 alpha beta
799 799
800 800 In [4]: %who int
801 801 alpha
802 802
803 803 In [5]: %who str
804 804 beta
805 805 """
806 806
807 807 varlist = self.magic_who_ls(parameter_s)
808 808 if not varlist:
809 809 if parameter_s:
810 810 print 'No variables match your requested type.'
811 811 else:
812 812 print 'Interactive namespace is empty.'
813 813 return
814 814
815 815 # if we have variables, move on...
816 816 count = 0
817 817 for i in varlist:
818 818 print i+'\t',
819 819 count += 1
820 820 if count > 8:
821 821 count = 0
822 822 print
823 823 print
824 824
825 825 @skip_doctest
826 826 def magic_whos(self, parameter_s=''):
827 827 """Like %who, but gives some extra information about each variable.
828 828
829 829 The same type filtering of %who can be applied here.
830 830
831 831 For all variables, the type is printed. Additionally it prints:
832 832
833 833 - For {},[],(): their length.
834 834
835 835 - For numpy arrays, a summary with shape, number of
836 836 elements, typecode and size in memory.
837 837
838 838 - Everything else: a string representation, snipping their middle if
839 839 too long.
840 840
841 841 Examples
842 842 --------
843 843
844 844 Define two variables and list them with whos::
845 845
846 846 In [1]: alpha = 123
847 847
848 848 In [2]: beta = 'test'
849 849
850 850 In [3]: %whos
851 851 Variable Type Data/Info
852 852 --------------------------------
853 853 alpha int 123
854 854 beta str test
855 855 """
856 856
857 857 varnames = self.magic_who_ls(parameter_s)
858 858 if not varnames:
859 859 if parameter_s:
860 860 print 'No variables match your requested type.'
861 861 else:
862 862 print 'Interactive namespace is empty.'
863 863 return
864 864
865 865 # if we have variables, move on...
866 866
867 867 # for these types, show len() instead of data:
868 868 seq_types = ['dict', 'list', 'tuple']
869 869
870 870 # for numpy arrays, display summary info
871 871 ndarray_type = None
872 872 if 'numpy' in sys.modules:
873 873 try:
874 874 from numpy import ndarray
875 875 except ImportError:
876 876 pass
877 877 else:
878 878 ndarray_type = ndarray.__name__
879 879
880 880 # Find all variable names and types so we can figure out column sizes
881 881 def get_vars(i):
882 882 return self.shell.user_ns[i]
883 883
884 884 # some types are well known and can be shorter
885 885 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
886 886 def type_name(v):
887 887 tn = type(v).__name__
888 888 return abbrevs.get(tn,tn)
889 889
890 890 varlist = map(get_vars,varnames)
891 891
892 892 typelist = []
893 893 for vv in varlist:
894 894 tt = type_name(vv)
895 895
896 896 if tt=='instance':
897 897 typelist.append( abbrevs.get(str(vv.__class__),
898 898 str(vv.__class__)))
899 899 else:
900 900 typelist.append(tt)
901 901
902 902 # column labels and # of spaces as separator
903 903 varlabel = 'Variable'
904 904 typelabel = 'Type'
905 905 datalabel = 'Data/Info'
906 906 colsep = 3
907 907 # variable format strings
908 908 vformat = "{0:<{varwidth}}{1:<{typewidth}}"
909 909 aformat = "%s: %s elems, type `%s`, %s bytes"
910 910 # find the size of the columns to format the output nicely
911 911 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
912 912 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
913 913 # table header
914 914 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
915 915 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
916 916 # and the table itself
917 917 kb = 1024
918 918 Mb = 1048576 # kb**2
919 919 for vname,var,vtype in zip(varnames,varlist,typelist):
920 920 print vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth),
921 921 if vtype in seq_types:
922 922 print "n="+str(len(var))
923 923 elif vtype == ndarray_type:
924 924 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
925 925 if vtype==ndarray_type:
926 926 # numpy
927 927 vsize = var.size
928 928 vbytes = vsize*var.itemsize
929 929 vdtype = var.dtype
930 930 else:
931 931 # Numeric
932 932 vsize = Numeric.size(var)
933 933 vbytes = vsize*var.itemsize()
934 934 vdtype = var.typecode()
935 935
936 936 if vbytes < 100000:
937 937 print aformat % (vshape,vsize,vdtype,vbytes)
938 938 else:
939 939 print aformat % (vshape,vsize,vdtype,vbytes),
940 940 if vbytes < Mb:
941 941 print '(%s kb)' % (vbytes/kb,)
942 942 else:
943 943 print '(%s Mb)' % (vbytes/Mb,)
944 944 else:
945 945 try:
946 946 vstr = str(var)
947 947 except UnicodeEncodeError:
948 948 vstr = unicode(var).encode(sys.getdefaultencoding(),
949 949 'backslashreplace')
950 950 vstr = vstr.replace('\n','\\n')
951 951 if len(vstr) < 50:
952 952 print vstr
953 953 else:
954 954 print vstr[:25] + "<...>" + vstr[-25:]
955 955
956 956 def magic_reset(self, parameter_s=''):
957 957 """Resets the namespace by removing all names defined by the user.
958 958
959 959 Parameters
960 960 ----------
961 961 -f : force reset without asking for confirmation.
962 962
963 963 -s : 'Soft' reset: Only clears your namespace, leaving history intact.
964 964 References to objects may be kept. By default (without this option),
965 965 we do a 'hard' reset, giving you a new session and removing all
966 966 references to objects from the current session.
967 967
968 968 Examples
969 969 --------
970 970 In [6]: a = 1
971 971
972 972 In [7]: a
973 973 Out[7]: 1
974 974
975 975 In [8]: 'a' in _ip.user_ns
976 976 Out[8]: True
977 977
978 978 In [9]: %reset -f
979 979
980 980 In [1]: 'a' in _ip.user_ns
981 981 Out[1]: False
982 982 """
983 983 opts, args = self.parse_options(parameter_s,'sf')
984 984 if 'f' in opts:
985 985 ans = True
986 986 else:
987 987 ans = self.shell.ask_yes_no(
988 988 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ", default='n')
989 989 if not ans:
990 990 print 'Nothing done.'
991 991 return
992 992
993 993 if 's' in opts: # Soft reset
994 994 user_ns = self.shell.user_ns
995 995 for i in self.magic_who_ls():
996 996 del(user_ns[i])
997 997
998 998 else: # Hard reset
999 999 self.shell.reset(new_session = False)
1000 1000
1001 1001
1002 1002
1003 1003 def magic_reset_selective(self, parameter_s=''):
1004 1004 """Resets the namespace by removing names defined by the user.
1005 1005
1006 1006 Input/Output history are left around in case you need them.
1007 1007
1008 1008 %reset_selective [-f] regex
1009 1009
1010 1010 No action is taken if regex is not included
1011 1011
1012 1012 Options
1013 1013 -f : force reset without asking for confirmation.
1014 1014
1015 1015 Examples
1016 1016 --------
1017 1017
1018 1018 We first fully reset the namespace so your output looks identical to
1019 1019 this example for pedagogical reasons; in practice you do not need a
1020 1020 full reset.
1021 1021
1022 1022 In [1]: %reset -f
1023 1023
1024 1024 Now, with a clean namespace we can make a few variables and use
1025 1025 %reset_selective to only delete names that match our regexp:
1026 1026
1027 1027 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1028 1028
1029 1029 In [3]: who_ls
1030 1030 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1031 1031
1032 1032 In [4]: %reset_selective -f b[2-3]m
1033 1033
1034 1034 In [5]: who_ls
1035 1035 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1036 1036
1037 1037 In [6]: %reset_selective -f d
1038 1038
1039 1039 In [7]: who_ls
1040 1040 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1041 1041
1042 1042 In [8]: %reset_selective -f c
1043 1043
1044 1044 In [9]: who_ls
1045 1045 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1046 1046
1047 1047 In [10]: %reset_selective -f b
1048 1048
1049 1049 In [11]: who_ls
1050 1050 Out[11]: ['a']
1051 1051 """
1052 1052
1053 1053 opts, regex = self.parse_options(parameter_s,'f')
1054 1054
1055 1055 if opts.has_key('f'):
1056 1056 ans = True
1057 1057 else:
1058 1058 ans = self.shell.ask_yes_no(
1059 1059 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
1060 1060 default='n')
1061 1061 if not ans:
1062 1062 print 'Nothing done.'
1063 1063 return
1064 1064 user_ns = self.shell.user_ns
1065 1065 if not regex:
1066 1066 print 'No regex pattern specified. Nothing done.'
1067 1067 return
1068 1068 else:
1069 1069 try:
1070 1070 m = re.compile(regex)
1071 1071 except TypeError:
1072 1072 raise TypeError('regex must be a string or compiled pattern')
1073 1073 for i in self.magic_who_ls():
1074 1074 if m.search(i):
1075 1075 del(user_ns[i])
1076 1076
1077 1077 def magic_xdel(self, parameter_s=''):
1078 1078 """Delete a variable, trying to clear it from anywhere that
1079 1079 IPython's machinery has references to it. By default, this uses
1080 1080 the identity of the named object in the user namespace to remove
1081 1081 references held under other names. The object is also removed
1082 1082 from the output history.
1083 1083
1084 1084 Options
1085 1085 -n : Delete the specified name from all namespaces, without
1086 1086 checking their identity.
1087 1087 """
1088 1088 opts, varname = self.parse_options(parameter_s,'n')
1089 1089 try:
1090 1090 self.shell.del_var(varname, ('n' in opts))
1091 1091 except (NameError, ValueError) as e:
1092 1092 print type(e).__name__ +": "+ str(e)
1093 1093
1094 1094 def magic_logstart(self,parameter_s=''):
1095 1095 """Start logging anywhere in a session.
1096 1096
1097 1097 %logstart [-o|-r|-t] [log_name [log_mode]]
1098 1098
1099 1099 If no name is given, it defaults to a file named 'ipython_log.py' in your
1100 1100 current directory, in 'rotate' mode (see below).
1101 1101
1102 1102 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1103 1103 history up to that point and then continues logging.
1104 1104
1105 1105 %logstart takes a second optional parameter: logging mode. This can be one
1106 1106 of (note that the modes are given unquoted):\\
1107 1107 append: well, that says it.\\
1108 1108 backup: rename (if exists) to name~ and start name.\\
1109 1109 global: single logfile in your home dir, appended to.\\
1110 1110 over : overwrite existing log.\\
1111 1111 rotate: create rotating logs name.1~, name.2~, etc.
1112 1112
1113 1113 Options:
1114 1114
1115 1115 -o: log also IPython's output. In this mode, all commands which
1116 1116 generate an Out[NN] prompt are recorded to the logfile, right after
1117 1117 their corresponding input line. The output lines are always
1118 1118 prepended with a '#[Out]# ' marker, so that the log remains valid
1119 1119 Python code.
1120 1120
1121 1121 Since this marker is always the same, filtering only the output from
1122 1122 a log is very easy, using for example a simple awk call:
1123 1123
1124 1124 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1125 1125
1126 1126 -r: log 'raw' input. Normally, IPython's logs contain the processed
1127 1127 input, so that user lines are logged in their final form, converted
1128 1128 into valid Python. For example, %Exit is logged as
1129 1129 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1130 1130 exactly as typed, with no transformations applied.
1131 1131
1132 1132 -t: put timestamps before each input line logged (these are put in
1133 1133 comments)."""
1134 1134
1135 1135 opts,par = self.parse_options(parameter_s,'ort')
1136 1136 log_output = 'o' in opts
1137 1137 log_raw_input = 'r' in opts
1138 1138 timestamp = 't' in opts
1139 1139
1140 1140 logger = self.shell.logger
1141 1141
1142 1142 # if no args are given, the defaults set in the logger constructor by
1143 1143 # ipytohn remain valid
1144 1144 if par:
1145 1145 try:
1146 1146 logfname,logmode = par.split()
1147 1147 except:
1148 1148 logfname = par
1149 1149 logmode = 'backup'
1150 1150 else:
1151 1151 logfname = logger.logfname
1152 1152 logmode = logger.logmode
1153 1153 # put logfname into rc struct as if it had been called on the command
1154 1154 # line, so it ends up saved in the log header Save it in case we need
1155 1155 # to restore it...
1156 1156 old_logfile = self.shell.logfile
1157 1157 if logfname:
1158 1158 logfname = os.path.expanduser(logfname)
1159 1159 self.shell.logfile = logfname
1160 1160
1161 1161 loghead = '# IPython log file\n\n'
1162 1162 try:
1163 1163 started = logger.logstart(logfname,loghead,logmode,
1164 1164 log_output,timestamp,log_raw_input)
1165 1165 except:
1166 1166 self.shell.logfile = old_logfile
1167 1167 warn("Couldn't start log: %s" % sys.exc_info()[1])
1168 1168 else:
1169 1169 # log input history up to this point, optionally interleaving
1170 1170 # output if requested
1171 1171
1172 1172 if timestamp:
1173 1173 # disable timestamping for the previous history, since we've
1174 1174 # lost those already (no time machine here).
1175 1175 logger.timestamp = False
1176 1176
1177 1177 if log_raw_input:
1178 1178 input_hist = self.shell.history_manager.input_hist_raw
1179 1179 else:
1180 1180 input_hist = self.shell.history_manager.input_hist_parsed
1181 1181
1182 1182 if log_output:
1183 1183 log_write = logger.log_write
1184 1184 output_hist = self.shell.history_manager.output_hist
1185 1185 for n in range(1,len(input_hist)-1):
1186 1186 log_write(input_hist[n].rstrip() + '\n')
1187 1187 if n in output_hist:
1188 1188 log_write(repr(output_hist[n]),'output')
1189 1189 else:
1190 1190 logger.log_write('\n'.join(input_hist[1:]))
1191 1191 logger.log_write('\n')
1192 1192 if timestamp:
1193 1193 # re-enable timestamping
1194 1194 logger.timestamp = True
1195 1195
1196 1196 print ('Activating auto-logging. '
1197 1197 'Current session state plus future input saved.')
1198 1198 logger.logstate()
1199 1199
1200 1200 def magic_logstop(self,parameter_s=''):
1201 1201 """Fully stop logging and close log file.
1202 1202
1203 1203 In order to start logging again, a new %logstart call needs to be made,
1204 1204 possibly (though not necessarily) with a new filename, mode and other
1205 1205 options."""
1206 1206 self.logger.logstop()
1207 1207
1208 1208 def magic_logoff(self,parameter_s=''):
1209 1209 """Temporarily stop logging.
1210 1210
1211 1211 You must have previously started logging."""
1212 1212 self.shell.logger.switch_log(0)
1213 1213
1214 1214 def magic_logon(self,parameter_s=''):
1215 1215 """Restart logging.
1216 1216
1217 1217 This function is for restarting logging which you've temporarily
1218 1218 stopped with %logoff. For starting logging for the first time, you
1219 1219 must use the %logstart function, which allows you to specify an
1220 1220 optional log filename."""
1221 1221
1222 1222 self.shell.logger.switch_log(1)
1223 1223
1224 1224 def magic_logstate(self,parameter_s=''):
1225 1225 """Print the status of the logging system."""
1226 1226
1227 1227 self.shell.logger.logstate()
1228 1228
1229 1229 def magic_pdb(self, parameter_s=''):
1230 1230 """Control the automatic calling of the pdb interactive debugger.
1231 1231
1232 1232 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1233 1233 argument it works as a toggle.
1234 1234
1235 1235 When an exception is triggered, IPython can optionally call the
1236 1236 interactive pdb debugger after the traceback printout. %pdb toggles
1237 1237 this feature on and off.
1238 1238
1239 1239 The initial state of this feature is set in your configuration
1240 1240 file (the option is ``InteractiveShell.pdb``).
1241 1241
1242 1242 If you want to just activate the debugger AFTER an exception has fired,
1243 1243 without having to type '%pdb on' and rerunning your code, you can use
1244 1244 the %debug magic."""
1245 1245
1246 1246 par = parameter_s.strip().lower()
1247 1247
1248 1248 if par:
1249 1249 try:
1250 1250 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1251 1251 except KeyError:
1252 1252 print ('Incorrect argument. Use on/1, off/0, '
1253 1253 'or nothing for a toggle.')
1254 1254 return
1255 1255 else:
1256 1256 # toggle
1257 1257 new_pdb = not self.shell.call_pdb
1258 1258
1259 1259 # set on the shell
1260 1260 self.shell.call_pdb = new_pdb
1261 1261 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1262 1262
1263 1263 def magic_debug(self, parameter_s=''):
1264 1264 """Activate the interactive debugger in post-mortem mode.
1265 1265
1266 1266 If an exception has just occurred, this lets you inspect its stack
1267 1267 frames interactively. Note that this will always work only on the last
1268 1268 traceback that occurred, so you must call this quickly after an
1269 1269 exception that you wish to inspect has fired, because if another one
1270 1270 occurs, it clobbers the previous one.
1271 1271
1272 1272 If you want IPython to automatically do this on every exception, see
1273 1273 the %pdb magic for more details.
1274 1274 """
1275 1275 self.shell.debugger(force=True)
1276 1276
1277 1277 @skip_doctest
1278 1278 def magic_prun(self, parameter_s ='',user_mode=1,
1279 1279 opts=None,arg_lst=None,prog_ns=None):
1280 1280
1281 1281 """Run a statement through the python code profiler.
1282 1282
1283 1283 Usage:
1284 1284 %prun [options] statement
1285 1285
1286 1286 The given statement (which doesn't require quote marks) is run via the
1287 1287 python profiler in a manner similar to the profile.run() function.
1288 1288 Namespaces are internally managed to work correctly; profile.run
1289 1289 cannot be used in IPython because it makes certain assumptions about
1290 1290 namespaces which do not hold under IPython.
1291 1291
1292 1292 Options:
1293 1293
1294 1294 -l <limit>: you can place restrictions on what or how much of the
1295 1295 profile gets printed. The limit value can be:
1296 1296
1297 1297 * A string: only information for function names containing this string
1298 1298 is printed.
1299 1299
1300 1300 * An integer: only these many lines are printed.
1301 1301
1302 1302 * A float (between 0 and 1): this fraction of the report is printed
1303 1303 (for example, use a limit of 0.4 to see the topmost 40% only).
1304 1304
1305 1305 You can combine several limits with repeated use of the option. For
1306 1306 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1307 1307 information about class constructors.
1308 1308
1309 1309 -r: return the pstats.Stats object generated by the profiling. This
1310 1310 object has all the information about the profile in it, and you can
1311 1311 later use it for further analysis or in other functions.
1312 1312
1313 1313 -s <key>: sort profile by given key. You can provide more than one key
1314 1314 by using the option several times: '-s key1 -s key2 -s key3...'. The
1315 1315 default sorting key is 'time'.
1316 1316
1317 1317 The following is copied verbatim from the profile documentation
1318 1318 referenced below:
1319 1319
1320 1320 When more than one key is provided, additional keys are used as
1321 1321 secondary criteria when the there is equality in all keys selected
1322 1322 before them.
1323 1323
1324 1324 Abbreviations can be used for any key names, as long as the
1325 1325 abbreviation is unambiguous. The following are the keys currently
1326 1326 defined:
1327 1327
1328 1328 Valid Arg Meaning
1329 1329 "calls" call count
1330 1330 "cumulative" cumulative time
1331 1331 "file" file name
1332 1332 "module" file name
1333 1333 "pcalls" primitive call count
1334 1334 "line" line number
1335 1335 "name" function name
1336 1336 "nfl" name/file/line
1337 1337 "stdname" standard name
1338 1338 "time" internal time
1339 1339
1340 1340 Note that all sorts on statistics are in descending order (placing
1341 1341 most time consuming items first), where as name, file, and line number
1342 1342 searches are in ascending order (i.e., alphabetical). The subtle
1343 1343 distinction between "nfl" and "stdname" is that the standard name is a
1344 1344 sort of the name as printed, which means that the embedded line
1345 1345 numbers get compared in an odd way. For example, lines 3, 20, and 40
1346 1346 would (if the file names were the same) appear in the string order
1347 1347 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1348 1348 line numbers. In fact, sort_stats("nfl") is the same as
1349 1349 sort_stats("name", "file", "line").
1350 1350
1351 1351 -T <filename>: save profile results as shown on screen to a text
1352 1352 file. The profile is still shown on screen.
1353 1353
1354 1354 -D <filename>: save (via dump_stats) profile statistics to given
1355 1355 filename. This data is in a format understod by the pstats module, and
1356 1356 is generated by a call to the dump_stats() method of profile
1357 1357 objects. The profile is still shown on screen.
1358 1358
1359 1359 If you want to run complete programs under the profiler's control, use
1360 1360 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1361 1361 contains profiler specific options as described here.
1362 1362
1363 1363 You can read the complete documentation for the profile module with::
1364 1364
1365 1365 In [1]: import profile; profile.help()
1366 1366 """
1367 1367
1368 1368 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1369 1369 # protect user quote marks
1370 1370 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1371 1371
1372 1372 if user_mode: # regular user call
1373 1373 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1374 1374 list_all=1)
1375 1375 namespace = self.shell.user_ns
1376 1376 else: # called to run a program by %run -p
1377 1377 try:
1378 1378 filename = get_py_filename(arg_lst[0])
1379 1379 except IOError as e:
1380 1380 try:
1381 1381 msg = str(e)
1382 1382 except UnicodeError:
1383 1383 msg = e.message
1384 1384 error(msg)
1385 1385 return
1386 1386
1387 1387 arg_str = 'execfile(filename,prog_ns)'
1388 1388 namespace = {
1389 1389 'execfile': self.shell.safe_execfile,
1390 1390 'prog_ns': prog_ns,
1391 1391 'filename': filename
1392 1392 }
1393 1393
1394 1394 opts.merge(opts_def)
1395 1395
1396 1396 prof = profile.Profile()
1397 1397 try:
1398 1398 prof = prof.runctx(arg_str,namespace,namespace)
1399 1399 sys_exit = ''
1400 1400 except SystemExit:
1401 1401 sys_exit = """*** SystemExit exception caught in code being profiled."""
1402 1402
1403 1403 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1404 1404
1405 1405 lims = opts.l
1406 1406 if lims:
1407 1407 lims = [] # rebuild lims with ints/floats/strings
1408 1408 for lim in opts.l:
1409 1409 try:
1410 1410 lims.append(int(lim))
1411 1411 except ValueError:
1412 1412 try:
1413 1413 lims.append(float(lim))
1414 1414 except ValueError:
1415 1415 lims.append(lim)
1416 1416
1417 1417 # Trap output.
1418 1418 stdout_trap = StringIO()
1419 1419
1420 1420 if hasattr(stats,'stream'):
1421 1421 # In newer versions of python, the stats object has a 'stream'
1422 1422 # attribute to write into.
1423 1423 stats.stream = stdout_trap
1424 1424 stats.print_stats(*lims)
1425 1425 else:
1426 1426 # For older versions, we manually redirect stdout during printing
1427 1427 sys_stdout = sys.stdout
1428 1428 try:
1429 1429 sys.stdout = stdout_trap
1430 1430 stats.print_stats(*lims)
1431 1431 finally:
1432 1432 sys.stdout = sys_stdout
1433 1433
1434 1434 output = stdout_trap.getvalue()
1435 1435 output = output.rstrip()
1436 1436
1437 1437 page.page(output)
1438 1438 print sys_exit,
1439 1439
1440 1440 dump_file = opts.D[0]
1441 1441 text_file = opts.T[0]
1442 1442 if dump_file:
1443 1443 dump_file = unquote_filename(dump_file)
1444 1444 prof.dump_stats(dump_file)
1445 1445 print '\n*** Profile stats marshalled to file',\
1446 1446 `dump_file`+'.',sys_exit
1447 1447 if text_file:
1448 1448 text_file = unquote_filename(text_file)
1449 1449 pfile = file(text_file,'w')
1450 1450 pfile.write(output)
1451 1451 pfile.close()
1452 1452 print '\n*** Profile printout saved to text file',\
1453 1453 `text_file`+'.',sys_exit
1454 1454
1455 1455 if opts.has_key('r'):
1456 1456 return stats
1457 1457 else:
1458 1458 return None
1459 1459
1460 1460 @skip_doctest
1461 1461 def magic_run(self, parameter_s ='', runner=None,
1462 1462 file_finder=get_py_filename):
1463 1463 """Run the named file inside IPython as a program.
1464 1464
1465 1465 Usage:\\
1466 1466 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1467 1467
1468 1468 Parameters after the filename are passed as command-line arguments to
1469 1469 the program (put in sys.argv). Then, control returns to IPython's
1470 1470 prompt.
1471 1471
1472 1472 This is similar to running at a system prompt:\\
1473 1473 $ python file args\\
1474 1474 but with the advantage of giving you IPython's tracebacks, and of
1475 1475 loading all variables into your interactive namespace for further use
1476 1476 (unless -p is used, see below).
1477 1477
1478 1478 The file is executed in a namespace initially consisting only of
1479 1479 __name__=='__main__' and sys.argv constructed as indicated. It thus
1480 1480 sees its environment as if it were being run as a stand-alone program
1481 1481 (except for sharing global objects such as previously imported
1482 1482 modules). But after execution, the IPython interactive namespace gets
1483 1483 updated with all variables defined in the program (except for __name__
1484 1484 and sys.argv). This allows for very convenient loading of code for
1485 1485 interactive work, while giving each program a 'clean sheet' to run in.
1486 1486
1487 1487 Options:
1488 1488
1489 1489 -n: __name__ is NOT set to '__main__', but to the running file's name
1490 1490 without extension (as python does under import). This allows running
1491 1491 scripts and reloading the definitions in them without calling code
1492 1492 protected by an ' if __name__ == "__main__" ' clause.
1493 1493
1494 1494 -i: run the file in IPython's namespace instead of an empty one. This
1495 1495 is useful if you are experimenting with code written in a text editor
1496 1496 which depends on variables defined interactively.
1497 1497
1498 1498 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1499 1499 being run. This is particularly useful if IPython is being used to
1500 1500 run unittests, which always exit with a sys.exit() call. In such
1501 1501 cases you are interested in the output of the test results, not in
1502 1502 seeing a traceback of the unittest module.
1503 1503
1504 1504 -t: print timing information at the end of the run. IPython will give
1505 1505 you an estimated CPU time consumption for your script, which under
1506 1506 Unix uses the resource module to avoid the wraparound problems of
1507 1507 time.clock(). Under Unix, an estimate of time spent on system tasks
1508 1508 is also given (for Windows platforms this is reported as 0.0).
1509 1509
1510 1510 If -t is given, an additional -N<N> option can be given, where <N>
1511 1511 must be an integer indicating how many times you want the script to
1512 1512 run. The final timing report will include total and per run results.
1513 1513
1514 1514 For example (testing the script uniq_stable.py):
1515 1515
1516 1516 In [1]: run -t uniq_stable
1517 1517
1518 1518 IPython CPU timings (estimated):\\
1519 1519 User : 0.19597 s.\\
1520 1520 System: 0.0 s.\\
1521 1521
1522 1522 In [2]: run -t -N5 uniq_stable
1523 1523
1524 1524 IPython CPU timings (estimated):\\
1525 1525 Total runs performed: 5\\
1526 1526 Times : Total Per run\\
1527 1527 User : 0.910862 s, 0.1821724 s.\\
1528 1528 System: 0.0 s, 0.0 s.
1529 1529
1530 1530 -d: run your program under the control of pdb, the Python debugger.
1531 1531 This allows you to execute your program step by step, watch variables,
1532 1532 etc. Internally, what IPython does is similar to calling:
1533 1533
1534 1534 pdb.run('execfile("YOURFILENAME")')
1535 1535
1536 1536 with a breakpoint set on line 1 of your file. You can change the line
1537 1537 number for this automatic breakpoint to be <N> by using the -bN option
1538 1538 (where N must be an integer). For example:
1539 1539
1540 1540 %run -d -b40 myscript
1541 1541
1542 1542 will set the first breakpoint at line 40 in myscript.py. Note that
1543 1543 the first breakpoint must be set on a line which actually does
1544 1544 something (not a comment or docstring) for it to stop execution.
1545 1545
1546 1546 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1547 1547 first enter 'c' (without qoutes) to start execution up to the first
1548 1548 breakpoint.
1549 1549
1550 1550 Entering 'help' gives information about the use of the debugger. You
1551 1551 can easily see pdb's full documentation with "import pdb;pdb.help()"
1552 1552 at a prompt.
1553 1553
1554 1554 -p: run program under the control of the Python profiler module (which
1555 1555 prints a detailed report of execution times, function calls, etc).
1556 1556
1557 1557 You can pass other options after -p which affect the behavior of the
1558 1558 profiler itself. See the docs for %prun for details.
1559 1559
1560 1560 In this mode, the program's variables do NOT propagate back to the
1561 1561 IPython interactive namespace (because they remain in the namespace
1562 1562 where the profiler executes them).
1563 1563
1564 1564 Internally this triggers a call to %prun, see its documentation for
1565 1565 details on the options available specifically for profiling.
1566 1566
1567 1567 There is one special usage for which the text above doesn't apply:
1568 1568 if the filename ends with .ipy, the file is run as ipython script,
1569 1569 just as if the commands were written on IPython prompt.
1570 1570
1571 1571 -m: specify module name to load instead of script path. Similar to
1572 1572 the -m option for the python interpreter. Use this option last if you
1573 1573 want to combine with other %run options. Unlike the python interpreter
1574 1574 only source modules are allowed no .pyc or .pyo files.
1575 1575 For example:
1576 1576
1577 1577 %run -m example
1578 1578
1579 1579 will run the example module.
1580 1580
1581 1581 """
1582 1582
1583 1583 # get arguments and set sys.argv for program to be run.
1584 1584 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
1585 1585 mode='list', list_all=1)
1586 1586 if "m" in opts:
1587 1587 modulename = opts["m"][0]
1588 1588 modpath = find_mod(modulename)
1589 1589 if modpath is None:
1590 1590 warn('%r is not a valid modulename on sys.path'%modulename)
1591 1591 return
1592 1592 arg_lst = [modpath] + arg_lst
1593 1593 try:
1594 1594 filename = file_finder(arg_lst[0])
1595 1595 except IndexError:
1596 1596 warn('you must provide at least a filename.')
1597 1597 print '\n%run:\n', oinspect.getdoc(self.magic_run)
1598 1598 return
1599 1599 except IOError as e:
1600 1600 try:
1601 1601 msg = str(e)
1602 1602 except UnicodeError:
1603 1603 msg = e.message
1604 1604 error(msg)
1605 1605 return
1606 1606
1607 1607 if filename.lower().endswith('.ipy'):
1608 1608 self.shell.safe_execfile_ipy(filename)
1609 1609 return
1610 1610
1611 1611 # Control the response to exit() calls made by the script being run
1612 1612 exit_ignore = 'e' in opts
1613 1613
1614 1614 # Make sure that the running script gets a proper sys.argv as if it
1615 1615 # were run from a system shell.
1616 1616 save_argv = sys.argv # save it for later restoring
1617 1617
1618 1618 # simulate shell expansion on arguments, at least tilde expansion
1619 1619 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
1620 1620
1621 1621 sys.argv = [filename] + args # put in the proper filename
1622 1622 # protect sys.argv from potential unicode strings on Python 2:
1623 1623 if not py3compat.PY3:
1624 1624 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
1625 1625
1626 1626 if 'i' in opts:
1627 1627 # Run in user's interactive namespace
1628 1628 prog_ns = self.shell.user_ns
1629 1629 __name__save = self.shell.user_ns['__name__']
1630 1630 prog_ns['__name__'] = '__main__'
1631 1631 main_mod = self.shell.new_main_mod(prog_ns)
1632 1632 else:
1633 1633 # Run in a fresh, empty namespace
1634 1634 if 'n' in opts:
1635 1635 name = os.path.splitext(os.path.basename(filename))[0]
1636 1636 else:
1637 1637 name = '__main__'
1638 1638
1639 1639 main_mod = self.shell.new_main_mod()
1640 1640 prog_ns = main_mod.__dict__
1641 1641 prog_ns['__name__'] = name
1642 1642
1643 1643 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1644 1644 # set the __file__ global in the script's namespace
1645 1645 prog_ns['__file__'] = filename
1646 1646
1647 1647 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1648 1648 # that, if we overwrite __main__, we replace it at the end
1649 1649 main_mod_name = prog_ns['__name__']
1650 1650
1651 1651 if main_mod_name == '__main__':
1652 1652 restore_main = sys.modules['__main__']
1653 1653 else:
1654 1654 restore_main = False
1655 1655
1656 1656 # This needs to be undone at the end to prevent holding references to
1657 1657 # every single object ever created.
1658 1658 sys.modules[main_mod_name] = main_mod
1659 1659
1660 1660 try:
1661 1661 stats = None
1662 1662 with self.readline_no_record:
1663 1663 if 'p' in opts:
1664 1664 stats = self.magic_prun('', 0, opts, arg_lst, prog_ns)
1665 1665 else:
1666 1666 if 'd' in opts:
1667 1667 deb = debugger.Pdb(self.shell.colors)
1668 1668 # reset Breakpoint state, which is moronically kept
1669 1669 # in a class
1670 1670 bdb.Breakpoint.next = 1
1671 1671 bdb.Breakpoint.bplist = {}
1672 1672 bdb.Breakpoint.bpbynumber = [None]
1673 1673 # Set an initial breakpoint to stop execution
1674 1674 maxtries = 10
1675 1675 bp = int(opts.get('b', [1])[0])
1676 1676 checkline = deb.checkline(filename, bp)
1677 1677 if not checkline:
1678 1678 for bp in range(bp + 1, bp + maxtries + 1):
1679 1679 if deb.checkline(filename, bp):
1680 1680 break
1681 1681 else:
1682 1682 msg = ("\nI failed to find a valid line to set "
1683 1683 "a breakpoint\n"
1684 1684 "after trying up to line: %s.\n"
1685 1685 "Please set a valid breakpoint manually "
1686 1686 "with the -b option." % bp)
1687 1687 error(msg)
1688 1688 return
1689 1689 # if we find a good linenumber, set the breakpoint
1690 1690 deb.do_break('%s:%s' % (filename, bp))
1691 1691 # Start file run
1692 1692 print "NOTE: Enter 'c' at the",
1693 1693 print "%s prompt to start your script." % deb.prompt
1694 1694 try:
1695 1695 deb.run('execfile("%s")' % filename, prog_ns)
1696 1696
1697 1697 except:
1698 1698 etype, value, tb = sys.exc_info()
1699 1699 # Skip three frames in the traceback: the %run one,
1700 1700 # one inside bdb.py, and the command-line typed by the
1701 1701 # user (run by exec in pdb itself).
1702 1702 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
1703 1703 else:
1704 1704 if runner is None:
1705 1705 runner = self.shell.safe_execfile
1706 1706 if 't' in opts:
1707 1707 # timed execution
1708 1708 try:
1709 1709 nruns = int(opts['N'][0])
1710 1710 if nruns < 1:
1711 1711 error('Number of runs must be >=1')
1712 1712 return
1713 1713 except (KeyError):
1714 1714 nruns = 1
1715 1715 twall0 = time.time()
1716 1716 if nruns == 1:
1717 1717 t0 = clock2()
1718 1718 runner(filename, prog_ns, prog_ns,
1719 1719 exit_ignore=exit_ignore)
1720 1720 t1 = clock2()
1721 1721 t_usr = t1[0] - t0[0]
1722 1722 t_sys = t1[1] - t0[1]
1723 1723 print "\nIPython CPU timings (estimated):"
1724 1724 print " User : %10.2f s." % t_usr
1725 1725 print " System : %10.2f s." % t_sys
1726 1726 else:
1727 1727 runs = range(nruns)
1728 1728 t0 = clock2()
1729 1729 for nr in runs:
1730 1730 runner(filename, prog_ns, prog_ns,
1731 1731 exit_ignore=exit_ignore)
1732 1732 t1 = clock2()
1733 1733 t_usr = t1[0] - t0[0]
1734 1734 t_sys = t1[1] - t0[1]
1735 1735 print "\nIPython CPU timings (estimated):"
1736 1736 print "Total runs performed:", nruns
1737 1737 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
1738 1738 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
1739 1739 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
1740 1740 twall1 = time.time()
1741 1741 print "Wall time: %10.2f s." % (twall1 - twall0)
1742 1742
1743 1743 else:
1744 1744 # regular execution
1745 1745 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
1746 1746
1747 1747 if 'i' in opts:
1748 1748 self.shell.user_ns['__name__'] = __name__save
1749 1749 else:
1750 1750 # The shell MUST hold a reference to prog_ns so after %run
1751 1751 # exits, the python deletion mechanism doesn't zero it out
1752 1752 # (leaving dangling references).
1753 1753 self.shell.cache_main_mod(prog_ns, filename)
1754 1754 # update IPython interactive namespace
1755 1755
1756 1756 # Some forms of read errors on the file may mean the
1757 1757 # __name__ key was never set; using pop we don't have to
1758 1758 # worry about a possible KeyError.
1759 1759 prog_ns.pop('__name__', None)
1760 1760
1761 1761 self.shell.user_ns.update(prog_ns)
1762 1762 finally:
1763 1763 # It's a bit of a mystery why, but __builtins__ can change from
1764 1764 # being a module to becoming a dict missing some key data after
1765 1765 # %run. As best I can see, this is NOT something IPython is doing
1766 1766 # at all, and similar problems have been reported before:
1767 1767 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1768 1768 # Since this seems to be done by the interpreter itself, the best
1769 1769 # we can do is to at least restore __builtins__ for the user on
1770 1770 # exit.
1771 1771 self.shell.user_ns['__builtins__'] = builtin_mod
1772 1772
1773 1773 # Ensure key global structures are restored
1774 1774 sys.argv = save_argv
1775 1775 if restore_main:
1776 1776 sys.modules['__main__'] = restore_main
1777 1777 else:
1778 1778 # Remove from sys.modules the reference to main_mod we'd
1779 1779 # added. Otherwise it will trap references to objects
1780 1780 # contained therein.
1781 1781 del sys.modules[main_mod_name]
1782 1782
1783 1783 return stats
1784 1784
1785 1785 @skip_doctest
1786 1786 def magic_timeit(self, parameter_s =''):
1787 1787 """Time execution of a Python statement or expression
1788 1788
1789 1789 Usage:\\
1790 1790 %timeit [-n<N> -r<R> [-t|-c]] statement
1791 1791
1792 1792 Time execution of a Python statement or expression using the timeit
1793 1793 module.
1794 1794
1795 1795 Options:
1796 1796 -n<N>: execute the given statement <N> times in a loop. If this value
1797 1797 is not given, a fitting value is chosen.
1798 1798
1799 1799 -r<R>: repeat the loop iteration <R> times and take the best result.
1800 1800 Default: 3
1801 1801
1802 1802 -t: use time.time to measure the time, which is the default on Unix.
1803 1803 This function measures wall time.
1804 1804
1805 1805 -c: use time.clock to measure the time, which is the default on
1806 1806 Windows and measures wall time. On Unix, resource.getrusage is used
1807 1807 instead and returns the CPU user time.
1808 1808
1809 1809 -p<P>: use a precision of <P> digits to display the timing result.
1810 1810 Default: 3
1811 1811
1812 1812
1813 1813 Examples:
1814 1814
1815 1815 In [1]: %timeit pass
1816 1816 10000000 loops, best of 3: 53.3 ns per loop
1817 1817
1818 1818 In [2]: u = None
1819 1819
1820 1820 In [3]: %timeit u is None
1821 1821 10000000 loops, best of 3: 184 ns per loop
1822 1822
1823 1823 In [4]: %timeit -r 4 u == None
1824 1824 1000000 loops, best of 4: 242 ns per loop
1825 1825
1826 1826 In [5]: import time
1827 1827
1828 1828 In [6]: %timeit -n1 time.sleep(2)
1829 1829 1 loops, best of 3: 2 s per loop
1830 1830
1831 1831
1832 1832 The times reported by %timeit will be slightly higher than those
1833 1833 reported by the timeit.py script when variables are accessed. This is
1834 1834 due to the fact that %timeit executes the statement in the namespace
1835 1835 of the shell, compared with timeit.py, which uses a single setup
1836 1836 statement to import function or create variables. Generally, the bias
1837 1837 does not matter as long as results from timeit.py are not mixed with
1838 1838 those from %timeit."""
1839 1839
1840 1840 import timeit
1841 1841 import math
1842 1842
1843 1843 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1844 1844 # certain terminals. Until we figure out a robust way of
1845 1845 # auto-detecting if the terminal can deal with it, use plain 'us' for
1846 1846 # microseconds. I am really NOT happy about disabling the proper
1847 1847 # 'micro' prefix, but crashing is worse... If anyone knows what the
1848 1848 # right solution for this is, I'm all ears...
1849 1849 #
1850 1850 # Note: using
1851 1851 #
1852 1852 # s = u'\xb5'
1853 1853 # s.encode(sys.getdefaultencoding())
1854 1854 #
1855 1855 # is not sufficient, as I've seen terminals where that fails but
1856 1856 # print s
1857 1857 #
1858 1858 # succeeds
1859 1859 #
1860 1860 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1861 1861
1862 1862 #units = [u"s", u"ms",u'\xb5',"ns"]
1863 1863 units = [u"s", u"ms",u'us',"ns"]
1864 1864
1865 1865 scaling = [1, 1e3, 1e6, 1e9]
1866 1866
1867 1867 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1868 1868 posix=False)
1869 1869 if stmt == "":
1870 1870 return
1871 1871 timefunc = timeit.default_timer
1872 1872 number = int(getattr(opts, "n", 0))
1873 1873 repeat = int(getattr(opts, "r", timeit.default_repeat))
1874 1874 precision = int(getattr(opts, "p", 3))
1875 1875 if hasattr(opts, "t"):
1876 1876 timefunc = time.time
1877 1877 if hasattr(opts, "c"):
1878 1878 timefunc = clock
1879 1879
1880 1880 timer = timeit.Timer(timer=timefunc)
1881 1881 # this code has tight coupling to the inner workings of timeit.Timer,
1882 1882 # but is there a better way to achieve that the code stmt has access
1883 1883 # to the shell namespace?
1884 1884
1885 1885 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1886 1886 'setup': "pass"}
1887 1887 # Track compilation time so it can be reported if too long
1888 1888 # Minimum time above which compilation time will be reported
1889 1889 tc_min = 0.1
1890 1890
1891 1891 t0 = clock()
1892 1892 code = compile(src, "<magic-timeit>", "exec")
1893 1893 tc = clock()-t0
1894 1894
1895 1895 ns = {}
1896 1896 exec code in self.shell.user_ns, ns
1897 1897 timer.inner = ns["inner"]
1898 1898
1899 1899 if number == 0:
1900 1900 # determine number so that 0.2 <= total time < 2.0
1901 1901 number = 1
1902 1902 for i in range(1, 10):
1903 1903 if timer.timeit(number) >= 0.2:
1904 1904 break
1905 1905 number *= 10
1906 1906
1907 1907 best = min(timer.repeat(repeat, number)) / number
1908 1908
1909 1909 if best > 0.0 and best < 1000.0:
1910 1910 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1911 1911 elif best >= 1000.0:
1912 1912 order = 0
1913 1913 else:
1914 1914 order = 3
1915 1915 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1916 1916 precision,
1917 1917 best * scaling[order],
1918 1918 units[order])
1919 1919 if tc > tc_min:
1920 1920 print "Compiler time: %.2f s" % tc
1921 1921
1922 1922 @skip_doctest
1923 1923 @needs_local_scope
1924 1924 def magic_time(self,parameter_s = ''):
1925 1925 """Time execution of a Python statement or expression.
1926 1926
1927 1927 The CPU and wall clock times are printed, and the value of the
1928 1928 expression (if any) is returned. Note that under Win32, system time
1929 1929 is always reported as 0, since it can not be measured.
1930 1930
1931 1931 This function provides very basic timing functionality. In Python
1932 1932 2.3, the timeit module offers more control and sophistication, so this
1933 1933 could be rewritten to use it (patches welcome).
1934 1934
1935 1935 Some examples:
1936 1936
1937 1937 In [1]: time 2**128
1938 1938 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1939 1939 Wall time: 0.00
1940 1940 Out[1]: 340282366920938463463374607431768211456L
1941 1941
1942 1942 In [2]: n = 1000000
1943 1943
1944 1944 In [3]: time sum(range(n))
1945 1945 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1946 1946 Wall time: 1.37
1947 1947 Out[3]: 499999500000L
1948 1948
1949 1949 In [4]: time print 'hello world'
1950 1950 hello world
1951 1951 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1952 1952 Wall time: 0.00
1953 1953
1954 1954 Note that the time needed by Python to compile the given expression
1955 1955 will be reported if it is more than 0.1s. In this example, the
1956 1956 actual exponentiation is done by Python at compilation time, so while
1957 1957 the expression can take a noticeable amount of time to compute, that
1958 1958 time is purely due to the compilation:
1959 1959
1960 1960 In [5]: time 3**9999;
1961 1961 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1962 1962 Wall time: 0.00 s
1963 1963
1964 1964 In [6]: time 3**999999;
1965 1965 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1966 1966 Wall time: 0.00 s
1967 1967 Compiler : 0.78 s
1968 1968 """
1969 1969
1970 1970 # fail immediately if the given expression can't be compiled
1971 1971
1972 1972 expr = self.shell.prefilter(parameter_s,False)
1973 1973
1974 1974 # Minimum time above which compilation time will be reported
1975 1975 tc_min = 0.1
1976 1976
1977 1977 try:
1978 1978 mode = 'eval'
1979 1979 t0 = clock()
1980 1980 code = compile(expr,'<timed eval>',mode)
1981 1981 tc = clock()-t0
1982 1982 except SyntaxError:
1983 1983 mode = 'exec'
1984 1984 t0 = clock()
1985 1985 code = compile(expr,'<timed exec>',mode)
1986 1986 tc = clock()-t0
1987 1987 # skew measurement as little as possible
1988 1988 glob = self.shell.user_ns
1989 1989 locs = self._magic_locals
1990 1990 clk = clock2
1991 1991 wtime = time.time
1992 1992 # time execution
1993 1993 wall_st = wtime()
1994 1994 if mode=='eval':
1995 1995 st = clk()
1996 1996 out = eval(code, glob, locs)
1997 1997 end = clk()
1998 1998 else:
1999 1999 st = clk()
2000 2000 exec code in glob, locs
2001 2001 end = clk()
2002 2002 out = None
2003 2003 wall_end = wtime()
2004 2004 # Compute actual times and report
2005 2005 wall_time = wall_end-wall_st
2006 2006 cpu_user = end[0]-st[0]
2007 2007 cpu_sys = end[1]-st[1]
2008 2008 cpu_tot = cpu_user+cpu_sys
2009 2009 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2010 2010 (cpu_user,cpu_sys,cpu_tot)
2011 2011 print "Wall time: %.2f s" % wall_time
2012 2012 if tc > tc_min:
2013 2013 print "Compiler : %.2f s" % tc
2014 2014 return out
2015 2015
2016 2016 @skip_doctest
2017 2017 def magic_macro(self,parameter_s = ''):
2018 2018 """Define a macro for future re-execution. It accepts ranges of history,
2019 2019 filenames or string objects.
2020 2020
2021 2021 Usage:\\
2022 2022 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2023 2023
2024 2024 Options:
2025 2025
2026 2026 -r: use 'raw' input. By default, the 'processed' history is used,
2027 2027 so that magics are loaded in their transformed version to valid
2028 2028 Python. If this option is given, the raw input as typed as the
2029 2029 command line is used instead.
2030 2030
2031 2031 This will define a global variable called `name` which is a string
2032 2032 made of joining the slices and lines you specify (n1,n2,... numbers
2033 2033 above) from your input history into a single string. This variable
2034 2034 acts like an automatic function which re-executes those lines as if
2035 2035 you had typed them. You just type 'name' at the prompt and the code
2036 2036 executes.
2037 2037
2038 2038 The syntax for indicating input ranges is described in %history.
2039 2039
2040 2040 Note: as a 'hidden' feature, you can also use traditional python slice
2041 2041 notation, where N:M means numbers N through M-1.
2042 2042
2043 2043 For example, if your history contains (%hist prints it):
2044 2044
2045 2045 44: x=1
2046 2046 45: y=3
2047 2047 46: z=x+y
2048 2048 47: print x
2049 2049 48: a=5
2050 2050 49: print 'x',x,'y',y
2051 2051
2052 2052 you can create a macro with lines 44 through 47 (included) and line 49
2053 2053 called my_macro with:
2054 2054
2055 2055 In [55]: %macro my_macro 44-47 49
2056 2056
2057 2057 Now, typing `my_macro` (without quotes) will re-execute all this code
2058 2058 in one pass.
2059 2059
2060 2060 You don't need to give the line-numbers in order, and any given line
2061 2061 number can appear multiple times. You can assemble macros with any
2062 2062 lines from your input history in any order.
2063 2063
2064 2064 The macro is a simple object which holds its value in an attribute,
2065 2065 but IPython's display system checks for macros and executes them as
2066 2066 code instead of printing them when you type their name.
2067 2067
2068 2068 You can view a macro's contents by explicitly printing it with:
2069 2069
2070 2070 'print macro_name'.
2071 2071
2072 2072 """
2073 2073 opts,args = self.parse_options(parameter_s,'r',mode='list')
2074 2074 if not args: # List existing macros
2075 2075 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2076 2076 isinstance(v, Macro))
2077 2077 if len(args) == 1:
2078 2078 raise UsageError(
2079 2079 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2080 2080 name, codefrom = args[0], " ".join(args[1:])
2081 2081
2082 2082 #print 'rng',ranges # dbg
2083 2083 try:
2084 2084 lines = self.shell.find_user_code(codefrom, 'r' in opts)
2085 2085 except (ValueError, TypeError) as e:
2086 2086 print e.args[0]
2087 2087 return
2088 2088 macro = Macro(lines)
2089 2089 self.shell.define_macro(name, macro)
2090 2090 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2091 2091 print '=== Macro contents: ==='
2092 2092 print macro,
2093 2093
2094 2094 def magic_save(self,parameter_s = ''):
2095 2095 """Save a set of lines or a macro to a given filename.
2096 2096
2097 2097 Usage:\\
2098 2098 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2099 2099
2100 2100 Options:
2101 2101
2102 2102 -r: use 'raw' input. By default, the 'processed' history is used,
2103 2103 so that magics are loaded in their transformed version to valid
2104 2104 Python. If this option is given, the raw input as typed as the
2105 2105 command line is used instead.
2106 2106
2107 2107 This function uses the same syntax as %history for input ranges,
2108 2108 then saves the lines to the filename you specify.
2109 2109
2110 2110 It adds a '.py' extension to the file if you don't do so yourself, and
2111 2111 it asks for confirmation before overwriting existing files."""
2112 2112
2113 2113 opts,args = self.parse_options(parameter_s,'r',mode='list')
2114 2114 fname, codefrom = unquote_filename(args[0]), " ".join(args[1:])
2115 2115 if not fname.endswith('.py'):
2116 2116 fname += '.py'
2117 2117 if os.path.isfile(fname):
2118 2118 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2119 2119 if ans.lower() not in ['y','yes']:
2120 2120 print 'Operation cancelled.'
2121 2121 return
2122 2122 try:
2123 2123 cmds = self.shell.find_user_code(codefrom, 'r' in opts)
2124 2124 except (TypeError, ValueError) as e:
2125 2125 print e.args[0]
2126 2126 return
2127 2127 with py3compat.open(fname,'w', encoding="utf-8") as f:
2128 2128 f.write(u"# coding: utf-8\n")
2129 2129 f.write(py3compat.cast_unicode(cmds))
2130 2130 print 'The following commands were written to file `%s`:' % fname
2131 2131 print cmds
2132 2132
2133 2133 def magic_pastebin(self, parameter_s = ''):
2134 2134 """Upload code to the 'Lodge it' paste bin, returning the URL."""
2135 2135 try:
2136 2136 code = self.shell.find_user_code(parameter_s)
2137 2137 except (ValueError, TypeError) as e:
2138 2138 print e.args[0]
2139 2139 return
2140 2140 pbserver = ServerProxy('http://paste.pocoo.org/xmlrpc/')
2141 2141 id = pbserver.pastes.newPaste("python", code)
2142 2142 return "http://paste.pocoo.org/show/" + id
2143 2143
2144 2144 def magic_loadpy(self, arg_s):
2145 2145 """Load a .py python script into the GUI console.
2146 2146
2147 2147 This magic command can either take a local filename or a url::
2148 2148
2149 2149 %loadpy myscript.py
2150 2150 %loadpy http://www.example.com/myscript.py
2151 2151 """
2152 2152 arg_s = unquote_filename(arg_s)
2153 2153 if not arg_s.endswith('.py'):
2154 2154 raise ValueError('%%load only works with .py files: %s' % arg_s)
2155 2155 if arg_s.startswith('http'):
2156 2156 import urllib2
2157 2157 response = urllib2.urlopen(arg_s)
2158 2158 content = response.read()
2159 2159 else:
2160 2160 with open(arg_s) as f:
2161 2161 content = f.read()
2162 2162 self.set_next_input(content)
2163 2163
2164 2164 def _find_edit_target(self, args, opts, last_call):
2165 2165 """Utility method used by magic_edit to find what to edit."""
2166 2166
2167 2167 def make_filename(arg):
2168 2168 "Make a filename from the given args"
2169 2169 arg = unquote_filename(arg)
2170 2170 try:
2171 2171 filename = get_py_filename(arg)
2172 2172 except IOError:
2173 2173 # If it ends with .py but doesn't already exist, assume we want
2174 2174 # a new file.
2175 2175 if arg.endswith('.py'):
2176 2176 filename = arg
2177 2177 else:
2178 2178 filename = None
2179 2179 return filename
2180 2180
2181 2181 # Set a few locals from the options for convenience:
2182 2182 opts_prev = 'p' in opts
2183 2183 opts_raw = 'r' in opts
2184 2184
2185 2185 # custom exceptions
2186 2186 class DataIsObject(Exception): pass
2187 2187
2188 2188 # Default line number value
2189 2189 lineno = opts.get('n',None)
2190 2190
2191 2191 if opts_prev:
2192 2192 args = '_%s' % last_call[0]
2193 2193 if not self.shell.user_ns.has_key(args):
2194 2194 args = last_call[1]
2195 2195
2196 2196 # use last_call to remember the state of the previous call, but don't
2197 2197 # let it be clobbered by successive '-p' calls.
2198 2198 try:
2199 2199 last_call[0] = self.shell.displayhook.prompt_count
2200 2200 if not opts_prev:
2201 2201 last_call[1] = parameter_s
2202 2202 except:
2203 2203 pass
2204 2204
2205 2205 # by default this is done with temp files, except when the given
2206 2206 # arg is a filename
2207 2207 use_temp = True
2208 2208
2209 2209 data = ''
2210 2210
2211 2211 # First, see if the arguments should be a filename.
2212 2212 filename = make_filename(args)
2213 2213 if filename:
2214 2214 use_temp = False
2215 2215 elif args:
2216 2216 # Mode where user specifies ranges of lines, like in %macro.
2217 2217 data = self.extract_input_lines(args, opts_raw)
2218 2218 if not data:
2219 2219 try:
2220 2220 # Load the parameter given as a variable. If not a string,
2221 2221 # process it as an object instead (below)
2222 2222
2223 2223 #print '*** args',args,'type',type(args) # dbg
2224 2224 data = eval(args, self.shell.user_ns)
2225 2225 if not isinstance(data, basestring):
2226 2226 raise DataIsObject
2227 2227
2228 2228 except (NameError,SyntaxError):
2229 2229 # given argument is not a variable, try as a filename
2230 2230 filename = make_filename(args)
2231 2231 if filename is None:
2232 2232 warn("Argument given (%s) can't be found as a variable "
2233 2233 "or as a filename." % args)
2234 2234 return
2235 2235 use_temp = False
2236 2236
2237 2237 except DataIsObject:
2238 2238 # macros have a special edit function
2239 2239 if isinstance(data, Macro):
2240 2240 raise MacroToEdit(data)
2241 2241
2242 2242 # For objects, try to edit the file where they are defined
2243 2243 try:
2244 2244 filename = inspect.getabsfile(data)
2245 2245 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2246 2246 # class created by %edit? Try to find source
2247 2247 # by looking for method definitions instead, the
2248 2248 # __module__ in those classes is FakeModule.
2249 2249 attrs = [getattr(data, aname) for aname in dir(data)]
2250 2250 for attr in attrs:
2251 2251 if not inspect.ismethod(attr):
2252 2252 continue
2253 2253 filename = inspect.getabsfile(attr)
2254 2254 if filename and 'fakemodule' not in filename.lower():
2255 2255 # change the attribute to be the edit target instead
2256 2256 data = attr
2257 2257 break
2258 2258
2259 2259 datafile = 1
2260 2260 except TypeError:
2261 2261 filename = make_filename(args)
2262 2262 datafile = 1
2263 2263 warn('Could not find file where `%s` is defined.\n'
2264 2264 'Opening a file named `%s`' % (args,filename))
2265 2265 # Now, make sure we can actually read the source (if it was in
2266 2266 # a temp file it's gone by now).
2267 2267 if datafile:
2268 2268 try:
2269 2269 if lineno is None:
2270 2270 lineno = inspect.getsourcelines(data)[1]
2271 2271 except IOError:
2272 2272 filename = make_filename(args)
2273 2273 if filename is None:
2274 2274 warn('The file `%s` where `%s` was defined cannot '
2275 2275 'be read.' % (filename,data))
2276 2276 return
2277 2277 use_temp = False
2278 2278
2279 2279 if use_temp:
2280 2280 filename = self.shell.mktempfile(data)
2281 2281 print 'IPython will make a temporary file named:',filename
2282 2282
2283 2283 return filename, lineno, use_temp
2284 2284
2285 2285 def _edit_macro(self,mname,macro):
2286 2286 """open an editor with the macro data in a file"""
2287 2287 filename = self.shell.mktempfile(macro.value)
2288 2288 self.shell.hooks.editor(filename)
2289 2289
2290 2290 # and make a new macro object, to replace the old one
2291 2291 mfile = open(filename)
2292 2292 mvalue = mfile.read()
2293 2293 mfile.close()
2294 2294 self.shell.user_ns[mname] = Macro(mvalue)
2295 2295
2296 2296 def magic_ed(self,parameter_s=''):
2297 2297 """Alias to %edit."""
2298 2298 return self.magic_edit(parameter_s)
2299 2299
2300 2300 @skip_doctest
2301 2301 def magic_edit(self,parameter_s='',last_call=['','']):
2302 2302 """Bring up an editor and execute the resulting code.
2303 2303
2304 2304 Usage:
2305 2305 %edit [options] [args]
2306 2306
2307 2307 %edit runs IPython's editor hook. The default version of this hook is
2308 2308 set to call the editor specified by your $EDITOR environment variable.
2309 2309 If this isn't found, it will default to vi under Linux/Unix and to
2310 2310 notepad under Windows. See the end of this docstring for how to change
2311 2311 the editor hook.
2312 2312
2313 2313 You can also set the value of this editor via the
2314 2314 ``TerminalInteractiveShell.editor`` option in your configuration file.
2315 2315 This is useful if you wish to use a different editor from your typical
2316 2316 default with IPython (and for Windows users who typically don't set
2317 2317 environment variables).
2318 2318
2319 2319 This command allows you to conveniently edit multi-line code right in
2320 2320 your IPython session.
2321 2321
2322 2322 If called without arguments, %edit opens up an empty editor with a
2323 2323 temporary file and will execute the contents of this file when you
2324 2324 close it (don't forget to save it!).
2325 2325
2326 2326
2327 2327 Options:
2328 2328
2329 2329 -n <number>: open the editor at a specified line number. By default,
2330 2330 the IPython editor hook uses the unix syntax 'editor +N filename', but
2331 2331 you can configure this by providing your own modified hook if your
2332 2332 favorite editor supports line-number specifications with a different
2333 2333 syntax.
2334 2334
2335 2335 -p: this will call the editor with the same data as the previous time
2336 2336 it was used, regardless of how long ago (in your current session) it
2337 2337 was.
2338 2338
2339 2339 -r: use 'raw' input. This option only applies to input taken from the
2340 2340 user's history. By default, the 'processed' history is used, so that
2341 2341 magics are loaded in their transformed version to valid Python. If
2342 2342 this option is given, the raw input as typed as the command line is
2343 2343 used instead. When you exit the editor, it will be executed by
2344 2344 IPython's own processor.
2345 2345
2346 2346 -x: do not execute the edited code immediately upon exit. This is
2347 2347 mainly useful if you are editing programs which need to be called with
2348 2348 command line arguments, which you can then do using %run.
2349 2349
2350 2350
2351 2351 Arguments:
2352 2352
2353 2353 If arguments are given, the following possibilites exist:
2354 2354
2355 2355 - If the argument is a filename, IPython will load that into the
2356 2356 editor. It will execute its contents with execfile() when you exit,
2357 2357 loading any code in the file into your interactive namespace.
2358 2358
2359 2359 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
2360 2360 The syntax is the same as in the %history magic.
2361 2361
2362 2362 - If the argument is a string variable, its contents are loaded
2363 2363 into the editor. You can thus edit any string which contains
2364 2364 python code (including the result of previous edits).
2365 2365
2366 2366 - If the argument is the name of an object (other than a string),
2367 2367 IPython will try to locate the file where it was defined and open the
2368 2368 editor at the point where it is defined. You can use `%edit function`
2369 2369 to load an editor exactly at the point where 'function' is defined,
2370 2370 edit it and have the file be executed automatically.
2371 2371
2372 2372 - If the object is a macro (see %macro for details), this opens up your
2373 2373 specified editor with a temporary file containing the macro's data.
2374 2374 Upon exit, the macro is reloaded with the contents of the file.
2375 2375
2376 2376 Note: opening at an exact line is only supported under Unix, and some
2377 2377 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2378 2378 '+NUMBER' parameter necessary for this feature. Good editors like
2379 2379 (X)Emacs, vi, jed, pico and joe all do.
2380 2380
2381 2381 After executing your code, %edit will return as output the code you
2382 2382 typed in the editor (except when it was an existing file). This way
2383 2383 you can reload the code in further invocations of %edit as a variable,
2384 2384 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2385 2385 the output.
2386 2386
2387 2387 Note that %edit is also available through the alias %ed.
2388 2388
2389 2389 This is an example of creating a simple function inside the editor and
2390 2390 then modifying it. First, start up the editor:
2391 2391
2392 2392 In [1]: ed
2393 2393 Editing... done. Executing edited code...
2394 2394 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2395 2395
2396 2396 We can then call the function foo():
2397 2397
2398 2398 In [2]: foo()
2399 2399 foo() was defined in an editing session
2400 2400
2401 2401 Now we edit foo. IPython automatically loads the editor with the
2402 2402 (temporary) file where foo() was previously defined:
2403 2403
2404 2404 In [3]: ed foo
2405 2405 Editing... done. Executing edited code...
2406 2406
2407 2407 And if we call foo() again we get the modified version:
2408 2408
2409 2409 In [4]: foo()
2410 2410 foo() has now been changed!
2411 2411
2412 2412 Here is an example of how to edit a code snippet successive
2413 2413 times. First we call the editor:
2414 2414
2415 2415 In [5]: ed
2416 2416 Editing... done. Executing edited code...
2417 2417 hello
2418 2418 Out[5]: "print 'hello'n"
2419 2419
2420 2420 Now we call it again with the previous output (stored in _):
2421 2421
2422 2422 In [6]: ed _
2423 2423 Editing... done. Executing edited code...
2424 2424 hello world
2425 2425 Out[6]: "print 'hello world'n"
2426 2426
2427 2427 Now we call it with the output #8 (stored in _8, also as Out[8]):
2428 2428
2429 2429 In [7]: ed _8
2430 2430 Editing... done. Executing edited code...
2431 2431 hello again
2432 2432 Out[7]: "print 'hello again'n"
2433 2433
2434 2434
2435 2435 Changing the default editor hook:
2436 2436
2437 2437 If you wish to write your own editor hook, you can put it in a
2438 2438 configuration file which you load at startup time. The default hook
2439 2439 is defined in the IPython.core.hooks module, and you can use that as a
2440 2440 starting example for further modifications. That file also has
2441 2441 general instructions on how to set a new hook for use once you've
2442 2442 defined it."""
2443 2443 opts,args = self.parse_options(parameter_s,'prxn:')
2444 2444
2445 2445 try:
2446 2446 filename, lineno, is_temp = self._find_edit_target(args, opts, last_call)
2447 2447 except MacroToEdit as e:
2448 2448 self._edit_macro(args, e.args[0])
2449 2449 return
2450 2450
2451 2451 # do actual editing here
2452 2452 print 'Editing...',
2453 2453 sys.stdout.flush()
2454 2454 try:
2455 2455 # Quote filenames that may have spaces in them
2456 2456 if ' ' in filename:
2457 2457 filename = "'%s'" % filename
2458 2458 self.shell.hooks.editor(filename,lineno)
2459 2459 except TryNext:
2460 2460 warn('Could not open editor')
2461 2461 return
2462 2462
2463 2463 # XXX TODO: should this be generalized for all string vars?
2464 2464 # For now, this is special-cased to blocks created by cpaste
2465 2465 if args.strip() == 'pasted_block':
2466 2466 self.shell.user_ns['pasted_block'] = file_read(filename)
2467 2467
2468 2468 if 'x' in opts: # -x prevents actual execution
2469 2469 print
2470 2470 else:
2471 2471 print 'done. Executing edited code...'
2472 2472 if 'r' in opts: # Untranslated IPython code
2473 2473 self.shell.run_cell(file_read(filename),
2474 2474 store_history=False)
2475 2475 else:
2476 2476 self.shell.safe_execfile(filename,self.shell.user_ns,
2477 2477 self.shell.user_ns)
2478 2478
2479 2479 if is_temp:
2480 2480 try:
2481 2481 return open(filename).read()
2482 2482 except IOError,msg:
2483 2483 if msg.filename == filename:
2484 2484 warn('File not found. Did you forget to save?')
2485 2485 return
2486 2486 else:
2487 2487 self.shell.showtraceback()
2488 2488
2489 2489 def magic_xmode(self,parameter_s = ''):
2490 2490 """Switch modes for the exception handlers.
2491 2491
2492 2492 Valid modes: Plain, Context and Verbose.
2493 2493
2494 2494 If called without arguments, acts as a toggle."""
2495 2495
2496 2496 def xmode_switch_err(name):
2497 2497 warn('Error changing %s exception modes.\n%s' %
2498 2498 (name,sys.exc_info()[1]))
2499 2499
2500 2500 shell = self.shell
2501 2501 new_mode = parameter_s.strip().capitalize()
2502 2502 try:
2503 2503 shell.InteractiveTB.set_mode(mode=new_mode)
2504 2504 print 'Exception reporting mode:',shell.InteractiveTB.mode
2505 2505 except:
2506 2506 xmode_switch_err('user')
2507 2507
2508 2508 def magic_colors(self,parameter_s = ''):
2509 2509 """Switch color scheme for prompts, info system and exception handlers.
2510 2510
2511 2511 Currently implemented schemes: NoColor, Linux, LightBG.
2512 2512
2513 2513 Color scheme names are not case-sensitive.
2514 2514
2515 2515 Examples
2516 2516 --------
2517 2517 To get a plain black and white terminal::
2518 2518
2519 2519 %colors nocolor
2520 2520 """
2521 2521
2522 2522 def color_switch_err(name):
2523 2523 warn('Error changing %s color schemes.\n%s' %
2524 2524 (name,sys.exc_info()[1]))
2525 2525
2526 2526
2527 2527 new_scheme = parameter_s.strip()
2528 2528 if not new_scheme:
2529 2529 raise UsageError(
2530 2530 "%colors: you must specify a color scheme. See '%colors?'")
2531 2531 return
2532 2532 # local shortcut
2533 2533 shell = self.shell
2534 2534
2535 2535 import IPython.utils.rlineimpl as readline
2536 2536
2537 2537 if not shell.colors_force and \
2538 2538 not readline.have_readline and sys.platform == "win32":
2539 2539 msg = """\
2540 2540 Proper color support under MS Windows requires the pyreadline library.
2541 2541 You can find it at:
2542 2542 http://ipython.org/pyreadline.html
2543 2543 Gary's readline needs the ctypes module, from:
2544 2544 http://starship.python.net/crew/theller/ctypes
2545 2545 (Note that ctypes is already part of Python versions 2.5 and newer).
2546 2546
2547 2547 Defaulting color scheme to 'NoColor'"""
2548 2548 new_scheme = 'NoColor'
2549 2549 warn(msg)
2550 2550
2551 2551 # readline option is 0
2552 2552 if not shell.colors_force and not shell.has_readline:
2553 2553 new_scheme = 'NoColor'
2554 2554
2555 2555 # Set prompt colors
2556 2556 try:
2557 2557 shell.prompt_manager.color_scheme = new_scheme
2558 2558 except:
2559 2559 color_switch_err('prompt')
2560 2560 else:
2561 2561 shell.colors = \
2562 2562 shell.prompt_manager.color_scheme_table.active_scheme_name
2563 2563 # Set exception colors
2564 2564 try:
2565 2565 shell.InteractiveTB.set_colors(scheme = new_scheme)
2566 2566 shell.SyntaxTB.set_colors(scheme = new_scheme)
2567 2567 except:
2568 2568 color_switch_err('exception')
2569 2569
2570 2570 # Set info (for 'object?') colors
2571 2571 if shell.color_info:
2572 2572 try:
2573 2573 shell.inspector.set_active_scheme(new_scheme)
2574 2574 except:
2575 2575 color_switch_err('object inspector')
2576 2576 else:
2577 2577 shell.inspector.set_active_scheme('NoColor')
2578 2578
2579 2579 def magic_pprint(self, parameter_s=''):
2580 2580 """Toggle pretty printing on/off."""
2581 2581 ptformatter = self.shell.display_formatter.formatters['text/plain']
2582 2582 ptformatter.pprint = bool(1 - ptformatter.pprint)
2583 2583 print 'Pretty printing has been turned', \
2584 2584 ['OFF','ON'][ptformatter.pprint]
2585 2585
2586 2586 #......................................................................
2587 2587 # Functions to implement unix shell-type things
2588 2588
2589 2589 @skip_doctest
2590 2590 def magic_alias(self, parameter_s = ''):
2591 2591 """Define an alias for a system command.
2592 2592
2593 2593 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2594 2594
2595 2595 Then, typing 'alias_name params' will execute the system command 'cmd
2596 2596 params' (from your underlying operating system).
2597 2597
2598 2598 Aliases have lower precedence than magic functions and Python normal
2599 2599 variables, so if 'foo' is both a Python variable and an alias, the
2600 2600 alias can not be executed until 'del foo' removes the Python variable.
2601 2601
2602 2602 You can use the %l specifier in an alias definition to represent the
2603 2603 whole line when the alias is called. For example:
2604 2604
2605 2605 In [2]: alias bracket echo "Input in brackets: <%l>"
2606 2606 In [3]: bracket hello world
2607 2607 Input in brackets: <hello world>
2608 2608
2609 2609 You can also define aliases with parameters using %s specifiers (one
2610 2610 per parameter):
2611 2611
2612 2612 In [1]: alias parts echo first %s second %s
2613 2613 In [2]: %parts A B
2614 2614 first A second B
2615 2615 In [3]: %parts A
2616 2616 Incorrect number of arguments: 2 expected.
2617 2617 parts is an alias to: 'echo first %s second %s'
2618 2618
2619 2619 Note that %l and %s are mutually exclusive. You can only use one or
2620 2620 the other in your aliases.
2621 2621
2622 2622 Aliases expand Python variables just like system calls using ! or !!
2623 2623 do: all expressions prefixed with '$' get expanded. For details of
2624 2624 the semantic rules, see PEP-215:
2625 2625 http://www.python.org/peps/pep-0215.html. This is the library used by
2626 2626 IPython for variable expansion. If you want to access a true shell
2627 2627 variable, an extra $ is necessary to prevent its expansion by IPython:
2628 2628
2629 2629 In [6]: alias show echo
2630 2630 In [7]: PATH='A Python string'
2631 2631 In [8]: show $PATH
2632 2632 A Python string
2633 2633 In [9]: show $$PATH
2634 2634 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2635 2635
2636 2636 You can use the alias facility to acess all of $PATH. See the %rehash
2637 2637 and %rehashx functions, which automatically create aliases for the
2638 2638 contents of your $PATH.
2639 2639
2640 2640 If called with no parameters, %alias prints the current alias table."""
2641 2641
2642 2642 par = parameter_s.strip()
2643 2643 if not par:
2644 2644 stored = self.db.get('stored_aliases', {} )
2645 2645 aliases = sorted(self.shell.alias_manager.aliases)
2646 2646 # for k, v in stored:
2647 2647 # atab.append(k, v[0])
2648 2648
2649 2649 print "Total number of aliases:", len(aliases)
2650 2650 sys.stdout.flush()
2651 2651 return aliases
2652 2652
2653 2653 # Now try to define a new one
2654 2654 try:
2655 2655 alias,cmd = par.split(None, 1)
2656 2656 except:
2657 2657 print oinspect.getdoc(self.magic_alias)
2658 2658 else:
2659 2659 self.shell.alias_manager.soft_define_alias(alias, cmd)
2660 2660 # end magic_alias
2661 2661
2662 2662 def magic_unalias(self, parameter_s = ''):
2663 2663 """Remove an alias"""
2664 2664
2665 2665 aname = parameter_s.strip()
2666 2666 self.shell.alias_manager.undefine_alias(aname)
2667 2667 stored = self.db.get('stored_aliases', {} )
2668 2668 if aname in stored:
2669 2669 print "Removing %stored alias",aname
2670 2670 del stored[aname]
2671 2671 self.db['stored_aliases'] = stored
2672 2672
2673 2673 def magic_rehashx(self, parameter_s = ''):
2674 2674 """Update the alias table with all executable files in $PATH.
2675 2675
2676 2676 This version explicitly checks that every entry in $PATH is a file
2677 2677 with execute access (os.X_OK), so it is much slower than %rehash.
2678 2678
2679 2679 Under Windows, it checks executability as a match agains a
2680 2680 '|'-separated string of extensions, stored in the IPython config
2681 2681 variable win_exec_ext. This defaults to 'exe|com|bat'.
2682 2682
2683 2683 This function also resets the root module cache of module completer,
2684 2684 used on slow filesystems.
2685 2685 """
2686 2686 from IPython.core.alias import InvalidAliasError
2687 2687
2688 2688 # for the benefit of module completer in ipy_completers.py
2689 2689 del self.shell.db['rootmodules']
2690 2690
2691 2691 path = [os.path.abspath(os.path.expanduser(p)) for p in
2692 2692 os.environ.get('PATH','').split(os.pathsep)]
2693 2693 path = filter(os.path.isdir,path)
2694 2694
2695 2695 syscmdlist = []
2696 2696 # Now define isexec in a cross platform manner.
2697 2697 if os.name == 'posix':
2698 2698 isexec = lambda fname:os.path.isfile(fname) and \
2699 2699 os.access(fname,os.X_OK)
2700 2700 else:
2701 2701 try:
2702 2702 winext = os.environ['pathext'].replace(';','|').replace('.','')
2703 2703 except KeyError:
2704 2704 winext = 'exe|com|bat|py'
2705 2705 if 'py' not in winext:
2706 2706 winext += '|py'
2707 2707 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2708 2708 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2709 2709 savedir = os.getcwdu()
2710 2710
2711 2711 # Now walk the paths looking for executables to alias.
2712 2712 try:
2713 2713 # write the whole loop for posix/Windows so we don't have an if in
2714 2714 # the innermost part
2715 2715 if os.name == 'posix':
2716 2716 for pdir in path:
2717 2717 os.chdir(pdir)
2718 2718 for ff in os.listdir(pdir):
2719 2719 if isexec(ff):
2720 2720 try:
2721 2721 # Removes dots from the name since ipython
2722 2722 # will assume names with dots to be python.
2723 2723 self.shell.alias_manager.define_alias(
2724 2724 ff.replace('.',''), ff)
2725 2725 except InvalidAliasError:
2726 2726 pass
2727 2727 else:
2728 2728 syscmdlist.append(ff)
2729 2729 else:
2730 2730 no_alias = self.shell.alias_manager.no_alias
2731 2731 for pdir in path:
2732 2732 os.chdir(pdir)
2733 2733 for ff in os.listdir(pdir):
2734 2734 base, ext = os.path.splitext(ff)
2735 2735 if isexec(ff) and base.lower() not in no_alias:
2736 2736 if ext.lower() == '.exe':
2737 2737 ff = base
2738 2738 try:
2739 2739 # Removes dots from the name since ipython
2740 2740 # will assume names with dots to be python.
2741 2741 self.shell.alias_manager.define_alias(
2742 2742 base.lower().replace('.',''), ff)
2743 2743 except InvalidAliasError:
2744 2744 pass
2745 2745 syscmdlist.append(ff)
2746 2746 self.shell.db['syscmdlist'] = syscmdlist
2747 2747 finally:
2748 2748 os.chdir(savedir)
2749 2749
2750 2750 @skip_doctest
2751 2751 def magic_pwd(self, parameter_s = ''):
2752 2752 """Return the current working directory path.
2753 2753
2754 2754 Examples
2755 2755 --------
2756 2756 ::
2757 2757
2758 2758 In [9]: pwd
2759 2759 Out[9]: '/home/tsuser/sprint/ipython'
2760 2760 """
2761 2761 return os.getcwdu()
2762 2762
2763 2763 @skip_doctest
2764 2764 def magic_cd(self, parameter_s=''):
2765 2765 """Change the current working directory.
2766 2766
2767 2767 This command automatically maintains an internal list of directories
2768 2768 you visit during your IPython session, in the variable _dh. The
2769 2769 command %dhist shows this history nicely formatted. You can also
2770 2770 do 'cd -<tab>' to see directory history conveniently.
2771 2771
2772 2772 Usage:
2773 2773
2774 2774 cd 'dir': changes to directory 'dir'.
2775 2775
2776 2776 cd -: changes to the last visited directory.
2777 2777
2778 2778 cd -<n>: changes to the n-th directory in the directory history.
2779 2779
2780 2780 cd --foo: change to directory that matches 'foo' in history
2781 2781
2782 2782 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2783 2783 (note: cd <bookmark_name> is enough if there is no
2784 2784 directory <bookmark_name>, but a bookmark with the name exists.)
2785 2785 'cd -b <tab>' allows you to tab-complete bookmark names.
2786 2786
2787 2787 Options:
2788 2788
2789 2789 -q: quiet. Do not print the working directory after the cd command is
2790 2790 executed. By default IPython's cd command does print this directory,
2791 2791 since the default prompts do not display path information.
2792 2792
2793 2793 Note that !cd doesn't work for this purpose because the shell where
2794 2794 !command runs is immediately discarded after executing 'command'.
2795 2795
2796 2796 Examples
2797 2797 --------
2798 2798 ::
2799 2799
2800 2800 In [10]: cd parent/child
2801 2801 /home/tsuser/parent/child
2802 2802 """
2803 2803
2804 2804 parameter_s = parameter_s.strip()
2805 2805 #bkms = self.shell.persist.get("bookmarks",{})
2806 2806
2807 2807 oldcwd = os.getcwdu()
2808 2808 numcd = re.match(r'(-)(\d+)$',parameter_s)
2809 2809 # jump in directory history by number
2810 2810 if numcd:
2811 2811 nn = int(numcd.group(2))
2812 2812 try:
2813 2813 ps = self.shell.user_ns['_dh'][nn]
2814 2814 except IndexError:
2815 2815 print 'The requested directory does not exist in history.'
2816 2816 return
2817 2817 else:
2818 2818 opts = {}
2819 2819 elif parameter_s.startswith('--'):
2820 2820 ps = None
2821 2821 fallback = None
2822 2822 pat = parameter_s[2:]
2823 2823 dh = self.shell.user_ns['_dh']
2824 2824 # first search only by basename (last component)
2825 2825 for ent in reversed(dh):
2826 2826 if pat in os.path.basename(ent) and os.path.isdir(ent):
2827 2827 ps = ent
2828 2828 break
2829 2829
2830 2830 if fallback is None and pat in ent and os.path.isdir(ent):
2831 2831 fallback = ent
2832 2832
2833 2833 # if we have no last part match, pick the first full path match
2834 2834 if ps is None:
2835 2835 ps = fallback
2836 2836
2837 2837 if ps is None:
2838 2838 print "No matching entry in directory history"
2839 2839 return
2840 2840 else:
2841 2841 opts = {}
2842 2842
2843 2843
2844 2844 else:
2845 2845 #turn all non-space-escaping backslashes to slashes,
2846 2846 # for c:\windows\directory\names\
2847 2847 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2848 2848 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2849 2849 # jump to previous
2850 2850 if ps == '-':
2851 2851 try:
2852 2852 ps = self.shell.user_ns['_dh'][-2]
2853 2853 except IndexError:
2854 2854 raise UsageError('%cd -: No previous directory to change to.')
2855 2855 # jump to bookmark if needed
2856 2856 else:
2857 2857 if not os.path.isdir(ps) or opts.has_key('b'):
2858 2858 bkms = self.db.get('bookmarks', {})
2859 2859
2860 2860 if bkms.has_key(ps):
2861 2861 target = bkms[ps]
2862 2862 print '(bookmark:%s) -> %s' % (ps,target)
2863 2863 ps = target
2864 2864 else:
2865 2865 if opts.has_key('b'):
2866 2866 raise UsageError("Bookmark '%s' not found. "
2867 2867 "Use '%%bookmark -l' to see your bookmarks." % ps)
2868 2868
2869 2869 # strip extra quotes on Windows, because os.chdir doesn't like them
2870 2870 ps = unquote_filename(ps)
2871 2871 # at this point ps should point to the target dir
2872 2872 if ps:
2873 2873 try:
2874 2874 os.chdir(os.path.expanduser(ps))
2875 2875 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2876 2876 set_term_title('IPython: ' + abbrev_cwd())
2877 2877 except OSError:
2878 2878 print sys.exc_info()[1]
2879 2879 else:
2880 2880 cwd = os.getcwdu()
2881 2881 dhist = self.shell.user_ns['_dh']
2882 2882 if oldcwd != cwd:
2883 2883 dhist.append(cwd)
2884 2884 self.db['dhist'] = compress_dhist(dhist)[-100:]
2885 2885
2886 2886 else:
2887 2887 os.chdir(self.shell.home_dir)
2888 2888 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2889 2889 set_term_title('IPython: ' + '~')
2890 2890 cwd = os.getcwdu()
2891 2891 dhist = self.shell.user_ns['_dh']
2892 2892
2893 2893 if oldcwd != cwd:
2894 2894 dhist.append(cwd)
2895 2895 self.db['dhist'] = compress_dhist(dhist)[-100:]
2896 2896 if not 'q' in opts and self.shell.user_ns['_dh']:
2897 2897 print self.shell.user_ns['_dh'][-1]
2898 2898
2899 2899
2900 2900 def magic_env(self, parameter_s=''):
2901 2901 """List environment variables."""
2902 2902
2903 2903 return os.environ.data
2904 2904
2905 2905 def magic_pushd(self, parameter_s=''):
2906 2906 """Place the current dir on stack and change directory.
2907 2907
2908 2908 Usage:\\
2909 2909 %pushd ['dirname']
2910 2910 """
2911 2911
2912 2912 dir_s = self.shell.dir_stack
2913 2913 tgt = os.path.expanduser(unquote_filename(parameter_s))
2914 2914 cwd = os.getcwdu().replace(self.home_dir,'~')
2915 2915 if tgt:
2916 2916 self.magic_cd(parameter_s)
2917 2917 dir_s.insert(0,cwd)
2918 2918 return self.magic_dirs()
2919 2919
2920 2920 def magic_popd(self, parameter_s=''):
2921 2921 """Change to directory popped off the top of the stack.
2922 2922 """
2923 2923 if not self.shell.dir_stack:
2924 2924 raise UsageError("%popd on empty stack")
2925 2925 top = self.shell.dir_stack.pop(0)
2926 2926 self.magic_cd(top)
2927 2927 print "popd ->",top
2928 2928
2929 2929 def magic_dirs(self, parameter_s=''):
2930 2930 """Return the current directory stack."""
2931 2931
2932 2932 return self.shell.dir_stack
2933 2933
2934 2934 def magic_dhist(self, parameter_s=''):
2935 2935 """Print your history of visited directories.
2936 2936
2937 2937 %dhist -> print full history\\
2938 2938 %dhist n -> print last n entries only\\
2939 2939 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2940 2940
2941 2941 This history is automatically maintained by the %cd command, and
2942 2942 always available as the global list variable _dh. You can use %cd -<n>
2943 2943 to go to directory number <n>.
2944 2944
2945 2945 Note that most of time, you should view directory history by entering
2946 2946 cd -<TAB>.
2947 2947
2948 2948 """
2949 2949
2950 2950 dh = self.shell.user_ns['_dh']
2951 2951 if parameter_s:
2952 2952 try:
2953 2953 args = map(int,parameter_s.split())
2954 2954 except:
2955 2955 self.arg_err(Magic.magic_dhist)
2956 2956 return
2957 2957 if len(args) == 1:
2958 2958 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2959 2959 elif len(args) == 2:
2960 2960 ini,fin = args
2961 2961 else:
2962 2962 self.arg_err(Magic.magic_dhist)
2963 2963 return
2964 2964 else:
2965 2965 ini,fin = 0,len(dh)
2966 2966 nlprint(dh,
2967 2967 header = 'Directory history (kept in _dh)',
2968 2968 start=ini,stop=fin)
2969 2969
2970 2970 @skip_doctest
2971 2971 def magic_sc(self, parameter_s=''):
2972 2972 """Shell capture - execute a shell command and capture its output.
2973 2973
2974 2974 DEPRECATED. Suboptimal, retained for backwards compatibility.
2975 2975
2976 2976 You should use the form 'var = !command' instead. Example:
2977 2977
2978 2978 "%sc -l myfiles = ls ~" should now be written as
2979 2979
2980 2980 "myfiles = !ls ~"
2981 2981
2982 2982 myfiles.s, myfiles.l and myfiles.n still apply as documented
2983 2983 below.
2984 2984
2985 2985 --
2986 2986 %sc [options] varname=command
2987 2987
2988 2988 IPython will run the given command using commands.getoutput(), and
2989 2989 will then update the user's interactive namespace with a variable
2990 2990 called varname, containing the value of the call. Your command can
2991 2991 contain shell wildcards, pipes, etc.
2992 2992
2993 2993 The '=' sign in the syntax is mandatory, and the variable name you
2994 2994 supply must follow Python's standard conventions for valid names.
2995 2995
2996 2996 (A special format without variable name exists for internal use)
2997 2997
2998 2998 Options:
2999 2999
3000 3000 -l: list output. Split the output on newlines into a list before
3001 3001 assigning it to the given variable. By default the output is stored
3002 3002 as a single string.
3003 3003
3004 3004 -v: verbose. Print the contents of the variable.
3005 3005
3006 3006 In most cases you should not need to split as a list, because the
3007 3007 returned value is a special type of string which can automatically
3008 3008 provide its contents either as a list (split on newlines) or as a
3009 3009 space-separated string. These are convenient, respectively, either
3010 3010 for sequential processing or to be passed to a shell command.
3011 3011
3012 3012 For example:
3013 3013
3014 3014 # all-random
3015 3015
3016 3016 # Capture into variable a
3017 3017 In [1]: sc a=ls *py
3018 3018
3019 3019 # a is a string with embedded newlines
3020 3020 In [2]: a
3021 3021 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3022 3022
3023 3023 # which can be seen as a list:
3024 3024 In [3]: a.l
3025 3025 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3026 3026
3027 3027 # or as a whitespace-separated string:
3028 3028 In [4]: a.s
3029 3029 Out[4]: 'setup.py win32_manual_post_install.py'
3030 3030
3031 3031 # a.s is useful to pass as a single command line:
3032 3032 In [5]: !wc -l $a.s
3033 3033 146 setup.py
3034 3034 130 win32_manual_post_install.py
3035 3035 276 total
3036 3036
3037 3037 # while the list form is useful to loop over:
3038 3038 In [6]: for f in a.l:
3039 3039 ...: !wc -l $f
3040 3040 ...:
3041 3041 146 setup.py
3042 3042 130 win32_manual_post_install.py
3043 3043
3044 3044 Similiarly, the lists returned by the -l option are also special, in
3045 3045 the sense that you can equally invoke the .s attribute on them to
3046 3046 automatically get a whitespace-separated string from their contents:
3047 3047
3048 3048 In [7]: sc -l b=ls *py
3049 3049
3050 3050 In [8]: b
3051 3051 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3052 3052
3053 3053 In [9]: b.s
3054 3054 Out[9]: 'setup.py win32_manual_post_install.py'
3055 3055
3056 3056 In summary, both the lists and strings used for ouptut capture have
3057 3057 the following special attributes:
3058 3058
3059 3059 .l (or .list) : value as list.
3060 3060 .n (or .nlstr): value as newline-separated string.
3061 3061 .s (or .spstr): value as space-separated string.
3062 3062 """
3063 3063
3064 3064 opts,args = self.parse_options(parameter_s,'lv')
3065 3065 # Try to get a variable name and command to run
3066 3066 try:
3067 3067 # the variable name must be obtained from the parse_options
3068 3068 # output, which uses shlex.split to strip options out.
3069 3069 var,_ = args.split('=',1)
3070 3070 var = var.strip()
3071 3071 # But the the command has to be extracted from the original input
3072 3072 # parameter_s, not on what parse_options returns, to avoid the
3073 3073 # quote stripping which shlex.split performs on it.
3074 3074 _,cmd = parameter_s.split('=',1)
3075 3075 except ValueError:
3076 3076 var,cmd = '',''
3077 3077 # If all looks ok, proceed
3078 3078 split = 'l' in opts
3079 3079 out = self.shell.getoutput(cmd, split=split)
3080 3080 if opts.has_key('v'):
3081 3081 print '%s ==\n%s' % (var,pformat(out))
3082 3082 if var:
3083 3083 self.shell.user_ns.update({var:out})
3084 3084 else:
3085 3085 return out
3086 3086
3087 3087 def magic_sx(self, parameter_s=''):
3088 3088 """Shell execute - run a shell command and capture its output.
3089 3089
3090 3090 %sx command
3091 3091
3092 3092 IPython will run the given command using commands.getoutput(), and
3093 3093 return the result formatted as a list (split on '\\n'). Since the
3094 3094 output is _returned_, it will be stored in ipython's regular output
3095 3095 cache Out[N] and in the '_N' automatic variables.
3096 3096
3097 3097 Notes:
3098 3098
3099 3099 1) If an input line begins with '!!', then %sx is automatically
3100 3100 invoked. That is, while:
3101 3101 !ls
3102 3102 causes ipython to simply issue system('ls'), typing
3103 3103 !!ls
3104 3104 is a shorthand equivalent to:
3105 3105 %sx ls
3106 3106
3107 3107 2) %sx differs from %sc in that %sx automatically splits into a list,
3108 3108 like '%sc -l'. The reason for this is to make it as easy as possible
3109 3109 to process line-oriented shell output via further python commands.
3110 3110 %sc is meant to provide much finer control, but requires more
3111 3111 typing.
3112 3112
3113 3113 3) Just like %sc -l, this is a list with special attributes:
3114 3114
3115 3115 .l (or .list) : value as list.
3116 3116 .n (or .nlstr): value as newline-separated string.
3117 3117 .s (or .spstr): value as whitespace-separated string.
3118 3118
3119 3119 This is very useful when trying to use such lists as arguments to
3120 3120 system commands."""
3121 3121
3122 3122 if parameter_s:
3123 3123 return self.shell.getoutput(parameter_s)
3124 3124
3125 3125
3126 3126 def magic_bookmark(self, parameter_s=''):
3127 3127 """Manage IPython's bookmark system.
3128 3128
3129 3129 %bookmark <name> - set bookmark to current dir
3130 3130 %bookmark <name> <dir> - set bookmark to <dir>
3131 3131 %bookmark -l - list all bookmarks
3132 3132 %bookmark -d <name> - remove bookmark
3133 3133 %bookmark -r - remove all bookmarks
3134 3134
3135 3135 You can later on access a bookmarked folder with:
3136 3136 %cd -b <name>
3137 3137 or simply '%cd <name>' if there is no directory called <name> AND
3138 3138 there is such a bookmark defined.
3139 3139
3140 3140 Your bookmarks persist through IPython sessions, but they are
3141 3141 associated with each profile."""
3142 3142
3143 3143 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3144 3144 if len(args) > 2:
3145 3145 raise UsageError("%bookmark: too many arguments")
3146 3146
3147 3147 bkms = self.db.get('bookmarks',{})
3148 3148
3149 3149 if opts.has_key('d'):
3150 3150 try:
3151 3151 todel = args[0]
3152 3152 except IndexError:
3153 3153 raise UsageError(
3154 3154 "%bookmark -d: must provide a bookmark to delete")
3155 3155 else:
3156 3156 try:
3157 3157 del bkms[todel]
3158 3158 except KeyError:
3159 3159 raise UsageError(
3160 3160 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3161 3161
3162 3162 elif opts.has_key('r'):
3163 3163 bkms = {}
3164 3164 elif opts.has_key('l'):
3165 3165 bks = bkms.keys()
3166 3166 bks.sort()
3167 3167 if bks:
3168 3168 size = max(map(len,bks))
3169 3169 else:
3170 3170 size = 0
3171 3171 fmt = '%-'+str(size)+'s -> %s'
3172 3172 print 'Current bookmarks:'
3173 3173 for bk in bks:
3174 3174 print fmt % (bk,bkms[bk])
3175 3175 else:
3176 3176 if not args:
3177 3177 raise UsageError("%bookmark: You must specify the bookmark name")
3178 3178 elif len(args)==1:
3179 3179 bkms[args[0]] = os.getcwdu()
3180 3180 elif len(args)==2:
3181 3181 bkms[args[0]] = args[1]
3182 3182 self.db['bookmarks'] = bkms
3183 3183
3184 3184 def magic_pycat(self, parameter_s=''):
3185 3185 """Show a syntax-highlighted file through a pager.
3186 3186
3187 3187 This magic is similar to the cat utility, but it will assume the file
3188 3188 to be Python source and will show it with syntax highlighting. """
3189 3189
3190 3190 try:
3191 3191 filename = get_py_filename(parameter_s)
3192 3192 cont = file_read(filename)
3193 3193 except IOError:
3194 3194 try:
3195 3195 cont = eval(parameter_s,self.user_ns)
3196 3196 except NameError:
3197 3197 cont = None
3198 3198 if cont is None:
3199 3199 print "Error: no such file or variable"
3200 3200 return
3201 3201
3202 3202 page.page(self.shell.pycolorize(cont))
3203 3203
3204 3204 def magic_quickref(self,arg):
3205 3205 """ Show a quick reference sheet """
3206 3206 import IPython.core.usage
3207 3207 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3208 3208
3209 3209 page.page(qr)
3210 3210
3211 3211 def magic_doctest_mode(self,parameter_s=''):
3212 3212 """Toggle doctest mode on and off.
3213 3213
3214 3214 This mode is intended to make IPython behave as much as possible like a
3215 3215 plain Python shell, from the perspective of how its prompts, exceptions
3216 3216 and output look. This makes it easy to copy and paste parts of a
3217 3217 session into doctests. It does so by:
3218 3218
3219 3219 - Changing the prompts to the classic ``>>>`` ones.
3220 3220 - Changing the exception reporting mode to 'Plain'.
3221 3221 - Disabling pretty-printing of output.
3222 3222
3223 3223 Note that IPython also supports the pasting of code snippets that have
3224 3224 leading '>>>' and '...' prompts in them. This means that you can paste
3225 3225 doctests from files or docstrings (even if they have leading
3226 3226 whitespace), and the code will execute correctly. You can then use
3227 3227 '%history -t' to see the translated history; this will give you the
3228 3228 input after removal of all the leading prompts and whitespace, which
3229 3229 can be pasted back into an editor.
3230 3230
3231 3231 With these features, you can switch into this mode easily whenever you
3232 3232 need to do testing and changes to doctests, without having to leave
3233 3233 your existing IPython session.
3234 3234 """
3235 3235
3236 3236 from IPython.utils.ipstruct import Struct
3237 3237
3238 3238 # Shorthands
3239 3239 shell = self.shell
3240 3240 pm = shell.prompt_manager
3241 3241 meta = shell.meta
3242 3242 disp_formatter = self.shell.display_formatter
3243 3243 ptformatter = disp_formatter.formatters['text/plain']
3244 3244 # dstore is a data store kept in the instance metadata bag to track any
3245 3245 # changes we make, so we can undo them later.
3246 3246 dstore = meta.setdefault('doctest_mode',Struct())
3247 3247 save_dstore = dstore.setdefault
3248 3248
3249 3249 # save a few values we'll need to recover later
3250 3250 mode = save_dstore('mode',False)
3251 3251 save_dstore('rc_pprint',ptformatter.pprint)
3252 3252 save_dstore('xmode',shell.InteractiveTB.mode)
3253 3253 save_dstore('rc_separate_out',shell.separate_out)
3254 3254 save_dstore('rc_separate_out2',shell.separate_out2)
3255 3255 save_dstore('rc_prompts_pad_left',pm.justify)
3256 3256 save_dstore('rc_separate_in',shell.separate_in)
3257 3257 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3258 3258 save_dstore('prompt_templates',(pm.in_template, pm.in2_template, pm.out_template))
3259 3259
3260 3260 if mode == False:
3261 3261 # turn on
3262 3262 pm.in_template = '>>> '
3263 3263 pm.in2_template = '... '
3264 3264 pm.out_template = ''
3265 3265
3266 3266 # Prompt separators like plain python
3267 3267 shell.separate_in = ''
3268 3268 shell.separate_out = ''
3269 3269 shell.separate_out2 = ''
3270 3270
3271 3271 pm.justify = False
3272 3272
3273 3273 ptformatter.pprint = False
3274 3274 disp_formatter.plain_text_only = True
3275 3275
3276 3276 shell.magic_xmode('Plain')
3277 3277 else:
3278 3278 # turn off
3279 3279 pm.in_template, pm.in2_template, pm.out_template = dstore.prompt_templates
3280 3280
3281 3281 shell.separate_in = dstore.rc_separate_in
3282 3282
3283 3283 shell.separate_out = dstore.rc_separate_out
3284 3284 shell.separate_out2 = dstore.rc_separate_out2
3285 3285
3286 3286 pm.justify = dstore.rc_prompts_pad_left
3287 3287
3288 3288 ptformatter.pprint = dstore.rc_pprint
3289 3289 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3290 3290
3291 3291 shell.magic_xmode(dstore.xmode)
3292 3292
3293 3293 # Store new mode and inform
3294 3294 dstore.mode = bool(1-int(mode))
3295 3295 mode_label = ['OFF','ON'][dstore.mode]
3296 3296 print 'Doctest mode is:', mode_label
3297 3297
3298 3298 def magic_gui(self, parameter_s=''):
3299 3299 """Enable or disable IPython GUI event loop integration.
3300 3300
3301 3301 %gui [GUINAME]
3302 3302
3303 3303 This magic replaces IPython's threaded shells that were activated
3304 3304 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3305 3305 can now be enabled at runtime and keyboard
3306 3306 interrupts should work without any problems. The following toolkits
3307 3307 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
3308 3308
3309 3309 %gui wx # enable wxPython event loop integration
3310 3310 %gui qt4|qt # enable PyQt4 event loop integration
3311 3311 %gui gtk # enable PyGTK event loop integration
3312 3312 %gui tk # enable Tk event loop integration
3313 3313 %gui OSX # enable Cocoa event loop integration
3314 3314 # (requires %matplotlib 1.1)
3315 3315 %gui # disable all event loop integration
3316 3316
3317 3317 WARNING: after any of these has been called you can simply create
3318 3318 an application object, but DO NOT start the event loop yourself, as
3319 3319 we have already handled that.
3320 3320 """
3321 3321 opts, arg = self.parse_options(parameter_s, '')
3322 3322 if arg=='': arg = None
3323 3323 try:
3324 3324 return self.enable_gui(arg)
3325 3325 except Exception as e:
3326 3326 # print simple error message, rather than traceback if we can't
3327 3327 # hook up the GUI
3328 3328 error(str(e))
3329 3329
3330 3330 def magic_load_ext(self, module_str):
3331 3331 """Load an IPython extension by its module name."""
3332 3332 return self.extension_manager.load_extension(module_str)
3333 3333
3334 3334 def magic_unload_ext(self, module_str):
3335 3335 """Unload an IPython extension by its module name."""
3336 3336 self.extension_manager.unload_extension(module_str)
3337 3337
3338 3338 def magic_reload_ext(self, module_str):
3339 3339 """Reload an IPython extension by its module name."""
3340 3340 self.extension_manager.reload_extension(module_str)
3341 3341
3342 3342 @skip_doctest
3343 3343 def magic_install_profiles(self, s):
3344 3344 """Install the default IPython profiles into the .ipython dir.
3345 3345
3346 3346 If the default profiles have already been installed, they will not
3347 3347 be overwritten. You can force overwriting them by using the ``-o``
3348 3348 option::
3349 3349
3350 3350 In [1]: %install_profiles -o
3351 3351 """
3352 3352 if '-o' in s:
3353 3353 overwrite = True
3354 3354 else:
3355 3355 overwrite = False
3356 3356 from IPython.config import profile
3357 3357 profile_dir = os.path.dirname(profile.__file__)
3358 3358 ipython_dir = self.ipython_dir
3359 3359 print "Installing profiles to: %s [overwrite=%s]"%(ipython_dir,overwrite)
3360 3360 for src in os.listdir(profile_dir):
3361 3361 if src.startswith('profile_'):
3362 3362 name = src.replace('profile_', '')
3363 3363 print " %s"%name
3364 3364 pd = ProfileDir.create_profile_dir_by_name(ipython_dir, name)
3365 3365 pd.copy_config_file('ipython_config.py', path=src,
3366 3366 overwrite=overwrite)
3367 3367
3368 3368 @skip_doctest
3369 3369 def magic_install_default_config(self, s):
3370 3370 """Install IPython's default config file into the .ipython dir.
3371 3371
3372 3372 If the default config file (:file:`ipython_config.py`) is already
3373 3373 installed, it will not be overwritten. You can force overwriting
3374 3374 by using the ``-o`` option::
3375 3375
3376 3376 In [1]: %install_default_config
3377 3377 """
3378 3378 if '-o' in s:
3379 3379 overwrite = True
3380 3380 else:
3381 3381 overwrite = False
3382 3382 pd = self.shell.profile_dir
3383 3383 print "Installing default config file in: %s" % pd.location
3384 3384 pd.copy_config_file('ipython_config.py', overwrite=overwrite)
3385 3385
3386 3386 # Pylab support: simple wrappers that activate pylab, load gui input
3387 3387 # handling and modify slightly %run
3388 3388
3389 3389 @skip_doctest
3390 3390 def _pylab_magic_run(self, parameter_s=''):
3391 3391 Magic.magic_run(self, parameter_s,
3392 3392 runner=mpl_runner(self.shell.safe_execfile))
3393 3393
3394 3394 _pylab_magic_run.__doc__ = magic_run.__doc__
3395 3395
3396 3396 @skip_doctest
3397 3397 def magic_pylab(self, s):
3398 3398 """Load numpy and matplotlib to work interactively.
3399 3399
3400 3400 %pylab [GUINAME]
3401 3401
3402 3402 This function lets you activate pylab (matplotlib, numpy and
3403 3403 interactive support) at any point during an IPython session.
3404 3404
3405 3405 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3406 3406 pylab and mlab, as well as all names from numpy and pylab.
3407 3407
3408 3408 If you are using the inline matplotlib backend for embedded figures,
3409 3409 you can adjust its behavior via the %config magic::
3410 3410
3411 3411 # enable SVG figures, necessary for SVG+XHTML export in the qtconsole
3412 3412 In [1]: %config InlineBackend.figure_format = 'svg'
3413 3413
3414 3414 # change the behavior of closing all figures at the end of each
3415 3415 # execution (cell), or allowing reuse of active figures across
3416 3416 # cells:
3417 3417 In [2]: %config InlineBackend.close_figures = False
3418 3418
3419 3419 Parameters
3420 3420 ----------
3421 3421 guiname : optional
3422 3422 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk',
3423 3423 'osx' or 'tk'). If given, the corresponding Matplotlib backend is
3424 3424 used, otherwise matplotlib's default (which you can override in your
3425 3425 matplotlib config file) is used.
3426 3426
3427 3427 Examples
3428 3428 --------
3429 3429 In this case, where the MPL default is TkAgg::
3430 3430
3431 3431 In [2]: %pylab
3432 3432
3433 3433 Welcome to pylab, a matplotlib-based Python environment.
3434 3434 Backend in use: TkAgg
3435 3435 For more information, type 'help(pylab)'.
3436 3436
3437 3437 But you can explicitly request a different backend::
3438 3438
3439 3439 In [3]: %pylab qt
3440 3440
3441 3441 Welcome to pylab, a matplotlib-based Python environment.
3442 3442 Backend in use: Qt4Agg
3443 3443 For more information, type 'help(pylab)'.
3444 3444 """
3445 3445
3446 3446 if Application.initialized():
3447 3447 app = Application.instance()
3448 3448 try:
3449 3449 import_all_status = app.pylab_import_all
3450 3450 except AttributeError:
3451 3451 import_all_status = True
3452 3452 else:
3453 3453 import_all_status = True
3454 3454
3455 3455 self.shell.enable_pylab(s, import_all=import_all_status)
3456 3456
3457 3457 def magic_tb(self, s):
3458 3458 """Print the last traceback with the currently active exception mode.
3459 3459
3460 3460 See %xmode for changing exception reporting modes."""
3461 3461 self.shell.showtraceback()
3462 3462
3463 3463 @skip_doctest
3464 3464 def magic_precision(self, s=''):
3465 3465 """Set floating point precision for pretty printing.
3466 3466
3467 3467 Can set either integer precision or a format string.
3468 3468
3469 3469 If numpy has been imported and precision is an int,
3470 3470 numpy display precision will also be set, via ``numpy.set_printoptions``.
3471 3471
3472 3472 If no argument is given, defaults will be restored.
3473 3473
3474 3474 Examples
3475 3475 --------
3476 3476 ::
3477 3477
3478 3478 In [1]: from math import pi
3479 3479
3480 3480 In [2]: %precision 3
3481 3481 Out[2]: u'%.3f'
3482 3482
3483 3483 In [3]: pi
3484 3484 Out[3]: 3.142
3485 3485
3486 3486 In [4]: %precision %i
3487 3487 Out[4]: u'%i'
3488 3488
3489 3489 In [5]: pi
3490 3490 Out[5]: 3
3491 3491
3492 3492 In [6]: %precision %e
3493 3493 Out[6]: u'%e'
3494 3494
3495 3495 In [7]: pi**10
3496 3496 Out[7]: 9.364805e+04
3497 3497
3498 3498 In [8]: %precision
3499 3499 Out[8]: u'%r'
3500 3500
3501 3501 In [9]: pi**10
3502 3502 Out[9]: 93648.047476082982
3503 3503
3504 3504 """
3505 3505
3506 3506 ptformatter = self.shell.display_formatter.formatters['text/plain']
3507 3507 ptformatter.float_precision = s
3508 3508 return ptformatter.float_format
3509 3509
3510 3510
3511 3511 @magic_arguments.magic_arguments()
3512 3512 @magic_arguments.argument(
3513 3513 '-e', '--export', action='store_true', default=False,
3514 3514 help='Export IPython history as a notebook. The filename argument '
3515 3515 'is used to specify the notebook name and format. For example '
3516 3516 'a filename of notebook.ipynb will result in a notebook name '
3517 3517 'of "notebook" and a format of "xml". Likewise using a ".json" '
3518 3518 'or ".py" file extension will write the notebook in the json '
3519 3519 'or py formats.'
3520 3520 )
3521 3521 @magic_arguments.argument(
3522 3522 '-f', '--format',
3523 3523 help='Convert an existing IPython notebook to a new format. This option '
3524 3524 'specifies the new format and can have the values: xml, json, py. '
3525 3525 'The target filename is choosen automatically based on the new '
3526 3526 'format. The filename argument gives the name of the source file.'
3527 3527 )
3528 3528 @magic_arguments.argument(
3529 3529 'filename', type=unicode,
3530 3530 help='Notebook name or filename'
3531 3531 )
3532 3532 def magic_notebook(self, s):
3533 3533 """Export and convert IPython notebooks.
3534 3534
3535 3535 This function can export the current IPython history to a notebook file
3536 3536 or can convert an existing notebook file into a different format. For
3537 3537 example, to export the history to "foo.ipynb" do "%notebook -e foo.ipynb".
3538 3538 To export the history to "foo.py" do "%notebook -e foo.py". To convert
3539 3539 "foo.ipynb" to "foo.json" do "%notebook -f json foo.ipynb". Possible
3540 3540 formats include (json/ipynb, py).
3541 3541 """
3542 3542 args = magic_arguments.parse_argstring(self.magic_notebook, s)
3543 3543
3544 3544 from IPython.nbformat import current
3545 3545 args.filename = unquote_filename(args.filename)
3546 3546 if args.export:
3547 3547 fname, name, format = current.parse_filename(args.filename)
3548 3548 cells = []
3549 3549 hist = list(self.history_manager.get_range())
3550 3550 for session, prompt_number, input in hist[:-1]:
3551 3551 cells.append(current.new_code_cell(prompt_number=prompt_number, input=input))
3552 3552 worksheet = current.new_worksheet(cells=cells)
3553 3553 nb = current.new_notebook(name=name,worksheets=[worksheet])
3554 3554 with open(fname, 'w') as f:
3555 3555 current.write(nb, f, format);
3556 3556 elif args.format is not None:
3557 3557 old_fname, old_name, old_format = current.parse_filename(args.filename)
3558 3558 new_format = args.format
3559 3559 if new_format == u'xml':
3560 3560 raise ValueError('Notebooks cannot be written as xml.')
3561 3561 elif new_format == u'ipynb' or new_format == u'json':
3562 3562 new_fname = old_name + u'.ipynb'
3563 3563 new_format = u'json'
3564 3564 elif new_format == u'py':
3565 3565 new_fname = old_name + u'.py'
3566 3566 else:
3567 3567 raise ValueError('Invalid notebook format: %s' % new_format)
3568 3568 with open(old_fname, 'r') as f:
3569 3569 s = f.read()
3570 3570 try:
3571 3571 nb = current.reads(s, old_format)
3572 3572 except:
3573 3573 nb = current.reads(s, u'xml')
3574 3574 with open(new_fname, 'w') as f:
3575 3575 current.write(nb, f, new_format)
3576 3576
3577 3577 def magic_config(self, s):
3578 3578 """configure IPython
3579 3579
3580 3580 %config Class[.trait=value]
3581 3581
3582 3582 This magic exposes most of the IPython config system. Any
3583 3583 Configurable class should be able to be configured with the simple
3584 3584 line::
3585 3585
3586 3586 %config Class.trait=value
3587 3587
3588 3588 Where `value` will be resolved in the user's namespace, if it is an
3589 3589 expression or variable name.
3590 3590
3591 3591 Examples
3592 3592 --------
3593 3593
3594 3594 To see what classes are availabe for config, pass no arguments::
3595 3595
3596 3596 In [1]: %config
3597 3597 Available objects for config:
3598 3598 TerminalInteractiveShell
3599 3599 HistoryManager
3600 3600 PrefilterManager
3601 3601 AliasManager
3602 3602 IPCompleter
3603 PromptManager
3603 3604 DisplayFormatter
3604 3605
3605 3606 To view what is configurable on a given class, just pass the class name::
3606 3607
3607 3608 In [2]: %config IPCompleter
3608 3609 IPCompleter options
3609 3610 -----------------
3610 3611 IPCompleter.omit__names=<Enum>
3611 3612 Current: 2
3612 3613 Choices: (0, 1, 2)
3613 3614 Instruct the completer to omit private method names
3614 3615 Specifically, when completing on ``object.<tab>``.
3615 3616 When 2 [default]: all names that start with '_' will be excluded.
3616 3617 When 1: all 'magic' names (``__foo__``) will be excluded.
3617 3618 When 0: nothing will be excluded.
3618 3619 IPCompleter.merge_completions=<CBool>
3619 3620 Current: True
3620 3621 Whether to merge completion results into a single list
3621 3622 If False, only the completion results from the first non-empty completer
3622 3623 will be returned.
3623 3624 IPCompleter.greedy=<CBool>
3624 3625 Current: False
3625 3626 Activate greedy completion
3626 3627 This will enable completion on elements of lists, results of function calls,
3627 3628 etc., but can be unsafe because the code is actually evaluated on TAB.
3628 3629
3629 3630 but the real use is in setting values::
3630 3631
3631 3632 In [3]: %config IPCompleter.greedy = True
3632 3633
3633 3634 and these values are read from the user_ns if they are variables::
3634 3635
3635 3636 In [4]: feeling_greedy=False
3636 3637
3637 3638 In [5]: %config IPCompleter.greedy = feeling_greedy
3638 3639
3639 3640 """
3640 3641 from IPython.config.loader import Config
3641 3642 # some IPython objects are Configurable, but do not yet have
3642 3643 # any configurable traits. Exclude them from the effects of
3643 3644 # this magic, as their presence is just noise:
3644 3645 configurables = [ c for c in self.configurables if c.__class__.class_traits(config=True) ]
3645 3646 classnames = [ c.__class__.__name__ for c in configurables ]
3646 3647
3647 3648 line = s.strip()
3648 3649 if not line:
3649 3650 # print available configurable names
3650 3651 print "Available objects for config:"
3651 3652 for name in classnames:
3652 3653 print " ", name
3653 3654 return
3654 3655 elif line in classnames:
3655 3656 # `%config TerminalInteractiveShell` will print trait info for
3656 3657 # TerminalInteractiveShell
3657 3658 c = configurables[classnames.index(line)]
3658 3659 cls = c.__class__
3659 3660 help = cls.class_get_help(c)
3660 3661 # strip leading '--' from cl-args:
3661 3662 help = re.sub(re.compile(r'^--', re.MULTILINE), '', help)
3662 3663 print help
3663 3664 return
3664 3665 elif '=' not in line:
3665 3666 raise UsageError("Invalid config statement: %r, should be Class.trait = value" % line)
3666 3667
3667 3668
3668 3669 # otherwise, assume we are setting configurables.
3669 3670 # leave quotes on args when splitting, because we want
3670 3671 # unquoted args to eval in user_ns
3671 3672 cfg = Config()
3672 3673 exec "cfg."+line in locals(), self.user_ns
3673 3674
3674 3675 for configurable in configurables:
3675 3676 try:
3676 3677 configurable.update_config(cfg)
3677 3678 except Exception as e:
3678 3679 error(e)
3679 3680
3680 3681 # end Magic
General Comments 0
You need to be logged in to leave comments. Login now