##// END OF EJS Templates
Add -r option to %logstart, to log 'raw' input instead of the processed one....
fperez -
Show More

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

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