##// END OF EJS Templates
Merged 1071-1076 from banches/0.7.1
vivainio -
Show More

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

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