##// END OF EJS Templates
PyColorize.py => utils/PyColorize.py and updated imports.
Brian Granger -
Show More
@@ -1,524 +1,524 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 Pdb debugger class.
4 4
5 5 Modified from the standard pdb.Pdb class to avoid including readline, so that
6 6 the command line completion of other programs which include this isn't
7 7 damaged.
8 8
9 9 In the future, this class will be expanded with improvements over the standard
10 10 pdb.
11 11
12 12 The code in this file is mainly lifted out of cmd.py in Python 2.2, with minor
13 13 changes. Licensing should therefore be under the standard Python terms. For
14 14 details on the PSF (Python Software Foundation) standard license, see:
15 15
16 16 http://www.python.org/2.2.3/license.html"""
17 17
18 18 #*****************************************************************************
19 19 #
20 20 # This file is licensed under the PSF license.
21 21 #
22 22 # Copyright (C) 2001 Python Software Foundation, www.python.org
23 23 # Copyright (C) 2005-2006 Fernando Perez. <fperez@colorado.edu>
24 24 #
25 25 #
26 26 #*****************************************************************************
27 27
28 28 import bdb
29 29 import cmd
30 30 import linecache
31 31 import os
32 32 import sys
33 33
34 from IPython import PyColorize
34 from IPython.utils import PyColorize
35 35 from IPython.core import ipapi
36 36 from IPython.utils import coloransi
37 37 from IPython.utils.genutils import Term
38 38 from IPython.core.excolors import exception_colors
39 39
40 40 # See if we can use pydb.
41 41 has_pydb = False
42 42 prompt = 'ipdb> '
43 43 #We have to check this directly from sys.argv, config struct not yet available
44 44 if '-pydb' in sys.argv:
45 45 try:
46 46 import pydb
47 47 if hasattr(pydb.pydb, "runl") and pydb.version>'1.17':
48 48 # Version 1.17 is broken, and that's what ships with Ubuntu Edgy, so we
49 49 # better protect against it.
50 50 has_pydb = True
51 51 except ImportError:
52 52 print "Pydb (http://bashdb.sourceforge.net/pydb/) does not seem to be available"
53 53
54 54 if has_pydb:
55 55 from pydb import Pdb as OldPdb
56 56 #print "Using pydb for %run -d and post-mortem" #dbg
57 57 prompt = 'ipydb> '
58 58 else:
59 59 from pdb import Pdb as OldPdb
60 60
61 61 # Allow the set_trace code to operate outside of an ipython instance, even if
62 62 # it does so with some limitations. The rest of this support is implemented in
63 63 # the Tracer constructor.
64 64 def BdbQuit_excepthook(et,ev,tb):
65 65 if et==bdb.BdbQuit:
66 66 print 'Exiting Debugger.'
67 67 else:
68 68 BdbQuit_excepthook.excepthook_ori(et,ev,tb)
69 69
70 70 def BdbQuit_IPython_excepthook(self,et,ev,tb):
71 71 print 'Exiting Debugger.'
72 72
73 73 class Tracer(object):
74 74 """Class for local debugging, similar to pdb.set_trace.
75 75
76 76 Instances of this class, when called, behave like pdb.set_trace, but
77 77 providing IPython's enhanced capabilities.
78 78
79 79 This is implemented as a class which must be initialized in your own code
80 80 and not as a standalone function because we need to detect at runtime
81 81 whether IPython is already active or not. That detection is done in the
82 82 constructor, ensuring that this code plays nicely with a running IPython,
83 83 while functioning acceptably (though with limitations) if outside of it.
84 84 """
85 85
86 86 def __init__(self,colors=None):
87 87 """Create a local debugger instance.
88 88
89 89 :Parameters:
90 90
91 91 - `colors` (None): a string containing the name of the color scheme to
92 92 use, it must be one of IPython's valid color schemes. If not given, the
93 93 function will default to the current IPython scheme when running inside
94 94 IPython, and to 'NoColor' otherwise.
95 95
96 96 Usage example:
97 97
98 98 from IPython.core.debugger import Tracer; debug_here = Tracer()
99 99
100 100 ... later in your code
101 101 debug_here() # -> will open up the debugger at that point.
102 102
103 103 Once the debugger activates, you can use all of its regular commands to
104 104 step through code, set breakpoints, etc. See the pdb documentation
105 105 from the Python standard library for usage details.
106 106 """
107 107
108 108 global __IPYTHON__
109 109 try:
110 110 __IPYTHON__
111 111 except NameError:
112 112 # Outside of ipython, we set our own exception hook manually
113 113 __IPYTHON__ = ipapi.get(True,False)
114 114 BdbQuit_excepthook.excepthook_ori = sys.excepthook
115 115 sys.excepthook = BdbQuit_excepthook
116 116 def_colors = 'NoColor'
117 117 try:
118 118 # Limited tab completion support
119 119 import readline
120 120 readline.parse_and_bind('tab: complete')
121 121 except ImportError:
122 122 pass
123 123 else:
124 124 # In ipython, we use its custom exception handler mechanism
125 125 ip = ipapi.get()
126 126 def_colors = ip.options.colors
127 127 ip.set_custom_exc((bdb.BdbQuit,),BdbQuit_IPython_excepthook)
128 128
129 129 if colors is None:
130 130 colors = def_colors
131 131 self.debugger = Pdb(colors)
132 132
133 133 def __call__(self):
134 134 """Starts an interactive debugger at the point where called.
135 135
136 136 This is similar to the pdb.set_trace() function from the std lib, but
137 137 using IPython's enhanced debugger."""
138 138
139 139 self.debugger.set_trace(sys._getframe().f_back)
140 140
141 141 def decorate_fn_with_doc(new_fn, old_fn, additional_text=""):
142 142 """Make new_fn have old_fn's doc string. This is particularly useful
143 143 for the do_... commands that hook into the help system.
144 144 Adapted from from a comp.lang.python posting
145 145 by Duncan Booth."""
146 146 def wrapper(*args, **kw):
147 147 return new_fn(*args, **kw)
148 148 if old_fn.__doc__:
149 149 wrapper.__doc__ = old_fn.__doc__ + additional_text
150 150 return wrapper
151 151
152 152 def _file_lines(fname):
153 153 """Return the contents of a named file as a list of lines.
154 154
155 155 This function never raises an IOError exception: if the file can't be
156 156 read, it simply returns an empty list."""
157 157
158 158 try:
159 159 outfile = open(fname)
160 160 except IOError:
161 161 return []
162 162 else:
163 163 out = outfile.readlines()
164 164 outfile.close()
165 165 return out
166 166
167 167 class Pdb(OldPdb):
168 168 """Modified Pdb class, does not load readline."""
169 169
170 170 if sys.version[:3] >= '2.5' or has_pydb:
171 171 def __init__(self,color_scheme='NoColor',completekey=None,
172 172 stdin=None, stdout=None):
173 173
174 174 # Parent constructor:
175 175 if has_pydb and completekey is None:
176 176 OldPdb.__init__(self,stdin=stdin,stdout=Term.cout)
177 177 else:
178 178 OldPdb.__init__(self,completekey,stdin,stdout)
179 179
180 180 self.prompt = prompt # The default prompt is '(Pdb)'
181 181
182 182 # IPython changes...
183 183 self.is_pydb = has_pydb
184 184
185 185 if self.is_pydb:
186 186
187 187 # iplib.py's ipalias seems to want pdb's checkline
188 188 # which located in pydb.fn
189 189 import pydb.fns
190 190 self.checkline = lambda filename, lineno: \
191 191 pydb.fns.checkline(self, filename, lineno)
192 192
193 193 self.curframe = None
194 194 self.do_restart = self.new_do_restart
195 195
196 196 self.old_all_completions = __IPYTHON__.Completer.all_completions
197 197 __IPYTHON__.Completer.all_completions=self.all_completions
198 198
199 199 self.do_list = decorate_fn_with_doc(self.list_command_pydb,
200 200 OldPdb.do_list)
201 201 self.do_l = self.do_list
202 202 self.do_frame = decorate_fn_with_doc(self.new_do_frame,
203 203 OldPdb.do_frame)
204 204
205 205 self.aliases = {}
206 206
207 207 # Create color table: we copy the default one from the traceback
208 208 # module and add a few attributes needed for debugging
209 209 self.color_scheme_table = exception_colors()
210 210
211 211 # shorthands
212 212 C = coloransi.TermColors
213 213 cst = self.color_scheme_table
214 214
215 215 cst['NoColor'].colors.breakpoint_enabled = C.NoColor
216 216 cst['NoColor'].colors.breakpoint_disabled = C.NoColor
217 217
218 218 cst['Linux'].colors.breakpoint_enabled = C.LightRed
219 219 cst['Linux'].colors.breakpoint_disabled = C.Red
220 220
221 221 cst['LightBG'].colors.breakpoint_enabled = C.LightRed
222 222 cst['LightBG'].colors.breakpoint_disabled = C.Red
223 223
224 224 self.set_colors(color_scheme)
225 225
226 226 # Add a python parser so we can syntax highlight source while
227 227 # debugging.
228 228 self.parser = PyColorize.Parser()
229 229
230 230
231 231 else:
232 232 # Ugly hack: for Python 2.3-2.4, we can't call the parent constructor,
233 233 # because it binds readline and breaks tab-completion. This means we
234 234 # have to COPY the constructor here.
235 235 def __init__(self,color_scheme='NoColor'):
236 236 bdb.Bdb.__init__(self)
237 237 cmd.Cmd.__init__(self,completekey=None) # don't load readline
238 238 self.prompt = 'ipdb> ' # The default prompt is '(Pdb)'
239 239 self.aliases = {}
240 240
241 241 # These two lines are part of the py2.4 constructor, let's put them
242 242 # unconditionally here as they won't cause any problems in 2.3.
243 243 self.mainpyfile = ''
244 244 self._wait_for_mainpyfile = 0
245 245
246 246 # Read $HOME/.pdbrc and ./.pdbrc
247 247 try:
248 248 self.rcLines = _file_lines(os.path.join(os.environ['HOME'],
249 249 ".pdbrc"))
250 250 except KeyError:
251 251 self.rcLines = []
252 252 self.rcLines.extend(_file_lines(".pdbrc"))
253 253
254 254 # Create color table: we copy the default one from the traceback
255 255 # module and add a few attributes needed for debugging
256 256 self.color_scheme_table = exception_colors()
257 257
258 258 # shorthands
259 259 C = coloransi.TermColors
260 260 cst = self.color_scheme_table
261 261
262 262 cst['NoColor'].colors.breakpoint_enabled = C.NoColor
263 263 cst['NoColor'].colors.breakpoint_disabled = C.NoColor
264 264
265 265 cst['Linux'].colors.breakpoint_enabled = C.LightRed
266 266 cst['Linux'].colors.breakpoint_disabled = C.Red
267 267
268 268 cst['LightBG'].colors.breakpoint_enabled = C.LightRed
269 269 cst['LightBG'].colors.breakpoint_disabled = C.Red
270 270
271 271 self.set_colors(color_scheme)
272 272
273 273 # Add a python parser so we can syntax highlight source while
274 274 # debugging.
275 275 self.parser = PyColorize.Parser()
276 276
277 277 def set_colors(self, scheme):
278 278 """Shorthand access to the color table scheme selector method."""
279 279 self.color_scheme_table.set_active_scheme(scheme)
280 280
281 281 def interaction(self, frame, traceback):
282 282 __IPYTHON__.set_completer_frame(frame)
283 283 OldPdb.interaction(self, frame, traceback)
284 284
285 285 def new_do_up(self, arg):
286 286 OldPdb.do_up(self, arg)
287 287 __IPYTHON__.set_completer_frame(self.curframe)
288 288 do_u = do_up = decorate_fn_with_doc(new_do_up, OldPdb.do_up)
289 289
290 290 def new_do_down(self, arg):
291 291 OldPdb.do_down(self, arg)
292 292 __IPYTHON__.set_completer_frame(self.curframe)
293 293
294 294 do_d = do_down = decorate_fn_with_doc(new_do_down, OldPdb.do_down)
295 295
296 296 def new_do_frame(self, arg):
297 297 OldPdb.do_frame(self, arg)
298 298 __IPYTHON__.set_completer_frame(self.curframe)
299 299
300 300 def new_do_quit(self, arg):
301 301
302 302 if hasattr(self, 'old_all_completions'):
303 303 __IPYTHON__.Completer.all_completions=self.old_all_completions
304 304
305 305
306 306 return OldPdb.do_quit(self, arg)
307 307
308 308 do_q = do_quit = decorate_fn_with_doc(new_do_quit, OldPdb.do_quit)
309 309
310 310 def new_do_restart(self, arg):
311 311 """Restart command. In the context of ipython this is exactly the same
312 312 thing as 'quit'."""
313 313 self.msg("Restart doesn't make sense here. Using 'quit' instead.")
314 314 return self.do_quit(arg)
315 315
316 316 def postloop(self):
317 317 __IPYTHON__.set_completer_frame(None)
318 318
319 319 def print_stack_trace(self):
320 320 try:
321 321 for frame_lineno in self.stack:
322 322 self.print_stack_entry(frame_lineno, context = 5)
323 323 except KeyboardInterrupt:
324 324 pass
325 325
326 326 def print_stack_entry(self,frame_lineno,prompt_prefix='\n-> ',
327 327 context = 3):
328 328 #frame, lineno = frame_lineno
329 329 print >>Term.cout, self.format_stack_entry(frame_lineno, '', context)
330 330
331 331 # vds: >>
332 332 frame, lineno = frame_lineno
333 333 filename = frame.f_code.co_filename
334 334 __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
335 335 # vds: <<
336 336
337 337 def format_stack_entry(self, frame_lineno, lprefix=': ', context = 3):
338 338 import linecache, repr
339 339
340 340 ret = []
341 341
342 342 Colors = self.color_scheme_table.active_colors
343 343 ColorsNormal = Colors.Normal
344 344 tpl_link = '%s%%s%s' % (Colors.filenameEm, ColorsNormal)
345 345 tpl_call = '%s%%s%s%%s%s' % (Colors.vName, Colors.valEm, ColorsNormal)
346 346 tpl_line = '%%s%s%%s %s%%s' % (Colors.lineno, ColorsNormal)
347 347 tpl_line_em = '%%s%s%%s %s%%s%s' % (Colors.linenoEm, Colors.line,
348 348 ColorsNormal)
349 349
350 350 frame, lineno = frame_lineno
351 351
352 352 return_value = ''
353 353 if '__return__' in frame.f_locals:
354 354 rv = frame.f_locals['__return__']
355 355 #return_value += '->'
356 356 return_value += repr.repr(rv) + '\n'
357 357 ret.append(return_value)
358 358
359 359 #s = filename + '(' + `lineno` + ')'
360 360 filename = self.canonic(frame.f_code.co_filename)
361 361 link = tpl_link % filename
362 362
363 363 if frame.f_code.co_name:
364 364 func = frame.f_code.co_name
365 365 else:
366 366 func = "<lambda>"
367 367
368 368 call = ''
369 369 if func != '?':
370 370 if '__args__' in frame.f_locals:
371 371 args = repr.repr(frame.f_locals['__args__'])
372 372 else:
373 373 args = '()'
374 374 call = tpl_call % (func, args)
375 375
376 376 # The level info should be generated in the same format pdb uses, to
377 377 # avoid breaking the pdbtrack functionality of python-mode in *emacs.
378 378 if frame is self.curframe:
379 379 ret.append('> ')
380 380 else:
381 381 ret.append(' ')
382 382 ret.append('%s(%s)%s\n' % (link,lineno,call))
383 383
384 384 start = lineno - 1 - context//2
385 385 lines = linecache.getlines(filename)
386 386 start = max(start, 0)
387 387 start = min(start, len(lines) - context)
388 388 lines = lines[start : start + context]
389 389
390 390 for i,line in enumerate(lines):
391 391 show_arrow = (start + 1 + i == lineno)
392 392 linetpl = (frame is self.curframe or show_arrow) \
393 393 and tpl_line_em \
394 394 or tpl_line
395 395 ret.append(self.__format_line(linetpl, filename,
396 396 start + 1 + i, line,
397 397 arrow = show_arrow) )
398 398
399 399 return ''.join(ret)
400 400
401 401 def __format_line(self, tpl_line, filename, lineno, line, arrow = False):
402 402 bp_mark = ""
403 403 bp_mark_color = ""
404 404
405 405 scheme = self.color_scheme_table.active_scheme_name
406 406 new_line, err = self.parser.format2(line, 'str', scheme)
407 407 if not err: line = new_line
408 408
409 409 bp = None
410 410 if lineno in self.get_file_breaks(filename):
411 411 bps = self.get_breaks(filename, lineno)
412 412 bp = bps[-1]
413 413
414 414 if bp:
415 415 Colors = self.color_scheme_table.active_colors
416 416 bp_mark = str(bp.number)
417 417 bp_mark_color = Colors.breakpoint_enabled
418 418 if not bp.enabled:
419 419 bp_mark_color = Colors.breakpoint_disabled
420 420
421 421 numbers_width = 7
422 422 if arrow:
423 423 # This is the line with the error
424 424 pad = numbers_width - len(str(lineno)) - len(bp_mark)
425 425 if pad >= 3:
426 426 marker = '-'*(pad-3) + '-> '
427 427 elif pad == 2:
428 428 marker = '> '
429 429 elif pad == 1:
430 430 marker = '>'
431 431 else:
432 432 marker = ''
433 433 num = '%s%s' % (marker, str(lineno))
434 434 line = tpl_line % (bp_mark_color + bp_mark, num, line)
435 435 else:
436 436 num = '%*s' % (numbers_width - len(bp_mark), str(lineno))
437 437 line = tpl_line % (bp_mark_color + bp_mark, num, line)
438 438
439 439 return line
440 440
441 441 def list_command_pydb(self, arg):
442 442 """List command to use if we have a newer pydb installed"""
443 443 filename, first, last = OldPdb.parse_list_cmd(self, arg)
444 444 if filename is not None:
445 445 self.print_list_lines(filename, first, last)
446 446
447 447 def print_list_lines(self, filename, first, last):
448 448 """The printing (as opposed to the parsing part of a 'list'
449 449 command."""
450 450 try:
451 451 Colors = self.color_scheme_table.active_colors
452 452 ColorsNormal = Colors.Normal
453 453 tpl_line = '%%s%s%%s %s%%s' % (Colors.lineno, ColorsNormal)
454 454 tpl_line_em = '%%s%s%%s %s%%s%s' % (Colors.linenoEm, Colors.line, ColorsNormal)
455 455 src = []
456 456 for lineno in range(first, last+1):
457 457 line = linecache.getline(filename, lineno)
458 458 if not line:
459 459 break
460 460
461 461 if lineno == self.curframe.f_lineno:
462 462 line = self.__format_line(tpl_line_em, filename, lineno, line, arrow = True)
463 463 else:
464 464 line = self.__format_line(tpl_line, filename, lineno, line, arrow = False)
465 465
466 466 src.append(line)
467 467 self.lineno = lineno
468 468
469 469 print >>Term.cout, ''.join(src)
470 470
471 471 except KeyboardInterrupt:
472 472 pass
473 473
474 474 def do_list(self, arg):
475 475 self.lastcmd = 'list'
476 476 last = None
477 477 if arg:
478 478 try:
479 479 x = eval(arg, {}, {})
480 480 if type(x) == type(()):
481 481 first, last = x
482 482 first = int(first)
483 483 last = int(last)
484 484 if last < first:
485 485 # Assume it's a count
486 486 last = first + last
487 487 else:
488 488 first = max(1, int(x) - 5)
489 489 except:
490 490 print '*** Error in argument:', `arg`
491 491 return
492 492 elif self.lineno is None:
493 493 first = max(1, self.curframe.f_lineno - 5)
494 494 else:
495 495 first = self.lineno + 1
496 496 if last is None:
497 497 last = first + 10
498 498 self.print_list_lines(self.curframe.f_code.co_filename, first, last)
499 499
500 500 # vds: >>
501 501 lineno = first
502 502 filename = self.curframe.f_code.co_filename
503 503 __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
504 504 # vds: <<
505 505
506 506 do_l = do_list
507 507
508 508 def do_pdef(self, arg):
509 509 """The debugger interface to magic_pdef"""
510 510 namespaces = [('Locals', self.curframe.f_locals),
511 511 ('Globals', self.curframe.f_globals)]
512 512 __IPYTHON__.magic_pdef(arg, namespaces=namespaces)
513 513
514 514 def do_pdoc(self, arg):
515 515 """The debugger interface to magic_pdoc"""
516 516 namespaces = [('Locals', self.curframe.f_locals),
517 517 ('Globals', self.curframe.f_globals)]
518 518 __IPYTHON__.magic_pdoc(arg, namespaces=namespaces)
519 519
520 520 def do_pinfo(self, arg):
521 521 """The debugger equivalant of ?obj"""
522 522 namespaces = [('Locals', self.curframe.f_locals),
523 523 ('Globals', self.curframe.f_globals)]
524 524 __IPYTHON__.magic_pinfo("pinfo %s" % arg, namespaces=namespaces)
@@ -1,2864 +1,2865 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 IPython -- An enhanced Interactive Python
4 4
5 5 Requires Python 2.4 or newer.
6 6
7 7 This file contains all the classes and helper functions specific to IPython.
8 8 """
9 9
10 10 #*****************************************************************************
11 11 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
12 12 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
13 13 #
14 14 # Distributed under the terms of the BSD License. The full license is in
15 15 # the file COPYING, distributed as part of this software.
16 16 #
17 17 # Note: this code originally subclassed code.InteractiveConsole from the
18 18 # Python standard library. Over time, all of that class has been copied
19 19 # verbatim here for modifications which could not be accomplished by
20 20 # subclassing. At this point, there are no dependencies at all on the code
21 21 # module anymore (it is not even imported). The Python License (sec. 2)
22 22 # allows for this, but it's always nice to acknowledge credit where credit is
23 23 # due.
24 24 #*****************************************************************************
25 25
26 26 #****************************************************************************
27 27 # Modules and globals
28 28
29 29 # Python standard modules
30 30 import __main__
31 31 import __builtin__
32 32 import StringIO
33 33 import bdb
34 34 import codeop
35 35 import exceptions
36 36 import glob
37 37 import keyword
38 38 import new
39 39 import os
40 40 import re
41 41 import shutil
42 42 import string
43 43 import sys
44 44 import tempfile
45 45
46 46 # IPython's own modules
47 47 #import IPython
48 from IPython import PyColorize,ultraTB
48 from IPython import ultraTB
49 from IPython.utils import PyColorize
49 50 from IPython.core import debugger, oinspect
50 51 from IPython.Extensions import pickleshare
51 52 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
52 53 from IPython.external.Itpl import ItplNS
53 54 from IPython.core.logger import Logger
54 55 from IPython.core.magic import Magic
55 56 from IPython.core.prompts import CachedOutput
56 57 from IPython.utils.ipstruct import Struct
57 58 from IPython.lib.backgroundjobs import BackgroundJobManager
58 59 from IPython.utils.genutils import *
59 60 from IPython.strdispatch import StrDispatch
60 61 from IPython.core import ipapi
61 62 import IPython.core.history
62 63 import IPython.core.prefilter as prefilter
63 64 import IPython.shadowns
64 65 # Globals
65 66
66 67 # store the builtin raw_input globally, and use this always, in case user code
67 68 # overwrites it (like wx.py.PyShell does)
68 69 raw_input_original = raw_input
69 70
70 71 # compiled regexps for autoindent management
71 72 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
72 73
73 74
74 75 #****************************************************************************
75 76 # Some utility function definitions
76 77
77 78 ini_spaces_re = re.compile(r'^(\s+)')
78 79
79 80 def num_ini_spaces(strng):
80 81 """Return the number of initial spaces in a string"""
81 82
82 83 ini_spaces = ini_spaces_re.match(strng)
83 84 if ini_spaces:
84 85 return ini_spaces.end()
85 86 else:
86 87 return 0
87 88
88 89 def softspace(file, newvalue):
89 90 """Copied from code.py, to remove the dependency"""
90 91
91 92 oldvalue = 0
92 93 try:
93 94 oldvalue = file.softspace
94 95 except AttributeError:
95 96 pass
96 97 try:
97 98 file.softspace = newvalue
98 99 except (AttributeError, TypeError):
99 100 # "attribute-less object" or "read-only attributes"
100 101 pass
101 102 return oldvalue
102 103
103 104
104 105 def user_setup(ipythondir,rc_suffix,mode='install',interactive=True):
105 106 """Install or upgrade the user configuration directory.
106 107
107 108 Can be called when running for the first time or to upgrade the user's
108 109 .ipython/ directory.
109 110
110 111 Parameters
111 112 ----------
112 113 ipythondir : path
113 114 The directory to be used for installation/upgrade. In 'install' mode,
114 115 if this path already exists, the function exits immediately.
115 116
116 117 rc_suffix : str
117 118 Extension for the config files. On *nix platforms it is typically the
118 119 empty string, while Windows normally uses '.ini'.
119 120
120 121 mode : str, optional
121 122 Valid modes are 'install' and 'upgrade'.
122 123
123 124 interactive : bool, optional
124 125 If False, do not wait for user input on any errors. Normally after
125 126 printing its status information, this function waits for the user to
126 127 hit Return before proceeding. This is because the default use case is
127 128 when first installing the IPython configuration, so we want the user to
128 129 acknowledge the initial message, which contains some useful
129 130 information.
130 131 """
131 132
132 133 # For automatic use, deactivate all i/o
133 134 if interactive:
134 135 def wait():
135 136 try:
136 137 raw_input("Please press <RETURN> to start IPython.")
137 138 except EOFError:
138 139 print >> Term.cout
139 140 print '*'*70
140 141
141 142 def printf(s):
142 143 print s
143 144 else:
144 145 wait = lambda : None
145 146 printf = lambda s : None
146 147
147 148 # Install mode should be re-entrant: if the install dir already exists,
148 149 # bail out cleanly.
149 150 # XXX. This is too hasty to return. We need to check to make sure that
150 151 # all the expected config files and directories are actually there. We
151 152 # currently have a failure mode if someone deletes a needed config file
152 153 # but still has the ipythondir.
153 154 if mode == 'install' and os.path.isdir(ipythondir):
154 155 return
155 156
156 157 cwd = os.getcwd() # remember where we started
157 158 glb = glob.glob
158 159
159 160 printf('*'*70)
160 161 if mode == 'install':
161 162 printf(
162 163 """Welcome to IPython. I will try to create a personal configuration directory
163 164 where you can customize many aspects of IPython's functionality in:\n""")
164 165 else:
165 166 printf('I am going to upgrade your configuration in:')
166 167
167 168 printf(ipythondir)
168 169
169 170 rcdirend = os.path.join('IPython','UserConfig')
170 171 cfg = lambda d: os.path.join(d,rcdirend)
171 172 try:
172 173 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
173 174 printf("Initializing from configuration: %s" % rcdir)
174 175 except IndexError:
175 176 warning = """
176 177 Installation error. IPython's directory was not found.
177 178
178 179 Check the following:
179 180
180 181 The ipython/IPython directory should be in a directory belonging to your
181 182 PYTHONPATH environment variable (that is, it should be in a directory
182 183 belonging to sys.path). You can copy it explicitly there or just link to it.
183 184
184 185 IPython will create a minimal default configuration for you.
185 186
186 187 """
187 188 warn(warning)
188 189 wait()
189 190
190 191 if sys.platform =='win32':
191 192 inif = 'ipythonrc.ini'
192 193 else:
193 194 inif = 'ipythonrc'
194 195 minimal_setup = {'ipy_user_conf.py' : 'import ipy_defaults',
195 196 inif : '# intentionally left blank' }
196 197 os.makedirs(ipythondir, mode = 0777)
197 198 for f, cont in minimal_setup.items():
198 199 # In 2.5, this can be more cleanly done using 'with'
199 200 fobj = file(ipythondir + '/' + f,'w')
200 201 fobj.write(cont)
201 202 fobj.close()
202 203
203 204 return
204 205
205 206 if mode == 'install':
206 207 try:
207 208 shutil.copytree(rcdir,ipythondir)
208 209 os.chdir(ipythondir)
209 210 rc_files = glb("ipythonrc*")
210 211 for rc_file in rc_files:
211 212 os.rename(rc_file,rc_file+rc_suffix)
212 213 except:
213 214 warning = """
214 215
215 216 There was a problem with the installation:
216 217 %s
217 218 Try to correct it or contact the developers if you think it's a bug.
218 219 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
219 220 warn(warning)
220 221 wait()
221 222 return
222 223
223 224 elif mode == 'upgrade':
224 225 try:
225 226 os.chdir(ipythondir)
226 227 except:
227 228 printf("""
228 229 Can not upgrade: changing to directory %s failed. Details:
229 230 %s
230 231 """ % (ipythondir,sys.exc_info()[1]) )
231 232 wait()
232 233 return
233 234 else:
234 235 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
235 236 for new_full_path in sources:
236 237 new_filename = os.path.basename(new_full_path)
237 238 if new_filename.startswith('ipythonrc'):
238 239 new_filename = new_filename + rc_suffix
239 240 # The config directory should only contain files, skip any
240 241 # directories which may be there (like CVS)
241 242 if os.path.isdir(new_full_path):
242 243 continue
243 244 if os.path.exists(new_filename):
244 245 old_file = new_filename+'.old'
245 246 if os.path.exists(old_file):
246 247 os.remove(old_file)
247 248 os.rename(new_filename,old_file)
248 249 shutil.copy(new_full_path,new_filename)
249 250 else:
250 251 raise ValueError('unrecognized mode for install: %r' % mode)
251 252
252 253 # Fix line-endings to those native to each platform in the config
253 254 # directory.
254 255 try:
255 256 os.chdir(ipythondir)
256 257 except:
257 258 printf("""
258 259 Problem: changing to directory %s failed.
259 260 Details:
260 261 %s
261 262
262 263 Some configuration files may have incorrect line endings. This should not
263 264 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1]) )
264 265 wait()
265 266 else:
266 267 for fname in glb('ipythonrc*'):
267 268 try:
268 269 native_line_ends(fname,backup=0)
269 270 except IOError:
270 271 pass
271 272
272 273 if mode == 'install':
273 274 printf("""
274 275 Successful installation!
275 276
276 277 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
277 278 IPython manual (there are both HTML and PDF versions supplied with the
278 279 distribution) to make sure that your system environment is properly configured
279 280 to take advantage of IPython's features.
280 281
281 282 Important note: the configuration system has changed! The old system is
282 283 still in place, but its setting may be partly overridden by the settings in
283 284 "~/.ipython/ipy_user_conf.py" config file. Please take a look at the file
284 285 if some of the new settings bother you.
285 286
286 287 """)
287 288 else:
288 289 printf("""
289 290 Successful upgrade!
290 291
291 292 All files in your directory:
292 293 %(ipythondir)s
293 294 which would have been overwritten by the upgrade were backed up with a .old
294 295 extension. If you had made particular customizations in those files you may
295 296 want to merge them back into the new files.""" % locals() )
296 297 wait()
297 298 os.chdir(cwd)
298 299
299 300 #****************************************************************************
300 301 # Local use exceptions
301 302 class SpaceInInput(exceptions.Exception): pass
302 303
303 304
304 305 #****************************************************************************
305 306 # Local use classes
306 307 class Bunch: pass
307 308
308 309 class Undefined: pass
309 310
310 311 class Quitter(object):
311 312 """Simple class to handle exit, similar to Python 2.5's.
312 313
313 314 It handles exiting in an ipython-safe manner, which the one in Python 2.5
314 315 doesn't do (obviously, since it doesn't know about ipython)."""
315 316
316 317 def __init__(self,shell,name):
317 318 self.shell = shell
318 319 self.name = name
319 320
320 321 def __repr__(self):
321 322 return 'Type %s() to exit.' % self.name
322 323 __str__ = __repr__
323 324
324 325 def __call__(self):
325 326 self.shell.exit()
326 327
327 328 class InputList(list):
328 329 """Class to store user input.
329 330
330 331 It's basically a list, but slices return a string instead of a list, thus
331 332 allowing things like (assuming 'In' is an instance):
332 333
333 334 exec In[4:7]
334 335
335 336 or
336 337
337 338 exec In[5:9] + In[14] + In[21:25]"""
338 339
339 340 def __getslice__(self,i,j):
340 341 return ''.join(list.__getslice__(self,i,j))
341 342
342 343 class SyntaxTB(ultraTB.ListTB):
343 344 """Extension which holds some state: the last exception value"""
344 345
345 346 def __init__(self,color_scheme = 'NoColor'):
346 347 ultraTB.ListTB.__init__(self,color_scheme)
347 348 self.last_syntax_error = None
348 349
349 350 def __call__(self, etype, value, elist):
350 351 self.last_syntax_error = value
351 352 ultraTB.ListTB.__call__(self,etype,value,elist)
352 353
353 354 def clear_err_state(self):
354 355 """Return the current error state and clear it"""
355 356 e = self.last_syntax_error
356 357 self.last_syntax_error = None
357 358 return e
358 359
359 360 #****************************************************************************
360 361 # Main IPython class
361 362
362 363 # FIXME: the Magic class is a mixin for now, and will unfortunately remain so
363 364 # until a full rewrite is made. I've cleaned all cross-class uses of
364 365 # attributes and methods, but too much user code out there relies on the
365 366 # equlity %foo == __IP.magic_foo, so I can't actually remove the mixin usage.
366 367 #
367 368 # But at least now, all the pieces have been separated and we could, in
368 369 # principle, stop using the mixin. This will ease the transition to the
369 370 # chainsaw branch.
370 371
371 372 # For reference, the following is the list of 'self.foo' uses in the Magic
372 373 # class as of 2005-12-28. These are names we CAN'T use in the main ipython
373 374 # class, to prevent clashes.
374 375
375 376 # ['self.__class__', 'self.__dict__', 'self._inspect', 'self._ofind',
376 377 # 'self.arg_err', 'self.extract_input', 'self.format_', 'self.lsmagic',
377 378 # 'self.magic_', 'self.options_table', 'self.parse', 'self.shell',
378 379 # 'self.value']
379 380
380 381 class InteractiveShell(object,Magic):
381 382 """An enhanced console for Python."""
382 383
383 384 # class attribute to indicate whether the class supports threads or not.
384 385 # Subclasses with thread support should override this as needed.
385 386 isthreaded = False
386 387
387 388 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
388 389 user_ns=None,user_global_ns=None,banner2='',
389 390 custom_exceptions=((),None),embedded=False):
390 391
391 392 # log system
392 393 self.logger = Logger(self,logfname='ipython_log.py',logmode='rotate')
393 394
394 395 # Job manager (for jobs run as background threads)
395 396 self.jobs = BackgroundJobManager()
396 397
397 398 # Store the actual shell's name
398 399 self.name = name
399 400 self.more = False
400 401
401 402 # We need to know whether the instance is meant for embedding, since
402 403 # global/local namespaces need to be handled differently in that case
403 404 self.embedded = embedded
404 405 if embedded:
405 406 # Control variable so users can, from within the embedded instance,
406 407 # permanently deactivate it.
407 408 self.embedded_active = True
408 409
409 410 # command compiler
410 411 self.compile = codeop.CommandCompiler()
411 412
412 413 # User input buffer
413 414 self.buffer = []
414 415
415 416 # Default name given in compilation of code
416 417 self.filename = '<ipython console>'
417 418
418 419 # Install our own quitter instead of the builtins. For python2.3-2.4,
419 420 # this brings in behavior like 2.5, and for 2.5 it's identical.
420 421 __builtin__.exit = Quitter(self,'exit')
421 422 __builtin__.quit = Quitter(self,'quit')
422 423
423 424 # Make an empty namespace, which extension writers can rely on both
424 425 # existing and NEVER being used by ipython itself. This gives them a
425 426 # convenient location for storing additional information and state
426 427 # their extensions may require, without fear of collisions with other
427 428 # ipython names that may develop later.
428 429 self.meta = Struct()
429 430
430 431 # Create the namespace where the user will operate. user_ns is
431 432 # normally the only one used, and it is passed to the exec calls as
432 433 # the locals argument. But we do carry a user_global_ns namespace
433 434 # given as the exec 'globals' argument, This is useful in embedding
434 435 # situations where the ipython shell opens in a context where the
435 436 # distinction between locals and globals is meaningful. For
436 437 # non-embedded contexts, it is just the same object as the user_ns dict.
437 438
438 439 # FIXME. For some strange reason, __builtins__ is showing up at user
439 440 # level as a dict instead of a module. This is a manual fix, but I
440 441 # should really track down where the problem is coming from. Alex
441 442 # Schmolck reported this problem first.
442 443
443 444 # A useful post by Alex Martelli on this topic:
444 445 # Re: inconsistent value from __builtins__
445 446 # Von: Alex Martelli <aleaxit@yahoo.com>
446 447 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
447 448 # Gruppen: comp.lang.python
448 449
449 450 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
450 451 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
451 452 # > <type 'dict'>
452 453 # > >>> print type(__builtins__)
453 454 # > <type 'module'>
454 455 # > Is this difference in return value intentional?
455 456
456 457 # Well, it's documented that '__builtins__' can be either a dictionary
457 458 # or a module, and it's been that way for a long time. Whether it's
458 459 # intentional (or sensible), I don't know. In any case, the idea is
459 460 # that if you need to access the built-in namespace directly, you
460 461 # should start with "import __builtin__" (note, no 's') which will
461 462 # definitely give you a module. Yeah, it's somewhat confusing:-(.
462 463
463 464 # These routines return properly built dicts as needed by the rest of
464 465 # the code, and can also be used by extension writers to generate
465 466 # properly initialized namespaces.
466 467 user_ns, user_global_ns = ipapi.make_user_namespaces(user_ns,
467 468 user_global_ns)
468 469
469 470 # Assign namespaces
470 471 # This is the namespace where all normal user variables live
471 472 self.user_ns = user_ns
472 473 self.user_global_ns = user_global_ns
473 474
474 475 # An auxiliary namespace that checks what parts of the user_ns were
475 476 # loaded at startup, so we can list later only variables defined in
476 477 # actual interactive use. Since it is always a subset of user_ns, it
477 478 # doesn't need to be seaparately tracked in the ns_table
478 479 self.user_config_ns = {}
479 480
480 481 # A namespace to keep track of internal data structures to prevent
481 482 # them from cluttering user-visible stuff. Will be updated later
482 483 self.internal_ns = {}
483 484
484 485 # Namespace of system aliases. Each entry in the alias
485 486 # table must be a 2-tuple of the form (N,name), where N is the number
486 487 # of positional arguments of the alias.
487 488 self.alias_table = {}
488 489
489 490 # Now that FakeModule produces a real module, we've run into a nasty
490 491 # problem: after script execution (via %run), the module where the user
491 492 # code ran is deleted. Now that this object is a true module (needed
492 493 # so docetst and other tools work correctly), the Python module
493 494 # teardown mechanism runs over it, and sets to None every variable
494 495 # present in that module. Top-level references to objects from the
495 496 # script survive, because the user_ns is updated with them. However,
496 497 # calling functions defined in the script that use other things from
497 498 # the script will fail, because the function's closure had references
498 499 # to the original objects, which are now all None. So we must protect
499 500 # these modules from deletion by keeping a cache.
500 501 #
501 502 # To avoid keeping stale modules around (we only need the one from the
502 503 # last run), we use a dict keyed with the full path to the script, so
503 504 # only the last version of the module is held in the cache. Note,
504 505 # however, that we must cache the module *namespace contents* (their
505 506 # __dict__). Because if we try to cache the actual modules, old ones
506 507 # (uncached) could be destroyed while still holding references (such as
507 508 # those held by GUI objects that tend to be long-lived)>
508 509 #
509 510 # The %reset command will flush this cache. See the cache_main_mod()
510 511 # and clear_main_mod_cache() methods for details on use.
511 512
512 513 # This is the cache used for 'main' namespaces
513 514 self._main_ns_cache = {}
514 515 # And this is the single instance of FakeModule whose __dict__ we keep
515 516 # copying and clearing for reuse on each %run
516 517 self._user_main_module = FakeModule()
517 518
518 519 # A table holding all the namespaces IPython deals with, so that
519 520 # introspection facilities can search easily.
520 521 self.ns_table = {'user':user_ns,
521 522 'user_global':user_global_ns,
522 523 'alias':self.alias_table,
523 524 'internal':self.internal_ns,
524 525 'builtin':__builtin__.__dict__
525 526 }
526 527
527 528 # Similarly, track all namespaces where references can be held and that
528 529 # we can safely clear (so it can NOT include builtin). This one can be
529 530 # a simple list.
530 531 self.ns_refs_table = [ user_ns, user_global_ns, self.user_config_ns,
531 532 self.alias_table, self.internal_ns,
532 533 self._main_ns_cache ]
533 534
534 535 # We need to insert into sys.modules something that looks like a
535 536 # module but which accesses the IPython namespace, for shelve and
536 537 # pickle to work interactively. Normally they rely on getting
537 538 # everything out of __main__, but for embedding purposes each IPython
538 539 # instance has its own private namespace, so we can't go shoving
539 540 # everything into __main__.
540 541
541 542 # note, however, that we should only do this for non-embedded
542 543 # ipythons, which really mimic the __main__.__dict__ with their own
543 544 # namespace. Embedded instances, on the other hand, should not do
544 545 # this because they need to manage the user local/global namespaces
545 546 # only, but they live within a 'normal' __main__ (meaning, they
546 547 # shouldn't overtake the execution environment of the script they're
547 548 # embedded in).
548 549
549 550 if not embedded:
550 551 try:
551 552 main_name = self.user_ns['__name__']
552 553 except KeyError:
553 554 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
554 555 else:
555 556 #print "pickle hack in place" # dbg
556 557 #print 'main_name:',main_name # dbg
557 558 sys.modules[main_name] = FakeModule(self.user_ns)
558 559
559 560 # List of input with multi-line handling.
560 561 self.input_hist = InputList()
561 562 # This one will hold the 'raw' input history, without any
562 563 # pre-processing. This will allow users to retrieve the input just as
563 564 # it was exactly typed in by the user, with %hist -r.
564 565 self.input_hist_raw = InputList()
565 566
566 567 # list of visited directories
567 568 try:
568 569 self.dir_hist = [os.getcwd()]
569 570 except OSError:
570 571 self.dir_hist = []
571 572
572 573 # dict of output history
573 574 self.output_hist = {}
574 575
575 576 # Get system encoding at startup time. Certain terminals (like Emacs
576 577 # under Win32 have it set to None, and we need to have a known valid
577 578 # encoding to use in the raw_input() method
578 579 try:
579 580 self.stdin_encoding = sys.stdin.encoding or 'ascii'
580 581 except AttributeError:
581 582 self.stdin_encoding = 'ascii'
582 583
583 584 # dict of things NOT to alias (keywords, builtins and some magics)
584 585 no_alias = {}
585 586 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
586 587 for key in keyword.kwlist + no_alias_magics:
587 588 no_alias[key] = 1
588 589 no_alias.update(__builtin__.__dict__)
589 590 self.no_alias = no_alias
590 591
591 592 # Object variable to store code object waiting execution. This is
592 593 # used mainly by the multithreaded shells, but it can come in handy in
593 594 # other situations. No need to use a Queue here, since it's a single
594 595 # item which gets cleared once run.
595 596 self.code_to_run = None
596 597
597 598 # escapes for automatic behavior on the command line
598 599 self.ESC_SHELL = '!'
599 600 self.ESC_SH_CAP = '!!'
600 601 self.ESC_HELP = '?'
601 602 self.ESC_MAGIC = '%'
602 603 self.ESC_QUOTE = ','
603 604 self.ESC_QUOTE2 = ';'
604 605 self.ESC_PAREN = '/'
605 606
606 607 # And their associated handlers
607 608 self.esc_handlers = {self.ESC_PAREN : self.handle_auto,
608 609 self.ESC_QUOTE : self.handle_auto,
609 610 self.ESC_QUOTE2 : self.handle_auto,
610 611 self.ESC_MAGIC : self.handle_magic,
611 612 self.ESC_HELP : self.handle_help,
612 613 self.ESC_SHELL : self.handle_shell_escape,
613 614 self.ESC_SH_CAP : self.handle_shell_escape,
614 615 }
615 616
616 617 # class initializations
617 618 Magic.__init__(self,self)
618 619
619 620 # Python source parser/formatter for syntax highlighting
620 621 pyformat = PyColorize.Parser().format
621 622 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
622 623
623 624 # hooks holds pointers used for user-side customizations
624 625 self.hooks = Struct()
625 626
626 627 self.strdispatchers = {}
627 628
628 629 # Set all default hooks, defined in the IPython.hooks module.
629 630 import IPython.core.hooks
630 631 hooks = IPython.core.hooks
631 632 for hook_name in hooks.__all__:
632 633 # default hooks have priority 100, i.e. low; user hooks should have
633 634 # 0-100 priority
634 635 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
635 636 #print "bound hook",hook_name
636 637
637 638 # Flag to mark unconditional exit
638 639 self.exit_now = False
639 640
640 641 self.usage_min = """\
641 642 An enhanced console for Python.
642 643 Some of its features are:
643 644 - Readline support if the readline library is present.
644 645 - Tab completion in the local namespace.
645 646 - Logging of input, see command-line options.
646 647 - System shell escape via ! , eg !ls.
647 648 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
648 649 - Keeps track of locally defined variables via %who, %whos.
649 650 - Show object information with a ? eg ?x or x? (use ?? for more info).
650 651 """
651 652 if usage: self.usage = usage
652 653 else: self.usage = self.usage_min
653 654
654 655 # Storage
655 656 self.rc = rc # This will hold all configuration information
656 657 self.pager = 'less'
657 658 # temporary files used for various purposes. Deleted at exit.
658 659 self.tempfiles = []
659 660
660 661 # Keep track of readline usage (later set by init_readline)
661 662 self.has_readline = False
662 663
663 664 # template for logfile headers. It gets resolved at runtime by the
664 665 # logstart method.
665 666 self.loghead_tpl = \
666 667 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
667 668 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
668 669 #log# opts = %s
669 670 #log# args = %s
670 671 #log# It is safe to make manual edits below here.
671 672 #log#-----------------------------------------------------------------------
672 673 """
673 674 # for pushd/popd management
674 675 try:
675 676 self.home_dir = get_home_dir()
676 677 except HomeDirError,msg:
677 678 fatal(msg)
678 679
679 680 self.dir_stack = []
680 681
681 682 # Functions to call the underlying shell.
682 683
683 684 # The first is similar to os.system, but it doesn't return a value,
684 685 # and it allows interpolation of variables in the user's namespace.
685 686 self.system = lambda cmd: \
686 687 self.hooks.shell_hook(self.var_expand(cmd,depth=2))
687 688
688 689 # These are for getoutput and getoutputerror:
689 690 self.getoutput = lambda cmd: \
690 691 getoutput(self.var_expand(cmd,depth=2),
691 692 header=self.rc.system_header,
692 693 verbose=self.rc.system_verbose)
693 694
694 695 self.getoutputerror = lambda cmd: \
695 696 getoutputerror(self.var_expand(cmd,depth=2),
696 697 header=self.rc.system_header,
697 698 verbose=self.rc.system_verbose)
698 699
699 700
700 701 # keep track of where we started running (mainly for crash post-mortem)
701 702 self.starting_dir = os.getcwd()
702 703
703 704 # Various switches which can be set
704 705 self.CACHELENGTH = 5000 # this is cheap, it's just text
705 706 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
706 707 self.banner2 = banner2
707 708
708 709 # TraceBack handlers:
709 710
710 711 # Syntax error handler.
711 712 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
712 713
713 714 # The interactive one is initialized with an offset, meaning we always
714 715 # want to remove the topmost item in the traceback, which is our own
715 716 # internal code. Valid modes: ['Plain','Context','Verbose']
716 717 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
717 718 color_scheme='NoColor',
718 719 tb_offset = 1)
719 720
720 721 # IPython itself shouldn't crash. This will produce a detailed
721 722 # post-mortem if it does. But we only install the crash handler for
722 723 # non-threaded shells, the threaded ones use a normal verbose reporter
723 724 # and lose the crash handler. This is because exceptions in the main
724 725 # thread (such as in GUI code) propagate directly to sys.excepthook,
725 726 # and there's no point in printing crash dumps for every user exception.
726 727 if self.isthreaded:
727 728 ipCrashHandler = ultraTB.FormattedTB()
728 729 else:
729 730 from IPython.core import crashhandler
730 731 ipCrashHandler = crashhandler.IPythonCrashHandler(self)
731 732 self.set_crash_handler(ipCrashHandler)
732 733
733 734 # and add any custom exception handlers the user may have specified
734 735 self.set_custom_exc(*custom_exceptions)
735 736
736 737 # indentation management
737 738 self.autoindent = False
738 739 self.indent_current_nsp = 0
739 740
740 741 # Make some aliases automatically
741 742 # Prepare list of shell aliases to auto-define
742 743 if os.name == 'posix':
743 744 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
744 745 'mv mv -i','rm rm -i','cp cp -i',
745 746 'cat cat','less less','clear clear',
746 747 # a better ls
747 748 'ls ls -F',
748 749 # long ls
749 750 'll ls -lF')
750 751 # Extra ls aliases with color, which need special treatment on BSD
751 752 # variants
752 753 ls_extra = ( # color ls
753 754 'lc ls -F -o --color',
754 755 # ls normal files only
755 756 'lf ls -F -o --color %l | grep ^-',
756 757 # ls symbolic links
757 758 'lk ls -F -o --color %l | grep ^l',
758 759 # directories or links to directories,
759 760 'ldir ls -F -o --color %l | grep /$',
760 761 # things which are executable
761 762 'lx ls -F -o --color %l | grep ^-..x',
762 763 )
763 764 # The BSDs don't ship GNU ls, so they don't understand the
764 765 # --color switch out of the box
765 766 if 'bsd' in sys.platform:
766 767 ls_extra = ( # ls normal files only
767 768 'lf ls -lF | grep ^-',
768 769 # ls symbolic links
769 770 'lk ls -lF | grep ^l',
770 771 # directories or links to directories,
771 772 'ldir ls -lF | grep /$',
772 773 # things which are executable
773 774 'lx ls -lF | grep ^-..x',
774 775 )
775 776 auto_alias = auto_alias + ls_extra
776 777 elif os.name in ['nt','dos']:
777 778 auto_alias = ('ls dir /on',
778 779 'ddir dir /ad /on', 'ldir dir /ad /on',
779 780 'mkdir mkdir','rmdir rmdir','echo echo',
780 781 'ren ren','cls cls','copy copy')
781 782 else:
782 783 auto_alias = ()
783 784 self.auto_alias = [s.split(None,1) for s in auto_alias]
784 785
785 786 # Produce a public API instance
786 787 self.api = ipapi.IPApi(self)
787 788
788 789 # Initialize all user-visible namespaces
789 790 self.init_namespaces()
790 791
791 792 # Call the actual (public) initializer
792 793 self.init_auto_alias()
793 794
794 795 # track which builtins we add, so we can clean up later
795 796 self.builtins_added = {}
796 797 # This method will add the necessary builtins for operation, but
797 798 # tracking what it did via the builtins_added dict.
798 799
799 800 #TODO: remove this, redundant
800 801 self.add_builtins()
801 802 # end __init__
802 803
803 804 def var_expand(self,cmd,depth=0):
804 805 """Expand python variables in a string.
805 806
806 807 The depth argument indicates how many frames above the caller should
807 808 be walked to look for the local namespace where to expand variables.
808 809
809 810 The global namespace for expansion is always the user's interactive
810 811 namespace.
811 812 """
812 813
813 814 return str(ItplNS(cmd,
814 815 self.user_ns, # globals
815 816 # Skip our own frame in searching for locals:
816 817 sys._getframe(depth+1).f_locals # locals
817 818 ))
818 819
819 820 def pre_config_initialization(self):
820 821 """Pre-configuration init method
821 822
822 823 This is called before the configuration files are processed to
823 824 prepare the services the config files might need.
824 825
825 826 self.rc already has reasonable default values at this point.
826 827 """
827 828 rc = self.rc
828 829 try:
829 830 self.db = pickleshare.PickleShareDB(rc.ipythondir + "/db")
830 831 except exceptions.UnicodeDecodeError:
831 832 print "Your ipythondir can't be decoded to unicode!"
832 833 print "Please set HOME environment variable to something that"
833 834 print r"only has ASCII characters, e.g. c:\home"
834 835 print "Now it is",rc.ipythondir
835 836 sys.exit()
836 837 self.shadowhist = IPython.core.history.ShadowHist(self.db)
837 838
838 839 def post_config_initialization(self):
839 840 """Post configuration init method
840 841
841 842 This is called after the configuration files have been processed to
842 843 'finalize' the initialization."""
843 844
844 845 rc = self.rc
845 846
846 847 # Object inspector
847 848 self.inspector = oinspect.Inspector(oinspect.InspectColors,
848 849 PyColorize.ANSICodeColors,
849 850 'NoColor',
850 851 rc.object_info_string_level)
851 852
852 853 self.rl_next_input = None
853 854 self.rl_do_indent = False
854 855 # Load readline proper
855 856 if rc.readline:
856 857 self.init_readline()
857 858
858 859 # local shortcut, this is used a LOT
859 860 self.log = self.logger.log
860 861
861 862 # Initialize cache, set in/out prompts and printing system
862 863 self.outputcache = CachedOutput(self,
863 864 rc.cache_size,
864 865 rc.pprint,
865 866 input_sep = rc.separate_in,
866 867 output_sep = rc.separate_out,
867 868 output_sep2 = rc.separate_out2,
868 869 ps1 = rc.prompt_in1,
869 870 ps2 = rc.prompt_in2,
870 871 ps_out = rc.prompt_out,
871 872 pad_left = rc.prompts_pad_left)
872 873
873 874 # user may have over-ridden the default print hook:
874 875 try:
875 876 self.outputcache.__class__.display = self.hooks.display
876 877 except AttributeError:
877 878 pass
878 879
879 880 # I don't like assigning globally to sys, because it means when
880 881 # embedding instances, each embedded instance overrides the previous
881 882 # choice. But sys.displayhook seems to be called internally by exec,
882 883 # so I don't see a way around it. We first save the original and then
883 884 # overwrite it.
884 885 self.sys_displayhook = sys.displayhook
885 886 sys.displayhook = self.outputcache
886 887
887 888 # Do a proper resetting of doctest, including the necessary displayhook
888 889 # monkeypatching
889 890 try:
890 891 doctest_reload()
891 892 except ImportError:
892 893 warn("doctest module does not exist.")
893 894
894 895 # Set user colors (don't do it in the constructor above so that it
895 896 # doesn't crash if colors option is invalid)
896 897 self.magic_colors(rc.colors)
897 898
898 899 # Set calling of pdb on exceptions
899 900 self.call_pdb = rc.pdb
900 901
901 902 # Load user aliases
902 903 for alias in rc.alias:
903 904 self.magic_alias(alias)
904 905
905 906 self.hooks.late_startup_hook()
906 907
907 908 for cmd in self.rc.autoexec:
908 909 #print "autoexec>",cmd #dbg
909 910 self.api.runlines(cmd)
910 911
911 912 batchrun = False
912 913 for batchfile in [path(arg) for arg in self.rc.args
913 914 if arg.lower().endswith('.ipy')]:
914 915 if not batchfile.isfile():
915 916 print "No such batch file:", batchfile
916 917 continue
917 918 self.api.runlines(batchfile.text())
918 919 batchrun = True
919 920 # without -i option, exit after running the batch file
920 921 if batchrun and not self.rc.interact:
921 922 self.ask_exit()
922 923
923 924 def init_namespaces(self):
924 925 """Initialize all user-visible namespaces to their minimum defaults.
925 926
926 927 Certain history lists are also initialized here, as they effectively
927 928 act as user namespaces.
928 929
929 930 Note
930 931 ----
931 932 All data structures here are only filled in, they are NOT reset by this
932 933 method. If they were not empty before, data will simply be added to
933 934 therm.
934 935 """
935 936 # The user namespace MUST have a pointer to the shell itself.
936 937 self.user_ns[self.name] = self
937 938
938 939 # Store the public api instance
939 940 self.user_ns['_ip'] = self.api
940 941
941 942 # make global variables for user access to the histories
942 943 self.user_ns['_ih'] = self.input_hist
943 944 self.user_ns['_oh'] = self.output_hist
944 945 self.user_ns['_dh'] = self.dir_hist
945 946
946 947 # user aliases to input and output histories
947 948 self.user_ns['In'] = self.input_hist
948 949 self.user_ns['Out'] = self.output_hist
949 950
950 951 self.user_ns['_sh'] = IPython.shadowns
951 952
952 953 # Fill the history zero entry, user counter starts at 1
953 954 self.input_hist.append('\n')
954 955 self.input_hist_raw.append('\n')
955 956
956 957 def add_builtins(self):
957 958 """Store ipython references into the builtin namespace.
958 959
959 960 Some parts of ipython operate via builtins injected here, which hold a
960 961 reference to IPython itself."""
961 962
962 963 # TODO: deprecate all of these, they are unsafe
963 964 builtins_new = dict(__IPYTHON__ = self,
964 965 ip_set_hook = self.set_hook,
965 966 jobs = self.jobs,
966 967 ipmagic = wrap_deprecated(self.ipmagic,'_ip.magic()'),
967 968 ipalias = wrap_deprecated(self.ipalias),
968 969 ipsystem = wrap_deprecated(self.ipsystem,'_ip.system()'),
969 970 #_ip = self.api
970 971 )
971 972 for biname,bival in builtins_new.items():
972 973 try:
973 974 # store the orignal value so we can restore it
974 975 self.builtins_added[biname] = __builtin__.__dict__[biname]
975 976 except KeyError:
976 977 # or mark that it wasn't defined, and we'll just delete it at
977 978 # cleanup
978 979 self.builtins_added[biname] = Undefined
979 980 __builtin__.__dict__[biname] = bival
980 981
981 982 # Keep in the builtins a flag for when IPython is active. We set it
982 983 # with setdefault so that multiple nested IPythons don't clobber one
983 984 # another. Each will increase its value by one upon being activated,
984 985 # which also gives us a way to determine the nesting level.
985 986 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
986 987
987 988 def clean_builtins(self):
988 989 """Remove any builtins which might have been added by add_builtins, or
989 990 restore overwritten ones to their previous values."""
990 991 for biname,bival in self.builtins_added.items():
991 992 if bival is Undefined:
992 993 del __builtin__.__dict__[biname]
993 994 else:
994 995 __builtin__.__dict__[biname] = bival
995 996 self.builtins_added.clear()
996 997
997 998 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
998 999 """set_hook(name,hook) -> sets an internal IPython hook.
999 1000
1000 1001 IPython exposes some of its internal API as user-modifiable hooks. By
1001 1002 adding your function to one of these hooks, you can modify IPython's
1002 1003 behavior to call at runtime your own routines."""
1003 1004
1004 1005 # At some point in the future, this should validate the hook before it
1005 1006 # accepts it. Probably at least check that the hook takes the number
1006 1007 # of args it's supposed to.
1007 1008
1008 1009 f = new.instancemethod(hook,self,self.__class__)
1009 1010
1010 1011 # check if the hook is for strdispatcher first
1011 1012 if str_key is not None:
1012 1013 sdp = self.strdispatchers.get(name, StrDispatch())
1013 1014 sdp.add_s(str_key, f, priority )
1014 1015 self.strdispatchers[name] = sdp
1015 1016 return
1016 1017 if re_key is not None:
1017 1018 sdp = self.strdispatchers.get(name, StrDispatch())
1018 1019 sdp.add_re(re.compile(re_key), f, priority )
1019 1020 self.strdispatchers[name] = sdp
1020 1021 return
1021 1022
1022 1023 dp = getattr(self.hooks, name, None)
1023 1024 if name not in IPython.core.hooks.__all__:
1024 1025 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
1025 1026 if not dp:
1026 1027 dp = IPython.core.hooks.CommandChainDispatcher()
1027 1028
1028 1029 try:
1029 1030 dp.add(f,priority)
1030 1031 except AttributeError:
1031 1032 # it was not commandchain, plain old func - replace
1032 1033 dp = f
1033 1034
1034 1035 setattr(self.hooks,name, dp)
1035 1036
1036 1037
1037 1038 #setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
1038 1039
1039 1040 def set_crash_handler(self,crashHandler):
1040 1041 """Set the IPython crash handler.
1041 1042
1042 1043 This must be a callable with a signature suitable for use as
1043 1044 sys.excepthook."""
1044 1045
1045 1046 # Install the given crash handler as the Python exception hook
1046 1047 sys.excepthook = crashHandler
1047 1048
1048 1049 # The instance will store a pointer to this, so that runtime code
1049 1050 # (such as magics) can access it. This is because during the
1050 1051 # read-eval loop, it gets temporarily overwritten (to deal with GUI
1051 1052 # frameworks).
1052 1053 self.sys_excepthook = sys.excepthook
1053 1054
1054 1055
1055 1056 def set_custom_exc(self,exc_tuple,handler):
1056 1057 """set_custom_exc(exc_tuple,handler)
1057 1058
1058 1059 Set a custom exception handler, which will be called if any of the
1059 1060 exceptions in exc_tuple occur in the mainloop (specifically, in the
1060 1061 runcode() method.
1061 1062
1062 1063 Inputs:
1063 1064
1064 1065 - exc_tuple: a *tuple* of valid exceptions to call the defined
1065 1066 handler for. It is very important that you use a tuple, and NOT A
1066 1067 LIST here, because of the way Python's except statement works. If
1067 1068 you only want to trap a single exception, use a singleton tuple:
1068 1069
1069 1070 exc_tuple == (MyCustomException,)
1070 1071
1071 1072 - handler: this must be defined as a function with the following
1072 1073 basic interface: def my_handler(self,etype,value,tb).
1073 1074
1074 1075 This will be made into an instance method (via new.instancemethod)
1075 1076 of IPython itself, and it will be called if any of the exceptions
1076 1077 listed in the exc_tuple are caught. If the handler is None, an
1077 1078 internal basic one is used, which just prints basic info.
1078 1079
1079 1080 WARNING: by putting in your own exception handler into IPython's main
1080 1081 execution loop, you run a very good chance of nasty crashes. This
1081 1082 facility should only be used if you really know what you are doing."""
1082 1083
1083 1084 assert type(exc_tuple)==type(()) , \
1084 1085 "The custom exceptions must be given AS A TUPLE."
1085 1086
1086 1087 def dummy_handler(self,etype,value,tb):
1087 1088 print '*** Simple custom exception handler ***'
1088 1089 print 'Exception type :',etype
1089 1090 print 'Exception value:',value
1090 1091 print 'Traceback :',tb
1091 1092 print 'Source code :','\n'.join(self.buffer)
1092 1093
1093 1094 if handler is None: handler = dummy_handler
1094 1095
1095 1096 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1096 1097 self.custom_exceptions = exc_tuple
1097 1098
1098 1099 def set_custom_completer(self,completer,pos=0):
1099 1100 """set_custom_completer(completer,pos=0)
1100 1101
1101 1102 Adds a new custom completer function.
1102 1103
1103 1104 The position argument (defaults to 0) is the index in the completers
1104 1105 list where you want the completer to be inserted."""
1105 1106
1106 1107 newcomp = new.instancemethod(completer,self.Completer,
1107 1108 self.Completer.__class__)
1108 1109 self.Completer.matchers.insert(pos,newcomp)
1109 1110
1110 1111 def set_completer(self):
1111 1112 """reset readline's completer to be our own."""
1112 1113 self.readline.set_completer(self.Completer.complete)
1113 1114
1114 1115 def _get_call_pdb(self):
1115 1116 return self._call_pdb
1116 1117
1117 1118 def _set_call_pdb(self,val):
1118 1119
1119 1120 if val not in (0,1,False,True):
1120 1121 raise ValueError,'new call_pdb value must be boolean'
1121 1122
1122 1123 # store value in instance
1123 1124 self._call_pdb = val
1124 1125
1125 1126 # notify the actual exception handlers
1126 1127 self.InteractiveTB.call_pdb = val
1127 1128 if self.isthreaded:
1128 1129 try:
1129 1130 self.sys_excepthook.call_pdb = val
1130 1131 except:
1131 1132 warn('Failed to activate pdb for threaded exception handler')
1132 1133
1133 1134 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1134 1135 'Control auto-activation of pdb at exceptions')
1135 1136
1136 1137 # These special functions get installed in the builtin namespace, to
1137 1138 # provide programmatic (pure python) access to magics, aliases and system
1138 1139 # calls. This is important for logging, user scripting, and more.
1139 1140
1140 1141 # We are basically exposing, via normal python functions, the three
1141 1142 # mechanisms in which ipython offers special call modes (magics for
1142 1143 # internal control, aliases for direct system access via pre-selected
1143 1144 # names, and !cmd for calling arbitrary system commands).
1144 1145
1145 1146 def ipmagic(self,arg_s):
1146 1147 """Call a magic function by name.
1147 1148
1148 1149 Input: a string containing the name of the magic function to call and any
1149 1150 additional arguments to be passed to the magic.
1150 1151
1151 1152 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
1152 1153 prompt:
1153 1154
1154 1155 In[1]: %name -opt foo bar
1155 1156
1156 1157 To call a magic without arguments, simply use ipmagic('name').
1157 1158
1158 1159 This provides a proper Python function to call IPython's magics in any
1159 1160 valid Python code you can type at the interpreter, including loops and
1160 1161 compound statements. It is added by IPython to the Python builtin
1161 1162 namespace upon initialization."""
1162 1163
1163 1164 args = arg_s.split(' ',1)
1164 1165 magic_name = args[0]
1165 1166 magic_name = magic_name.lstrip(self.ESC_MAGIC)
1166 1167
1167 1168 try:
1168 1169 magic_args = args[1]
1169 1170 except IndexError:
1170 1171 magic_args = ''
1171 1172 fn = getattr(self,'magic_'+magic_name,None)
1172 1173 if fn is None:
1173 1174 error("Magic function `%s` not found." % magic_name)
1174 1175 else:
1175 1176 magic_args = self.var_expand(magic_args,1)
1176 1177 return fn(magic_args)
1177 1178
1178 1179 def ipalias(self,arg_s):
1179 1180 """Call an alias by name.
1180 1181
1181 1182 Input: a string containing the name of the alias to call and any
1182 1183 additional arguments to be passed to the magic.
1183 1184
1184 1185 ipalias('name -opt foo bar') is equivalent to typing at the ipython
1185 1186 prompt:
1186 1187
1187 1188 In[1]: name -opt foo bar
1188 1189
1189 1190 To call an alias without arguments, simply use ipalias('name').
1190 1191
1191 1192 This provides a proper Python function to call IPython's aliases in any
1192 1193 valid Python code you can type at the interpreter, including loops and
1193 1194 compound statements. It is added by IPython to the Python builtin
1194 1195 namespace upon initialization."""
1195 1196
1196 1197 args = arg_s.split(' ',1)
1197 1198 alias_name = args[0]
1198 1199 try:
1199 1200 alias_args = args[1]
1200 1201 except IndexError:
1201 1202 alias_args = ''
1202 1203 if alias_name in self.alias_table:
1203 1204 self.call_alias(alias_name,alias_args)
1204 1205 else:
1205 1206 error("Alias `%s` not found." % alias_name)
1206 1207
1207 1208 def ipsystem(self,arg_s):
1208 1209 """Make a system call, using IPython."""
1209 1210
1210 1211 self.system(arg_s)
1211 1212
1212 1213 def complete(self,text):
1213 1214 """Return a sorted list of all possible completions on text.
1214 1215
1215 1216 Inputs:
1216 1217
1217 1218 - text: a string of text to be completed on.
1218 1219
1219 1220 This is a wrapper around the completion mechanism, similar to what
1220 1221 readline does at the command line when the TAB key is hit. By
1221 1222 exposing it as a method, it can be used by other non-readline
1222 1223 environments (such as GUIs) for text completion.
1223 1224
1224 1225 Simple usage example:
1225 1226
1226 1227 In [7]: x = 'hello'
1227 1228
1228 1229 In [8]: x
1229 1230 Out[8]: 'hello'
1230 1231
1231 1232 In [9]: print x
1232 1233 hello
1233 1234
1234 1235 In [10]: _ip.IP.complete('x.l')
1235 1236 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1236 1237 """
1237 1238
1238 1239 complete = self.Completer.complete
1239 1240 state = 0
1240 1241 # use a dict so we get unique keys, since ipyhton's multiple
1241 1242 # completers can return duplicates. When we make 2.4 a requirement,
1242 1243 # start using sets instead, which are faster.
1243 1244 comps = {}
1244 1245 while True:
1245 1246 newcomp = complete(text,state,line_buffer=text)
1246 1247 if newcomp is None:
1247 1248 break
1248 1249 comps[newcomp] = 1
1249 1250 state += 1
1250 1251 outcomps = comps.keys()
1251 1252 outcomps.sort()
1252 1253 #print "T:",text,"OC:",outcomps # dbg
1253 1254 #print "vars:",self.user_ns.keys()
1254 1255 return outcomps
1255 1256
1256 1257 def set_completer_frame(self, frame=None):
1257 1258 if frame:
1258 1259 self.Completer.namespace = frame.f_locals
1259 1260 self.Completer.global_namespace = frame.f_globals
1260 1261 else:
1261 1262 self.Completer.namespace = self.user_ns
1262 1263 self.Completer.global_namespace = self.user_global_ns
1263 1264
1264 1265 def init_auto_alias(self):
1265 1266 """Define some aliases automatically.
1266 1267
1267 1268 These are ALL parameter-less aliases"""
1268 1269
1269 1270 for alias,cmd in self.auto_alias:
1270 1271 self.getapi().defalias(alias,cmd)
1271 1272
1272 1273
1273 1274 def alias_table_validate(self,verbose=0):
1274 1275 """Update information about the alias table.
1275 1276
1276 1277 In particular, make sure no Python keywords/builtins are in it."""
1277 1278
1278 1279 no_alias = self.no_alias
1279 1280 for k in self.alias_table.keys():
1280 1281 if k in no_alias:
1281 1282 del self.alias_table[k]
1282 1283 if verbose:
1283 1284 print ("Deleting alias <%s>, it's a Python "
1284 1285 "keyword or builtin." % k)
1285 1286
1286 1287 def set_autoindent(self,value=None):
1287 1288 """Set the autoindent flag, checking for readline support.
1288 1289
1289 1290 If called with no arguments, it acts as a toggle."""
1290 1291
1291 1292 if not self.has_readline:
1292 1293 if os.name == 'posix':
1293 1294 warn("The auto-indent feature requires the readline library")
1294 1295 self.autoindent = 0
1295 1296 return
1296 1297 if value is None:
1297 1298 self.autoindent = not self.autoindent
1298 1299 else:
1299 1300 self.autoindent = value
1300 1301
1301 1302 def rc_set_toggle(self,rc_field,value=None):
1302 1303 """Set or toggle a field in IPython's rc config. structure.
1303 1304
1304 1305 If called with no arguments, it acts as a toggle.
1305 1306
1306 1307 If called with a non-existent field, the resulting AttributeError
1307 1308 exception will propagate out."""
1308 1309
1309 1310 rc_val = getattr(self.rc,rc_field)
1310 1311 if value is None:
1311 1312 value = not rc_val
1312 1313 setattr(self.rc,rc_field,value)
1313 1314
1314 1315 def user_setup(self,ipythondir,rc_suffix,mode='install'):
1315 1316 """Install the user configuration directory.
1316 1317
1317 1318 Note
1318 1319 ----
1319 1320 DEPRECATED: use the top-level user_setup() function instead.
1320 1321 """
1321 1322 return user_setup(ipythondir,rc_suffix,mode)
1322 1323
1323 1324 def atexit_operations(self):
1324 1325 """This will be executed at the time of exit.
1325 1326
1326 1327 Saving of persistent data should be performed here. """
1327 1328
1328 1329 #print '*** IPython exit cleanup ***' # dbg
1329 1330 # input history
1330 1331 self.savehist()
1331 1332
1332 1333 # Cleanup all tempfiles left around
1333 1334 for tfile in self.tempfiles:
1334 1335 try:
1335 1336 os.unlink(tfile)
1336 1337 except OSError:
1337 1338 pass
1338 1339
1339 1340 # Clear all user namespaces to release all references cleanly.
1340 1341 self.reset()
1341 1342
1342 1343 # Run user hooks
1343 1344 self.hooks.shutdown_hook()
1344 1345
1345 1346 def reset(self):
1346 1347 """Clear all internal namespaces.
1347 1348
1348 1349 Note that this is much more aggressive than %reset, since it clears
1349 1350 fully all namespaces, as well as all input/output lists.
1350 1351 """
1351 1352 for ns in self.ns_refs_table:
1352 1353 ns.clear()
1353 1354
1354 1355 # Clear input and output histories
1355 1356 self.input_hist[:] = []
1356 1357 self.input_hist_raw[:] = []
1357 1358 self.output_hist.clear()
1358 1359 # Restore the user namespaces to minimal usability
1359 1360 self.init_namespaces()
1360 1361
1361 1362 def savehist(self):
1362 1363 """Save input history to a file (via readline library)."""
1363 1364
1364 1365 if not self.has_readline:
1365 1366 return
1366 1367
1367 1368 try:
1368 1369 self.readline.write_history_file(self.histfile)
1369 1370 except:
1370 1371 print 'Unable to save IPython command history to file: ' + \
1371 1372 `self.histfile`
1372 1373
1373 1374 def reloadhist(self):
1374 1375 """Reload the input history from disk file."""
1375 1376
1376 1377 if self.has_readline:
1377 1378 try:
1378 1379 self.readline.clear_history()
1379 1380 self.readline.read_history_file(self.shell.histfile)
1380 1381 except AttributeError:
1381 1382 pass
1382 1383
1383 1384
1384 1385 def history_saving_wrapper(self, func):
1385 1386 """ Wrap func for readline history saving
1386 1387
1387 1388 Convert func into callable that saves & restores
1388 1389 history around the call """
1389 1390
1390 1391 if not self.has_readline:
1391 1392 return func
1392 1393
1393 1394 def wrapper():
1394 1395 self.savehist()
1395 1396 try:
1396 1397 func()
1397 1398 finally:
1398 1399 readline.read_history_file(self.histfile)
1399 1400 return wrapper
1400 1401
1401 1402 def pre_readline(self):
1402 1403 """readline hook to be used at the start of each line.
1403 1404
1404 1405 Currently it handles auto-indent only."""
1405 1406
1406 1407 #debugx('self.indent_current_nsp','pre_readline:')
1407 1408
1408 1409 if self.rl_do_indent:
1409 1410 self.readline.insert_text(self.indent_current_str())
1410 1411 if self.rl_next_input is not None:
1411 1412 self.readline.insert_text(self.rl_next_input)
1412 1413 self.rl_next_input = None
1413 1414
1414 1415 def init_readline(self):
1415 1416 """Command history completion/saving/reloading."""
1416 1417
1417 1418
1418 1419 import IPython.rlineimpl as readline
1419 1420
1420 1421 if not readline.have_readline:
1421 1422 self.has_readline = 0
1422 1423 self.readline = None
1423 1424 # no point in bugging windows users with this every time:
1424 1425 warn('Readline services not available on this platform.')
1425 1426 else:
1426 1427 sys.modules['readline'] = readline
1427 1428 import atexit
1428 1429 from IPython.core.completer import IPCompleter
1429 1430 self.Completer = IPCompleter(self,
1430 1431 self.user_ns,
1431 1432 self.user_global_ns,
1432 1433 self.rc.readline_omit__names,
1433 1434 self.alias_table)
1434 1435 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1435 1436 self.strdispatchers['complete_command'] = sdisp
1436 1437 self.Completer.custom_completers = sdisp
1437 1438 # Platform-specific configuration
1438 1439 if os.name == 'nt':
1439 1440 self.readline_startup_hook = readline.set_pre_input_hook
1440 1441 else:
1441 1442 self.readline_startup_hook = readline.set_startup_hook
1442 1443
1443 1444 # Load user's initrc file (readline config)
1444 1445 # Or if libedit is used, load editrc.
1445 1446 inputrc_name = os.environ.get('INPUTRC')
1446 1447 if inputrc_name is None:
1447 1448 home_dir = get_home_dir()
1448 1449 if home_dir is not None:
1449 1450 inputrc_name = '.inputrc'
1450 1451 if readline.uses_libedit:
1451 1452 inputrc_name = '.editrc'
1452 1453 inputrc_name = os.path.join(home_dir, inputrc_name)
1453 1454 if os.path.isfile(inputrc_name):
1454 1455 try:
1455 1456 readline.read_init_file(inputrc_name)
1456 1457 except:
1457 1458 warn('Problems reading readline initialization file <%s>'
1458 1459 % inputrc_name)
1459 1460
1460 1461 self.has_readline = 1
1461 1462 self.readline = readline
1462 1463 # save this in sys so embedded copies can restore it properly
1463 1464 sys.ipcompleter = self.Completer.complete
1464 1465 self.set_completer()
1465 1466
1466 1467 # Configure readline according to user's prefs
1467 1468 # This is only done if GNU readline is being used. If libedit
1468 1469 # is being used (as on Leopard) the readline config is
1469 1470 # not run as the syntax for libedit is different.
1470 1471 if not readline.uses_libedit:
1471 1472 for rlcommand in self.rc.readline_parse_and_bind:
1472 1473 #print "loading rl:",rlcommand # dbg
1473 1474 readline.parse_and_bind(rlcommand)
1474 1475
1475 1476 # Remove some chars from the delimiters list. If we encounter
1476 1477 # unicode chars, discard them.
1477 1478 delims = readline.get_completer_delims().encode("ascii", "ignore")
1478 1479 delims = delims.translate(string._idmap,
1479 1480 self.rc.readline_remove_delims)
1480 1481 readline.set_completer_delims(delims)
1481 1482 # otherwise we end up with a monster history after a while:
1482 1483 readline.set_history_length(1000)
1483 1484 try:
1484 1485 #print '*** Reading readline history' # dbg
1485 1486 readline.read_history_file(self.histfile)
1486 1487 except IOError:
1487 1488 pass # It doesn't exist yet.
1488 1489
1489 1490 atexit.register(self.atexit_operations)
1490 1491 del atexit
1491 1492
1492 1493 # Configure auto-indent for all platforms
1493 1494 self.set_autoindent(self.rc.autoindent)
1494 1495
1495 1496 def ask_yes_no(self,prompt,default=True):
1496 1497 if self.rc.quiet:
1497 1498 return True
1498 1499 return ask_yes_no(prompt,default)
1499 1500
1500 1501 def new_main_mod(self,ns=None):
1501 1502 """Return a new 'main' module object for user code execution.
1502 1503 """
1503 1504 main_mod = self._user_main_module
1504 1505 init_fakemod_dict(main_mod,ns)
1505 1506 return main_mod
1506 1507
1507 1508 def cache_main_mod(self,ns,fname):
1508 1509 """Cache a main module's namespace.
1509 1510
1510 1511 When scripts are executed via %run, we must keep a reference to the
1511 1512 namespace of their __main__ module (a FakeModule instance) around so
1512 1513 that Python doesn't clear it, rendering objects defined therein
1513 1514 useless.
1514 1515
1515 1516 This method keeps said reference in a private dict, keyed by the
1516 1517 absolute path of the module object (which corresponds to the script
1517 1518 path). This way, for multiple executions of the same script we only
1518 1519 keep one copy of the namespace (the last one), thus preventing memory
1519 1520 leaks from old references while allowing the objects from the last
1520 1521 execution to be accessible.
1521 1522
1522 1523 Note: we can not allow the actual FakeModule instances to be deleted,
1523 1524 because of how Python tears down modules (it hard-sets all their
1524 1525 references to None without regard for reference counts). This method
1525 1526 must therefore make a *copy* of the given namespace, to allow the
1526 1527 original module's __dict__ to be cleared and reused.
1527 1528
1528 1529
1529 1530 Parameters
1530 1531 ----------
1531 1532 ns : a namespace (a dict, typically)
1532 1533
1533 1534 fname : str
1534 1535 Filename associated with the namespace.
1535 1536
1536 1537 Examples
1537 1538 --------
1538 1539
1539 1540 In [10]: import IPython
1540 1541
1541 1542 In [11]: _ip.IP.cache_main_mod(IPython.__dict__,IPython.__file__)
1542 1543
1543 1544 In [12]: IPython.__file__ in _ip.IP._main_ns_cache
1544 1545 Out[12]: True
1545 1546 """
1546 1547 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
1547 1548
1548 1549 def clear_main_mod_cache(self):
1549 1550 """Clear the cache of main modules.
1550 1551
1551 1552 Mainly for use by utilities like %reset.
1552 1553
1553 1554 Examples
1554 1555 --------
1555 1556
1556 1557 In [15]: import IPython
1557 1558
1558 1559 In [16]: _ip.IP.cache_main_mod(IPython.__dict__,IPython.__file__)
1559 1560
1560 1561 In [17]: len(_ip.IP._main_ns_cache) > 0
1561 1562 Out[17]: True
1562 1563
1563 1564 In [18]: _ip.IP.clear_main_mod_cache()
1564 1565
1565 1566 In [19]: len(_ip.IP._main_ns_cache) == 0
1566 1567 Out[19]: True
1567 1568 """
1568 1569 self._main_ns_cache.clear()
1569 1570
1570 1571 def _should_recompile(self,e):
1571 1572 """Utility routine for edit_syntax_error"""
1572 1573
1573 1574 if e.filename in ('<ipython console>','<input>','<string>',
1574 1575 '<console>','<BackgroundJob compilation>',
1575 1576 None):
1576 1577
1577 1578 return False
1578 1579 try:
1579 1580 if (self.rc.autoedit_syntax and
1580 1581 not self.ask_yes_no('Return to editor to correct syntax error? '
1581 1582 '[Y/n] ','y')):
1582 1583 return False
1583 1584 except EOFError:
1584 1585 return False
1585 1586
1586 1587 def int0(x):
1587 1588 try:
1588 1589 return int(x)
1589 1590 except TypeError:
1590 1591 return 0
1591 1592 # always pass integer line and offset values to editor hook
1592 1593 try:
1593 1594 self.hooks.fix_error_editor(e.filename,
1594 1595 int0(e.lineno),int0(e.offset),e.msg)
1595 1596 except ipapi.TryNext:
1596 1597 warn('Could not open editor')
1597 1598 return False
1598 1599 return True
1599 1600
1600 1601 def edit_syntax_error(self):
1601 1602 """The bottom half of the syntax error handler called in the main loop.
1602 1603
1603 1604 Loop until syntax error is fixed or user cancels.
1604 1605 """
1605 1606
1606 1607 while self.SyntaxTB.last_syntax_error:
1607 1608 # copy and clear last_syntax_error
1608 1609 err = self.SyntaxTB.clear_err_state()
1609 1610 if not self._should_recompile(err):
1610 1611 return
1611 1612 try:
1612 1613 # may set last_syntax_error again if a SyntaxError is raised
1613 1614 self.safe_execfile(err.filename,self.user_ns)
1614 1615 except:
1615 1616 self.showtraceback()
1616 1617 else:
1617 1618 try:
1618 1619 f = file(err.filename)
1619 1620 try:
1620 1621 sys.displayhook(f.read())
1621 1622 finally:
1622 1623 f.close()
1623 1624 except:
1624 1625 self.showtraceback()
1625 1626
1626 1627 def showsyntaxerror(self, filename=None):
1627 1628 """Display the syntax error that just occurred.
1628 1629
1629 1630 This doesn't display a stack trace because there isn't one.
1630 1631
1631 1632 If a filename is given, it is stuffed in the exception instead
1632 1633 of what was there before (because Python's parser always uses
1633 1634 "<string>" when reading from a string).
1634 1635 """
1635 1636 etype, value, last_traceback = sys.exc_info()
1636 1637
1637 1638 # See note about these variables in showtraceback() below
1638 1639 sys.last_type = etype
1639 1640 sys.last_value = value
1640 1641 sys.last_traceback = last_traceback
1641 1642
1642 1643 if filename and etype is SyntaxError:
1643 1644 # Work hard to stuff the correct filename in the exception
1644 1645 try:
1645 1646 msg, (dummy_filename, lineno, offset, line) = value
1646 1647 except:
1647 1648 # Not the format we expect; leave it alone
1648 1649 pass
1649 1650 else:
1650 1651 # Stuff in the right filename
1651 1652 try:
1652 1653 # Assume SyntaxError is a class exception
1653 1654 value = SyntaxError(msg, (filename, lineno, offset, line))
1654 1655 except:
1655 1656 # If that failed, assume SyntaxError is a string
1656 1657 value = msg, (filename, lineno, offset, line)
1657 1658 self.SyntaxTB(etype,value,[])
1658 1659
1659 1660 def debugger(self,force=False):
1660 1661 """Call the pydb/pdb debugger.
1661 1662
1662 1663 Keywords:
1663 1664
1664 1665 - force(False): by default, this routine checks the instance call_pdb
1665 1666 flag and does not actually invoke the debugger if the flag is false.
1666 1667 The 'force' option forces the debugger to activate even if the flag
1667 1668 is false.
1668 1669 """
1669 1670
1670 1671 if not (force or self.call_pdb):
1671 1672 return
1672 1673
1673 1674 if not hasattr(sys,'last_traceback'):
1674 1675 error('No traceback has been produced, nothing to debug.')
1675 1676 return
1676 1677
1677 1678 # use pydb if available
1678 1679 if debugger.has_pydb:
1679 1680 from pydb import pm
1680 1681 else:
1681 1682 # fallback to our internal debugger
1682 1683 pm = lambda : self.InteractiveTB.debugger(force=True)
1683 1684 self.history_saving_wrapper(pm)()
1684 1685
1685 1686 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1686 1687 """Display the exception that just occurred.
1687 1688
1688 1689 If nothing is known about the exception, this is the method which
1689 1690 should be used throughout the code for presenting user tracebacks,
1690 1691 rather than directly invoking the InteractiveTB object.
1691 1692
1692 1693 A specific showsyntaxerror() also exists, but this method can take
1693 1694 care of calling it if needed, so unless you are explicitly catching a
1694 1695 SyntaxError exception, don't try to analyze the stack manually and
1695 1696 simply call this method."""
1696 1697
1697 1698
1698 1699 # Though this won't be called by syntax errors in the input line,
1699 1700 # there may be SyntaxError cases whith imported code.
1700 1701
1701 1702 try:
1702 1703 if exc_tuple is None:
1703 1704 etype, value, tb = sys.exc_info()
1704 1705 else:
1705 1706 etype, value, tb = exc_tuple
1706 1707
1707 1708 if etype is SyntaxError:
1708 1709 self.showsyntaxerror(filename)
1709 1710 elif etype is ipapi.UsageError:
1710 1711 print "UsageError:", value
1711 1712 else:
1712 1713 # WARNING: these variables are somewhat deprecated and not
1713 1714 # necessarily safe to use in a threaded environment, but tools
1714 1715 # like pdb depend on their existence, so let's set them. If we
1715 1716 # find problems in the field, we'll need to revisit their use.
1716 1717 sys.last_type = etype
1717 1718 sys.last_value = value
1718 1719 sys.last_traceback = tb
1719 1720
1720 1721 if etype in self.custom_exceptions:
1721 1722 self.CustomTB(etype,value,tb)
1722 1723 else:
1723 1724 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1724 1725 if self.InteractiveTB.call_pdb and self.has_readline:
1725 1726 # pdb mucks up readline, fix it back
1726 1727 self.set_completer()
1727 1728 except KeyboardInterrupt:
1728 1729 self.write("\nKeyboardInterrupt\n")
1729 1730
1730 1731 def mainloop(self,banner=None):
1731 1732 """Creates the local namespace and starts the mainloop.
1732 1733
1733 1734 If an optional banner argument is given, it will override the
1734 1735 internally created default banner."""
1735 1736
1736 1737 if self.rc.c: # Emulate Python's -c option
1737 1738 self.exec_init_cmd()
1738 1739 if banner is None:
1739 1740 if not self.rc.banner:
1740 1741 banner = ''
1741 1742 # banner is string? Use it directly!
1742 1743 elif isinstance(self.rc.banner,basestring):
1743 1744 banner = self.rc.banner
1744 1745 else:
1745 1746 banner = self.BANNER+self.banner2
1746 1747
1747 1748 # if you run stuff with -c <cmd>, raw hist is not updated
1748 1749 # ensure that it's in sync
1749 1750 if len(self.input_hist) != len (self.input_hist_raw):
1750 1751 self.input_hist_raw = InputList(self.input_hist)
1751 1752
1752 1753 while 1:
1753 1754 try:
1754 1755 self.interact(banner)
1755 1756 #self.interact_with_readline()
1756 1757
1757 1758 # XXX for testing of a readline-decoupled repl loop, call
1758 1759 # interact_with_readline above
1759 1760
1760 1761 break
1761 1762 except KeyboardInterrupt:
1762 1763 # this should not be necessary, but KeyboardInterrupt
1763 1764 # handling seems rather unpredictable...
1764 1765 self.write("\nKeyboardInterrupt in interact()\n")
1765 1766
1766 1767 def exec_init_cmd(self):
1767 1768 """Execute a command given at the command line.
1768 1769
1769 1770 This emulates Python's -c option."""
1770 1771
1771 1772 #sys.argv = ['-c']
1772 1773 self.push(self.prefilter(self.rc.c, False))
1773 1774 if not self.rc.interact:
1774 1775 self.ask_exit()
1775 1776
1776 1777 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1777 1778 """Embeds IPython into a running python program.
1778 1779
1779 1780 Input:
1780 1781
1781 1782 - header: An optional header message can be specified.
1782 1783
1783 1784 - local_ns, global_ns: working namespaces. If given as None, the
1784 1785 IPython-initialized one is updated with __main__.__dict__, so that
1785 1786 program variables become visible but user-specific configuration
1786 1787 remains possible.
1787 1788
1788 1789 - stack_depth: specifies how many levels in the stack to go to
1789 1790 looking for namespaces (when local_ns and global_ns are None). This
1790 1791 allows an intermediate caller to make sure that this function gets
1791 1792 the namespace from the intended level in the stack. By default (0)
1792 1793 it will get its locals and globals from the immediate caller.
1793 1794
1794 1795 Warning: it's possible to use this in a program which is being run by
1795 1796 IPython itself (via %run), but some funny things will happen (a few
1796 1797 globals get overwritten). In the future this will be cleaned up, as
1797 1798 there is no fundamental reason why it can't work perfectly."""
1798 1799
1799 1800 # Get locals and globals from caller
1800 1801 if local_ns is None or global_ns is None:
1801 1802 call_frame = sys._getframe(stack_depth).f_back
1802 1803
1803 1804 if local_ns is None:
1804 1805 local_ns = call_frame.f_locals
1805 1806 if global_ns is None:
1806 1807 global_ns = call_frame.f_globals
1807 1808
1808 1809 # Update namespaces and fire up interpreter
1809 1810
1810 1811 # The global one is easy, we can just throw it in
1811 1812 self.user_global_ns = global_ns
1812 1813
1813 1814 # but the user/local one is tricky: ipython needs it to store internal
1814 1815 # data, but we also need the locals. We'll copy locals in the user
1815 1816 # one, but will track what got copied so we can delete them at exit.
1816 1817 # This is so that a later embedded call doesn't see locals from a
1817 1818 # previous call (which most likely existed in a separate scope).
1818 1819 local_varnames = local_ns.keys()
1819 1820 self.user_ns.update(local_ns)
1820 1821 #self.user_ns['local_ns'] = local_ns # dbg
1821 1822
1822 1823 # Patch for global embedding to make sure that things don't overwrite
1823 1824 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1824 1825 # FIXME. Test this a bit more carefully (the if.. is new)
1825 1826 if local_ns is None and global_ns is None:
1826 1827 self.user_global_ns.update(__main__.__dict__)
1827 1828
1828 1829 # make sure the tab-completer has the correct frame information, so it
1829 1830 # actually completes using the frame's locals/globals
1830 1831 self.set_completer_frame()
1831 1832
1832 1833 # before activating the interactive mode, we need to make sure that
1833 1834 # all names in the builtin namespace needed by ipython point to
1834 1835 # ourselves, and not to other instances.
1835 1836 self.add_builtins()
1836 1837
1837 1838 self.interact(header)
1838 1839
1839 1840 # now, purge out the user namespace from anything we might have added
1840 1841 # from the caller's local namespace
1841 1842 delvar = self.user_ns.pop
1842 1843 for var in local_varnames:
1843 1844 delvar(var,None)
1844 1845 # and clean builtins we may have overridden
1845 1846 self.clean_builtins()
1846 1847
1847 1848 def interact_prompt(self):
1848 1849 """ Print the prompt (in read-eval-print loop)
1849 1850
1850 1851 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1851 1852 used in standard IPython flow.
1852 1853 """
1853 1854 if self.more:
1854 1855 try:
1855 1856 prompt = self.hooks.generate_prompt(True)
1856 1857 except:
1857 1858 self.showtraceback()
1858 1859 if self.autoindent:
1859 1860 self.rl_do_indent = True
1860 1861
1861 1862 else:
1862 1863 try:
1863 1864 prompt = self.hooks.generate_prompt(False)
1864 1865 except:
1865 1866 self.showtraceback()
1866 1867 self.write(prompt)
1867 1868
1868 1869 def interact_handle_input(self,line):
1869 1870 """ Handle the input line (in read-eval-print loop)
1870 1871
1871 1872 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1872 1873 used in standard IPython flow.
1873 1874 """
1874 1875 if line.lstrip() == line:
1875 1876 self.shadowhist.add(line.strip())
1876 1877 lineout = self.prefilter(line,self.more)
1877 1878
1878 1879 if line.strip():
1879 1880 if self.more:
1880 1881 self.input_hist_raw[-1] += '%s\n' % line
1881 1882 else:
1882 1883 self.input_hist_raw.append('%s\n' % line)
1883 1884
1884 1885
1885 1886 self.more = self.push(lineout)
1886 1887 if (self.SyntaxTB.last_syntax_error and
1887 1888 self.rc.autoedit_syntax):
1888 1889 self.edit_syntax_error()
1889 1890
1890 1891 def interact_with_readline(self):
1891 1892 """ Demo of using interact_handle_input, interact_prompt
1892 1893
1893 1894 This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
1894 1895 it should work like this.
1895 1896 """
1896 1897 self.readline_startup_hook(self.pre_readline)
1897 1898 while not self.exit_now:
1898 1899 self.interact_prompt()
1899 1900 if self.more:
1900 1901 self.rl_do_indent = True
1901 1902 else:
1902 1903 self.rl_do_indent = False
1903 1904 line = raw_input_original().decode(self.stdin_encoding)
1904 1905 self.interact_handle_input(line)
1905 1906
1906 1907
1907 1908 def interact(self, banner=None):
1908 1909 """Closely emulate the interactive Python console.
1909 1910
1910 1911 The optional banner argument specify the banner to print
1911 1912 before the first interaction; by default it prints a banner
1912 1913 similar to the one printed by the real Python interpreter,
1913 1914 followed by the current class name in parentheses (so as not
1914 1915 to confuse this with the real interpreter -- since it's so
1915 1916 close!).
1916 1917
1917 1918 """
1918 1919
1919 1920 if self.exit_now:
1920 1921 # batch run -> do not interact
1921 1922 return
1922 1923 cprt = 'Type "copyright", "credits" or "license" for more information.'
1923 1924 if banner is None:
1924 1925 self.write("Python %s on %s\n%s\n(%s)\n" %
1925 1926 (sys.version, sys.platform, cprt,
1926 1927 self.__class__.__name__))
1927 1928 else:
1928 1929 self.write(banner)
1929 1930
1930 1931 more = 0
1931 1932
1932 1933 # Mark activity in the builtins
1933 1934 __builtin__.__dict__['__IPYTHON__active'] += 1
1934 1935
1935 1936 if self.has_readline:
1936 1937 self.readline_startup_hook(self.pre_readline)
1937 1938 # exit_now is set by a call to %Exit or %Quit, through the
1938 1939 # ask_exit callback.
1939 1940
1940 1941 while not self.exit_now:
1941 1942 self.hooks.pre_prompt_hook()
1942 1943 if more:
1943 1944 try:
1944 1945 prompt = self.hooks.generate_prompt(True)
1945 1946 except:
1946 1947 self.showtraceback()
1947 1948 if self.autoindent:
1948 1949 self.rl_do_indent = True
1949 1950
1950 1951 else:
1951 1952 try:
1952 1953 prompt = self.hooks.generate_prompt(False)
1953 1954 except:
1954 1955 self.showtraceback()
1955 1956 try:
1956 1957 line = self.raw_input(prompt,more)
1957 1958 if self.exit_now:
1958 1959 # quick exit on sys.std[in|out] close
1959 1960 break
1960 1961 if self.autoindent:
1961 1962 self.rl_do_indent = False
1962 1963
1963 1964 except KeyboardInterrupt:
1964 1965 #double-guard against keyboardinterrupts during kbdint handling
1965 1966 try:
1966 1967 self.write('\nKeyboardInterrupt\n')
1967 1968 self.resetbuffer()
1968 1969 # keep cache in sync with the prompt counter:
1969 1970 self.outputcache.prompt_count -= 1
1970 1971
1971 1972 if self.autoindent:
1972 1973 self.indent_current_nsp = 0
1973 1974 more = 0
1974 1975 except KeyboardInterrupt:
1975 1976 pass
1976 1977 except EOFError:
1977 1978 if self.autoindent:
1978 1979 self.rl_do_indent = False
1979 1980 self.readline_startup_hook(None)
1980 1981 self.write('\n')
1981 1982 self.exit()
1982 1983 except bdb.BdbQuit:
1983 1984 warn('The Python debugger has exited with a BdbQuit exception.\n'
1984 1985 'Because of how pdb handles the stack, it is impossible\n'
1985 1986 'for IPython to properly format this particular exception.\n'
1986 1987 'IPython will resume normal operation.')
1987 1988 except:
1988 1989 # exceptions here are VERY RARE, but they can be triggered
1989 1990 # asynchronously by signal handlers, for example.
1990 1991 self.showtraceback()
1991 1992 else:
1992 1993 more = self.push(line)
1993 1994 if (self.SyntaxTB.last_syntax_error and
1994 1995 self.rc.autoedit_syntax):
1995 1996 self.edit_syntax_error()
1996 1997
1997 1998 # We are off again...
1998 1999 __builtin__.__dict__['__IPYTHON__active'] -= 1
1999 2000
2000 2001 def excepthook(self, etype, value, tb):
2001 2002 """One more defense for GUI apps that call sys.excepthook.
2002 2003
2003 2004 GUI frameworks like wxPython trap exceptions and call
2004 2005 sys.excepthook themselves. I guess this is a feature that
2005 2006 enables them to keep running after exceptions that would
2006 2007 otherwise kill their mainloop. This is a bother for IPython
2007 2008 which excepts to catch all of the program exceptions with a try:
2008 2009 except: statement.
2009 2010
2010 2011 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
2011 2012 any app directly invokes sys.excepthook, it will look to the user like
2012 2013 IPython crashed. In order to work around this, we can disable the
2013 2014 CrashHandler and replace it with this excepthook instead, which prints a
2014 2015 regular traceback using our InteractiveTB. In this fashion, apps which
2015 2016 call sys.excepthook will generate a regular-looking exception from
2016 2017 IPython, and the CrashHandler will only be triggered by real IPython
2017 2018 crashes.
2018 2019
2019 2020 This hook should be used sparingly, only in places which are not likely
2020 2021 to be true IPython errors.
2021 2022 """
2022 2023 self.showtraceback((etype,value,tb),tb_offset=0)
2023 2024
2024 2025 def expand_aliases(self,fn,rest):
2025 2026 """ Expand multiple levels of aliases:
2026 2027
2027 2028 if:
2028 2029
2029 2030 alias foo bar /tmp
2030 2031 alias baz foo
2031 2032
2032 2033 then:
2033 2034
2034 2035 baz huhhahhei -> bar /tmp huhhahhei
2035 2036
2036 2037 """
2037 2038 line = fn + " " + rest
2038 2039
2039 2040 done = set()
2040 2041 while 1:
2041 2042 pre,fn,rest = prefilter.splitUserInput(line,
2042 2043 prefilter.shell_line_split)
2043 2044 if fn in self.alias_table:
2044 2045 if fn in done:
2045 2046 warn("Cyclic alias definition, repeated '%s'" % fn)
2046 2047 return ""
2047 2048 done.add(fn)
2048 2049
2049 2050 l2 = self.transform_alias(fn,rest)
2050 2051 # dir -> dir
2051 2052 # print "alias",line, "->",l2 #dbg
2052 2053 if l2 == line:
2053 2054 break
2054 2055 # ls -> ls -F should not recurse forever
2055 2056 if l2.split(None,1)[0] == line.split(None,1)[0]:
2056 2057 line = l2
2057 2058 break
2058 2059
2059 2060 line=l2
2060 2061
2061 2062
2062 2063 # print "al expand to",line #dbg
2063 2064 else:
2064 2065 break
2065 2066
2066 2067 return line
2067 2068
2068 2069 def transform_alias(self, alias,rest=''):
2069 2070 """ Transform alias to system command string.
2070 2071 """
2071 2072 trg = self.alias_table[alias]
2072 2073
2073 2074 nargs,cmd = trg
2074 2075 # print trg #dbg
2075 2076 if ' ' in cmd and os.path.isfile(cmd):
2076 2077 cmd = '"%s"' % cmd
2077 2078
2078 2079 # Expand the %l special to be the user's input line
2079 2080 if cmd.find('%l') >= 0:
2080 2081 cmd = cmd.replace('%l',rest)
2081 2082 rest = ''
2082 2083 if nargs==0:
2083 2084 # Simple, argument-less aliases
2084 2085 cmd = '%s %s' % (cmd,rest)
2085 2086 else:
2086 2087 # Handle aliases with positional arguments
2087 2088 args = rest.split(None,nargs)
2088 2089 if len(args)< nargs:
2089 2090 error('Alias <%s> requires %s arguments, %s given.' %
2090 2091 (alias,nargs,len(args)))
2091 2092 return None
2092 2093 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
2093 2094 # Now call the macro, evaluating in the user's namespace
2094 2095 #print 'new command: <%r>' % cmd # dbg
2095 2096 return cmd
2096 2097
2097 2098 def call_alias(self,alias,rest=''):
2098 2099 """Call an alias given its name and the rest of the line.
2099 2100
2100 2101 This is only used to provide backwards compatibility for users of
2101 2102 ipalias(), use of which is not recommended for anymore."""
2102 2103
2103 2104 # Now call the macro, evaluating in the user's namespace
2104 2105 cmd = self.transform_alias(alias, rest)
2105 2106 try:
2106 2107 self.system(cmd)
2107 2108 except:
2108 2109 self.showtraceback()
2109 2110
2110 2111 def indent_current_str(self):
2111 2112 """return the current level of indentation as a string"""
2112 2113 return self.indent_current_nsp * ' '
2113 2114
2114 2115 def autoindent_update(self,line):
2115 2116 """Keep track of the indent level."""
2116 2117
2117 2118 #debugx('line')
2118 2119 #debugx('self.indent_current_nsp')
2119 2120 if self.autoindent:
2120 2121 if line:
2121 2122 inisp = num_ini_spaces(line)
2122 2123 if inisp < self.indent_current_nsp:
2123 2124 self.indent_current_nsp = inisp
2124 2125
2125 2126 if line[-1] == ':':
2126 2127 self.indent_current_nsp += 4
2127 2128 elif dedent_re.match(line):
2128 2129 self.indent_current_nsp -= 4
2129 2130 else:
2130 2131 self.indent_current_nsp = 0
2131 2132
2132 2133 def runlines(self,lines):
2133 2134 """Run a string of one or more lines of source.
2134 2135
2135 2136 This method is capable of running a string containing multiple source
2136 2137 lines, as if they had been entered at the IPython prompt. Since it
2137 2138 exposes IPython's processing machinery, the given strings can contain
2138 2139 magic calls (%magic), special shell access (!cmd), etc."""
2139 2140
2140 2141 # We must start with a clean buffer, in case this is run from an
2141 2142 # interactive IPython session (via a magic, for example).
2142 2143 self.resetbuffer()
2143 2144 lines = lines.split('\n')
2144 2145 more = 0
2145 2146
2146 2147 for line in lines:
2147 2148 # skip blank lines so we don't mess up the prompt counter, but do
2148 2149 # NOT skip even a blank line if we are in a code block (more is
2149 2150 # true)
2150 2151
2151 2152 if line or more:
2152 2153 # push to raw history, so hist line numbers stay in sync
2153 2154 self.input_hist_raw.append("# " + line + "\n")
2154 2155 more = self.push(self.prefilter(line,more))
2155 2156 # IPython's runsource returns None if there was an error
2156 2157 # compiling the code. This allows us to stop processing right
2157 2158 # away, so the user gets the error message at the right place.
2158 2159 if more is None:
2159 2160 break
2160 2161 else:
2161 2162 self.input_hist_raw.append("\n")
2162 2163 # final newline in case the input didn't have it, so that the code
2163 2164 # actually does get executed
2164 2165 if more:
2165 2166 self.push('\n')
2166 2167
2167 2168 def runsource(self, source, filename='<input>', symbol='single'):
2168 2169 """Compile and run some source in the interpreter.
2169 2170
2170 2171 Arguments are as for compile_command().
2171 2172
2172 2173 One several things can happen:
2173 2174
2174 2175 1) The input is incorrect; compile_command() raised an
2175 2176 exception (SyntaxError or OverflowError). A syntax traceback
2176 2177 will be printed by calling the showsyntaxerror() method.
2177 2178
2178 2179 2) The input is incomplete, and more input is required;
2179 2180 compile_command() returned None. Nothing happens.
2180 2181
2181 2182 3) The input is complete; compile_command() returned a code
2182 2183 object. The code is executed by calling self.runcode() (which
2183 2184 also handles run-time exceptions, except for SystemExit).
2184 2185
2185 2186 The return value is:
2186 2187
2187 2188 - True in case 2
2188 2189
2189 2190 - False in the other cases, unless an exception is raised, where
2190 2191 None is returned instead. This can be used by external callers to
2191 2192 know whether to continue feeding input or not.
2192 2193
2193 2194 The return value can be used to decide whether to use sys.ps1 or
2194 2195 sys.ps2 to prompt the next line."""
2195 2196
2196 2197 # if the source code has leading blanks, add 'if 1:\n' to it
2197 2198 # this allows execution of indented pasted code. It is tempting
2198 2199 # to add '\n' at the end of source to run commands like ' a=1'
2199 2200 # directly, but this fails for more complicated scenarios
2200 2201 source=source.encode(self.stdin_encoding)
2201 2202 if source[:1] in [' ', '\t']:
2202 2203 source = 'if 1:\n%s' % source
2203 2204
2204 2205 try:
2205 2206 code = self.compile(source,filename,symbol)
2206 2207 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2207 2208 # Case 1
2208 2209 self.showsyntaxerror(filename)
2209 2210 return None
2210 2211
2211 2212 if code is None:
2212 2213 # Case 2
2213 2214 return True
2214 2215
2215 2216 # Case 3
2216 2217 # We store the code object so that threaded shells and
2217 2218 # custom exception handlers can access all this info if needed.
2218 2219 # The source corresponding to this can be obtained from the
2219 2220 # buffer attribute as '\n'.join(self.buffer).
2220 2221 self.code_to_run = code
2221 2222 # now actually execute the code object
2222 2223 if self.runcode(code) == 0:
2223 2224 return False
2224 2225 else:
2225 2226 return None
2226 2227
2227 2228 def runcode(self,code_obj):
2228 2229 """Execute a code object.
2229 2230
2230 2231 When an exception occurs, self.showtraceback() is called to display a
2231 2232 traceback.
2232 2233
2233 2234 Return value: a flag indicating whether the code to be run completed
2234 2235 successfully:
2235 2236
2236 2237 - 0: successful execution.
2237 2238 - 1: an error occurred.
2238 2239 """
2239 2240
2240 2241 # Set our own excepthook in case the user code tries to call it
2241 2242 # directly, so that the IPython crash handler doesn't get triggered
2242 2243 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2243 2244
2244 2245 # we save the original sys.excepthook in the instance, in case config
2245 2246 # code (such as magics) needs access to it.
2246 2247 self.sys_excepthook = old_excepthook
2247 2248 outflag = 1 # happens in more places, so it's easier as default
2248 2249 try:
2249 2250 try:
2250 2251 self.hooks.pre_runcode_hook()
2251 2252 exec code_obj in self.user_global_ns, self.user_ns
2252 2253 finally:
2253 2254 # Reset our crash handler in place
2254 2255 sys.excepthook = old_excepthook
2255 2256 except SystemExit:
2256 2257 self.resetbuffer()
2257 2258 self.showtraceback()
2258 2259 warn("Type %exit or %quit to exit IPython "
2259 2260 "(%Exit or %Quit do so unconditionally).",level=1)
2260 2261 except self.custom_exceptions:
2261 2262 etype,value,tb = sys.exc_info()
2262 2263 self.CustomTB(etype,value,tb)
2263 2264 except:
2264 2265 self.showtraceback()
2265 2266 else:
2266 2267 outflag = 0
2267 2268 if softspace(sys.stdout, 0):
2268 2269 print
2269 2270 # Flush out code object which has been run (and source)
2270 2271 self.code_to_run = None
2271 2272 return outflag
2272 2273
2273 2274 def push(self, line):
2274 2275 """Push a line to the interpreter.
2275 2276
2276 2277 The line should not have a trailing newline; it may have
2277 2278 internal newlines. The line is appended to a buffer and the
2278 2279 interpreter's runsource() method is called with the
2279 2280 concatenated contents of the buffer as source. If this
2280 2281 indicates that the command was executed or invalid, the buffer
2281 2282 is reset; otherwise, the command is incomplete, and the buffer
2282 2283 is left as it was after the line was appended. The return
2283 2284 value is 1 if more input is required, 0 if the line was dealt
2284 2285 with in some way (this is the same as runsource()).
2285 2286 """
2286 2287
2287 2288 # autoindent management should be done here, and not in the
2288 2289 # interactive loop, since that one is only seen by keyboard input. We
2289 2290 # need this done correctly even for code run via runlines (which uses
2290 2291 # push).
2291 2292
2292 2293 #print 'push line: <%s>' % line # dbg
2293 2294 for subline in line.splitlines():
2294 2295 self.autoindent_update(subline)
2295 2296 self.buffer.append(line)
2296 2297 more = self.runsource('\n'.join(self.buffer), self.filename)
2297 2298 if not more:
2298 2299 self.resetbuffer()
2299 2300 return more
2300 2301
2301 2302 def split_user_input(self, line):
2302 2303 # This is really a hold-over to support ipapi and some extensions
2303 2304 return prefilter.splitUserInput(line)
2304 2305
2305 2306 def resetbuffer(self):
2306 2307 """Reset the input buffer."""
2307 2308 self.buffer[:] = []
2308 2309
2309 2310 def raw_input(self,prompt='',continue_prompt=False):
2310 2311 """Write a prompt and read a line.
2311 2312
2312 2313 The returned line does not include the trailing newline.
2313 2314 When the user enters the EOF key sequence, EOFError is raised.
2314 2315
2315 2316 Optional inputs:
2316 2317
2317 2318 - prompt(''): a string to be printed to prompt the user.
2318 2319
2319 2320 - continue_prompt(False): whether this line is the first one or a
2320 2321 continuation in a sequence of inputs.
2321 2322 """
2322 2323
2323 2324 # Code run by the user may have modified the readline completer state.
2324 2325 # We must ensure that our completer is back in place.
2325 2326 if self.has_readline:
2326 2327 self.set_completer()
2327 2328
2328 2329 try:
2329 2330 line = raw_input_original(prompt).decode(self.stdin_encoding)
2330 2331 except ValueError:
2331 2332 warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
2332 2333 " or sys.stdout.close()!\nExiting IPython!")
2333 2334 self.ask_exit()
2334 2335 return ""
2335 2336
2336 2337 # Try to be reasonably smart about not re-indenting pasted input more
2337 2338 # than necessary. We do this by trimming out the auto-indent initial
2338 2339 # spaces, if the user's actual input started itself with whitespace.
2339 2340 #debugx('self.buffer[-1]')
2340 2341
2341 2342 if self.autoindent:
2342 2343 if num_ini_spaces(line) > self.indent_current_nsp:
2343 2344 line = line[self.indent_current_nsp:]
2344 2345 self.indent_current_nsp = 0
2345 2346
2346 2347 # store the unfiltered input before the user has any chance to modify
2347 2348 # it.
2348 2349 if line.strip():
2349 2350 if continue_prompt:
2350 2351 self.input_hist_raw[-1] += '%s\n' % line
2351 2352 if self.has_readline: # and some config option is set?
2352 2353 try:
2353 2354 histlen = self.readline.get_current_history_length()
2354 2355 if histlen > 1:
2355 2356 newhist = self.input_hist_raw[-1].rstrip()
2356 2357 self.readline.remove_history_item(histlen-1)
2357 2358 self.readline.replace_history_item(histlen-2,
2358 2359 newhist.encode(self.stdin_encoding))
2359 2360 except AttributeError:
2360 2361 pass # re{move,place}_history_item are new in 2.4.
2361 2362 else:
2362 2363 self.input_hist_raw.append('%s\n' % line)
2363 2364 # only entries starting at first column go to shadow history
2364 2365 if line.lstrip() == line:
2365 2366 self.shadowhist.add(line.strip())
2366 2367 elif not continue_prompt:
2367 2368 self.input_hist_raw.append('\n')
2368 2369 try:
2369 2370 lineout = self.prefilter(line,continue_prompt)
2370 2371 except:
2371 2372 # blanket except, in case a user-defined prefilter crashes, so it
2372 2373 # can't take all of ipython with it.
2373 2374 self.showtraceback()
2374 2375 return ''
2375 2376 else:
2376 2377 return lineout
2377 2378
2378 2379 def _prefilter(self, line, continue_prompt):
2379 2380 """Calls different preprocessors, depending on the form of line."""
2380 2381
2381 2382 # All handlers *must* return a value, even if it's blank ('').
2382 2383
2383 2384 # Lines are NOT logged here. Handlers should process the line as
2384 2385 # needed, update the cache AND log it (so that the input cache array
2385 2386 # stays synced).
2386 2387
2387 2388 #.....................................................................
2388 2389 # Code begins
2389 2390
2390 2391 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
2391 2392
2392 2393 # save the line away in case we crash, so the post-mortem handler can
2393 2394 # record it
2394 2395 self._last_input_line = line
2395 2396
2396 2397 #print '***line: <%s>' % line # dbg
2397 2398
2398 2399 if not line:
2399 2400 # Return immediately on purely empty lines, so that if the user
2400 2401 # previously typed some whitespace that started a continuation
2401 2402 # prompt, he can break out of that loop with just an empty line.
2402 2403 # This is how the default python prompt works.
2403 2404
2404 2405 # Only return if the accumulated input buffer was just whitespace!
2405 2406 if ''.join(self.buffer).isspace():
2406 2407 self.buffer[:] = []
2407 2408 return ''
2408 2409
2409 2410 line_info = prefilter.LineInfo(line, continue_prompt)
2410 2411
2411 2412 # the input history needs to track even empty lines
2412 2413 stripped = line.strip()
2413 2414
2414 2415 if not stripped:
2415 2416 if not continue_prompt:
2416 2417 self.outputcache.prompt_count -= 1
2417 2418 return self.handle_normal(line_info)
2418 2419
2419 2420 # print '***cont',continue_prompt # dbg
2420 2421 # special handlers are only allowed for single line statements
2421 2422 if continue_prompt and not self.rc.multi_line_specials:
2422 2423 return self.handle_normal(line_info)
2423 2424
2424 2425
2425 2426 # See whether any pre-existing handler can take care of it
2426 2427 rewritten = self.hooks.input_prefilter(stripped)
2427 2428 if rewritten != stripped: # ok, some prefilter did something
2428 2429 rewritten = line_info.pre + rewritten # add indentation
2429 2430 return self.handle_normal(prefilter.LineInfo(rewritten,
2430 2431 continue_prompt))
2431 2432
2432 2433 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2433 2434
2434 2435 return prefilter.prefilter(line_info, self)
2435 2436
2436 2437
2437 2438 def _prefilter_dumb(self, line, continue_prompt):
2438 2439 """simple prefilter function, for debugging"""
2439 2440 return self.handle_normal(line,continue_prompt)
2440 2441
2441 2442
2442 2443 def multiline_prefilter(self, line, continue_prompt):
2443 2444 """ Run _prefilter for each line of input
2444 2445
2445 2446 Covers cases where there are multiple lines in the user entry,
2446 2447 which is the case when the user goes back to a multiline history
2447 2448 entry and presses enter.
2448 2449
2449 2450 """
2450 2451 out = []
2451 2452 for l in line.rstrip('\n').split('\n'):
2452 2453 out.append(self._prefilter(l, continue_prompt))
2453 2454 return '\n'.join(out)
2454 2455
2455 2456 # Set the default prefilter() function (this can be user-overridden)
2456 2457 prefilter = multiline_prefilter
2457 2458
2458 2459 def handle_normal(self,line_info):
2459 2460 """Handle normal input lines. Use as a template for handlers."""
2460 2461
2461 2462 # With autoindent on, we need some way to exit the input loop, and I
2462 2463 # don't want to force the user to have to backspace all the way to
2463 2464 # clear the line. The rule will be in this case, that either two
2464 2465 # lines of pure whitespace in a row, or a line of pure whitespace but
2465 2466 # of a size different to the indent level, will exit the input loop.
2466 2467 line = line_info.line
2467 2468 continue_prompt = line_info.continue_prompt
2468 2469
2469 2470 if (continue_prompt and self.autoindent and line.isspace() and
2470 2471 (0 < abs(len(line) - self.indent_current_nsp) <= 2 or
2471 2472 (self.buffer[-1]).isspace() )):
2472 2473 line = ''
2473 2474
2474 2475 self.log(line,line,continue_prompt)
2475 2476 return line
2476 2477
2477 2478 def handle_alias(self,line_info):
2478 2479 """Handle alias input lines. """
2479 2480 tgt = self.alias_table[line_info.iFun]
2480 2481 # print "=>",tgt #dbg
2481 2482 if callable(tgt):
2482 2483 if '$' in line_info.line:
2483 2484 call_meth = '(_ip, _ip.itpl(%s))'
2484 2485 else:
2485 2486 call_meth = '(_ip,%s)'
2486 2487 line_out = ("%s_sh.%s" + call_meth) % (line_info.preWhitespace,
2487 2488 line_info.iFun,
2488 2489 make_quoted_expr(line_info.line))
2489 2490 else:
2490 2491 transformed = self.expand_aliases(line_info.iFun,line_info.theRest)
2491 2492
2492 2493 # pre is needed, because it carries the leading whitespace. Otherwise
2493 2494 # aliases won't work in indented sections.
2494 2495 line_out = '%s_ip.system(%s)' % (line_info.preWhitespace,
2495 2496 make_quoted_expr( transformed ))
2496 2497
2497 2498 self.log(line_info.line,line_out,line_info.continue_prompt)
2498 2499 #print 'line out:',line_out # dbg
2499 2500 return line_out
2500 2501
2501 2502 def handle_shell_escape(self, line_info):
2502 2503 """Execute the line in a shell, empty return value"""
2503 2504 #print 'line in :', `line` # dbg
2504 2505 line = line_info.line
2505 2506 if line.lstrip().startswith('!!'):
2506 2507 # rewrite LineInfo's line, iFun and theRest to properly hold the
2507 2508 # call to %sx and the actual command to be executed, so
2508 2509 # handle_magic can work correctly. Note that this works even if
2509 2510 # the line is indented, so it handles multi_line_specials
2510 2511 # properly.
2511 2512 new_rest = line.lstrip()[2:]
2512 2513 line_info.line = '%ssx %s' % (self.ESC_MAGIC,new_rest)
2513 2514 line_info.iFun = 'sx'
2514 2515 line_info.theRest = new_rest
2515 2516 return self.handle_magic(line_info)
2516 2517 else:
2517 2518 cmd = line.lstrip().lstrip('!')
2518 2519 line_out = '%s_ip.system(%s)' % (line_info.preWhitespace,
2519 2520 make_quoted_expr(cmd))
2520 2521 # update cache/log and return
2521 2522 self.log(line,line_out,line_info.continue_prompt)
2522 2523 return line_out
2523 2524
2524 2525 def handle_magic(self, line_info):
2525 2526 """Execute magic functions."""
2526 2527 iFun = line_info.iFun
2527 2528 theRest = line_info.theRest
2528 2529 cmd = '%s_ip.magic(%s)' % (line_info.preWhitespace,
2529 2530 make_quoted_expr(iFun + " " + theRest))
2530 2531 self.log(line_info.line,cmd,line_info.continue_prompt)
2531 2532 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
2532 2533 return cmd
2533 2534
2534 2535 def handle_auto(self, line_info):
2535 2536 """Hande lines which can be auto-executed, quoting if requested."""
2536 2537
2537 2538 line = line_info.line
2538 2539 iFun = line_info.iFun
2539 2540 theRest = line_info.theRest
2540 2541 pre = line_info.pre
2541 2542 continue_prompt = line_info.continue_prompt
2542 2543 obj = line_info.ofind(self)['obj']
2543 2544
2544 2545 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2545 2546
2546 2547 # This should only be active for single-line input!
2547 2548 if continue_prompt:
2548 2549 self.log(line,line,continue_prompt)
2549 2550 return line
2550 2551
2551 2552 force_auto = isinstance(obj, ipapi.IPyAutocall)
2552 2553 auto_rewrite = True
2553 2554
2554 2555 if pre == self.ESC_QUOTE:
2555 2556 # Auto-quote splitting on whitespace
2556 2557 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
2557 2558 elif pre == self.ESC_QUOTE2:
2558 2559 # Auto-quote whole string
2559 2560 newcmd = '%s("%s")' % (iFun,theRest)
2560 2561 elif pre == self.ESC_PAREN:
2561 2562 newcmd = '%s(%s)' % (iFun,",".join(theRest.split()))
2562 2563 else:
2563 2564 # Auto-paren.
2564 2565 # We only apply it to argument-less calls if the autocall
2565 2566 # parameter is set to 2. We only need to check that autocall is <
2566 2567 # 2, since this function isn't called unless it's at least 1.
2567 2568 if not theRest and (self.rc.autocall < 2) and not force_auto:
2568 2569 newcmd = '%s %s' % (iFun,theRest)
2569 2570 auto_rewrite = False
2570 2571 else:
2571 2572 if not force_auto and theRest.startswith('['):
2572 2573 if hasattr(obj,'__getitem__'):
2573 2574 # Don't autocall in this case: item access for an object
2574 2575 # which is BOTH callable and implements __getitem__.
2575 2576 newcmd = '%s %s' % (iFun,theRest)
2576 2577 auto_rewrite = False
2577 2578 else:
2578 2579 # if the object doesn't support [] access, go ahead and
2579 2580 # autocall
2580 2581 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
2581 2582 elif theRest.endswith(';'):
2582 2583 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
2583 2584 else:
2584 2585 newcmd = '%s(%s)' % (iFun.rstrip(), theRest)
2585 2586
2586 2587 if auto_rewrite:
2587 2588 rw = self.outputcache.prompt1.auto_rewrite() + newcmd
2588 2589
2589 2590 try:
2590 2591 # plain ascii works better w/ pyreadline, on some machines, so
2591 2592 # we use it and only print uncolored rewrite if we have unicode
2592 2593 rw = str(rw)
2593 2594 print >>Term.cout, rw
2594 2595 except UnicodeEncodeError:
2595 2596 print "-------------->" + newcmd
2596 2597
2597 2598 # log what is now valid Python, not the actual user input (without the
2598 2599 # final newline)
2599 2600 self.log(line,newcmd,continue_prompt)
2600 2601 return newcmd
2601 2602
2602 2603 def handle_help(self, line_info):
2603 2604 """Try to get some help for the object.
2604 2605
2605 2606 obj? or ?obj -> basic information.
2606 2607 obj?? or ??obj -> more details.
2607 2608 """
2608 2609
2609 2610 line = line_info.line
2610 2611 # We need to make sure that we don't process lines which would be
2611 2612 # otherwise valid python, such as "x=1 # what?"
2612 2613 try:
2613 2614 codeop.compile_command(line)
2614 2615 except SyntaxError:
2615 2616 # We should only handle as help stuff which is NOT valid syntax
2616 2617 if line[0]==self.ESC_HELP:
2617 2618 line = line[1:]
2618 2619 elif line[-1]==self.ESC_HELP:
2619 2620 line = line[:-1]
2620 2621 self.log(line,'#?'+line,line_info.continue_prompt)
2621 2622 if line:
2622 2623 #print 'line:<%r>' % line # dbg
2623 2624 self.magic_pinfo(line)
2624 2625 else:
2625 2626 page(self.usage,screen_lines=self.rc.screen_length)
2626 2627 return '' # Empty string is needed here!
2627 2628 except:
2628 2629 # Pass any other exceptions through to the normal handler
2629 2630 return self.handle_normal(line_info)
2630 2631 else:
2631 2632 # If the code compiles ok, we should handle it normally
2632 2633 return self.handle_normal(line_info)
2633 2634
2634 2635 def getapi(self):
2635 2636 """ Get an IPApi object for this shell instance
2636 2637
2637 2638 Getting an IPApi object is always preferable to accessing the shell
2638 2639 directly, but this holds true especially for extensions.
2639 2640
2640 2641 It should always be possible to implement an extension with IPApi
2641 2642 alone. If not, contact maintainer to request an addition.
2642 2643
2643 2644 """
2644 2645 return self.api
2645 2646
2646 2647 def handle_emacs(self, line_info):
2647 2648 """Handle input lines marked by python-mode."""
2648 2649
2649 2650 # Currently, nothing is done. Later more functionality can be added
2650 2651 # here if needed.
2651 2652
2652 2653 # The input cache shouldn't be updated
2653 2654 return line_info.line
2654 2655
2655 2656
2656 2657 def mktempfile(self,data=None):
2657 2658 """Make a new tempfile and return its filename.
2658 2659
2659 2660 This makes a call to tempfile.mktemp, but it registers the created
2660 2661 filename internally so ipython cleans it up at exit time.
2661 2662
2662 2663 Optional inputs:
2663 2664
2664 2665 - data(None): if data is given, it gets written out to the temp file
2665 2666 immediately, and the file is closed again."""
2666 2667
2667 2668 filename = tempfile.mktemp('.py','ipython_edit_')
2668 2669 self.tempfiles.append(filename)
2669 2670
2670 2671 if data:
2671 2672 tmp_file = open(filename,'w')
2672 2673 tmp_file.write(data)
2673 2674 tmp_file.close()
2674 2675 return filename
2675 2676
2676 2677 def write(self,data):
2677 2678 """Write a string to the default output"""
2678 2679 Term.cout.write(data)
2679 2680
2680 2681 def write_err(self,data):
2681 2682 """Write a string to the default error output"""
2682 2683 Term.cerr.write(data)
2683 2684
2684 2685 def ask_exit(self):
2685 2686 """ Call for exiting. Can be overiden and used as a callback. """
2686 2687 self.exit_now = True
2687 2688
2688 2689 def exit(self):
2689 2690 """Handle interactive exit.
2690 2691
2691 2692 This method calls the ask_exit callback."""
2692 2693
2693 2694 if self.rc.confirm_exit:
2694 2695 if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2695 2696 self.ask_exit()
2696 2697 else:
2697 2698 self.ask_exit()
2698 2699
2699 2700 def safe_execfile(self,fname,*where,**kw):
2700 2701 """A safe version of the builtin execfile().
2701 2702
2702 2703 This version will never throw an exception, and knows how to handle
2703 2704 ipython logs as well.
2704 2705
2705 2706 :Parameters:
2706 2707 fname : string
2707 2708 Name of the file to be executed.
2708 2709
2709 2710 where : tuple
2710 2711 One or two namespaces, passed to execfile() as (globals,locals).
2711 2712 If only one is given, it is passed as both.
2712 2713
2713 2714 :Keywords:
2714 2715 islog : boolean (False)
2715 2716
2716 2717 quiet : boolean (True)
2717 2718
2718 2719 exit_ignore : boolean (False)
2719 2720 """
2720 2721
2721 2722 def syspath_cleanup():
2722 2723 """Internal cleanup routine for sys.path."""
2723 2724 if add_dname:
2724 2725 try:
2725 2726 sys.path.remove(dname)
2726 2727 except ValueError:
2727 2728 # For some reason the user has already removed it, ignore.
2728 2729 pass
2729 2730
2730 2731 fname = os.path.expanduser(fname)
2731 2732
2732 2733 # Find things also in current directory. This is needed to mimic the
2733 2734 # behavior of running a script from the system command line, where
2734 2735 # Python inserts the script's directory into sys.path
2735 2736 dname = os.path.dirname(os.path.abspath(fname))
2736 2737 add_dname = False
2737 2738 if dname not in sys.path:
2738 2739 sys.path.insert(0,dname)
2739 2740 add_dname = True
2740 2741
2741 2742 try:
2742 2743 xfile = open(fname)
2743 2744 except:
2744 2745 print >> Term.cerr, \
2745 2746 'Could not open file <%s> for safe execution.' % fname
2746 2747 syspath_cleanup()
2747 2748 return None
2748 2749
2749 2750 kw.setdefault('islog',0)
2750 2751 kw.setdefault('quiet',1)
2751 2752 kw.setdefault('exit_ignore',0)
2752 2753
2753 2754 first = xfile.readline()
2754 2755 loghead = str(self.loghead_tpl).split('\n',1)[0].strip()
2755 2756 xfile.close()
2756 2757 # line by line execution
2757 2758 if first.startswith(loghead) or kw['islog']:
2758 2759 print 'Loading log file <%s> one line at a time...' % fname
2759 2760 if kw['quiet']:
2760 2761 stdout_save = sys.stdout
2761 2762 sys.stdout = StringIO.StringIO()
2762 2763 try:
2763 2764 globs,locs = where[0:2]
2764 2765 except:
2765 2766 try:
2766 2767 globs = locs = where[0]
2767 2768 except:
2768 2769 globs = locs = globals()
2769 2770 badblocks = []
2770 2771
2771 2772 # we also need to identify indented blocks of code when replaying
2772 2773 # logs and put them together before passing them to an exec
2773 2774 # statement. This takes a bit of regexp and look-ahead work in the
2774 2775 # file. It's easiest if we swallow the whole thing in memory
2775 2776 # first, and manually walk through the lines list moving the
2776 2777 # counter ourselves.
2777 2778 indent_re = re.compile('\s+\S')
2778 2779 xfile = open(fname)
2779 2780 filelines = xfile.readlines()
2780 2781 xfile.close()
2781 2782 nlines = len(filelines)
2782 2783 lnum = 0
2783 2784 while lnum < nlines:
2784 2785 line = filelines[lnum]
2785 2786 lnum += 1
2786 2787 # don't re-insert logger status info into cache
2787 2788 if line.startswith('#log#'):
2788 2789 continue
2789 2790 else:
2790 2791 # build a block of code (maybe a single line) for execution
2791 2792 block = line
2792 2793 try:
2793 2794 next = filelines[lnum] # lnum has already incremented
2794 2795 except:
2795 2796 next = None
2796 2797 while next and indent_re.match(next):
2797 2798 block += next
2798 2799 lnum += 1
2799 2800 try:
2800 2801 next = filelines[lnum]
2801 2802 except:
2802 2803 next = None
2803 2804 # now execute the block of one or more lines
2804 2805 try:
2805 2806 exec block in globs,locs
2806 2807 except SystemExit:
2807 2808 pass
2808 2809 except:
2809 2810 badblocks.append(block.rstrip())
2810 2811 if kw['quiet']: # restore stdout
2811 2812 sys.stdout.close()
2812 2813 sys.stdout = stdout_save
2813 2814 print 'Finished replaying log file <%s>' % fname
2814 2815 if badblocks:
2815 2816 print >> sys.stderr, ('\nThe following lines/blocks in file '
2816 2817 '<%s> reported errors:' % fname)
2817 2818
2818 2819 for badline in badblocks:
2819 2820 print >> sys.stderr, badline
2820 2821 else: # regular file execution
2821 2822 try:
2822 2823 if sys.platform == 'win32' and sys.version_info < (2,5,1):
2823 2824 # Work around a bug in Python for Windows. The bug was
2824 2825 # fixed in in Python 2.5 r54159 and 54158, but that's still
2825 2826 # SVN Python as of March/07. For details, see:
2826 2827 # http://projects.scipy.org/ipython/ipython/ticket/123
2827 2828 try:
2828 2829 globs,locs = where[0:2]
2829 2830 except:
2830 2831 try:
2831 2832 globs = locs = where[0]
2832 2833 except:
2833 2834 globs = locs = globals()
2834 2835 exec file(fname) in globs,locs
2835 2836 else:
2836 2837 execfile(fname,*where)
2837 2838 except SyntaxError:
2838 2839 self.showsyntaxerror()
2839 2840 warn('Failure executing file: <%s>' % fname)
2840 2841 except SystemExit,status:
2841 2842 # Code that correctly sets the exit status flag to success (0)
2842 2843 # shouldn't be bothered with a traceback. Note that a plain
2843 2844 # sys.exit() does NOT set the message to 0 (it's empty) so that
2844 2845 # will still get a traceback. Note that the structure of the
2845 2846 # SystemExit exception changed between Python 2.4 and 2.5, so
2846 2847 # the checks must be done in a version-dependent way.
2847 2848 show = False
2848 2849
2849 2850 if sys.version_info[:2] > (2,5):
2850 2851 if status.message!=0 and not kw['exit_ignore']:
2851 2852 show = True
2852 2853 else:
2853 2854 if status.code and not kw['exit_ignore']:
2854 2855 show = True
2855 2856 if show:
2856 2857 self.showtraceback()
2857 2858 warn('Failure executing file: <%s>' % fname)
2858 2859 except:
2859 2860 self.showtraceback()
2860 2861 warn('Failure executing file: <%s>' % fname)
2861 2862
2862 2863 syspath_cleanup()
2863 2864
2864 2865 #************************* end of file <iplib.py> *****************************
@@ -1,3457 +1,3457 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Magic functions for InteractiveShell.
3 3 """
4 4
5 5 #*****************************************************************************
6 6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
8 8 #
9 9 # Distributed under the terms of the BSD License. The full license is in
10 10 # the file COPYING, distributed as part of this software.
11 11 #*****************************************************************************
12 12
13 13 #****************************************************************************
14 14 # Modules and globals
15 15
16 16 # Python standard modules
17 17 import __builtin__
18 18 import bdb
19 19 import inspect
20 20 import os
21 21 import pdb
22 22 import pydoc
23 23 import sys
24 24 import re
25 25 import tempfile
26 26 import time
27 27 import cPickle as pickle
28 28 import textwrap
29 29 from cStringIO import StringIO
30 30 from getopt import getopt,GetoptError
31 31 from pprint import pprint, pformat
32 32
33 33 # cProfile was added in Python2.5
34 34 try:
35 35 import cProfile as profile
36 36 import pstats
37 37 except ImportError:
38 38 # profile isn't bundled by default in Debian for license reasons
39 39 try:
40 40 import profile,pstats
41 41 except ImportError:
42 42 profile = pstats = None
43 43
44 44 # Homebrewed
45 45 import IPython
46 46 from IPython import wildcard
47 47 from IPython.core import debugger, oinspect
48 48 from IPython.core.fakemodule import FakeModule
49 49 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
50 from IPython.PyColorize import Parser
50 from IPython.utils.PyColorize import Parser
51 51 from IPython.utils.ipstruct import Struct
52 52 from IPython.core.macro import Macro
53 53 from IPython.utils.genutils import *
54 54 from IPython.utils import platutils
55 55 import IPython.utils.generics
56 56 from IPython.core import ipapi
57 57 from IPython.core.ipapi import UsageError
58 58 from IPython.testing import decorators as testdec
59 59
60 60 #***************************************************************************
61 61 # Utility functions
62 62 def on_off(tag):
63 63 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
64 64 return ['OFF','ON'][tag]
65 65
66 66 class Bunch: pass
67 67
68 68 def compress_dhist(dh):
69 69 head, tail = dh[:-10], dh[-10:]
70 70
71 71 newhead = []
72 72 done = set()
73 73 for h in head:
74 74 if h in done:
75 75 continue
76 76 newhead.append(h)
77 77 done.add(h)
78 78
79 79 return newhead + tail
80 80
81 81
82 82 #***************************************************************************
83 83 # Main class implementing Magic functionality
84 84 class Magic:
85 85 """Magic functions for InteractiveShell.
86 86
87 87 Shell functions which can be reached as %function_name. All magic
88 88 functions should accept a string, which they can parse for their own
89 89 needs. This can make some functions easier to type, eg `%cd ../`
90 90 vs. `%cd("../")`
91 91
92 92 ALL definitions MUST begin with the prefix magic_. The user won't need it
93 93 at the command line, but it is is needed in the definition. """
94 94
95 95 # class globals
96 96 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
97 97 'Automagic is ON, % prefix NOT needed for magic functions.']
98 98
99 99 #......................................................................
100 100 # some utility functions
101 101
102 102 def __init__(self,shell):
103 103
104 104 self.options_table = {}
105 105 if profile is None:
106 106 self.magic_prun = self.profile_missing_notice
107 107 self.shell = shell
108 108
109 109 # namespace for holding state we may need
110 110 self._magic_state = Bunch()
111 111
112 112 def profile_missing_notice(self, *args, **kwargs):
113 113 error("""\
114 114 The profile module could not be found. It has been removed from the standard
115 115 python packages because of its non-free license. To use profiling, install the
116 116 python-profiler package from non-free.""")
117 117
118 118 def default_option(self,fn,optstr):
119 119 """Make an entry in the options_table for fn, with value optstr"""
120 120
121 121 if fn not in self.lsmagic():
122 122 error("%s is not a magic function" % fn)
123 123 self.options_table[fn] = optstr
124 124
125 125 def lsmagic(self):
126 126 """Return a list of currently available magic functions.
127 127
128 128 Gives a list of the bare names after mangling (['ls','cd', ...], not
129 129 ['magic_ls','magic_cd',...]"""
130 130
131 131 # FIXME. This needs a cleanup, in the way the magics list is built.
132 132
133 133 # magics in class definition
134 134 class_magic = lambda fn: fn.startswith('magic_') and \
135 135 callable(Magic.__dict__[fn])
136 136 # in instance namespace (run-time user additions)
137 137 inst_magic = lambda fn: fn.startswith('magic_') and \
138 138 callable(self.__dict__[fn])
139 139 # and bound magics by user (so they can access self):
140 140 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
141 141 callable(self.__class__.__dict__[fn])
142 142 magics = filter(class_magic,Magic.__dict__.keys()) + \
143 143 filter(inst_magic,self.__dict__.keys()) + \
144 144 filter(inst_bound_magic,self.__class__.__dict__.keys())
145 145 out = []
146 146 for fn in set(magics):
147 147 out.append(fn.replace('magic_','',1))
148 148 out.sort()
149 149 return out
150 150
151 151 def extract_input_slices(self,slices,raw=False):
152 152 """Return as a string a set of input history slices.
153 153
154 154 Inputs:
155 155
156 156 - slices: the set of slices is given as a list of strings (like
157 157 ['1','4:8','9'], since this function is for use by magic functions
158 158 which get their arguments as strings.
159 159
160 160 Optional inputs:
161 161
162 162 - raw(False): by default, the processed input is used. If this is
163 163 true, the raw input history is used instead.
164 164
165 165 Note that slices can be called with two notations:
166 166
167 167 N:M -> standard python form, means including items N...(M-1).
168 168
169 169 N-M -> include items N..M (closed endpoint)."""
170 170
171 171 if raw:
172 172 hist = self.shell.input_hist_raw
173 173 else:
174 174 hist = self.shell.input_hist
175 175
176 176 cmds = []
177 177 for chunk in slices:
178 178 if ':' in chunk:
179 179 ini,fin = map(int,chunk.split(':'))
180 180 elif '-' in chunk:
181 181 ini,fin = map(int,chunk.split('-'))
182 182 fin += 1
183 183 else:
184 184 ini = int(chunk)
185 185 fin = ini+1
186 186 cmds.append(hist[ini:fin])
187 187 return cmds
188 188
189 189 def _ofind(self, oname, namespaces=None):
190 190 """Find an object in the available namespaces.
191 191
192 192 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
193 193
194 194 Has special code to detect magic functions.
195 195 """
196 196
197 197 oname = oname.strip()
198 198
199 199 alias_ns = None
200 200 if namespaces is None:
201 201 # Namespaces to search in:
202 202 # Put them in a list. The order is important so that we
203 203 # find things in the same order that Python finds them.
204 204 namespaces = [ ('Interactive', self.shell.user_ns),
205 205 ('IPython internal', self.shell.internal_ns),
206 206 ('Python builtin', __builtin__.__dict__),
207 207 ('Alias', self.shell.alias_table),
208 208 ]
209 209 alias_ns = self.shell.alias_table
210 210
211 211 # initialize results to 'null'
212 212 found = 0; obj = None; ospace = None; ds = None;
213 213 ismagic = 0; isalias = 0; parent = None
214 214
215 215 # Look for the given name by splitting it in parts. If the head is
216 216 # found, then we look for all the remaining parts as members, and only
217 217 # declare success if we can find them all.
218 218 oname_parts = oname.split('.')
219 219 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
220 220 for nsname,ns in namespaces:
221 221 try:
222 222 obj = ns[oname_head]
223 223 except KeyError:
224 224 continue
225 225 else:
226 226 #print 'oname_rest:', oname_rest # dbg
227 227 for part in oname_rest:
228 228 try:
229 229 parent = obj
230 230 obj = getattr(obj,part)
231 231 except:
232 232 # Blanket except b/c some badly implemented objects
233 233 # allow __getattr__ to raise exceptions other than
234 234 # AttributeError, which then crashes IPython.
235 235 break
236 236 else:
237 237 # If we finish the for loop (no break), we got all members
238 238 found = 1
239 239 ospace = nsname
240 240 if ns == alias_ns:
241 241 isalias = 1
242 242 break # namespace loop
243 243
244 244 # Try to see if it's magic
245 245 if not found:
246 246 if oname.startswith(self.shell.ESC_MAGIC):
247 247 oname = oname[1:]
248 248 obj = getattr(self,'magic_'+oname,None)
249 249 if obj is not None:
250 250 found = 1
251 251 ospace = 'IPython internal'
252 252 ismagic = 1
253 253
254 254 # Last try: special-case some literals like '', [], {}, etc:
255 255 if not found and oname_head in ["''",'""','[]','{}','()']:
256 256 obj = eval(oname_head)
257 257 found = 1
258 258 ospace = 'Interactive'
259 259
260 260 return {'found':found, 'obj':obj, 'namespace':ospace,
261 261 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
262 262
263 263 def arg_err(self,func):
264 264 """Print docstring if incorrect arguments were passed"""
265 265 print 'Error in arguments:'
266 266 print OInspect.getdoc(func)
267 267
268 268 def format_latex(self,strng):
269 269 """Format a string for latex inclusion."""
270 270
271 271 # Characters that need to be escaped for latex:
272 272 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
273 273 # Magic command names as headers:
274 274 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
275 275 re.MULTILINE)
276 276 # Magic commands
277 277 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
278 278 re.MULTILINE)
279 279 # Paragraph continue
280 280 par_re = re.compile(r'\\$',re.MULTILINE)
281 281
282 282 # The "\n" symbol
283 283 newline_re = re.compile(r'\\n')
284 284
285 285 # Now build the string for output:
286 286 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
287 287 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
288 288 strng)
289 289 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
290 290 strng = par_re.sub(r'\\\\',strng)
291 291 strng = escape_re.sub(r'\\\1',strng)
292 292 strng = newline_re.sub(r'\\textbackslash{}n',strng)
293 293 return strng
294 294
295 295 def format_screen(self,strng):
296 296 """Format a string for screen printing.
297 297
298 298 This removes some latex-type format codes."""
299 299 # Paragraph continue
300 300 par_re = re.compile(r'\\$',re.MULTILINE)
301 301 strng = par_re.sub('',strng)
302 302 return strng
303 303
304 304 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
305 305 """Parse options passed to an argument string.
306 306
307 307 The interface is similar to that of getopt(), but it returns back a
308 308 Struct with the options as keys and the stripped argument string still
309 309 as a string.
310 310
311 311 arg_str is quoted as a true sys.argv vector by using shlex.split.
312 312 This allows us to easily expand variables, glob files, quote
313 313 arguments, etc.
314 314
315 315 Options:
316 316 -mode: default 'string'. If given as 'list', the argument string is
317 317 returned as a list (split on whitespace) instead of a string.
318 318
319 319 -list_all: put all option values in lists. Normally only options
320 320 appearing more than once are put in a list.
321 321
322 322 -posix (True): whether to split the input line in POSIX mode or not,
323 323 as per the conventions outlined in the shlex module from the
324 324 standard library."""
325 325
326 326 # inject default options at the beginning of the input line
327 327 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
328 328 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
329 329
330 330 mode = kw.get('mode','string')
331 331 if mode not in ['string','list']:
332 332 raise ValueError,'incorrect mode given: %s' % mode
333 333 # Get options
334 334 list_all = kw.get('list_all',0)
335 335 posix = kw.get('posix',True)
336 336
337 337 # Check if we have more than one argument to warrant extra processing:
338 338 odict = {} # Dictionary with options
339 339 args = arg_str.split()
340 340 if len(args) >= 1:
341 341 # If the list of inputs only has 0 or 1 thing in it, there's no
342 342 # need to look for options
343 343 argv = arg_split(arg_str,posix)
344 344 # Do regular option processing
345 345 try:
346 346 opts,args = getopt(argv,opt_str,*long_opts)
347 347 except GetoptError,e:
348 348 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
349 349 " ".join(long_opts)))
350 350 for o,a in opts:
351 351 if o.startswith('--'):
352 352 o = o[2:]
353 353 else:
354 354 o = o[1:]
355 355 try:
356 356 odict[o].append(a)
357 357 except AttributeError:
358 358 odict[o] = [odict[o],a]
359 359 except KeyError:
360 360 if list_all:
361 361 odict[o] = [a]
362 362 else:
363 363 odict[o] = a
364 364
365 365 # Prepare opts,args for return
366 366 opts = Struct(odict)
367 367 if mode == 'string':
368 368 args = ' '.join(args)
369 369
370 370 return opts,args
371 371
372 372 #......................................................................
373 373 # And now the actual magic functions
374 374
375 375 # Functions for IPython shell work (vars,funcs, config, etc)
376 376 def magic_lsmagic(self, parameter_s = ''):
377 377 """List currently available magic functions."""
378 378 mesc = self.shell.ESC_MAGIC
379 379 print 'Available magic functions:\n'+mesc+\
380 380 (' '+mesc).join(self.lsmagic())
381 381 print '\n' + Magic.auto_status[self.shell.rc.automagic]
382 382 return None
383 383
384 384 def magic_magic(self, parameter_s = ''):
385 385 """Print information about the magic function system.
386 386
387 387 Supported formats: -latex, -brief, -rest
388 388 """
389 389
390 390 mode = ''
391 391 try:
392 392 if parameter_s.split()[0] == '-latex':
393 393 mode = 'latex'
394 394 if parameter_s.split()[0] == '-brief':
395 395 mode = 'brief'
396 396 if parameter_s.split()[0] == '-rest':
397 397 mode = 'rest'
398 398 rest_docs = []
399 399 except:
400 400 pass
401 401
402 402 magic_docs = []
403 403 for fname in self.lsmagic():
404 404 mname = 'magic_' + fname
405 405 for space in (Magic,self,self.__class__):
406 406 try:
407 407 fn = space.__dict__[mname]
408 408 except KeyError:
409 409 pass
410 410 else:
411 411 break
412 412 if mode == 'brief':
413 413 # only first line
414 414 if fn.__doc__:
415 415 fndoc = fn.__doc__.split('\n',1)[0]
416 416 else:
417 417 fndoc = 'No documentation'
418 418 else:
419 419 if fn.__doc__:
420 420 fndoc = fn.__doc__.rstrip()
421 421 else:
422 422 fndoc = 'No documentation'
423 423
424 424
425 425 if mode == 'rest':
426 426 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
427 427 fname,fndoc))
428 428
429 429 else:
430 430 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
431 431 fname,fndoc))
432 432
433 433 magic_docs = ''.join(magic_docs)
434 434
435 435 if mode == 'rest':
436 436 return "".join(rest_docs)
437 437
438 438 if mode == 'latex':
439 439 print self.format_latex(magic_docs)
440 440 return
441 441 else:
442 442 magic_docs = self.format_screen(magic_docs)
443 443 if mode == 'brief':
444 444 return magic_docs
445 445
446 446 outmsg = """
447 447 IPython's 'magic' functions
448 448 ===========================
449 449
450 450 The magic function system provides a series of functions which allow you to
451 451 control the behavior of IPython itself, plus a lot of system-type
452 452 features. All these functions are prefixed with a % character, but parameters
453 453 are given without parentheses or quotes.
454 454
455 455 NOTE: If you have 'automagic' enabled (via the command line option or with the
456 456 %automagic function), you don't need to type in the % explicitly. By default,
457 457 IPython ships with automagic on, so you should only rarely need the % escape.
458 458
459 459 Example: typing '%cd mydir' (without the quotes) changes you working directory
460 460 to 'mydir', if it exists.
461 461
462 462 You can define your own magic functions to extend the system. See the supplied
463 463 ipythonrc and example-magic.py files for details (in your ipython
464 464 configuration directory, typically $HOME/.ipython/).
465 465
466 466 You can also define your own aliased names for magic functions. In your
467 467 ipythonrc file, placing a line like:
468 468
469 469 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
470 470
471 471 will define %pf as a new name for %profile.
472 472
473 473 You can also call magics in code using the ipmagic() function, which IPython
474 474 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
475 475
476 476 For a list of the available magic functions, use %lsmagic. For a description
477 477 of any of them, type %magic_name?, e.g. '%cd?'.
478 478
479 479 Currently the magic system has the following functions:\n"""
480 480
481 481 mesc = self.shell.ESC_MAGIC
482 482 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
483 483 "\n\n%s%s\n\n%s" % (outmsg,
484 484 magic_docs,mesc,mesc,
485 485 (' '+mesc).join(self.lsmagic()),
486 486 Magic.auto_status[self.shell.rc.automagic] ) )
487 487
488 488 page(outmsg,screen_lines=self.shell.rc.screen_length)
489 489
490 490
491 491 def magic_autoindent(self, parameter_s = ''):
492 492 """Toggle autoindent on/off (if available)."""
493 493
494 494 self.shell.set_autoindent()
495 495 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
496 496
497 497
498 498 def magic_automagic(self, parameter_s = ''):
499 499 """Make magic functions callable without having to type the initial %.
500 500
501 501 Without argumentsl toggles on/off (when off, you must call it as
502 502 %automagic, of course). With arguments it sets the value, and you can
503 503 use any of (case insensitive):
504 504
505 505 - on,1,True: to activate
506 506
507 507 - off,0,False: to deactivate.
508 508
509 509 Note that magic functions have lowest priority, so if there's a
510 510 variable whose name collides with that of a magic fn, automagic won't
511 511 work for that function (you get the variable instead). However, if you
512 512 delete the variable (del var), the previously shadowed magic function
513 513 becomes visible to automagic again."""
514 514
515 515 rc = self.shell.rc
516 516 arg = parameter_s.lower()
517 517 if parameter_s in ('on','1','true'):
518 518 rc.automagic = True
519 519 elif parameter_s in ('off','0','false'):
520 520 rc.automagic = False
521 521 else:
522 522 rc.automagic = not rc.automagic
523 523 print '\n' + Magic.auto_status[rc.automagic]
524 524
525 525 @testdec.skip_doctest
526 526 def magic_autocall(self, parameter_s = ''):
527 527 """Make functions callable without having to type parentheses.
528 528
529 529 Usage:
530 530
531 531 %autocall [mode]
532 532
533 533 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
534 534 value is toggled on and off (remembering the previous state).
535 535
536 536 In more detail, these values mean:
537 537
538 538 0 -> fully disabled
539 539
540 540 1 -> active, but do not apply if there are no arguments on the line.
541 541
542 542 In this mode, you get:
543 543
544 544 In [1]: callable
545 545 Out[1]: <built-in function callable>
546 546
547 547 In [2]: callable 'hello'
548 548 ------> callable('hello')
549 549 Out[2]: False
550 550
551 551 2 -> Active always. Even if no arguments are present, the callable
552 552 object is called:
553 553
554 554 In [2]: float
555 555 ------> float()
556 556 Out[2]: 0.0
557 557
558 558 Note that even with autocall off, you can still use '/' at the start of
559 559 a line to treat the first argument on the command line as a function
560 560 and add parentheses to it:
561 561
562 562 In [8]: /str 43
563 563 ------> str(43)
564 564 Out[8]: '43'
565 565
566 566 # all-random (note for auto-testing)
567 567 """
568 568
569 569 rc = self.shell.rc
570 570
571 571 if parameter_s:
572 572 arg = int(parameter_s)
573 573 else:
574 574 arg = 'toggle'
575 575
576 576 if not arg in (0,1,2,'toggle'):
577 577 error('Valid modes: (0->Off, 1->Smart, 2->Full')
578 578 return
579 579
580 580 if arg in (0,1,2):
581 581 rc.autocall = arg
582 582 else: # toggle
583 583 if rc.autocall:
584 584 self._magic_state.autocall_save = rc.autocall
585 585 rc.autocall = 0
586 586 else:
587 587 try:
588 588 rc.autocall = self._magic_state.autocall_save
589 589 except AttributeError:
590 590 rc.autocall = self._magic_state.autocall_save = 1
591 591
592 592 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
593 593
594 594 def magic_system_verbose(self, parameter_s = ''):
595 595 """Set verbose printing of system calls.
596 596
597 597 If called without an argument, act as a toggle"""
598 598
599 599 if parameter_s:
600 600 val = bool(eval(parameter_s))
601 601 else:
602 602 val = None
603 603
604 604 self.shell.rc_set_toggle('system_verbose',val)
605 605 print "System verbose printing is:",\
606 606 ['OFF','ON'][self.shell.rc.system_verbose]
607 607
608 608
609 609 def magic_page(self, parameter_s=''):
610 610 """Pretty print the object and display it through a pager.
611 611
612 612 %page [options] OBJECT
613 613
614 614 If no object is given, use _ (last output).
615 615
616 616 Options:
617 617
618 618 -r: page str(object), don't pretty-print it."""
619 619
620 620 # After a function contributed by Olivier Aubert, slightly modified.
621 621
622 622 # Process options/args
623 623 opts,args = self.parse_options(parameter_s,'r')
624 624 raw = 'r' in opts
625 625
626 626 oname = args and args or '_'
627 627 info = self._ofind(oname)
628 628 if info['found']:
629 629 txt = (raw and str or pformat)( info['obj'] )
630 630 page(txt)
631 631 else:
632 632 print 'Object `%s` not found' % oname
633 633
634 634 def magic_profile(self, parameter_s=''):
635 635 """Print your currently active IPyhton profile."""
636 636 if self.shell.rc.profile:
637 637 printpl('Current IPython profile: $self.shell.rc.profile.')
638 638 else:
639 639 print 'No profile active.'
640 640
641 641 def magic_pinfo(self, parameter_s='', namespaces=None):
642 642 """Provide detailed information about an object.
643 643
644 644 '%pinfo object' is just a synonym for object? or ?object."""
645 645
646 646 #print 'pinfo par: <%s>' % parameter_s # dbg
647 647
648 648
649 649 # detail_level: 0 -> obj? , 1 -> obj??
650 650 detail_level = 0
651 651 # We need to detect if we got called as 'pinfo pinfo foo', which can
652 652 # happen if the user types 'pinfo foo?' at the cmd line.
653 653 pinfo,qmark1,oname,qmark2 = \
654 654 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
655 655 if pinfo or qmark1 or qmark2:
656 656 detail_level = 1
657 657 if "*" in oname:
658 658 self.magic_psearch(oname)
659 659 else:
660 660 self._inspect('pinfo', oname, detail_level=detail_level,
661 661 namespaces=namespaces)
662 662
663 663 def magic_pdef(self, parameter_s='', namespaces=None):
664 664 """Print the definition header for any callable object.
665 665
666 666 If the object is a class, print the constructor information."""
667 667 self._inspect('pdef',parameter_s, namespaces)
668 668
669 669 def magic_pdoc(self, parameter_s='', namespaces=None):
670 670 """Print the docstring for an object.
671 671
672 672 If the given object is a class, it will print both the class and the
673 673 constructor docstrings."""
674 674 self._inspect('pdoc',parameter_s, namespaces)
675 675
676 676 def magic_psource(self, parameter_s='', namespaces=None):
677 677 """Print (or run through pager) the source code for an object."""
678 678 self._inspect('psource',parameter_s, namespaces)
679 679
680 680 def magic_pfile(self, parameter_s=''):
681 681 """Print (or run through pager) the file where an object is defined.
682 682
683 683 The file opens at the line where the object definition begins. IPython
684 684 will honor the environment variable PAGER if set, and otherwise will
685 685 do its best to print the file in a convenient form.
686 686
687 687 If the given argument is not an object currently defined, IPython will
688 688 try to interpret it as a filename (automatically adding a .py extension
689 689 if needed). You can thus use %pfile as a syntax highlighting code
690 690 viewer."""
691 691
692 692 # first interpret argument as an object name
693 693 out = self._inspect('pfile',parameter_s)
694 694 # if not, try the input as a filename
695 695 if out == 'not found':
696 696 try:
697 697 filename = get_py_filename(parameter_s)
698 698 except IOError,msg:
699 699 print msg
700 700 return
701 701 page(self.shell.inspector.format(file(filename).read()))
702 702
703 703 def _inspect(self,meth,oname,namespaces=None,**kw):
704 704 """Generic interface to the inspector system.
705 705
706 706 This function is meant to be called by pdef, pdoc & friends."""
707 707
708 708 #oname = oname.strip()
709 709 #print '1- oname: <%r>' % oname # dbg
710 710 try:
711 711 oname = oname.strip().encode('ascii')
712 712 #print '2- oname: <%r>' % oname # dbg
713 713 except UnicodeEncodeError:
714 714 print 'Python identifiers can only contain ascii characters.'
715 715 return 'not found'
716 716
717 717 info = Struct(self._ofind(oname, namespaces))
718 718
719 719 if info.found:
720 720 try:
721 721 IPython.utils.generics.inspect_object(info.obj)
722 722 return
723 723 except ipapi.TryNext:
724 724 pass
725 725 # Get the docstring of the class property if it exists.
726 726 path = oname.split('.')
727 727 root = '.'.join(path[:-1])
728 728 if info.parent is not None:
729 729 try:
730 730 target = getattr(info.parent, '__class__')
731 731 # The object belongs to a class instance.
732 732 try:
733 733 target = getattr(target, path[-1])
734 734 # The class defines the object.
735 735 if isinstance(target, property):
736 736 oname = root + '.__class__.' + path[-1]
737 737 info = Struct(self._ofind(oname))
738 738 except AttributeError: pass
739 739 except AttributeError: pass
740 740
741 741 pmethod = getattr(self.shell.inspector,meth)
742 742 formatter = info.ismagic and self.format_screen or None
743 743 if meth == 'pdoc':
744 744 pmethod(info.obj,oname,formatter)
745 745 elif meth == 'pinfo':
746 746 pmethod(info.obj,oname,formatter,info,**kw)
747 747 else:
748 748 pmethod(info.obj,oname)
749 749 else:
750 750 print 'Object `%s` not found.' % oname
751 751 return 'not found' # so callers can take other action
752 752
753 753 def magic_psearch(self, parameter_s=''):
754 754 """Search for object in namespaces by wildcard.
755 755
756 756 %psearch [options] PATTERN [OBJECT TYPE]
757 757
758 758 Note: ? can be used as a synonym for %psearch, at the beginning or at
759 759 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
760 760 rest of the command line must be unchanged (options come first), so
761 761 for example the following forms are equivalent
762 762
763 763 %psearch -i a* function
764 764 -i a* function?
765 765 ?-i a* function
766 766
767 767 Arguments:
768 768
769 769 PATTERN
770 770
771 771 where PATTERN is a string containing * as a wildcard similar to its
772 772 use in a shell. The pattern is matched in all namespaces on the
773 773 search path. By default objects starting with a single _ are not
774 774 matched, many IPython generated objects have a single
775 775 underscore. The default is case insensitive matching. Matching is
776 776 also done on the attributes of objects and not only on the objects
777 777 in a module.
778 778
779 779 [OBJECT TYPE]
780 780
781 781 Is the name of a python type from the types module. The name is
782 782 given in lowercase without the ending type, ex. StringType is
783 783 written string. By adding a type here only objects matching the
784 784 given type are matched. Using all here makes the pattern match all
785 785 types (this is the default).
786 786
787 787 Options:
788 788
789 789 -a: makes the pattern match even objects whose names start with a
790 790 single underscore. These names are normally ommitted from the
791 791 search.
792 792
793 793 -i/-c: make the pattern case insensitive/sensitive. If neither of
794 794 these options is given, the default is read from your ipythonrc
795 795 file. The option name which sets this value is
796 796 'wildcards_case_sensitive'. If this option is not specified in your
797 797 ipythonrc file, IPython's internal default is to do a case sensitive
798 798 search.
799 799
800 800 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
801 801 specifiy can be searched in any of the following namespaces:
802 802 'builtin', 'user', 'user_global','internal', 'alias', where
803 803 'builtin' and 'user' are the search defaults. Note that you should
804 804 not use quotes when specifying namespaces.
805 805
806 806 'Builtin' contains the python module builtin, 'user' contains all
807 807 user data, 'alias' only contain the shell aliases and no python
808 808 objects, 'internal' contains objects used by IPython. The
809 809 'user_global' namespace is only used by embedded IPython instances,
810 810 and it contains module-level globals. You can add namespaces to the
811 811 search with -s or exclude them with -e (these options can be given
812 812 more than once).
813 813
814 814 Examples:
815 815
816 816 %psearch a* -> objects beginning with an a
817 817 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
818 818 %psearch a* function -> all functions beginning with an a
819 819 %psearch re.e* -> objects beginning with an e in module re
820 820 %psearch r*.e* -> objects that start with e in modules starting in r
821 821 %psearch r*.* string -> all strings in modules beginning with r
822 822
823 823 Case sensitve search:
824 824
825 825 %psearch -c a* list all object beginning with lower case a
826 826
827 827 Show objects beginning with a single _:
828 828
829 829 %psearch -a _* list objects beginning with a single underscore"""
830 830 try:
831 831 parameter_s = parameter_s.encode('ascii')
832 832 except UnicodeEncodeError:
833 833 print 'Python identifiers can only contain ascii characters.'
834 834 return
835 835
836 836 # default namespaces to be searched
837 837 def_search = ['user','builtin']
838 838
839 839 # Process options/args
840 840 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
841 841 opt = opts.get
842 842 shell = self.shell
843 843 psearch = shell.inspector.psearch
844 844
845 845 # select case options
846 846 if opts.has_key('i'):
847 847 ignore_case = True
848 848 elif opts.has_key('c'):
849 849 ignore_case = False
850 850 else:
851 851 ignore_case = not shell.rc.wildcards_case_sensitive
852 852
853 853 # Build list of namespaces to search from user options
854 854 def_search.extend(opt('s',[]))
855 855 ns_exclude = ns_exclude=opt('e',[])
856 856 ns_search = [nm for nm in def_search if nm not in ns_exclude]
857 857
858 858 # Call the actual search
859 859 try:
860 860 psearch(args,shell.ns_table,ns_search,
861 861 show_all=opt('a'),ignore_case=ignore_case)
862 862 except:
863 863 shell.showtraceback()
864 864
865 865 def magic_who_ls(self, parameter_s=''):
866 866 """Return a sorted list of all interactive variables.
867 867
868 868 If arguments are given, only variables of types matching these
869 869 arguments are returned."""
870 870
871 871 user_ns = self.shell.user_ns
872 872 internal_ns = self.shell.internal_ns
873 873 user_config_ns = self.shell.user_config_ns
874 874 out = []
875 875 typelist = parameter_s.split()
876 876
877 877 for i in user_ns:
878 878 if not (i.startswith('_') or i.startswith('_i')) \
879 879 and not (i in internal_ns or i in user_config_ns):
880 880 if typelist:
881 881 if type(user_ns[i]).__name__ in typelist:
882 882 out.append(i)
883 883 else:
884 884 out.append(i)
885 885 out.sort()
886 886 return out
887 887
888 888 def magic_who(self, parameter_s=''):
889 889 """Print all interactive variables, with some minimal formatting.
890 890
891 891 If any arguments are given, only variables whose type matches one of
892 892 these are printed. For example:
893 893
894 894 %who function str
895 895
896 896 will only list functions and strings, excluding all other types of
897 897 variables. To find the proper type names, simply use type(var) at a
898 898 command line to see how python prints type names. For example:
899 899
900 900 In [1]: type('hello')\\
901 901 Out[1]: <type 'str'>
902 902
903 903 indicates that the type name for strings is 'str'.
904 904
905 905 %who always excludes executed names loaded through your configuration
906 906 file and things which are internal to IPython.
907 907
908 908 This is deliberate, as typically you may load many modules and the
909 909 purpose of %who is to show you only what you've manually defined."""
910 910
911 911 varlist = self.magic_who_ls(parameter_s)
912 912 if not varlist:
913 913 if parameter_s:
914 914 print 'No variables match your requested type.'
915 915 else:
916 916 print 'Interactive namespace is empty.'
917 917 return
918 918
919 919 # if we have variables, move on...
920 920 count = 0
921 921 for i in varlist:
922 922 print i+'\t',
923 923 count += 1
924 924 if count > 8:
925 925 count = 0
926 926 print
927 927 print
928 928
929 929 def magic_whos(self, parameter_s=''):
930 930 """Like %who, but gives some extra information about each variable.
931 931
932 932 The same type filtering of %who can be applied here.
933 933
934 934 For all variables, the type is printed. Additionally it prints:
935 935
936 936 - For {},[],(): their length.
937 937
938 938 - For numpy and Numeric arrays, a summary with shape, number of
939 939 elements, typecode and size in memory.
940 940
941 941 - Everything else: a string representation, snipping their middle if
942 942 too long."""
943 943
944 944 varnames = self.magic_who_ls(parameter_s)
945 945 if not varnames:
946 946 if parameter_s:
947 947 print 'No variables match your requested type.'
948 948 else:
949 949 print 'Interactive namespace is empty.'
950 950 return
951 951
952 952 # if we have variables, move on...
953 953
954 954 # for these types, show len() instead of data:
955 955 seq_types = [types.DictType,types.ListType,types.TupleType]
956 956
957 957 # for numpy/Numeric arrays, display summary info
958 958 try:
959 959 import numpy
960 960 except ImportError:
961 961 ndarray_type = None
962 962 else:
963 963 ndarray_type = numpy.ndarray.__name__
964 964 try:
965 965 import Numeric
966 966 except ImportError:
967 967 array_type = None
968 968 else:
969 969 array_type = Numeric.ArrayType.__name__
970 970
971 971 # Find all variable names and types so we can figure out column sizes
972 972 def get_vars(i):
973 973 return self.shell.user_ns[i]
974 974
975 975 # some types are well known and can be shorter
976 976 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
977 977 def type_name(v):
978 978 tn = type(v).__name__
979 979 return abbrevs.get(tn,tn)
980 980
981 981 varlist = map(get_vars,varnames)
982 982
983 983 typelist = []
984 984 for vv in varlist:
985 985 tt = type_name(vv)
986 986
987 987 if tt=='instance':
988 988 typelist.append( abbrevs.get(str(vv.__class__),
989 989 str(vv.__class__)))
990 990 else:
991 991 typelist.append(tt)
992 992
993 993 # column labels and # of spaces as separator
994 994 varlabel = 'Variable'
995 995 typelabel = 'Type'
996 996 datalabel = 'Data/Info'
997 997 colsep = 3
998 998 # variable format strings
999 999 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1000 1000 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1001 1001 aformat = "%s: %s elems, type `%s`, %s bytes"
1002 1002 # find the size of the columns to format the output nicely
1003 1003 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1004 1004 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1005 1005 # table header
1006 1006 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1007 1007 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1008 1008 # and the table itself
1009 1009 kb = 1024
1010 1010 Mb = 1048576 # kb**2
1011 1011 for vname,var,vtype in zip(varnames,varlist,typelist):
1012 1012 print itpl(vformat),
1013 1013 if vtype in seq_types:
1014 1014 print len(var)
1015 1015 elif vtype in [array_type,ndarray_type]:
1016 1016 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1017 1017 if vtype==ndarray_type:
1018 1018 # numpy
1019 1019 vsize = var.size
1020 1020 vbytes = vsize*var.itemsize
1021 1021 vdtype = var.dtype
1022 1022 else:
1023 1023 # Numeric
1024 1024 vsize = Numeric.size(var)
1025 1025 vbytes = vsize*var.itemsize()
1026 1026 vdtype = var.typecode()
1027 1027
1028 1028 if vbytes < 100000:
1029 1029 print aformat % (vshape,vsize,vdtype,vbytes)
1030 1030 else:
1031 1031 print aformat % (vshape,vsize,vdtype,vbytes),
1032 1032 if vbytes < Mb:
1033 1033 print '(%s kb)' % (vbytes/kb,)
1034 1034 else:
1035 1035 print '(%s Mb)' % (vbytes/Mb,)
1036 1036 else:
1037 1037 try:
1038 1038 vstr = str(var)
1039 1039 except UnicodeEncodeError:
1040 1040 vstr = unicode(var).encode(sys.getdefaultencoding(),
1041 1041 'backslashreplace')
1042 1042 vstr = vstr.replace('\n','\\n')
1043 1043 if len(vstr) < 50:
1044 1044 print vstr
1045 1045 else:
1046 1046 printpl(vfmt_short)
1047 1047
1048 1048 def magic_reset(self, parameter_s=''):
1049 1049 """Resets the namespace by removing all names defined by the user.
1050 1050
1051 1051 Input/Output history are left around in case you need them.
1052 1052
1053 1053 Parameters
1054 1054 ----------
1055 1055 -y : force reset without asking for confirmation.
1056 1056
1057 1057 Examples
1058 1058 --------
1059 1059 In [6]: a = 1
1060 1060
1061 1061 In [7]: a
1062 1062 Out[7]: 1
1063 1063
1064 1064 In [8]: 'a' in _ip.user_ns
1065 1065 Out[8]: True
1066 1066
1067 1067 In [9]: %reset -f
1068 1068
1069 1069 In [10]: 'a' in _ip.user_ns
1070 1070 Out[10]: False
1071 1071 """
1072 1072
1073 1073 if parameter_s == '-f':
1074 1074 ans = True
1075 1075 else:
1076 1076 ans = self.shell.ask_yes_no(
1077 1077 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1078 1078 if not ans:
1079 1079 print 'Nothing done.'
1080 1080 return
1081 1081 user_ns = self.shell.user_ns
1082 1082 for i in self.magic_who_ls():
1083 1083 del(user_ns[i])
1084 1084
1085 1085 # Also flush the private list of module references kept for script
1086 1086 # execution protection
1087 1087 self.shell.clear_main_mod_cache()
1088 1088
1089 1089 def magic_logstart(self,parameter_s=''):
1090 1090 """Start logging anywhere in a session.
1091 1091
1092 1092 %logstart [-o|-r|-t] [log_name [log_mode]]
1093 1093
1094 1094 If no name is given, it defaults to a file named 'ipython_log.py' in your
1095 1095 current directory, in 'rotate' mode (see below).
1096 1096
1097 1097 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1098 1098 history up to that point and then continues logging.
1099 1099
1100 1100 %logstart takes a second optional parameter: logging mode. This can be one
1101 1101 of (note that the modes are given unquoted):\\
1102 1102 append: well, that says it.\\
1103 1103 backup: rename (if exists) to name~ and start name.\\
1104 1104 global: single logfile in your home dir, appended to.\\
1105 1105 over : overwrite existing log.\\
1106 1106 rotate: create rotating logs name.1~, name.2~, etc.
1107 1107
1108 1108 Options:
1109 1109
1110 1110 -o: log also IPython's output. In this mode, all commands which
1111 1111 generate an Out[NN] prompt are recorded to the logfile, right after
1112 1112 their corresponding input line. The output lines are always
1113 1113 prepended with a '#[Out]# ' marker, so that the log remains valid
1114 1114 Python code.
1115 1115
1116 1116 Since this marker is always the same, filtering only the output from
1117 1117 a log is very easy, using for example a simple awk call:
1118 1118
1119 1119 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1120 1120
1121 1121 -r: log 'raw' input. Normally, IPython's logs contain the processed
1122 1122 input, so that user lines are logged in their final form, converted
1123 1123 into valid Python. For example, %Exit is logged as
1124 1124 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1125 1125 exactly as typed, with no transformations applied.
1126 1126
1127 1127 -t: put timestamps before each input line logged (these are put in
1128 1128 comments)."""
1129 1129
1130 1130 opts,par = self.parse_options(parameter_s,'ort')
1131 1131 log_output = 'o' in opts
1132 1132 log_raw_input = 'r' in opts
1133 1133 timestamp = 't' in opts
1134 1134
1135 1135 rc = self.shell.rc
1136 1136 logger = self.shell.logger
1137 1137
1138 1138 # if no args are given, the defaults set in the logger constructor by
1139 1139 # ipytohn remain valid
1140 1140 if par:
1141 1141 try:
1142 1142 logfname,logmode = par.split()
1143 1143 except:
1144 1144 logfname = par
1145 1145 logmode = 'backup'
1146 1146 else:
1147 1147 logfname = logger.logfname
1148 1148 logmode = logger.logmode
1149 1149 # put logfname into rc struct as if it had been called on the command
1150 1150 # line, so it ends up saved in the log header Save it in case we need
1151 1151 # to restore it...
1152 1152 old_logfile = rc.opts.get('logfile','')
1153 1153 if logfname:
1154 1154 logfname = os.path.expanduser(logfname)
1155 1155 rc.opts.logfile = logfname
1156 1156 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1157 1157 try:
1158 1158 started = logger.logstart(logfname,loghead,logmode,
1159 1159 log_output,timestamp,log_raw_input)
1160 1160 except:
1161 1161 rc.opts.logfile = old_logfile
1162 1162 warn("Couldn't start log: %s" % sys.exc_info()[1])
1163 1163 else:
1164 1164 # log input history up to this point, optionally interleaving
1165 1165 # output if requested
1166 1166
1167 1167 if timestamp:
1168 1168 # disable timestamping for the previous history, since we've
1169 1169 # lost those already (no time machine here).
1170 1170 logger.timestamp = False
1171 1171
1172 1172 if log_raw_input:
1173 1173 input_hist = self.shell.input_hist_raw
1174 1174 else:
1175 1175 input_hist = self.shell.input_hist
1176 1176
1177 1177 if log_output:
1178 1178 log_write = logger.log_write
1179 1179 output_hist = self.shell.output_hist
1180 1180 for n in range(1,len(input_hist)-1):
1181 1181 log_write(input_hist[n].rstrip())
1182 1182 if n in output_hist:
1183 1183 log_write(repr(output_hist[n]),'output')
1184 1184 else:
1185 1185 logger.log_write(input_hist[1:])
1186 1186 if timestamp:
1187 1187 # re-enable timestamping
1188 1188 logger.timestamp = True
1189 1189
1190 1190 print ('Activating auto-logging. '
1191 1191 'Current session state plus future input saved.')
1192 1192 logger.logstate()
1193 1193
1194 1194 def magic_logstop(self,parameter_s=''):
1195 1195 """Fully stop logging and close log file.
1196 1196
1197 1197 In order to start logging again, a new %logstart call needs to be made,
1198 1198 possibly (though not necessarily) with a new filename, mode and other
1199 1199 options."""
1200 1200 self.logger.logstop()
1201 1201
1202 1202 def magic_logoff(self,parameter_s=''):
1203 1203 """Temporarily stop logging.
1204 1204
1205 1205 You must have previously started logging."""
1206 1206 self.shell.logger.switch_log(0)
1207 1207
1208 1208 def magic_logon(self,parameter_s=''):
1209 1209 """Restart logging.
1210 1210
1211 1211 This function is for restarting logging which you've temporarily
1212 1212 stopped with %logoff. For starting logging for the first time, you
1213 1213 must use the %logstart function, which allows you to specify an
1214 1214 optional log filename."""
1215 1215
1216 1216 self.shell.logger.switch_log(1)
1217 1217
1218 1218 def magic_logstate(self,parameter_s=''):
1219 1219 """Print the status of the logging system."""
1220 1220
1221 1221 self.shell.logger.logstate()
1222 1222
1223 1223 def magic_pdb(self, parameter_s=''):
1224 1224 """Control the automatic calling of the pdb interactive debugger.
1225 1225
1226 1226 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1227 1227 argument it works as a toggle.
1228 1228
1229 1229 When an exception is triggered, IPython can optionally call the
1230 1230 interactive pdb debugger after the traceback printout. %pdb toggles
1231 1231 this feature on and off.
1232 1232
1233 1233 The initial state of this feature is set in your ipythonrc
1234 1234 configuration file (the variable is called 'pdb').
1235 1235
1236 1236 If you want to just activate the debugger AFTER an exception has fired,
1237 1237 without having to type '%pdb on' and rerunning your code, you can use
1238 1238 the %debug magic."""
1239 1239
1240 1240 par = parameter_s.strip().lower()
1241 1241
1242 1242 if par:
1243 1243 try:
1244 1244 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1245 1245 except KeyError:
1246 1246 print ('Incorrect argument. Use on/1, off/0, '
1247 1247 'or nothing for a toggle.')
1248 1248 return
1249 1249 else:
1250 1250 # toggle
1251 1251 new_pdb = not self.shell.call_pdb
1252 1252
1253 1253 # set on the shell
1254 1254 self.shell.call_pdb = new_pdb
1255 1255 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1256 1256
1257 1257 def magic_debug(self, parameter_s=''):
1258 1258 """Activate the interactive debugger in post-mortem mode.
1259 1259
1260 1260 If an exception has just occurred, this lets you inspect its stack
1261 1261 frames interactively. Note that this will always work only on the last
1262 1262 traceback that occurred, so you must call this quickly after an
1263 1263 exception that you wish to inspect has fired, because if another one
1264 1264 occurs, it clobbers the previous one.
1265 1265
1266 1266 If you want IPython to automatically do this on every exception, see
1267 1267 the %pdb magic for more details.
1268 1268 """
1269 1269
1270 1270 self.shell.debugger(force=True)
1271 1271
1272 1272 @testdec.skip_doctest
1273 1273 def magic_prun(self, parameter_s ='',user_mode=1,
1274 1274 opts=None,arg_lst=None,prog_ns=None):
1275 1275
1276 1276 """Run a statement through the python code profiler.
1277 1277
1278 1278 Usage:
1279 1279 %prun [options] statement
1280 1280
1281 1281 The given statement (which doesn't require quote marks) is run via the
1282 1282 python profiler in a manner similar to the profile.run() function.
1283 1283 Namespaces are internally managed to work correctly; profile.run
1284 1284 cannot be used in IPython because it makes certain assumptions about
1285 1285 namespaces which do not hold under IPython.
1286 1286
1287 1287 Options:
1288 1288
1289 1289 -l <limit>: you can place restrictions on what or how much of the
1290 1290 profile gets printed. The limit value can be:
1291 1291
1292 1292 * A string: only information for function names containing this string
1293 1293 is printed.
1294 1294
1295 1295 * An integer: only these many lines are printed.
1296 1296
1297 1297 * A float (between 0 and 1): this fraction of the report is printed
1298 1298 (for example, use a limit of 0.4 to see the topmost 40% only).
1299 1299
1300 1300 You can combine several limits with repeated use of the option. For
1301 1301 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1302 1302 information about class constructors.
1303 1303
1304 1304 -r: return the pstats.Stats object generated by the profiling. This
1305 1305 object has all the information about the profile in it, and you can
1306 1306 later use it for further analysis or in other functions.
1307 1307
1308 1308 -s <key>: sort profile by given key. You can provide more than one key
1309 1309 by using the option several times: '-s key1 -s key2 -s key3...'. The
1310 1310 default sorting key is 'time'.
1311 1311
1312 1312 The following is copied verbatim from the profile documentation
1313 1313 referenced below:
1314 1314
1315 1315 When more than one key is provided, additional keys are used as
1316 1316 secondary criteria when the there is equality in all keys selected
1317 1317 before them.
1318 1318
1319 1319 Abbreviations can be used for any key names, as long as the
1320 1320 abbreviation is unambiguous. The following are the keys currently
1321 1321 defined:
1322 1322
1323 1323 Valid Arg Meaning
1324 1324 "calls" call count
1325 1325 "cumulative" cumulative time
1326 1326 "file" file name
1327 1327 "module" file name
1328 1328 "pcalls" primitive call count
1329 1329 "line" line number
1330 1330 "name" function name
1331 1331 "nfl" name/file/line
1332 1332 "stdname" standard name
1333 1333 "time" internal time
1334 1334
1335 1335 Note that all sorts on statistics are in descending order (placing
1336 1336 most time consuming items first), where as name, file, and line number
1337 1337 searches are in ascending order (i.e., alphabetical). The subtle
1338 1338 distinction between "nfl" and "stdname" is that the standard name is a
1339 1339 sort of the name as printed, which means that the embedded line
1340 1340 numbers get compared in an odd way. For example, lines 3, 20, and 40
1341 1341 would (if the file names were the same) appear in the string order
1342 1342 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1343 1343 line numbers. In fact, sort_stats("nfl") is the same as
1344 1344 sort_stats("name", "file", "line").
1345 1345
1346 1346 -T <filename>: save profile results as shown on screen to a text
1347 1347 file. The profile is still shown on screen.
1348 1348
1349 1349 -D <filename>: save (via dump_stats) profile statistics to given
1350 1350 filename. This data is in a format understod by the pstats module, and
1351 1351 is generated by a call to the dump_stats() method of profile
1352 1352 objects. The profile is still shown on screen.
1353 1353
1354 1354 If you want to run complete programs under the profiler's control, use
1355 1355 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1356 1356 contains profiler specific options as described here.
1357 1357
1358 1358 You can read the complete documentation for the profile module with::
1359 1359
1360 1360 In [1]: import profile; profile.help()
1361 1361 """
1362 1362
1363 1363 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1364 1364 # protect user quote marks
1365 1365 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1366 1366
1367 1367 if user_mode: # regular user call
1368 1368 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1369 1369 list_all=1)
1370 1370 namespace = self.shell.user_ns
1371 1371 else: # called to run a program by %run -p
1372 1372 try:
1373 1373 filename = get_py_filename(arg_lst[0])
1374 1374 except IOError,msg:
1375 1375 error(msg)
1376 1376 return
1377 1377
1378 1378 arg_str = 'execfile(filename,prog_ns)'
1379 1379 namespace = locals()
1380 1380
1381 1381 opts.merge(opts_def)
1382 1382
1383 1383 prof = profile.Profile()
1384 1384 try:
1385 1385 prof = prof.runctx(arg_str,namespace,namespace)
1386 1386 sys_exit = ''
1387 1387 except SystemExit:
1388 1388 sys_exit = """*** SystemExit exception caught in code being profiled."""
1389 1389
1390 1390 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1391 1391
1392 1392 lims = opts.l
1393 1393 if lims:
1394 1394 lims = [] # rebuild lims with ints/floats/strings
1395 1395 for lim in opts.l:
1396 1396 try:
1397 1397 lims.append(int(lim))
1398 1398 except ValueError:
1399 1399 try:
1400 1400 lims.append(float(lim))
1401 1401 except ValueError:
1402 1402 lims.append(lim)
1403 1403
1404 1404 # Trap output.
1405 1405 stdout_trap = StringIO()
1406 1406
1407 1407 if hasattr(stats,'stream'):
1408 1408 # In newer versions of python, the stats object has a 'stream'
1409 1409 # attribute to write into.
1410 1410 stats.stream = stdout_trap
1411 1411 stats.print_stats(*lims)
1412 1412 else:
1413 1413 # For older versions, we manually redirect stdout during printing
1414 1414 sys_stdout = sys.stdout
1415 1415 try:
1416 1416 sys.stdout = stdout_trap
1417 1417 stats.print_stats(*lims)
1418 1418 finally:
1419 1419 sys.stdout = sys_stdout
1420 1420
1421 1421 output = stdout_trap.getvalue()
1422 1422 output = output.rstrip()
1423 1423
1424 1424 page(output,screen_lines=self.shell.rc.screen_length)
1425 1425 print sys_exit,
1426 1426
1427 1427 dump_file = opts.D[0]
1428 1428 text_file = opts.T[0]
1429 1429 if dump_file:
1430 1430 prof.dump_stats(dump_file)
1431 1431 print '\n*** Profile stats marshalled to file',\
1432 1432 `dump_file`+'.',sys_exit
1433 1433 if text_file:
1434 1434 pfile = file(text_file,'w')
1435 1435 pfile.write(output)
1436 1436 pfile.close()
1437 1437 print '\n*** Profile printout saved to text file',\
1438 1438 `text_file`+'.',sys_exit
1439 1439
1440 1440 if opts.has_key('r'):
1441 1441 return stats
1442 1442 else:
1443 1443 return None
1444 1444
1445 1445 @testdec.skip_doctest
1446 1446 def magic_run(self, parameter_s ='',runner=None,
1447 1447 file_finder=get_py_filename):
1448 1448 """Run the named file inside IPython as a program.
1449 1449
1450 1450 Usage:\\
1451 1451 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1452 1452
1453 1453 Parameters after the filename are passed as command-line arguments to
1454 1454 the program (put in sys.argv). Then, control returns to IPython's
1455 1455 prompt.
1456 1456
1457 1457 This is similar to running at a system prompt:\\
1458 1458 $ python file args\\
1459 1459 but with the advantage of giving you IPython's tracebacks, and of
1460 1460 loading all variables into your interactive namespace for further use
1461 1461 (unless -p is used, see below).
1462 1462
1463 1463 The file is executed in a namespace initially consisting only of
1464 1464 __name__=='__main__' and sys.argv constructed as indicated. It thus
1465 1465 sees its environment as if it were being run as a stand-alone program
1466 1466 (except for sharing global objects such as previously imported
1467 1467 modules). But after execution, the IPython interactive namespace gets
1468 1468 updated with all variables defined in the program (except for __name__
1469 1469 and sys.argv). This allows for very convenient loading of code for
1470 1470 interactive work, while giving each program a 'clean sheet' to run in.
1471 1471
1472 1472 Options:
1473 1473
1474 1474 -n: __name__ is NOT set to '__main__', but to the running file's name
1475 1475 without extension (as python does under import). This allows running
1476 1476 scripts and reloading the definitions in them without calling code
1477 1477 protected by an ' if __name__ == "__main__" ' clause.
1478 1478
1479 1479 -i: run the file in IPython's namespace instead of an empty one. This
1480 1480 is useful if you are experimenting with code written in a text editor
1481 1481 which depends on variables defined interactively.
1482 1482
1483 1483 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1484 1484 being run. This is particularly useful if IPython is being used to
1485 1485 run unittests, which always exit with a sys.exit() call. In such
1486 1486 cases you are interested in the output of the test results, not in
1487 1487 seeing a traceback of the unittest module.
1488 1488
1489 1489 -t: print timing information at the end of the run. IPython will give
1490 1490 you an estimated CPU time consumption for your script, which under
1491 1491 Unix uses the resource module to avoid the wraparound problems of
1492 1492 time.clock(). Under Unix, an estimate of time spent on system tasks
1493 1493 is also given (for Windows platforms this is reported as 0.0).
1494 1494
1495 1495 If -t is given, an additional -N<N> option can be given, where <N>
1496 1496 must be an integer indicating how many times you want the script to
1497 1497 run. The final timing report will include total and per run results.
1498 1498
1499 1499 For example (testing the script uniq_stable.py):
1500 1500
1501 1501 In [1]: run -t uniq_stable
1502 1502
1503 1503 IPython CPU timings (estimated):\\
1504 1504 User : 0.19597 s.\\
1505 1505 System: 0.0 s.\\
1506 1506
1507 1507 In [2]: run -t -N5 uniq_stable
1508 1508
1509 1509 IPython CPU timings (estimated):\\
1510 1510 Total runs performed: 5\\
1511 1511 Times : Total Per run\\
1512 1512 User : 0.910862 s, 0.1821724 s.\\
1513 1513 System: 0.0 s, 0.0 s.
1514 1514
1515 1515 -d: run your program under the control of pdb, the Python debugger.
1516 1516 This allows you to execute your program step by step, watch variables,
1517 1517 etc. Internally, what IPython does is similar to calling:
1518 1518
1519 1519 pdb.run('execfile("YOURFILENAME")')
1520 1520
1521 1521 with a breakpoint set on line 1 of your file. You can change the line
1522 1522 number for this automatic breakpoint to be <N> by using the -bN option
1523 1523 (where N must be an integer). For example:
1524 1524
1525 1525 %run -d -b40 myscript
1526 1526
1527 1527 will set the first breakpoint at line 40 in myscript.py. Note that
1528 1528 the first breakpoint must be set on a line which actually does
1529 1529 something (not a comment or docstring) for it to stop execution.
1530 1530
1531 1531 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1532 1532 first enter 'c' (without qoutes) to start execution up to the first
1533 1533 breakpoint.
1534 1534
1535 1535 Entering 'help' gives information about the use of the debugger. You
1536 1536 can easily see pdb's full documentation with "import pdb;pdb.help()"
1537 1537 at a prompt.
1538 1538
1539 1539 -p: run program under the control of the Python profiler module (which
1540 1540 prints a detailed report of execution times, function calls, etc).
1541 1541
1542 1542 You can pass other options after -p which affect the behavior of the
1543 1543 profiler itself. See the docs for %prun for details.
1544 1544
1545 1545 In this mode, the program's variables do NOT propagate back to the
1546 1546 IPython interactive namespace (because they remain in the namespace
1547 1547 where the profiler executes them).
1548 1548
1549 1549 Internally this triggers a call to %prun, see its documentation for
1550 1550 details on the options available specifically for profiling.
1551 1551
1552 1552 There is one special usage for which the text above doesn't apply:
1553 1553 if the filename ends with .ipy, the file is run as ipython script,
1554 1554 just as if the commands were written on IPython prompt.
1555 1555 """
1556 1556
1557 1557 # get arguments and set sys.argv for program to be run.
1558 1558 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1559 1559 mode='list',list_all=1)
1560 1560
1561 1561 try:
1562 1562 filename = file_finder(arg_lst[0])
1563 1563 except IndexError:
1564 1564 warn('you must provide at least a filename.')
1565 1565 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1566 1566 return
1567 1567 except IOError,msg:
1568 1568 error(msg)
1569 1569 return
1570 1570
1571 1571 if filename.lower().endswith('.ipy'):
1572 1572 self.api.runlines(open(filename).read())
1573 1573 return
1574 1574
1575 1575 # Control the response to exit() calls made by the script being run
1576 1576 exit_ignore = opts.has_key('e')
1577 1577
1578 1578 # Make sure that the running script gets a proper sys.argv as if it
1579 1579 # were run from a system shell.
1580 1580 save_argv = sys.argv # save it for later restoring
1581 1581 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1582 1582
1583 1583 if opts.has_key('i'):
1584 1584 # Run in user's interactive namespace
1585 1585 prog_ns = self.shell.user_ns
1586 1586 __name__save = self.shell.user_ns['__name__']
1587 1587 prog_ns['__name__'] = '__main__'
1588 1588 main_mod = self.shell.new_main_mod(prog_ns)
1589 1589 else:
1590 1590 # Run in a fresh, empty namespace
1591 1591 if opts.has_key('n'):
1592 1592 name = os.path.splitext(os.path.basename(filename))[0]
1593 1593 else:
1594 1594 name = '__main__'
1595 1595
1596 1596 main_mod = self.shell.new_main_mod()
1597 1597 prog_ns = main_mod.__dict__
1598 1598 prog_ns['__name__'] = name
1599 1599
1600 1600 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1601 1601 # set the __file__ global in the script's namespace
1602 1602 prog_ns['__file__'] = filename
1603 1603
1604 1604 # pickle fix. See iplib for an explanation. But we need to make sure
1605 1605 # that, if we overwrite __main__, we replace it at the end
1606 1606 main_mod_name = prog_ns['__name__']
1607 1607
1608 1608 if main_mod_name == '__main__':
1609 1609 restore_main = sys.modules['__main__']
1610 1610 else:
1611 1611 restore_main = False
1612 1612
1613 1613 # This needs to be undone at the end to prevent holding references to
1614 1614 # every single object ever created.
1615 1615 sys.modules[main_mod_name] = main_mod
1616 1616
1617 1617 stats = None
1618 1618 try:
1619 1619 self.shell.savehist()
1620 1620
1621 1621 if opts.has_key('p'):
1622 1622 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1623 1623 else:
1624 1624 if opts.has_key('d'):
1625 1625 deb = debugger.Pdb(self.shell.rc.colors)
1626 1626 # reset Breakpoint state, which is moronically kept
1627 1627 # in a class
1628 1628 bdb.Breakpoint.next = 1
1629 1629 bdb.Breakpoint.bplist = {}
1630 1630 bdb.Breakpoint.bpbynumber = [None]
1631 1631 # Set an initial breakpoint to stop execution
1632 1632 maxtries = 10
1633 1633 bp = int(opts.get('b',[1])[0])
1634 1634 checkline = deb.checkline(filename,bp)
1635 1635 if not checkline:
1636 1636 for bp in range(bp+1,bp+maxtries+1):
1637 1637 if deb.checkline(filename,bp):
1638 1638 break
1639 1639 else:
1640 1640 msg = ("\nI failed to find a valid line to set "
1641 1641 "a breakpoint\n"
1642 1642 "after trying up to line: %s.\n"
1643 1643 "Please set a valid breakpoint manually "
1644 1644 "with the -b option." % bp)
1645 1645 error(msg)
1646 1646 return
1647 1647 # if we find a good linenumber, set the breakpoint
1648 1648 deb.do_break('%s:%s' % (filename,bp))
1649 1649 # Start file run
1650 1650 print "NOTE: Enter 'c' at the",
1651 1651 print "%s prompt to start your script." % deb.prompt
1652 1652 try:
1653 1653 deb.run('execfile("%s")' % filename,prog_ns)
1654 1654
1655 1655 except:
1656 1656 etype, value, tb = sys.exc_info()
1657 1657 # Skip three frames in the traceback: the %run one,
1658 1658 # one inside bdb.py, and the command-line typed by the
1659 1659 # user (run by exec in pdb itself).
1660 1660 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1661 1661 else:
1662 1662 if runner is None:
1663 1663 runner = self.shell.safe_execfile
1664 1664 if opts.has_key('t'):
1665 1665 # timed execution
1666 1666 try:
1667 1667 nruns = int(opts['N'][0])
1668 1668 if nruns < 1:
1669 1669 error('Number of runs must be >=1')
1670 1670 return
1671 1671 except (KeyError):
1672 1672 nruns = 1
1673 1673 if nruns == 1:
1674 1674 t0 = clock2()
1675 1675 runner(filename,prog_ns,prog_ns,
1676 1676 exit_ignore=exit_ignore)
1677 1677 t1 = clock2()
1678 1678 t_usr = t1[0]-t0[0]
1679 1679 t_sys = t1[1]-t0[1]
1680 1680 print "\nIPython CPU timings (estimated):"
1681 1681 print " User : %10s s." % t_usr
1682 1682 print " System: %10s s." % t_sys
1683 1683 else:
1684 1684 runs = range(nruns)
1685 1685 t0 = clock2()
1686 1686 for nr in runs:
1687 1687 runner(filename,prog_ns,prog_ns,
1688 1688 exit_ignore=exit_ignore)
1689 1689 t1 = clock2()
1690 1690 t_usr = t1[0]-t0[0]
1691 1691 t_sys = t1[1]-t0[1]
1692 1692 print "\nIPython CPU timings (estimated):"
1693 1693 print "Total runs performed:",nruns
1694 1694 print " Times : %10s %10s" % ('Total','Per run')
1695 1695 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1696 1696 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1697 1697
1698 1698 else:
1699 1699 # regular execution
1700 1700 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1701 1701
1702 1702 if opts.has_key('i'):
1703 1703 self.shell.user_ns['__name__'] = __name__save
1704 1704 else:
1705 1705 # The shell MUST hold a reference to prog_ns so after %run
1706 1706 # exits, the python deletion mechanism doesn't zero it out
1707 1707 # (leaving dangling references).
1708 1708 self.shell.cache_main_mod(prog_ns,filename)
1709 1709 # update IPython interactive namespace
1710 1710 del prog_ns['__name__']
1711 1711 self.shell.user_ns.update(prog_ns)
1712 1712 finally:
1713 1713 # It's a bit of a mystery why, but __builtins__ can change from
1714 1714 # being a module to becoming a dict missing some key data after
1715 1715 # %run. As best I can see, this is NOT something IPython is doing
1716 1716 # at all, and similar problems have been reported before:
1717 1717 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1718 1718 # Since this seems to be done by the interpreter itself, the best
1719 1719 # we can do is to at least restore __builtins__ for the user on
1720 1720 # exit.
1721 1721 self.shell.user_ns['__builtins__'] = __builtin__
1722 1722
1723 1723 # Ensure key global structures are restored
1724 1724 sys.argv = save_argv
1725 1725 if restore_main:
1726 1726 sys.modules['__main__'] = restore_main
1727 1727 else:
1728 1728 # Remove from sys.modules the reference to main_mod we'd
1729 1729 # added. Otherwise it will trap references to objects
1730 1730 # contained therein.
1731 1731 del sys.modules[main_mod_name]
1732 1732
1733 1733 self.shell.reloadhist()
1734 1734
1735 1735 return stats
1736 1736
1737 1737 def magic_runlog(self, parameter_s =''):
1738 1738 """Run files as logs.
1739 1739
1740 1740 Usage:\\
1741 1741 %runlog file1 file2 ...
1742 1742
1743 1743 Run the named files (treating them as log files) in sequence inside
1744 1744 the interpreter, and return to the prompt. This is much slower than
1745 1745 %run because each line is executed in a try/except block, but it
1746 1746 allows running files with syntax errors in them.
1747 1747
1748 1748 Normally IPython will guess when a file is one of its own logfiles, so
1749 1749 you can typically use %run even for logs. This shorthand allows you to
1750 1750 force any file to be treated as a log file."""
1751 1751
1752 1752 for f in parameter_s.split():
1753 1753 self.shell.safe_execfile(f,self.shell.user_ns,
1754 1754 self.shell.user_ns,islog=1)
1755 1755
1756 1756 @testdec.skip_doctest
1757 1757 def magic_timeit(self, parameter_s =''):
1758 1758 """Time execution of a Python statement or expression
1759 1759
1760 1760 Usage:\\
1761 1761 %timeit [-n<N> -r<R> [-t|-c]] statement
1762 1762
1763 1763 Time execution of a Python statement or expression using the timeit
1764 1764 module.
1765 1765
1766 1766 Options:
1767 1767 -n<N>: execute the given statement <N> times in a loop. If this value
1768 1768 is not given, a fitting value is chosen.
1769 1769
1770 1770 -r<R>: repeat the loop iteration <R> times and take the best result.
1771 1771 Default: 3
1772 1772
1773 1773 -t: use time.time to measure the time, which is the default on Unix.
1774 1774 This function measures wall time.
1775 1775
1776 1776 -c: use time.clock to measure the time, which is the default on
1777 1777 Windows and measures wall time. On Unix, resource.getrusage is used
1778 1778 instead and returns the CPU user time.
1779 1779
1780 1780 -p<P>: use a precision of <P> digits to display the timing result.
1781 1781 Default: 3
1782 1782
1783 1783
1784 1784 Examples:
1785 1785
1786 1786 In [1]: %timeit pass
1787 1787 10000000 loops, best of 3: 53.3 ns per loop
1788 1788
1789 1789 In [2]: u = None
1790 1790
1791 1791 In [3]: %timeit u is None
1792 1792 10000000 loops, best of 3: 184 ns per loop
1793 1793
1794 1794 In [4]: %timeit -r 4 u == None
1795 1795 1000000 loops, best of 4: 242 ns per loop
1796 1796
1797 1797 In [5]: import time
1798 1798
1799 1799 In [6]: %timeit -n1 time.sleep(2)
1800 1800 1 loops, best of 3: 2 s per loop
1801 1801
1802 1802
1803 1803 The times reported by %timeit will be slightly higher than those
1804 1804 reported by the timeit.py script when variables are accessed. This is
1805 1805 due to the fact that %timeit executes the statement in the namespace
1806 1806 of the shell, compared with timeit.py, which uses a single setup
1807 1807 statement to import function or create variables. Generally, the bias
1808 1808 does not matter as long as results from timeit.py are not mixed with
1809 1809 those from %timeit."""
1810 1810
1811 1811 import timeit
1812 1812 import math
1813 1813
1814 1814 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1815 1815 # certain terminals. Until we figure out a robust way of
1816 1816 # auto-detecting if the terminal can deal with it, use plain 'us' for
1817 1817 # microseconds. I am really NOT happy about disabling the proper
1818 1818 # 'micro' prefix, but crashing is worse... If anyone knows what the
1819 1819 # right solution for this is, I'm all ears...
1820 1820 #
1821 1821 # Note: using
1822 1822 #
1823 1823 # s = u'\xb5'
1824 1824 # s.encode(sys.getdefaultencoding())
1825 1825 #
1826 1826 # is not sufficient, as I've seen terminals where that fails but
1827 1827 # print s
1828 1828 #
1829 1829 # succeeds
1830 1830 #
1831 1831 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1832 1832
1833 1833 #units = [u"s", u"ms",u'\xb5',"ns"]
1834 1834 units = [u"s", u"ms",u'us',"ns"]
1835 1835
1836 1836 scaling = [1, 1e3, 1e6, 1e9]
1837 1837
1838 1838 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1839 1839 posix=False)
1840 1840 if stmt == "":
1841 1841 return
1842 1842 timefunc = timeit.default_timer
1843 1843 number = int(getattr(opts, "n", 0))
1844 1844 repeat = int(getattr(opts, "r", timeit.default_repeat))
1845 1845 precision = int(getattr(opts, "p", 3))
1846 1846 if hasattr(opts, "t"):
1847 1847 timefunc = time.time
1848 1848 if hasattr(opts, "c"):
1849 1849 timefunc = clock
1850 1850
1851 1851 timer = timeit.Timer(timer=timefunc)
1852 1852 # this code has tight coupling to the inner workings of timeit.Timer,
1853 1853 # but is there a better way to achieve that the code stmt has access
1854 1854 # to the shell namespace?
1855 1855
1856 1856 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1857 1857 'setup': "pass"}
1858 1858 # Track compilation time so it can be reported if too long
1859 1859 # Minimum time above which compilation time will be reported
1860 1860 tc_min = 0.1
1861 1861
1862 1862 t0 = clock()
1863 1863 code = compile(src, "<magic-timeit>", "exec")
1864 1864 tc = clock()-t0
1865 1865
1866 1866 ns = {}
1867 1867 exec code in self.shell.user_ns, ns
1868 1868 timer.inner = ns["inner"]
1869 1869
1870 1870 if number == 0:
1871 1871 # determine number so that 0.2 <= total time < 2.0
1872 1872 number = 1
1873 1873 for i in range(1, 10):
1874 1874 if timer.timeit(number) >= 0.2:
1875 1875 break
1876 1876 number *= 10
1877 1877
1878 1878 best = min(timer.repeat(repeat, number)) / number
1879 1879
1880 1880 if best > 0.0:
1881 1881 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1882 1882 else:
1883 1883 order = 3
1884 1884 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1885 1885 precision,
1886 1886 best * scaling[order],
1887 1887 units[order])
1888 1888 if tc > tc_min:
1889 1889 print "Compiler time: %.2f s" % tc
1890 1890
1891 1891 @testdec.skip_doctest
1892 1892 def magic_time(self,parameter_s = ''):
1893 1893 """Time execution of a Python statement or expression.
1894 1894
1895 1895 The CPU and wall clock times are printed, and the value of the
1896 1896 expression (if any) is returned. Note that under Win32, system time
1897 1897 is always reported as 0, since it can not be measured.
1898 1898
1899 1899 This function provides very basic timing functionality. In Python
1900 1900 2.3, the timeit module offers more control and sophistication, so this
1901 1901 could be rewritten to use it (patches welcome).
1902 1902
1903 1903 Some examples:
1904 1904
1905 1905 In [1]: time 2**128
1906 1906 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1907 1907 Wall time: 0.00
1908 1908 Out[1]: 340282366920938463463374607431768211456L
1909 1909
1910 1910 In [2]: n = 1000000
1911 1911
1912 1912 In [3]: time sum(range(n))
1913 1913 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1914 1914 Wall time: 1.37
1915 1915 Out[3]: 499999500000L
1916 1916
1917 1917 In [4]: time print 'hello world'
1918 1918 hello world
1919 1919 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1920 1920 Wall time: 0.00
1921 1921
1922 1922 Note that the time needed by Python to compile the given expression
1923 1923 will be reported if it is more than 0.1s. In this example, the
1924 1924 actual exponentiation is done by Python at compilation time, so while
1925 1925 the expression can take a noticeable amount of time to compute, that
1926 1926 time is purely due to the compilation:
1927 1927
1928 1928 In [5]: time 3**9999;
1929 1929 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1930 1930 Wall time: 0.00 s
1931 1931
1932 1932 In [6]: time 3**999999;
1933 1933 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1934 1934 Wall time: 0.00 s
1935 1935 Compiler : 0.78 s
1936 1936 """
1937 1937
1938 1938 # fail immediately if the given expression can't be compiled
1939 1939
1940 1940 expr = self.shell.prefilter(parameter_s,False)
1941 1941
1942 1942 # Minimum time above which compilation time will be reported
1943 1943 tc_min = 0.1
1944 1944
1945 1945 try:
1946 1946 mode = 'eval'
1947 1947 t0 = clock()
1948 1948 code = compile(expr,'<timed eval>',mode)
1949 1949 tc = clock()-t0
1950 1950 except SyntaxError:
1951 1951 mode = 'exec'
1952 1952 t0 = clock()
1953 1953 code = compile(expr,'<timed exec>',mode)
1954 1954 tc = clock()-t0
1955 1955 # skew measurement as little as possible
1956 1956 glob = self.shell.user_ns
1957 1957 clk = clock2
1958 1958 wtime = time.time
1959 1959 # time execution
1960 1960 wall_st = wtime()
1961 1961 if mode=='eval':
1962 1962 st = clk()
1963 1963 out = eval(code,glob)
1964 1964 end = clk()
1965 1965 else:
1966 1966 st = clk()
1967 1967 exec code in glob
1968 1968 end = clk()
1969 1969 out = None
1970 1970 wall_end = wtime()
1971 1971 # Compute actual times and report
1972 1972 wall_time = wall_end-wall_st
1973 1973 cpu_user = end[0]-st[0]
1974 1974 cpu_sys = end[1]-st[1]
1975 1975 cpu_tot = cpu_user+cpu_sys
1976 1976 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1977 1977 (cpu_user,cpu_sys,cpu_tot)
1978 1978 print "Wall time: %.2f s" % wall_time
1979 1979 if tc > tc_min:
1980 1980 print "Compiler : %.2f s" % tc
1981 1981 return out
1982 1982
1983 1983 @testdec.skip_doctest
1984 1984 def magic_macro(self,parameter_s = ''):
1985 1985 """Define a set of input lines as a macro for future re-execution.
1986 1986
1987 1987 Usage:\\
1988 1988 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1989 1989
1990 1990 Options:
1991 1991
1992 1992 -r: use 'raw' input. By default, the 'processed' history is used,
1993 1993 so that magics are loaded in their transformed version to valid
1994 1994 Python. If this option is given, the raw input as typed as the
1995 1995 command line is used instead.
1996 1996
1997 1997 This will define a global variable called `name` which is a string
1998 1998 made of joining the slices and lines you specify (n1,n2,... numbers
1999 1999 above) from your input history into a single string. This variable
2000 2000 acts like an automatic function which re-executes those lines as if
2001 2001 you had typed them. You just type 'name' at the prompt and the code
2002 2002 executes.
2003 2003
2004 2004 The notation for indicating number ranges is: n1-n2 means 'use line
2005 2005 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2006 2006 using the lines numbered 5,6 and 7.
2007 2007
2008 2008 Note: as a 'hidden' feature, you can also use traditional python slice
2009 2009 notation, where N:M means numbers N through M-1.
2010 2010
2011 2011 For example, if your history contains (%hist prints it):
2012 2012
2013 2013 44: x=1
2014 2014 45: y=3
2015 2015 46: z=x+y
2016 2016 47: print x
2017 2017 48: a=5
2018 2018 49: print 'x',x,'y',y
2019 2019
2020 2020 you can create a macro with lines 44 through 47 (included) and line 49
2021 2021 called my_macro with:
2022 2022
2023 2023 In [55]: %macro my_macro 44-47 49
2024 2024
2025 2025 Now, typing `my_macro` (without quotes) will re-execute all this code
2026 2026 in one pass.
2027 2027
2028 2028 You don't need to give the line-numbers in order, and any given line
2029 2029 number can appear multiple times. You can assemble macros with any
2030 2030 lines from your input history in any order.
2031 2031
2032 2032 The macro is a simple object which holds its value in an attribute,
2033 2033 but IPython's display system checks for macros and executes them as
2034 2034 code instead of printing them when you type their name.
2035 2035
2036 2036 You can view a macro's contents by explicitly printing it with:
2037 2037
2038 2038 'print macro_name'.
2039 2039
2040 2040 For one-off cases which DON'T contain magic function calls in them you
2041 2041 can obtain similar results by explicitly executing slices from your
2042 2042 input history with:
2043 2043
2044 2044 In [60]: exec In[44:48]+In[49]"""
2045 2045
2046 2046 opts,args = self.parse_options(parameter_s,'r',mode='list')
2047 2047 if not args:
2048 2048 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2049 2049 macs.sort()
2050 2050 return macs
2051 2051 if len(args) == 1:
2052 2052 raise UsageError(
2053 2053 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2054 2054 name,ranges = args[0], args[1:]
2055 2055
2056 2056 #print 'rng',ranges # dbg
2057 2057 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2058 2058 macro = Macro(lines)
2059 2059 self.shell.user_ns.update({name:macro})
2060 2060 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2061 2061 print 'Macro contents:'
2062 2062 print macro,
2063 2063
2064 2064 def magic_save(self,parameter_s = ''):
2065 2065 """Save a set of lines to a given filename.
2066 2066
2067 2067 Usage:\\
2068 2068 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2069 2069
2070 2070 Options:
2071 2071
2072 2072 -r: use 'raw' input. By default, the 'processed' history is used,
2073 2073 so that magics are loaded in their transformed version to valid
2074 2074 Python. If this option is given, the raw input as typed as the
2075 2075 command line is used instead.
2076 2076
2077 2077 This function uses the same syntax as %macro for line extraction, but
2078 2078 instead of creating a macro it saves the resulting string to the
2079 2079 filename you specify.
2080 2080
2081 2081 It adds a '.py' extension to the file if you don't do so yourself, and
2082 2082 it asks for confirmation before overwriting existing files."""
2083 2083
2084 2084 opts,args = self.parse_options(parameter_s,'r',mode='list')
2085 2085 fname,ranges = args[0], args[1:]
2086 2086 if not fname.endswith('.py'):
2087 2087 fname += '.py'
2088 2088 if os.path.isfile(fname):
2089 2089 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2090 2090 if ans.lower() not in ['y','yes']:
2091 2091 print 'Operation cancelled.'
2092 2092 return
2093 2093 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2094 2094 f = file(fname,'w')
2095 2095 f.write(cmds)
2096 2096 f.close()
2097 2097 print 'The following commands were written to file `%s`:' % fname
2098 2098 print cmds
2099 2099
2100 2100 def _edit_macro(self,mname,macro):
2101 2101 """open an editor with the macro data in a file"""
2102 2102 filename = self.shell.mktempfile(macro.value)
2103 2103 self.shell.hooks.editor(filename)
2104 2104
2105 2105 # and make a new macro object, to replace the old one
2106 2106 mfile = open(filename)
2107 2107 mvalue = mfile.read()
2108 2108 mfile.close()
2109 2109 self.shell.user_ns[mname] = Macro(mvalue)
2110 2110
2111 2111 def magic_ed(self,parameter_s=''):
2112 2112 """Alias to %edit."""
2113 2113 return self.magic_edit(parameter_s)
2114 2114
2115 2115 @testdec.skip_doctest
2116 2116 def magic_edit(self,parameter_s='',last_call=['','']):
2117 2117 """Bring up an editor and execute the resulting code.
2118 2118
2119 2119 Usage:
2120 2120 %edit [options] [args]
2121 2121
2122 2122 %edit runs IPython's editor hook. The default version of this hook is
2123 2123 set to call the __IPYTHON__.rc.editor command. This is read from your
2124 2124 environment variable $EDITOR. If this isn't found, it will default to
2125 2125 vi under Linux/Unix and to notepad under Windows. See the end of this
2126 2126 docstring for how to change the editor hook.
2127 2127
2128 2128 You can also set the value of this editor via the command line option
2129 2129 '-editor' or in your ipythonrc file. This is useful if you wish to use
2130 2130 specifically for IPython an editor different from your typical default
2131 2131 (and for Windows users who typically don't set environment variables).
2132 2132
2133 2133 This command allows you to conveniently edit multi-line code right in
2134 2134 your IPython session.
2135 2135
2136 2136 If called without arguments, %edit opens up an empty editor with a
2137 2137 temporary file and will execute the contents of this file when you
2138 2138 close it (don't forget to save it!).
2139 2139
2140 2140
2141 2141 Options:
2142 2142
2143 2143 -n <number>: open the editor at a specified line number. By default,
2144 2144 the IPython editor hook uses the unix syntax 'editor +N filename', but
2145 2145 you can configure this by providing your own modified hook if your
2146 2146 favorite editor supports line-number specifications with a different
2147 2147 syntax.
2148 2148
2149 2149 -p: this will call the editor with the same data as the previous time
2150 2150 it was used, regardless of how long ago (in your current session) it
2151 2151 was.
2152 2152
2153 2153 -r: use 'raw' input. This option only applies to input taken from the
2154 2154 user's history. By default, the 'processed' history is used, so that
2155 2155 magics are loaded in their transformed version to valid Python. If
2156 2156 this option is given, the raw input as typed as the command line is
2157 2157 used instead. When you exit the editor, it will be executed by
2158 2158 IPython's own processor.
2159 2159
2160 2160 -x: do not execute the edited code immediately upon exit. This is
2161 2161 mainly useful if you are editing programs which need to be called with
2162 2162 command line arguments, which you can then do using %run.
2163 2163
2164 2164
2165 2165 Arguments:
2166 2166
2167 2167 If arguments are given, the following possibilites exist:
2168 2168
2169 2169 - The arguments are numbers or pairs of colon-separated numbers (like
2170 2170 1 4:8 9). These are interpreted as lines of previous input to be
2171 2171 loaded into the editor. The syntax is the same of the %macro command.
2172 2172
2173 2173 - If the argument doesn't start with a number, it is evaluated as a
2174 2174 variable and its contents loaded into the editor. You can thus edit
2175 2175 any string which contains python code (including the result of
2176 2176 previous edits).
2177 2177
2178 2178 - If the argument is the name of an object (other than a string),
2179 2179 IPython will try to locate the file where it was defined and open the
2180 2180 editor at the point where it is defined. You can use `%edit function`
2181 2181 to load an editor exactly at the point where 'function' is defined,
2182 2182 edit it and have the file be executed automatically.
2183 2183
2184 2184 If the object is a macro (see %macro for details), this opens up your
2185 2185 specified editor with a temporary file containing the macro's data.
2186 2186 Upon exit, the macro is reloaded with the contents of the file.
2187 2187
2188 2188 Note: opening at an exact line is only supported under Unix, and some
2189 2189 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2190 2190 '+NUMBER' parameter necessary for this feature. Good editors like
2191 2191 (X)Emacs, vi, jed, pico and joe all do.
2192 2192
2193 2193 - If the argument is not found as a variable, IPython will look for a
2194 2194 file with that name (adding .py if necessary) and load it into the
2195 2195 editor. It will execute its contents with execfile() when you exit,
2196 2196 loading any code in the file into your interactive namespace.
2197 2197
2198 2198 After executing your code, %edit will return as output the code you
2199 2199 typed in the editor (except when it was an existing file). This way
2200 2200 you can reload the code in further invocations of %edit as a variable,
2201 2201 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2202 2202 the output.
2203 2203
2204 2204 Note that %edit is also available through the alias %ed.
2205 2205
2206 2206 This is an example of creating a simple function inside the editor and
2207 2207 then modifying it. First, start up the editor:
2208 2208
2209 2209 In [1]: ed
2210 2210 Editing... done. Executing edited code...
2211 2211 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2212 2212
2213 2213 We can then call the function foo():
2214 2214
2215 2215 In [2]: foo()
2216 2216 foo() was defined in an editing session
2217 2217
2218 2218 Now we edit foo. IPython automatically loads the editor with the
2219 2219 (temporary) file where foo() was previously defined:
2220 2220
2221 2221 In [3]: ed foo
2222 2222 Editing... done. Executing edited code...
2223 2223
2224 2224 And if we call foo() again we get the modified version:
2225 2225
2226 2226 In [4]: foo()
2227 2227 foo() has now been changed!
2228 2228
2229 2229 Here is an example of how to edit a code snippet successive
2230 2230 times. First we call the editor:
2231 2231
2232 2232 In [5]: ed
2233 2233 Editing... done. Executing edited code...
2234 2234 hello
2235 2235 Out[5]: "print 'hello'n"
2236 2236
2237 2237 Now we call it again with the previous output (stored in _):
2238 2238
2239 2239 In [6]: ed _
2240 2240 Editing... done. Executing edited code...
2241 2241 hello world
2242 2242 Out[6]: "print 'hello world'n"
2243 2243
2244 2244 Now we call it with the output #8 (stored in _8, also as Out[8]):
2245 2245
2246 2246 In [7]: ed _8
2247 2247 Editing... done. Executing edited code...
2248 2248 hello again
2249 2249 Out[7]: "print 'hello again'n"
2250 2250
2251 2251
2252 2252 Changing the default editor hook:
2253 2253
2254 2254 If you wish to write your own editor hook, you can put it in a
2255 2255 configuration file which you load at startup time. The default hook
2256 2256 is defined in the IPython.core.hooks module, and you can use that as a
2257 2257 starting example for further modifications. That file also has
2258 2258 general instructions on how to set a new hook for use once you've
2259 2259 defined it."""
2260 2260
2261 2261 # FIXME: This function has become a convoluted mess. It needs a
2262 2262 # ground-up rewrite with clean, simple logic.
2263 2263
2264 2264 def make_filename(arg):
2265 2265 "Make a filename from the given args"
2266 2266 try:
2267 2267 filename = get_py_filename(arg)
2268 2268 except IOError:
2269 2269 if args.endswith('.py'):
2270 2270 filename = arg
2271 2271 else:
2272 2272 filename = None
2273 2273 return filename
2274 2274
2275 2275 # custom exceptions
2276 2276 class DataIsObject(Exception): pass
2277 2277
2278 2278 opts,args = self.parse_options(parameter_s,'prxn:')
2279 2279 # Set a few locals from the options for convenience:
2280 2280 opts_p = opts.has_key('p')
2281 2281 opts_r = opts.has_key('r')
2282 2282
2283 2283 # Default line number value
2284 2284 lineno = opts.get('n',None)
2285 2285
2286 2286 if opts_p:
2287 2287 args = '_%s' % last_call[0]
2288 2288 if not self.shell.user_ns.has_key(args):
2289 2289 args = last_call[1]
2290 2290
2291 2291 # use last_call to remember the state of the previous call, but don't
2292 2292 # let it be clobbered by successive '-p' calls.
2293 2293 try:
2294 2294 last_call[0] = self.shell.outputcache.prompt_count
2295 2295 if not opts_p:
2296 2296 last_call[1] = parameter_s
2297 2297 except:
2298 2298 pass
2299 2299
2300 2300 # by default this is done with temp files, except when the given
2301 2301 # arg is a filename
2302 2302 use_temp = 1
2303 2303
2304 2304 if re.match(r'\d',args):
2305 2305 # Mode where user specifies ranges of lines, like in %macro.
2306 2306 # This means that you can't edit files whose names begin with
2307 2307 # numbers this way. Tough.
2308 2308 ranges = args.split()
2309 2309 data = ''.join(self.extract_input_slices(ranges,opts_r))
2310 2310 elif args.endswith('.py'):
2311 2311 filename = make_filename(args)
2312 2312 data = ''
2313 2313 use_temp = 0
2314 2314 elif args:
2315 2315 try:
2316 2316 # Load the parameter given as a variable. If not a string,
2317 2317 # process it as an object instead (below)
2318 2318
2319 2319 #print '*** args',args,'type',type(args) # dbg
2320 2320 data = eval(args,self.shell.user_ns)
2321 2321 if not type(data) in StringTypes:
2322 2322 raise DataIsObject
2323 2323
2324 2324 except (NameError,SyntaxError):
2325 2325 # given argument is not a variable, try as a filename
2326 2326 filename = make_filename(args)
2327 2327 if filename is None:
2328 2328 warn("Argument given (%s) can't be found as a variable "
2329 2329 "or as a filename." % args)
2330 2330 return
2331 2331
2332 2332 data = ''
2333 2333 use_temp = 0
2334 2334 except DataIsObject:
2335 2335
2336 2336 # macros have a special edit function
2337 2337 if isinstance(data,Macro):
2338 2338 self._edit_macro(args,data)
2339 2339 return
2340 2340
2341 2341 # For objects, try to edit the file where they are defined
2342 2342 try:
2343 2343 filename = inspect.getabsfile(data)
2344 2344 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2345 2345 # class created by %edit? Try to find source
2346 2346 # by looking for method definitions instead, the
2347 2347 # __module__ in those classes is FakeModule.
2348 2348 attrs = [getattr(data, aname) for aname in dir(data)]
2349 2349 for attr in attrs:
2350 2350 if not inspect.ismethod(attr):
2351 2351 continue
2352 2352 filename = inspect.getabsfile(attr)
2353 2353 if filename and 'fakemodule' not in filename.lower():
2354 2354 # change the attribute to be the edit target instead
2355 2355 data = attr
2356 2356 break
2357 2357
2358 2358 datafile = 1
2359 2359 except TypeError:
2360 2360 filename = make_filename(args)
2361 2361 datafile = 1
2362 2362 warn('Could not find file where `%s` is defined.\n'
2363 2363 'Opening a file named `%s`' % (args,filename))
2364 2364 # Now, make sure we can actually read the source (if it was in
2365 2365 # a temp file it's gone by now).
2366 2366 if datafile:
2367 2367 try:
2368 2368 if lineno is None:
2369 2369 lineno = inspect.getsourcelines(data)[1]
2370 2370 except IOError:
2371 2371 filename = make_filename(args)
2372 2372 if filename is None:
2373 2373 warn('The file `%s` where `%s` was defined cannot '
2374 2374 'be read.' % (filename,data))
2375 2375 return
2376 2376 use_temp = 0
2377 2377 else:
2378 2378 data = ''
2379 2379
2380 2380 if use_temp:
2381 2381 filename = self.shell.mktempfile(data)
2382 2382 print 'IPython will make a temporary file named:',filename
2383 2383
2384 2384 # do actual editing here
2385 2385 print 'Editing...',
2386 2386 sys.stdout.flush()
2387 2387 try:
2388 2388 self.shell.hooks.editor(filename,lineno)
2389 2389 except ipapi.TryNext:
2390 2390 warn('Could not open editor')
2391 2391 return
2392 2392
2393 2393 # XXX TODO: should this be generalized for all string vars?
2394 2394 # For now, this is special-cased to blocks created by cpaste
2395 2395 if args.strip() == 'pasted_block':
2396 2396 self.shell.user_ns['pasted_block'] = file_read(filename)
2397 2397
2398 2398 if opts.has_key('x'): # -x prevents actual execution
2399 2399 print
2400 2400 else:
2401 2401 print 'done. Executing edited code...'
2402 2402 if opts_r:
2403 2403 self.shell.runlines(file_read(filename))
2404 2404 else:
2405 2405 self.shell.safe_execfile(filename,self.shell.user_ns,
2406 2406 self.shell.user_ns)
2407 2407
2408 2408
2409 2409 if use_temp:
2410 2410 try:
2411 2411 return open(filename).read()
2412 2412 except IOError,msg:
2413 2413 if msg.filename == filename:
2414 2414 warn('File not found. Did you forget to save?')
2415 2415 return
2416 2416 else:
2417 2417 self.shell.showtraceback()
2418 2418
2419 2419 def magic_xmode(self,parameter_s = ''):
2420 2420 """Switch modes for the exception handlers.
2421 2421
2422 2422 Valid modes: Plain, Context and Verbose.
2423 2423
2424 2424 If called without arguments, acts as a toggle."""
2425 2425
2426 2426 def xmode_switch_err(name):
2427 2427 warn('Error changing %s exception modes.\n%s' %
2428 2428 (name,sys.exc_info()[1]))
2429 2429
2430 2430 shell = self.shell
2431 2431 new_mode = parameter_s.strip().capitalize()
2432 2432 try:
2433 2433 shell.InteractiveTB.set_mode(mode=new_mode)
2434 2434 print 'Exception reporting mode:',shell.InteractiveTB.mode
2435 2435 except:
2436 2436 xmode_switch_err('user')
2437 2437
2438 2438 # threaded shells use a special handler in sys.excepthook
2439 2439 if shell.isthreaded:
2440 2440 try:
2441 2441 shell.sys_excepthook.set_mode(mode=new_mode)
2442 2442 except:
2443 2443 xmode_switch_err('threaded')
2444 2444
2445 2445 def magic_colors(self,parameter_s = ''):
2446 2446 """Switch color scheme for prompts, info system and exception handlers.
2447 2447
2448 2448 Currently implemented schemes: NoColor, Linux, LightBG.
2449 2449
2450 2450 Color scheme names are not case-sensitive."""
2451 2451
2452 2452 def color_switch_err(name):
2453 2453 warn('Error changing %s color schemes.\n%s' %
2454 2454 (name,sys.exc_info()[1]))
2455 2455
2456 2456
2457 2457 new_scheme = parameter_s.strip()
2458 2458 if not new_scheme:
2459 2459 raise UsageError(
2460 2460 "%colors: you must specify a color scheme. See '%colors?'")
2461 2461 return
2462 2462 # local shortcut
2463 2463 shell = self.shell
2464 2464
2465 2465 import IPython.rlineimpl as readline
2466 2466
2467 2467 if not readline.have_readline and sys.platform == "win32":
2468 2468 msg = """\
2469 2469 Proper color support under MS Windows requires the pyreadline library.
2470 2470 You can find it at:
2471 2471 http://ipython.scipy.org/moin/PyReadline/Intro
2472 2472 Gary's readline needs the ctypes module, from:
2473 2473 http://starship.python.net/crew/theller/ctypes
2474 2474 (Note that ctypes is already part of Python versions 2.5 and newer).
2475 2475
2476 2476 Defaulting color scheme to 'NoColor'"""
2477 2477 new_scheme = 'NoColor'
2478 2478 warn(msg)
2479 2479
2480 2480 # readline option is 0
2481 2481 if not shell.has_readline:
2482 2482 new_scheme = 'NoColor'
2483 2483
2484 2484 # Set prompt colors
2485 2485 try:
2486 2486 shell.outputcache.set_colors(new_scheme)
2487 2487 except:
2488 2488 color_switch_err('prompt')
2489 2489 else:
2490 2490 shell.rc.colors = \
2491 2491 shell.outputcache.color_table.active_scheme_name
2492 2492 # Set exception colors
2493 2493 try:
2494 2494 shell.InteractiveTB.set_colors(scheme = new_scheme)
2495 2495 shell.SyntaxTB.set_colors(scheme = new_scheme)
2496 2496 except:
2497 2497 color_switch_err('exception')
2498 2498
2499 2499 # threaded shells use a verbose traceback in sys.excepthook
2500 2500 if shell.isthreaded:
2501 2501 try:
2502 2502 shell.sys_excepthook.set_colors(scheme=new_scheme)
2503 2503 except:
2504 2504 color_switch_err('system exception handler')
2505 2505
2506 2506 # Set info (for 'object?') colors
2507 2507 if shell.rc.color_info:
2508 2508 try:
2509 2509 shell.inspector.set_active_scheme(new_scheme)
2510 2510 except:
2511 2511 color_switch_err('object inspector')
2512 2512 else:
2513 2513 shell.inspector.set_active_scheme('NoColor')
2514 2514
2515 2515 def magic_color_info(self,parameter_s = ''):
2516 2516 """Toggle color_info.
2517 2517
2518 2518 The color_info configuration parameter controls whether colors are
2519 2519 used for displaying object details (by things like %psource, %pfile or
2520 2520 the '?' system). This function toggles this value with each call.
2521 2521
2522 2522 Note that unless you have a fairly recent pager (less works better
2523 2523 than more) in your system, using colored object information displays
2524 2524 will not work properly. Test it and see."""
2525 2525
2526 2526 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2527 2527 self.magic_colors(self.shell.rc.colors)
2528 2528 print 'Object introspection functions have now coloring:',
2529 2529 print ['OFF','ON'][self.shell.rc.color_info]
2530 2530
2531 2531 def magic_Pprint(self, parameter_s=''):
2532 2532 """Toggle pretty printing on/off."""
2533 2533
2534 2534 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2535 2535 print 'Pretty printing has been turned', \
2536 2536 ['OFF','ON'][self.shell.rc.pprint]
2537 2537
2538 2538 def magic_exit(self, parameter_s=''):
2539 2539 """Exit IPython, confirming if configured to do so.
2540 2540
2541 2541 You can configure whether IPython asks for confirmation upon exit by
2542 2542 setting the confirm_exit flag in the ipythonrc file."""
2543 2543
2544 2544 self.shell.exit()
2545 2545
2546 2546 def magic_quit(self, parameter_s=''):
2547 2547 """Exit IPython, confirming if configured to do so (like %exit)"""
2548 2548
2549 2549 self.shell.exit()
2550 2550
2551 2551 def magic_Exit(self, parameter_s=''):
2552 2552 """Exit IPython without confirmation."""
2553 2553
2554 2554 self.shell.ask_exit()
2555 2555
2556 2556 #......................................................................
2557 2557 # Functions to implement unix shell-type things
2558 2558
2559 2559 @testdec.skip_doctest
2560 2560 def magic_alias(self, parameter_s = ''):
2561 2561 """Define an alias for a system command.
2562 2562
2563 2563 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2564 2564
2565 2565 Then, typing 'alias_name params' will execute the system command 'cmd
2566 2566 params' (from your underlying operating system).
2567 2567
2568 2568 Aliases have lower precedence than magic functions and Python normal
2569 2569 variables, so if 'foo' is both a Python variable and an alias, the
2570 2570 alias can not be executed until 'del foo' removes the Python variable.
2571 2571
2572 2572 You can use the %l specifier in an alias definition to represent the
2573 2573 whole line when the alias is called. For example:
2574 2574
2575 2575 In [2]: alias all echo "Input in brackets: <%l>"
2576 2576 In [3]: all hello world
2577 2577 Input in brackets: <hello world>
2578 2578
2579 2579 You can also define aliases with parameters using %s specifiers (one
2580 2580 per parameter):
2581 2581
2582 2582 In [1]: alias parts echo first %s second %s
2583 2583 In [2]: %parts A B
2584 2584 first A second B
2585 2585 In [3]: %parts A
2586 2586 Incorrect number of arguments: 2 expected.
2587 2587 parts is an alias to: 'echo first %s second %s'
2588 2588
2589 2589 Note that %l and %s are mutually exclusive. You can only use one or
2590 2590 the other in your aliases.
2591 2591
2592 2592 Aliases expand Python variables just like system calls using ! or !!
2593 2593 do: all expressions prefixed with '$' get expanded. For details of
2594 2594 the semantic rules, see PEP-215:
2595 2595 http://www.python.org/peps/pep-0215.html. This is the library used by
2596 2596 IPython for variable expansion. If you want to access a true shell
2597 2597 variable, an extra $ is necessary to prevent its expansion by IPython:
2598 2598
2599 2599 In [6]: alias show echo
2600 2600 In [7]: PATH='A Python string'
2601 2601 In [8]: show $PATH
2602 2602 A Python string
2603 2603 In [9]: show $$PATH
2604 2604 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2605 2605
2606 2606 You can use the alias facility to acess all of $PATH. See the %rehash
2607 2607 and %rehashx functions, which automatically create aliases for the
2608 2608 contents of your $PATH.
2609 2609
2610 2610 If called with no parameters, %alias prints the current alias table."""
2611 2611
2612 2612 par = parameter_s.strip()
2613 2613 if not par:
2614 2614 stored = self.db.get('stored_aliases', {} )
2615 2615 atab = self.shell.alias_table
2616 2616 aliases = atab.keys()
2617 2617 aliases.sort()
2618 2618 res = []
2619 2619 showlast = []
2620 2620 for alias in aliases:
2621 2621 special = False
2622 2622 try:
2623 2623 tgt = atab[alias][1]
2624 2624 except (TypeError, AttributeError):
2625 2625 # unsubscriptable? probably a callable
2626 2626 tgt = atab[alias]
2627 2627 special = True
2628 2628 # 'interesting' aliases
2629 2629 if (alias in stored or
2630 2630 special or
2631 2631 alias.lower() != os.path.splitext(tgt)[0].lower() or
2632 2632 ' ' in tgt):
2633 2633 showlast.append((alias, tgt))
2634 2634 else:
2635 2635 res.append((alias, tgt ))
2636 2636
2637 2637 # show most interesting aliases last
2638 2638 res.extend(showlast)
2639 2639 print "Total number of aliases:",len(aliases)
2640 2640 return res
2641 2641 try:
2642 2642 alias,cmd = par.split(None,1)
2643 2643 except:
2644 2644 print oinspect.getdoc(self.magic_alias)
2645 2645 else:
2646 2646 nargs = cmd.count('%s')
2647 2647 if nargs>0 and cmd.find('%l')>=0:
2648 2648 error('The %s and %l specifiers are mutually exclusive '
2649 2649 'in alias definitions.')
2650 2650 else: # all looks OK
2651 2651 self.shell.alias_table[alias] = (nargs,cmd)
2652 2652 self.shell.alias_table_validate(verbose=0)
2653 2653 # end magic_alias
2654 2654
2655 2655 def magic_unalias(self, parameter_s = ''):
2656 2656 """Remove an alias"""
2657 2657
2658 2658 aname = parameter_s.strip()
2659 2659 if aname in self.shell.alias_table:
2660 2660 del self.shell.alias_table[aname]
2661 2661 stored = self.db.get('stored_aliases', {} )
2662 2662 if aname in stored:
2663 2663 print "Removing %stored alias",aname
2664 2664 del stored[aname]
2665 2665 self.db['stored_aliases'] = stored
2666 2666
2667 2667
2668 2668 def magic_rehashx(self, parameter_s = ''):
2669 2669 """Update the alias table with all executable files in $PATH.
2670 2670
2671 2671 This version explicitly checks that every entry in $PATH is a file
2672 2672 with execute access (os.X_OK), so it is much slower than %rehash.
2673 2673
2674 2674 Under Windows, it checks executability as a match agains a
2675 2675 '|'-separated string of extensions, stored in the IPython config
2676 2676 variable win_exec_ext. This defaults to 'exe|com|bat'.
2677 2677
2678 2678 This function also resets the root module cache of module completer,
2679 2679 used on slow filesystems.
2680 2680 """
2681 2681
2682 2682
2683 2683 ip = self.api
2684 2684
2685 2685 # for the benefit of module completer in ipy_completers.py
2686 2686 del ip.db['rootmodules']
2687 2687
2688 2688 path = [os.path.abspath(os.path.expanduser(p)) for p in
2689 2689 os.environ.get('PATH','').split(os.pathsep)]
2690 2690 path = filter(os.path.isdir,path)
2691 2691
2692 2692 alias_table = self.shell.alias_table
2693 2693 syscmdlist = []
2694 2694 if os.name == 'posix':
2695 2695 isexec = lambda fname:os.path.isfile(fname) and \
2696 2696 os.access(fname,os.X_OK)
2697 2697 else:
2698 2698
2699 2699 try:
2700 2700 winext = os.environ['pathext'].replace(';','|').replace('.','')
2701 2701 except KeyError:
2702 2702 winext = 'exe|com|bat|py'
2703 2703 if 'py' not in winext:
2704 2704 winext += '|py'
2705 2705 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2706 2706 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2707 2707 savedir = os.getcwd()
2708 2708 try:
2709 2709 # write the whole loop for posix/Windows so we don't have an if in
2710 2710 # the innermost part
2711 2711 if os.name == 'posix':
2712 2712 for pdir in path:
2713 2713 os.chdir(pdir)
2714 2714 for ff in os.listdir(pdir):
2715 2715 if isexec(ff) and ff not in self.shell.no_alias:
2716 2716 # each entry in the alias table must be (N,name),
2717 2717 # where N is the number of positional arguments of the
2718 2718 # alias.
2719 2719 # Dots will be removed from alias names, since ipython
2720 2720 # assumes names with dots to be python code
2721 2721 alias_table[ff.replace('.','')] = (0,ff)
2722 2722 syscmdlist.append(ff)
2723 2723 else:
2724 2724 for pdir in path:
2725 2725 os.chdir(pdir)
2726 2726 for ff in os.listdir(pdir):
2727 2727 base, ext = os.path.splitext(ff)
2728 2728 if isexec(ff) and base.lower() not in self.shell.no_alias:
2729 2729 if ext.lower() == '.exe':
2730 2730 ff = base
2731 2731 alias_table[base.lower().replace('.','')] = (0,ff)
2732 2732 syscmdlist.append(ff)
2733 2733 # Make sure the alias table doesn't contain keywords or builtins
2734 2734 self.shell.alias_table_validate()
2735 2735 # Call again init_auto_alias() so we get 'rm -i' and other
2736 2736 # modified aliases since %rehashx will probably clobber them
2737 2737
2738 2738 # no, we don't want them. if %rehashx clobbers them, good,
2739 2739 # we'll probably get better versions
2740 2740 # self.shell.init_auto_alias()
2741 2741 db = ip.db
2742 2742 db['syscmdlist'] = syscmdlist
2743 2743 finally:
2744 2744 os.chdir(savedir)
2745 2745
2746 2746 def magic_pwd(self, parameter_s = ''):
2747 2747 """Return the current working directory path."""
2748 2748 return os.getcwd()
2749 2749
2750 2750 def magic_cd(self, parameter_s=''):
2751 2751 """Change the current working directory.
2752 2752
2753 2753 This command automatically maintains an internal list of directories
2754 2754 you visit during your IPython session, in the variable _dh. The
2755 2755 command %dhist shows this history nicely formatted. You can also
2756 2756 do 'cd -<tab>' to see directory history conveniently.
2757 2757
2758 2758 Usage:
2759 2759
2760 2760 cd 'dir': changes to directory 'dir'.
2761 2761
2762 2762 cd -: changes to the last visited directory.
2763 2763
2764 2764 cd -<n>: changes to the n-th directory in the directory history.
2765 2765
2766 2766 cd --foo: change to directory that matches 'foo' in history
2767 2767
2768 2768 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2769 2769 (note: cd <bookmark_name> is enough if there is no
2770 2770 directory <bookmark_name>, but a bookmark with the name exists.)
2771 2771 'cd -b <tab>' allows you to tab-complete bookmark names.
2772 2772
2773 2773 Options:
2774 2774
2775 2775 -q: quiet. Do not print the working directory after the cd command is
2776 2776 executed. By default IPython's cd command does print this directory,
2777 2777 since the default prompts do not display path information.
2778 2778
2779 2779 Note that !cd doesn't work for this purpose because the shell where
2780 2780 !command runs is immediately discarded after executing 'command'."""
2781 2781
2782 2782 parameter_s = parameter_s.strip()
2783 2783 #bkms = self.shell.persist.get("bookmarks",{})
2784 2784
2785 2785 oldcwd = os.getcwd()
2786 2786 numcd = re.match(r'(-)(\d+)$',parameter_s)
2787 2787 # jump in directory history by number
2788 2788 if numcd:
2789 2789 nn = int(numcd.group(2))
2790 2790 try:
2791 2791 ps = self.shell.user_ns['_dh'][nn]
2792 2792 except IndexError:
2793 2793 print 'The requested directory does not exist in history.'
2794 2794 return
2795 2795 else:
2796 2796 opts = {}
2797 2797 elif parameter_s.startswith('--'):
2798 2798 ps = None
2799 2799 fallback = None
2800 2800 pat = parameter_s[2:]
2801 2801 dh = self.shell.user_ns['_dh']
2802 2802 # first search only by basename (last component)
2803 2803 for ent in reversed(dh):
2804 2804 if pat in os.path.basename(ent) and os.path.isdir(ent):
2805 2805 ps = ent
2806 2806 break
2807 2807
2808 2808 if fallback is None and pat in ent and os.path.isdir(ent):
2809 2809 fallback = ent
2810 2810
2811 2811 # if we have no last part match, pick the first full path match
2812 2812 if ps is None:
2813 2813 ps = fallback
2814 2814
2815 2815 if ps is None:
2816 2816 print "No matching entry in directory history"
2817 2817 return
2818 2818 else:
2819 2819 opts = {}
2820 2820
2821 2821
2822 2822 else:
2823 2823 #turn all non-space-escaping backslashes to slashes,
2824 2824 # for c:\windows\directory\names\
2825 2825 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2826 2826 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2827 2827 # jump to previous
2828 2828 if ps == '-':
2829 2829 try:
2830 2830 ps = self.shell.user_ns['_dh'][-2]
2831 2831 except IndexError:
2832 2832 raise UsageError('%cd -: No previous directory to change to.')
2833 2833 # jump to bookmark if needed
2834 2834 else:
2835 2835 if not os.path.isdir(ps) or opts.has_key('b'):
2836 2836 bkms = self.db.get('bookmarks', {})
2837 2837
2838 2838 if bkms.has_key(ps):
2839 2839 target = bkms[ps]
2840 2840 print '(bookmark:%s) -> %s' % (ps,target)
2841 2841 ps = target
2842 2842 else:
2843 2843 if opts.has_key('b'):
2844 2844 raise UsageError("Bookmark '%s' not found. "
2845 2845 "Use '%%bookmark -l' to see your bookmarks." % ps)
2846 2846
2847 2847 # at this point ps should point to the target dir
2848 2848 if ps:
2849 2849 try:
2850 2850 os.chdir(os.path.expanduser(ps))
2851 2851 if self.shell.rc.term_title:
2852 2852 #print 'set term title:',self.shell.rc.term_title # dbg
2853 2853 platutils.set_term_title('IPy ' + abbrev_cwd())
2854 2854 except OSError:
2855 2855 print sys.exc_info()[1]
2856 2856 else:
2857 2857 cwd = os.getcwd()
2858 2858 dhist = self.shell.user_ns['_dh']
2859 2859 if oldcwd != cwd:
2860 2860 dhist.append(cwd)
2861 2861 self.db['dhist'] = compress_dhist(dhist)[-100:]
2862 2862
2863 2863 else:
2864 2864 os.chdir(self.shell.home_dir)
2865 2865 if self.shell.rc.term_title:
2866 2866 platutils.set_term_title("IPy ~")
2867 2867 cwd = os.getcwd()
2868 2868 dhist = self.shell.user_ns['_dh']
2869 2869
2870 2870 if oldcwd != cwd:
2871 2871 dhist.append(cwd)
2872 2872 self.db['dhist'] = compress_dhist(dhist)[-100:]
2873 2873 if not 'q' in opts and self.shell.user_ns['_dh']:
2874 2874 print self.shell.user_ns['_dh'][-1]
2875 2875
2876 2876
2877 2877 def magic_env(self, parameter_s=''):
2878 2878 """List environment variables."""
2879 2879
2880 2880 return os.environ.data
2881 2881
2882 2882 def magic_pushd(self, parameter_s=''):
2883 2883 """Place the current dir on stack and change directory.
2884 2884
2885 2885 Usage:\\
2886 2886 %pushd ['dirname']
2887 2887 """
2888 2888
2889 2889 dir_s = self.shell.dir_stack
2890 2890 tgt = os.path.expanduser(parameter_s)
2891 2891 cwd = os.getcwd().replace(self.home_dir,'~')
2892 2892 if tgt:
2893 2893 self.magic_cd(parameter_s)
2894 2894 dir_s.insert(0,cwd)
2895 2895 return self.magic_dirs()
2896 2896
2897 2897 def magic_popd(self, parameter_s=''):
2898 2898 """Change to directory popped off the top of the stack.
2899 2899 """
2900 2900 if not self.shell.dir_stack:
2901 2901 raise UsageError("%popd on empty stack")
2902 2902 top = self.shell.dir_stack.pop(0)
2903 2903 self.magic_cd(top)
2904 2904 print "popd ->",top
2905 2905
2906 2906 def magic_dirs(self, parameter_s=''):
2907 2907 """Return the current directory stack."""
2908 2908
2909 2909 return self.shell.dir_stack
2910 2910
2911 2911 def magic_dhist(self, parameter_s=''):
2912 2912 """Print your history of visited directories.
2913 2913
2914 2914 %dhist -> print full history\\
2915 2915 %dhist n -> print last n entries only\\
2916 2916 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2917 2917
2918 2918 This history is automatically maintained by the %cd command, and
2919 2919 always available as the global list variable _dh. You can use %cd -<n>
2920 2920 to go to directory number <n>.
2921 2921
2922 2922 Note that most of time, you should view directory history by entering
2923 2923 cd -<TAB>.
2924 2924
2925 2925 """
2926 2926
2927 2927 dh = self.shell.user_ns['_dh']
2928 2928 if parameter_s:
2929 2929 try:
2930 2930 args = map(int,parameter_s.split())
2931 2931 except:
2932 2932 self.arg_err(Magic.magic_dhist)
2933 2933 return
2934 2934 if len(args) == 1:
2935 2935 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2936 2936 elif len(args) == 2:
2937 2937 ini,fin = args
2938 2938 else:
2939 2939 self.arg_err(Magic.magic_dhist)
2940 2940 return
2941 2941 else:
2942 2942 ini,fin = 0,len(dh)
2943 2943 nlprint(dh,
2944 2944 header = 'Directory history (kept in _dh)',
2945 2945 start=ini,stop=fin)
2946 2946
2947 2947 @testdec.skip_doctest
2948 2948 def magic_sc(self, parameter_s=''):
2949 2949 """Shell capture - execute a shell command and capture its output.
2950 2950
2951 2951 DEPRECATED. Suboptimal, retained for backwards compatibility.
2952 2952
2953 2953 You should use the form 'var = !command' instead. Example:
2954 2954
2955 2955 "%sc -l myfiles = ls ~" should now be written as
2956 2956
2957 2957 "myfiles = !ls ~"
2958 2958
2959 2959 myfiles.s, myfiles.l and myfiles.n still apply as documented
2960 2960 below.
2961 2961
2962 2962 --
2963 2963 %sc [options] varname=command
2964 2964
2965 2965 IPython will run the given command using commands.getoutput(), and
2966 2966 will then update the user's interactive namespace with a variable
2967 2967 called varname, containing the value of the call. Your command can
2968 2968 contain shell wildcards, pipes, etc.
2969 2969
2970 2970 The '=' sign in the syntax is mandatory, and the variable name you
2971 2971 supply must follow Python's standard conventions for valid names.
2972 2972
2973 2973 (A special format without variable name exists for internal use)
2974 2974
2975 2975 Options:
2976 2976
2977 2977 -l: list output. Split the output on newlines into a list before
2978 2978 assigning it to the given variable. By default the output is stored
2979 2979 as a single string.
2980 2980
2981 2981 -v: verbose. Print the contents of the variable.
2982 2982
2983 2983 In most cases you should not need to split as a list, because the
2984 2984 returned value is a special type of string which can automatically
2985 2985 provide its contents either as a list (split on newlines) or as a
2986 2986 space-separated string. These are convenient, respectively, either
2987 2987 for sequential processing or to be passed to a shell command.
2988 2988
2989 2989 For example:
2990 2990
2991 2991 # all-random
2992 2992
2993 2993 # Capture into variable a
2994 2994 In [1]: sc a=ls *py
2995 2995
2996 2996 # a is a string with embedded newlines
2997 2997 In [2]: a
2998 2998 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2999 2999
3000 3000 # which can be seen as a list:
3001 3001 In [3]: a.l
3002 3002 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3003 3003
3004 3004 # or as a whitespace-separated string:
3005 3005 In [4]: a.s
3006 3006 Out[4]: 'setup.py win32_manual_post_install.py'
3007 3007
3008 3008 # a.s is useful to pass as a single command line:
3009 3009 In [5]: !wc -l $a.s
3010 3010 146 setup.py
3011 3011 130 win32_manual_post_install.py
3012 3012 276 total
3013 3013
3014 3014 # while the list form is useful to loop over:
3015 3015 In [6]: for f in a.l:
3016 3016 ...: !wc -l $f
3017 3017 ...:
3018 3018 146 setup.py
3019 3019 130 win32_manual_post_install.py
3020 3020
3021 3021 Similiarly, the lists returned by the -l option are also special, in
3022 3022 the sense that you can equally invoke the .s attribute on them to
3023 3023 automatically get a whitespace-separated string from their contents:
3024 3024
3025 3025 In [7]: sc -l b=ls *py
3026 3026
3027 3027 In [8]: b
3028 3028 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3029 3029
3030 3030 In [9]: b.s
3031 3031 Out[9]: 'setup.py win32_manual_post_install.py'
3032 3032
3033 3033 In summary, both the lists and strings used for ouptut capture have
3034 3034 the following special attributes:
3035 3035
3036 3036 .l (or .list) : value as list.
3037 3037 .n (or .nlstr): value as newline-separated string.
3038 3038 .s (or .spstr): value as space-separated string.
3039 3039 """
3040 3040
3041 3041 opts,args = self.parse_options(parameter_s,'lv')
3042 3042 # Try to get a variable name and command to run
3043 3043 try:
3044 3044 # the variable name must be obtained from the parse_options
3045 3045 # output, which uses shlex.split to strip options out.
3046 3046 var,_ = args.split('=',1)
3047 3047 var = var.strip()
3048 3048 # But the the command has to be extracted from the original input
3049 3049 # parameter_s, not on what parse_options returns, to avoid the
3050 3050 # quote stripping which shlex.split performs on it.
3051 3051 _,cmd = parameter_s.split('=',1)
3052 3052 except ValueError:
3053 3053 var,cmd = '',''
3054 3054 # If all looks ok, proceed
3055 3055 out,err = self.shell.getoutputerror(cmd)
3056 3056 if err:
3057 3057 print >> Term.cerr,err
3058 3058 if opts.has_key('l'):
3059 3059 out = SList(out.split('\n'))
3060 3060 else:
3061 3061 out = LSString(out)
3062 3062 if opts.has_key('v'):
3063 3063 print '%s ==\n%s' % (var,pformat(out))
3064 3064 if var:
3065 3065 self.shell.user_ns.update({var:out})
3066 3066 else:
3067 3067 return out
3068 3068
3069 3069 def magic_sx(self, parameter_s=''):
3070 3070 """Shell execute - run a shell command and capture its output.
3071 3071
3072 3072 %sx command
3073 3073
3074 3074 IPython will run the given command using commands.getoutput(), and
3075 3075 return the result formatted as a list (split on '\\n'). Since the
3076 3076 output is _returned_, it will be stored in ipython's regular output
3077 3077 cache Out[N] and in the '_N' automatic variables.
3078 3078
3079 3079 Notes:
3080 3080
3081 3081 1) If an input line begins with '!!', then %sx is automatically
3082 3082 invoked. That is, while:
3083 3083 !ls
3084 3084 causes ipython to simply issue system('ls'), typing
3085 3085 !!ls
3086 3086 is a shorthand equivalent to:
3087 3087 %sx ls
3088 3088
3089 3089 2) %sx differs from %sc in that %sx automatically splits into a list,
3090 3090 like '%sc -l'. The reason for this is to make it as easy as possible
3091 3091 to process line-oriented shell output via further python commands.
3092 3092 %sc is meant to provide much finer control, but requires more
3093 3093 typing.
3094 3094
3095 3095 3) Just like %sc -l, this is a list with special attributes:
3096 3096
3097 3097 .l (or .list) : value as list.
3098 3098 .n (or .nlstr): value as newline-separated string.
3099 3099 .s (or .spstr): value as whitespace-separated string.
3100 3100
3101 3101 This is very useful when trying to use such lists as arguments to
3102 3102 system commands."""
3103 3103
3104 3104 if parameter_s:
3105 3105 out,err = self.shell.getoutputerror(parameter_s)
3106 3106 if err:
3107 3107 print >> Term.cerr,err
3108 3108 return SList(out.split('\n'))
3109 3109
3110 3110 def magic_bg(self, parameter_s=''):
3111 3111 """Run a job in the background, in a separate thread.
3112 3112
3113 3113 For example,
3114 3114
3115 3115 %bg myfunc(x,y,z=1)
3116 3116
3117 3117 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3118 3118 execution starts, a message will be printed indicating the job
3119 3119 number. If your job number is 5, you can use
3120 3120
3121 3121 myvar = jobs.result(5) or myvar = jobs[5].result
3122 3122
3123 3123 to assign this result to variable 'myvar'.
3124 3124
3125 3125 IPython has a job manager, accessible via the 'jobs' object. You can
3126 3126 type jobs? to get more information about it, and use jobs.<TAB> to see
3127 3127 its attributes. All attributes not starting with an underscore are
3128 3128 meant for public use.
3129 3129
3130 3130 In particular, look at the jobs.new() method, which is used to create
3131 3131 new jobs. This magic %bg function is just a convenience wrapper
3132 3132 around jobs.new(), for expression-based jobs. If you want to create a
3133 3133 new job with an explicit function object and arguments, you must call
3134 3134 jobs.new() directly.
3135 3135
3136 3136 The jobs.new docstring also describes in detail several important
3137 3137 caveats associated with a thread-based model for background job
3138 3138 execution. Type jobs.new? for details.
3139 3139
3140 3140 You can check the status of all jobs with jobs.status().
3141 3141
3142 3142 The jobs variable is set by IPython into the Python builtin namespace.
3143 3143 If you ever declare a variable named 'jobs', you will shadow this
3144 3144 name. You can either delete your global jobs variable to regain
3145 3145 access to the job manager, or make a new name and assign it manually
3146 3146 to the manager (stored in IPython's namespace). For example, to
3147 3147 assign the job manager to the Jobs name, use:
3148 3148
3149 3149 Jobs = __builtins__.jobs"""
3150 3150
3151 3151 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3152 3152
3153 3153 def magic_r(self, parameter_s=''):
3154 3154 """Repeat previous input.
3155 3155
3156 3156 Note: Consider using the more powerfull %rep instead!
3157 3157
3158 3158 If given an argument, repeats the previous command which starts with
3159 3159 the same string, otherwise it just repeats the previous input.
3160 3160
3161 3161 Shell escaped commands (with ! as first character) are not recognized
3162 3162 by this system, only pure python code and magic commands.
3163 3163 """
3164 3164
3165 3165 start = parameter_s.strip()
3166 3166 esc_magic = self.shell.ESC_MAGIC
3167 3167 # Identify magic commands even if automagic is on (which means
3168 3168 # the in-memory version is different from that typed by the user).
3169 3169 if self.shell.rc.automagic:
3170 3170 start_magic = esc_magic+start
3171 3171 else:
3172 3172 start_magic = start
3173 3173 # Look through the input history in reverse
3174 3174 for n in range(len(self.shell.input_hist)-2,0,-1):
3175 3175 input = self.shell.input_hist[n]
3176 3176 # skip plain 'r' lines so we don't recurse to infinity
3177 3177 if input != '_ip.magic("r")\n' and \
3178 3178 (input.startswith(start) or input.startswith(start_magic)):
3179 3179 #print 'match',`input` # dbg
3180 3180 print 'Executing:',input,
3181 3181 self.shell.runlines(input)
3182 3182 return
3183 3183 print 'No previous input matching `%s` found.' % start
3184 3184
3185 3185
3186 3186 def magic_bookmark(self, parameter_s=''):
3187 3187 """Manage IPython's bookmark system.
3188 3188
3189 3189 %bookmark <name> - set bookmark to current dir
3190 3190 %bookmark <name> <dir> - set bookmark to <dir>
3191 3191 %bookmark -l - list all bookmarks
3192 3192 %bookmark -d <name> - remove bookmark
3193 3193 %bookmark -r - remove all bookmarks
3194 3194
3195 3195 You can later on access a bookmarked folder with:
3196 3196 %cd -b <name>
3197 3197 or simply '%cd <name>' if there is no directory called <name> AND
3198 3198 there is such a bookmark defined.
3199 3199
3200 3200 Your bookmarks persist through IPython sessions, but they are
3201 3201 associated with each profile."""
3202 3202
3203 3203 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3204 3204 if len(args) > 2:
3205 3205 raise UsageError("%bookmark: too many arguments")
3206 3206
3207 3207 bkms = self.db.get('bookmarks',{})
3208 3208
3209 3209 if opts.has_key('d'):
3210 3210 try:
3211 3211 todel = args[0]
3212 3212 except IndexError:
3213 3213 raise UsageError(
3214 3214 "%bookmark -d: must provide a bookmark to delete")
3215 3215 else:
3216 3216 try:
3217 3217 del bkms[todel]
3218 3218 except KeyError:
3219 3219 raise UsageError(
3220 3220 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3221 3221
3222 3222 elif opts.has_key('r'):
3223 3223 bkms = {}
3224 3224 elif opts.has_key('l'):
3225 3225 bks = bkms.keys()
3226 3226 bks.sort()
3227 3227 if bks:
3228 3228 size = max(map(len,bks))
3229 3229 else:
3230 3230 size = 0
3231 3231 fmt = '%-'+str(size)+'s -> %s'
3232 3232 print 'Current bookmarks:'
3233 3233 for bk in bks:
3234 3234 print fmt % (bk,bkms[bk])
3235 3235 else:
3236 3236 if not args:
3237 3237 raise UsageError("%bookmark: You must specify the bookmark name")
3238 3238 elif len(args)==1:
3239 3239 bkms[args[0]] = os.getcwd()
3240 3240 elif len(args)==2:
3241 3241 bkms[args[0]] = args[1]
3242 3242 self.db['bookmarks'] = bkms
3243 3243
3244 3244 def magic_pycat(self, parameter_s=''):
3245 3245 """Show a syntax-highlighted file through a pager.
3246 3246
3247 3247 This magic is similar to the cat utility, but it will assume the file
3248 3248 to be Python source and will show it with syntax highlighting. """
3249 3249
3250 3250 try:
3251 3251 filename = get_py_filename(parameter_s)
3252 3252 cont = file_read(filename)
3253 3253 except IOError:
3254 3254 try:
3255 3255 cont = eval(parameter_s,self.user_ns)
3256 3256 except NameError:
3257 3257 cont = None
3258 3258 if cont is None:
3259 3259 print "Error: no such file or variable"
3260 3260 return
3261 3261
3262 3262 page(self.shell.pycolorize(cont),
3263 3263 screen_lines=self.shell.rc.screen_length)
3264 3264
3265 3265 def magic_cpaste(self, parameter_s=''):
3266 3266 """Allows you to paste & execute a pre-formatted code block from clipboard.
3267 3267
3268 3268 You must terminate the block with '--' (two minus-signs) alone on the
3269 3269 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3270 3270 is the new sentinel for this operation)
3271 3271
3272 3272 The block is dedented prior to execution to enable execution of method
3273 3273 definitions. '>' and '+' characters at the beginning of a line are
3274 3274 ignored, to allow pasting directly from e-mails, diff files and
3275 3275 doctests (the '...' continuation prompt is also stripped). The
3276 3276 executed block is also assigned to variable named 'pasted_block' for
3277 3277 later editing with '%edit pasted_block'.
3278 3278
3279 3279 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3280 3280 This assigns the pasted block to variable 'foo' as string, without
3281 3281 dedenting or executing it (preceding >>> and + is still stripped)
3282 3282
3283 3283 '%cpaste -r' re-executes the block previously entered by cpaste.
3284 3284
3285 3285 Do not be alarmed by garbled output on Windows (it's a readline bug).
3286 3286 Just press enter and type -- (and press enter again) and the block
3287 3287 will be what was just pasted.
3288 3288
3289 3289 IPython statements (magics, shell escapes) are not supported (yet).
3290 3290 """
3291 3291 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3292 3292 par = args.strip()
3293 3293 if opts.has_key('r'):
3294 3294 b = self.user_ns.get('pasted_block', None)
3295 3295 if b is None:
3296 3296 raise UsageError('No previous pasted block available')
3297 3297 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3298 3298 exec b in self.user_ns
3299 3299 return
3300 3300
3301 3301 sentinel = opts.get('s','--')
3302 3302
3303 3303 # Regular expressions that declare text we strip from the input:
3304 3304 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3305 3305 r'^\s*(\s?>)+', # Python input prompt
3306 3306 r'^\s*\.{3,}', # Continuation prompts
3307 3307 r'^\++',
3308 3308 ]
3309 3309
3310 3310 strip_from_start = map(re.compile,strip_re)
3311 3311
3312 3312 from IPython.core import iplib
3313 3313 lines = []
3314 3314 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3315 3315 while 1:
3316 3316 l = iplib.raw_input_original(':')
3317 3317 if l ==sentinel:
3318 3318 break
3319 3319
3320 3320 for pat in strip_from_start:
3321 3321 l = pat.sub('',l)
3322 3322 lines.append(l)
3323 3323
3324 3324 block = "\n".join(lines) + '\n'
3325 3325 #print "block:\n",block
3326 3326 if not par:
3327 3327 b = textwrap.dedent(block)
3328 3328 self.user_ns['pasted_block'] = b
3329 3329 exec b in self.user_ns
3330 3330 else:
3331 3331 self.user_ns[par] = SList(block.splitlines())
3332 3332 print "Block assigned to '%s'" % par
3333 3333
3334 3334 def magic_quickref(self,arg):
3335 3335 """ Show a quick reference sheet """
3336 3336 import IPython.usage
3337 3337 qr = IPython.usage.quick_reference + self.magic_magic('-brief')
3338 3338
3339 3339 page(qr)
3340 3340
3341 3341 def magic_upgrade(self,arg):
3342 3342 """ Upgrade your IPython installation
3343 3343
3344 3344 This will copy the config files that don't yet exist in your
3345 3345 ipython dir from the system config dir. Use this after upgrading
3346 3346 IPython if you don't wish to delete your .ipython dir.
3347 3347
3348 3348 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3349 3349 new users)
3350 3350
3351 3351 """
3352 3352 ip = self.getapi()
3353 3353 ipinstallation = path(IPython.__file__).dirname()
3354 3354 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'upgrade_dir.py')
3355 3355 src_config = ipinstallation / 'UserConfig'
3356 3356 userdir = path(ip.options.ipythondir)
3357 3357 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3358 3358 print ">",cmd
3359 3359 shell(cmd)
3360 3360 if arg == '-nolegacy':
3361 3361 legacy = userdir.files('ipythonrc*')
3362 3362 print "Nuking legacy files:",legacy
3363 3363
3364 3364 [p.remove() for p in legacy]
3365 3365 suffix = (sys.platform == 'win32' and '.ini' or '')
3366 3366 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3367 3367
3368 3368
3369 3369 def magic_doctest_mode(self,parameter_s=''):
3370 3370 """Toggle doctest mode on and off.
3371 3371
3372 3372 This mode allows you to toggle the prompt behavior between normal
3373 3373 IPython prompts and ones that are as similar to the default IPython
3374 3374 interpreter as possible.
3375 3375
3376 3376 It also supports the pasting of code snippets that have leading '>>>'
3377 3377 and '...' prompts in them. This means that you can paste doctests from
3378 3378 files or docstrings (even if they have leading whitespace), and the
3379 3379 code will execute correctly. You can then use '%history -tn' to see
3380 3380 the translated history without line numbers; this will give you the
3381 3381 input after removal of all the leading prompts and whitespace, which
3382 3382 can be pasted back into an editor.
3383 3383
3384 3384 With these features, you can switch into this mode easily whenever you
3385 3385 need to do testing and changes to doctests, without having to leave
3386 3386 your existing IPython session.
3387 3387 """
3388 3388
3389 3389 # XXX - Fix this to have cleaner activate/deactivate calls.
3390 3390 from IPython.Extensions import InterpreterPasteInput as ipaste
3391 3391 from IPython.utils.ipstruct import Struct
3392 3392
3393 3393 # Shorthands
3394 3394 shell = self.shell
3395 3395 oc = shell.outputcache
3396 3396 rc = shell.rc
3397 3397 meta = shell.meta
3398 3398 # dstore is a data store kept in the instance metadata bag to track any
3399 3399 # changes we make, so we can undo them later.
3400 3400 dstore = meta.setdefault('doctest_mode',Struct())
3401 3401 save_dstore = dstore.setdefault
3402 3402
3403 3403 # save a few values we'll need to recover later
3404 3404 mode = save_dstore('mode',False)
3405 3405 save_dstore('rc_pprint',rc.pprint)
3406 3406 save_dstore('xmode',shell.InteractiveTB.mode)
3407 3407 save_dstore('rc_separate_out',rc.separate_out)
3408 3408 save_dstore('rc_separate_out2',rc.separate_out2)
3409 3409 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3410 3410 save_dstore('rc_separate_in',rc.separate_in)
3411 3411
3412 3412 if mode == False:
3413 3413 # turn on
3414 3414 ipaste.activate_prefilter()
3415 3415
3416 3416 oc.prompt1.p_template = '>>> '
3417 3417 oc.prompt2.p_template = '... '
3418 3418 oc.prompt_out.p_template = ''
3419 3419
3420 3420 # Prompt separators like plain python
3421 3421 oc.input_sep = oc.prompt1.sep = ''
3422 3422 oc.output_sep = ''
3423 3423 oc.output_sep2 = ''
3424 3424
3425 3425 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3426 3426 oc.prompt_out.pad_left = False
3427 3427
3428 3428 rc.pprint = False
3429 3429
3430 3430 shell.magic_xmode('Plain')
3431 3431
3432 3432 else:
3433 3433 # turn off
3434 3434 ipaste.deactivate_prefilter()
3435 3435
3436 3436 oc.prompt1.p_template = rc.prompt_in1
3437 3437 oc.prompt2.p_template = rc.prompt_in2
3438 3438 oc.prompt_out.p_template = rc.prompt_out
3439 3439
3440 3440 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3441 3441
3442 3442 oc.output_sep = dstore.rc_separate_out
3443 3443 oc.output_sep2 = dstore.rc_separate_out2
3444 3444
3445 3445 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3446 3446 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3447 3447
3448 3448 rc.pprint = dstore.rc_pprint
3449 3449
3450 3450 shell.magic_xmode(dstore.xmode)
3451 3451
3452 3452 # Store new mode and inform
3453 3453 dstore.mode = bool(1-int(mode))
3454 3454 print 'Doctest mode is:',
3455 3455 print ['OFF','ON'][dstore.mode]
3456 3456
3457 3457 # end Magic
@@ -1,607 +1,607 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Tools for inspecting Python objects.
3 3
4 4 Uses syntax highlighting for presenting the various information elements.
5 5
6 6 Similar in spirit to the inspect module, but all calls take a name argument to
7 7 reference the name under which an object is being read.
8 8 """
9 9
10 10 #*****************************************************************************
11 11 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
12 12 #
13 13 # Distributed under the terms of the BSD License. The full license is in
14 14 # the file COPYING, distributed as part of this software.
15 15 #*****************************************************************************
16 16
17 17 __all__ = ['Inspector','InspectColors']
18 18
19 19 # stdlib modules
20 20 import __builtin__
21 21 import StringIO
22 22 import inspect
23 23 import linecache
24 24 import os
25 25 import string
26 26 import sys
27 27 import types
28 28
29 29 # IPython's own
30 from IPython import PyColorize
30 from IPython.utils import PyColorize
31 31 from IPython.utils.genutils import page,indent,Term
32 32 from IPython.external.Itpl import itpl
33 33 from IPython.wildcard import list_namespace
34 34 from IPython.utils.coloransi import *
35 35
36 36 #****************************************************************************
37 37 # HACK!!! This is a crude fix for bugs in python 2.3's inspect module. We
38 38 # simply monkeypatch inspect with code copied from python 2.4.
39 39 if sys.version_info[:2] == (2,3):
40 40 from inspect import ismodule, getabsfile, modulesbyfile
41 41 def getmodule(object):
42 42 """Return the module an object was defined in, or None if not found."""
43 43 if ismodule(object):
44 44 return object
45 45 if hasattr(object, '__module__'):
46 46 return sys.modules.get(object.__module__)
47 47 try:
48 48 file = getabsfile(object)
49 49 except TypeError:
50 50 return None
51 51 if file in modulesbyfile:
52 52 return sys.modules.get(modulesbyfile[file])
53 53 for module in sys.modules.values():
54 54 if hasattr(module, '__file__'):
55 55 modulesbyfile[
56 56 os.path.realpath(
57 57 getabsfile(module))] = module.__name__
58 58 if file in modulesbyfile:
59 59 return sys.modules.get(modulesbyfile[file])
60 60 main = sys.modules['__main__']
61 61 if not hasattr(object, '__name__'):
62 62 return None
63 63 if hasattr(main, object.__name__):
64 64 mainobject = getattr(main, object.__name__)
65 65 if mainobject is object:
66 66 return main
67 67 builtin = sys.modules['__builtin__']
68 68 if hasattr(builtin, object.__name__):
69 69 builtinobject = getattr(builtin, object.__name__)
70 70 if builtinobject is object:
71 71 return builtin
72 72
73 73 inspect.getmodule = getmodule
74 74
75 75 #****************************************************************************
76 76 # Builtin color schemes
77 77
78 78 Colors = TermColors # just a shorthand
79 79
80 80 # Build a few color schemes
81 81 NoColor = ColorScheme(
82 82 'NoColor',{
83 83 'header' : Colors.NoColor,
84 84 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
85 85 } )
86 86
87 87 LinuxColors = ColorScheme(
88 88 'Linux',{
89 89 'header' : Colors.LightRed,
90 90 'normal' : Colors.Normal # color off (usu. Colors.Normal)
91 91 } )
92 92
93 93 LightBGColors = ColorScheme(
94 94 'LightBG',{
95 95 'header' : Colors.Red,
96 96 'normal' : Colors.Normal # color off (usu. Colors.Normal)
97 97 } )
98 98
99 99 # Build table of color schemes (needed by the parser)
100 100 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
101 101 'Linux')
102 102
103 103 #****************************************************************************
104 104 # Auxiliary functions
105 105 def getdoc(obj):
106 106 """Stable wrapper around inspect.getdoc.
107 107
108 108 This can't crash because of attribute problems.
109 109
110 110 It also attempts to call a getdoc() method on the given object. This
111 111 allows objects which provide their docstrings via non-standard mechanisms
112 112 (like Pyro proxies) to still be inspected by ipython's ? system."""
113 113
114 114 ds = None # default return value
115 115 try:
116 116 ds = inspect.getdoc(obj)
117 117 except:
118 118 # Harden against an inspect failure, which can occur with
119 119 # SWIG-wrapped extensions.
120 120 pass
121 121 # Allow objects to offer customized documentation via a getdoc method:
122 122 try:
123 123 ds2 = obj.getdoc()
124 124 except:
125 125 pass
126 126 else:
127 127 # if we get extra info, we add it to the normal docstring.
128 128 if ds is None:
129 129 ds = ds2
130 130 else:
131 131 ds = '%s\n%s' % (ds,ds2)
132 132 return ds
133 133
134 134
135 135 def getsource(obj,is_binary=False):
136 136 """Wrapper around inspect.getsource.
137 137
138 138 This can be modified by other projects to provide customized source
139 139 extraction.
140 140
141 141 Inputs:
142 142
143 143 - obj: an object whose source code we will attempt to extract.
144 144
145 145 Optional inputs:
146 146
147 147 - is_binary: whether the object is known to come from a binary source.
148 148 This implementation will skip returning any output for binary objects, but
149 149 custom extractors may know how to meaningfully process them."""
150 150
151 151 if is_binary:
152 152 return None
153 153 else:
154 154 try:
155 155 src = inspect.getsource(obj)
156 156 except TypeError:
157 157 if hasattr(obj,'__class__'):
158 158 src = inspect.getsource(obj.__class__)
159 159 return src
160 160
161 161 def getargspec(obj):
162 162 """Get the names and default values of a function's arguments.
163 163
164 164 A tuple of four things is returned: (args, varargs, varkw, defaults).
165 165 'args' is a list of the argument names (it may contain nested lists).
166 166 'varargs' and 'varkw' are the names of the * and ** arguments or None.
167 167 'defaults' is an n-tuple of the default values of the last n arguments.
168 168
169 169 Modified version of inspect.getargspec from the Python Standard
170 170 Library."""
171 171
172 172 if inspect.isfunction(obj):
173 173 func_obj = obj
174 174 elif inspect.ismethod(obj):
175 175 func_obj = obj.im_func
176 176 else:
177 177 raise TypeError, 'arg is not a Python function'
178 178 args, varargs, varkw = inspect.getargs(func_obj.func_code)
179 179 return args, varargs, varkw, func_obj.func_defaults
180 180
181 181 #****************************************************************************
182 182 # Class definitions
183 183
184 184 class myStringIO(StringIO.StringIO):
185 185 """Adds a writeln method to normal StringIO."""
186 186 def writeln(self,*arg,**kw):
187 187 """Does a write() and then a write('\n')"""
188 188 self.write(*arg,**kw)
189 189 self.write('\n')
190 190
191 191
192 192 class Inspector:
193 193 def __init__(self,color_table,code_color_table,scheme,
194 194 str_detail_level=0):
195 195 self.color_table = color_table
196 196 self.parser = PyColorize.Parser(code_color_table,out='str')
197 197 self.format = self.parser.format
198 198 self.str_detail_level = str_detail_level
199 199 self.set_active_scheme(scheme)
200 200
201 201 def __getdef(self,obj,oname=''):
202 202 """Return the definition header for any callable object.
203 203
204 204 If any exception is generated, None is returned instead and the
205 205 exception is suppressed."""
206 206
207 207 try:
208 208 return oname + inspect.formatargspec(*getargspec(obj))
209 209 except:
210 210 return None
211 211
212 212 def __head(self,h):
213 213 """Return a header string with proper colors."""
214 214 return '%s%s%s' % (self.color_table.active_colors.header,h,
215 215 self.color_table.active_colors.normal)
216 216
217 217 def set_active_scheme(self,scheme):
218 218 self.color_table.set_active_scheme(scheme)
219 219 self.parser.color_table.set_active_scheme(scheme)
220 220
221 221 def noinfo(self,msg,oname):
222 222 """Generic message when no information is found."""
223 223 print 'No %s found' % msg,
224 224 if oname:
225 225 print 'for %s' % oname
226 226 else:
227 227 print
228 228
229 229 def pdef(self,obj,oname=''):
230 230 """Print the definition header for any callable object.
231 231
232 232 If the object is a class, print the constructor information."""
233 233
234 234 if not callable(obj):
235 235 print 'Object is not callable.'
236 236 return
237 237
238 238 header = ''
239 239
240 240 if inspect.isclass(obj):
241 241 header = self.__head('Class constructor information:\n')
242 242 obj = obj.__init__
243 243 elif type(obj) is types.InstanceType:
244 244 obj = obj.__call__
245 245
246 246 output = self.__getdef(obj,oname)
247 247 if output is None:
248 248 self.noinfo('definition header',oname)
249 249 else:
250 250 print >>Term.cout, header,self.format(output),
251 251
252 252 def pdoc(self,obj,oname='',formatter = None):
253 253 """Print the docstring for any object.
254 254
255 255 Optional:
256 256 -formatter: a function to run the docstring through for specially
257 257 formatted docstrings."""
258 258
259 259 head = self.__head # so that itpl can find it even if private
260 260 ds = getdoc(obj)
261 261 if formatter:
262 262 ds = formatter(ds)
263 263 if inspect.isclass(obj):
264 264 init_ds = getdoc(obj.__init__)
265 265 output = itpl('$head("Class Docstring:")\n'
266 266 '$indent(ds)\n'
267 267 '$head("Constructor Docstring"):\n'
268 268 '$indent(init_ds)')
269 269 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
270 270 and hasattr(obj,'__call__'):
271 271 call_ds = getdoc(obj.__call__)
272 272 if call_ds:
273 273 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
274 274 '$head("Calling Docstring:")\n$indent(call_ds)')
275 275 else:
276 276 output = ds
277 277 else:
278 278 output = ds
279 279 if output is None:
280 280 self.noinfo('documentation',oname)
281 281 return
282 282 page(output)
283 283
284 284 def psource(self,obj,oname=''):
285 285 """Print the source code for an object."""
286 286
287 287 # Flush the source cache because inspect can return out-of-date source
288 288 linecache.checkcache()
289 289 try:
290 290 src = getsource(obj)
291 291 except:
292 292 self.noinfo('source',oname)
293 293 else:
294 294 page(self.format(src))
295 295
296 296 def pfile(self,obj,oname=''):
297 297 """Show the whole file where an object was defined."""
298 298
299 299 try:
300 300 try:
301 301 lineno = inspect.getsourcelines(obj)[1]
302 302 except TypeError:
303 303 # For instances, try the class object like getsource() does
304 304 if hasattr(obj,'__class__'):
305 305 lineno = inspect.getsourcelines(obj.__class__)[1]
306 306 # Adjust the inspected object so getabsfile() below works
307 307 obj = obj.__class__
308 308 except:
309 309 self.noinfo('file',oname)
310 310 return
311 311
312 312 # We only reach this point if object was successfully queried
313 313
314 314 # run contents of file through pager starting at line
315 315 # where the object is defined
316 316 ofile = inspect.getabsfile(obj)
317 317
318 318 if (ofile.endswith('.so') or ofile.endswith('.dll')):
319 319 print 'File %r is binary, not printing.' % ofile
320 320 elif not os.path.isfile(ofile):
321 321 print 'File %r does not exist, not printing.' % ofile
322 322 else:
323 323 # Print only text files, not extension binaries. Note that
324 324 # getsourcelines returns lineno with 1-offset and page() uses
325 325 # 0-offset, so we must adjust.
326 326 page(self.format(open(ofile).read()),lineno-1)
327 327
328 328 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
329 329 """Show detailed information about an object.
330 330
331 331 Optional arguments:
332 332
333 333 - oname: name of the variable pointing to the object.
334 334
335 335 - formatter: special formatter for docstrings (see pdoc)
336 336
337 337 - info: a structure with some information fields which may have been
338 338 precomputed already.
339 339
340 340 - detail_level: if set to 1, more information is given.
341 341 """
342 342
343 343 obj_type = type(obj)
344 344
345 345 header = self.__head
346 346 if info is None:
347 347 ismagic = 0
348 348 isalias = 0
349 349 ospace = ''
350 350 else:
351 351 ismagic = info.ismagic
352 352 isalias = info.isalias
353 353 ospace = info.namespace
354 354 # Get docstring, special-casing aliases:
355 355 if isalias:
356 356 if not callable(obj):
357 357 try:
358 358 ds = "Alias to the system command:\n %s" % obj[1]
359 359 except:
360 360 ds = "Alias: " + str(obj)
361 361 else:
362 362 ds = "Alias to " + str(obj)
363 363 if obj.__doc__:
364 364 ds += "\nDocstring:\n" + obj.__doc__
365 365 else:
366 366 ds = getdoc(obj)
367 367 if ds is None:
368 368 ds = '<no docstring>'
369 369 if formatter is not None:
370 370 ds = formatter(ds)
371 371
372 372 # store output in a list which gets joined with \n at the end.
373 373 out = myStringIO()
374 374
375 375 string_max = 200 # max size of strings to show (snipped if longer)
376 376 shalf = int((string_max -5)/2)
377 377
378 378 if ismagic:
379 379 obj_type_name = 'Magic function'
380 380 elif isalias:
381 381 obj_type_name = 'System alias'
382 382 else:
383 383 obj_type_name = obj_type.__name__
384 384 out.writeln(header('Type:\t\t')+obj_type_name)
385 385
386 386 try:
387 387 bclass = obj.__class__
388 388 out.writeln(header('Base Class:\t')+str(bclass))
389 389 except: pass
390 390
391 391 # String form, but snip if too long in ? form (full in ??)
392 392 if detail_level >= self.str_detail_level:
393 393 try:
394 394 ostr = str(obj)
395 395 str_head = 'String Form:'
396 396 if not detail_level and len(ostr)>string_max:
397 397 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
398 398 ostr = ("\n" + " " * len(str_head.expandtabs())).\
399 399 join(map(string.strip,ostr.split("\n")))
400 400 if ostr.find('\n') > -1:
401 401 # Print multi-line strings starting at the next line.
402 402 str_sep = '\n'
403 403 else:
404 404 str_sep = '\t'
405 405 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
406 406 except:
407 407 pass
408 408
409 409 if ospace:
410 410 out.writeln(header('Namespace:\t')+ospace)
411 411
412 412 # Length (for strings and lists)
413 413 try:
414 414 length = str(len(obj))
415 415 out.writeln(header('Length:\t\t')+length)
416 416 except: pass
417 417
418 418 # Filename where object was defined
419 419 binary_file = False
420 420 try:
421 421 try:
422 422 fname = inspect.getabsfile(obj)
423 423 except TypeError:
424 424 # For an instance, the file that matters is where its class was
425 425 # declared.
426 426 if hasattr(obj,'__class__'):
427 427 fname = inspect.getabsfile(obj.__class__)
428 428 if fname.endswith('<string>'):
429 429 fname = 'Dynamically generated function. No source code available.'
430 430 if (fname.endswith('.so') or fname.endswith('.dll')):
431 431 binary_file = True
432 432 out.writeln(header('File:\t\t')+fname)
433 433 except:
434 434 # if anything goes wrong, we don't want to show source, so it's as
435 435 # if the file was binary
436 436 binary_file = True
437 437
438 438 # reconstruct the function definition and print it:
439 439 defln = self.__getdef(obj,oname)
440 440 if defln:
441 441 out.write(header('Definition:\t')+self.format(defln))
442 442
443 443 # Docstrings only in detail 0 mode, since source contains them (we
444 444 # avoid repetitions). If source fails, we add them back, see below.
445 445 if ds and detail_level == 0:
446 446 out.writeln(header('Docstring:\n') + indent(ds))
447 447
448 448 # Original source code for any callable
449 449 if detail_level:
450 450 # Flush the source cache because inspect can return out-of-date
451 451 # source
452 452 linecache.checkcache()
453 453 source_success = False
454 454 try:
455 455 try:
456 456 src = getsource(obj,binary_file)
457 457 except TypeError:
458 458 if hasattr(obj,'__class__'):
459 459 src = getsource(obj.__class__,binary_file)
460 460 if src is not None:
461 461 source = self.format(src)
462 462 out.write(header('Source:\n')+source.rstrip())
463 463 source_success = True
464 464 except Exception, msg:
465 465 pass
466 466
467 467 if ds and not source_success:
468 468 out.writeln(header('Docstring [source file open failed]:\n')
469 469 + indent(ds))
470 470
471 471 # Constructor docstring for classes
472 472 if inspect.isclass(obj):
473 473 # reconstruct the function definition and print it:
474 474 try:
475 475 obj_init = obj.__init__
476 476 except AttributeError:
477 477 init_def = init_ds = None
478 478 else:
479 479 init_def = self.__getdef(obj_init,oname)
480 480 init_ds = getdoc(obj_init)
481 481 # Skip Python's auto-generated docstrings
482 482 if init_ds and \
483 483 init_ds.startswith('x.__init__(...) initializes'):
484 484 init_ds = None
485 485
486 486 if init_def or init_ds:
487 487 out.writeln(header('\nConstructor information:'))
488 488 if init_def:
489 489 out.write(header('Definition:\t')+ self.format(init_def))
490 490 if init_ds:
491 491 out.writeln(header('Docstring:\n') + indent(init_ds))
492 492 # and class docstring for instances:
493 493 elif obj_type is types.InstanceType or \
494 494 isinstance(obj,object):
495 495
496 496 # First, check whether the instance docstring is identical to the
497 497 # class one, and print it separately if they don't coincide. In
498 498 # most cases they will, but it's nice to print all the info for
499 499 # objects which use instance-customized docstrings.
500 500 if ds:
501 501 try:
502 502 cls = getattr(obj,'__class__')
503 503 except:
504 504 class_ds = None
505 505 else:
506 506 class_ds = getdoc(cls)
507 507 # Skip Python's auto-generated docstrings
508 508 if class_ds and \
509 509 (class_ds.startswith('function(code, globals[,') or \
510 510 class_ds.startswith('instancemethod(function, instance,') or \
511 511 class_ds.startswith('module(name[,') ):
512 512 class_ds = None
513 513 if class_ds and ds != class_ds:
514 514 out.writeln(header('Class Docstring:\n') +
515 515 indent(class_ds))
516 516
517 517 # Next, try to show constructor docstrings
518 518 try:
519 519 init_ds = getdoc(obj.__init__)
520 520 # Skip Python's auto-generated docstrings
521 521 if init_ds and \
522 522 init_ds.startswith('x.__init__(...) initializes'):
523 523 init_ds = None
524 524 except AttributeError:
525 525 init_ds = None
526 526 if init_ds:
527 527 out.writeln(header('Constructor Docstring:\n') +
528 528 indent(init_ds))
529 529
530 530 # Call form docstring for callable instances
531 531 if hasattr(obj,'__call__'):
532 532 #out.writeln(header('Callable:\t')+'Yes')
533 533 call_def = self.__getdef(obj.__call__,oname)
534 534 #if call_def is None:
535 535 # out.writeln(header('Call def:\t')+
536 536 # 'Calling definition not available.')
537 537 if call_def is not None:
538 538 out.writeln(header('Call def:\t')+self.format(call_def))
539 539 call_ds = getdoc(obj.__call__)
540 540 # Skip Python's auto-generated docstrings
541 541 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
542 542 call_ds = None
543 543 if call_ds:
544 544 out.writeln(header('Call docstring:\n') + indent(call_ds))
545 545
546 546 # Finally send to printer/pager
547 547 output = out.getvalue()
548 548 if output:
549 549 page(output)
550 550 # end pinfo
551 551
552 552 def psearch(self,pattern,ns_table,ns_search=[],
553 553 ignore_case=False,show_all=False):
554 554 """Search namespaces with wildcards for objects.
555 555
556 556 Arguments:
557 557
558 558 - pattern: string containing shell-like wildcards to use in namespace
559 559 searches and optionally a type specification to narrow the search to
560 560 objects of that type.
561 561
562 562 - ns_table: dict of name->namespaces for search.
563 563
564 564 Optional arguments:
565 565
566 566 - ns_search: list of namespace names to include in search.
567 567
568 568 - ignore_case(False): make the search case-insensitive.
569 569
570 570 - show_all(False): show all names, including those starting with
571 571 underscores.
572 572 """
573 573 #print 'ps pattern:<%r>' % pattern # dbg
574 574
575 575 # defaults
576 576 type_pattern = 'all'
577 577 filter = ''
578 578
579 579 cmds = pattern.split()
580 580 len_cmds = len(cmds)
581 581 if len_cmds == 1:
582 582 # Only filter pattern given
583 583 filter = cmds[0]
584 584 elif len_cmds == 2:
585 585 # Both filter and type specified
586 586 filter,type_pattern = cmds
587 587 else:
588 588 raise ValueError('invalid argument string for psearch: <%s>' %
589 589 pattern)
590 590
591 591 # filter search namespaces
592 592 for name in ns_search:
593 593 if name not in ns_table:
594 594 raise ValueError('invalid namespace <%s>. Valid names: %s' %
595 595 (name,ns_table.keys()))
596 596
597 597 #print 'type_pattern:',type_pattern # dbg
598 598 search_result = []
599 599 for ns_name in ns_search:
600 600 ns = ns_table[ns_name]
601 601 tmp_res = list(list_namespace(ns,type_pattern,filter,
602 602 ignore_case=ignore_case,
603 603 show_all=show_all))
604 604 search_result.extend(tmp_res)
605 605 search_result.sort()
606 606
607 607 page('\n'.join(search_result))
@@ -1,1067 +1,1067 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 ultraTB.py -- Spice up your tracebacks!
4 4
5 5 * ColorTB
6 6 I've always found it a bit hard to visually parse tracebacks in Python. The
7 7 ColorTB class is a solution to that problem. It colors the different parts of a
8 8 traceback in a manner similar to what you would expect from a syntax-highlighting
9 9 text editor.
10 10
11 11 Installation instructions for ColorTB:
12 12 import sys,ultraTB
13 13 sys.excepthook = ultraTB.ColorTB()
14 14
15 15 * VerboseTB
16 16 I've also included a port of Ka-Ping Yee's "cgitb.py" that produces all kinds
17 17 of useful info when a traceback occurs. Ping originally had it spit out HTML
18 18 and intended it for CGI programmers, but why should they have all the fun? I
19 19 altered it to spit out colored text to the terminal. It's a bit overwhelming,
20 20 but kind of neat, and maybe useful for long-running programs that you believe
21 21 are bug-free. If a crash *does* occur in that type of program you want details.
22 22 Give it a shot--you'll love it or you'll hate it.
23 23
24 24 Note:
25 25
26 26 The Verbose mode prints the variables currently visible where the exception
27 27 happened (shortening their strings if too long). This can potentially be
28 28 very slow, if you happen to have a huge data structure whose string
29 29 representation is complex to compute. Your computer may appear to freeze for
30 30 a while with cpu usage at 100%. If this occurs, you can cancel the traceback
31 31 with Ctrl-C (maybe hitting it more than once).
32 32
33 33 If you encounter this kind of situation often, you may want to use the
34 34 Verbose_novars mode instead of the regular Verbose, which avoids formatting
35 35 variables (but otherwise includes the information and context given by
36 36 Verbose).
37 37
38 38
39 39 Installation instructions for ColorTB:
40 40 import sys,ultraTB
41 41 sys.excepthook = ultraTB.VerboseTB()
42 42
43 43 Note: Much of the code in this module was lifted verbatim from the standard
44 44 library module 'traceback.py' and Ka-Ping Yee's 'cgitb.py'.
45 45
46 46 * Color schemes
47 47 The colors are defined in the class TBTools through the use of the
48 48 ColorSchemeTable class. Currently the following exist:
49 49
50 50 - NoColor: allows all of this module to be used in any terminal (the color
51 51 escapes are just dummy blank strings).
52 52
53 53 - Linux: is meant to look good in a terminal like the Linux console (black
54 54 or very dark background).
55 55
56 56 - LightBG: similar to Linux but swaps dark/light colors to be more readable
57 57 in light background terminals.
58 58
59 59 You can implement other color schemes easily, the syntax is fairly
60 60 self-explanatory. Please send back new schemes you develop to the author for
61 61 possible inclusion in future releases.
62 62 """
63 63
64 64 #*****************************************************************************
65 65 # Copyright (C) 2001 Nathaniel Gray <n8gray@caltech.edu>
66 66 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
67 67 #
68 68 # Distributed under the terms of the BSD License. The full license is in
69 69 # the file COPYING, distributed as part of this software.
70 70 #*****************************************************************************
71 71
72 72 # Required modules
73 73 import inspect
74 74 import keyword
75 75 import linecache
76 76 import os
77 77 import pydoc
78 78 import re
79 79 import string
80 80 import sys
81 81 import time
82 82 import tokenize
83 83 import traceback
84 84 import types
85 85
86 86 # For purposes of monkeypatching inspect to fix a bug in it.
87 87 from inspect import getsourcefile, getfile, getmodule,\
88 88 ismodule, isclass, ismethod, isfunction, istraceback, isframe, iscode
89 89
90 90
91 91 # IPython's own modules
92 92 # Modified pdb which doesn't damage IPython's readline handling
93 from IPython import PyColorize
93 from IPython.utils import PyColorize
94 94 from IPython.core import debugger
95 95 from IPython.utils.ipstruct import Struct
96 96 from IPython.core.excolors import exception_colors
97 97 from IPython.utils.genutils import Term,uniq_stable,error,info
98 98
99 99 # Globals
100 100 # amount of space to put line numbers before verbose tracebacks
101 101 INDENT_SIZE = 8
102 102
103 103 # Default color scheme. This is used, for example, by the traceback
104 104 # formatter. When running in an actual IPython instance, the user's rc.colors
105 105 # value is used, but havinga module global makes this functionality available
106 106 # to users of ultraTB who are NOT running inside ipython.
107 107 DEFAULT_SCHEME = 'NoColor'
108 108
109 109 #---------------------------------------------------------------------------
110 110 # Code begins
111 111
112 112 # Utility functions
113 113 def inspect_error():
114 114 """Print a message about internal inspect errors.
115 115
116 116 These are unfortunately quite common."""
117 117
118 118 error('Internal Python error in the inspect module.\n'
119 119 'Below is the traceback from this internal error.\n')
120 120
121 121
122 122 def findsource(object):
123 123 """Return the entire source file and starting line number for an object.
124 124
125 125 The argument may be a module, class, method, function, traceback, frame,
126 126 or code object. The source code is returned as a list of all the lines
127 127 in the file and the line number indexes a line in that list. An IOError
128 128 is raised if the source code cannot be retrieved.
129 129
130 130 FIXED version with which we monkeypatch the stdlib to work around a bug."""
131 131
132 132 file = getsourcefile(object) or getfile(object)
133 133 # If the object is a frame, then trying to get the globals dict from its
134 134 # module won't work. Instead, the frame object itself has the globals
135 135 # dictionary.
136 136 globals_dict = None
137 137 if inspect.isframe(object):
138 138 # XXX: can this ever be false?
139 139 globals_dict = object.f_globals
140 140 else:
141 141 module = getmodule(object, file)
142 142 if module:
143 143 globals_dict = module.__dict__
144 144 lines = linecache.getlines(file, globals_dict)
145 145 if not lines:
146 146 raise IOError('could not get source code')
147 147
148 148 if ismodule(object):
149 149 return lines, 0
150 150
151 151 if isclass(object):
152 152 name = object.__name__
153 153 pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
154 154 # make some effort to find the best matching class definition:
155 155 # use the one with the least indentation, which is the one
156 156 # that's most probably not inside a function definition.
157 157 candidates = []
158 158 for i in range(len(lines)):
159 159 match = pat.match(lines[i])
160 160 if match:
161 161 # if it's at toplevel, it's already the best one
162 162 if lines[i][0] == 'c':
163 163 return lines, i
164 164 # else add whitespace to candidate list
165 165 candidates.append((match.group(1), i))
166 166 if candidates:
167 167 # this will sort by whitespace, and by line number,
168 168 # less whitespace first
169 169 candidates.sort()
170 170 return lines, candidates[0][1]
171 171 else:
172 172 raise IOError('could not find class definition')
173 173
174 174 if ismethod(object):
175 175 object = object.im_func
176 176 if isfunction(object):
177 177 object = object.func_code
178 178 if istraceback(object):
179 179 object = object.tb_frame
180 180 if isframe(object):
181 181 object = object.f_code
182 182 if iscode(object):
183 183 if not hasattr(object, 'co_firstlineno'):
184 184 raise IOError('could not find function definition')
185 185 pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
186 186 pmatch = pat.match
187 187 # fperez - fix: sometimes, co_firstlineno can give a number larger than
188 188 # the length of lines, which causes an error. Safeguard against that.
189 189 lnum = min(object.co_firstlineno,len(lines))-1
190 190 while lnum > 0:
191 191 if pmatch(lines[lnum]): break
192 192 lnum -= 1
193 193
194 194 return lines, lnum
195 195 raise IOError('could not find code object')
196 196
197 197 # Monkeypatch inspect to apply our bugfix. This code only works with py25
198 198 if sys.version_info[:2] >= (2,5):
199 199 inspect.findsource = findsource
200 200
201 201 def fix_frame_records_filenames(records):
202 202 """Try to fix the filenames in each record from inspect.getinnerframes().
203 203
204 204 Particularly, modules loaded from within zip files have useless filenames
205 205 attached to their code object, and inspect.getinnerframes() just uses it.
206 206 """
207 207 fixed_records = []
208 208 for frame, filename, line_no, func_name, lines, index in records:
209 209 # Look inside the frame's globals dictionary for __file__, which should
210 210 # be better.
211 211 better_fn = frame.f_globals.get('__file__', None)
212 212 if isinstance(better_fn, str):
213 213 # Check the type just in case someone did something weird with
214 214 # __file__. It might also be None if the error occurred during
215 215 # import.
216 216 filename = better_fn
217 217 fixed_records.append((frame, filename, line_no, func_name, lines, index))
218 218 return fixed_records
219 219
220 220
221 221 def _fixed_getinnerframes(etb, context=1,tb_offset=0):
222 222 import linecache
223 223 LNUM_POS, LINES_POS, INDEX_POS = 2, 4, 5
224 224
225 225 records = fix_frame_records_filenames(inspect.getinnerframes(etb, context))
226 226
227 227 # If the error is at the console, don't build any context, since it would
228 228 # otherwise produce 5 blank lines printed out (there is no file at the
229 229 # console)
230 230 rec_check = records[tb_offset:]
231 231 try:
232 232 rname = rec_check[0][1]
233 233 if rname == '<ipython console>' or rname.endswith('<string>'):
234 234 return rec_check
235 235 except IndexError:
236 236 pass
237 237
238 238 aux = traceback.extract_tb(etb)
239 239 assert len(records) == len(aux)
240 240 for i, (file, lnum, _, _) in zip(range(len(records)), aux):
241 241 maybeStart = lnum-1 - context//2
242 242 start = max(maybeStart, 0)
243 243 end = start + context
244 244 lines = linecache.getlines(file)[start:end]
245 245 # pad with empty lines if necessary
246 246 if maybeStart < 0:
247 247 lines = (['\n'] * -maybeStart) + lines
248 248 if len(lines) < context:
249 249 lines += ['\n'] * (context - len(lines))
250 250 buf = list(records[i])
251 251 buf[LNUM_POS] = lnum
252 252 buf[INDEX_POS] = lnum - 1 - start
253 253 buf[LINES_POS] = lines
254 254 records[i] = tuple(buf)
255 255 return records[tb_offset:]
256 256
257 257 # Helper function -- largely belongs to VerboseTB, but we need the same
258 258 # functionality to produce a pseudo verbose TB for SyntaxErrors, so that they
259 259 # can be recognized properly by ipython.el's py-traceback-line-re
260 260 # (SyntaxErrors have to be treated specially because they have no traceback)
261 261
262 262 _parser = PyColorize.Parser()
263 263
264 264 def _formatTracebackLines(lnum, index, lines, Colors, lvals=None,scheme=None):
265 265 numbers_width = INDENT_SIZE - 1
266 266 res = []
267 267 i = lnum - index
268 268
269 269 # This lets us get fully syntax-highlighted tracebacks.
270 270 if scheme is None:
271 271 try:
272 272 # Again, reference to a global __IPYTHON__ that doesn't exist.
273 273 # XXX
274 274 scheme = __IPYTHON__.rc.colors
275 275 except:
276 276 scheme = DEFAULT_SCHEME
277 277 _line_format = _parser.format2
278 278
279 279 for line in lines:
280 280 new_line, err = _line_format(line,'str',scheme)
281 281 if not err: line = new_line
282 282
283 283 if i == lnum:
284 284 # This is the line with the error
285 285 pad = numbers_width - len(str(i))
286 286 if pad >= 3:
287 287 marker = '-'*(pad-3) + '-> '
288 288 elif pad == 2:
289 289 marker = '> '
290 290 elif pad == 1:
291 291 marker = '>'
292 292 else:
293 293 marker = ''
294 294 num = marker + str(i)
295 295 line = '%s%s%s %s%s' %(Colors.linenoEm, num,
296 296 Colors.line, line, Colors.Normal)
297 297 else:
298 298 num = '%*s' % (numbers_width,i)
299 299 line = '%s%s%s %s' %(Colors.lineno, num,
300 300 Colors.Normal, line)
301 301
302 302 res.append(line)
303 303 if lvals and i == lnum:
304 304 res.append(lvals + '\n')
305 305 i = i + 1
306 306 return res
307 307
308 308
309 309 #---------------------------------------------------------------------------
310 310 # Module classes
311 311 class TBTools:
312 312 """Basic tools used by all traceback printer classes."""
313 313
314 314 def __init__(self,color_scheme = 'NoColor',call_pdb=False):
315 315 # Whether to call the interactive pdb debugger after printing
316 316 # tracebacks or not
317 317 self.call_pdb = call_pdb
318 318
319 319 # Create color table
320 320 self.color_scheme_table = exception_colors()
321 321
322 322 self.set_colors(color_scheme)
323 323 self.old_scheme = color_scheme # save initial value for toggles
324 324
325 325 if call_pdb:
326 326 self.pdb = debugger.Pdb(self.color_scheme_table.active_scheme_name)
327 327 else:
328 328 self.pdb = None
329 329
330 330 def set_colors(self,*args,**kw):
331 331 """Shorthand access to the color table scheme selector method."""
332 332
333 333 # Set own color table
334 334 self.color_scheme_table.set_active_scheme(*args,**kw)
335 335 # for convenience, set Colors to the active scheme
336 336 self.Colors = self.color_scheme_table.active_colors
337 337 # Also set colors of debugger
338 338 if hasattr(self,'pdb') and self.pdb is not None:
339 339 self.pdb.set_colors(*args,**kw)
340 340
341 341 def color_toggle(self):
342 342 """Toggle between the currently active color scheme and NoColor."""
343 343
344 344 if self.color_scheme_table.active_scheme_name == 'NoColor':
345 345 self.color_scheme_table.set_active_scheme(self.old_scheme)
346 346 self.Colors = self.color_scheme_table.active_colors
347 347 else:
348 348 self.old_scheme = self.color_scheme_table.active_scheme_name
349 349 self.color_scheme_table.set_active_scheme('NoColor')
350 350 self.Colors = self.color_scheme_table.active_colors
351 351
352 352 #---------------------------------------------------------------------------
353 353 class ListTB(TBTools):
354 354 """Print traceback information from a traceback list, with optional color.
355 355
356 356 Calling: requires 3 arguments:
357 357 (etype, evalue, elist)
358 358 as would be obtained by:
359 359 etype, evalue, tb = sys.exc_info()
360 360 if tb:
361 361 elist = traceback.extract_tb(tb)
362 362 else:
363 363 elist = None
364 364
365 365 It can thus be used by programs which need to process the traceback before
366 366 printing (such as console replacements based on the code module from the
367 367 standard library).
368 368
369 369 Because they are meant to be called without a full traceback (only a
370 370 list), instances of this class can't call the interactive pdb debugger."""
371 371
372 372 def __init__(self,color_scheme = 'NoColor'):
373 373 TBTools.__init__(self,color_scheme = color_scheme,call_pdb=0)
374 374
375 375 def __call__(self, etype, value, elist):
376 376 Term.cout.flush()
377 377 print >> Term.cerr, self.text(etype,value,elist)
378 378 Term.cerr.flush()
379 379
380 380 def text(self,etype, value, elist,context=5):
381 381 """Return a color formatted string with the traceback info."""
382 382
383 383 Colors = self.Colors
384 384 out_string = ['%s%s%s\n' % (Colors.topline,'-'*60,Colors.Normal)]
385 385 if elist:
386 386 out_string.append('Traceback %s(most recent call last)%s:' % \
387 387 (Colors.normalEm, Colors.Normal) + '\n')
388 388 out_string.extend(self._format_list(elist))
389 389 lines = self._format_exception_only(etype, value)
390 390 for line in lines[:-1]:
391 391 out_string.append(" "+line)
392 392 out_string.append(lines[-1])
393 393 return ''.join(out_string)
394 394
395 395 def _format_list(self, extracted_list):
396 396 """Format a list of traceback entry tuples for printing.
397 397
398 398 Given a list of tuples as returned by extract_tb() or
399 399 extract_stack(), return a list of strings ready for printing.
400 400 Each string in the resulting list corresponds to the item with the
401 401 same index in the argument list. Each string ends in a newline;
402 402 the strings may contain internal newlines as well, for those items
403 403 whose source text line is not None.
404 404
405 405 Lifted almost verbatim from traceback.py
406 406 """
407 407
408 408 Colors = self.Colors
409 409 list = []
410 410 for filename, lineno, name, line in extracted_list[:-1]:
411 411 item = ' File %s"%s"%s, line %s%d%s, in %s%s%s\n' % \
412 412 (Colors.filename, filename, Colors.Normal,
413 413 Colors.lineno, lineno, Colors.Normal,
414 414 Colors.name, name, Colors.Normal)
415 415 if line:
416 416 item = item + ' %s\n' % line.strip()
417 417 list.append(item)
418 418 # Emphasize the last entry
419 419 filename, lineno, name, line = extracted_list[-1]
420 420 item = '%s File %s"%s"%s, line %s%d%s, in %s%s%s%s\n' % \
421 421 (Colors.normalEm,
422 422 Colors.filenameEm, filename, Colors.normalEm,
423 423 Colors.linenoEm, lineno, Colors.normalEm,
424 424 Colors.nameEm, name, Colors.normalEm,
425 425 Colors.Normal)
426 426 if line:
427 427 item = item + '%s %s%s\n' % (Colors.line, line.strip(),
428 428 Colors.Normal)
429 429 list.append(item)
430 430 return list
431 431
432 432 def _format_exception_only(self, etype, value):
433 433 """Format the exception part of a traceback.
434 434
435 435 The arguments are the exception type and value such as given by
436 436 sys.exc_info()[:2]. The return value is a list of strings, each ending
437 437 in a newline. Normally, the list contains a single string; however,
438 438 for SyntaxError exceptions, it contains several lines that (when
439 439 printed) display detailed information about where the syntax error
440 440 occurred. The message indicating which exception occurred is the
441 441 always last string in the list.
442 442
443 443 Also lifted nearly verbatim from traceback.py
444 444 """
445 445
446 446 have_filedata = False
447 447 Colors = self.Colors
448 448 list = []
449 449 try:
450 450 stype = Colors.excName + etype.__name__ + Colors.Normal
451 451 except AttributeError:
452 452 stype = etype # String exceptions don't get special coloring
453 453 if value is None:
454 454 list.append( str(stype) + '\n')
455 455 else:
456 456 if etype is SyntaxError:
457 457 try:
458 458 msg, (filename, lineno, offset, line) = value
459 459 except:
460 460 have_filedata = False
461 461 else:
462 462 have_filedata = True
463 463 #print 'filename is',filename # dbg
464 464 if not filename: filename = "<string>"
465 465 list.append('%s File %s"%s"%s, line %s%d%s\n' % \
466 466 (Colors.normalEm,
467 467 Colors.filenameEm, filename, Colors.normalEm,
468 468 Colors.linenoEm, lineno, Colors.Normal ))
469 469 if line is not None:
470 470 i = 0
471 471 while i < len(line) and line[i].isspace():
472 472 i = i+1
473 473 list.append('%s %s%s\n' % (Colors.line,
474 474 line.strip(),
475 475 Colors.Normal))
476 476 if offset is not None:
477 477 s = ' '
478 478 for c in line[i:offset-1]:
479 479 if c.isspace():
480 480 s = s + c
481 481 else:
482 482 s = s + ' '
483 483 list.append('%s%s^%s\n' % (Colors.caret, s,
484 484 Colors.Normal) )
485 485 value = msg
486 486 s = self._some_str(value)
487 487 if s:
488 488 list.append('%s%s:%s %s\n' % (str(stype), Colors.excName,
489 489 Colors.Normal, s))
490 490 else:
491 491 list.append('%s\n' % str(stype))
492 492
493 493 # This is being commented out for now as the __IPYTHON__ variable
494 494 # referenced here is not resolved and causes massive test failures
495 495 # and errors. B. Granger, 04/2009. XXX
496 496 # See https://bugs.launchpad.net/bugs/362137
497 497 # # vds:>>
498 498 # if have_filedata:
499 499 # __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
500 500 # # vds:<<
501 501
502 502 return list
503 503
504 504 def _some_str(self, value):
505 505 # Lifted from traceback.py
506 506 try:
507 507 return str(value)
508 508 except:
509 509 return '<unprintable %s object>' % type(value).__name__
510 510
511 511 #----------------------------------------------------------------------------
512 512 class VerboseTB(TBTools):
513 513 """A port of Ka-Ping Yee's cgitb.py module that outputs color text instead
514 514 of HTML. Requires inspect and pydoc. Crazy, man.
515 515
516 516 Modified version which optionally strips the topmost entries from the
517 517 traceback, to be used with alternate interpreters (because their own code
518 518 would appear in the traceback)."""
519 519
520 520 def __init__(self,color_scheme = 'Linux',tb_offset=0,long_header=0,
521 521 call_pdb = 0, include_vars=1):
522 522 """Specify traceback offset, headers and color scheme.
523 523
524 524 Define how many frames to drop from the tracebacks. Calling it with
525 525 tb_offset=1 allows use of this handler in interpreters which will have
526 526 their own code at the top of the traceback (VerboseTB will first
527 527 remove that frame before printing the traceback info)."""
528 528 TBTools.__init__(self,color_scheme=color_scheme,call_pdb=call_pdb)
529 529 self.tb_offset = tb_offset
530 530 self.long_header = long_header
531 531 self.include_vars = include_vars
532 532
533 533 def text(self, etype, evalue, etb, context=5):
534 534 """Return a nice text document describing the traceback."""
535 535
536 536 # some locals
537 537 try:
538 538 etype = etype.__name__
539 539 except AttributeError:
540 540 pass
541 541 Colors = self.Colors # just a shorthand + quicker name lookup
542 542 ColorsNormal = Colors.Normal # used a lot
543 543 col_scheme = self.color_scheme_table.active_scheme_name
544 544 indent = ' '*INDENT_SIZE
545 545 em_normal = '%s\n%s%s' % (Colors.valEm, indent,ColorsNormal)
546 546 undefined = '%sundefined%s' % (Colors.em, ColorsNormal)
547 547 exc = '%s%s%s' % (Colors.excName,etype,ColorsNormal)
548 548
549 549 # some internal-use functions
550 550 def text_repr(value):
551 551 """Hopefully pretty robust repr equivalent."""
552 552 # this is pretty horrible but should always return *something*
553 553 try:
554 554 return pydoc.text.repr(value)
555 555 except KeyboardInterrupt:
556 556 raise
557 557 except:
558 558 try:
559 559 return repr(value)
560 560 except KeyboardInterrupt:
561 561 raise
562 562 except:
563 563 try:
564 564 # all still in an except block so we catch
565 565 # getattr raising
566 566 name = getattr(value, '__name__', None)
567 567 if name:
568 568 # ick, recursion
569 569 return text_repr(name)
570 570 klass = getattr(value, '__class__', None)
571 571 if klass:
572 572 return '%s instance' % text_repr(klass)
573 573 except KeyboardInterrupt:
574 574 raise
575 575 except:
576 576 return 'UNRECOVERABLE REPR FAILURE'
577 577 def eqrepr(value, repr=text_repr): return '=%s' % repr(value)
578 578 def nullrepr(value, repr=text_repr): return ''
579 579
580 580 # meat of the code begins
581 581 try:
582 582 etype = etype.__name__
583 583 except AttributeError:
584 584 pass
585 585
586 586 if self.long_header:
587 587 # Header with the exception type, python version, and date
588 588 pyver = 'Python ' + string.split(sys.version)[0] + ': ' + sys.executable
589 589 date = time.ctime(time.time())
590 590
591 591 head = '%s%s%s\n%s%s%s\n%s' % (Colors.topline, '-'*75, ColorsNormal,
592 592 exc, ' '*(75-len(str(etype))-len(pyver)),
593 593 pyver, string.rjust(date, 75) )
594 594 head += "\nA problem occured executing Python code. Here is the sequence of function"\
595 595 "\ncalls leading up to the error, with the most recent (innermost) call last."
596 596 else:
597 597 # Simplified header
598 598 head = '%s%s%s\n%s%s' % (Colors.topline, '-'*75, ColorsNormal,exc,
599 599 string.rjust('Traceback (most recent call last)',
600 600 75 - len(str(etype)) ) )
601 601 frames = []
602 602 # Flush cache before calling inspect. This helps alleviate some of the
603 603 # problems with python 2.3's inspect.py.
604 604 linecache.checkcache()
605 605 # Drop topmost frames if requested
606 606 try:
607 607 # Try the default getinnerframes and Alex's: Alex's fixes some
608 608 # problems, but it generates empty tracebacks for console errors
609 609 # (5 blanks lines) where none should be returned.
610 610 #records = inspect.getinnerframes(etb, context)[self.tb_offset:]
611 611 #print 'python records:', records # dbg
612 612 records = _fixed_getinnerframes(etb, context,self.tb_offset)
613 613 #print 'alex records:', records # dbg
614 614 except:
615 615
616 616 # FIXME: I've been getting many crash reports from python 2.3
617 617 # users, traceable to inspect.py. If I can find a small test-case
618 618 # to reproduce this, I should either write a better workaround or
619 619 # file a bug report against inspect (if that's the real problem).
620 620 # So far, I haven't been able to find an isolated example to
621 621 # reproduce the problem.
622 622 inspect_error()
623 623 traceback.print_exc(file=Term.cerr)
624 624 info('\nUnfortunately, your original traceback can not be constructed.\n')
625 625 return ''
626 626
627 627 # build some color string templates outside these nested loops
628 628 tpl_link = '%s%%s%s' % (Colors.filenameEm,ColorsNormal)
629 629 tpl_call = 'in %s%%s%s%%s%s' % (Colors.vName, Colors.valEm,
630 630 ColorsNormal)
631 631 tpl_call_fail = 'in %s%%s%s(***failed resolving arguments***)%s' % \
632 632 (Colors.vName, Colors.valEm, ColorsNormal)
633 633 tpl_local_var = '%s%%s%s' % (Colors.vName, ColorsNormal)
634 634 tpl_global_var = '%sglobal%s %s%%s%s' % (Colors.em, ColorsNormal,
635 635 Colors.vName, ColorsNormal)
636 636 tpl_name_val = '%%s %s= %%s%s' % (Colors.valEm, ColorsNormal)
637 637 tpl_line = '%s%%s%s %%s' % (Colors.lineno, ColorsNormal)
638 638 tpl_line_em = '%s%%s%s %%s%s' % (Colors.linenoEm,Colors.line,
639 639 ColorsNormal)
640 640
641 641 # now, loop over all records printing context and info
642 642 abspath = os.path.abspath
643 643 for frame, file, lnum, func, lines, index in records:
644 644 #print '*** record:',file,lnum,func,lines,index # dbg
645 645 try:
646 646 file = file and abspath(file) or '?'
647 647 except OSError:
648 648 # if file is '<console>' or something not in the filesystem,
649 649 # the abspath call will throw an OSError. Just ignore it and
650 650 # keep the original file string.
651 651 pass
652 652 link = tpl_link % file
653 653 try:
654 654 args, varargs, varkw, locals = inspect.getargvalues(frame)
655 655 except:
656 656 # This can happen due to a bug in python2.3. We should be
657 657 # able to remove this try/except when 2.4 becomes a
658 658 # requirement. Bug details at http://python.org/sf/1005466
659 659 inspect_error()
660 660 traceback.print_exc(file=Term.cerr)
661 661 info("\nIPython's exception reporting continues...\n")
662 662
663 663 if func == '?':
664 664 call = ''
665 665 else:
666 666 # Decide whether to include variable details or not
667 667 var_repr = self.include_vars and eqrepr or nullrepr
668 668 try:
669 669 call = tpl_call % (func,inspect.formatargvalues(args,
670 670 varargs, varkw,
671 671 locals,formatvalue=var_repr))
672 672 except KeyError:
673 673 # Very odd crash from inspect.formatargvalues(). The
674 674 # scenario under which it appeared was a call to
675 675 # view(array,scale) in NumTut.view.view(), where scale had
676 676 # been defined as a scalar (it should be a tuple). Somehow
677 677 # inspect messes up resolving the argument list of view()
678 678 # and barfs out. At some point I should dig into this one
679 679 # and file a bug report about it.
680 680 inspect_error()
681 681 traceback.print_exc(file=Term.cerr)
682 682 info("\nIPython's exception reporting continues...\n")
683 683 call = tpl_call_fail % func
684 684
685 685 # Initialize a list of names on the current line, which the
686 686 # tokenizer below will populate.
687 687 names = []
688 688
689 689 def tokeneater(token_type, token, start, end, line):
690 690 """Stateful tokeneater which builds dotted names.
691 691
692 692 The list of names it appends to (from the enclosing scope) can
693 693 contain repeated composite names. This is unavoidable, since
694 694 there is no way to disambguate partial dotted structures until
695 695 the full list is known. The caller is responsible for pruning
696 696 the final list of duplicates before using it."""
697 697
698 698 # build composite names
699 699 if token == '.':
700 700 try:
701 701 names[-1] += '.'
702 702 # store state so the next token is added for x.y.z names
703 703 tokeneater.name_cont = True
704 704 return
705 705 except IndexError:
706 706 pass
707 707 if token_type == tokenize.NAME and token not in keyword.kwlist:
708 708 if tokeneater.name_cont:
709 709 # Dotted names
710 710 names[-1] += token
711 711 tokeneater.name_cont = False
712 712 else:
713 713 # Regular new names. We append everything, the caller
714 714 # will be responsible for pruning the list later. It's
715 715 # very tricky to try to prune as we go, b/c composite
716 716 # names can fool us. The pruning at the end is easy
717 717 # to do (or the caller can print a list with repeated
718 718 # names if so desired.
719 719 names.append(token)
720 720 elif token_type == tokenize.NEWLINE:
721 721 raise IndexError
722 722 # we need to store a bit of state in the tokenizer to build
723 723 # dotted names
724 724 tokeneater.name_cont = False
725 725
726 726 def linereader(file=file, lnum=[lnum], getline=linecache.getline):
727 727 line = getline(file, lnum[0])
728 728 lnum[0] += 1
729 729 return line
730 730
731 731 # Build the list of names on this line of code where the exception
732 732 # occurred.
733 733 try:
734 734 # This builds the names list in-place by capturing it from the
735 735 # enclosing scope.
736 736 tokenize.tokenize(linereader, tokeneater)
737 737 except IndexError:
738 738 # signals exit of tokenizer
739 739 pass
740 740 except tokenize.TokenError,msg:
741 741 _m = ("An unexpected error occurred while tokenizing input\n"
742 742 "The following traceback may be corrupted or invalid\n"
743 743 "The error message is: %s\n" % msg)
744 744 error(_m)
745 745
746 746 # prune names list of duplicates, but keep the right order
747 747 unique_names = uniq_stable(names)
748 748
749 749 # Start loop over vars
750 750 lvals = []
751 751 if self.include_vars:
752 752 for name_full in unique_names:
753 753 name_base = name_full.split('.',1)[0]
754 754 if name_base in frame.f_code.co_varnames:
755 755 if locals.has_key(name_base):
756 756 try:
757 757 value = repr(eval(name_full,locals))
758 758 except:
759 759 value = undefined
760 760 else:
761 761 value = undefined
762 762 name = tpl_local_var % name_full
763 763 else:
764 764 if frame.f_globals.has_key(name_base):
765 765 try:
766 766 value = repr(eval(name_full,frame.f_globals))
767 767 except:
768 768 value = undefined
769 769 else:
770 770 value = undefined
771 771 name = tpl_global_var % name_full
772 772 lvals.append(tpl_name_val % (name,value))
773 773 if lvals:
774 774 lvals = '%s%s' % (indent,em_normal.join(lvals))
775 775 else:
776 776 lvals = ''
777 777
778 778 level = '%s %s\n' % (link,call)
779 779
780 780 if index is None:
781 781 frames.append(level)
782 782 else:
783 783 frames.append('%s%s' % (level,''.join(
784 784 _formatTracebackLines(lnum,index,lines,Colors,lvals,
785 785 col_scheme))))
786 786
787 787 # Get (safely) a string form of the exception info
788 788 try:
789 789 etype_str,evalue_str = map(str,(etype,evalue))
790 790 except:
791 791 # User exception is improperly defined.
792 792 etype,evalue = str,sys.exc_info()[:2]
793 793 etype_str,evalue_str = map(str,(etype,evalue))
794 794 # ... and format it
795 795 exception = ['%s%s%s: %s' % (Colors.excName, etype_str,
796 796 ColorsNormal, evalue_str)]
797 797 if type(evalue) is types.InstanceType:
798 798 try:
799 799 names = [w for w in dir(evalue) if isinstance(w, basestring)]
800 800 except:
801 801 # Every now and then, an object with funny inernals blows up
802 802 # when dir() is called on it. We do the best we can to report
803 803 # the problem and continue
804 804 _m = '%sException reporting error (object with broken dir())%s:'
805 805 exception.append(_m % (Colors.excName,ColorsNormal))
806 806 etype_str,evalue_str = map(str,sys.exc_info()[:2])
807 807 exception.append('%s%s%s: %s' % (Colors.excName,etype_str,
808 808 ColorsNormal, evalue_str))
809 809 names = []
810 810 for name in names:
811 811 value = text_repr(getattr(evalue, name))
812 812 exception.append('\n%s%s = %s' % (indent, name, value))
813 813
814 814 # This is being commented out for now as the __IPYTHON__ variable
815 815 # referenced here is not resolved and causes massive test failures
816 816 # and errors. B. Granger, 04/2009. XXX
817 817 # See https://bugs.launchpad.net/bugs/362137
818 818 # # vds: >>
819 819 # if records:
820 820 # filepath, lnum = records[-1][1:3]
821 821 # #print "file:", str(file), "linenb", str(lnum) # dbg
822 822 # filepath = os.path.abspath(filepath)
823 823 # __IPYTHON__.hooks.synchronize_with_editor(filepath, lnum, 0)
824 824 # # vds: <<
825 825
826 826 # return all our info assembled as a single string
827 827 return '%s\n\n%s\n%s' % (head,'\n'.join(frames),''.join(exception[0]) )
828 828
829 829 def debugger(self,force=False):
830 830 """Call up the pdb debugger if desired, always clean up the tb
831 831 reference.
832 832
833 833 Keywords:
834 834
835 835 - force(False): by default, this routine checks the instance call_pdb
836 836 flag and does not actually invoke the debugger if the flag is false.
837 837 The 'force' option forces the debugger to activate even if the flag
838 838 is false.
839 839
840 840 If the call_pdb flag is set, the pdb interactive debugger is
841 841 invoked. In all cases, the self.tb reference to the current traceback
842 842 is deleted to prevent lingering references which hamper memory
843 843 management.
844 844
845 845 Note that each call to pdb() does an 'import readline', so if your app
846 846 requires a special setup for the readline completers, you'll have to
847 847 fix that by hand after invoking the exception handler."""
848 848
849 849 if force or self.call_pdb:
850 850 if self.pdb is None:
851 851 self.pdb = debugger.Pdb(
852 852 self.color_scheme_table.active_scheme_name)
853 853 # the system displayhook may have changed, restore the original
854 854 # for pdb
855 855 dhook = sys.displayhook
856 856 sys.displayhook = sys.__displayhook__
857 857 self.pdb.reset()
858 858 # Find the right frame so we don't pop up inside ipython itself
859 859 if hasattr(self,'tb'):
860 860 etb = self.tb
861 861 else:
862 862 etb = self.tb = sys.last_traceback
863 863 while self.tb.tb_next is not None:
864 864 self.tb = self.tb.tb_next
865 865 try:
866 866 if etb and etb.tb_next:
867 867 etb = etb.tb_next
868 868 self.pdb.botframe = etb.tb_frame
869 869 self.pdb.interaction(self.tb.tb_frame, self.tb)
870 870 finally:
871 871 sys.displayhook = dhook
872 872
873 873 if hasattr(self,'tb'):
874 874 del self.tb
875 875
876 876 def handler(self, info=None):
877 877 (etype, evalue, etb) = info or sys.exc_info()
878 878 self.tb = etb
879 879 Term.cout.flush()
880 880 print >> Term.cerr, self.text(etype, evalue, etb)
881 881 Term.cerr.flush()
882 882
883 883 # Changed so an instance can just be called as VerboseTB_inst() and print
884 884 # out the right info on its own.
885 885 def __call__(self, etype=None, evalue=None, etb=None):
886 886 """This hook can replace sys.excepthook (for Python 2.1 or higher)."""
887 887 if etb is None:
888 888 self.handler()
889 889 else:
890 890 self.handler((etype, evalue, etb))
891 891 try:
892 892 self.debugger()
893 893 except KeyboardInterrupt:
894 894 print "\nKeyboardInterrupt"
895 895
896 896 #----------------------------------------------------------------------------
897 897 class FormattedTB(VerboseTB,ListTB):
898 898 """Subclass ListTB but allow calling with a traceback.
899 899
900 900 It can thus be used as a sys.excepthook for Python > 2.1.
901 901
902 902 Also adds 'Context' and 'Verbose' modes, not available in ListTB.
903 903
904 904 Allows a tb_offset to be specified. This is useful for situations where
905 905 one needs to remove a number of topmost frames from the traceback (such as
906 906 occurs with python programs that themselves execute other python code,
907 907 like Python shells). """
908 908
909 909 def __init__(self, mode = 'Plain', color_scheme='Linux',
910 910 tb_offset = 0,long_header=0,call_pdb=0,include_vars=0):
911 911
912 912 # NEVER change the order of this list. Put new modes at the end:
913 913 self.valid_modes = ['Plain','Context','Verbose']
914 914 self.verbose_modes = self.valid_modes[1:3]
915 915
916 916 VerboseTB.__init__(self,color_scheme,tb_offset,long_header,
917 917 call_pdb=call_pdb,include_vars=include_vars)
918 918 self.set_mode(mode)
919 919
920 920 def _extract_tb(self,tb):
921 921 if tb:
922 922 return traceback.extract_tb(tb)
923 923 else:
924 924 return None
925 925
926 926 def text(self, etype, value, tb,context=5,mode=None):
927 927 """Return formatted traceback.
928 928
929 929 If the optional mode parameter is given, it overrides the current
930 930 mode."""
931 931
932 932 if mode is None:
933 933 mode = self.mode
934 934 if mode in self.verbose_modes:
935 935 # verbose modes need a full traceback
936 936 return VerboseTB.text(self,etype, value, tb,context=5)
937 937 else:
938 938 # We must check the source cache because otherwise we can print
939 939 # out-of-date source code.
940 940 linecache.checkcache()
941 941 # Now we can extract and format the exception
942 942 elist = self._extract_tb(tb)
943 943 if len(elist) > self.tb_offset:
944 944 del elist[:self.tb_offset]
945 945 return ListTB.text(self,etype,value,elist)
946 946
947 947 def set_mode(self,mode=None):
948 948 """Switch to the desired mode.
949 949
950 950 If mode is not specified, cycles through the available modes."""
951 951
952 952 if not mode:
953 953 new_idx = ( self.valid_modes.index(self.mode) + 1 ) % \
954 954 len(self.valid_modes)
955 955 self.mode = self.valid_modes[new_idx]
956 956 elif mode not in self.valid_modes:
957 957 raise ValueError, 'Unrecognized mode in FormattedTB: <'+mode+'>\n'\
958 958 'Valid modes: '+str(self.valid_modes)
959 959 else:
960 960 self.mode = mode
961 961 # include variable details only in 'Verbose' mode
962 962 self.include_vars = (self.mode == self.valid_modes[2])
963 963
964 964 # some convenient shorcuts
965 965 def plain(self):
966 966 self.set_mode(self.valid_modes[0])
967 967
968 968 def context(self):
969 969 self.set_mode(self.valid_modes[1])
970 970
971 971 def verbose(self):
972 972 self.set_mode(self.valid_modes[2])
973 973
974 974 #----------------------------------------------------------------------------
975 975 class AutoFormattedTB(FormattedTB):
976 976 """A traceback printer which can be called on the fly.
977 977
978 978 It will find out about exceptions by itself.
979 979
980 980 A brief example:
981 981
982 982 AutoTB = AutoFormattedTB(mode = 'Verbose',color_scheme='Linux')
983 983 try:
984 984 ...
985 985 except:
986 986 AutoTB() # or AutoTB(out=logfile) where logfile is an open file object
987 987 """
988 988 def __call__(self,etype=None,evalue=None,etb=None,
989 989 out=None,tb_offset=None):
990 990 """Print out a formatted exception traceback.
991 991
992 992 Optional arguments:
993 993 - out: an open file-like object to direct output to.
994 994
995 995 - tb_offset: the number of frames to skip over in the stack, on a
996 996 per-call basis (this overrides temporarily the instance's tb_offset
997 997 given at initialization time. """
998 998
999 999 if out is None:
1000 1000 out = Term.cerr
1001 1001 Term.cout.flush()
1002 1002 if tb_offset is not None:
1003 1003 tb_offset, self.tb_offset = self.tb_offset, tb_offset
1004 1004 print >> out, self.text(etype, evalue, etb)
1005 1005 self.tb_offset = tb_offset
1006 1006 else:
1007 1007 print >> out, self.text(etype, evalue, etb)
1008 1008 out.flush()
1009 1009 try:
1010 1010 self.debugger()
1011 1011 except KeyboardInterrupt:
1012 1012 print "\nKeyboardInterrupt"
1013 1013
1014 1014 def text(self,etype=None,value=None,tb=None,context=5,mode=None):
1015 1015 if etype is None:
1016 1016 etype,value,tb = sys.exc_info()
1017 1017 self.tb = tb
1018 1018 return FormattedTB.text(self,etype,value,tb,context=5,mode=mode)
1019 1019
1020 1020 #---------------------------------------------------------------------------
1021 1021 # A simple class to preserve Nathan's original functionality.
1022 1022 class ColorTB(FormattedTB):
1023 1023 """Shorthand to initialize a FormattedTB in Linux colors mode."""
1024 1024 def __init__(self,color_scheme='Linux',call_pdb=0):
1025 1025 FormattedTB.__init__(self,color_scheme=color_scheme,
1026 1026 call_pdb=call_pdb)
1027 1027
1028 1028 #----------------------------------------------------------------------------
1029 1029 # module testing (minimal)
1030 1030 if __name__ == "__main__":
1031 1031 def spam(c, (d, e)):
1032 1032 x = c + d
1033 1033 y = c * d
1034 1034 foo(x, y)
1035 1035
1036 1036 def foo(a, b, bar=1):
1037 1037 eggs(a, b + bar)
1038 1038
1039 1039 def eggs(f, g, z=globals()):
1040 1040 h = f + g
1041 1041 i = f - g
1042 1042 return h / i
1043 1043
1044 1044 print ''
1045 1045 print '*** Before ***'
1046 1046 try:
1047 1047 print spam(1, (2, 3))
1048 1048 except:
1049 1049 traceback.print_exc()
1050 1050 print ''
1051 1051
1052 1052 handler = ColorTB()
1053 1053 print '*** ColorTB ***'
1054 1054 try:
1055 1055 print spam(1, (2, 3))
1056 1056 except:
1057 1057 apply(handler, sys.exc_info() )
1058 1058 print ''
1059 1059
1060 1060 handler = VerboseTB()
1061 1061 print '*** VerboseTB ***'
1062 1062 try:
1063 1063 print spam(1, (2, 3))
1064 1064 except:
1065 1065 apply(handler, sys.exc_info() )
1066 1066 print ''
1067 1067
@@ -1,526 +1,526 b''
1 1 """Module for interactive demos using IPython.
2 2
3 3 This module implements a few classes for running Python scripts interactively
4 4 in IPython for demonstrations. With very simple markup (a few tags in
5 5 comments), you can control points where the script stops executing and returns
6 6 control to IPython.
7 7
8 8
9 9 Provided classes
10 10 ================
11 11
12 12 The classes are (see their docstrings for further details):
13 13
14 14 - Demo: pure python demos
15 15
16 16 - IPythonDemo: demos with input to be processed by IPython as if it had been
17 17 typed interactively (so magics work, as well as any other special syntax you
18 18 may have added via input prefilters).
19 19
20 20 - LineDemo: single-line version of the Demo class. These demos are executed
21 21 one line at a time, and require no markup.
22 22
23 23 - IPythonLineDemo: IPython version of the LineDemo class (the demo is
24 24 executed a line at a time, but processed via IPython).
25 25
26 26 - ClearMixin: mixin to make Demo classes with less visual clutter. It
27 27 declares an empty marquee and a pre_cmd that clears the screen before each
28 28 block (see Subclassing below).
29 29
30 30 - ClearDemo, ClearIPDemo: mixin-enabled versions of the Demo and IPythonDemo
31 31 classes.
32 32
33 33
34 34 Subclassing
35 35 ===========
36 36
37 37 The classes here all include a few methods meant to make customization by
38 38 subclassing more convenient. Their docstrings below have some more details:
39 39
40 40 - marquee(): generates a marquee to provide visible on-screen markers at each
41 41 block start and end.
42 42
43 43 - pre_cmd(): run right before the execution of each block.
44 44
45 45 - post_cmd(): run right after the execution of each block. If the block
46 46 raises an exception, this is NOT called.
47 47
48 48
49 49 Operation
50 50 =========
51 51
52 52 The file is run in its own empty namespace (though you can pass it a string of
53 53 arguments as if in a command line environment, and it will see those as
54 54 sys.argv). But at each stop, the global IPython namespace is updated with the
55 55 current internal demo namespace, so you can work interactively with the data
56 56 accumulated so far.
57 57
58 58 By default, each block of code is printed (with syntax highlighting) before
59 59 executing it and you have to confirm execution. This is intended to show the
60 60 code to an audience first so you can discuss it, and only proceed with
61 61 execution once you agree. There are a few tags which allow you to modify this
62 62 behavior.
63 63
64 64 The supported tags are:
65 65
66 66 # <demo> stop
67 67
68 68 Defines block boundaries, the points where IPython stops execution of the
69 69 file and returns to the interactive prompt.
70 70
71 71 You can optionally mark the stop tag with extra dashes before and after the
72 72 word 'stop', to help visually distinguish the blocks in a text editor:
73 73
74 74 # <demo> --- stop ---
75 75
76 76
77 77 # <demo> silent
78 78
79 79 Make a block execute silently (and hence automatically). Typically used in
80 80 cases where you have some boilerplate or initialization code which you need
81 81 executed but do not want to be seen in the demo.
82 82
83 83 # <demo> auto
84 84
85 85 Make a block execute automatically, but still being printed. Useful for
86 86 simple code which does not warrant discussion, since it avoids the extra
87 87 manual confirmation.
88 88
89 89 # <demo> auto_all
90 90
91 91 This tag can _only_ be in the first block, and if given it overrides the
92 92 individual auto tags to make the whole demo fully automatic (no block asks
93 93 for confirmation). It can also be given at creation time (or the attribute
94 94 set later) to override what's in the file.
95 95
96 96 While _any_ python file can be run as a Demo instance, if there are no stop
97 97 tags the whole file will run in a single block (no different that calling
98 98 first %pycat and then %run). The minimal markup to make this useful is to
99 99 place a set of stop tags; the other tags are only there to let you fine-tune
100 100 the execution.
101 101
102 102 This is probably best explained with the simple example file below. You can
103 103 copy this into a file named ex_demo.py, and try running it via:
104 104
105 105 from IPython.demo import Demo
106 106 d = Demo('ex_demo.py')
107 107 d() <--- Call the d object (omit the parens if you have autocall set to 2).
108 108
109 109 Each time you call the demo object, it runs the next block. The demo object
110 110 has a few useful methods for navigation, like again(), edit(), jump(), seek()
111 111 and back(). It can be reset for a new run via reset() or reloaded from disk
112 112 (in case you've edited the source) via reload(). See their docstrings below.
113 113
114 114
115 115 Example
116 116 =======
117 117
118 118 The following is a very simple example of a valid demo file.
119 119
120 120 #################### EXAMPLE DEMO <ex_demo.py> ###############################
121 121 '''A simple interactive demo to illustrate the use of IPython's Demo class.'''
122 122
123 123 print 'Hello, welcome to an interactive IPython demo.'
124 124
125 125 # The mark below defines a block boundary, which is a point where IPython will
126 126 # stop execution and return to the interactive prompt. The dashes are actually
127 127 # optional and used only as a visual aid to clearly separate blocks while
128 128 editing the demo code.
129 129 # <demo> stop
130 130
131 131 x = 1
132 132 y = 2
133 133
134 134 # <demo> stop
135 135
136 136 # the mark below makes this block as silent
137 137 # <demo> silent
138 138
139 139 print 'This is a silent block, which gets executed but not printed.'
140 140
141 141 # <demo> stop
142 142 # <demo> auto
143 143 print 'This is an automatic block.'
144 144 print 'It is executed without asking for confirmation, but printed.'
145 145 z = x+y
146 146
147 147 print 'z=',x
148 148
149 149 # <demo> stop
150 150 # This is just another normal block.
151 151 print 'z is now:', z
152 152
153 153 print 'bye!'
154 154 ################### END EXAMPLE DEMO <ex_demo.py> ############################
155 155 """
156 156
157 157 #*****************************************************************************
158 158 # Copyright (C) 2005-2006 Fernando Perez. <Fernando.Perez@colorado.edu>
159 159 #
160 160 # Distributed under the terms of the BSD License. The full license is in
161 161 # the file COPYING, distributed as part of this software.
162 162 #
163 163 #*****************************************************************************
164 164
165 165 import exceptions
166 166 import os
167 167 import re
168 168 import shlex
169 169 import sys
170 170
171 from IPython.PyColorize import Parser
171 from IPython.utils.PyColorize import Parser
172 172 from IPython.utils.genutils import marquee, file_read, file_readlines
173 173
174 174 __all__ = ['Demo','IPythonDemo','LineDemo','IPythonLineDemo','DemoError']
175 175
176 176 class DemoError(exceptions.Exception): pass
177 177
178 178 def re_mark(mark):
179 179 return re.compile(r'^\s*#\s+<demo>\s+%s\s*$' % mark,re.MULTILINE)
180 180
181 181 class Demo(object):
182 182
183 183 re_stop = re_mark('-*\s?stop\s?-*')
184 184 re_silent = re_mark('silent')
185 185 re_auto = re_mark('auto')
186 186 re_auto_all = re_mark('auto_all')
187 187
188 188 def __init__(self,fname,arg_str='',auto_all=None):
189 189 """Make a new demo object. To run the demo, simply call the object.
190 190
191 191 See the module docstring for full details and an example (you can use
192 192 IPython.Demo? in IPython to see it).
193 193
194 194 Inputs:
195 195
196 196 - fname = filename.
197 197
198 198 Optional inputs:
199 199
200 200 - arg_str(''): a string of arguments, internally converted to a list
201 201 just like sys.argv, so the demo script can see a similar
202 202 environment.
203 203
204 204 - auto_all(None): global flag to run all blocks automatically without
205 205 confirmation. This attribute overrides the block-level tags and
206 206 applies to the whole demo. It is an attribute of the object, and
207 207 can be changed at runtime simply by reassigning it to a boolean
208 208 value.
209 209 """
210 210
211 211 self.fname = fname
212 212 self.sys_argv = [fname] + shlex.split(arg_str)
213 213 self.auto_all = auto_all
214 214
215 215 # get a few things from ipython. While it's a bit ugly design-wise,
216 216 # it ensures that things like color scheme and the like are always in
217 217 # sync with the ipython mode being used. This class is only meant to
218 218 # be used inside ipython anyways, so it's OK.
219 219 self.ip_ns = __IPYTHON__.user_ns
220 220 self.ip_colorize = __IPYTHON__.pycolorize
221 221 self.ip_showtb = __IPYTHON__.showtraceback
222 222 self.ip_runlines = __IPYTHON__.runlines
223 223 self.shell = __IPYTHON__
224 224
225 225 # load user data and initialize data structures
226 226 self.reload()
227 227
228 228 def reload(self):
229 229 """Reload source from disk and initialize state."""
230 230 # read data and parse into blocks
231 231 self.src = file_read(self.fname)
232 232 src_b = [b.strip() for b in self.re_stop.split(self.src) if b]
233 233 self._silent = [bool(self.re_silent.findall(b)) for b in src_b]
234 234 self._auto = [bool(self.re_auto.findall(b)) for b in src_b]
235 235
236 236 # if auto_all is not given (def. None), we read it from the file
237 237 if self.auto_all is None:
238 238 self.auto_all = bool(self.re_auto_all.findall(src_b[0]))
239 239 else:
240 240 self.auto_all = bool(self.auto_all)
241 241
242 242 # Clean the sources from all markup so it doesn't get displayed when
243 243 # running the demo
244 244 src_blocks = []
245 245 auto_strip = lambda s: self.re_auto.sub('',s)
246 246 for i,b in enumerate(src_b):
247 247 if self._auto[i]:
248 248 src_blocks.append(auto_strip(b))
249 249 else:
250 250 src_blocks.append(b)
251 251 # remove the auto_all marker
252 252 src_blocks[0] = self.re_auto_all.sub('',src_blocks[0])
253 253
254 254 self.nblocks = len(src_blocks)
255 255 self.src_blocks = src_blocks
256 256
257 257 # also build syntax-highlighted source
258 258 self.src_blocks_colored = map(self.ip_colorize,self.src_blocks)
259 259
260 260 # ensure clean namespace and seek offset
261 261 self.reset()
262 262
263 263 def reset(self):
264 264 """Reset the namespace and seek pointer to restart the demo"""
265 265 self.user_ns = {}
266 266 self.finished = False
267 267 self.block_index = 0
268 268
269 269 def _validate_index(self,index):
270 270 if index<0 or index>=self.nblocks:
271 271 raise ValueError('invalid block index %s' % index)
272 272
273 273 def _get_index(self,index):
274 274 """Get the current block index, validating and checking status.
275 275
276 276 Returns None if the demo is finished"""
277 277
278 278 if index is None:
279 279 if self.finished:
280 280 print 'Demo finished. Use reset() if you want to rerun it.'
281 281 return None
282 282 index = self.block_index
283 283 else:
284 284 self._validate_index(index)
285 285 return index
286 286
287 287 def seek(self,index):
288 288 """Move the current seek pointer to the given block.
289 289
290 290 You can use negative indices to seek from the end, with identical
291 291 semantics to those of Python lists."""
292 292 if index<0:
293 293 index = self.nblocks + index
294 294 self._validate_index(index)
295 295 self.block_index = index
296 296 self.finished = False
297 297
298 298 def back(self,num=1):
299 299 """Move the seek pointer back num blocks (default is 1)."""
300 300 self.seek(self.block_index-num)
301 301
302 302 def jump(self,num=1):
303 303 """Jump a given number of blocks relative to the current one.
304 304
305 305 The offset can be positive or negative, defaults to 1."""
306 306 self.seek(self.block_index+num)
307 307
308 308 def again(self):
309 309 """Move the seek pointer back one block and re-execute."""
310 310 self.back(1)
311 311 self()
312 312
313 313 def edit(self,index=None):
314 314 """Edit a block.
315 315
316 316 If no number is given, use the last block executed.
317 317
318 318 This edits the in-memory copy of the demo, it does NOT modify the
319 319 original source file. If you want to do that, simply open the file in
320 320 an editor and use reload() when you make changes to the file. This
321 321 method is meant to let you change a block during a demonstration for
322 322 explanatory purposes, without damaging your original script."""
323 323
324 324 index = self._get_index(index)
325 325 if index is None:
326 326 return
327 327 # decrease the index by one (unless we're at the very beginning), so
328 328 # that the default demo.edit() call opens up the sblock we've last run
329 329 if index>0:
330 330 index -= 1
331 331
332 332 filename = self.shell.mktempfile(self.src_blocks[index])
333 333 self.shell.hooks.editor(filename,1)
334 334 new_block = file_read(filename)
335 335 # update the source and colored block
336 336 self.src_blocks[index] = new_block
337 337 self.src_blocks_colored[index] = self.ip_colorize(new_block)
338 338 self.block_index = index
339 339 # call to run with the newly edited index
340 340 self()
341 341
342 342 def show(self,index=None):
343 343 """Show a single block on screen"""
344 344
345 345 index = self._get_index(index)
346 346 if index is None:
347 347 return
348 348
349 349 print self.marquee('<%s> block # %s (%s remaining)' %
350 350 (self.fname,index,self.nblocks-index-1))
351 351 sys.stdout.write(self.src_blocks_colored[index])
352 352 sys.stdout.flush()
353 353
354 354 def show_all(self):
355 355 """Show entire demo on screen, block by block"""
356 356
357 357 fname = self.fname
358 358 nblocks = self.nblocks
359 359 silent = self._silent
360 360 marquee = self.marquee
361 361 for index,block in enumerate(self.src_blocks_colored):
362 362 if silent[index]:
363 363 print marquee('<%s> SILENT block # %s (%s remaining)' %
364 364 (fname,index,nblocks-index-1))
365 365 else:
366 366 print marquee('<%s> block # %s (%s remaining)' %
367 367 (fname,index,nblocks-index-1))
368 368 print block,
369 369 sys.stdout.flush()
370 370
371 371 def runlines(self,source):
372 372 """Execute a string with one or more lines of code"""
373 373
374 374 exec source in self.user_ns
375 375
376 376 def __call__(self,index=None):
377 377 """run a block of the demo.
378 378
379 379 If index is given, it should be an integer >=1 and <= nblocks. This
380 380 means that the calling convention is one off from typical Python
381 381 lists. The reason for the inconsistency is that the demo always
382 382 prints 'Block n/N, and N is the total, so it would be very odd to use
383 383 zero-indexing here."""
384 384
385 385 index = self._get_index(index)
386 386 if index is None:
387 387 return
388 388 try:
389 389 marquee = self.marquee
390 390 next_block = self.src_blocks[index]
391 391 self.block_index += 1
392 392 if self._silent[index]:
393 393 print marquee('Executing silent block # %s (%s remaining)' %
394 394 (index,self.nblocks-index-1))
395 395 else:
396 396 self.pre_cmd()
397 397 self.show(index)
398 398 if self.auto_all or self._auto[index]:
399 399 print marquee('output:')
400 400 else:
401 401 print marquee('Press <q> to quit, <Enter> to execute...'),
402 402 ans = raw_input().strip()
403 403 if ans:
404 404 print marquee('Block NOT executed')
405 405 return
406 406 try:
407 407 save_argv = sys.argv
408 408 sys.argv = self.sys_argv
409 409 self.runlines(next_block)
410 410 self.post_cmd()
411 411 finally:
412 412 sys.argv = save_argv
413 413
414 414 except:
415 415 self.ip_showtb(filename=self.fname)
416 416 else:
417 417 self.ip_ns.update(self.user_ns)
418 418
419 419 if self.block_index == self.nblocks:
420 420 mq1 = self.marquee('END OF DEMO')
421 421 if mq1:
422 422 # avoid spurious prints if empty marquees are used
423 423 print
424 424 print mq1
425 425 print self.marquee('Use reset() if you want to rerun it.')
426 426 self.finished = True
427 427
428 428 # These methods are meant to be overridden by subclasses who may wish to
429 429 # customize the behavior of of their demos.
430 430 def marquee(self,txt='',width=78,mark='*'):
431 431 """Return the input string centered in a 'marquee'."""
432 432 return marquee(txt,width,mark)
433 433
434 434 def pre_cmd(self):
435 435 """Method called before executing each block."""
436 436 pass
437 437
438 438 def post_cmd(self):
439 439 """Method called after executing each block."""
440 440 pass
441 441
442 442
443 443 class IPythonDemo(Demo):
444 444 """Class for interactive demos with IPython's input processing applied.
445 445
446 446 This subclasses Demo, but instead of executing each block by the Python
447 447 interpreter (via exec), it actually calls IPython on it, so that any input
448 448 filters which may be in place are applied to the input block.
449 449
450 450 If you have an interactive environment which exposes special input
451 451 processing, you can use this class instead to write demo scripts which
452 452 operate exactly as if you had typed them interactively. The default Demo
453 453 class requires the input to be valid, pure Python code.
454 454 """
455 455
456 456 def runlines(self,source):
457 457 """Execute a string with one or more lines of code"""
458 458
459 459 self.shell.runlines(source)
460 460
461 461 class LineDemo(Demo):
462 462 """Demo where each line is executed as a separate block.
463 463
464 464 The input script should be valid Python code.
465 465
466 466 This class doesn't require any markup at all, and it's meant for simple
467 467 scripts (with no nesting or any kind of indentation) which consist of
468 468 multiple lines of input to be executed, one at a time, as if they had been
469 469 typed in the interactive prompt."""
470 470
471 471 def reload(self):
472 472 """Reload source from disk and initialize state."""
473 473 # read data and parse into blocks
474 474 src_b = [l for l in file_readlines(self.fname) if l.strip()]
475 475 nblocks = len(src_b)
476 476 self.src = os.linesep.join(file_readlines(self.fname))
477 477 self._silent = [False]*nblocks
478 478 self._auto = [True]*nblocks
479 479 self.auto_all = True
480 480 self.nblocks = nblocks
481 481 self.src_blocks = src_b
482 482
483 483 # also build syntax-highlighted source
484 484 self.src_blocks_colored = map(self.ip_colorize,self.src_blocks)
485 485
486 486 # ensure clean namespace and seek offset
487 487 self.reset()
488 488
489 489
490 490 class IPythonLineDemo(IPythonDemo,LineDemo):
491 491 """Variant of the LineDemo class whose input is processed by IPython."""
492 492 pass
493 493
494 494
495 495 class ClearMixin(object):
496 496 """Use this mixin to make Demo classes with less visual clutter.
497 497
498 498 Demos using this mixin will clear the screen before every block and use
499 499 blank marquees.
500 500
501 501 Note that in order for the methods defined here to actually override those
502 502 of the classes it's mixed with, it must go /first/ in the inheritance
503 503 tree. For example:
504 504
505 505 class ClearIPDemo(ClearMixin,IPythonDemo): pass
506 506
507 507 will provide an IPythonDemo class with the mixin's features.
508 508 """
509 509
510 510 def marquee(self,txt='',width=78,mark='*'):
511 511 """Blank marquee that returns '' no matter what the input."""
512 512 return ''
513 513
514 514 def pre_cmd(self):
515 515 """Method called before executing each block.
516 516
517 517 This one simply clears the screen."""
518 518 os.system('clear')
519 519
520 520
521 521 class ClearDemo(ClearMixin,Demo):
522 522 pass
523 523
524 524
525 525 class ClearIPDemo(ClearMixin,IPythonDemo):
526 526 pass
@@ -1,1057 +1,1057 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 ultraTB.py -- Spice up your tracebacks!
4 4
5 5 * ColorTB
6 6 I've always found it a bit hard to visually parse tracebacks in Python. The
7 7 ColorTB class is a solution to that problem. It colors the different parts of a
8 8 traceback in a manner similar to what you would expect from a syntax-highlighting
9 9 text editor.
10 10
11 11 Installation instructions for ColorTB:
12 12 import sys,ultraTB
13 13 sys.excepthook = ultraTB.ColorTB()
14 14
15 15 * VerboseTB
16 16 I've also included a port of Ka-Ping Yee's "cgitb.py" that produces all kinds
17 17 of useful info when a traceback occurs. Ping originally had it spit out HTML
18 18 and intended it for CGI programmers, but why should they have all the fun? I
19 19 altered it to spit out colored text to the terminal. It's a bit overwhelming,
20 20 but kind of neat, and maybe useful for long-running programs that you believe
21 21 are bug-free. If a crash *does* occur in that type of program you want details.
22 22 Give it a shot--you'll love it or you'll hate it.
23 23
24 24 Note:
25 25
26 26 The Verbose mode prints the variables currently visible where the exception
27 27 happened (shortening their strings if too long). This can potentially be
28 28 very slow, if you happen to have a huge data structure whose string
29 29 representation is complex to compute. Your computer may appear to freeze for
30 30 a while with cpu usage at 100%. If this occurs, you can cancel the traceback
31 31 with Ctrl-C (maybe hitting it more than once).
32 32
33 33 If you encounter this kind of situation often, you may want to use the
34 34 Verbose_novars mode instead of the regular Verbose, which avoids formatting
35 35 variables (but otherwise includes the information and context given by
36 36 Verbose).
37 37
38 38
39 39 Installation instructions for ColorTB:
40 40 import sys,ultraTB
41 41 sys.excepthook = ultraTB.VerboseTB()
42 42
43 43 Note: Much of the code in this module was lifted verbatim from the standard
44 44 library module 'traceback.py' and Ka-Ping Yee's 'cgitb.py'.
45 45
46 46 * Color schemes
47 47 The colors are defined in the class TBTools through the use of the
48 48 ColorSchemeTable class. Currently the following exist:
49 49
50 50 - NoColor: allows all of this module to be used in any terminal (the color
51 51 escapes are just dummy blank strings).
52 52
53 53 - Linux: is meant to look good in a terminal like the Linux console (black
54 54 or very dark background).
55 55
56 56 - LightBG: similar to Linux but swaps dark/light colors to be more readable
57 57 in light background terminals.
58 58
59 59 You can implement other color schemes easily, the syntax is fairly
60 60 self-explanatory. Please send back new schemes you develop to the author for
61 61 possible inclusion in future releases.
62 62 """
63 63
64 64 #*****************************************************************************
65 65 # Copyright (C) 2001 Nathaniel Gray <n8gray@caltech.edu>
66 66 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
67 67 #
68 68 # Distributed under the terms of the BSD License. The full license is in
69 69 # the file COPYING, distributed as part of this software.
70 70 #*****************************************************************************
71 71
72 72 # Required modules
73 73 import inspect
74 74 import keyword
75 75 import linecache
76 76 import os
77 77 import pydoc
78 78 import re
79 79 import string
80 80 import sys
81 81 import time
82 82 import tokenize
83 83 import traceback
84 84 import types
85 85
86 86 # For purposes of monkeypatching inspect to fix a bug in it.
87 87 from inspect import getsourcefile, getfile, getmodule,\
88 88 ismodule, isclass, ismethod, isfunction, istraceback, isframe, iscode
89 89
90 90
91 91 # IPython's own modules
92 92 # Modified pdb which doesn't damage IPython's readline handling
93 from IPython import PyColorize
93 from IPython.utils import PyColorize
94 94 from IPython.core import debugger
95 95 from IPython.utils.ipstruct import Struct
96 96 from IPython.core.excolors import exception_colors
97 97 from IPython.utils.genutils import Term,uniq_stable,error,info
98 98
99 99 # Globals
100 100 # amount of space to put line numbers before verbose tracebacks
101 101 INDENT_SIZE = 8
102 102
103 103 # Default color scheme. This is used, for example, by the traceback
104 104 # formatter. When running in an actual IPython instance, the user's rc.colors
105 105 # value is used, but havinga module global makes this functionality available
106 106 # to users of ultraTB who are NOT running inside ipython.
107 107 DEFAULT_SCHEME = 'NoColor'
108 108
109 109 #---------------------------------------------------------------------------
110 110 # Code begins
111 111
112 112 # Utility functions
113 113 def inspect_error():
114 114 """Print a message about internal inspect errors.
115 115
116 116 These are unfortunately quite common."""
117 117
118 118 error('Internal Python error in the inspect module.\n'
119 119 'Below is the traceback from this internal error.\n')
120 120
121 121
122 122 def findsource(object):
123 123 """Return the entire source file and starting line number for an object.
124 124
125 125 The argument may be a module, class, method, function, traceback, frame,
126 126 or code object. The source code is returned as a list of all the lines
127 127 in the file and the line number indexes a line in that list. An IOError
128 128 is raised if the source code cannot be retrieved.
129 129
130 130 FIXED version with which we monkeypatch the stdlib to work around a bug."""
131 131
132 132 file = getsourcefile(object) or getfile(object)
133 133 # If the object is a frame, then trying to get the globals dict from its
134 134 # module won't work. Instead, the frame object itself has the globals
135 135 # dictionary.
136 136 globals_dict = None
137 137 if inspect.isframe(object):
138 138 # XXX: can this ever be false?
139 139 globals_dict = object.f_globals
140 140 else:
141 141 module = getmodule(object, file)
142 142 if module:
143 143 globals_dict = module.__dict__
144 144 lines = linecache.getlines(file, globals_dict)
145 145 if not lines:
146 146 raise IOError('could not get source code')
147 147
148 148 if ismodule(object):
149 149 return lines, 0
150 150
151 151 if isclass(object):
152 152 name = object.__name__
153 153 pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
154 154 # make some effort to find the best matching class definition:
155 155 # use the one with the least indentation, which is the one
156 156 # that's most probably not inside a function definition.
157 157 candidates = []
158 158 for i in range(len(lines)):
159 159 match = pat.match(lines[i])
160 160 if match:
161 161 # if it's at toplevel, it's already the best one
162 162 if lines[i][0] == 'c':
163 163 return lines, i
164 164 # else add whitespace to candidate list
165 165 candidates.append((match.group(1), i))
166 166 if candidates:
167 167 # this will sort by whitespace, and by line number,
168 168 # less whitespace first
169 169 candidates.sort()
170 170 return lines, candidates[0][1]
171 171 else:
172 172 raise IOError('could not find class definition')
173 173
174 174 if ismethod(object):
175 175 object = object.im_func
176 176 if isfunction(object):
177 177 object = object.func_code
178 178 if istraceback(object):
179 179 object = object.tb_frame
180 180 if isframe(object):
181 181 object = object.f_code
182 182 if iscode(object):
183 183 if not hasattr(object, 'co_firstlineno'):
184 184 raise IOError('could not find function definition')
185 185 pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
186 186 pmatch = pat.match
187 187 # fperez - fix: sometimes, co_firstlineno can give a number larger than
188 188 # the length of lines, which causes an error. Safeguard against that.
189 189 lnum = min(object.co_firstlineno,len(lines))-1
190 190 while lnum > 0:
191 191 if pmatch(lines[lnum]): break
192 192 lnum -= 1
193 193
194 194 return lines, lnum
195 195 raise IOError('could not find code object')
196 196
197 197 # Monkeypatch inspect to apply our bugfix. This code only works with py25
198 198 if sys.version_info[:2] >= (2,5):
199 199 inspect.findsource = findsource
200 200
201 201 def fix_frame_records_filenames(records):
202 202 """Try to fix the filenames in each record from inspect.getinnerframes().
203 203
204 204 Particularly, modules loaded from within zip files have useless filenames
205 205 attached to their code object, and inspect.getinnerframes() just uses it.
206 206 """
207 207 fixed_records = []
208 208 for frame, filename, line_no, func_name, lines, index in records:
209 209 # Look inside the frame's globals dictionary for __file__, which should
210 210 # be better.
211 211 better_fn = frame.f_globals.get('__file__', None)
212 212 if isinstance(better_fn, str):
213 213 # Check the type just in case someone did something weird with
214 214 # __file__. It might also be None if the error occurred during
215 215 # import.
216 216 filename = better_fn
217 217 fixed_records.append((frame, filename, line_no, func_name, lines, index))
218 218 return fixed_records
219 219
220 220
221 221 def _fixed_getinnerframes(etb, context=1,tb_offset=0):
222 222 import linecache
223 223 LNUM_POS, LINES_POS, INDEX_POS = 2, 4, 5
224 224
225 225 records = fix_frame_records_filenames(inspect.getinnerframes(etb, context))
226 226
227 227 # If the error is at the console, don't build any context, since it would
228 228 # otherwise produce 5 blank lines printed out (there is no file at the
229 229 # console)
230 230 rec_check = records[tb_offset:]
231 231 try:
232 232 rname = rec_check[0][1]
233 233 if rname == '<ipython console>' or rname.endswith('<string>'):
234 234 return rec_check
235 235 except IndexError:
236 236 pass
237 237
238 238 aux = traceback.extract_tb(etb)
239 239 assert len(records) == len(aux)
240 240 for i, (file, lnum, _, _) in zip(range(len(records)), aux):
241 241 maybeStart = lnum-1 - context//2
242 242 start = max(maybeStart, 0)
243 243 end = start + context
244 244 lines = linecache.getlines(file)[start:end]
245 245 # pad with empty lines if necessary
246 246 if maybeStart < 0:
247 247 lines = (['\n'] * -maybeStart) + lines
248 248 if len(lines) < context:
249 249 lines += ['\n'] * (context - len(lines))
250 250 buf = list(records[i])
251 251 buf[LNUM_POS] = lnum
252 252 buf[INDEX_POS] = lnum - 1 - start
253 253 buf[LINES_POS] = lines
254 254 records[i] = tuple(buf)
255 255 return records[tb_offset:]
256 256
257 257 # Helper function -- largely belongs to VerboseTB, but we need the same
258 258 # functionality to produce a pseudo verbose TB for SyntaxErrors, so that they
259 259 # can be recognized properly by ipython.el's py-traceback-line-re
260 260 # (SyntaxErrors have to be treated specially because they have no traceback)
261 261
262 262 _parser = PyColorize.Parser()
263 263
264 264 def _formatTracebackLines(lnum, index, lines, Colors, lvals=None,scheme=None):
265 265 numbers_width = INDENT_SIZE - 1
266 266 res = []
267 267 i = lnum - index
268 268
269 269 # This lets us get fully syntax-highlighted tracebacks.
270 270 if scheme is None:
271 271 try:
272 272 scheme = __IPYTHON__.rc.colors
273 273 except:
274 274 scheme = DEFAULT_SCHEME
275 275 _line_format = _parser.format2
276 276
277 277 for line in lines:
278 278 new_line, err = _line_format(line,'str',scheme)
279 279 if not err: line = new_line
280 280
281 281 if i == lnum:
282 282 # This is the line with the error
283 283 pad = numbers_width - len(str(i))
284 284 if pad >= 3:
285 285 marker = '-'*(pad-3) + '-> '
286 286 elif pad == 2:
287 287 marker = '> '
288 288 elif pad == 1:
289 289 marker = '>'
290 290 else:
291 291 marker = ''
292 292 num = marker + str(i)
293 293 line = '%s%s%s %s%s' %(Colors.linenoEm, num,
294 294 Colors.line, line, Colors.Normal)
295 295 else:
296 296 num = '%*s' % (numbers_width,i)
297 297 line = '%s%s%s %s' %(Colors.lineno, num,
298 298 Colors.Normal, line)
299 299
300 300 res.append(line)
301 301 if lvals and i == lnum:
302 302 res.append(lvals + '\n')
303 303 i = i + 1
304 304 return res
305 305
306 306
307 307 #---------------------------------------------------------------------------
308 308 # Module classes
309 309 class TBTools:
310 310 """Basic tools used by all traceback printer classes."""
311 311
312 312 def __init__(self,color_scheme = 'NoColor',call_pdb=False):
313 313 # Whether to call the interactive pdb debugger after printing
314 314 # tracebacks or not
315 315 self.call_pdb = call_pdb
316 316
317 317 # Create color table
318 318 self.color_scheme_table = exception_colors()
319 319
320 320 self.set_colors(color_scheme)
321 321 self.old_scheme = color_scheme # save initial value for toggles
322 322
323 323 if call_pdb:
324 324 self.pdb = debugger.Pdb(self.color_scheme_table.active_scheme_name)
325 325 else:
326 326 self.pdb = None
327 327
328 328 def set_colors(self,*args,**kw):
329 329 """Shorthand access to the color table scheme selector method."""
330 330
331 331 # Set own color table
332 332 self.color_scheme_table.set_active_scheme(*args,**kw)
333 333 # for convenience, set Colors to the active scheme
334 334 self.Colors = self.color_scheme_table.active_colors
335 335 # Also set colors of debugger
336 336 if hasattr(self,'pdb') and self.pdb is not None:
337 337 self.pdb.set_colors(*args,**kw)
338 338
339 339 def color_toggle(self):
340 340 """Toggle between the currently active color scheme and NoColor."""
341 341
342 342 if self.color_scheme_table.active_scheme_name == 'NoColor':
343 343 self.color_scheme_table.set_active_scheme(self.old_scheme)
344 344 self.Colors = self.color_scheme_table.active_colors
345 345 else:
346 346 self.old_scheme = self.color_scheme_table.active_scheme_name
347 347 self.color_scheme_table.set_active_scheme('NoColor')
348 348 self.Colors = self.color_scheme_table.active_colors
349 349
350 350 #---------------------------------------------------------------------------
351 351 class ListTB(TBTools):
352 352 """Print traceback information from a traceback list, with optional color.
353 353
354 354 Calling: requires 3 arguments:
355 355 (etype, evalue, elist)
356 356 as would be obtained by:
357 357 etype, evalue, tb = sys.exc_info()
358 358 if tb:
359 359 elist = traceback.extract_tb(tb)
360 360 else:
361 361 elist = None
362 362
363 363 It can thus be used by programs which need to process the traceback before
364 364 printing (such as console replacements based on the code module from the
365 365 standard library).
366 366
367 367 Because they are meant to be called without a full traceback (only a
368 368 list), instances of this class can't call the interactive pdb debugger."""
369 369
370 370 def __init__(self,color_scheme = 'NoColor'):
371 371 TBTools.__init__(self,color_scheme = color_scheme,call_pdb=0)
372 372
373 373 def __call__(self, etype, value, elist):
374 374 Term.cout.flush()
375 375 print >> Term.cerr, self.text(etype,value,elist)
376 376 Term.cerr.flush()
377 377
378 378 def text(self,etype, value, elist,context=5):
379 379 """Return a color formatted string with the traceback info."""
380 380
381 381 Colors = self.Colors
382 382 out_string = ['%s%s%s\n' % (Colors.topline,'-'*60,Colors.Normal)]
383 383 if elist:
384 384 out_string.append('Traceback %s(most recent call last)%s:' % \
385 385 (Colors.normalEm, Colors.Normal) + '\n')
386 386 out_string.extend(self._format_list(elist))
387 387 lines = self._format_exception_only(etype, value)
388 388 for line in lines[:-1]:
389 389 out_string.append(" "+line)
390 390 out_string.append(lines[-1])
391 391 return ''.join(out_string)
392 392
393 393 def _format_list(self, extracted_list):
394 394 """Format a list of traceback entry tuples for printing.
395 395
396 396 Given a list of tuples as returned by extract_tb() or
397 397 extract_stack(), return a list of strings ready for printing.
398 398 Each string in the resulting list corresponds to the item with the
399 399 same index in the argument list. Each string ends in a newline;
400 400 the strings may contain internal newlines as well, for those items
401 401 whose source text line is not None.
402 402
403 403 Lifted almost verbatim from traceback.py
404 404 """
405 405
406 406 Colors = self.Colors
407 407 list = []
408 408 for filename, lineno, name, line in extracted_list[:-1]:
409 409 item = ' File %s"%s"%s, line %s%d%s, in %s%s%s\n' % \
410 410 (Colors.filename, filename, Colors.Normal,
411 411 Colors.lineno, lineno, Colors.Normal,
412 412 Colors.name, name, Colors.Normal)
413 413 if line:
414 414 item = item + ' %s\n' % line.strip()
415 415 list.append(item)
416 416 # Emphasize the last entry
417 417 filename, lineno, name, line = extracted_list[-1]
418 418 item = '%s File %s"%s"%s, line %s%d%s, in %s%s%s%s\n' % \
419 419 (Colors.normalEm,
420 420 Colors.filenameEm, filename, Colors.normalEm,
421 421 Colors.linenoEm, lineno, Colors.normalEm,
422 422 Colors.nameEm, name, Colors.normalEm,
423 423 Colors.Normal)
424 424 if line:
425 425 item = item + '%s %s%s\n' % (Colors.line, line.strip(),
426 426 Colors.Normal)
427 427 list.append(item)
428 428 return list
429 429
430 430 def _format_exception_only(self, etype, value):
431 431 """Format the exception part of a traceback.
432 432
433 433 The arguments are the exception type and value such as given by
434 434 sys.exc_info()[:2]. The return value is a list of strings, each ending
435 435 in a newline. Normally, the list contains a single string; however,
436 436 for SyntaxError exceptions, it contains several lines that (when
437 437 printed) display detailed information about where the syntax error
438 438 occurred. The message indicating which exception occurred is the
439 439 always last string in the list.
440 440
441 441 Also lifted nearly verbatim from traceback.py
442 442 """
443 443
444 444 have_filedata = False
445 445 Colors = self.Colors
446 446 list = []
447 447 try:
448 448 stype = Colors.excName + etype.__name__ + Colors.Normal
449 449 except AttributeError:
450 450 stype = etype # String exceptions don't get special coloring
451 451 if value is None:
452 452 list.append( str(stype) + '\n')
453 453 else:
454 454 if etype is SyntaxError:
455 455 try:
456 456 msg, (filename, lineno, offset, line) = value
457 457 except:
458 458 have_filedata = False
459 459 else:
460 460 have_filedata = True
461 461 #print 'filename is',filename # dbg
462 462 if not filename: filename = "<string>"
463 463 list.append('%s File %s"%s"%s, line %s%d%s\n' % \
464 464 (Colors.normalEm,
465 465 Colors.filenameEm, filename, Colors.normalEm,
466 466 Colors.linenoEm, lineno, Colors.Normal ))
467 467 if line is not None:
468 468 i = 0
469 469 while i < len(line) and line[i].isspace():
470 470 i = i+1
471 471 list.append('%s %s%s\n' % (Colors.line,
472 472 line.strip(),
473 473 Colors.Normal))
474 474 if offset is not None:
475 475 s = ' '
476 476 for c in line[i:offset-1]:
477 477 if c.isspace():
478 478 s = s + c
479 479 else:
480 480 s = s + ' '
481 481 list.append('%s%s^%s\n' % (Colors.caret, s,
482 482 Colors.Normal) )
483 483 value = msg
484 484 s = self._some_str(value)
485 485 if s:
486 486 list.append('%s%s:%s %s\n' % (str(stype), Colors.excName,
487 487 Colors.Normal, s))
488 488 else:
489 489 list.append('%s\n' % str(stype))
490 490
491 491 # vds:>>
492 492 if have_filedata:
493 493 __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
494 494 # vds:<<
495 495
496 496 return list
497 497
498 498 def _some_str(self, value):
499 499 # Lifted from traceback.py
500 500 try:
501 501 return str(value)
502 502 except:
503 503 return '<unprintable %s object>' % type(value).__name__
504 504
505 505 #----------------------------------------------------------------------------
506 506 class VerboseTB(TBTools):
507 507 """A port of Ka-Ping Yee's cgitb.py module that outputs color text instead
508 508 of HTML. Requires inspect and pydoc. Crazy, man.
509 509
510 510 Modified version which optionally strips the topmost entries from the
511 511 traceback, to be used with alternate interpreters (because their own code
512 512 would appear in the traceback)."""
513 513
514 514 def __init__(self,color_scheme = 'Linux',tb_offset=0,long_header=0,
515 515 call_pdb = 0, include_vars=1):
516 516 """Specify traceback offset, headers and color scheme.
517 517
518 518 Define how many frames to drop from the tracebacks. Calling it with
519 519 tb_offset=1 allows use of this handler in interpreters which will have
520 520 their own code at the top of the traceback (VerboseTB will first
521 521 remove that frame before printing the traceback info)."""
522 522 TBTools.__init__(self,color_scheme=color_scheme,call_pdb=call_pdb)
523 523 self.tb_offset = tb_offset
524 524 self.long_header = long_header
525 525 self.include_vars = include_vars
526 526
527 527 def text(self, etype, evalue, etb, context=5):
528 528 """Return a nice text document describing the traceback."""
529 529
530 530 # some locals
531 531 try:
532 532 etype = etype.__name__
533 533 except AttributeError:
534 534 pass
535 535 Colors = self.Colors # just a shorthand + quicker name lookup
536 536 ColorsNormal = Colors.Normal # used a lot
537 537 col_scheme = self.color_scheme_table.active_scheme_name
538 538 indent = ' '*INDENT_SIZE
539 539 em_normal = '%s\n%s%s' % (Colors.valEm, indent,ColorsNormal)
540 540 undefined = '%sundefined%s' % (Colors.em, ColorsNormal)
541 541 exc = '%s%s%s' % (Colors.excName,etype,ColorsNormal)
542 542
543 543 # some internal-use functions
544 544 def text_repr(value):
545 545 """Hopefully pretty robust repr equivalent."""
546 546 # this is pretty horrible but should always return *something*
547 547 try:
548 548 return pydoc.text.repr(value)
549 549 except KeyboardInterrupt:
550 550 raise
551 551 except:
552 552 try:
553 553 return repr(value)
554 554 except KeyboardInterrupt:
555 555 raise
556 556 except:
557 557 try:
558 558 # all still in an except block so we catch
559 559 # getattr raising
560 560 name = getattr(value, '__name__', None)
561 561 if name:
562 562 # ick, recursion
563 563 return text_repr(name)
564 564 klass = getattr(value, '__class__', None)
565 565 if klass:
566 566 return '%s instance' % text_repr(klass)
567 567 except KeyboardInterrupt:
568 568 raise
569 569 except:
570 570 return 'UNRECOVERABLE REPR FAILURE'
571 571 def eqrepr(value, repr=text_repr): return '=%s' % repr(value)
572 572 def nullrepr(value, repr=text_repr): return ''
573 573
574 574 # meat of the code begins
575 575 try:
576 576 etype = etype.__name__
577 577 except AttributeError:
578 578 pass
579 579
580 580 if self.long_header:
581 581 # Header with the exception type, python version, and date
582 582 pyver = 'Python ' + string.split(sys.version)[0] + ': ' + sys.executable
583 583 date = time.ctime(time.time())
584 584
585 585 head = '%s%s%s\n%s%s%s\n%s' % (Colors.topline, '-'*75, ColorsNormal,
586 586 exc, ' '*(75-len(str(etype))-len(pyver)),
587 587 pyver, string.rjust(date, 75) )
588 588 head += "\nA problem occured executing Python code. Here is the sequence of function"\
589 589 "\ncalls leading up to the error, with the most recent (innermost) call last."
590 590 else:
591 591 # Simplified header
592 592 head = '%s%s%s\n%s%s' % (Colors.topline, '-'*75, ColorsNormal,exc,
593 593 string.rjust('Traceback (most recent call last)',
594 594 75 - len(str(etype)) ) )
595 595 frames = []
596 596 # Flush cache before calling inspect. This helps alleviate some of the
597 597 # problems with python 2.3's inspect.py.
598 598 linecache.checkcache()
599 599 # Drop topmost frames if requested
600 600 try:
601 601 # Try the default getinnerframes and Alex's: Alex's fixes some
602 602 # problems, but it generates empty tracebacks for console errors
603 603 # (5 blanks lines) where none should be returned.
604 604 #records = inspect.getinnerframes(etb, context)[self.tb_offset:]
605 605 #print 'python records:', records # dbg
606 606 records = _fixed_getinnerframes(etb, context,self.tb_offset)
607 607 #print 'alex records:', records # dbg
608 608 except:
609 609
610 610 # FIXME: I've been getting many crash reports from python 2.3
611 611 # users, traceable to inspect.py. If I can find a small test-case
612 612 # to reproduce this, I should either write a better workaround or
613 613 # file a bug report against inspect (if that's the real problem).
614 614 # So far, I haven't been able to find an isolated example to
615 615 # reproduce the problem.
616 616 inspect_error()
617 617 traceback.print_exc(file=Term.cerr)
618 618 info('\nUnfortunately, your original traceback can not be constructed.\n')
619 619 return ''
620 620
621 621 # build some color string templates outside these nested loops
622 622 tpl_link = '%s%%s%s' % (Colors.filenameEm,ColorsNormal)
623 623 tpl_call = 'in %s%%s%s%%s%s' % (Colors.vName, Colors.valEm,
624 624 ColorsNormal)
625 625 tpl_call_fail = 'in %s%%s%s(***failed resolving arguments***)%s' % \
626 626 (Colors.vName, Colors.valEm, ColorsNormal)
627 627 tpl_local_var = '%s%%s%s' % (Colors.vName, ColorsNormal)
628 628 tpl_global_var = '%sglobal%s %s%%s%s' % (Colors.em, ColorsNormal,
629 629 Colors.vName, ColorsNormal)
630 630 tpl_name_val = '%%s %s= %%s%s' % (Colors.valEm, ColorsNormal)
631 631 tpl_line = '%s%%s%s %%s' % (Colors.lineno, ColorsNormal)
632 632 tpl_line_em = '%s%%s%s %%s%s' % (Colors.linenoEm,Colors.line,
633 633 ColorsNormal)
634 634
635 635 # now, loop over all records printing context and info
636 636 abspath = os.path.abspath
637 637 for frame, file, lnum, func, lines, index in records:
638 638 #print '*** record:',file,lnum,func,lines,index # dbg
639 639 try:
640 640 file = file and abspath(file) or '?'
641 641 except OSError:
642 642 # if file is '<console>' or something not in the filesystem,
643 643 # the abspath call will throw an OSError. Just ignore it and
644 644 # keep the original file string.
645 645 pass
646 646 link = tpl_link % file
647 647 try:
648 648 args, varargs, varkw, locals = inspect.getargvalues(frame)
649 649 except:
650 650 # This can happen due to a bug in python2.3. We should be
651 651 # able to remove this try/except when 2.4 becomes a
652 652 # requirement. Bug details at http://python.org/sf/1005466
653 653 inspect_error()
654 654 traceback.print_exc(file=Term.cerr)
655 655 info("\nIPython's exception reporting continues...\n")
656 656
657 657 if func == '?':
658 658 call = ''
659 659 else:
660 660 # Decide whether to include variable details or not
661 661 var_repr = self.include_vars and eqrepr or nullrepr
662 662 try:
663 663 call = tpl_call % (func,inspect.formatargvalues(args,
664 664 varargs, varkw,
665 665 locals,formatvalue=var_repr))
666 666 except KeyError:
667 667 # Very odd crash from inspect.formatargvalues(). The
668 668 # scenario under which it appeared was a call to
669 669 # view(array,scale) in NumTut.view.view(), where scale had
670 670 # been defined as a scalar (it should be a tuple). Somehow
671 671 # inspect messes up resolving the argument list of view()
672 672 # and barfs out. At some point I should dig into this one
673 673 # and file a bug report about it.
674 674 inspect_error()
675 675 traceback.print_exc(file=Term.cerr)
676 676 info("\nIPython's exception reporting continues...\n")
677 677 call = tpl_call_fail % func
678 678
679 679 # Initialize a list of names on the current line, which the
680 680 # tokenizer below will populate.
681 681 names = []
682 682
683 683 def tokeneater(token_type, token, start, end, line):
684 684 """Stateful tokeneater which builds dotted names.
685 685
686 686 The list of names it appends to (from the enclosing scope) can
687 687 contain repeated composite names. This is unavoidable, since
688 688 there is no way to disambguate partial dotted structures until
689 689 the full list is known. The caller is responsible for pruning
690 690 the final list of duplicates before using it."""
691 691
692 692 # build composite names
693 693 if token == '.':
694 694 try:
695 695 names[-1] += '.'
696 696 # store state so the next token is added for x.y.z names
697 697 tokeneater.name_cont = True
698 698 return
699 699 except IndexError:
700 700 pass
701 701 if token_type == tokenize.NAME and token not in keyword.kwlist:
702 702 if tokeneater.name_cont:
703 703 # Dotted names
704 704 names[-1] += token
705 705 tokeneater.name_cont = False
706 706 else:
707 707 # Regular new names. We append everything, the caller
708 708 # will be responsible for pruning the list later. It's
709 709 # very tricky to try to prune as we go, b/c composite
710 710 # names can fool us. The pruning at the end is easy
711 711 # to do (or the caller can print a list with repeated
712 712 # names if so desired.
713 713 names.append(token)
714 714 elif token_type == tokenize.NEWLINE:
715 715 raise IndexError
716 716 # we need to store a bit of state in the tokenizer to build
717 717 # dotted names
718 718 tokeneater.name_cont = False
719 719
720 720 def linereader(file=file, lnum=[lnum], getline=linecache.getline):
721 721 line = getline(file, lnum[0])
722 722 lnum[0] += 1
723 723 return line
724 724
725 725 # Build the list of names on this line of code where the exception
726 726 # occurred.
727 727 try:
728 728 # This builds the names list in-place by capturing it from the
729 729 # enclosing scope.
730 730 tokenize.tokenize(linereader, tokeneater)
731 731 except IndexError:
732 732 # signals exit of tokenizer
733 733 pass
734 734 except tokenize.TokenError,msg:
735 735 _m = ("An unexpected error occurred while tokenizing input\n"
736 736 "The following traceback may be corrupted or invalid\n"
737 737 "The error message is: %s\n" % msg)
738 738 error(_m)
739 739
740 740 # prune names list of duplicates, but keep the right order
741 741 unique_names = uniq_stable(names)
742 742
743 743 # Start loop over vars
744 744 lvals = []
745 745 if self.include_vars:
746 746 for name_full in unique_names:
747 747 name_base = name_full.split('.',1)[0]
748 748 if name_base in frame.f_code.co_varnames:
749 749 if locals.has_key(name_base):
750 750 try:
751 751 value = repr(eval(name_full,locals))
752 752 except:
753 753 value = undefined
754 754 else:
755 755 value = undefined
756 756 name = tpl_local_var % name_full
757 757 else:
758 758 if frame.f_globals.has_key(name_base):
759 759 try:
760 760 value = repr(eval(name_full,frame.f_globals))
761 761 except:
762 762 value = undefined
763 763 else:
764 764 value = undefined
765 765 name = tpl_global_var % name_full
766 766 lvals.append(tpl_name_val % (name,value))
767 767 if lvals:
768 768 lvals = '%s%s' % (indent,em_normal.join(lvals))
769 769 else:
770 770 lvals = ''
771 771
772 772 level = '%s %s\n' % (link,call)
773 773
774 774 if index is None:
775 775 frames.append(level)
776 776 else:
777 777 frames.append('%s%s' % (level,''.join(
778 778 _formatTracebackLines(lnum,index,lines,Colors,lvals,
779 779 col_scheme))))
780 780
781 781 # Get (safely) a string form of the exception info
782 782 try:
783 783 etype_str,evalue_str = map(str,(etype,evalue))
784 784 except:
785 785 # User exception is improperly defined.
786 786 etype,evalue = str,sys.exc_info()[:2]
787 787 etype_str,evalue_str = map(str,(etype,evalue))
788 788 # ... and format it
789 789 exception = ['%s%s%s: %s' % (Colors.excName, etype_str,
790 790 ColorsNormal, evalue_str)]
791 791 if type(evalue) is types.InstanceType:
792 792 try:
793 793 names = [w for w in dir(evalue) if isinstance(w, basestring)]
794 794 except:
795 795 # Every now and then, an object with funny inernals blows up
796 796 # when dir() is called on it. We do the best we can to report
797 797 # the problem and continue
798 798 _m = '%sException reporting error (object with broken dir())%s:'
799 799 exception.append(_m % (Colors.excName,ColorsNormal))
800 800 etype_str,evalue_str = map(str,sys.exc_info()[:2])
801 801 exception.append('%s%s%s: %s' % (Colors.excName,etype_str,
802 802 ColorsNormal, evalue_str))
803 803 names = []
804 804 for name in names:
805 805 value = text_repr(getattr(evalue, name))
806 806 exception.append('\n%s%s = %s' % (indent, name, value))
807 807
808 808 # vds: >>
809 809 if records:
810 810 filepath, lnum = records[-1][1:3]
811 811 #print "file:", str(file), "linenb", str(lnum) # dbg
812 812 filepath = os.path.abspath(filepath)
813 813 __IPYTHON__.hooks.synchronize_with_editor(filepath, lnum, 0)
814 814 # vds: <<
815 815
816 816 # return all our info assembled as a single string
817 817 return '%s\n\n%s\n%s' % (head,'\n'.join(frames),''.join(exception[0]) )
818 818
819 819 def debugger(self,force=False):
820 820 """Call up the pdb debugger if desired, always clean up the tb
821 821 reference.
822 822
823 823 Keywords:
824 824
825 825 - force(False): by default, this routine checks the instance call_pdb
826 826 flag and does not actually invoke the debugger if the flag is false.
827 827 The 'force' option forces the debugger to activate even if the flag
828 828 is false.
829 829
830 830 If the call_pdb flag is set, the pdb interactive debugger is
831 831 invoked. In all cases, the self.tb reference to the current traceback
832 832 is deleted to prevent lingering references which hamper memory
833 833 management.
834 834
835 835 Note that each call to pdb() does an 'import readline', so if your app
836 836 requires a special setup for the readline completers, you'll have to
837 837 fix that by hand after invoking the exception handler."""
838 838
839 839 if force or self.call_pdb:
840 840 if self.pdb is None:
841 841 self.pdb = debugger.Pdb(
842 842 self.color_scheme_table.active_scheme_name)
843 843 # the system displayhook may have changed, restore the original
844 844 # for pdb
845 845 dhook = sys.displayhook
846 846 sys.displayhook = sys.__displayhook__
847 847 self.pdb.reset()
848 848 # Find the right frame so we don't pop up inside ipython itself
849 849 if hasattr(self,'tb'):
850 850 etb = self.tb
851 851 else:
852 852 etb = self.tb = sys.last_traceback
853 853 while self.tb.tb_next is not None:
854 854 self.tb = self.tb.tb_next
855 855 try:
856 856 if etb and etb.tb_next:
857 857 etb = etb.tb_next
858 858 self.pdb.botframe = etb.tb_frame
859 859 self.pdb.interaction(self.tb.tb_frame, self.tb)
860 860 finally:
861 861 sys.displayhook = dhook
862 862
863 863 if hasattr(self,'tb'):
864 864 del self.tb
865 865
866 866 def handler(self, info=None):
867 867 (etype, evalue, etb) = info or sys.exc_info()
868 868 self.tb = etb
869 869 Term.cout.flush()
870 870 print >> Term.cerr, self.text(etype, evalue, etb)
871 871 Term.cerr.flush()
872 872
873 873 # Changed so an instance can just be called as VerboseTB_inst() and print
874 874 # out the right info on its own.
875 875 def __call__(self, etype=None, evalue=None, etb=None):
876 876 """This hook can replace sys.excepthook (for Python 2.1 or higher)."""
877 877 if etb is None:
878 878 self.handler()
879 879 else:
880 880 self.handler((etype, evalue, etb))
881 881 try:
882 882 self.debugger()
883 883 except KeyboardInterrupt:
884 884 print "\nKeyboardInterrupt"
885 885
886 886 #----------------------------------------------------------------------------
887 887 class FormattedTB(VerboseTB,ListTB):
888 888 """Subclass ListTB but allow calling with a traceback.
889 889
890 890 It can thus be used as a sys.excepthook for Python > 2.1.
891 891
892 892 Also adds 'Context' and 'Verbose' modes, not available in ListTB.
893 893
894 894 Allows a tb_offset to be specified. This is useful for situations where
895 895 one needs to remove a number of topmost frames from the traceback (such as
896 896 occurs with python programs that themselves execute other python code,
897 897 like Python shells). """
898 898
899 899 def __init__(self, mode = 'Plain', color_scheme='Linux',
900 900 tb_offset = 0,long_header=0,call_pdb=0,include_vars=0):
901 901
902 902 # NEVER change the order of this list. Put new modes at the end:
903 903 self.valid_modes = ['Plain','Context','Verbose']
904 904 self.verbose_modes = self.valid_modes[1:3]
905 905
906 906 VerboseTB.__init__(self,color_scheme,tb_offset,long_header,
907 907 call_pdb=call_pdb,include_vars=include_vars)
908 908 self.set_mode(mode)
909 909
910 910 def _extract_tb(self,tb):
911 911 if tb:
912 912 return traceback.extract_tb(tb)
913 913 else:
914 914 return None
915 915
916 916 def text(self, etype, value, tb,context=5,mode=None):
917 917 """Return formatted traceback.
918 918
919 919 If the optional mode parameter is given, it overrides the current
920 920 mode."""
921 921
922 922 if mode is None:
923 923 mode = self.mode
924 924 if mode in self.verbose_modes:
925 925 # verbose modes need a full traceback
926 926 return VerboseTB.text(self,etype, value, tb,context=5)
927 927 else:
928 928 # We must check the source cache because otherwise we can print
929 929 # out-of-date source code.
930 930 linecache.checkcache()
931 931 # Now we can extract and format the exception
932 932 elist = self._extract_tb(tb)
933 933 if len(elist) > self.tb_offset:
934 934 del elist[:self.tb_offset]
935 935 return ListTB.text(self,etype,value,elist)
936 936
937 937 def set_mode(self,mode=None):
938 938 """Switch to the desired mode.
939 939
940 940 If mode is not specified, cycles through the available modes."""
941 941
942 942 if not mode:
943 943 new_idx = ( self.valid_modes.index(self.mode) + 1 ) % \
944 944 len(self.valid_modes)
945 945 self.mode = self.valid_modes[new_idx]
946 946 elif mode not in self.valid_modes:
947 947 raise ValueError, 'Unrecognized mode in FormattedTB: <'+mode+'>\n'\
948 948 'Valid modes: '+str(self.valid_modes)
949 949 else:
950 950 self.mode = mode
951 951 # include variable details only in 'Verbose' mode
952 952 self.include_vars = (self.mode == self.valid_modes[2])
953 953
954 954 # some convenient shorcuts
955 955 def plain(self):
956 956 self.set_mode(self.valid_modes[0])
957 957
958 958 def context(self):
959 959 self.set_mode(self.valid_modes[1])
960 960
961 961 def verbose(self):
962 962 self.set_mode(self.valid_modes[2])
963 963
964 964 #----------------------------------------------------------------------------
965 965 class AutoFormattedTB(FormattedTB):
966 966 """A traceback printer which can be called on the fly.
967 967
968 968 It will find out about exceptions by itself.
969 969
970 970 A brief example:
971 971
972 972 AutoTB = AutoFormattedTB(mode = 'Verbose',color_scheme='Linux')
973 973 try:
974 974 ...
975 975 except:
976 976 AutoTB() # or AutoTB(out=logfile) where logfile is an open file object
977 977 """
978 978 def __call__(self,etype=None,evalue=None,etb=None,
979 979 out=None,tb_offset=None):
980 980 """Print out a formatted exception traceback.
981 981
982 982 Optional arguments:
983 983 - out: an open file-like object to direct output to.
984 984
985 985 - tb_offset: the number of frames to skip over in the stack, on a
986 986 per-call basis (this overrides temporarily the instance's tb_offset
987 987 given at initialization time. """
988 988
989 989 if out is None:
990 990 out = Term.cerr
991 991 Term.cout.flush()
992 992 if tb_offset is not None:
993 993 tb_offset, self.tb_offset = self.tb_offset, tb_offset
994 994 print >> out, self.text(etype, evalue, etb)
995 995 self.tb_offset = tb_offset
996 996 else:
997 997 print >> out, self.text(etype, evalue, etb)
998 998 out.flush()
999 999 try:
1000 1000 self.debugger()
1001 1001 except KeyboardInterrupt:
1002 1002 print "\nKeyboardInterrupt"
1003 1003
1004 1004 def text(self,etype=None,value=None,tb=None,context=5,mode=None):
1005 1005 if etype is None:
1006 1006 etype,value,tb = sys.exc_info()
1007 1007 self.tb = tb
1008 1008 return FormattedTB.text(self,etype,value,tb,context=5,mode=mode)
1009 1009
1010 1010 #---------------------------------------------------------------------------
1011 1011 # A simple class to preserve Nathan's original functionality.
1012 1012 class ColorTB(FormattedTB):
1013 1013 """Shorthand to initialize a FormattedTB in Linux colors mode."""
1014 1014 def __init__(self,color_scheme='Linux',call_pdb=0):
1015 1015 FormattedTB.__init__(self,color_scheme=color_scheme,
1016 1016 call_pdb=call_pdb)
1017 1017
1018 1018 #----------------------------------------------------------------------------
1019 1019 # module testing (minimal)
1020 1020 if __name__ == "__main__":
1021 1021 def spam(c, (d, e)):
1022 1022 x = c + d
1023 1023 y = c * d
1024 1024 foo(x, y)
1025 1025
1026 1026 def foo(a, b, bar=1):
1027 1027 eggs(a, b + bar)
1028 1028
1029 1029 def eggs(f, g, z=globals()):
1030 1030 h = f + g
1031 1031 i = f - g
1032 1032 return h / i
1033 1033
1034 1034 print ''
1035 1035 print '*** Before ***'
1036 1036 try:
1037 1037 print spam(1, (2, 3))
1038 1038 except:
1039 1039 traceback.print_exc()
1040 1040 print ''
1041 1041
1042 1042 handler = ColorTB()
1043 1043 print '*** ColorTB ***'
1044 1044 try:
1045 1045 print spam(1, (2, 3))
1046 1046 except:
1047 1047 apply(handler, sys.exc_info() )
1048 1048 print ''
1049 1049
1050 1050 handler = VerboseTB()
1051 1051 print '*** VerboseTB ***'
1052 1052 try:
1053 1053 print spam(1, (2, 3))
1054 1054 except:
1055 1055 apply(handler, sys.exc_info() )
1056 1056 print ''
1057 1057
1 NO CONTENT: file renamed from IPython/PyColorize.py to IPython/utils/PyColorize.py
@@ -1,21 +1,23 b''
1 1 #!/usr/bin/env python
2 2 # encoding: utf-8
3 3
4 4 def test_import_coloransi():
5 5 from IPython.utils import coloransi
6 6
7 7 def test_import_DPyGetOpt():
8 8 from IPython.utils import DPyGetOpt
9 9
10 10 def test_import_generics():
11 11 from IPython.utils import generics
12 12
13 13 def test_import_genutils():
14 14 from IPython.utils import genutils
15 15
16 16 def test_import_ipstruct():
17 17 from IPython.utils import ipstruct
18 18
19 19 def test_import_platutils():
20 20 from IPython.utils import platutils
21 21
22 def test_import_PyColorize():
23 from IPython.utils import PyColorize
General Comments 0
You need to be logged in to leave comments. Login now