##// END OF EJS Templates
Fixes to:...
fperez -
Show More

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

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