##// END OF EJS Templates
Made upgrade_dir executable on win32
vivainio -
Show More
@@ -1,2952 +1,2952 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Magic functions for InteractiveShell.
3 3
4 $Id: Magic.py 1205 2006-03-12 18:31:19Z vivainio $"""
4 $Id: Magic.py 1209 2006-03-12 20:34:28Z 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_timeit(self, parameter_s =''):
1564 1564 """Time execution of a Python statement or expression
1565 1565
1566 1566 Usage:\\
1567 1567 %timeit [-n<N> -r<R> [-t|-c]] statement
1568 1568
1569 1569 Time execution of a Python statement or expression using the timeit
1570 1570 module.
1571 1571
1572 1572 Options:
1573 1573 -n<N>: execute the given statement <N> times in a loop. If this value
1574 1574 is not given, a fitting value is chosen.
1575 1575
1576 1576 -r<R>: repeat the loop iteration <R> times and take the best result.
1577 1577 Default: 3
1578 1578
1579 1579 -t: use time.time to measure the time, which is the default on Unix.
1580 1580 This function measures wall time.
1581 1581
1582 1582 -c: use time.clock to measure the time, which is the default on
1583 1583 Windows and measures wall time. On Unix, resource.getrusage is used
1584 1584 instead and returns the CPU user time.
1585 1585
1586 1586 -p<P>: use a precision of <P> digits to display the timing result.
1587 1587 Default: 3
1588 1588
1589 1589
1590 1590 Examples:\\
1591 1591 In [1]: %timeit pass
1592 1592 10000000 loops, best of 3: 53.3 ns per loop
1593 1593
1594 1594 In [2]: u = None
1595 1595
1596 1596 In [3]: %timeit u is None
1597 1597 10000000 loops, best of 3: 184 ns per loop
1598 1598
1599 1599 In [4]: %timeit -r 4 u == None
1600 1600 1000000 loops, best of 4: 242 ns per loop
1601 1601
1602 1602 In [5]: import time
1603 1603
1604 1604 In [6]: %timeit -n1 time.sleep(2)
1605 1605 1 loops, best of 3: 2 s per loop
1606 1606
1607 1607
1608 1608 The times reported by %timeit will be slightly higher than those reported
1609 1609 by the timeit.py script when variables are accessed. This is due to the
1610 1610 fact that %timeit executes the statement in the namespace of the shell,
1611 1611 compared with timeit.py, which uses a single setup statement to import
1612 1612 function or create variables. Generally, the bias does not matter as long
1613 1613 as results from timeit.py are not mixed with those from %timeit."""
1614 1614 import timeit
1615 1615 import math
1616 1616
1617 1617 units = ["s", "ms", "\xc2\xb5s", "ns"]
1618 1618 scaling = [1, 1e3, 1e6, 1e9]
1619 1619
1620 1620 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:')
1621 1621 if stmt == "":
1622 1622 return
1623 1623 timefunc = timeit.default_timer
1624 1624 number = int(getattr(opts, "n", 0))
1625 1625 repeat = int(getattr(opts, "r", timeit.default_repeat))
1626 1626 precision = int(getattr(opts, "p", 3))
1627 1627 if hasattr(opts, "t"):
1628 1628 timefunc = time.time
1629 1629 if hasattr(opts, "c"):
1630 1630 timefunc = clock
1631 1631
1632 1632 timer = timeit.Timer(timer=timefunc)
1633 1633 # this code has tight coupling to the inner workings of timeit.Timer,
1634 1634 # but is there a better way to achieve that the code stmt has access
1635 1635 # to the shell namespace?
1636 1636
1637 1637 src = timeit.template % {'stmt': timeit.reindent(stmt, 8), 'setup': "pass"}
1638 1638 code = compile(src, "<magic-timeit>", "exec")
1639 1639 ns = {}
1640 1640 exec code in self.shell.user_ns, ns
1641 1641 timer.inner = ns["inner"]
1642 1642
1643 1643 if number == 0:
1644 1644 # determine number so that 0.2 <= total time < 2.0
1645 1645 number = 1
1646 1646 for i in range(1, 10):
1647 1647 number *= 10
1648 1648 if timer.timeit(number) >= 0.2:
1649 1649 break
1650 1650
1651 1651 best = min(timer.repeat(repeat, number)) / number
1652 1652
1653 1653 if best > 0.0:
1654 1654 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1655 1655 else:
1656 1656 order = 3
1657 1657 print "%d loops, best of %d: %.*g %s per loop" % (number, repeat, precision,
1658 1658 best * scaling[order],
1659 1659 units[order])
1660 1660
1661 1661
1662 1662
1663 1663
1664 1664 def magic_time(self,parameter_s = ''):
1665 1665 """Time execution of a Python statement or expression.
1666 1666
1667 1667 The CPU and wall clock times are printed, and the value of the
1668 1668 expression (if any) is returned. Note that under Win32, system time
1669 1669 is always reported as 0, since it can not be measured.
1670 1670
1671 1671 This function provides very basic timing functionality. In Python
1672 1672 2.3, the timeit module offers more control and sophistication, but for
1673 1673 now IPython supports Python 2.2, so we can not rely on timeit being
1674 1674 present.
1675 1675
1676 1676 Some examples:
1677 1677
1678 1678 In [1]: time 2**128
1679 1679 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1680 1680 Wall time: 0.00
1681 1681 Out[1]: 340282366920938463463374607431768211456L
1682 1682
1683 1683 In [2]: n = 1000000
1684 1684
1685 1685 In [3]: time sum(range(n))
1686 1686 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1687 1687 Wall time: 1.37
1688 1688 Out[3]: 499999500000L
1689 1689
1690 1690 In [4]: time print 'hello world'
1691 1691 hello world
1692 1692 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1693 1693 Wall time: 0.00
1694 1694 """
1695 1695
1696 1696 # fail immediately if the given expression can't be compiled
1697 1697 try:
1698 1698 mode = 'eval'
1699 1699 code = compile(parameter_s,'<timed eval>',mode)
1700 1700 except SyntaxError:
1701 1701 mode = 'exec'
1702 1702 code = compile(parameter_s,'<timed exec>',mode)
1703 1703 # skew measurement as little as possible
1704 1704 glob = self.shell.user_ns
1705 1705 clk = clock2
1706 1706 wtime = time.time
1707 1707 # time execution
1708 1708 wall_st = wtime()
1709 1709 if mode=='eval':
1710 1710 st = clk()
1711 1711 out = eval(code,glob)
1712 1712 end = clk()
1713 1713 else:
1714 1714 st = clk()
1715 1715 exec code in glob
1716 1716 end = clk()
1717 1717 out = None
1718 1718 wall_end = wtime()
1719 1719 # Compute actual times and report
1720 1720 wall_time = wall_end-wall_st
1721 1721 cpu_user = end[0]-st[0]
1722 1722 cpu_sys = end[1]-st[1]
1723 1723 cpu_tot = cpu_user+cpu_sys
1724 1724 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1725 1725 (cpu_user,cpu_sys,cpu_tot)
1726 1726 print "Wall time: %.2f" % wall_time
1727 1727 return out
1728 1728
1729 1729 def magic_macro(self,parameter_s = ''):
1730 1730 """Define a set of input lines as a macro for future re-execution.
1731 1731
1732 1732 Usage:\\
1733 1733 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1734 1734
1735 1735 Options:
1736 1736
1737 1737 -r: use 'raw' input. By default, the 'processed' history is used,
1738 1738 so that magics are loaded in their transformed version to valid
1739 1739 Python. If this option is given, the raw input as typed as the
1740 1740 command line is used instead.
1741 1741
1742 1742 This will define a global variable called `name` which is a string
1743 1743 made of joining the slices and lines you specify (n1,n2,... numbers
1744 1744 above) from your input history into a single string. This variable
1745 1745 acts like an automatic function which re-executes those lines as if
1746 1746 you had typed them. You just type 'name' at the prompt and the code
1747 1747 executes.
1748 1748
1749 1749 The notation for indicating number ranges is: n1-n2 means 'use line
1750 1750 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1751 1751 using the lines numbered 5,6 and 7.
1752 1752
1753 1753 Note: as a 'hidden' feature, you can also use traditional python slice
1754 1754 notation, where N:M means numbers N through M-1.
1755 1755
1756 1756 For example, if your history contains (%hist prints it):
1757 1757
1758 1758 44: x=1\\
1759 1759 45: y=3\\
1760 1760 46: z=x+y\\
1761 1761 47: print x\\
1762 1762 48: a=5\\
1763 1763 49: print 'x',x,'y',y\\
1764 1764
1765 1765 you can create a macro with lines 44 through 47 (included) and line 49
1766 1766 called my_macro with:
1767 1767
1768 1768 In [51]: %macro my_macro 44-47 49
1769 1769
1770 1770 Now, typing `my_macro` (without quotes) will re-execute all this code
1771 1771 in one pass.
1772 1772
1773 1773 You don't need to give the line-numbers in order, and any given line
1774 1774 number can appear multiple times. You can assemble macros with any
1775 1775 lines from your input history in any order.
1776 1776
1777 1777 The macro is a simple object which holds its value in an attribute,
1778 1778 but IPython's display system checks for macros and executes them as
1779 1779 code instead of printing them when you type their name.
1780 1780
1781 1781 You can view a macro's contents by explicitly printing it with:
1782 1782
1783 1783 'print macro_name'.
1784 1784
1785 1785 For one-off cases which DON'T contain magic function calls in them you
1786 1786 can obtain similar results by explicitly executing slices from your
1787 1787 input history with:
1788 1788
1789 1789 In [60]: exec In[44:48]+In[49]"""
1790 1790
1791 1791 opts,args = self.parse_options(parameter_s,'r',mode='list')
1792 1792 name,ranges = args[0], args[1:]
1793 1793 #print 'rng',ranges # dbg
1794 1794 lines = self.extract_input_slices(ranges,opts.has_key('r'))
1795 1795 macro = Macro(lines)
1796 1796 self.shell.user_ns.update({name:macro})
1797 1797 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1798 1798 print 'Macro contents:'
1799 1799 print macro,
1800 1800
1801 1801 def magic_save(self,parameter_s = ''):
1802 1802 """Save a set of lines to a given filename.
1803 1803
1804 1804 Usage:\\
1805 1805 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
1806 1806
1807 1807 Options:
1808 1808
1809 1809 -r: use 'raw' input. By default, the 'processed' history is used,
1810 1810 so that magics are loaded in their transformed version to valid
1811 1811 Python. If this option is given, the raw input as typed as the
1812 1812 command line is used instead.
1813 1813
1814 1814 This function uses the same syntax as %macro for line extraction, but
1815 1815 instead of creating a macro it saves the resulting string to the
1816 1816 filename you specify.
1817 1817
1818 1818 It adds a '.py' extension to the file if you don't do so yourself, and
1819 1819 it asks for confirmation before overwriting existing files."""
1820 1820
1821 1821 opts,args = self.parse_options(parameter_s,'r',mode='list')
1822 1822 fname,ranges = args[0], args[1:]
1823 1823 if not fname.endswith('.py'):
1824 1824 fname += '.py'
1825 1825 if os.path.isfile(fname):
1826 1826 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1827 1827 if ans.lower() not in ['y','yes']:
1828 1828 print 'Operation cancelled.'
1829 1829 return
1830 1830 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
1831 1831 f = file(fname,'w')
1832 1832 f.write(cmds)
1833 1833 f.close()
1834 1834 print 'The following commands were written to file `%s`:' % fname
1835 1835 print cmds
1836 1836
1837 1837 def _edit_macro(self,mname,macro):
1838 1838 """open an editor with the macro data in a file"""
1839 1839 filename = self.shell.mktempfile(macro.value)
1840 1840 self.shell.hooks.editor(filename)
1841 1841
1842 1842 # and make a new macro object, to replace the old one
1843 1843 mfile = open(filename)
1844 1844 mvalue = mfile.read()
1845 1845 mfile.close()
1846 1846 self.shell.user_ns[mname] = Macro(mvalue)
1847 1847
1848 1848 def magic_ed(self,parameter_s=''):
1849 1849 """Alias to %edit."""
1850 1850 return self.magic_edit(parameter_s)
1851 1851
1852 1852 def magic_edit(self,parameter_s='',last_call=['','']):
1853 1853 """Bring up an editor and execute the resulting code.
1854 1854
1855 1855 Usage:
1856 1856 %edit [options] [args]
1857 1857
1858 1858 %edit runs IPython's editor hook. The default version of this hook is
1859 1859 set to call the __IPYTHON__.rc.editor command. This is read from your
1860 1860 environment variable $EDITOR. If this isn't found, it will default to
1861 1861 vi under Linux/Unix and to notepad under Windows. See the end of this
1862 1862 docstring for how to change the editor hook.
1863 1863
1864 1864 You can also set the value of this editor via the command line option
1865 1865 '-editor' or in your ipythonrc file. This is useful if you wish to use
1866 1866 specifically for IPython an editor different from your typical default
1867 1867 (and for Windows users who typically don't set environment variables).
1868 1868
1869 1869 This command allows you to conveniently edit multi-line code right in
1870 1870 your IPython session.
1871 1871
1872 1872 If called without arguments, %edit opens up an empty editor with a
1873 1873 temporary file and will execute the contents of this file when you
1874 1874 close it (don't forget to save it!).
1875 1875
1876 1876
1877 1877 Options:
1878 1878
1879 1879 -p: this will call the editor with the same data as the previous time
1880 1880 it was used, regardless of how long ago (in your current session) it
1881 1881 was.
1882 1882
1883 1883 -r: use 'raw' input. This option only applies to input taken from the
1884 1884 user's history. By default, the 'processed' history is used, so that
1885 1885 magics are loaded in their transformed version to valid Python. If
1886 1886 this option is given, the raw input as typed as the command line is
1887 1887 used instead. When you exit the editor, it will be executed by
1888 1888 IPython's own processor.
1889 1889
1890 1890 -x: do not execute the edited code immediately upon exit. This is
1891 1891 mainly useful if you are editing programs which need to be called with
1892 1892 command line arguments, which you can then do using %run.
1893 1893
1894 1894
1895 1895 Arguments:
1896 1896
1897 1897 If arguments are given, the following possibilites exist:
1898 1898
1899 1899 - The arguments are numbers or pairs of colon-separated numbers (like
1900 1900 1 4:8 9). These are interpreted as lines of previous input to be
1901 1901 loaded into the editor. The syntax is the same of the %macro command.
1902 1902
1903 1903 - If the argument doesn't start with a number, it is evaluated as a
1904 1904 variable and its contents loaded into the editor. You can thus edit
1905 1905 any string which contains python code (including the result of
1906 1906 previous edits).
1907 1907
1908 1908 - If the argument is the name of an object (other than a string),
1909 1909 IPython will try to locate the file where it was defined and open the
1910 1910 editor at the point where it is defined. You can use `%edit function`
1911 1911 to load an editor exactly at the point where 'function' is defined,
1912 1912 edit it and have the file be executed automatically.
1913 1913
1914 1914 If the object is a macro (see %macro for details), this opens up your
1915 1915 specified editor with a temporary file containing the macro's data.
1916 1916 Upon exit, the macro is reloaded with the contents of the file.
1917 1917
1918 1918 Note: opening at an exact line is only supported under Unix, and some
1919 1919 editors (like kedit and gedit up to Gnome 2.8) do not understand the
1920 1920 '+NUMBER' parameter necessary for this feature. Good editors like
1921 1921 (X)Emacs, vi, jed, pico and joe all do.
1922 1922
1923 1923 - If the argument is not found as a variable, IPython will look for a
1924 1924 file with that name (adding .py if necessary) and load it into the
1925 1925 editor. It will execute its contents with execfile() when you exit,
1926 1926 loading any code in the file into your interactive namespace.
1927 1927
1928 1928 After executing your code, %edit will return as output the code you
1929 1929 typed in the editor (except when it was an existing file). This way
1930 1930 you can reload the code in further invocations of %edit as a variable,
1931 1931 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
1932 1932 the output.
1933 1933
1934 1934 Note that %edit is also available through the alias %ed.
1935 1935
1936 1936 This is an example of creating a simple function inside the editor and
1937 1937 then modifying it. First, start up the editor:
1938 1938
1939 1939 In [1]: ed\\
1940 1940 Editing... done. Executing edited code...\\
1941 1941 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
1942 1942
1943 1943 We can then call the function foo():
1944 1944
1945 1945 In [2]: foo()\\
1946 1946 foo() was defined in an editing session
1947 1947
1948 1948 Now we edit foo. IPython automatically loads the editor with the
1949 1949 (temporary) file where foo() was previously defined:
1950 1950
1951 1951 In [3]: ed foo\\
1952 1952 Editing... done. Executing edited code...
1953 1953
1954 1954 And if we call foo() again we get the modified version:
1955 1955
1956 1956 In [4]: foo()\\
1957 1957 foo() has now been changed!
1958 1958
1959 1959 Here is an example of how to edit a code snippet successive
1960 1960 times. First we call the editor:
1961 1961
1962 1962 In [8]: ed\\
1963 1963 Editing... done. Executing edited code...\\
1964 1964 hello\\
1965 1965 Out[8]: "print 'hello'\\n"
1966 1966
1967 1967 Now we call it again with the previous output (stored in _):
1968 1968
1969 1969 In [9]: ed _\\
1970 1970 Editing... done. Executing edited code...\\
1971 1971 hello world\\
1972 1972 Out[9]: "print 'hello world'\\n"
1973 1973
1974 1974 Now we call it with the output #8 (stored in _8, also as Out[8]):
1975 1975
1976 1976 In [10]: ed _8\\
1977 1977 Editing... done. Executing edited code...\\
1978 1978 hello again\\
1979 1979 Out[10]: "print 'hello again'\\n"
1980 1980
1981 1981
1982 1982 Changing the default editor hook:
1983 1983
1984 1984 If you wish to write your own editor hook, you can put it in a
1985 1985 configuration file which you load at startup time. The default hook
1986 1986 is defined in the IPython.hooks module, and you can use that as a
1987 1987 starting example for further modifications. That file also has
1988 1988 general instructions on how to set a new hook for use once you've
1989 1989 defined it."""
1990 1990
1991 1991 # FIXME: This function has become a convoluted mess. It needs a
1992 1992 # ground-up rewrite with clean, simple logic.
1993 1993
1994 1994 def make_filename(arg):
1995 1995 "Make a filename from the given args"
1996 1996 try:
1997 1997 filename = get_py_filename(arg)
1998 1998 except IOError:
1999 1999 if args.endswith('.py'):
2000 2000 filename = arg
2001 2001 else:
2002 2002 filename = None
2003 2003 return filename
2004 2004
2005 2005 # custom exceptions
2006 2006 class DataIsObject(Exception): pass
2007 2007
2008 2008 opts,args = self.parse_options(parameter_s,'prx')
2009 2009 # Set a few locals from the options for convenience:
2010 2010 opts_p = opts.has_key('p')
2011 2011 opts_r = opts.has_key('r')
2012 2012
2013 2013 # Default line number value
2014 2014 lineno = None
2015 2015 if opts_p:
2016 2016 args = '_%s' % last_call[0]
2017 2017 if not self.shell.user_ns.has_key(args):
2018 2018 args = last_call[1]
2019 2019
2020 2020 # use last_call to remember the state of the previous call, but don't
2021 2021 # let it be clobbered by successive '-p' calls.
2022 2022 try:
2023 2023 last_call[0] = self.shell.outputcache.prompt_count
2024 2024 if not opts_p:
2025 2025 last_call[1] = parameter_s
2026 2026 except:
2027 2027 pass
2028 2028
2029 2029 # by default this is done with temp files, except when the given
2030 2030 # arg is a filename
2031 2031 use_temp = 1
2032 2032
2033 2033 if re.match(r'\d',args):
2034 2034 # Mode where user specifies ranges of lines, like in %macro.
2035 2035 # This means that you can't edit files whose names begin with
2036 2036 # numbers this way. Tough.
2037 2037 ranges = args.split()
2038 2038 data = ''.join(self.extract_input_slices(ranges,opts_r))
2039 2039 elif args.endswith('.py'):
2040 2040 filename = make_filename(args)
2041 2041 data = ''
2042 2042 use_temp = 0
2043 2043 elif args:
2044 2044 try:
2045 2045 # Load the parameter given as a variable. If not a string,
2046 2046 # process it as an object instead (below)
2047 2047
2048 2048 #print '*** args',args,'type',type(args) # dbg
2049 2049 data = eval(args,self.shell.user_ns)
2050 2050 if not type(data) in StringTypes:
2051 2051 raise DataIsObject
2052 2052
2053 2053 except (NameError,SyntaxError):
2054 2054 # given argument is not a variable, try as a filename
2055 2055 filename = make_filename(args)
2056 2056 if filename is None:
2057 2057 warn("Argument given (%s) can't be found as a variable "
2058 2058 "or as a filename." % args)
2059 2059 return
2060 2060
2061 2061 data = ''
2062 2062 use_temp = 0
2063 2063 except DataIsObject:
2064 2064
2065 2065 # macros have a special edit function
2066 2066 if isinstance(data,Macro):
2067 2067 self._edit_macro(args,data)
2068 2068 return
2069 2069
2070 2070 # For objects, try to edit the file where they are defined
2071 2071 try:
2072 2072 filename = inspect.getabsfile(data)
2073 2073 datafile = 1
2074 2074 except TypeError:
2075 2075 filename = make_filename(args)
2076 2076 datafile = 1
2077 2077 warn('Could not find file where `%s` is defined.\n'
2078 2078 'Opening a file named `%s`' % (args,filename))
2079 2079 # Now, make sure we can actually read the source (if it was in
2080 2080 # a temp file it's gone by now).
2081 2081 if datafile:
2082 2082 try:
2083 2083 lineno = inspect.getsourcelines(data)[1]
2084 2084 except IOError:
2085 2085 filename = make_filename(args)
2086 2086 if filename is None:
2087 2087 warn('The file `%s` where `%s` was defined cannot '
2088 2088 'be read.' % (filename,data))
2089 2089 return
2090 2090 use_temp = 0
2091 2091 else:
2092 2092 data = ''
2093 2093
2094 2094 if use_temp:
2095 2095 filename = self.shell.mktempfile(data)
2096 2096 print 'IPython will make a temporary file named:',filename
2097 2097
2098 2098 # do actual editing here
2099 2099 print 'Editing...',
2100 2100 sys.stdout.flush()
2101 2101 self.shell.hooks.editor(filename,lineno)
2102 2102 if opts.has_key('x'): # -x prevents actual execution
2103 2103 print
2104 2104 else:
2105 2105 print 'done. Executing edited code...'
2106 2106 if opts_r:
2107 2107 self.shell.runlines(file_read(filename))
2108 2108 else:
2109 2109 self.shell.safe_execfile(filename,self.shell.user_ns)
2110 2110 if use_temp:
2111 2111 try:
2112 2112 return open(filename).read()
2113 2113 except IOError,msg:
2114 2114 if msg.filename == filename:
2115 2115 warn('File not found. Did you forget to save?')
2116 2116 return
2117 2117 else:
2118 2118 self.shell.showtraceback()
2119 2119
2120 2120 def magic_xmode(self,parameter_s = ''):
2121 2121 """Switch modes for the exception handlers.
2122 2122
2123 2123 Valid modes: Plain, Context and Verbose.
2124 2124
2125 2125 If called without arguments, acts as a toggle."""
2126 2126
2127 2127 def xmode_switch_err(name):
2128 2128 warn('Error changing %s exception modes.\n%s' %
2129 2129 (name,sys.exc_info()[1]))
2130 2130
2131 2131 shell = self.shell
2132 2132 new_mode = parameter_s.strip().capitalize()
2133 2133 try:
2134 2134 shell.InteractiveTB.set_mode(mode=new_mode)
2135 2135 print 'Exception reporting mode:',shell.InteractiveTB.mode
2136 2136 except:
2137 2137 xmode_switch_err('user')
2138 2138
2139 2139 # threaded shells use a special handler in sys.excepthook
2140 2140 if shell.isthreaded:
2141 2141 try:
2142 2142 shell.sys_excepthook.set_mode(mode=new_mode)
2143 2143 except:
2144 2144 xmode_switch_err('threaded')
2145 2145
2146 2146 def magic_colors(self,parameter_s = ''):
2147 2147 """Switch color scheme for prompts, info system and exception handlers.
2148 2148
2149 2149 Currently implemented schemes: NoColor, Linux, LightBG.
2150 2150
2151 2151 Color scheme names are not case-sensitive."""
2152 2152
2153 2153 def color_switch_err(name):
2154 2154 warn('Error changing %s color schemes.\n%s' %
2155 2155 (name,sys.exc_info()[1]))
2156 2156
2157 2157
2158 2158 new_scheme = parameter_s.strip()
2159 2159 if not new_scheme:
2160 2160 print 'You must specify a color scheme.'
2161 2161 return
2162 2162 import IPython.rlineimpl as readline
2163 2163 if not readline.have_readline:
2164 2164 msg = """\
2165 2165 Proper color support under MS Windows requires Gary Bishop's readline library.
2166 2166 You can find it at:
2167 2167 http://sourceforge.net/projects/uncpythontools
2168 2168 Gary's readline needs the ctypes module, from:
2169 2169 http://starship.python.net/crew/theller/ctypes
2170 2170
2171 2171 Defaulting color scheme to 'NoColor'"""
2172 2172 new_scheme = 'NoColor'
2173 2173 warn(msg)
2174 2174 # local shortcut
2175 2175 shell = self.shell
2176 2176
2177 2177 # Set prompt colors
2178 2178 try:
2179 2179 shell.outputcache.set_colors(new_scheme)
2180 2180 except:
2181 2181 color_switch_err('prompt')
2182 2182 else:
2183 2183 shell.rc.colors = \
2184 2184 shell.outputcache.color_table.active_scheme_name
2185 2185 # Set exception colors
2186 2186 try:
2187 2187 shell.InteractiveTB.set_colors(scheme = new_scheme)
2188 2188 shell.SyntaxTB.set_colors(scheme = new_scheme)
2189 2189 except:
2190 2190 color_switch_err('exception')
2191 2191
2192 2192 # threaded shells use a verbose traceback in sys.excepthook
2193 2193 if shell.isthreaded:
2194 2194 try:
2195 2195 shell.sys_excepthook.set_colors(scheme=new_scheme)
2196 2196 except:
2197 2197 color_switch_err('system exception handler')
2198 2198
2199 2199 # Set info (for 'object?') colors
2200 2200 if shell.rc.color_info:
2201 2201 try:
2202 2202 shell.inspector.set_active_scheme(new_scheme)
2203 2203 except:
2204 2204 color_switch_err('object inspector')
2205 2205 else:
2206 2206 shell.inspector.set_active_scheme('NoColor')
2207 2207
2208 2208 def magic_color_info(self,parameter_s = ''):
2209 2209 """Toggle color_info.
2210 2210
2211 2211 The color_info configuration parameter controls whether colors are
2212 2212 used for displaying object details (by things like %psource, %pfile or
2213 2213 the '?' system). This function toggles this value with each call.
2214 2214
2215 2215 Note that unless you have a fairly recent pager (less works better
2216 2216 than more) in your system, using colored object information displays
2217 2217 will not work properly. Test it and see."""
2218 2218
2219 2219 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2220 2220 self.magic_colors(self.shell.rc.colors)
2221 2221 print 'Object introspection functions have now coloring:',
2222 2222 print ['OFF','ON'][self.shell.rc.color_info]
2223 2223
2224 2224 def magic_Pprint(self, parameter_s=''):
2225 2225 """Toggle pretty printing on/off."""
2226 2226
2227 2227 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2228 2228 print 'Pretty printing has been turned', \
2229 2229 ['OFF','ON'][self.shell.rc.pprint]
2230 2230
2231 2231 def magic_exit(self, parameter_s=''):
2232 2232 """Exit IPython, confirming if configured to do so.
2233 2233
2234 2234 You can configure whether IPython asks for confirmation upon exit by
2235 2235 setting the confirm_exit flag in the ipythonrc file."""
2236 2236
2237 2237 self.shell.exit()
2238 2238
2239 2239 def magic_quit(self, parameter_s=''):
2240 2240 """Exit IPython, confirming if configured to do so (like %exit)"""
2241 2241
2242 2242 self.shell.exit()
2243 2243
2244 2244 def magic_Exit(self, parameter_s=''):
2245 2245 """Exit IPython without confirmation."""
2246 2246
2247 2247 self.shell.exit_now = True
2248 2248
2249 2249 def magic_Quit(self, parameter_s=''):
2250 2250 """Exit IPython without confirmation (like %Exit)."""
2251 2251
2252 2252 self.shell.exit_now = True
2253 2253
2254 2254 #......................................................................
2255 2255 # Functions to implement unix shell-type things
2256 2256
2257 2257 def magic_alias(self, parameter_s = ''):
2258 2258 """Define an alias for a system command.
2259 2259
2260 2260 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2261 2261
2262 2262 Then, typing 'alias_name params' will execute the system command 'cmd
2263 2263 params' (from your underlying operating system).
2264 2264
2265 2265 Aliases have lower precedence than magic functions and Python normal
2266 2266 variables, so if 'foo' is both a Python variable and an alias, the
2267 2267 alias can not be executed until 'del foo' removes the Python variable.
2268 2268
2269 2269 You can use the %l specifier in an alias definition to represent the
2270 2270 whole line when the alias is called. For example:
2271 2271
2272 2272 In [2]: alias all echo "Input in brackets: <%l>"\\
2273 2273 In [3]: all hello world\\
2274 2274 Input in brackets: <hello world>
2275 2275
2276 2276 You can also define aliases with parameters using %s specifiers (one
2277 2277 per parameter):
2278 2278
2279 2279 In [1]: alias parts echo first %s second %s\\
2280 2280 In [2]: %parts A B\\
2281 2281 first A second B\\
2282 2282 In [3]: %parts A\\
2283 2283 Incorrect number of arguments: 2 expected.\\
2284 2284 parts is an alias to: 'echo first %s second %s'
2285 2285
2286 2286 Note that %l and %s are mutually exclusive. You can only use one or
2287 2287 the other in your aliases.
2288 2288
2289 2289 Aliases expand Python variables just like system calls using ! or !!
2290 2290 do: all expressions prefixed with '$' get expanded. For details of
2291 2291 the semantic rules, see PEP-215:
2292 2292 http://www.python.org/peps/pep-0215.html. This is the library used by
2293 2293 IPython for variable expansion. If you want to access a true shell
2294 2294 variable, an extra $ is necessary to prevent its expansion by IPython:
2295 2295
2296 2296 In [6]: alias show echo\\
2297 2297 In [7]: PATH='A Python string'\\
2298 2298 In [8]: show $PATH\\
2299 2299 A Python string\\
2300 2300 In [9]: show $$PATH\\
2301 2301 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2302 2302
2303 2303 You can use the alias facility to acess all of $PATH. See the %rehash
2304 2304 and %rehashx functions, which automatically create aliases for the
2305 2305 contents of your $PATH.
2306 2306
2307 2307 If called with no parameters, %alias prints the current alias table."""
2308 2308
2309 2309 par = parameter_s.strip()
2310 2310 if not par:
2311 2311 if self.shell.rc.automagic:
2312 2312 prechar = ''
2313 2313 else:
2314 2314 prechar = self.shell.ESC_MAGIC
2315 2315 #print 'Alias\t\tSystem Command\n'+'-'*30
2316 2316 atab = self.shell.alias_table
2317 2317 aliases = atab.keys()
2318 2318 aliases.sort()
2319 2319 res = []
2320 2320 for alias in aliases:
2321 2321 res.append((alias, atab[alias][1]))
2322 2322 print "Total number of aliases:",len(aliases)
2323 2323 return res
2324 2324 try:
2325 2325 alias,cmd = par.split(None,1)
2326 2326 except:
2327 2327 print OInspect.getdoc(self.magic_alias)
2328 2328 else:
2329 2329 nargs = cmd.count('%s')
2330 2330 if nargs>0 and cmd.find('%l')>=0:
2331 2331 error('The %s and %l specifiers are mutually exclusive '
2332 2332 'in alias definitions.')
2333 2333 else: # all looks OK
2334 2334 self.shell.alias_table[alias] = (nargs,cmd)
2335 2335 self.shell.alias_table_validate(verbose=0)
2336 2336 # end magic_alias
2337 2337
2338 2338 def magic_unalias(self, parameter_s = ''):
2339 2339 """Remove an alias"""
2340 2340
2341 2341 aname = parameter_s.strip()
2342 2342 if aname in self.shell.alias_table:
2343 2343 del self.shell.alias_table[aname]
2344 2344
2345 2345 def magic_rehash(self, parameter_s = ''):
2346 2346 """Update the alias table with all entries in $PATH.
2347 2347
2348 2348 This version does no checks on execute permissions or whether the
2349 2349 contents of $PATH are truly files (instead of directories or something
2350 2350 else). For such a safer (but slower) version, use %rehashx."""
2351 2351
2352 2352 # This function (and rehashx) manipulate the alias_table directly
2353 2353 # rather than calling magic_alias, for speed reasons. A rehash on a
2354 2354 # typical Linux box involves several thousand entries, so efficiency
2355 2355 # here is a top concern.
2356 2356
2357 2357 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2358 2358 alias_table = self.shell.alias_table
2359 2359 for pdir in path:
2360 2360 for ff in os.listdir(pdir):
2361 2361 # each entry in the alias table must be (N,name), where
2362 2362 # N is the number of positional arguments of the alias.
2363 2363 alias_table[ff] = (0,ff)
2364 2364 # Make sure the alias table doesn't contain keywords or builtins
2365 2365 self.shell.alias_table_validate()
2366 2366 # Call again init_auto_alias() so we get 'rm -i' and other modified
2367 2367 # aliases since %rehash will probably clobber them
2368 2368 self.shell.init_auto_alias()
2369 2369
2370 2370 def magic_rehashx(self, parameter_s = ''):
2371 2371 """Update the alias table with all executable files in $PATH.
2372 2372
2373 2373 This version explicitly checks that every entry in $PATH is a file
2374 2374 with execute access (os.X_OK), so it is much slower than %rehash.
2375 2375
2376 2376 Under Windows, it checks executability as a match agains a
2377 2377 '|'-separated string of extensions, stored in the IPython config
2378 2378 variable win_exec_ext. This defaults to 'exe|com|bat'. """
2379 2379
2380 2380 path = [os.path.abspath(os.path.expanduser(p)) for p in
2381 2381 os.environ['PATH'].split(os.pathsep)]
2382 2382 path = filter(os.path.isdir,path)
2383 2383
2384 2384 alias_table = self.shell.alias_table
2385 2385 syscmdlist = []
2386 2386 if os.name == 'posix':
2387 2387 isexec = lambda fname:os.path.isfile(fname) and \
2388 2388 os.access(fname,os.X_OK)
2389 2389 else:
2390 2390
2391 2391 try:
2392 2392 winext = os.environ['pathext'].replace(';','|').replace('.','')
2393 2393 except KeyError:
2394 2394 winext = 'exe|com|bat'
2395 2395
2396 2396 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2397 2397 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2398 2398 savedir = os.getcwd()
2399 2399 try:
2400 2400 # write the whole loop for posix/Windows so we don't have an if in
2401 2401 # the innermost part
2402 2402 if os.name == 'posix':
2403 2403 for pdir in path:
2404 2404 os.chdir(pdir)
2405 2405 for ff in os.listdir(pdir):
2406 2406 if isexec(ff):
2407 2407 # each entry in the alias table must be (N,name),
2408 2408 # where N is the number of positional arguments of the
2409 2409 # alias.
2410 2410 alias_table[ff] = (0,ff)
2411 2411 syscmdlist.append(ff)
2412 2412 else:
2413 2413 for pdir in path:
2414 2414 os.chdir(pdir)
2415 2415 for ff in os.listdir(pdir):
2416 2416 if isexec(ff):
2417 2417 alias_table[execre.sub(r'\1',ff)] = (0,ff)
2418 2418 syscmdlist.append(ff)
2419 2419 # Make sure the alias table doesn't contain keywords or builtins
2420 2420 self.shell.alias_table_validate()
2421 2421 # Call again init_auto_alias() so we get 'rm -i' and other
2422 2422 # modified aliases since %rehashx will probably clobber them
2423 2423 self.shell.init_auto_alias()
2424 2424 db = self.getapi().getdb()
2425 2425 db['syscmdlist'] = syscmdlist
2426 2426 finally:
2427 2427 os.chdir(savedir)
2428 2428
2429 2429 def magic_pwd(self, parameter_s = ''):
2430 2430 """Return the current working directory path."""
2431 2431 return os.getcwd()
2432 2432
2433 2433 def magic_cd(self, parameter_s=''):
2434 2434 """Change the current working directory.
2435 2435
2436 2436 This command automatically maintains an internal list of directories
2437 2437 you visit during your IPython session, in the variable _dh. The
2438 2438 command %dhist shows this history nicely formatted.
2439 2439
2440 2440 Usage:
2441 2441
2442 2442 cd 'dir': changes to directory 'dir'.
2443 2443
2444 2444 cd -: changes to the last visited directory.
2445 2445
2446 2446 cd -<n>: changes to the n-th directory in the directory history.
2447 2447
2448 2448 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2449 2449 (note: cd <bookmark_name> is enough if there is no
2450 2450 directory <bookmark_name>, but a bookmark with the name exists.)
2451 2451
2452 2452 Options:
2453 2453
2454 2454 -q: quiet. Do not print the working directory after the cd command is
2455 2455 executed. By default IPython's cd command does print this directory,
2456 2456 since the default prompts do not display path information.
2457 2457
2458 2458 Note that !cd doesn't work for this purpose because the shell where
2459 2459 !command runs is immediately discarded after executing 'command'."""
2460 2460
2461 2461 parameter_s = parameter_s.strip()
2462 2462 #bkms = self.shell.persist.get("bookmarks",{})
2463 2463
2464 2464 numcd = re.match(r'(-)(\d+)$',parameter_s)
2465 2465 # jump in directory history by number
2466 2466 if numcd:
2467 2467 nn = int(numcd.group(2))
2468 2468 try:
2469 2469 ps = self.shell.user_ns['_dh'][nn]
2470 2470 except IndexError:
2471 2471 print 'The requested directory does not exist in history.'
2472 2472 return
2473 2473 else:
2474 2474 opts = {}
2475 2475 else:
2476 2476 #turn all non-space-escaping backslashes to slashes,
2477 2477 # for c:\windows\directory\names\
2478 2478 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2479 2479 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2480 2480 # jump to previous
2481 2481 if ps == '-':
2482 2482 try:
2483 2483 ps = self.shell.user_ns['_dh'][-2]
2484 2484 except IndexError:
2485 2485 print 'No previous directory to change to.'
2486 2486 return
2487 2487 # jump to bookmark if needed
2488 2488 else:
2489 2489 if not os.path.isdir(ps) or opts.has_key('b'):
2490 2490 bkms = self.db.get('bookmarks', {})
2491 2491
2492 2492 if bkms.has_key(ps):
2493 2493 target = bkms[ps]
2494 2494 print '(bookmark:%s) -> %s' % (ps,target)
2495 2495 ps = target
2496 2496 else:
2497 2497 if opts.has_key('b'):
2498 2498 error("Bookmark '%s' not found. "
2499 2499 "Use '%%bookmark -l' to see your bookmarks." % ps)
2500 2500 return
2501 2501
2502 2502 # at this point ps should point to the target dir
2503 2503 if ps:
2504 2504 try:
2505 2505 os.chdir(os.path.expanduser(ps))
2506 2506 ttitle = ("IPy:" + (
2507 2507 os.getcwd() == '/' and '/' or os.path.basename(os.getcwd())))
2508 2508 platutils.set_term_title(ttitle)
2509 2509 except OSError:
2510 2510 print sys.exc_info()[1]
2511 2511 else:
2512 2512 self.shell.user_ns['_dh'].append(os.getcwd())
2513 2513 else:
2514 2514 os.chdir(self.shell.home_dir)
2515 2515 platutils.set_term_title("IPy:~")
2516 2516 self.shell.user_ns['_dh'].append(os.getcwd())
2517 2517 if not 'q' in opts:
2518 2518 print self.shell.user_ns['_dh'][-1]
2519 2519
2520 2520 def magic_dhist(self, parameter_s=''):
2521 2521 """Print your history of visited directories.
2522 2522
2523 2523 %dhist -> print full history\\
2524 2524 %dhist n -> print last n entries only\\
2525 2525 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2526 2526
2527 2527 This history is automatically maintained by the %cd command, and
2528 2528 always available as the global list variable _dh. You can use %cd -<n>
2529 2529 to go to directory number <n>."""
2530 2530
2531 2531 dh = self.shell.user_ns['_dh']
2532 2532 if parameter_s:
2533 2533 try:
2534 2534 args = map(int,parameter_s.split())
2535 2535 except:
2536 2536 self.arg_err(Magic.magic_dhist)
2537 2537 return
2538 2538 if len(args) == 1:
2539 2539 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2540 2540 elif len(args) == 2:
2541 2541 ini,fin = args
2542 2542 else:
2543 2543 self.arg_err(Magic.magic_dhist)
2544 2544 return
2545 2545 else:
2546 2546 ini,fin = 0,len(dh)
2547 2547 nlprint(dh,
2548 2548 header = 'Directory history (kept in _dh)',
2549 2549 start=ini,stop=fin)
2550 2550
2551 2551 def magic_env(self, parameter_s=''):
2552 2552 """List environment variables."""
2553 2553
2554 2554 return os.environ.data
2555 2555
2556 2556 def magic_pushd(self, parameter_s=''):
2557 2557 """Place the current dir on stack and change directory.
2558 2558
2559 2559 Usage:\\
2560 2560 %pushd ['dirname']
2561 2561
2562 2562 %pushd with no arguments does a %pushd to your home directory.
2563 2563 """
2564 2564 if parameter_s == '': parameter_s = '~'
2565 2565 dir_s = self.shell.dir_stack
2566 2566 if len(dir_s)>0 and os.path.expanduser(parameter_s) != \
2567 2567 os.path.expanduser(self.shell.dir_stack[0]):
2568 2568 try:
2569 2569 self.magic_cd(parameter_s)
2570 2570 dir_s.insert(0,os.getcwd().replace(self.home_dir,'~'))
2571 2571 self.magic_dirs()
2572 2572 except:
2573 2573 print 'Invalid directory'
2574 2574 else:
2575 2575 print 'You are already there!'
2576 2576
2577 2577 def magic_popd(self, parameter_s=''):
2578 2578 """Change to directory popped off the top of the stack.
2579 2579 """
2580 2580 if len (self.shell.dir_stack) > 1:
2581 2581 self.shell.dir_stack.pop(0)
2582 2582 self.magic_cd(self.shell.dir_stack[0])
2583 2583 print self.shell.dir_stack[0]
2584 2584 else:
2585 2585 print "You can't remove the starting directory from the stack:",\
2586 2586 self.shell.dir_stack
2587 2587
2588 2588 def magic_dirs(self, parameter_s=''):
2589 2589 """Return the current directory stack."""
2590 2590
2591 2591 return self.shell.dir_stack[:]
2592 2592
2593 2593 def magic_sc(self, parameter_s=''):
2594 2594 """Shell capture - execute a shell command and capture its output.
2595 2595
2596 2596 DEPRECATED. Suboptimal, retained for backwards compatibility.
2597 2597
2598 2598 You should use the form 'var = !command' instead. Example:
2599 2599
2600 2600 "%sc -l myfiles = ls ~" should now be written as
2601 2601
2602 2602 "myfiles = !ls ~"
2603 2603
2604 2604 myfiles.s, myfiles.l and myfiles.n still apply as documented
2605 2605 below.
2606 2606
2607 2607 --
2608 2608 %sc [options] varname=command
2609 2609
2610 2610 IPython will run the given command using commands.getoutput(), and
2611 2611 will then update the user's interactive namespace with a variable
2612 2612 called varname, containing the value of the call. Your command can
2613 2613 contain shell wildcards, pipes, etc.
2614 2614
2615 2615 The '=' sign in the syntax is mandatory, and the variable name you
2616 2616 supply must follow Python's standard conventions for valid names.
2617 2617
2618 2618 (A special format without variable name exists for internal use)
2619 2619
2620 2620 Options:
2621 2621
2622 2622 -l: list output. Split the output on newlines into a list before
2623 2623 assigning it to the given variable. By default the output is stored
2624 2624 as a single string.
2625 2625
2626 2626 -v: verbose. Print the contents of the variable.
2627 2627
2628 2628 In most cases you should not need to split as a list, because the
2629 2629 returned value is a special type of string which can automatically
2630 2630 provide its contents either as a list (split on newlines) or as a
2631 2631 space-separated string. These are convenient, respectively, either
2632 2632 for sequential processing or to be passed to a shell command.
2633 2633
2634 2634 For example:
2635 2635
2636 2636 # Capture into variable a
2637 2637 In [9]: sc a=ls *py
2638 2638
2639 2639 # a is a string with embedded newlines
2640 2640 In [10]: a
2641 2641 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2642 2642
2643 2643 # which can be seen as a list:
2644 2644 In [11]: a.l
2645 2645 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2646 2646
2647 2647 # or as a whitespace-separated string:
2648 2648 In [12]: a.s
2649 2649 Out[12]: 'setup.py win32_manual_post_install.py'
2650 2650
2651 2651 # a.s is useful to pass as a single command line:
2652 2652 In [13]: !wc -l $a.s
2653 2653 146 setup.py
2654 2654 130 win32_manual_post_install.py
2655 2655 276 total
2656 2656
2657 2657 # while the list form is useful to loop over:
2658 2658 In [14]: for f in a.l:
2659 2659 ....: !wc -l $f
2660 2660 ....:
2661 2661 146 setup.py
2662 2662 130 win32_manual_post_install.py
2663 2663
2664 2664 Similiarly, the lists returned by the -l option are also special, in
2665 2665 the sense that you can equally invoke the .s attribute on them to
2666 2666 automatically get a whitespace-separated string from their contents:
2667 2667
2668 2668 In [1]: sc -l b=ls *py
2669 2669
2670 2670 In [2]: b
2671 2671 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2672 2672
2673 2673 In [3]: b.s
2674 2674 Out[3]: 'setup.py win32_manual_post_install.py'
2675 2675
2676 2676 In summary, both the lists and strings used for ouptut capture have
2677 2677 the following special attributes:
2678 2678
2679 2679 .l (or .list) : value as list.
2680 2680 .n (or .nlstr): value as newline-separated string.
2681 2681 .s (or .spstr): value as space-separated string.
2682 2682 """
2683 2683
2684 2684 opts,args = self.parse_options(parameter_s,'lv')
2685 2685 # Try to get a variable name and command to run
2686 2686 try:
2687 2687 # the variable name must be obtained from the parse_options
2688 2688 # output, which uses shlex.split to strip options out.
2689 2689 var,_ = args.split('=',1)
2690 2690 var = var.strip()
2691 2691 # But the the command has to be extracted from the original input
2692 2692 # parameter_s, not on what parse_options returns, to avoid the
2693 2693 # quote stripping which shlex.split performs on it.
2694 2694 _,cmd = parameter_s.split('=',1)
2695 2695 except ValueError:
2696 2696 var,cmd = '',''
2697 2697 # If all looks ok, proceed
2698 2698 out,err = self.shell.getoutputerror(cmd)
2699 2699 if err:
2700 2700 print >> Term.cerr,err
2701 2701 if opts.has_key('l'):
2702 2702 out = SList(out.split('\n'))
2703 2703 else:
2704 2704 out = LSString(out)
2705 2705 if opts.has_key('v'):
2706 2706 print '%s ==\n%s' % (var,pformat(out))
2707 2707 if var:
2708 2708 self.shell.user_ns.update({var:out})
2709 2709 else:
2710 2710 return out
2711 2711
2712 2712 def magic_sx(self, parameter_s=''):
2713 2713 """Shell execute - run a shell command and capture its output.
2714 2714
2715 2715 %sx command
2716 2716
2717 2717 IPython will run the given command using commands.getoutput(), and
2718 2718 return the result formatted as a list (split on '\\n'). Since the
2719 2719 output is _returned_, it will be stored in ipython's regular output
2720 2720 cache Out[N] and in the '_N' automatic variables.
2721 2721
2722 2722 Notes:
2723 2723
2724 2724 1) If an input line begins with '!!', then %sx is automatically
2725 2725 invoked. That is, while:
2726 2726 !ls
2727 2727 causes ipython to simply issue system('ls'), typing
2728 2728 !!ls
2729 2729 is a shorthand equivalent to:
2730 2730 %sx ls
2731 2731
2732 2732 2) %sx differs from %sc in that %sx automatically splits into a list,
2733 2733 like '%sc -l'. The reason for this is to make it as easy as possible
2734 2734 to process line-oriented shell output via further python commands.
2735 2735 %sc is meant to provide much finer control, but requires more
2736 2736 typing.
2737 2737
2738 2738 3) Just like %sc -l, this is a list with special attributes:
2739 2739
2740 2740 .l (or .list) : value as list.
2741 2741 .n (or .nlstr): value as newline-separated string.
2742 2742 .s (or .spstr): value as whitespace-separated string.
2743 2743
2744 2744 This is very useful when trying to use such lists as arguments to
2745 2745 system commands."""
2746 2746
2747 2747 if parameter_s:
2748 2748 out,err = self.shell.getoutputerror(parameter_s)
2749 2749 if err:
2750 2750 print >> Term.cerr,err
2751 2751 return SList(out.split('\n'))
2752 2752
2753 2753 def magic_bg(self, parameter_s=''):
2754 2754 """Run a job in the background, in a separate thread.
2755 2755
2756 2756 For example,
2757 2757
2758 2758 %bg myfunc(x,y,z=1)
2759 2759
2760 2760 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2761 2761 execution starts, a message will be printed indicating the job
2762 2762 number. If your job number is 5, you can use
2763 2763
2764 2764 myvar = jobs.result(5) or myvar = jobs[5].result
2765 2765
2766 2766 to assign this result to variable 'myvar'.
2767 2767
2768 2768 IPython has a job manager, accessible via the 'jobs' object. You can
2769 2769 type jobs? to get more information about it, and use jobs.<TAB> to see
2770 2770 its attributes. All attributes not starting with an underscore are
2771 2771 meant for public use.
2772 2772
2773 2773 In particular, look at the jobs.new() method, which is used to create
2774 2774 new jobs. This magic %bg function is just a convenience wrapper
2775 2775 around jobs.new(), for expression-based jobs. If you want to create a
2776 2776 new job with an explicit function object and arguments, you must call
2777 2777 jobs.new() directly.
2778 2778
2779 2779 The jobs.new docstring also describes in detail several important
2780 2780 caveats associated with a thread-based model for background job
2781 2781 execution. Type jobs.new? for details.
2782 2782
2783 2783 You can check the status of all jobs with jobs.status().
2784 2784
2785 2785 The jobs variable is set by IPython into the Python builtin namespace.
2786 2786 If you ever declare a variable named 'jobs', you will shadow this
2787 2787 name. You can either delete your global jobs variable to regain
2788 2788 access to the job manager, or make a new name and assign it manually
2789 2789 to the manager (stored in IPython's namespace). For example, to
2790 2790 assign the job manager to the Jobs name, use:
2791 2791
2792 2792 Jobs = __builtins__.jobs"""
2793 2793
2794 2794 self.shell.jobs.new(parameter_s,self.shell.user_ns)
2795 2795
2796 2796
2797 2797 def magic_bookmark(self, parameter_s=''):
2798 2798 """Manage IPython's bookmark system.
2799 2799
2800 2800 %bookmark <name> - set bookmark to current dir
2801 2801 %bookmark <name> <dir> - set bookmark to <dir>
2802 2802 %bookmark -l - list all bookmarks
2803 2803 %bookmark -d <name> - remove bookmark
2804 2804 %bookmark -r - remove all bookmarks
2805 2805
2806 2806 You can later on access a bookmarked folder with:
2807 2807 %cd -b <name>
2808 2808 or simply '%cd <name>' if there is no directory called <name> AND
2809 2809 there is such a bookmark defined.
2810 2810
2811 2811 Your bookmarks persist through IPython sessions, but they are
2812 2812 associated with each profile."""
2813 2813
2814 2814 opts,args = self.parse_options(parameter_s,'drl',mode='list')
2815 2815 if len(args) > 2:
2816 2816 error('You can only give at most two arguments')
2817 2817 return
2818 2818
2819 2819 bkms = self.db.get('bookmarks',{})
2820 2820
2821 2821 if opts.has_key('d'):
2822 2822 try:
2823 2823 todel = args[0]
2824 2824 except IndexError:
2825 2825 error('You must provide a bookmark to delete')
2826 2826 else:
2827 2827 try:
2828 2828 del bkms[todel]
2829 2829 except:
2830 2830 error("Can't delete bookmark '%s'" % todel)
2831 2831 elif opts.has_key('r'):
2832 2832 bkms = {}
2833 2833 elif opts.has_key('l'):
2834 2834 bks = bkms.keys()
2835 2835 bks.sort()
2836 2836 if bks:
2837 2837 size = max(map(len,bks))
2838 2838 else:
2839 2839 size = 0
2840 2840 fmt = '%-'+str(size)+'s -> %s'
2841 2841 print 'Current bookmarks:'
2842 2842 for bk in bks:
2843 2843 print fmt % (bk,bkms[bk])
2844 2844 else:
2845 2845 if not args:
2846 2846 error("You must specify the bookmark name")
2847 2847 elif len(args)==1:
2848 2848 bkms[args[0]] = os.getcwd()
2849 2849 elif len(args)==2:
2850 2850 bkms[args[0]] = args[1]
2851 2851 self.db['bookmarks'] = bkms
2852 2852
2853 2853 def magic_pycat(self, parameter_s=''):
2854 2854 """Show a syntax-highlighted file through a pager.
2855 2855
2856 2856 This magic is similar to the cat utility, but it will assume the file
2857 2857 to be Python source and will show it with syntax highlighting. """
2858 2858
2859 2859 try:
2860 2860 filename = get_py_filename(parameter_s)
2861 2861 cont = file_read(filename)
2862 2862 except IOError:
2863 2863 try:
2864 2864 cont = eval(parameter_s,self.user_ns)
2865 2865 except NameError:
2866 2866 cont = None
2867 2867 if cont is None:
2868 2868 print "Error: no such file or variable"
2869 2869 return
2870 2870
2871 2871 page(self.shell.pycolorize(cont),
2872 2872 screen_lines=self.shell.rc.screen_length)
2873 2873
2874 2874 def magic_cpaste(self, parameter_s=''):
2875 2875 """Allows you to paste & execute a pre-formatted code block from clipboard
2876 2876
2877 2877 You must terminate the block with '--' (two minus-signs) alone on the
2878 2878 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
2879 2879 is the new sentinel for this operation)
2880 2880
2881 2881 The block is dedented prior to execution to enable execution of
2882 2882 method definitions. The executed block is also assigned to variable
2883 2883 named 'pasted_block' for later editing with '%edit pasted_block'.
2884 2884
2885 2885 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
2886 2886 This assigns the pasted block to variable 'foo' as string, without
2887 2887 dedenting or executing it.
2888 2888
2889 2889 Do not be alarmed by garbled output on Windows (it's a readline bug).
2890 2890 Just press enter and type -- (and press enter again) and the block
2891 2891 will be what was just pasted.
2892 2892
2893 2893 IPython statements (magics, shell escapes) are not supported (yet).
2894 2894 """
2895 2895 opts,args = self.parse_options(parameter_s,'s:',mode='string')
2896 2896 par = args.strip()
2897 2897 sentinel = opts.get('s','--')
2898 2898
2899 2899 from IPython import iplib
2900 2900 lines = []
2901 2901 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
2902 2902 while 1:
2903 2903 l = iplib.raw_input_original(':')
2904 2904 if l ==sentinel:
2905 2905 break
2906 2906 lines.append(l)
2907 2907 block = "\n".join(lines) + '\n'
2908 2908 #print "block:\n",block
2909 2909 if not par:
2910 2910 b = textwrap.dedent(block)
2911 2911 exec b in self.user_ns
2912 2912 self.user_ns['pasted_block'] = b
2913 2913 else:
2914 2914 self.user_ns[par] = block
2915 2915 print "Block assigned to '%s'" % par
2916 2916
2917 2917 def magic_quickref(self,arg):
2918 2918 """ Show a quick reference sheet """
2919 2919 import IPython.usage
2920 2920 qr = IPython.usage.quick_reference + self.magic_magic('-brief')
2921 2921
2922 2922 page(qr)
2923 2923
2924 2924 def magic_upgrade(self,arg):
2925 2925 """ Upgrade your IPython installation
2926 2926
2927 2927 This will copy the config files that don't yet exist in your
2928 2928 ipython dir from the system config dir. Use this after upgrading
2929 2929 IPython if you don't wish to delete your .ipython dir.
2930 2930
2931 2931 Call with -nolegacy to get rid of ipythonrc* files (recommended for
2932 2932 new users)
2933 2933
2934 2934 """
2935 2935 ip = self.getapi()
2936 2936 ipinstallation = path(IPython.__file__).dirname()
2937 upgrade_script = ipinstallation / 'upgrade_dir.py'
2937 upgrade_script = sys.executable + " " + ipinstallation / 'upgrade_dir.py'
2938 2938 src_config = ipinstallation / 'UserConfig'
2939 2939 userdir = path(ip.options().ipythondir)
2940 2940 cmd = upgrade_script + " " + src_config + " " + userdir
2941 2941 print ">",cmd
2942 2942 shell(cmd)
2943 2943 if arg == '-nolegacy':
2944 2944 legacy = userdir.files('ipythonrc*')
2945 2945 print "Nuking legacy files:",legacy
2946 2946
2947 2947 [p.remove() for p in legacy]
2948 2948 suffix = (sys.platform == 'win32' and '.ini' or '')
2949 2949 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
2950 2950
2951 2951
2952 2952 # end Magic
@@ -1,87 +1,88 b''
1 #!/usr/bin/env python
1 2 """ A script/util to upgrade all files in a directory
2 3
3 4 This is rather conservative in its approach, only copying/overwriting
4 5 new and unedited files.
5 6
6 7 To be used by "upgrade" feature.
7 8 """
8 9 from path import path
9 10 import md5,pickle
10 11
11 12 def showdiff(old,new):
12 13 import difflib
13 14 d = difflib.Differ()
14 15 lines = d.compare(old.lines(),new.lines())
15 16 realdiff = False
16 17 for l in lines:
17 18 print l,
18 19 if not realdiff and not l[0].isspace():
19 20 realdiff = True
20 21 return realdiff
21 22
22 23 def upgrade_dir(srcdir, tgtdir):
23 24 """ Copy over all files in srcdir to tgtdir w/ native line endings
24 25
25 26 Creates .upgrade_report in tgtdir that stores md5sums of all files
26 27 to notice changed files b/w upgrades.
27 28 """
28 29
29 30 def pr(s):
30 31 print s
31 32
32 33 def ignorable(p):
33 34 if p.lower().startswith('.svn') or p.startswith('ipythonrc'):
34 35 return True
35 36 return False
36 37
37 38
38 39 modded = []
39 40 files = [path(srcdir).relpathto(p) for p in path(srcdir).walkfiles()]
40 41 #print files
41 42 rep = tgtdir / '.upgrade_report'
42 43 try:
43 44 rpt = pickle.load(rep.open())
44 45 except:
45 46 rpt = {}
46 47
47 48 for f in files:
48 49 if ignorable(f):
49 50 continue
50 51 src = srcdir / f
51 52 tgt = tgtdir / f
52 53 if not tgt.isfile():
53 54 pr("Creating %s" % str(tgt))
54 55
55 56 tgt.write_text(src.text())
56 57 rpt[str(tgt)] = md5.new(tgt.text()).hexdigest()
57 58 else:
58 59 cont = tgt.text()
59 60 sum = rpt.get(str(tgt), None)
60 61 #print sum
61 62 if sum and md5.new(cont).hexdigest() == sum:
62 63 pr("Unedited, installing new %s" % tgt)
63 64 rpt[str(tgt)] = md5.new(tgt.text()).hexdigest()
64 65 else:
65 66 pr(' == Modified, skipping %s, diffs below == ' % tgt)
66 67 #rpt[str(tgt)] = md5.new(tgt.bytes()).hexdigest()
67 68 real = showdiff(tgt,src)
68 69 pr('') # empty line
69 70 if not real:
70 71 pr("(Ok, it wasn't that different at all, upgrading checksum)")
71 72 rpt[str(tgt)] = md5.new(tgt.text()).hexdigest()
72 73 else:
73 74 modded.append(tgt)
74 75
75 76 #print rpt
76 77 pickle.dump(rpt, rep.open('w'))
77 78 if modded:
78 79 print "\n\nDelete the following files manually if you need a full upgrade:"
79 80 for m in modded:
80 81 print m
81 82
82 83
83 84 import sys
84 85 if __name__ == "__main__":
85 86 upgrade_dir(path(sys.argv[1]), path(sys.argv[2]))
86 87
87 No newline at end of file
88
General Comments 0
You need to be logged in to leave comments. Login now