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