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