##// END OF EJS Templates
- Cleanup [1786], which went in with unfinished stuff by accident....
fperez -
Show More

The requested changes are too big and content was truncated. Show full diff

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