##// END OF EJS Templates
Major cleanups and changes, see changelog/changeset for full details.
fperez -
Show More

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

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