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