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