##// 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 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 Logger class for IPython's logging facilities.
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 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
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 # Distributed under the terms of the BSD License. The full license is in
12 # Distributed under the terms of the BSD License. The full license is in
13 # the file COPYING, distributed as part of this software.
13 # the file COPYING, distributed as part of this software.
14 #*****************************************************************************
14 #*****************************************************************************
15
15
16 #****************************************************************************
16 #****************************************************************************
17 # Modules and globals
17 # Modules and globals
18
18
19 from IPython import Release
19 from IPython import Release
20 __author__ = '%s <%s>\n%s <%s>' % \
20 __author__ = '%s <%s>\n%s <%s>' % \
21 ( Release.authors['Janko'] + Release.authors['Fernando'] )
21 ( Release.authors['Janko'] + Release.authors['Fernando'] )
22 __license__ = Release.license
22 __license__ = Release.license
23
23
24 # Python standard modules
24 # Python standard modules
25 import glob
25 import glob
26 import os
26 import os
27 import sys
27 import time
28
29 # Homebrewed
30 from IPython.genutils import *
31
28
32 #****************************************************************************
29 #****************************************************************************
33 # FIXME: The logger class shouldn't be a mixin, it throws too many things into
30 # FIXME: This class isn't a mixin anymore, but it still needs attributes from
34 # the InteractiveShell namespace. Rather make it a standalone tool, and create
31 # ipython and does input cache management. Finish cleanup later...
35 # a Logger instance in InteractiveShell that uses it. Doing this will require
32
36 # tracking down a *lot* of nasty uses of the Logger attributes in
33 class Logger(object):
37 # InteractiveShell, but will clean up things quite a bit.
34 """A Logfile class with different policies for file creation"""
38
35
39 class Logger:
36 def __init__(self,shell,logfname='Logger.log',loghead='',logmode='over'):
40 """A Logfile Mixin class with different policies for file creation"""
37
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):
45 self._i00,self._i,self._ii,self._iii = '','','',''
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
57 if self.LOG:
58 self.logfname = self.LOG
59 else:
60 self.logfname = defname
61
39
62 if self.LOGMODE == 'over':
40 # this is the full ipython instance, we need some attributes from it
63 if os.path.isfile(self.logfname):
41 # which won't exist until later. What a mess, clean up later...
64 os.remove(self.logfname)
42 self.shell = shell
65 self.logfile = open(self.logfname,'w')
43
66 if self.LOGMODE == 'backup':
44 self.logfname = logfname
67 if os.path.isfile(self.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)
78
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 backup_logname = self.logfname+'~'
97 backup_logname = self.logfname+'~'
69 # Manually remove any old backup, since os.rename may fail
98 # Manually remove any old backup, since os.rename may fail
70 # under Windows.
99 # under Windows.
71 if os.path.isfile(backup_logname):
100 if isfile(backup_logname):
72 os.remove(backup_logname)
101 os.remove(backup_logname)
73 os.rename(self.logfname,backup_logname)
102 os.rename(self.logfname,backup_logname)
74 self.logfile = open(self.logfname,'w')
103 self.logfile = open(self.logfname,'w')
75 elif self.LOGMODE == 'global':
104
76 self.logfname = os.path.join(self.home_dir, self.defname)
105 elif logmode == 'global':
106 self.logfname = os.path.join(self.shell.home_dir,self.logfname)
77 self.logfile = open(self.logfname, 'a')
107 self.logfile = open(self.logfname, 'a')
78 self.LOG = self.logfname
108
79 elif self.LOGMODE == 'rotate':
109 elif logmode == 'over':
80 if os.path.isfile(self.logfname):
110 if isfile(self.logfname):
81 if os.path.isfile(self.logfname+'.001~'):
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 old = glob.glob(self.logfname+'.*~')
117 old = glob.glob(self.logfname+'.*~')
83 old.sort()
118 old.sort()
84 old.reverse()
119 old.reverse()
85 for f in old:
120 for f in old:
86 root, ext = os.path.splitext(f)
121 root, ext = os.path.splitext(f)
87 num = int(ext[1:-1])+1
122 num = int(ext[1:-1])+1
88 os.rename(f, root+'.'+`num`.zfill(3)+'~')
123 os.rename(f, root+'.'+`num`.zfill(3)+'~')
89 os.rename(self.logfname, self.logfname+'.001~')
124 os.rename(self.logfname, self.logfname+'.001~')
90 self.logfile = open(self.logfname,'w')
125 self.logfile = open(self.logfname,'w')
91 elif self.LOGMODE == 'append':
92 self.logfile = open(self.logfname,'a')
93
94 if self.LOGMODE != 'append':
95 self.logfile.write(header)
96 self.logfile.flush()
97
126
98 def logstart(self, header='',parameter_s = ''):
127 if logmode != 'append':
99 if not hasattr(self, 'LOG'):
128 self.logfile.write(self.loghead)
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
129
107 self._dolog = 1
130 self.logfile.flush()
108
131
109 def switch_log(self,val):
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 raise ValueError, \
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:
141 if self.logfile is None:
119 _ = self.logfile
120 except AttributeError:
121 print """
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 %logon/%logoff are for temporarily starting and stopping logging for a logfile
145 %logon/%logoff are for temporarily starting and stopping logging for a logfile
125 which already exists. But you must first start the logging process with
146 which already exists. But you must first start the logging process with
126 %logstart (optionally giving a logfile name)."""
147 %logstart (optionally giving a logfile name)."""
127
148
128 else:
149 else:
129 if self._dolog == val:
150 if self.log_active == val:
130 print 'Logging is already',label[val]
151 print 'Logging is already',label[val]
131 else:
152 else:
132 print 'Switching logging',label[val]
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 def logstate(self):
157 def logstate(self):
136 """Print a status message about the logger."""
158 """Print a status message about the logger."""
137 try:
159 if self.logfile is None:
138 logfile = self.logfname
139 except:
140 print 'Logging has not been activated.'
160 print 'Logging has not been activated.'
141 else:
161 else:
142 state = self._dolog and 'active' or 'temporarily suspended'
162 state = self.log_active and 'active' or 'temporarily suspended'
143 print """
163 print 'Filename :',self.logfname
144 File:\t%s
164 print 'Mode :',self.logmode
145 Mode:\t%s
165 print 'Output logging:',self.log_output
146 State:\t%s """ % (logfile,self.LOGMODE,state)
166 print 'Timestamping :',self.timestamp
147
167 print 'State :',state
148
168
149 def log(self, line,continuation=None):
169 def log(self, line,continuation=None):
150 """Write the line to a log and create input cache variables _i*."""
170 """Write the line to a log and create input cache variables _i*."""
151
171
152 # update the auto _i tables
172 # update the auto _i tables
153 #print '***logging line',line # dbg
173 #print '***logging line',line # dbg
154 #print '***cache_count', self.outputcache.prompt_count # dbg
174 #print '***cache_count', self.shell.outputcache.prompt_count # dbg
155 input_hist = self.log_ns['_ih']
175 input_hist = self.shell.user_ns['_ih']
156 if not continuation and line:
176 if not continuation and line:
157 self._iii = self._ii
177 self._iii = self._ii
158 self._ii = self._i
178 self._ii = self._i
159 self._i = self._i00
179 self._i = self._i00
160 # put back the final \n of every input line
180 # put back the final \n of every input line
161 self._i00 = line+'\n'
181 self._i00 = line+'\n'
162 #print 'Logging input:<%s>' % line # dbg
182 #print 'Logging input:<%s>' % line # dbg
163 input_hist.append(self._i00)
183 input_hist.append(self._i00)
164
184
165 # hackish access to top-level namespace to create _i1,_i2... dynamically
185 # hackish access to top-level namespace to create _i1,_i2... dynamically
166 to_main = {'_i':self._i,'_ii':self._ii,'_iii':self._iii}
186 to_main = {'_i':self._i,'_ii':self._ii,'_iii':self._iii}
167 if self.do_full_cache:
187 if self.shell.outputcache.do_full_cache:
168 in_num = self.outputcache.prompt_count
188 in_num = self.shell.outputcache.prompt_count
169 # add blank lines if the input cache fell out of sync. This can happen
189 # add blank lines if the input cache fell out of sync. This can
170 # for embedded instances which get killed via C-D and then get resumed.
190 # happen for embedded instances which get killed via C-D and then
191 # get resumed.
171 while in_num >= len(input_hist):
192 while in_num >= len(input_hist):
172 input_hist.append('\n')
193 input_hist.append('\n')
173 new_i = '_i%s' % in_num
194 new_i = '_i%s' % in_num
174 if continuation:
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 input_hist[in_num] = self._i00
197 input_hist[in_num] = self._i00
177 to_main[new_i] = self._i00
198 to_main[new_i] = self._i00
178 self.log_ns.update(to_main)
199 self.shell.user_ns.update(to_main)
179
200 self.log_write(line)
180 if self._dolog and line:
201
181 self.logfile.write(line+'\n')
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 self.logfile.flush()
216 self.logfile.flush()
183
217
184 def close_log(self):
218 def close_log(self):
185 if hasattr(self, 'logfile'):
186 self.logfile.close()
219 self.logfile.close()
220 self.logfile = None
187 self.logfname = ''
221 self.logfname = ''
@@ -1,2620 +1,2594 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Magic functions for InteractiveShell.
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 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
8 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
8 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
9 #
9 #
10 # Distributed under the terms of the BSD License. The full license is in
10 # Distributed under the terms of the BSD License. The full license is in
11 # the file COPYING, distributed as part of this software.
11 # the file COPYING, distributed as part of this software.
12 #*****************************************************************************
12 #*****************************************************************************
13
13
14 #****************************************************************************
14 #****************************************************************************
15 # Modules and globals
15 # Modules and globals
16
16
17 from IPython import Release
17 from IPython import Release
18 __author__ = '%s <%s>\n%s <%s>' % \
18 __author__ = '%s <%s>\n%s <%s>' % \
19 ( Release.authors['Janko'] + Release.authors['Fernando'] )
19 ( Release.authors['Janko'] + Release.authors['Fernando'] )
20 __license__ = Release.license
20 __license__ = Release.license
21
21
22 # Python standard modules
22 # Python standard modules
23 import __builtin__
23 import __builtin__
24 import bdb
24 import bdb
25 import inspect
25 import inspect
26 import os
26 import os
27 import pdb
27 import pdb
28 import pydoc
28 import pydoc
29 import sys
29 import sys
30 import re
30 import re
31 import tempfile
31 import tempfile
32 import time
32 import time
33 from cStringIO import StringIO
33 from cStringIO import StringIO
34 from getopt import getopt
34 from getopt import getopt
35 from pprint import pprint, pformat
35 from pprint import pprint, pformat
36
36
37 # profile isn't bundled by default in Debian for license reasons
37 # profile isn't bundled by default in Debian for license reasons
38 try:
38 try:
39 import profile,pstats
39 import profile,pstats
40 except ImportError:
40 except ImportError:
41 profile = pstats = None
41 profile = pstats = None
42
42
43 # Homebrewed
43 # Homebrewed
44 from IPython import Debugger, OInspect, wildcard
44 from IPython import Debugger, OInspect, wildcard
45 from IPython.FakeModule import FakeModule
45 from IPython.FakeModule import FakeModule
46 from IPython.Itpl import Itpl, itpl, printpl,itplns
46 from IPython.Itpl import Itpl, itpl, printpl,itplns
47 from IPython.PyColorize import Parser
47 from IPython.PyColorize import Parser
48 from IPython.Struct import Struct
48 from IPython.Struct import Struct
49 from IPython.genutils import *
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 # Utility functions
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 def on_off(tag):
53 def on_off(tag):
79 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
54 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
80 return ['OFF','ON'][tag]
55 return ['OFF','ON'][tag]
81
56
82
57
83 #****************************************************************************
58 #****************************************************************************
84 # Utility classes
59 # Utility classes
85 class Macro:
60 class Macro(list):
86 """Simple class to store the value of macros as strings.
61 """Simple class to store the value of macros as strings.
87
62
88 This allows us to later exec them by checking when something is an
63 This allows us to later exec them by checking when something is an
89 instance of this class."""
64 instance of this class."""
90
65
91 def __init__(self,cmds):
66 def __init__(self,data):
92 """Build a macro from a list of commands."""
67 list.__init__(self,data)
93
68 self.value = ''.join(data)
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
101
69
102 #***************************************************************************
70 #***************************************************************************
103 # Main class implementing Magic functionality
71 # Main class implementing Magic functionality
104 class Magic:
72 class Magic:
105 """Magic functions for InteractiveShell.
73 """Magic functions for InteractiveShell.
106
74
107 Shell functions which can be reached as %function_name. All magic
75 Shell functions which can be reached as %function_name. All magic
108 functions should accept a string, which they can parse for their own
76 functions should accept a string, which they can parse for their own
109 needs. This can make some functions easier to type, eg `%cd ../`
77 needs. This can make some functions easier to type, eg `%cd ../`
110 vs. `%cd("../")`
78 vs. `%cd("../")`
111
79
112 ALL definitions MUST begin with the prefix magic_. The user won't need it
80 ALL definitions MUST begin with the prefix magic_. The user won't need it
113 at the command line, but it is is needed in the definition. """
81 at the command line, but it is is needed in the definition. """
114
82
115 # class globals
83 # class globals
116 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
84 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
117 'Automagic is ON, % prefix NOT needed for magic functions.']
85 'Automagic is ON, % prefix NOT needed for magic functions.']
118
86
119 #......................................................................
87 #......................................................................
120 # some utility functions
88 # some utility functions
121
89
122 def __init__(self,shell):
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 self.options_table = {}
92 self.options_table = {}
127 MAGIC_PREFIX = shell.name+'.magic_'
128 MAGIC_ESCAPE = shell.ESC_MAGIC
129 if profile is None:
93 if profile is None:
130 self.magic_prun = self.profile_missing_notice
94 self.magic_prun = self.profile_missing_notice
95 self.shell = shell
131
96
132 def profile_missing_notice(self, *args, **kwargs):
97 def profile_missing_notice(self, *args, **kwargs):
133 error("""\
98 error("""\
134 The profile module could not be found. If you are a Debian user,
99 The profile module could not be found. If you are a Debian user,
135 it has been removed from the standard Debian package because of its non-free
100 it has been removed from the standard Debian package because of its non-free
136 license. To use profiling, please install"python2.3-profiler" from non-free.""")
101 license. To use profiling, please install"python2.3-profiler" from non-free.""")
137
102
138 def default_option(self,fn,optstr):
103 def default_option(self,fn,optstr):
139 """Make an entry in the options_table for fn, with value optstr"""
104 """Make an entry in the options_table for fn, with value optstr"""
140
105
141 if fn not in self.lsmagic():
106 if fn not in self.lsmagic():
142 error("%s is not a magic function" % fn)
107 error("%s is not a magic function" % fn)
143 self.options_table[fn] = optstr
108 self.options_table[fn] = optstr
144
109
145 def lsmagic(self):
110 def lsmagic(self):
146 """Return a list of currently available magic functions.
111 """Return a list of currently available magic functions.
147
112
148 Gives a list of the bare names after mangling (['ls','cd', ...], not
113 Gives a list of the bare names after mangling (['ls','cd', ...], not
149 ['magic_ls','magic_cd',...]"""
114 ['magic_ls','magic_cd',...]"""
150
115
151 # FIXME. This needs a cleanup, in the way the magics list is built.
116 # FIXME. This needs a cleanup, in the way the magics list is built.
152
117
153 # magics in class definition
118 # magics in class definition
154 class_magic = lambda fn: fn.startswith('magic_') and \
119 class_magic = lambda fn: fn.startswith('magic_') and \
155 callable(Magic.__dict__[fn])
120 callable(Magic.__dict__[fn])
156 # in instance namespace (run-time user additions)
121 # in instance namespace (run-time user additions)
157 inst_magic = lambda fn: fn.startswith('magic_') and \
122 inst_magic = lambda fn: fn.startswith('magic_') and \
158 callable(self.__dict__[fn])
123 callable(self.__dict__[fn])
159 # and bound magics by user (so they can access self):
124 # and bound magics by user (so they can access self):
160 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
125 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
161 callable(self.__class__.__dict__[fn])
126 callable(self.__class__.__dict__[fn])
162 magics = filter(class_magic,Magic.__dict__.keys()) + \
127 magics = filter(class_magic,Magic.__dict__.keys()) + \
163 filter(inst_magic,self.__dict__.keys()) + \
128 filter(inst_magic,self.__dict__.keys()) + \
164 filter(inst_bound_magic,self.__class__.__dict__.keys())
129 filter(inst_bound_magic,self.__class__.__dict__.keys())
165 out = []
130 out = []
166 for fn in magics:
131 for fn in magics:
167 out.append(fn.replace('magic_','',1))
132 out.append(fn.replace('magic_','',1))
168 out.sort()
133 out.sort()
169 return out
134 return out
170
135
171 def set_shell(self,shell):
172 self.shell = shell
173 self.alias_table = shell.alias_table
174
175 def extract_input_slices(self,slices):
136 def extract_input_slices(self,slices):
176 """Return as a string a set of input history slices.
137 """Return as a string a set of input history slices.
177
138
178 The set of slices is given as a list of strings (like ['1','4:8','9'],
139 The set of slices is given as a list of strings (like ['1','4:8','9'],
179 since this function is for use by magic functions which get their
140 since this function is for use by magic functions which get their
180 arguments as strings."""
141 arguments as strings."""
181
142
182 cmds = []
143 cmds = []
183 for chunk in slices:
144 for chunk in slices:
184 if ':' in chunk:
145 if ':' in chunk:
185 ini,fin = map(int,chunk.split(':'))
146 ini,fin = map(int,chunk.split(':'))
186 else:
147 else:
187 ini = int(chunk)
148 ini = int(chunk)
188 fin = ini+1
149 fin = ini+1
189 cmds.append(self.shell.input_hist[ini:fin])
150 cmds.append(self.shell.input_hist[ini:fin])
190 return cmds
151 return cmds
191
152
192 def _ofind(self,oname):
153 def _ofind(self,oname):
193 """Find an object in the available namespaces.
154 """Find an object in the available namespaces.
194
155
195 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
156 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
196
157
197 Has special code to detect magic functions.
158 Has special code to detect magic functions.
198 """
159 """
199
160
200 oname = oname.strip()
161 oname = oname.strip()
201
162
202 # Namespaces to search in:
163 # Namespaces to search in:
203 user_ns = self.shell.user_ns
164 user_ns = self.shell.user_ns
204 internal_ns = self.shell.internal_ns
165 internal_ns = self.shell.internal_ns
205 builtin_ns = __builtin__.__dict__
166 builtin_ns = __builtin__.__dict__
206 alias_ns = self.shell.alias_table
167 alias_ns = self.shell.alias_table
207
168
208 # Put them in a list. The order is important so that we find things in
169 # Put them in a list. The order is important so that we find things in
209 # the same order that Python finds them.
170 # the same order that Python finds them.
210 namespaces = [ ('Interactive',user_ns),
171 namespaces = [ ('Interactive',user_ns),
211 ('IPython internal',internal_ns),
172 ('IPython internal',internal_ns),
212 ('Python builtin',builtin_ns),
173 ('Python builtin',builtin_ns),
213 ('Alias',alias_ns),
174 ('Alias',alias_ns),
214 ]
175 ]
215
176
216 # initialize results to 'null'
177 # initialize results to 'null'
217 found = 0; obj = None; ospace = None; ds = None;
178 found = 0; obj = None; ospace = None; ds = None;
218 ismagic = 0; isalias = 0
179 ismagic = 0; isalias = 0
219
180
220 # Look for the given name by splitting it in parts. If the head is
181 # Look for the given name by splitting it in parts. If the head is
221 # found, then we look for all the remaining parts as members, and only
182 # found, then we look for all the remaining parts as members, and only
222 # declare success if we can find them all.
183 # declare success if we can find them all.
223 oname_parts = oname.split('.')
184 oname_parts = oname.split('.')
224 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
185 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
225 for nsname,ns in namespaces:
186 for nsname,ns in namespaces:
226 try:
187 try:
227 obj = ns[oname_head]
188 obj = ns[oname_head]
228 except KeyError:
189 except KeyError:
229 continue
190 continue
230 else:
191 else:
231 for part in oname_rest:
192 for part in oname_rest:
232 try:
193 try:
233 obj = getattr(obj,part)
194 obj = getattr(obj,part)
234 except:
195 except:
235 # Blanket except b/c some badly implemented objects
196 # Blanket except b/c some badly implemented objects
236 # allow __getattr__ to raise exceptions other than
197 # allow __getattr__ to raise exceptions other than
237 # AttributeError, which then crashes IPython.
198 # AttributeError, which then crashes IPython.
238 break
199 break
239 else:
200 else:
240 # If we finish the for loop (no break), we got all members
201 # If we finish the for loop (no break), we got all members
241 found = 1
202 found = 1
242 ospace = nsname
203 ospace = nsname
243 if ns == alias_ns:
204 if ns == alias_ns:
244 isalias = 1
205 isalias = 1
245 break # namespace loop
206 break # namespace loop
246
207
247 # Try to see if it's magic
208 # Try to see if it's magic
248 if not found:
209 if not found:
249 if oname.startswith(self.shell.ESC_MAGIC):
210 if oname.startswith(self.shell.ESC_MAGIC):
250 oname = oname[1:]
211 oname = oname[1:]
251 obj = getattr(self,'magic_'+oname,None)
212 obj = getattr(self,'magic_'+oname,None)
252 if obj is not None:
213 if obj is not None:
253 found = 1
214 found = 1
254 ospace = 'IPython internal'
215 ospace = 'IPython internal'
255 ismagic = 1
216 ismagic = 1
256
217
257 # Last try: special-case some literals like '', [], {}, etc:
218 # Last try: special-case some literals like '', [], {}, etc:
258 if not found and oname_head in ["''",'""','[]','{}','()']:
219 if not found and oname_head in ["''",'""','[]','{}','()']:
259 obj = eval(oname_head)
220 obj = eval(oname_head)
260 found = 1
221 found = 1
261 ospace = 'Interactive'
222 ospace = 'Interactive'
262
223
263 return {'found':found, 'obj':obj, 'namespace':ospace,
224 return {'found':found, 'obj':obj, 'namespace':ospace,
264 'ismagic':ismagic, 'isalias':isalias}
225 'ismagic':ismagic, 'isalias':isalias}
265
226
266 def arg_err(self,func):
227 def arg_err(self,func):
267 """Print docstring if incorrect arguments were passed"""
228 """Print docstring if incorrect arguments were passed"""
268 print 'Error in arguments:'
229 print 'Error in arguments:'
269 print OInspect.getdoc(func)
230 print OInspect.getdoc(func)
270
231
271
232
272 def format_latex(self,str):
233 def format_latex(self,str):
273 """Format a string for latex inclusion."""
234 """Format a string for latex inclusion."""
274
235
275 # Characters that need to be escaped for latex:
236 # Characters that need to be escaped for latex:
276 escape_re = re.compile(r'(%|_|\$)',re.MULTILINE)
237 escape_re = re.compile(r'(%|_|\$)',re.MULTILINE)
277 # Magic command names as headers:
238 # Magic command names as headers:
278 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
239 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
279 re.MULTILINE)
240 re.MULTILINE)
280 # Magic commands
241 # Magic commands
281 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
242 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
282 re.MULTILINE)
243 re.MULTILINE)
283 # Paragraph continue
244 # Paragraph continue
284 par_re = re.compile(r'\\$',re.MULTILINE)
245 par_re = re.compile(r'\\$',re.MULTILINE)
285
246
286 str = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',str)
247 str = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',str)
287 str = cmd_re.sub(r'\\texttt{\g<cmd>}',str)
248 str = cmd_re.sub(r'\\texttt{\g<cmd>}',str)
288 str = par_re.sub(r'\\\\',str)
249 str = par_re.sub(r'\\\\',str)
289 str = escape_re.sub(r'\\\1',str)
250 str = escape_re.sub(r'\\\1',str)
290 return str
251 return str
291
252
292 def format_screen(self,str):
253 def format_screen(self,str):
293 """Format a string for screen printing.
254 """Format a string for screen printing.
294
255
295 This removes some latex-type format codes."""
256 This removes some latex-type format codes."""
296 # Paragraph continue
257 # Paragraph continue
297 par_re = re.compile(r'\\$',re.MULTILINE)
258 par_re = re.compile(r'\\$',re.MULTILINE)
298 str = par_re.sub('',str)
259 str = par_re.sub('',str)
299 return str
260 return str
300
261
301 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
262 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
302 """Parse options passed to an argument string.
263 """Parse options passed to an argument string.
303
264
304 The interface is similar to that of getopt(), but it returns back a
265 The interface is similar to that of getopt(), but it returns back a
305 Struct with the options as keys and the stripped argument string still
266 Struct with the options as keys and the stripped argument string still
306 as a string.
267 as a string.
307
268
308 arg_str is quoted as a true sys.argv vector by using shlex.split.
269 arg_str is quoted as a true sys.argv vector by using shlex.split.
309 This allows us to easily expand variables, glob files, quote
270 This allows us to easily expand variables, glob files, quote
310 arguments, etc.
271 arguments, etc.
311
272
312 Options:
273 Options:
313 -mode: default 'string'. If given as 'list', the argument string is
274 -mode: default 'string'. If given as 'list', the argument string is
314 returned as a list (split on whitespace) instead of a string.
275 returned as a list (split on whitespace) instead of a string.
315
276
316 -list_all: put all option values in lists. Normally only options
277 -list_all: put all option values in lists. Normally only options
317 appearing more than once are put in a list."""
278 appearing more than once are put in a list."""
318
279
319 # inject default options at the beginning of the input line
280 # inject default options at the beginning of the input line
320 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
281 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
321 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
282 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
322
283
323 mode = kw.get('mode','string')
284 mode = kw.get('mode','string')
324 if mode not in ['string','list']:
285 if mode not in ['string','list']:
325 raise ValueError,'incorrect mode given: %s' % mode
286 raise ValueError,'incorrect mode given: %s' % mode
326 # Get options
287 # Get options
327 list_all = kw.get('list_all',0)
288 list_all = kw.get('list_all',0)
328
289
329 # Check if we have more than one argument to warrant extra processing:
290 # Check if we have more than one argument to warrant extra processing:
330 odict = {} # Dictionary with options
291 odict = {} # Dictionary with options
331 args = arg_str.split()
292 args = arg_str.split()
332 if len(args) >= 1:
293 if len(args) >= 1:
333 # If the list of inputs only has 0 or 1 thing in it, there's no
294 # If the list of inputs only has 0 or 1 thing in it, there's no
334 # need to look for options
295 # need to look for options
335 argv = shlex_split(arg_str)
296 argv = shlex_split(arg_str)
336 # Do regular option processing
297 # Do regular option processing
337 opts,args = getopt(argv,opt_str,*long_opts)
298 opts,args = getopt(argv,opt_str,*long_opts)
338 for o,a in opts:
299 for o,a in opts:
339 if o.startswith('--'):
300 if o.startswith('--'):
340 o = o[2:]
301 o = o[2:]
341 else:
302 else:
342 o = o[1:]
303 o = o[1:]
343 try:
304 try:
344 odict[o].append(a)
305 odict[o].append(a)
345 except AttributeError:
306 except AttributeError:
346 odict[o] = [odict[o],a]
307 odict[o] = [odict[o],a]
347 except KeyError:
308 except KeyError:
348 if list_all:
309 if list_all:
349 odict[o] = [a]
310 odict[o] = [a]
350 else:
311 else:
351 odict[o] = a
312 odict[o] = a
352
313
353 # Prepare opts,args for return
314 # Prepare opts,args for return
354 opts = Struct(odict)
315 opts = Struct(odict)
355 if mode == 'string':
316 if mode == 'string':
356 args = ' '.join(args)
317 args = ' '.join(args)
357
318
358 return opts,args
319 return opts,args
359
320
360 #......................................................................
321 #......................................................................
361 # And now the actual magic functions
322 # And now the actual magic functions
362
323
363 # Functions for IPython shell work (vars,funcs, config, etc)
324 # Functions for IPython shell work (vars,funcs, config, etc)
364 def magic_lsmagic(self, parameter_s = ''):
325 def magic_lsmagic(self, parameter_s = ''):
365 """List currently available magic functions."""
326 """List currently available magic functions."""
366 mesc = self.shell.ESC_MAGIC
327 mesc = self.shell.ESC_MAGIC
367 print 'Available magic functions:\n'+mesc+\
328 print 'Available magic functions:\n'+mesc+\
368 (' '+mesc).join(self.lsmagic())
329 (' '+mesc).join(self.lsmagic())
369 print '\n' + Magic.auto_status[self.shell.rc.automagic]
330 print '\n' + Magic.auto_status[self.shell.rc.automagic]
370 return None
331 return None
371
332
372 def magic_magic(self, parameter_s = ''):
333 def magic_magic(self, parameter_s = ''):
373 """Print information about the magic function system."""
334 """Print information about the magic function system."""
374
335
375 mode = ''
336 mode = ''
376 try:
337 try:
377 if parameter_s.split()[0] == '-latex':
338 if parameter_s.split()[0] == '-latex':
378 mode = 'latex'
339 mode = 'latex'
379 except:
340 except:
380 pass
341 pass
381
342
382 magic_docs = []
343 magic_docs = []
383 for fname in self.lsmagic():
344 for fname in self.lsmagic():
384 mname = 'magic_' + fname
345 mname = 'magic_' + fname
385 for space in (Magic,self,self.__class__):
346 for space in (Magic,self,self.__class__):
386 try:
347 try:
387 fn = space.__dict__[mname]
348 fn = space.__dict__[mname]
388 except KeyError:
349 except KeyError:
389 pass
350 pass
390 else:
351 else:
391 break
352 break
392 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
353 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
393 fname,fn.__doc__))
354 fname,fn.__doc__))
394 magic_docs = ''.join(magic_docs)
355 magic_docs = ''.join(magic_docs)
395
356
396 if mode == 'latex':
357 if mode == 'latex':
397 print self.format_latex(magic_docs)
358 print self.format_latex(magic_docs)
398 return
359 return
399 else:
360 else:
400 magic_docs = self.format_screen(magic_docs)
361 magic_docs = self.format_screen(magic_docs)
401
362
402 outmsg = """
363 outmsg = """
403 IPython's 'magic' functions
364 IPython's 'magic' functions
404 ===========================
365 ===========================
405
366
406 The magic function system provides a series of functions which allow you to
367 The magic function system provides a series of functions which allow you to
407 control the behavior of IPython itself, plus a lot of system-type
368 control the behavior of IPython itself, plus a lot of system-type
408 features. All these functions are prefixed with a % character, but parameters
369 features. All these functions are prefixed with a % character, but parameters
409 are given without parentheses or quotes.
370 are given without parentheses or quotes.
410
371
411 NOTE: If you have 'automagic' enabled (via the command line option or with the
372 NOTE: If you have 'automagic' enabled (via the command line option or with the
412 %automagic function), you don't need to type in the % explicitly. By default,
373 %automagic function), you don't need to type in the % explicitly. By default,
413 IPython ships with automagic on, so you should only rarely need the % escape.
374 IPython ships with automagic on, so you should only rarely need the % escape.
414
375
415 Example: typing '%cd mydir' (without the quotes) changes you working directory
376 Example: typing '%cd mydir' (without the quotes) changes you working directory
416 to 'mydir', if it exists.
377 to 'mydir', if it exists.
417
378
418 You can define your own magic functions to extend the system. See the supplied
379 You can define your own magic functions to extend the system. See the supplied
419 ipythonrc and example-magic.py files for details (in your ipython
380 ipythonrc and example-magic.py files for details (in your ipython
420 configuration directory, typically $HOME/.ipython/).
381 configuration directory, typically $HOME/.ipython/).
421
382
422 You can also define your own aliased names for magic functions. In your
383 You can also define your own aliased names for magic functions. In your
423 ipythonrc file, placing a line like:
384 ipythonrc file, placing a line like:
424
385
425 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
386 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
426
387
427 will define %pf as a new name for %profile.
388 will define %pf as a new name for %profile.
428
389
429 You can also call magics in code using the ipmagic() function, which IPython
390 You can also call magics in code using the ipmagic() function, which IPython
430 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
391 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
431
392
432 For a list of the available magic functions, use %lsmagic. For a description
393 For a list of the available magic functions, use %lsmagic. For a description
433 of any of them, type %magic_name?, e.g. '%cd?'.
394 of any of them, type %magic_name?, e.g. '%cd?'.
434
395
435 Currently the magic system has the following functions:\n"""
396 Currently the magic system has the following functions:\n"""
436
397
437 mesc = self.shell.ESC_MAGIC
398 mesc = self.shell.ESC_MAGIC
438 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
399 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
439 "\n\n%s%s\n\n%s" % (outmsg,
400 "\n\n%s%s\n\n%s" % (outmsg,
440 magic_docs,mesc,mesc,
401 magic_docs,mesc,mesc,
441 (' '+mesc).join(self.lsmagic()),
402 (' '+mesc).join(self.lsmagic()),
442 Magic.auto_status[self.shell.rc.automagic] ) )
403 Magic.auto_status[self.shell.rc.automagic] ) )
443
404
444 page(outmsg,screen_lines=self.shell.rc.screen_length)
405 page(outmsg,screen_lines=self.shell.rc.screen_length)
445
406
446 def magic_automagic(self, parameter_s = ''):
407 def magic_automagic(self, parameter_s = ''):
447 """Make magic functions callable without having to type the initial %.
408 """Make magic functions callable without having to type the initial %.
448
409
449 Toggles on/off (when off, you must call it as %automagic, of
410 Toggles on/off (when off, you must call it as %automagic, of
450 course). Note that magic functions have lowest priority, so if there's
411 course). Note that magic functions have lowest priority, so if there's
451 a variable whose name collides with that of a magic fn, automagic
412 a variable whose name collides with that of a magic fn, automagic
452 won't work for that function (you get the variable instead). However,
413 won't work for that function (you get the variable instead). However,
453 if you delete the variable (del var), the previously shadowed magic
414 if you delete the variable (del var), the previously shadowed magic
454 function becomes visible to automagic again."""
415 function becomes visible to automagic again."""
455
416
456 rc = self.shell.rc
417 rc = self.shell.rc
457 rc.automagic = not rc.automagic
418 rc.automagic = not rc.automagic
458 print '\n' + Magic.auto_status[rc.automagic]
419 print '\n' + Magic.auto_status[rc.automagic]
459
420
460 def magic_autocall(self, parameter_s = ''):
421 def magic_autocall(self, parameter_s = ''):
461 """Make functions callable without having to type parentheses.
422 """Make functions callable without having to type parentheses.
462
423
463 This toggles the autocall command line option on and off."""
424 This toggles the autocall command line option on and off."""
464
425
465 rc = self.shell.rc
426 rc = self.shell.rc
466 rc.autocall = not rc.autocall
427 rc.autocall = not rc.autocall
467 print "Automatic calling is:",['OFF','ON'][rc.autocall]
428 print "Automatic calling is:",['OFF','ON'][rc.autocall]
468
429
469 def magic_autoindent(self, parameter_s = ''):
430 def magic_autoindent(self, parameter_s = ''):
470 """Toggle autoindent on/off (if available)."""
431 """Toggle autoindent on/off (if available)."""
471
432
472 self.shell.set_autoindent()
433 self.shell.set_autoindent()
473 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
434 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
474
435
475 def magic_system_verbose(self, parameter_s = ''):
436 def magic_system_verbose(self, parameter_s = ''):
476 """Toggle verbose printing of system calls on/off."""
437 """Toggle verbose printing of system calls on/off."""
477
438
478 self.shell.rc_set_toggle('system_verbose')
439 self.shell.rc_set_toggle('system_verbose')
479 print "System verbose printing is:",\
440 print "System verbose printing is:",\
480 ['OFF','ON'][self.shell.rc.system_verbose]
441 ['OFF','ON'][self.shell.rc.system_verbose]
481
442
482 def magic_history(self, parameter_s = ''):
443 def magic_history(self, parameter_s = ''):
483 """Print input history (_i<n> variables), with most recent last.
444 """Print input history (_i<n> variables), with most recent last.
484
445
485 %history [-n] -> print at most 40 inputs (some may be multi-line)\\
446 %history [-n] -> print at most 40 inputs (some may be multi-line)\\
486 %history [-n] n -> print at most n inputs\\
447 %history [-n] n -> print at most n inputs\\
487 %history [-n] n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
448 %history [-n] n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
488
449
489 Each input's number <n> is shown, and is accessible as the
450 Each input's number <n> is shown, and is accessible as the
490 automatically generated variable _i<n>. Multi-line statements are
451 automatically generated variable _i<n>. Multi-line statements are
491 printed starting at a new line for easy copy/paste.
452 printed starting at a new line for easy copy/paste.
492
453
493 If option -n is used, input numbers are not printed. This is useful if
454 If option -n is used, input numbers are not printed. This is useful if
494 you want to get a printout of many lines which can be directly pasted
455 you want to get a printout of many lines which can be directly pasted
495 into a text editor.
456 into a text editor.
496
457
497 This feature is only available if numbered prompts are in use."""
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 print 'This feature is only available if numbered prompts are in use.'
461 print 'This feature is only available if numbered prompts are in use.'
501 return
462 return
502 opts,args = self.parse_options(parameter_s,'n',mode='list')
463 opts,args = self.parse_options(parameter_s,'n',mode='list')
503
464
504 default_length = 40
465 default_length = 40
505 if len(args) == 0:
466 if len(args) == 0:
506 final = self.outputcache.prompt_count
467 final = self.shell.outputcache.prompt_count
507 init = max(1,final-default_length)
468 init = max(1,final-default_length)
508 elif len(args) == 1:
469 elif len(args) == 1:
509 final = self.outputcache.prompt_count
470 final = self.shell.outputcache.prompt_count
510 init = max(1,final-int(args[0]))
471 init = max(1,final-int(args[0]))
511 elif len(args) == 2:
472 elif len(args) == 2:
512 init,final = map(int,args)
473 init,final = map(int,args)
513 else:
474 else:
514 warn('%hist takes 0, 1 or 2 arguments separated by spaces.')
475 warn('%hist takes 0, 1 or 2 arguments separated by spaces.')
515 print self.magic_hist.__doc__
476 print self.magic_hist.__doc__
516 return
477 return
517 width = len(str(final))
478 width = len(str(final))
518 line_sep = ['','\n']
479 line_sep = ['','\n']
519 input_hist = self.shell.input_hist
480 input_hist = self.shell.input_hist
520 print_nums = not opts.has_key('n')
481 print_nums = not opts.has_key('n')
521 for in_num in range(init,final):
482 for in_num in range(init,final):
522 inline = input_hist[in_num]
483 inline = input_hist[in_num]
523 multiline = inline.count('\n') > 1
484 multiline = inline.count('\n') > 1
524 if print_nums:
485 if print_nums:
525 print str(in_num).ljust(width)+':'+ line_sep[multiline],
486 print str(in_num).ljust(width)+':'+ line_sep[multiline],
526 if inline.startswith('#'+self.shell.ESC_MAGIC) or \
487 if inline.startswith('#'+self.shell.ESC_MAGIC) or \
527 inline.startswith('#!'):
488 inline.startswith('#!'):
528 print inline[1:],
489 print inline[1:],
529 else:
490 else:
530 print inline,
491 print inline,
531
492
532 def magic_hist(self, parameter_s=''):
493 def magic_hist(self, parameter_s=''):
533 """Alternate name for %history."""
494 """Alternate name for %history."""
534 return self.magic_history(parameter_s)
495 return self.magic_history(parameter_s)
535
496
536 def magic_p(self, parameter_s=''):
497 def magic_p(self, parameter_s=''):
537 """Just a short alias for Python's 'print'."""
498 """Just a short alias for Python's 'print'."""
538 exec 'print ' + parameter_s in self.shell.user_ns
499 exec 'print ' + parameter_s in self.shell.user_ns
539
500
540 def magic_r(self, parameter_s=''):
501 def magic_r(self, parameter_s=''):
541 """Repeat previous input.
502 """Repeat previous input.
542
503
543 If given an argument, repeats the previous command which starts with
504 If given an argument, repeats the previous command which starts with
544 the same string, otherwise it just repeats the previous input.
505 the same string, otherwise it just repeats the previous input.
545
506
546 Shell escaped commands (with ! as first character) are not recognized
507 Shell escaped commands (with ! as first character) are not recognized
547 by this system, only pure python code and magic commands.
508 by this system, only pure python code and magic commands.
548 """
509 """
549
510
550 start = parameter_s.strip()
511 start = parameter_s.strip()
551 esc_magic = self.shell.ESC_MAGIC
512 esc_magic = self.shell.ESC_MAGIC
552 # Identify magic commands even if automagic is on (which means
513 # Identify magic commands even if automagic is on (which means
553 # the in-memory version is different from that typed by the user).
514 # the in-memory version is different from that typed by the user).
554 if self.shell.rc.automagic:
515 if self.shell.rc.automagic:
555 start_magic = esc_magic+start
516 start_magic = esc_magic+start
556 else:
517 else:
557 start_magic = start
518 start_magic = start
558 # Look through the input history in reverse
519 # Look through the input history in reverse
559 for n in range(len(self.shell.input_hist)-2,0,-1):
520 for n in range(len(self.shell.input_hist)-2,0,-1):
560 input = self.shell.input_hist[n]
521 input = self.shell.input_hist[n]
561 # skip plain 'r' lines so we don't recurse to infinity
522 # skip plain 'r' lines so we don't recurse to infinity
562 if input != 'ipmagic("r")\n' and \
523 if input != 'ipmagic("r")\n' and \
563 (input.startswith(start) or input.startswith(start_magic)):
524 (input.startswith(start) or input.startswith(start_magic)):
564 #print 'match',`input` # dbg
525 #print 'match',`input` # dbg
565 if input.startswith(esc_magic):
566 input = magic2python(input)
567 #print 'modified',`input` # dbg
568 print 'Executing:',input,
526 print 'Executing:',input,
569 exec input in self.shell.user_ns
527 self.shell.runlines(input)
570 return
528 return
571 print 'No previous input matching `%s` found.' % start
529 print 'No previous input matching `%s` found.' % start
572
530
573 def magic_page(self, parameter_s=''):
531 def magic_page(self, parameter_s=''):
574 """Pretty print the object and display it through a pager.
532 """Pretty print the object and display it through a pager.
575
533
576 If no parameter is given, use _ (last output)."""
534 If no parameter is given, use _ (last output)."""
577 # After a function contributed by Olivier Aubert, slightly modified.
535 # After a function contributed by Olivier Aubert, slightly modified.
578
536
579 oname = parameter_s and parameter_s or '_'
537 oname = parameter_s and parameter_s or '_'
580 info = self._ofind(oname)
538 info = self._ofind(oname)
581 if info['found']:
539 if info['found']:
582 page(pformat(info['obj']))
540 page(pformat(info['obj']))
583 else:
541 else:
584 print 'Object `%s` not found' % oname
542 print 'Object `%s` not found' % oname
585
543
586 def magic_profile(self, parameter_s=''):
544 def magic_profile(self, parameter_s=''):
587 """Print your currently active IPyhton profile."""
545 """Print your currently active IPyhton profile."""
588 if self.shell.rc.profile:
546 if self.shell.rc.profile:
589 printpl('Current IPython profile: $self.shell.rc.profile.')
547 printpl('Current IPython profile: $self.shell.rc.profile.')
590 else:
548 else:
591 print 'No profile active.'
549 print 'No profile active.'
592
550
593 def _inspect(self,meth,oname,**kw):
551 def _inspect(self,meth,oname,**kw):
594 """Generic interface to the inspector system.
552 """Generic interface to the inspector system.
595
553
596 This function is meant to be called by pdef, pdoc & friends."""
554 This function is meant to be called by pdef, pdoc & friends."""
597
555
598 oname = oname.strip()
556 oname = oname.strip()
599 info = Struct(self._ofind(oname))
557 info = Struct(self._ofind(oname))
600 if info.found:
558 if info.found:
601 pmethod = getattr(self.shell.inspector,meth)
559 pmethod = getattr(self.shell.inspector,meth)
602 formatter = info.ismagic and self.format_screen or None
560 formatter = info.ismagic and self.format_screen or None
603 if meth == 'pdoc':
561 if meth == 'pdoc':
604 pmethod(info.obj,oname,formatter)
562 pmethod(info.obj,oname,formatter)
605 elif meth == 'pinfo':
563 elif meth == 'pinfo':
606 pmethod(info.obj,oname,formatter,info,**kw)
564 pmethod(info.obj,oname,formatter,info,**kw)
607 else:
565 else:
608 pmethod(info.obj,oname)
566 pmethod(info.obj,oname)
609 else:
567 else:
610 print 'Object `%s` not found.' % oname
568 print 'Object `%s` not found.' % oname
611 return 'not found' # so callers can take other action
569 return 'not found' # so callers can take other action
612
570
613 def magic_pdef(self, parameter_s=''):
571 def magic_pdef(self, parameter_s=''):
614 """Print the definition header for any callable object.
572 """Print the definition header for any callable object.
615
573
616 If the object is a class, print the constructor information."""
574 If the object is a class, print the constructor information."""
617 self._inspect('pdef',parameter_s)
575 self._inspect('pdef',parameter_s)
618
576
619 def magic_pdoc(self, parameter_s=''):
577 def magic_pdoc(self, parameter_s=''):
620 """Print the docstring for an object.
578 """Print the docstring for an object.
621
579
622 If the given object is a class, it will print both the class and the
580 If the given object is a class, it will print both the class and the
623 constructor docstrings."""
581 constructor docstrings."""
624 self._inspect('pdoc',parameter_s)
582 self._inspect('pdoc',parameter_s)
625
583
626 def magic_psource(self, parameter_s=''):
584 def magic_psource(self, parameter_s=''):
627 """Print (or run through pager) the source code for an object."""
585 """Print (or run through pager) the source code for an object."""
628 self._inspect('psource',parameter_s)
586 self._inspect('psource',parameter_s)
629
587
630 def magic_pfile(self, parameter_s=''):
588 def magic_pfile(self, parameter_s=''):
631 """Print (or run through pager) the file where an object is defined.
589 """Print (or run through pager) the file where an object is defined.
632
590
633 The file opens at the line where the object definition begins. IPython
591 The file opens at the line where the object definition begins. IPython
634 will honor the environment variable PAGER if set, and otherwise will
592 will honor the environment variable PAGER if set, and otherwise will
635 do its best to print the file in a convenient form.
593 do its best to print the file in a convenient form.
636
594
637 If the given argument is not an object currently defined, IPython will
595 If the given argument is not an object currently defined, IPython will
638 try to interpret it as a filename (automatically adding a .py extension
596 try to interpret it as a filename (automatically adding a .py extension
639 if needed). You can thus use %pfile as a syntax highlighting code
597 if needed). You can thus use %pfile as a syntax highlighting code
640 viewer."""
598 viewer."""
641
599
642 # first interpret argument as an object name
600 # first interpret argument as an object name
643 out = self._inspect('pfile',parameter_s)
601 out = self._inspect('pfile',parameter_s)
644 # if not, try the input as a filename
602 # if not, try the input as a filename
645 if out == 'not found':
603 if out == 'not found':
646 try:
604 try:
647 filename = get_py_filename(parameter_s)
605 filename = get_py_filename(parameter_s)
648 except IOError,msg:
606 except IOError,msg:
649 print msg
607 print msg
650 return
608 return
651 page(self.shell.inspector.format(file(filename).read()))
609 page(self.shell.inspector.format(file(filename).read()))
652
610
653 def magic_pinfo(self, parameter_s=''):
611 def magic_pinfo(self, parameter_s=''):
654 """Provide detailed information about an object.
612 """Provide detailed information about an object.
655
613
656 '%pinfo object' is just a synonym for object? or ?object."""
614 '%pinfo object' is just a synonym for object? or ?object."""
657
615
658 #print 'pinfo par: <%s>' % parameter_s # dbg
616 #print 'pinfo par: <%s>' % parameter_s # dbg
659
617
660 # detail_level: 0 -> obj? , 1 -> obj??
618 # detail_level: 0 -> obj? , 1 -> obj??
661 detail_level = 0
619 detail_level = 0
662 # We need to detect if we got called as 'pinfo pinfo foo', which can
620 # We need to detect if we got called as 'pinfo pinfo foo', which can
663 # happen if the user types 'pinfo foo?' at the cmd line.
621 # happen if the user types 'pinfo foo?' at the cmd line.
664 pinfo,qmark1,oname,qmark2 = \
622 pinfo,qmark1,oname,qmark2 = \
665 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
623 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
666 if pinfo or qmark1 or qmark2:
624 if pinfo or qmark1 or qmark2:
667 detail_level = 1
625 detail_level = 1
668 if "*" in oname:
626 if "*" in oname:
669 self.magic_psearch(oname)
627 self.magic_psearch(oname)
670 else:
628 else:
671 self._inspect('pinfo',oname,detail_level=detail_level)
629 self._inspect('pinfo',oname,detail_level=detail_level)
672
630
673 def magic_psearch(self, parameter_s=''):
631 def magic_psearch(self, parameter_s=''):
674 """Search for object in namespaces by wildcard.
632 """Search for object in namespaces by wildcard.
675
633
676 %psearch [options] PATTERN [OBJECT TYPE]
634 %psearch [options] PATTERN [OBJECT TYPE]
677
635
678 Note: ? can be used as a synonym for %psearch, at the beginning or at
636 Note: ? can be used as a synonym for %psearch, at the beginning or at
679 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
637 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
680 rest of the command line must be unchanged (options come first), so
638 rest of the command line must be unchanged (options come first), so
681 for example the following forms are equivalent
639 for example the following forms are equivalent
682
640
683 %psearch -i a* function
641 %psearch -i a* function
684 -i a* function?
642 -i a* function?
685 ?-i a* function
643 ?-i a* function
686
644
687 Arguments:
645 Arguments:
688
646
689 PATTERN
647 PATTERN
690
648
691 where PATTERN is a string containing * as a wildcard similar to its
649 where PATTERN is a string containing * as a wildcard similar to its
692 use in a shell. The pattern is matched in all namespaces on the
650 use in a shell. The pattern is matched in all namespaces on the
693 search path. By default objects starting with a single _ are not
651 search path. By default objects starting with a single _ are not
694 matched, many IPython generated objects have a single
652 matched, many IPython generated objects have a single
695 underscore. The default is case insensitive matching. Matching is
653 underscore. The default is case insensitive matching. Matching is
696 also done on the attributes of objects and not only on the objects
654 also done on the attributes of objects and not only on the objects
697 in a module.
655 in a module.
698
656
699 [OBJECT TYPE]
657 [OBJECT TYPE]
700
658
701 Is the name of a python type from the types module. The name is
659 Is the name of a python type from the types module. The name is
702 given in lowercase without the ending type, ex. StringType is
660 given in lowercase without the ending type, ex. StringType is
703 written string. By adding a type here only objects matching the
661 written string. By adding a type here only objects matching the
704 given type are matched. Using all here makes the pattern match all
662 given type are matched. Using all here makes the pattern match all
705 types (this is the default).
663 types (this is the default).
706
664
707 Options:
665 Options:
708
666
709 -a: makes the pattern match even objects whose names start with a
667 -a: makes the pattern match even objects whose names start with a
710 single underscore. These names are normally ommitted from the
668 single underscore. These names are normally ommitted from the
711 search.
669 search.
712
670
713 -i/-c: make the pattern case insensitive/sensitive. If neither of
671 -i/-c: make the pattern case insensitive/sensitive. If neither of
714 these options is given, the default is read from your ipythonrc
672 these options is given, the default is read from your ipythonrc
715 file. The option name which sets this value is
673 file. The option name which sets this value is
716 'wildcards_case_sensitive'. If this option is not specified in your
674 'wildcards_case_sensitive'. If this option is not specified in your
717 ipythonrc file, IPython's internal default is to do a case sensitive
675 ipythonrc file, IPython's internal default is to do a case sensitive
718 search.
676 search.
719
677
720 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
678 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
721 specifiy can be searched in any of the following namespaces:
679 specifiy can be searched in any of the following namespaces:
722 'builtin', 'user', 'user_global','internal', 'alias', where
680 'builtin', 'user', 'user_global','internal', 'alias', where
723 'builtin' and 'user' are the search defaults. Note that you should
681 'builtin' and 'user' are the search defaults. Note that you should
724 not use quotes when specifying namespaces.
682 not use quotes when specifying namespaces.
725
683
726 'Builtin' contains the python module builtin, 'user' contains all
684 'Builtin' contains the python module builtin, 'user' contains all
727 user data, 'alias' only contain the shell aliases and no python
685 user data, 'alias' only contain the shell aliases and no python
728 objects, 'internal' contains objects used by IPython. The
686 objects, 'internal' contains objects used by IPython. The
729 'user_global' namespace is only used by embedded IPython instances,
687 'user_global' namespace is only used by embedded IPython instances,
730 and it contains module-level globals. You can add namespaces to the
688 and it contains module-level globals. You can add namespaces to the
731 search with -s or exclude them with -e (these options can be given
689 search with -s or exclude them with -e (these options can be given
732 more than once).
690 more than once).
733
691
734 Examples:
692 Examples:
735
693
736 %psearch a* -> objects beginning with an a
694 %psearch a* -> objects beginning with an a
737 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
695 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
738 %psearch a* function -> all functions beginning with an a
696 %psearch a* function -> all functions beginning with an a
739 %psearch re.e* -> objects beginning with an e in module re
697 %psearch re.e* -> objects beginning with an e in module re
740 %psearch r*.e* -> objects that start with e in modules starting in r
698 %psearch r*.e* -> objects that start with e in modules starting in r
741 %psearch r*.* string -> all strings in modules beginning with r
699 %psearch r*.* string -> all strings in modules beginning with r
742
700
743 Case sensitve search:
701 Case sensitve search:
744
702
745 %psearch -c a* list all object beginning with lower case a
703 %psearch -c a* list all object beginning with lower case a
746
704
747 Show objects beginning with a single _:
705 Show objects beginning with a single _:
748
706
749 %psearch -a _* list objects beginning with a single underscore"""
707 %psearch -a _* list objects beginning with a single underscore"""
750
708
751 # default namespaces to be searched
709 # default namespaces to be searched
752 def_search = ['user','builtin']
710 def_search = ['user','builtin']
753
711
754 # Process options/args
712 # Process options/args
755 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
713 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
756 opt = opts.get
714 opt = opts.get
757 shell = self.shell
715 shell = self.shell
758 psearch = shell.inspector.psearch
716 psearch = shell.inspector.psearch
759
717
760 # select case options
718 # select case options
761 if opts.has_key('i'):
719 if opts.has_key('i'):
762 ignore_case = True
720 ignore_case = True
763 elif opts.has_key('c'):
721 elif opts.has_key('c'):
764 ignore_case = False
722 ignore_case = False
765 else:
723 else:
766 ignore_case = not shell.rc.wildcards_case_sensitive
724 ignore_case = not shell.rc.wildcards_case_sensitive
767
725
768 # Build list of namespaces to search from user options
726 # Build list of namespaces to search from user options
769 def_search.extend(opt('s',[]))
727 def_search.extend(opt('s',[]))
770 ns_exclude = ns_exclude=opt('e',[])
728 ns_exclude = ns_exclude=opt('e',[])
771 ns_search = [nm for nm in def_search if nm not in ns_exclude]
729 ns_search = [nm for nm in def_search if nm not in ns_exclude]
772
730
773 # Call the actual search
731 # Call the actual search
774 try:
732 try:
775 psearch(args,shell.ns_table,ns_search,
733 psearch(args,shell.ns_table,ns_search,
776 show_all=opt('a'),ignore_case=ignore_case)
734 show_all=opt('a'),ignore_case=ignore_case)
777 except:
735 except:
778 shell.showtraceback()
736 shell.showtraceback()
779
737
780 def magic_who_ls(self, parameter_s=''):
738 def magic_who_ls(self, parameter_s=''):
781 """Return a sorted list of all interactive variables.
739 """Return a sorted list of all interactive variables.
782
740
783 If arguments are given, only variables of types matching these
741 If arguments are given, only variables of types matching these
784 arguments are returned."""
742 arguments are returned."""
785
743
786 user_ns = self.shell.user_ns
744 user_ns = self.shell.user_ns
787 out = []
745 out = []
788 typelist = parameter_s.split()
746 typelist = parameter_s.split()
789 for i in self.shell.user_ns.keys():
747 for i in self.shell.user_ns.keys():
790 if not (i.startswith('_') or i.startswith('_i')) \
748 if not (i.startswith('_') or i.startswith('_i')) \
791 and not (self.internal_ns.has_key(i) or
749 and not (self.shell.internal_ns.has_key(i) or
792 self.user_config_ns.has_key(i)):
750 self.shell.user_config_ns.has_key(i)):
793 if typelist:
751 if typelist:
794 if type(user_ns[i]).__name__ in typelist:
752 if type(user_ns[i]).__name__ in typelist:
795 out.append(i)
753 out.append(i)
796 else:
754 else:
797 out.append(i)
755 out.append(i)
798 out.sort()
756 out.sort()
799 return out
757 return out
800
758
801 def magic_who(self, parameter_s=''):
759 def magic_who(self, parameter_s=''):
802 """Print all interactive variables, with some minimal formatting.
760 """Print all interactive variables, with some minimal formatting.
803
761
804 If any arguments are given, only variables whose type matches one of
762 If any arguments are given, only variables whose type matches one of
805 these are printed. For example:
763 these are printed. For example:
806
764
807 %who function str
765 %who function str
808
766
809 will only list functions and strings, excluding all other types of
767 will only list functions and strings, excluding all other types of
810 variables. To find the proper type names, simply use type(var) at a
768 variables. To find the proper type names, simply use type(var) at a
811 command line to see how python prints type names. For example:
769 command line to see how python prints type names. For example:
812
770
813 In [1]: type('hello')\\
771 In [1]: type('hello')\\
814 Out[1]: <type 'str'>
772 Out[1]: <type 'str'>
815
773
816 indicates that the type name for strings is 'str'.
774 indicates that the type name for strings is 'str'.
817
775
818 %who always excludes executed names loaded through your configuration
776 %who always excludes executed names loaded through your configuration
819 file and things which are internal to IPython.
777 file and things which are internal to IPython.
820
778
821 This is deliberate, as typically you may load many modules and the
779 This is deliberate, as typically you may load many modules and the
822 purpose of %who is to show you only what you've manually defined."""
780 purpose of %who is to show you only what you've manually defined."""
823
781
824 varlist = self.magic_who_ls(parameter_s)
782 varlist = self.magic_who_ls(parameter_s)
825 if not varlist:
783 if not varlist:
826 print 'Interactive namespace is empty.'
784 print 'Interactive namespace is empty.'
827 return
785 return
828
786
829 # if we have variables, move on...
787 # if we have variables, move on...
830
788
831 # stupid flushing problem: when prompts have no separators, stdout is
789 # stupid flushing problem: when prompts have no separators, stdout is
832 # getting lost. I'm starting to think this is a python bug. I'm having
790 # getting lost. I'm starting to think this is a python bug. I'm having
833 # to force a flush with a print because even a sys.stdout.flush
791 # to force a flush with a print because even a sys.stdout.flush
834 # doesn't seem to do anything!
792 # doesn't seem to do anything!
835
793
836 count = 0
794 count = 0
837 for i in varlist:
795 for i in varlist:
838 print i+'\t',
796 print i+'\t',
839 count += 1
797 count += 1
840 if count > 8:
798 if count > 8:
841 count = 0
799 count = 0
842 print
800 print
843 sys.stdout.flush() # FIXME. Why the hell isn't this flushing???
801 sys.stdout.flush() # FIXME. Why the hell isn't this flushing???
844
802
845 print # well, this does force a flush at the expense of an extra \n
803 print # well, this does force a flush at the expense of an extra \n
846
804
847 def magic_whos(self, parameter_s=''):
805 def magic_whos(self, parameter_s=''):
848 """Like %who, but gives some extra information about each variable.
806 """Like %who, but gives some extra information about each variable.
849
807
850 The same type filtering of %who can be applied here.
808 The same type filtering of %who can be applied here.
851
809
852 For all variables, the type is printed. Additionally it prints:
810 For all variables, the type is printed. Additionally it prints:
853
811
854 - For {},[],(): their length.
812 - For {},[],(): their length.
855
813
856 - For Numeric arrays, a summary with shape, number of elements,
814 - For Numeric arrays, a summary with shape, number of elements,
857 typecode and size in memory.
815 typecode and size in memory.
858
816
859 - Everything else: a string representation, snipping their middle if
817 - Everything else: a string representation, snipping their middle if
860 too long."""
818 too long."""
861
819
862 varnames = self.magic_who_ls(parameter_s)
820 varnames = self.magic_who_ls(parameter_s)
863 if not varnames:
821 if not varnames:
864 print 'Interactive namespace is empty.'
822 print 'Interactive namespace is empty.'
865 return
823 return
866
824
867 # if we have variables, move on...
825 # if we have variables, move on...
868
826
869 # for these types, show len() instead of data:
827 # for these types, show len() instead of data:
870 seq_types = [types.DictType,types.ListType,types.TupleType]
828 seq_types = [types.DictType,types.ListType,types.TupleType]
871
829
872 # for Numeric arrays, display summary info
830 # for Numeric arrays, display summary info
873 try:
831 try:
874 import Numeric
832 import Numeric
875 except ImportError:
833 except ImportError:
876 array_type = None
834 array_type = None
877 else:
835 else:
878 array_type = Numeric.ArrayType.__name__
836 array_type = Numeric.ArrayType.__name__
879
837
880 # Find all variable names and types so we can figure out column sizes
838 # Find all variable names and types so we can figure out column sizes
881 get_vars = lambda i: self.shell.user_ns[i]
839 get_vars = lambda i: self.shell.user_ns[i]
882 type_name = lambda v: type(v).__name__
840 type_name = lambda v: type(v).__name__
883 varlist = map(get_vars,varnames)
841 varlist = map(get_vars,varnames)
884 typelist = map(type_name,varlist)
842 typelist = map(type_name,varlist)
885 # column labels and # of spaces as separator
843 # column labels and # of spaces as separator
886 varlabel = 'Variable'
844 varlabel = 'Variable'
887 typelabel = 'Type'
845 typelabel = 'Type'
888 datalabel = 'Data/Info'
846 datalabel = 'Data/Info'
889 colsep = 3
847 colsep = 3
890 # variable format strings
848 # variable format strings
891 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
849 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
892 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
850 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
893 aformat = "%s: %s elems, type `%s`, %s bytes"
851 aformat = "%s: %s elems, type `%s`, %s bytes"
894 # find the size of the columns to format the output nicely
852 # find the size of the columns to format the output nicely
895 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
853 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
896 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
854 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
897 # table header
855 # table header
898 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
856 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
899 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
857 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
900 # and the table itself
858 # and the table itself
901 kb = 1024
859 kb = 1024
902 Mb = 1048576 # kb**2
860 Mb = 1048576 # kb**2
903 for vname,var,vtype in zip(varnames,varlist,typelist):
861 for vname,var,vtype in zip(varnames,varlist,typelist):
904 print itpl(vformat),
862 print itpl(vformat),
905 if vtype in seq_types:
863 if vtype in seq_types:
906 print len(var)
864 print len(var)
907 elif vtype==array_type:
865 elif vtype==array_type:
908 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
866 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
909 vsize = Numeric.size(var)
867 vsize = Numeric.size(var)
910 vbytes = vsize*var.itemsize()
868 vbytes = vsize*var.itemsize()
911 if vbytes < 100000:
869 if vbytes < 100000:
912 print aformat % (vshape,vsize,var.typecode(),vbytes)
870 print aformat % (vshape,vsize,var.typecode(),vbytes)
913 else:
871 else:
914 print aformat % (vshape,vsize,var.typecode(),vbytes),
872 print aformat % (vshape,vsize,var.typecode(),vbytes),
915 if vbytes < Mb:
873 if vbytes < Mb:
916 print '(%s kb)' % (vbytes/kb,)
874 print '(%s kb)' % (vbytes/kb,)
917 else:
875 else:
918 print '(%s Mb)' % (vbytes/Mb,)
876 print '(%s Mb)' % (vbytes/Mb,)
919 else:
877 else:
920 vstr = str(var)
878 vstr = str(var)
921 if len(vstr) < 50:
879 if len(vstr) < 50:
922 print vstr
880 print vstr
923 else:
881 else:
924 printpl(vfmt_short)
882 printpl(vfmt_short)
925
883
926 def magic_reset(self, parameter_s=''):
884 def magic_reset(self, parameter_s=''):
927 """Resets the namespace by removing all names defined by the user.
885 """Resets the namespace by removing all names defined by the user.
928
886
929 Input/Output history are left around in case you need them."""
887 Input/Output history are left around in case you need them."""
930
888
931 ans = raw_input(
889 ans = raw_input(
932 "Once deleted, variables cannot be recovered. Proceed (y/n)? ")
890 "Once deleted, variables cannot be recovered. Proceed (y/n)? ")
933 if not ans.lower() == 'y':
891 if not ans.lower() == 'y':
934 print 'Nothing done.'
892 print 'Nothing done.'
935 return
893 return
936 user_ns = self.shell.user_ns
894 user_ns = self.shell.user_ns
937 for i in self.magic_who_ls():
895 for i in self.magic_who_ls():
938 del(user_ns[i])
896 del(user_ns[i])
939
897
940 def magic_config(self,parameter_s=''):
898 def magic_config(self,parameter_s=''):
941 """Show IPython's internal configuration."""
899 """Show IPython's internal configuration."""
942
900
943 page('Current configuration structure:\n'+
901 page('Current configuration structure:\n'+
944 pformat(self.shell.rc.dict()))
902 pformat(self.shell.rc.dict()))
945
903
946 def magic_logstart(self,parameter_s=''):
904 def magic_logstart(self,parameter_s=''):
947 """Start logging anywhere in a session.
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 current directory, in 'rotate' mode (see below).
910 current directory, in 'rotate' mode (see below).
953
911
954 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
912 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
955 history up to that point and then continues logging.
913 history up to that point and then continues logging.
956
914
957 %logstart takes a second optional parameter: logging mode. This can be one
915 %logstart takes a second optional parameter: logging mode. This can be one
958 of (note that the modes are given unquoted):\\
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 append: well, that says it.\\
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 rotate: create rotating logs name.1~, name.2~, etc.
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:
966
924
967 valid_modes = qw('over backup append rotate')
925 -o: log also IPython's output. In this mode, all commands which
968 if self.LOG:
926 generate an Out[NN] prompt are recorded to the logfile, right after
969 print 'Logging is already in place. Logfile:',self.LOG
927 their corresponding input line. The output lines are always
970 return
928 prepended with a #[Out]# marker, so that the log remains valid
929 Python code.
971
930
972 par = parameter_s.strip()
931 -t: put timestamps before each input line logged (these are put in
973 if not par:
932 comments)."""
974 logname = self.LOGDEF
933
975 logmode = 'rotate' # use rotate for the auto-generated logs
934 opts,par = self.parse_options(parameter_s,'ot')
976 else:
935 log_output = 'o' in opts
936 timestamp = 't' in opts
937
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 try:
944 try:
978 logname,logmode = par.split()
945 logfname,logmode = par.split()
979 except:
946 except:
980 try:
947 logfname = par
981 logname = par
982 logmode = 'backup'
948 logmode = 'backup'
983 except:
949 else:
984 warn('Usage: %log [log_name [log_mode]]')
950 logfname = logger.logfname
985 return
951 logmode = logger.logmode
986 if not logmode in valid_modes:
952 # put logfname into rc struct as if it had been called on the command
987 warn('Logging NOT activated.\n'
953 # line, so it ends up saved in the log header Save it in case we need
988 'Usage: %log [log_name [log_mode]]\n'
954 # to restore it...
989 'Valid modes: '+str(valid_modes))
955 old_logfile = rc.opts.get('logfile','')
990 return
956 if logfname:
991
957 logfname = os.path.expanduser(logfname)
992 # If we made it this far, I think we're ok:
958 rc.opts.logfile = logfname
993 print 'Activating auto-logging.'
959 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
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.
1003 try:
960 try:
1004 header = str(self.LOGHEAD)
961 started = logger.logstart(logfname,loghead,logmode,
1005 self.create_log(header,logname)
962 log_output,timestamp)
1006 self.logstart(header,logname)
1007 except:
963 except:
1008 self.LOG = '' # we are NOT logging, something went wrong
964 rc.opts.logfile = old_logfile
1009 self.shell.rc.opts.logfile = old_logfile
965 warn("Couldn't start log: %s" % sys.exc_info()[1])
1010 warn("Couldn't start log: "+str(sys.exc_info()[1]))
966 else:
1011 else: # log input history up to this point
967 # log input history up to this point, optionally interleaving
1012 self.logfile.write(self.shell.user_ns['_ih'][1:])
968 # output if requested
1013 self.logfile.flush()
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()
1014
991
1015 def magic_logoff(self,parameter_s=''):
992 def magic_logoff(self,parameter_s=''):
1016 """Temporarily stop logging.
993 """Temporarily stop logging.
1017
994
1018 You must have previously started logging."""
995 You must have previously started logging."""
1019 self.switch_log(0)
996 self.shell.logger.switch_log(0)
1020
997
1021 def magic_logon(self,parameter_s=''):
998 def magic_logon(self,parameter_s=''):
1022 """Restart logging.
999 """Restart logging.
1023
1000
1024 This function is for restarting logging which you've temporarily
1001 This function is for restarting logging which you've temporarily
1025 stopped with %logoff. For starting logging for the first time, you
1002 stopped with %logoff. For starting logging for the first time, you
1026 must use the %logstart function, which allows you to specify an
1003 must use the %logstart function, which allows you to specify an
1027 optional log filename."""
1004 optional log filename."""
1028
1005
1029 self.switch_log(1)
1006 self.shell.logger.switch_log(1)
1030
1007
1031 def magic_logstate(self,parameter_s=''):
1008 def magic_logstate(self,parameter_s=''):
1032 """Print the status of the logging system."""
1009 """Print the status of the logging system."""
1033
1010
1034 self.logstate()
1011 self.shell.logger.logstate()
1035
1012
1036 def magic_pdb(self, parameter_s=''):
1013 def magic_pdb(self, parameter_s=''):
1037 """Control the calling of the pdb interactive debugger.
1014 """Control the calling of the pdb interactive debugger.
1038
1015
1039 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1016 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1040 argument it works as a toggle.
1017 argument it works as a toggle.
1041
1018
1042 When an exception is triggered, IPython can optionally call the
1019 When an exception is triggered, IPython can optionally call the
1043 interactive pdb debugger after the traceback printout. %pdb toggles
1020 interactive pdb debugger after the traceback printout. %pdb toggles
1044 this feature on and off."""
1021 this feature on and off."""
1045
1022
1046 par = parameter_s.strip().lower()
1023 par = parameter_s.strip().lower()
1047
1024
1048 if par:
1025 if par:
1049 try:
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 except KeyError:
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 return
1031 return
1054 else:
1032 else:
1055 self.shell.InteractiveTB.call_pdb = pdb
1033 # toggle
1056 else:
1057 new_pdb = not self.shell.InteractiveTB.call_pdb
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
1035
1036 # set on the shell
1037 self.shell.call_pdb = new_pdb
1065 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1038 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1066
1039
1067
1068
1069 def magic_prun(self, parameter_s ='',user_mode=1,
1040 def magic_prun(self, parameter_s ='',user_mode=1,
1070 opts=None,arg_lst=None,prog_ns=None):
1041 opts=None,arg_lst=None,prog_ns=None):
1071
1042
1072 """Run a statement through the python code profiler.
1043 """Run a statement through the python code profiler.
1073
1044
1074 Usage:\\
1045 Usage:\\
1075 %prun [options] statement
1046 %prun [options] statement
1076
1047
1077 The given statement (which doesn't require quote marks) is run via the
1048 The given statement (which doesn't require quote marks) is run via the
1078 python profiler in a manner similar to the profile.run() function.
1049 python profiler in a manner similar to the profile.run() function.
1079 Namespaces are internally managed to work correctly; profile.run
1050 Namespaces are internally managed to work correctly; profile.run
1080 cannot be used in IPython because it makes certain assumptions about
1051 cannot be used in IPython because it makes certain assumptions about
1081 namespaces which do not hold under IPython.
1052 namespaces which do not hold under IPython.
1082
1053
1083 Options:
1054 Options:
1084
1055
1085 -l <limit>: you can place restrictions on what or how much of the
1056 -l <limit>: you can place restrictions on what or how much of the
1086 profile gets printed. The limit value can be:
1057 profile gets printed. The limit value can be:
1087
1058
1088 * A string: only information for function names containing this string
1059 * A string: only information for function names containing this string
1089 is printed.
1060 is printed.
1090
1061
1091 * An integer: only these many lines are printed.
1062 * An integer: only these many lines are printed.
1092
1063
1093 * A float (between 0 and 1): this fraction of the report is printed
1064 * A float (between 0 and 1): this fraction of the report is printed
1094 (for example, use a limit of 0.4 to see the topmost 40% only).
1065 (for example, use a limit of 0.4 to see the topmost 40% only).
1095
1066
1096 You can combine several limits with repeated use of the option. For
1067 You can combine several limits with repeated use of the option. For
1097 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1068 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1098 information about class constructors.
1069 information about class constructors.
1099
1070
1100 -r: return the pstats.Stats object generated by the profiling. This
1071 -r: return the pstats.Stats object generated by the profiling. This
1101 object has all the information about the profile in it, and you can
1072 object has all the information about the profile in it, and you can
1102 later use it for further analysis or in other functions.
1073 later use it for further analysis or in other functions.
1103
1074
1104 Since magic functions have a particular form of calling which prevents
1075 Since magic functions have a particular form of calling which prevents
1105 you from writing something like:\\
1076 you from writing something like:\\
1106 In [1]: p = %prun -r print 4 # invalid!\\
1077 In [1]: p = %prun -r print 4 # invalid!\\
1107 you must instead use IPython's automatic variables to assign this:\\
1078 you must instead use IPython's automatic variables to assign this:\\
1108 In [1]: %prun -r print 4 \\
1079 In [1]: %prun -r print 4 \\
1109 Out[1]: <pstats.Stats instance at 0x8222cec>\\
1080 Out[1]: <pstats.Stats instance at 0x8222cec>\\
1110 In [2]: stats = _
1081 In [2]: stats = _
1111
1082
1112 If you really need to assign this value via an explicit function call,
1083 If you really need to assign this value via an explicit function call,
1113 you can always tap directly into the true name of the magic function
1084 you can always tap directly into the true name of the magic function
1114 by using the ipmagic function (which IPython automatically adds to the
1085 by using the ipmagic function (which IPython automatically adds to the
1115 builtins):\\
1086 builtins):\\
1116 In [3]: stats = ipmagic('prun','-r print 4')
1087 In [3]: stats = ipmagic('prun','-r print 4')
1117
1088
1118 You can type ipmagic? for more details on ipmagic.
1089 You can type ipmagic? for more details on ipmagic.
1119
1090
1120 -s <key>: sort profile by given key. You can provide more than one key
1091 -s <key>: sort profile by given key. You can provide more than one key
1121 by using the option several times: '-s key1 -s key2 -s key3...'. The
1092 by using the option several times: '-s key1 -s key2 -s key3...'. The
1122 default sorting key is 'time'.
1093 default sorting key is 'time'.
1123
1094
1124 The following is copied verbatim from the profile documentation
1095 The following is copied verbatim from the profile documentation
1125 referenced below:
1096 referenced below:
1126
1097
1127 When more than one key is provided, additional keys are used as
1098 When more than one key is provided, additional keys are used as
1128 secondary criteria when the there is equality in all keys selected
1099 secondary criteria when the there is equality in all keys selected
1129 before them.
1100 before them.
1130
1101
1131 Abbreviations can be used for any key names, as long as the
1102 Abbreviations can be used for any key names, as long as the
1132 abbreviation is unambiguous. The following are the keys currently
1103 abbreviation is unambiguous. The following are the keys currently
1133 defined:
1104 defined:
1134
1105
1135 Valid Arg Meaning\\
1106 Valid Arg Meaning\\
1136 "calls" call count\\
1107 "calls" call count\\
1137 "cumulative" cumulative time\\
1108 "cumulative" cumulative time\\
1138 "file" file name\\
1109 "file" file name\\
1139 "module" file name\\
1110 "module" file name\\
1140 "pcalls" primitive call count\\
1111 "pcalls" primitive call count\\
1141 "line" line number\\
1112 "line" line number\\
1142 "name" function name\\
1113 "name" function name\\
1143 "nfl" name/file/line\\
1114 "nfl" name/file/line\\
1144 "stdname" standard name\\
1115 "stdname" standard name\\
1145 "time" internal time
1116 "time" internal time
1146
1117
1147 Note that all sorts on statistics are in descending order (placing
1118 Note that all sorts on statistics are in descending order (placing
1148 most time consuming items first), where as name, file, and line number
1119 most time consuming items first), where as name, file, and line number
1149 searches are in ascending order (i.e., alphabetical). The subtle
1120 searches are in ascending order (i.e., alphabetical). The subtle
1150 distinction between "nfl" and "stdname" is that the standard name is a
1121 distinction between "nfl" and "stdname" is that the standard name is a
1151 sort of the name as printed, which means that the embedded line
1122 sort of the name as printed, which means that the embedded line
1152 numbers get compared in an odd way. For example, lines 3, 20, and 40
1123 numbers get compared in an odd way. For example, lines 3, 20, and 40
1153 would (if the file names were the same) appear in the string order
1124 would (if the file names were the same) appear in the string order
1154 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1125 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1155 line numbers. In fact, sort_stats("nfl") is the same as
1126 line numbers. In fact, sort_stats("nfl") is the same as
1156 sort_stats("name", "file", "line").
1127 sort_stats("name", "file", "line").
1157
1128
1158 -T <filename>: save profile results as shown on screen to a text
1129 -T <filename>: save profile results as shown on screen to a text
1159 file. The profile is still shown on screen.
1130 file. The profile is still shown on screen.
1160
1131
1161 -D <filename>: save (via dump_stats) profile statistics to given
1132 -D <filename>: save (via dump_stats) profile statistics to given
1162 filename. This data is in a format understod by the pstats module, and
1133 filename. This data is in a format understod by the pstats module, and
1163 is generated by a call to the dump_stats() method of profile
1134 is generated by a call to the dump_stats() method of profile
1164 objects. The profile is still shown on screen.
1135 objects. The profile is still shown on screen.
1165
1136
1166 If you want to run complete programs under the profiler's control, use
1137 If you want to run complete programs under the profiler's control, use
1167 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1138 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1168 contains profiler specific options as described here.
1139 contains profiler specific options as described here.
1169
1140
1170 You can read the complete documentation for the profile module with:\\
1141 You can read the complete documentation for the profile module with:\\
1171 In [1]: import profile; profile.help() """
1142 In [1]: import profile; profile.help() """
1172
1143
1173 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1144 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1174 # protect user quote marks
1145 # protect user quote marks
1175 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1146 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1176
1147
1177 if user_mode: # regular user call
1148 if user_mode: # regular user call
1178 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1149 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1179 list_all=1)
1150 list_all=1)
1180 namespace = self.shell.user_ns
1151 namespace = self.shell.user_ns
1181 else: # called to run a program by %run -p
1152 else: # called to run a program by %run -p
1182 try:
1153 try:
1183 filename = get_py_filename(arg_lst[0])
1154 filename = get_py_filename(arg_lst[0])
1184 except IOError,msg:
1155 except IOError,msg:
1185 error(msg)
1156 error(msg)
1186 return
1157 return
1187
1158
1188 arg_str = 'execfile(filename,prog_ns)'
1159 arg_str = 'execfile(filename,prog_ns)'
1189 namespace = locals()
1160 namespace = locals()
1190
1161
1191 opts.merge(opts_def)
1162 opts.merge(opts_def)
1192
1163
1193 prof = profile.Profile()
1164 prof = profile.Profile()
1194 try:
1165 try:
1195 prof = prof.runctx(arg_str,namespace,namespace)
1166 prof = prof.runctx(arg_str,namespace,namespace)
1196 sys_exit = ''
1167 sys_exit = ''
1197 except SystemExit:
1168 except SystemExit:
1198 sys_exit = """*** SystemExit exception caught in code being profiled."""
1169 sys_exit = """*** SystemExit exception caught in code being profiled."""
1199
1170
1200 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1171 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1201
1172
1202 lims = opts.l
1173 lims = opts.l
1203 if lims:
1174 if lims:
1204 lims = [] # rebuild lims with ints/floats/strings
1175 lims = [] # rebuild lims with ints/floats/strings
1205 for lim in opts.l:
1176 for lim in opts.l:
1206 try:
1177 try:
1207 lims.append(int(lim))
1178 lims.append(int(lim))
1208 except ValueError:
1179 except ValueError:
1209 try:
1180 try:
1210 lims.append(float(lim))
1181 lims.append(float(lim))
1211 except ValueError:
1182 except ValueError:
1212 lims.append(lim)
1183 lims.append(lim)
1213
1184
1214 # trap output
1185 # trap output
1215 sys_stdout = sys.stdout
1186 sys_stdout = sys.stdout
1216 stdout_trap = StringIO()
1187 stdout_trap = StringIO()
1217 try:
1188 try:
1218 sys.stdout = stdout_trap
1189 sys.stdout = stdout_trap
1219 stats.print_stats(*lims)
1190 stats.print_stats(*lims)
1220 finally:
1191 finally:
1221 sys.stdout = sys_stdout
1192 sys.stdout = sys_stdout
1222 output = stdout_trap.getvalue()
1193 output = stdout_trap.getvalue()
1223 output = output.rstrip()
1194 output = output.rstrip()
1224
1195
1225 page(output,screen_lines=self.shell.rc.screen_length)
1196 page(output,screen_lines=self.shell.rc.screen_length)
1226 print sys_exit,
1197 print sys_exit,
1227
1198
1228 dump_file = opts.D[0]
1199 dump_file = opts.D[0]
1229 text_file = opts.T[0]
1200 text_file = opts.T[0]
1230 if dump_file:
1201 if dump_file:
1231 prof.dump_stats(dump_file)
1202 prof.dump_stats(dump_file)
1232 print '\n*** Profile stats marshalled to file',\
1203 print '\n*** Profile stats marshalled to file',\
1233 `dump_file`+'.',sys_exit
1204 `dump_file`+'.',sys_exit
1234 if text_file:
1205 if text_file:
1235 file(text_file,'w').write(output)
1206 file(text_file,'w').write(output)
1236 print '\n*** Profile printout saved to text file',\
1207 print '\n*** Profile printout saved to text file',\
1237 `text_file`+'.',sys_exit
1208 `text_file`+'.',sys_exit
1238
1209
1239 if opts.has_key('r'):
1210 if opts.has_key('r'):
1240 return stats
1211 return stats
1241 else:
1212 else:
1242 return None
1213 return None
1243
1214
1244 def magic_run(self, parameter_s ='',runner=None):
1215 def magic_run(self, parameter_s ='',runner=None):
1245 """Run the named file inside IPython as a program.
1216 """Run the named file inside IPython as a program.
1246
1217
1247 Usage:\\
1218 Usage:\\
1248 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1219 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1249
1220
1250 Parameters after the filename are passed as command-line arguments to
1221 Parameters after the filename are passed as command-line arguments to
1251 the program (put in sys.argv). Then, control returns to IPython's
1222 the program (put in sys.argv). Then, control returns to IPython's
1252 prompt.
1223 prompt.
1253
1224
1254 This is similar to running at a system prompt:\\
1225 This is similar to running at a system prompt:\\
1255 $ python file args\\
1226 $ python file args\\
1256 but with the advantage of giving you IPython's tracebacks, and of
1227 but with the advantage of giving you IPython's tracebacks, and of
1257 loading all variables into your interactive namespace for further use
1228 loading all variables into your interactive namespace for further use
1258 (unless -p is used, see below).
1229 (unless -p is used, see below).
1259
1230
1260 The file is executed in a namespace initially consisting only of
1231 The file is executed in a namespace initially consisting only of
1261 __name__=='__main__' and sys.argv constructed as indicated. It thus
1232 __name__=='__main__' and sys.argv constructed as indicated. It thus
1262 sees its environment as if it were being run as a stand-alone
1233 sees its environment as if it were being run as a stand-alone
1263 program. But after execution, the IPython interactive namespace gets
1234 program. But after execution, the IPython interactive namespace gets
1264 updated with all variables defined in the program (except for __name__
1235 updated with all variables defined in the program (except for __name__
1265 and sys.argv). This allows for very convenient loading of code for
1236 and sys.argv). This allows for very convenient loading of code for
1266 interactive work, while giving each program a 'clean sheet' to run in.
1237 interactive work, while giving each program a 'clean sheet' to run in.
1267
1238
1268 Options:
1239 Options:
1269
1240
1270 -n: __name__ is NOT set to '__main__', but to the running file's name
1241 -n: __name__ is NOT set to '__main__', but to the running file's name
1271 without extension (as python does under import). This allows running
1242 without extension (as python does under import). This allows running
1272 scripts and reloading the definitions in them without calling code
1243 scripts and reloading the definitions in them without calling code
1273 protected by an ' if __name__ == "__main__" ' clause.
1244 protected by an ' if __name__ == "__main__" ' clause.
1274
1245
1275 -i: run the file in IPython's namespace instead of an empty one. This
1246 -i: run the file in IPython's namespace instead of an empty one. This
1276 is useful if you are experimenting with code written in a text editor
1247 is useful if you are experimenting with code written in a text editor
1277 which depends on variables defined interactively.
1248 which depends on variables defined interactively.
1278
1249
1279 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1250 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1280 being run. This is particularly useful if IPython is being used to
1251 being run. This is particularly useful if IPython is being used to
1281 run unittests, which always exit with a sys.exit() call. In such
1252 run unittests, which always exit with a sys.exit() call. In such
1282 cases you are interested in the output of the test results, not in
1253 cases you are interested in the output of the test results, not in
1283 seeing a traceback of the unittest module.
1254 seeing a traceback of the unittest module.
1284
1255
1285 -t: print timing information at the end of the run. IPython will give
1256 -t: print timing information at the end of the run. IPython will give
1286 you an estimated CPU time consumption for your script, which under
1257 you an estimated CPU time consumption for your script, which under
1287 Unix uses the resource module to avoid the wraparound problems of
1258 Unix uses the resource module to avoid the wraparound problems of
1288 time.clock(). Under Unix, an estimate of time spent on system tasks
1259 time.clock(). Under Unix, an estimate of time spent on system tasks
1289 is also given (for Windows platforms this is reported as 0.0).
1260 is also given (for Windows platforms this is reported as 0.0).
1290
1261
1291 If -t is given, an additional -N<N> option can be given, where <N>
1262 If -t is given, an additional -N<N> option can be given, where <N>
1292 must be an integer indicating how many times you want the script to
1263 must be an integer indicating how many times you want the script to
1293 run. The final timing report will include total and per run results.
1264 run. The final timing report will include total and per run results.
1294
1265
1295 For example (testing the script uniq_stable.py):
1266 For example (testing the script uniq_stable.py):
1296
1267
1297 In [1]: run -t uniq_stable
1268 In [1]: run -t uniq_stable
1298
1269
1299 IPython CPU timings (estimated):\\
1270 IPython CPU timings (estimated):\\
1300 User : 0.19597 s.\\
1271 User : 0.19597 s.\\
1301 System: 0.0 s.\\
1272 System: 0.0 s.\\
1302
1273
1303 In [2]: run -t -N5 uniq_stable
1274 In [2]: run -t -N5 uniq_stable
1304
1275
1305 IPython CPU timings (estimated):\\
1276 IPython CPU timings (estimated):\\
1306 Total runs performed: 5\\
1277 Total runs performed: 5\\
1307 Times : Total Per run\\
1278 Times : Total Per run\\
1308 User : 0.910862 s, 0.1821724 s.\\
1279 User : 0.910862 s, 0.1821724 s.\\
1309 System: 0.0 s, 0.0 s.
1280 System: 0.0 s, 0.0 s.
1310
1281
1311 -d: run your program under the control of pdb, the Python debugger.
1282 -d: run your program under the control of pdb, the Python debugger.
1312 This allows you to execute your program step by step, watch variables,
1283 This allows you to execute your program step by step, watch variables,
1313 etc. Internally, what IPython does is similar to calling:
1284 etc. Internally, what IPython does is similar to calling:
1314
1285
1315 pdb.run('execfile("YOURFILENAME")')
1286 pdb.run('execfile("YOURFILENAME")')
1316
1287
1317 with a breakpoint set on line 1 of your file. You can change the line
1288 with a breakpoint set on line 1 of your file. You can change the line
1318 number for this automatic breakpoint to be <N> by using the -bN option
1289 number for this automatic breakpoint to be <N> by using the -bN option
1319 (where N must be an integer). For example:
1290 (where N must be an integer). For example:
1320
1291
1321 %run -d -b40 myscript
1292 %run -d -b40 myscript
1322
1293
1323 will set the first breakpoint at line 40 in myscript.py. Note that
1294 will set the first breakpoint at line 40 in myscript.py. Note that
1324 the first breakpoint must be set on a line which actually does
1295 the first breakpoint must be set on a line which actually does
1325 something (not a comment or docstring) for it to stop execution.
1296 something (not a comment or docstring) for it to stop execution.
1326
1297
1327 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1298 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1328 first enter 'c' (without qoutes) to start execution up to the first
1299 first enter 'c' (without qoutes) to start execution up to the first
1329 breakpoint.
1300 breakpoint.
1330
1301
1331 Entering 'help' gives information about the use of the debugger. You
1302 Entering 'help' gives information about the use of the debugger. You
1332 can easily see pdb's full documentation with "import pdb;pdb.help()"
1303 can easily see pdb's full documentation with "import pdb;pdb.help()"
1333 at a prompt.
1304 at a prompt.
1334
1305
1335 -p: run program under the control of the Python profiler module (which
1306 -p: run program under the control of the Python profiler module (which
1336 prints a detailed report of execution times, function calls, etc).
1307 prints a detailed report of execution times, function calls, etc).
1337
1308
1338 You can pass other options after -p which affect the behavior of the
1309 You can pass other options after -p which affect the behavior of the
1339 profiler itself. See the docs for %prun for details.
1310 profiler itself. See the docs for %prun for details.
1340
1311
1341 In this mode, the program's variables do NOT propagate back to the
1312 In this mode, the program's variables do NOT propagate back to the
1342 IPython interactive namespace (because they remain in the namespace
1313 IPython interactive namespace (because they remain in the namespace
1343 where the profiler executes them).
1314 where the profiler executes them).
1344
1315
1345 Internally this triggers a call to %prun, see its documentation for
1316 Internally this triggers a call to %prun, see its documentation for
1346 details on the options available specifically for profiling."""
1317 details on the options available specifically for profiling."""
1347
1318
1348 # get arguments and set sys.argv for program to be run.
1319 # get arguments and set sys.argv for program to be run.
1349 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1320 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1350 mode='list',list_all=1)
1321 mode='list',list_all=1)
1351
1322
1352 try:
1323 try:
1353 filename = get_py_filename(arg_lst[0])
1324 filename = get_py_filename(arg_lst[0])
1354 except IndexError:
1325 except IndexError:
1355 warn('you must provide at least a filename.')
1326 warn('you must provide at least a filename.')
1356 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1327 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1357 return
1328 return
1358 except IOError,msg:
1329 except IOError,msg:
1359 error(msg)
1330 error(msg)
1360 return
1331 return
1361
1332
1362 # Control the response to exit() calls made by the script being run
1333 # Control the response to exit() calls made by the script being run
1363 exit_ignore = opts.has_key('e')
1334 exit_ignore = opts.has_key('e')
1364
1335
1365 # Make sure that the running script gets a proper sys.argv as if it
1336 # Make sure that the running script gets a proper sys.argv as if it
1366 # were run from a system shell.
1337 # were run from a system shell.
1367 save_argv = sys.argv # save it for later restoring
1338 save_argv = sys.argv # save it for later restoring
1368 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1339 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1369
1340
1370 if opts.has_key('i'):
1341 if opts.has_key('i'):
1371 prog_ns = self.shell.user_ns
1342 prog_ns = self.shell.user_ns
1372 __name__save = self.shell.user_ns['__name__']
1343 __name__save = self.shell.user_ns['__name__']
1373 prog_ns['__name__'] = '__main__'
1344 prog_ns['__name__'] = '__main__'
1374 else:
1345 else:
1375 if opts.has_key('n'):
1346 if opts.has_key('n'):
1376 name = os.path.splitext(os.path.basename(filename))[0]
1347 name = os.path.splitext(os.path.basename(filename))[0]
1377 else:
1348 else:
1378 name = '__main__'
1349 name = '__main__'
1379 prog_ns = {'__name__':name}
1350 prog_ns = {'__name__':name}
1380
1351
1381 # pickle fix. See iplib for an explanation
1352 # pickle fix. See iplib for an explanation
1382 sys.modules[prog_ns['__name__']] = FakeModule(prog_ns)
1353 sys.modules[prog_ns['__name__']] = FakeModule(prog_ns)
1383
1354
1384 stats = None
1355 stats = None
1385 try:
1356 try:
1386 if opts.has_key('p'):
1357 if opts.has_key('p'):
1387 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1358 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1388 else:
1359 else:
1389 if opts.has_key('d'):
1360 if opts.has_key('d'):
1390 deb = Debugger.Pdb(self.shell.rc.colors)
1361 deb = Debugger.Pdb(self.shell.rc.colors)
1391 # reset Breakpoint state, which is moronically kept
1362 # reset Breakpoint state, which is moronically kept
1392 # in a class
1363 # in a class
1393 bdb.Breakpoint.next = 1
1364 bdb.Breakpoint.next = 1
1394 bdb.Breakpoint.bplist = {}
1365 bdb.Breakpoint.bplist = {}
1395 bdb.Breakpoint.bpbynumber = [None]
1366 bdb.Breakpoint.bpbynumber = [None]
1396 # Set an initial breakpoint to stop execution
1367 # Set an initial breakpoint to stop execution
1397 maxtries = 10
1368 maxtries = 10
1398 bp = int(opts.get('b',[1])[0])
1369 bp = int(opts.get('b',[1])[0])
1399 checkline = deb.checkline(filename,bp)
1370 checkline = deb.checkline(filename,bp)
1400 if not checkline:
1371 if not checkline:
1401 for bp in range(bp+1,bp+maxtries+1):
1372 for bp in range(bp+1,bp+maxtries+1):
1402 if deb.checkline(filename,bp):
1373 if deb.checkline(filename,bp):
1403 break
1374 break
1404 else:
1375 else:
1405 msg = ("\nI failed to find a valid line to set "
1376 msg = ("\nI failed to find a valid line to set "
1406 "a breakpoint\n"
1377 "a breakpoint\n"
1407 "after trying up to line: %s.\n"
1378 "after trying up to line: %s.\n"
1408 "Please set a valid breakpoint manually "
1379 "Please set a valid breakpoint manually "
1409 "with the -b option." % bp)
1380 "with the -b option." % bp)
1410 error(msg)
1381 error(msg)
1411 return
1382 return
1412 # if we find a good linenumber, set the breakpoint
1383 # if we find a good linenumber, set the breakpoint
1413 deb.do_break('%s:%s' % (filename,bp))
1384 deb.do_break('%s:%s' % (filename,bp))
1414 # Start file run
1385 # Start file run
1415 print "NOTE: Enter 'c' at the",
1386 print "NOTE: Enter 'c' at the",
1416 print "ipdb> prompt to start your script."
1387 print "ipdb> prompt to start your script."
1417 try:
1388 try:
1418 deb.run('execfile("%s")' % filename,prog_ns)
1389 deb.run('execfile("%s")' % filename,prog_ns)
1419 except:
1390 except:
1420 etype, value, tb = sys.exc_info()
1391 etype, value, tb = sys.exc_info()
1421 # Skip three frames in the traceback: the %run one,
1392 # Skip three frames in the traceback: the %run one,
1422 # one inside bdb.py, and the command-line typed by the
1393 # one inside bdb.py, and the command-line typed by the
1423 # user (run by exec in pdb itself).
1394 # user (run by exec in pdb itself).
1424 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1395 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1425 else:
1396 else:
1426 if runner is None:
1397 if runner is None:
1427 runner = self.shell.safe_execfile
1398 runner = self.shell.safe_execfile
1428 if opts.has_key('t'):
1399 if opts.has_key('t'):
1429 try:
1400 try:
1430 nruns = int(opts['N'][0])
1401 nruns = int(opts['N'][0])
1431 if nruns < 1:
1402 if nruns < 1:
1432 error('Number of runs must be >=1')
1403 error('Number of runs must be >=1')
1433 return
1404 return
1434 except (KeyError):
1405 except (KeyError):
1435 nruns = 1
1406 nruns = 1
1436 if nruns == 1:
1407 if nruns == 1:
1437 t0 = clock2()
1408 t0 = clock2()
1438 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1409 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1439 t1 = clock2()
1410 t1 = clock2()
1440 t_usr = t1[0]-t0[0]
1411 t_usr = t1[0]-t0[0]
1441 t_sys = t1[1]-t1[1]
1412 t_sys = t1[1]-t1[1]
1442 print "\nIPython CPU timings (estimated):"
1413 print "\nIPython CPU timings (estimated):"
1443 print " User : %10s s." % t_usr
1414 print " User : %10s s." % t_usr
1444 print " System: %10s s." % t_sys
1415 print " System: %10s s." % t_sys
1445 else:
1416 else:
1446 runs = range(nruns)
1417 runs = range(nruns)
1447 t0 = clock2()
1418 t0 = clock2()
1448 for nr in runs:
1419 for nr in runs:
1449 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1420 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1450 t1 = clock2()
1421 t1 = clock2()
1451 t_usr = t1[0]-t0[0]
1422 t_usr = t1[0]-t0[0]
1452 t_sys = t1[1]-t1[1]
1423 t_sys = t1[1]-t1[1]
1453 print "\nIPython CPU timings (estimated):"
1424 print "\nIPython CPU timings (estimated):"
1454 print "Total runs performed:",nruns
1425 print "Total runs performed:",nruns
1455 print " Times : %10s %10s" % ('Total','Per run')
1426 print " Times : %10s %10s" % ('Total','Per run')
1456 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1427 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1457 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1428 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1458
1429
1459 else:
1430 else:
1460 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1431 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1461 if opts.has_key('i'):
1432 if opts.has_key('i'):
1462 self.shell.user_ns['__name__'] = __name__save
1433 self.shell.user_ns['__name__'] = __name__save
1463 else:
1434 else:
1464 # update IPython interactive namespace
1435 # update IPython interactive namespace
1465 del prog_ns['__name__']
1436 del prog_ns['__name__']
1466 self.shell.user_ns.update(prog_ns)
1437 self.shell.user_ns.update(prog_ns)
1467 finally:
1438 finally:
1468 sys.argv = save_argv
1439 sys.argv = save_argv
1469 return stats
1440 return stats
1470
1441
1471 def magic_runlog(self, parameter_s =''):
1442 def magic_runlog(self, parameter_s =''):
1472 """Run files as logs.
1443 """Run files as logs.
1473
1444
1474 Usage:\\
1445 Usage:\\
1475 %runlog file1 file2 ...
1446 %runlog file1 file2 ...
1476
1447
1477 Run the named files (treating them as log files) in sequence inside
1448 Run the named files (treating them as log files) in sequence inside
1478 the interpreter, and return to the prompt. This is much slower than
1449 the interpreter, and return to the prompt. This is much slower than
1479 %run because each line is executed in a try/except block, but it
1450 %run because each line is executed in a try/except block, but it
1480 allows running files with syntax errors in them.
1451 allows running files with syntax errors in them.
1481
1452
1482 Normally IPython will guess when a file is one of its own logfiles, so
1453 Normally IPython will guess when a file is one of its own logfiles, so
1483 you can typically use %run even for logs. This shorthand allows you to
1454 you can typically use %run even for logs. This shorthand allows you to
1484 force any file to be treated as a log file."""
1455 force any file to be treated as a log file."""
1485
1456
1486 for f in parameter_s.split():
1457 for f in parameter_s.split():
1487 self.shell.safe_execfile(f,self.shell.user_ns,
1458 self.shell.safe_execfile(f,self.shell.user_ns,
1488 self.shell.user_ns,islog=1)
1459 self.shell.user_ns,islog=1)
1489
1460
1490 def magic_time(self,parameter_s = ''):
1461 def magic_time(self,parameter_s = ''):
1491 """Time execution of a Python statement or expression.
1462 """Time execution of a Python statement or expression.
1492
1463
1493 The CPU and wall clock times are printed, and the value of the
1464 The CPU and wall clock times are printed, and the value of the
1494 expression (if any) is returned. Note that under Win32, system time
1465 expression (if any) is returned. Note that under Win32, system time
1495 is always reported as 0, since it can not be measured.
1466 is always reported as 0, since it can not be measured.
1496
1467
1497 This function provides very basic timing functionality. In Python
1468 This function provides very basic timing functionality. In Python
1498 2.3, the timeit module offers more control and sophistication, but for
1469 2.3, the timeit module offers more control and sophistication, but for
1499 now IPython supports Python 2.2, so we can not rely on timeit being
1470 now IPython supports Python 2.2, so we can not rely on timeit being
1500 present.
1471 present.
1501
1472
1502 Some examples:
1473 Some examples:
1503
1474
1504 In [1]: time 2**128
1475 In [1]: time 2**128
1505 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1476 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1506 Wall time: 0.00
1477 Wall time: 0.00
1507 Out[1]: 340282366920938463463374607431768211456L
1478 Out[1]: 340282366920938463463374607431768211456L
1508
1479
1509 In [2]: n = 1000000
1480 In [2]: n = 1000000
1510
1481
1511 In [3]: time sum(range(n))
1482 In [3]: time sum(range(n))
1512 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1483 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1513 Wall time: 1.37
1484 Wall time: 1.37
1514 Out[3]: 499999500000L
1485 Out[3]: 499999500000L
1515
1486
1516 In [4]: time print 'hello world'
1487 In [4]: time print 'hello world'
1517 hello world
1488 hello world
1518 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1489 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1519 Wall time: 0.00
1490 Wall time: 0.00
1520 """
1491 """
1521
1492
1522 # fail immediately if the given expression can't be compiled
1493 # fail immediately if the given expression can't be compiled
1523 try:
1494 try:
1524 mode = 'eval'
1495 mode = 'eval'
1525 code = compile(parameter_s,'<timed eval>',mode)
1496 code = compile(parameter_s,'<timed eval>',mode)
1526 except SyntaxError:
1497 except SyntaxError:
1527 mode = 'exec'
1498 mode = 'exec'
1528 code = compile(parameter_s,'<timed exec>',mode)
1499 code = compile(parameter_s,'<timed exec>',mode)
1529 # skew measurement as little as possible
1500 # skew measurement as little as possible
1530 glob = self.shell.user_ns
1501 glob = self.shell.user_ns
1531 clk = clock2
1502 clk = clock2
1532 wtime = time.time
1503 wtime = time.time
1533 # time execution
1504 # time execution
1534 wall_st = wtime()
1505 wall_st = wtime()
1535 if mode=='eval':
1506 if mode=='eval':
1536 st = clk()
1507 st = clk()
1537 out = eval(code,glob)
1508 out = eval(code,glob)
1538 end = clk()
1509 end = clk()
1539 else:
1510 else:
1540 st = clk()
1511 st = clk()
1541 exec code in glob
1512 exec code in glob
1542 end = clk()
1513 end = clk()
1543 out = None
1514 out = None
1544 wall_end = wtime()
1515 wall_end = wtime()
1545 # Compute actual times and report
1516 # Compute actual times and report
1546 wall_time = wall_end-wall_st
1517 wall_time = wall_end-wall_st
1547 cpu_user = end[0]-st[0]
1518 cpu_user = end[0]-st[0]
1548 cpu_sys = end[1]-st[1]
1519 cpu_sys = end[1]-st[1]
1549 cpu_tot = cpu_user+cpu_sys
1520 cpu_tot = cpu_user+cpu_sys
1550 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1521 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1551 (cpu_user,cpu_sys,cpu_tot)
1522 (cpu_user,cpu_sys,cpu_tot)
1552 print "Wall time: %.2f" % wall_time
1523 print "Wall time: %.2f" % wall_time
1553 return out
1524 return out
1554
1525
1555 def magic_macro(self,parameter_s = ''):
1526 def magic_macro(self,parameter_s = ''):
1556 """Define a set of input lines as a macro for future re-execution.
1527 """Define a set of input lines as a macro for future re-execution.
1557
1528
1558 Usage:\\
1529 Usage:\\
1559 %macro name n1:n2 n3:n4 ... n5 .. n6 ...
1530 %macro name n1:n2 n3:n4 ... n5 .. n6 ...
1560
1531
1561 This will define a global variable called `name` which is a string
1532 This will define a global variable called `name` which is a string
1562 made of joining the slices and lines you specify (n1,n2,... numbers
1533 made of joining the slices and lines you specify (n1,n2,... numbers
1563 above) from your input history into a single string. This variable
1534 above) from your input history into a single string. This variable
1564 acts like an automatic function which re-executes those lines as if
1535 acts like an automatic function which re-executes those lines as if
1565 you had typed them. You just type 'name' at the prompt and the code
1536 you had typed them. You just type 'name' at the prompt and the code
1566 executes.
1537 executes.
1567
1538
1568 Note that the slices use the standard Python slicing notation (5:8
1539 Note that the slices use the standard Python slicing notation (5:8
1569 means include lines numbered 5,6,7).
1540 means include lines numbered 5,6,7).
1570
1541
1571 For example, if your history contains (%hist prints it):
1542 For example, if your history contains (%hist prints it):
1572
1543
1573 44: x=1\\
1544 44: x=1\\
1574 45: y=3\\
1545 45: y=3\\
1575 46: z=x+y\\
1546 46: z=x+y\\
1576 47: print x\\
1547 47: print x\\
1577 48: a=5\\
1548 48: a=5\\
1578 49: print 'x',x,'y',y\\
1549 49: print 'x',x,'y',y\\
1579
1550
1580 you can create a macro with lines 44 through 47 (included) and line 49
1551 you can create a macro with lines 44 through 47 (included) and line 49
1581 called my_macro with:
1552 called my_macro with:
1582
1553
1583 In [51]: %macro my_macro 44:48 49
1554 In [51]: %macro my_macro 44:48 49
1584
1555
1585 Now, typing `my_macro` (without quotes) will re-execute all this code
1556 Now, typing `my_macro` (without quotes) will re-execute all this code
1586 in one pass.
1557 in one pass.
1587
1558
1588 You don't need to give the line-numbers in order, and any given line
1559 You don't need to give the line-numbers in order, and any given line
1589 number can appear multiple times. You can assemble macros with any
1560 number can appear multiple times. You can assemble macros with any
1590 lines from your input history in any order.
1561 lines from your input history in any order.
1591
1562
1592 The macro is a simple object which holds its value in an attribute,
1563 The macro is a simple object which holds its value in an attribute,
1593 but IPython's display system checks for macros and executes them as
1564 but IPython's display system checks for macros and executes them as
1594 code instead of printing them when you type their name.
1565 code instead of printing them when you type their name.
1595
1566
1596 You can view a macro's contents by explicitly printing it with:
1567 You can view a macro's contents by explicitly printing it with:
1597
1568
1598 'print macro_name'.
1569 'print macro_name'.
1599
1570
1600 For one-off cases which DON'T contain magic function calls in them you
1571 For one-off cases which DON'T contain magic function calls in them you
1601 can obtain similar results by explicitly executing slices from your
1572 can obtain similar results by explicitly executing slices from your
1602 input history with:
1573 input history with:
1603
1574
1604 In [60]: exec In[44:48]+In[49]"""
1575 In [60]: exec In[44:48]+In[49]"""
1605
1576
1606 args = parameter_s.split()
1577 args = parameter_s.split()
1607 name,ranges = args[0], args[1:]
1578 name,ranges = args[0], args[1:]
1608 #print 'rng',ranges # dbg
1579 #print 'rng',ranges # dbg
1609 cmds = self.extract_input_slices(ranges)
1580 lines = self.extract_input_slices(ranges)
1610 macro = Macro(cmds)
1581 macro = Macro(lines)
1611 self.shell.user_ns.update({name:macro})
1582 self.shell.user_ns.update({name:macro})
1612 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1583 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1613 print 'Macro contents:'
1584 print 'Macro contents:'
1614 print str(macro).rstrip(),
1585 print macro
1615
1586
1616 def magic_save(self,parameter_s = ''):
1587 def magic_save(self,parameter_s = ''):
1617 """Save a set of lines to a given filename.
1588 """Save a set of lines to a given filename.
1618
1589
1619 Usage:\\
1590 Usage:\\
1620 %save filename n1:n2 n3:n4 ... n5 .. n6 ...
1591 %save filename n1:n2 n3:n4 ... n5 .. n6 ...
1621
1592
1622 This function uses the same syntax as %macro for line extraction, but
1593 This function uses the same syntax as %macro for line extraction, but
1623 instead of creating a macro it saves the resulting string to the
1594 instead of creating a macro it saves the resulting string to the
1624 filename you specify.
1595 filename you specify.
1625
1596
1626 It adds a '.py' extension to the file if you don't do so yourself, and
1597 It adds a '.py' extension to the file if you don't do so yourself, and
1627 it asks for confirmation before overwriting existing files."""
1598 it asks for confirmation before overwriting existing files."""
1628
1599
1629 args = parameter_s.split()
1600 args = parameter_s.split()
1630 fname,ranges = args[0], args[1:]
1601 fname,ranges = args[0], args[1:]
1631 if not fname.endswith('.py'):
1602 if not fname.endswith('.py'):
1632 fname += '.py'
1603 fname += '.py'
1633 if os.path.isfile(fname):
1604 if os.path.isfile(fname):
1634 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1605 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1635 if ans.lower() not in ['y','yes']:
1606 if ans.lower() not in ['y','yes']:
1636 print 'Operation cancelled.'
1607 print 'Operation cancelled.'
1637 return
1608 return
1638 cmds = ''.join(self.extract_input_slices(ranges))
1609 cmds = ''.join(self.extract_input_slices(ranges))
1639 f = file(fname,'w')
1610 f = file(fname,'w')
1640 f.write(cmds)
1611 f.write(cmds)
1641 f.close()
1612 f.close()
1642 print 'The following commands were written to file `%s`:' % fname
1613 print 'The following commands were written to file `%s`:' % fname
1643 print cmds
1614 print cmds
1644
1615
1645 def magic_ed(self,parameter_s = ''):
1616 def magic_ed(self,parameter_s = ''):
1646 """Alias to %edit."""
1617 """Alias to %edit."""
1647 return self.magic_edit(parameter_s)
1618 return self.magic_edit(parameter_s)
1648
1619
1649 def magic_edit(self,parameter_s = '',last_call=['','']):
1620 def magic_edit(self,parameter_s = '',last_call=['','']):
1650 """Bring up an editor and execute the resulting code.
1621 """Bring up an editor and execute the resulting code.
1651
1622
1652 Usage:
1623 Usage:
1653 %edit [options] [args]
1624 %edit [options] [args]
1654
1625
1655 %edit runs IPython's editor hook. The default version of this hook is
1626 %edit runs IPython's editor hook. The default version of this hook is
1656 set to call the __IPYTHON__.rc.editor command. This is read from your
1627 set to call the __IPYTHON__.rc.editor command. This is read from your
1657 environment variable $EDITOR. If this isn't found, it will default to
1628 environment variable $EDITOR. If this isn't found, it will default to
1658 vi under Linux/Unix and to notepad under Windows. See the end of this
1629 vi under Linux/Unix and to notepad under Windows. See the end of this
1659 docstring for how to change the editor hook.
1630 docstring for how to change the editor hook.
1660
1631
1661 You can also set the value of this editor via the command line option
1632 You can also set the value of this editor via the command line option
1662 '-editor' or in your ipythonrc file. This is useful if you wish to use
1633 '-editor' or in your ipythonrc file. This is useful if you wish to use
1663 specifically for IPython an editor different from your typical default
1634 specifically for IPython an editor different from your typical default
1664 (and for Windows users who typically don't set environment variables).
1635 (and for Windows users who typically don't set environment variables).
1665
1636
1666 This command allows you to conveniently edit multi-line code right in
1637 This command allows you to conveniently edit multi-line code right in
1667 your IPython session.
1638 your IPython session.
1668
1639
1669 If called without arguments, %edit opens up an empty editor with a
1640 If called without arguments, %edit opens up an empty editor with a
1670 temporary file and will execute the contents of this file when you
1641 temporary file and will execute the contents of this file when you
1671 close it (don't forget to save it!).
1642 close it (don't forget to save it!).
1672
1643
1673 Options:
1644 Options:
1674
1645
1675 -p: this will call the editor with the same data as the previous time
1646 -p: this will call the editor with the same data as the previous time
1676 it was used, regardless of how long ago (in your current session) it
1647 it was used, regardless of how long ago (in your current session) it
1677 was.
1648 was.
1678
1649
1679 -x: do not execute the edited code immediately upon exit. This is
1650 -x: do not execute the edited code immediately upon exit. This is
1680 mainly useful if you are editing programs which need to be called with
1651 mainly useful if you are editing programs which need to be called with
1681 command line arguments, which you can then do using %run.
1652 command line arguments, which you can then do using %run.
1682
1653
1683 Arguments:
1654 Arguments:
1684
1655
1685 If arguments are given, the following possibilites exist:
1656 If arguments are given, the following possibilites exist:
1686
1657
1687 - The arguments are numbers or pairs of colon-separated numbers (like
1658 - The arguments are numbers or pairs of colon-separated numbers (like
1688 1 4:8 9). These are interpreted as lines of previous input to be
1659 1 4:8 9). These are interpreted as lines of previous input to be
1689 loaded into the editor. The syntax is the same of the %macro command.
1660 loaded into the editor. The syntax is the same of the %macro command.
1690
1661
1691 - If the argument doesn't start with a number, it is evaluated as a
1662 - If the argument doesn't start with a number, it is evaluated as a
1692 variable and its contents loaded into the editor. You can thus edit
1663 variable and its contents loaded into the editor. You can thus edit
1693 any string which contains python code (including the result of
1664 any string which contains python code (including the result of
1694 previous edits).
1665 previous edits).
1695
1666
1696 - If the argument is the name of an object (other than a string),
1667 - If the argument is the name of an object (other than a string),
1697 IPython will try to locate the file where it was defined and open the
1668 IPython will try to locate the file where it was defined and open the
1698 editor at the point where it is defined. You can use `%edit function`
1669 editor at the point where it is defined. You can use `%edit function`
1699 to load an editor exactly at the point where 'function' is defined,
1670 to load an editor exactly at the point where 'function' is defined,
1700 edit it and have the file be executed automatically.
1671 edit it and have the file be executed automatically.
1701
1672
1702 Note: opening at an exact line is only supported under Unix, and some
1673 Note: opening at an exact line is only supported under Unix, and some
1703 editors (like kedit and gedit up to Gnome 2.8) do not understand the
1674 editors (like kedit and gedit up to Gnome 2.8) do not understand the
1704 '+NUMBER' parameter necessary for this feature. Good editors like
1675 '+NUMBER' parameter necessary for this feature. Good editors like
1705 (X)Emacs, vi, jed, pico and joe all do.
1676 (X)Emacs, vi, jed, pico and joe all do.
1706
1677
1707 - If the argument is not found as a variable, IPython will look for a
1678 - If the argument is not found as a variable, IPython will look for a
1708 file with that name (adding .py if necessary) and load it into the
1679 file with that name (adding .py if necessary) and load it into the
1709 editor. It will execute its contents with execfile() when you exit,
1680 editor. It will execute its contents with execfile() when you exit,
1710 loading any code in the file into your interactive namespace.
1681 loading any code in the file into your interactive namespace.
1711
1682
1712 After executing your code, %edit will return as output the code you
1683 After executing your code, %edit will return as output the code you
1713 typed in the editor (except when it was an existing file). This way
1684 typed in the editor (except when it was an existing file). This way
1714 you can reload the code in further invocations of %edit as a variable,
1685 you can reload the code in further invocations of %edit as a variable,
1715 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
1686 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
1716 the output.
1687 the output.
1717
1688
1718 Note that %edit is also available through the alias %ed.
1689 Note that %edit is also available through the alias %ed.
1719
1690
1720 This is an example of creating a simple function inside the editor and
1691 This is an example of creating a simple function inside the editor and
1721 then modifying it. First, start up the editor:
1692 then modifying it. First, start up the editor:
1722
1693
1723 In [1]: ed\\
1694 In [1]: ed\\
1724 Editing... done. Executing edited code...\\
1695 Editing... done. Executing edited code...\\
1725 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
1696 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
1726
1697
1727 We can then call the function foo():
1698 We can then call the function foo():
1728
1699
1729 In [2]: foo()\\
1700 In [2]: foo()\\
1730 foo() was defined in an editing session
1701 foo() was defined in an editing session
1731
1702
1732 Now we edit foo. IPython automatically loads the editor with the
1703 Now we edit foo. IPython automatically loads the editor with the
1733 (temporary) file where foo() was previously defined:
1704 (temporary) file where foo() was previously defined:
1734
1705
1735 In [3]: ed foo\\
1706 In [3]: ed foo\\
1736 Editing... done. Executing edited code...
1707 Editing... done. Executing edited code...
1737
1708
1738 And if we call foo() again we get the modified version:
1709 And if we call foo() again we get the modified version:
1739
1710
1740 In [4]: foo()\\
1711 In [4]: foo()\\
1741 foo() has now been changed!
1712 foo() has now been changed!
1742
1713
1743 Here is an example of how to edit a code snippet successive
1714 Here is an example of how to edit a code snippet successive
1744 times. First we call the editor:
1715 times. First we call the editor:
1745
1716
1746 In [8]: ed\\
1717 In [8]: ed\\
1747 Editing... done. Executing edited code...\\
1718 Editing... done. Executing edited code...\\
1748 hello\\
1719 hello\\
1749 Out[8]: "print 'hello'\\n"
1720 Out[8]: "print 'hello'\\n"
1750
1721
1751 Now we call it again with the previous output (stored in _):
1722 Now we call it again with the previous output (stored in _):
1752
1723
1753 In [9]: ed _\\
1724 In [9]: ed _\\
1754 Editing... done. Executing edited code...\\
1725 Editing... done. Executing edited code...\\
1755 hello world\\
1726 hello world\\
1756 Out[9]: "print 'hello world'\\n"
1727 Out[9]: "print 'hello world'\\n"
1757
1728
1758 Now we call it with the output #8 (stored in _8, also as Out[8]):
1729 Now we call it with the output #8 (stored in _8, also as Out[8]):
1759
1730
1760 In [10]: ed _8\\
1731 In [10]: ed _8\\
1761 Editing... done. Executing edited code...\\
1732 Editing... done. Executing edited code...\\
1762 hello again\\
1733 hello again\\
1763 Out[10]: "print 'hello again'\\n"
1734 Out[10]: "print 'hello again'\\n"
1764
1735
1765
1736
1766 Changing the default editor hook:
1737 Changing the default editor hook:
1767
1738
1768 If you wish to write your own editor hook, you can put it in a
1739 If you wish to write your own editor hook, you can put it in a
1769 configuration file which you load at startup time. The default hook
1740 configuration file which you load at startup time. The default hook
1770 is defined in the IPython.hooks module, and you can use that as a
1741 is defined in the IPython.hooks module, and you can use that as a
1771 starting example for further modifications. That file also has
1742 starting example for further modifications. That file also has
1772 general instructions on how to set a new hook for use once you've
1743 general instructions on how to set a new hook for use once you've
1773 defined it."""
1744 defined it."""
1774
1745
1775 # FIXME: This function has become a convoluted mess. It needs a
1746 # FIXME: This function has become a convoluted mess. It needs a
1776 # ground-up rewrite with clean, simple logic.
1747 # ground-up rewrite with clean, simple logic.
1777
1748
1778 def make_filename(arg):
1749 def make_filename(arg):
1779 "Make a filename from the given args"
1750 "Make a filename from the given args"
1780 try:
1751 try:
1781 filename = get_py_filename(arg)
1752 filename = get_py_filename(arg)
1782 except IOError:
1753 except IOError:
1783 if args.endswith('.py'):
1754 if args.endswith('.py'):
1784 filename = arg
1755 filename = arg
1785 else:
1756 else:
1786 filename = None
1757 filename = None
1787 return filename
1758 return filename
1788
1759
1789 # custom exceptions
1760 # custom exceptions
1790 class DataIsObject(Exception): pass
1761 class DataIsObject(Exception): pass
1791
1762
1792 opts,args = self.parse_options(parameter_s,'px')
1763 opts,args = self.parse_options(parameter_s,'px')
1793
1764
1794 # Default line number value
1765 # Default line number value
1795 lineno = None
1766 lineno = None
1796 if opts.has_key('p'):
1767 if opts.has_key('p'):
1797 args = '_%s' % last_call[0]
1768 args = '_%s' % last_call[0]
1798 if not self.shell.user_ns.has_key(args):
1769 if not self.shell.user_ns.has_key(args):
1799 args = last_call[1]
1770 args = last_call[1]
1800
1771
1801 # use last_call to remember the state of the previous call, but don't
1772 # use last_call to remember the state of the previous call, but don't
1802 # let it be clobbered by successive '-p' calls.
1773 # let it be clobbered by successive '-p' calls.
1803 try:
1774 try:
1804 last_call[0] = self.shell.outputcache.prompt_count
1775 last_call[0] = self.shell.outputcache.prompt_count
1805 if not opts.has_key('p'):
1776 if not opts.has_key('p'):
1806 last_call[1] = parameter_s
1777 last_call[1] = parameter_s
1807 except:
1778 except:
1808 pass
1779 pass
1809
1780
1810 # by default this is done with temp files, except when the given
1781 # by default this is done with temp files, except when the given
1811 # arg is a filename
1782 # arg is a filename
1812 use_temp = 1
1783 use_temp = 1
1813
1784
1814 if re.match(r'\d',args):
1785 if re.match(r'\d',args):
1815 # Mode where user specifies ranges of lines, like in %macro.
1786 # Mode where user specifies ranges of lines, like in %macro.
1816 # This means that you can't edit files whose names begin with
1787 # This means that you can't edit files whose names begin with
1817 # numbers this way. Tough.
1788 # numbers this way. Tough.
1818 ranges = args.split()
1789 ranges = args.split()
1819 data = ''.join(self.extract_input_slices(ranges))
1790 data = ''.join(self.extract_input_slices(ranges))
1820 elif args.endswith('.py'):
1791 elif args.endswith('.py'):
1821 filename = make_filename(args)
1792 filename = make_filename(args)
1822 data = ''
1793 data = ''
1823 use_temp = 0
1794 use_temp = 0
1824 elif args:
1795 elif args:
1825 try:
1796 try:
1826 # Load the parameter given as a variable. If not a string,
1797 # Load the parameter given as a variable. If not a string,
1827 # process it as an object instead (below)
1798 # process it as an object instead (below)
1828
1799
1829 #print '*** args',args,'type',type(args) # dbg
1800 #print '*** args',args,'type',type(args) # dbg
1830 data = eval(args,self.shell.user_ns)
1801 data = eval(args,self.shell.user_ns)
1831 if not type(data) in StringTypes:
1802 if not type(data) in StringTypes:
1832 raise DataIsObject
1803 raise DataIsObject
1833 except (NameError,SyntaxError):
1804 except (NameError,SyntaxError):
1834 # given argument is not a variable, try as a filename
1805 # given argument is not a variable, try as a filename
1835 filename = make_filename(args)
1806 filename = make_filename(args)
1836 if filename is None:
1807 if filename is None:
1837 warn("Argument given (%s) can't be found as a variable "
1808 warn("Argument given (%s) can't be found as a variable "
1838 "or as a filename." % args)
1809 "or as a filename." % args)
1839 return
1810 return
1840 data = ''
1811 data = ''
1841 use_temp = 0
1812 use_temp = 0
1842 except DataIsObject:
1813 except DataIsObject:
1843 # For objects, try to edit the file where they are defined
1814 # For objects, try to edit the file where they are defined
1844 try:
1815 try:
1845 filename = inspect.getabsfile(data)
1816 filename = inspect.getabsfile(data)
1846 datafile = 1
1817 datafile = 1
1847 except TypeError:
1818 except TypeError:
1848 filename = make_filename(args)
1819 filename = make_filename(args)
1849 datafile = 1
1820 datafile = 1
1850 warn('Could not find file where `%s` is defined.\n'
1821 warn('Could not find file where `%s` is defined.\n'
1851 'Opening a file named `%s`' % (args,filename))
1822 'Opening a file named `%s`' % (args,filename))
1852 # Now, make sure we can actually read the source (if it was in
1823 # Now, make sure we can actually read the source (if it was in
1853 # a temp file it's gone by now).
1824 # a temp file it's gone by now).
1854 if datafile:
1825 if datafile:
1855 try:
1826 try:
1856 lineno = inspect.getsourcelines(data)[1]
1827 lineno = inspect.getsourcelines(data)[1]
1857 except IOError:
1828 except IOError:
1858 filename = make_filename(args)
1829 filename = make_filename(args)
1859 if filename is None:
1830 if filename is None:
1860 warn('The file `%s` where `%s` was defined cannot '
1831 warn('The file `%s` where `%s` was defined cannot '
1861 'be read.' % (filename,data))
1832 'be read.' % (filename,data))
1862 return
1833 return
1863 use_temp = 0
1834 use_temp = 0
1864 else:
1835 else:
1865 data = ''
1836 data = ''
1866
1837
1867 if use_temp:
1838 if use_temp:
1868 filename = tempfile.mktemp('.py')
1839 filename = tempfile.mktemp('.py')
1869 self.shell.tempfiles.append(filename)
1840 self.shell.tempfiles.append(filename)
1870
1841
1871 if data and use_temp:
1842 if data and use_temp:
1872 tmp_file = open(filename,'w')
1843 tmp_file = open(filename,'w')
1873 tmp_file.write(data)
1844 tmp_file.write(data)
1874 tmp_file.close()
1845 tmp_file.close()
1875
1846
1876 # do actual editing here
1847 # do actual editing here
1877 print 'Editing...',
1848 print 'Editing...',
1878 sys.stdout.flush()
1849 sys.stdout.flush()
1879 self.shell.hooks.editor(filename,lineno)
1850 self.shell.hooks.editor(filename,lineno)
1880 if opts.has_key('x'): # -x prevents actual execution
1851 if opts.has_key('x'): # -x prevents actual execution
1881 print
1852 print
1882 else:
1853 else:
1883 print 'done. Executing edited code...'
1854 print 'done. Executing edited code...'
1884 try:
1855 try:
1885 self.shell.safe_execfile(filename,self.shell.user_ns)
1856 self.shell.safe_execfile(filename,self.shell.user_ns)
1886 except IOError,msg:
1857 except IOError,msg:
1887 if msg.filename == filename:
1858 if msg.filename == filename:
1888 warn('File not found. Did you forget to save?')
1859 warn('File not found. Did you forget to save?')
1889 return
1860 return
1890 else:
1861 else:
1891 self.shell.showtraceback()
1862 self.shell.showtraceback()
1892 except:
1863 except:
1893 self.shell.showtraceback()
1864 self.shell.showtraceback()
1894 if use_temp:
1865 if use_temp:
1895 contents = open(filename).read()
1866 contents = open(filename).read()
1896 return contents
1867 return contents
1897
1868
1898 def magic_xmode(self,parameter_s = ''):
1869 def magic_xmode(self,parameter_s = ''):
1899 """Switch modes for the exception handlers.
1870 """Switch modes for the exception handlers.
1900
1871
1901 Valid modes: Plain, Context and Verbose.
1872 Valid modes: Plain, Context and Verbose.
1902
1873
1903 If called without arguments, acts as a toggle."""
1874 If called without arguments, acts as a toggle."""
1904
1875
1905 def xmode_switch_err(name):
1876 def xmode_switch_err(name):
1906 warn('Error changing %s exception modes.\n%s' %
1877 warn('Error changing %s exception modes.\n%s' %
1907 (name,sys.exc_info()[1]))
1878 (name,sys.exc_info()[1]))
1908
1879
1880 shell = self.shell
1909 new_mode = parameter_s.strip().capitalize()
1881 new_mode = parameter_s.strip().capitalize()
1910 try:
1882 try:
1911 self.InteractiveTB.set_mode(mode=new_mode)
1883 shell.InteractiveTB.set_mode(mode=new_mode)
1912 print 'Exception reporting mode:',self.InteractiveTB.mode
1884 print 'Exception reporting mode:',shell.InteractiveTB.mode
1913 except:
1885 except:
1914 xmode_switch_err('user')
1886 xmode_switch_err('user')
1915
1887
1916 # threaded shells use a special handler in sys.excepthook
1888 # threaded shells use a special handler in sys.excepthook
1917 if self.isthreaded:
1889 if shell.isthreaded:
1918 try:
1890 try:
1919 self.shell.sys_excepthook.set_mode(mode=new_mode)
1891 shell.sys_excepthook.set_mode(mode=new_mode)
1920 except:
1892 except:
1921 xmode_switch_err('threaded')
1893 xmode_switch_err('threaded')
1922
1894
1923 def magic_colors(self,parameter_s = ''):
1895 def magic_colors(self,parameter_s = ''):
1924 """Switch color scheme for prompts, info system and exception handlers.
1896 """Switch color scheme for prompts, info system and exception handlers.
1925
1897
1926 Currently implemented schemes: NoColor, Linux, LightBG.
1898 Currently implemented schemes: NoColor, Linux, LightBG.
1927
1899
1928 Color scheme names are not case-sensitive."""
1900 Color scheme names are not case-sensitive."""
1929
1901
1930 def color_switch_err(name):
1902 def color_switch_err(name):
1931 warn('Error changing %s color schemes.\n%s' %
1903 warn('Error changing %s color schemes.\n%s' %
1932 (name,sys.exc_info()[1]))
1904 (name,sys.exc_info()[1]))
1933
1905
1934
1906
1935 new_scheme = parameter_s.strip()
1907 new_scheme = parameter_s.strip()
1936 if not new_scheme:
1908 if not new_scheme:
1937 print 'You must specify a color scheme.'
1909 print 'You must specify a color scheme.'
1938 return
1910 return
1939 # Under Windows, check for Gary Bishop's readline, which is necessary
1911 # Under Windows, check for Gary Bishop's readline, which is necessary
1940 # for ANSI coloring
1912 # for ANSI coloring
1941 if os.name in ['nt','dos']:
1913 if os.name in ['nt','dos']:
1942 try:
1914 try:
1943 import readline
1915 import readline
1944 except ImportError:
1916 except ImportError:
1945 has_readline = 0
1917 has_readline = 0
1946 else:
1918 else:
1947 try:
1919 try:
1948 readline.GetOutputFile()
1920 readline.GetOutputFile()
1949 except AttributeError:
1921 except AttributeError:
1950 has_readline = 0
1922 has_readline = 0
1951 else:
1923 else:
1952 has_readline = 1
1924 has_readline = 1
1953 if not has_readline:
1925 if not has_readline:
1954 msg = """\
1926 msg = """\
1955 Proper color support under MS Windows requires Gary Bishop's readline library.
1927 Proper color support under MS Windows requires Gary Bishop's readline library.
1956 You can find it at:
1928 You can find it at:
1957 http://sourceforge.net/projects/uncpythontools
1929 http://sourceforge.net/projects/uncpythontools
1958 Gary's readline needs the ctypes module, from:
1930 Gary's readline needs the ctypes module, from:
1959 http://starship.python.net/crew/theller/ctypes
1931 http://starship.python.net/crew/theller/ctypes
1960
1932
1961 Defaulting color scheme to 'NoColor'"""
1933 Defaulting color scheme to 'NoColor'"""
1962 new_scheme = 'NoColor'
1934 new_scheme = 'NoColor'
1963 warn(msg)
1935 warn(msg)
1936 # local shortcut
1937 shell = self.shell
1964
1938
1965 # Set prompt colors
1939 # Set prompt colors
1966 try:
1940 try:
1967 self.shell.outputcache.set_colors(new_scheme)
1941 shell.outputcache.set_colors(new_scheme)
1968 except:
1942 except:
1969 color_switch_err('prompt')
1943 color_switch_err('prompt')
1970 else:
1944 else:
1971 self.shell.rc.colors = \
1945 shell.rc.colors = \
1972 self.shell.outputcache.color_table.active_scheme_name
1946 shell.outputcache.color_table.active_scheme_name
1973 # Set exception colors
1947 # Set exception colors
1974 try:
1948 try:
1975 self.shell.InteractiveTB.set_colors(scheme = new_scheme)
1949 shell.InteractiveTB.set_colors(scheme = new_scheme)
1976 self.shell.SyntaxTB.set_colors(scheme = new_scheme)
1950 shell.SyntaxTB.set_colors(scheme = new_scheme)
1977 except:
1951 except:
1978 color_switch_err('exception')
1952 color_switch_err('exception')
1979
1953
1980 # threaded shells use a verbose traceback in sys.excepthook
1954 # threaded shells use a verbose traceback in sys.excepthook
1981 if self.isthreaded:
1955 if shell.isthreaded:
1982 try:
1956 try:
1983 self.shell.sys_excepthook.set_colors(scheme=new_scheme)
1957 shell.sys_excepthook.set_colors(scheme=new_scheme)
1984 except:
1958 except:
1985 color_switch_err('system exception handler')
1959 color_switch_err('system exception handler')
1986
1960
1987 # Set info (for 'object?') colors
1961 # Set info (for 'object?') colors
1988 if self.shell.rc.color_info:
1962 if shell.rc.color_info:
1989 try:
1963 try:
1990 self.shell.inspector.set_active_scheme(new_scheme)
1964 shell.inspector.set_active_scheme(new_scheme)
1991 except:
1965 except:
1992 color_switch_err('object inspector')
1966 color_switch_err('object inspector')
1993 else:
1967 else:
1994 self.shell.inspector.set_active_scheme('NoColor')
1968 shell.inspector.set_active_scheme('NoColor')
1995
1969
1996 def magic_color_info(self,parameter_s = ''):
1970 def magic_color_info(self,parameter_s = ''):
1997 """Toggle color_info.
1971 """Toggle color_info.
1998
1972
1999 The color_info configuration parameter controls whether colors are
1973 The color_info configuration parameter controls whether colors are
2000 used for displaying object details (by things like %psource, %pfile or
1974 used for displaying object details (by things like %psource, %pfile or
2001 the '?' system). This function toggles this value with each call.
1975 the '?' system). This function toggles this value with each call.
2002
1976
2003 Note that unless you have a fairly recent pager (less works better
1977 Note that unless you have a fairly recent pager (less works better
2004 than more) in your system, using colored object information displays
1978 than more) in your system, using colored object information displays
2005 will not work properly. Test it and see."""
1979 will not work properly. Test it and see."""
2006
1980
2007 self.shell.rc.color_info = 1 - self.shell.rc.color_info
1981 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2008 self.magic_colors(self.shell.rc.colors)
1982 self.magic_colors(self.shell.rc.colors)
2009 print 'Object introspection functions have now coloring:',
1983 print 'Object introspection functions have now coloring:',
2010 print ['OFF','ON'][self.shell.rc.color_info]
1984 print ['OFF','ON'][self.shell.rc.color_info]
2011
1985
2012 def magic_Pprint(self, parameter_s=''):
1986 def magic_Pprint(self, parameter_s=''):
2013 """Toggle pretty printing on/off."""
1987 """Toggle pretty printing on/off."""
2014
1988
2015 self.shell.outputcache.Pprint = 1 - self.shell.outputcache.Pprint
1989 self.shell.outputcache.Pprint = 1 - self.shell.outputcache.Pprint
2016 print 'Pretty printing has been turned', \
1990 print 'Pretty printing has been turned', \
2017 ['OFF','ON'][self.shell.outputcache.Pprint]
1991 ['OFF','ON'][self.shell.outputcache.Pprint]
2018
1992
2019 def magic_exit(self, parameter_s=''):
1993 def magic_exit(self, parameter_s=''):
2020 """Exit IPython, confirming if configured to do so.
1994 """Exit IPython, confirming if configured to do so.
2021
1995
2022 You can configure whether IPython asks for confirmation upon exit by
1996 You can configure whether IPython asks for confirmation upon exit by
2023 setting the confirm_exit flag in the ipythonrc file."""
1997 setting the confirm_exit flag in the ipythonrc file."""
2024
1998
2025 self.shell.exit()
1999 self.shell.exit()
2026
2000
2027 def magic_quit(self, parameter_s=''):
2001 def magic_quit(self, parameter_s=''):
2028 """Exit IPython, confirming if configured to do so (like %exit)"""
2002 """Exit IPython, confirming if configured to do so (like %exit)"""
2029
2003
2030 self.shell.exit()
2004 self.shell.exit()
2031
2005
2032 def magic_Exit(self, parameter_s=''):
2006 def magic_Exit(self, parameter_s=''):
2033 """Exit IPython without confirmation."""
2007 """Exit IPython without confirmation."""
2034
2008
2035 self.shell.exit_now = True
2009 self.shell.exit_now = True
2036
2010
2037 def magic_Quit(self, parameter_s=''):
2011 def magic_Quit(self, parameter_s=''):
2038 """Exit IPython without confirmation (like %Exit)."""
2012 """Exit IPython without confirmation (like %Exit)."""
2039
2013
2040 self.shell.exit_now = True
2014 self.shell.exit_now = True
2041
2015
2042 #......................................................................
2016 #......................................................................
2043 # Functions to implement unix shell-type things
2017 # Functions to implement unix shell-type things
2044
2018
2045 def magic_alias(self, parameter_s = ''):
2019 def magic_alias(self, parameter_s = ''):
2046 """Define an alias for a system command.
2020 """Define an alias for a system command.
2047
2021
2048 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2022 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2049
2023
2050 Then, typing 'alias_name params' will execute the system command 'cmd
2024 Then, typing 'alias_name params' will execute the system command 'cmd
2051 params' (from your underlying operating system).
2025 params' (from your underlying operating system).
2052
2026
2053 Aliases have lower precedence than magic functions and Python normal
2027 Aliases have lower precedence than magic functions and Python normal
2054 variables, so if 'foo' is both a Python variable and an alias, the
2028 variables, so if 'foo' is both a Python variable and an alias, the
2055 alias can not be executed until 'del foo' removes the Python variable.
2029 alias can not be executed until 'del foo' removes the Python variable.
2056
2030
2057 You can use the %l specifier in an alias definition to represent the
2031 You can use the %l specifier in an alias definition to represent the
2058 whole line when the alias is called. For example:
2032 whole line when the alias is called. For example:
2059
2033
2060 In [2]: alias all echo "Input in brackets: <%l>"\\
2034 In [2]: alias all echo "Input in brackets: <%l>"\\
2061 In [3]: all hello world\\
2035 In [3]: all hello world\\
2062 Input in brackets: <hello world>
2036 Input in brackets: <hello world>
2063
2037
2064 You can also define aliases with parameters using %s specifiers (one
2038 You can also define aliases with parameters using %s specifiers (one
2065 per parameter):
2039 per parameter):
2066
2040
2067 In [1]: alias parts echo first %s second %s\\
2041 In [1]: alias parts echo first %s second %s\\
2068 In [2]: %parts A B\\
2042 In [2]: %parts A B\\
2069 first A second B\\
2043 first A second B\\
2070 In [3]: %parts A\\
2044 In [3]: %parts A\\
2071 Incorrect number of arguments: 2 expected.\\
2045 Incorrect number of arguments: 2 expected.\\
2072 parts is an alias to: 'echo first %s second %s'
2046 parts is an alias to: 'echo first %s second %s'
2073
2047
2074 Note that %l and %s are mutually exclusive. You can only use one or
2048 Note that %l and %s are mutually exclusive. You can only use one or
2075 the other in your aliases.
2049 the other in your aliases.
2076
2050
2077 Aliases expand Python variables just like system calls using ! or !!
2051 Aliases expand Python variables just like system calls using ! or !!
2078 do: all expressions prefixed with '$' get expanded. For details of
2052 do: all expressions prefixed with '$' get expanded. For details of
2079 the semantic rules, see PEP-215:
2053 the semantic rules, see PEP-215:
2080 http://www.python.org/peps/pep-0215.html. This is the library used by
2054 http://www.python.org/peps/pep-0215.html. This is the library used by
2081 IPython for variable expansion. If you want to access a true shell
2055 IPython for variable expansion. If you want to access a true shell
2082 variable, an extra $ is necessary to prevent its expansion by IPython:
2056 variable, an extra $ is necessary to prevent its expansion by IPython:
2083
2057
2084 In [6]: alias show echo\\
2058 In [6]: alias show echo\\
2085 In [7]: PATH='A Python string'\\
2059 In [7]: PATH='A Python string'\\
2086 In [8]: show $PATH\\
2060 In [8]: show $PATH\\
2087 A Python string\\
2061 A Python string\\
2088 In [9]: show $$PATH\\
2062 In [9]: show $$PATH\\
2089 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2063 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2090
2064
2091 You can use the alias facility to acess all of $PATH. See the %rehash
2065 You can use the alias facility to acess all of $PATH. See the %rehash
2092 and %rehashx functions, which automatically create aliases for the
2066 and %rehashx functions, which automatically create aliases for the
2093 contents of your $PATH.
2067 contents of your $PATH.
2094
2068
2095 If called with no parameters, %alias prints the current alias table."""
2069 If called with no parameters, %alias prints the current alias table."""
2096
2070
2097 par = parameter_s.strip()
2071 par = parameter_s.strip()
2098 if not par:
2072 if not par:
2099 if self.shell.rc.automagic:
2073 if self.shell.rc.automagic:
2100 prechar = ''
2074 prechar = ''
2101 else:
2075 else:
2102 prechar = self.shell.ESC_MAGIC
2076 prechar = self.shell.ESC_MAGIC
2103 print 'Alias\t\tSystem Command\n'+'-'*30
2077 print 'Alias\t\tSystem Command\n'+'-'*30
2104 atab = self.shell.alias_table
2078 atab = self.shell.alias_table
2105 aliases = atab.keys()
2079 aliases = atab.keys()
2106 aliases.sort()
2080 aliases.sort()
2107 for alias in aliases:
2081 for alias in aliases:
2108 print prechar+alias+'\t\t'+atab[alias][1]
2082 print prechar+alias+'\t\t'+atab[alias][1]
2109 print '-'*30+'\nTotal number of aliases:',len(aliases)
2083 print '-'*30+'\nTotal number of aliases:',len(aliases)
2110 return
2084 return
2111 try:
2085 try:
2112 alias,cmd = par.split(None,1)
2086 alias,cmd = par.split(None,1)
2113 except:
2087 except:
2114 print OInspect.getdoc(self.magic_alias)
2088 print OInspect.getdoc(self.magic_alias)
2115 else:
2089 else:
2116 nargs = cmd.count('%s')
2090 nargs = cmd.count('%s')
2117 if nargs>0 and cmd.find('%l')>=0:
2091 if nargs>0 and cmd.find('%l')>=0:
2118 error('The %s and %l specifiers are mutually exclusive '
2092 error('The %s and %l specifiers are mutually exclusive '
2119 'in alias definitions.')
2093 'in alias definitions.')
2120 else: # all looks OK
2094 else: # all looks OK
2121 self.shell.alias_table[alias] = (nargs,cmd)
2095 self.shell.alias_table[alias] = (nargs,cmd)
2122 self.shell.alias_table_validate(verbose=1)
2096 self.shell.alias_table_validate(verbose=1)
2123 # end magic_alias
2097 # end magic_alias
2124
2098
2125 def magic_unalias(self, parameter_s = ''):
2099 def magic_unalias(self, parameter_s = ''):
2126 """Remove an alias"""
2100 """Remove an alias"""
2127
2101
2128 aname = parameter_s.strip()
2102 aname = parameter_s.strip()
2129 if aname in self.shell.alias_table:
2103 if aname in self.shell.alias_table:
2130 del self.shell.alias_table[aname]
2104 del self.shell.alias_table[aname]
2131
2105
2132 def magic_rehash(self, parameter_s = ''):
2106 def magic_rehash(self, parameter_s = ''):
2133 """Update the alias table with all entries in $PATH.
2107 """Update the alias table with all entries in $PATH.
2134
2108
2135 This version does no checks on execute permissions or whether the
2109 This version does no checks on execute permissions or whether the
2136 contents of $PATH are truly files (instead of directories or something
2110 contents of $PATH are truly files (instead of directories or something
2137 else). For such a safer (but slower) version, use %rehashx."""
2111 else). For such a safer (but slower) version, use %rehashx."""
2138
2112
2139 # This function (and rehashx) manipulate the alias_table directly
2113 # This function (and rehashx) manipulate the alias_table directly
2140 # rather than calling magic_alias, for speed reasons. A rehash on a
2114 # rather than calling magic_alias, for speed reasons. A rehash on a
2141 # typical Linux box involves several thousand entries, so efficiency
2115 # typical Linux box involves several thousand entries, so efficiency
2142 # here is a top concern.
2116 # here is a top concern.
2143
2117
2144 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2118 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2145 alias_table = self.shell.alias_table
2119 alias_table = self.shell.alias_table
2146 for pdir in path:
2120 for pdir in path:
2147 for ff in os.listdir(pdir):
2121 for ff in os.listdir(pdir):
2148 # each entry in the alias table must be (N,name), where
2122 # each entry in the alias table must be (N,name), where
2149 # N is the number of positional arguments of the alias.
2123 # N is the number of positional arguments of the alias.
2150 alias_table[ff] = (0,ff)
2124 alias_table[ff] = (0,ff)
2151 # Make sure the alias table doesn't contain keywords or builtins
2125 # Make sure the alias table doesn't contain keywords or builtins
2152 self.shell.alias_table_validate()
2126 self.shell.alias_table_validate()
2153 # Call again init_auto_alias() so we get 'rm -i' and other modified
2127 # Call again init_auto_alias() so we get 'rm -i' and other modified
2154 # aliases since %rehash will probably clobber them
2128 # aliases since %rehash will probably clobber them
2155 self.shell.init_auto_alias()
2129 self.shell.init_auto_alias()
2156
2130
2157 def magic_rehashx(self, parameter_s = ''):
2131 def magic_rehashx(self, parameter_s = ''):
2158 """Update the alias table with all executable files in $PATH.
2132 """Update the alias table with all executable files in $PATH.
2159
2133
2160 This version explicitly checks that every entry in $PATH is a file
2134 This version explicitly checks that every entry in $PATH is a file
2161 with execute access (os.X_OK), so it is much slower than %rehash.
2135 with execute access (os.X_OK), so it is much slower than %rehash.
2162
2136
2163 Under Windows, it checks executability as a match agains a
2137 Under Windows, it checks executability as a match agains a
2164 '|'-separated string of extensions, stored in the IPython config
2138 '|'-separated string of extensions, stored in the IPython config
2165 variable win_exec_ext. This defaults to 'exe|com|bat'. """
2139 variable win_exec_ext. This defaults to 'exe|com|bat'. """
2166
2140
2167 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2141 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2168 alias_table = self.shell.alias_table
2142 alias_table = self.shell.alias_table
2169
2143
2170 if os.name == 'posix':
2144 if os.name == 'posix':
2171 isexec = lambda fname:os.path.isfile(fname) and \
2145 isexec = lambda fname:os.path.isfile(fname) and \
2172 os.access(fname,os.X_OK)
2146 os.access(fname,os.X_OK)
2173 else:
2147 else:
2174
2148
2175 try:
2149 try:
2176 winext = os.environ['pathext'].replace(';','|').replace('.','')
2150 winext = os.environ['pathext'].replace(';','|').replace('.','')
2177 except KeyError:
2151 except KeyError:
2178 winext = 'exe|com|bat'
2152 winext = 'exe|com|bat'
2179
2153
2180 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2154 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2181 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2155 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2182 savedir = os.getcwd()
2156 savedir = os.getcwd()
2183 try:
2157 try:
2184 # write the whole loop for posix/Windows so we don't have an if in
2158 # write the whole loop for posix/Windows so we don't have an if in
2185 # the innermost part
2159 # the innermost part
2186 if os.name == 'posix':
2160 if os.name == 'posix':
2187 for pdir in path:
2161 for pdir in path:
2188 os.chdir(pdir)
2162 os.chdir(pdir)
2189 for ff in os.listdir(pdir):
2163 for ff in os.listdir(pdir):
2190 if isexec(ff):
2164 if isexec(ff):
2191 # each entry in the alias table must be (N,name),
2165 # each entry in the alias table must be (N,name),
2192 # where N is the number of positional arguments of the
2166 # where N is the number of positional arguments of the
2193 # alias.
2167 # alias.
2194 alias_table[ff] = (0,ff)
2168 alias_table[ff] = (0,ff)
2195 else:
2169 else:
2196 for pdir in path:
2170 for pdir in path:
2197 os.chdir(pdir)
2171 os.chdir(pdir)
2198 for ff in os.listdir(pdir):
2172 for ff in os.listdir(pdir):
2199 if isexec(ff):
2173 if isexec(ff):
2200 alias_table[execre.sub(r'\1',ff)] = (0,ff)
2174 alias_table[execre.sub(r'\1',ff)] = (0,ff)
2201 # Make sure the alias table doesn't contain keywords or builtins
2175 # Make sure the alias table doesn't contain keywords or builtins
2202 self.shell.alias_table_validate()
2176 self.shell.alias_table_validate()
2203 # Call again init_auto_alias() so we get 'rm -i' and other
2177 # Call again init_auto_alias() so we get 'rm -i' and other
2204 # modified aliases since %rehashx will probably clobber them
2178 # modified aliases since %rehashx will probably clobber them
2205 self.shell.init_auto_alias()
2179 self.shell.init_auto_alias()
2206 finally:
2180 finally:
2207 os.chdir(savedir)
2181 os.chdir(savedir)
2208
2182
2209 def magic_pwd(self, parameter_s = ''):
2183 def magic_pwd(self, parameter_s = ''):
2210 """Return the current working directory path."""
2184 """Return the current working directory path."""
2211 return os.getcwd()
2185 return os.getcwd()
2212
2186
2213 def magic_cd(self, parameter_s=''):
2187 def magic_cd(self, parameter_s=''):
2214 """Change the current working directory.
2188 """Change the current working directory.
2215
2189
2216 This command automatically maintains an internal list of directories
2190 This command automatically maintains an internal list of directories
2217 you visit during your IPython session, in the variable _dh. The
2191 you visit during your IPython session, in the variable _dh. The
2218 command %dhist shows this history nicely formatted.
2192 command %dhist shows this history nicely formatted.
2219
2193
2220 Usage:
2194 Usage:
2221
2195
2222 cd 'dir': changes to directory 'dir'.
2196 cd 'dir': changes to directory 'dir'.
2223
2197
2224 cd -: changes to the last visited directory.
2198 cd -: changes to the last visited directory.
2225
2199
2226 cd -<n>: changes to the n-th directory in the directory history.
2200 cd -<n>: changes to the n-th directory in the directory history.
2227
2201
2228 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2202 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2229 (note: cd <bookmark_name> is enough if there is no
2203 (note: cd <bookmark_name> is enough if there is no
2230 directory <bookmark_name>, but a bookmark with the name exists.)
2204 directory <bookmark_name>, but a bookmark with the name exists.)
2231
2205
2232 Options:
2206 Options:
2233
2207
2234 -q: quiet. Do not print the working directory after the cd command is
2208 -q: quiet. Do not print the working directory after the cd command is
2235 executed. By default IPython's cd command does print this directory,
2209 executed. By default IPython's cd command does print this directory,
2236 since the default prompts do not display path information.
2210 since the default prompts do not display path information.
2237
2211
2238 Note that !cd doesn't work for this purpose because the shell where
2212 Note that !cd doesn't work for this purpose because the shell where
2239 !command runs is immediately discarded after executing 'command'."""
2213 !command runs is immediately discarded after executing 'command'."""
2240
2214
2241 parameter_s = parameter_s.strip()
2215 parameter_s = parameter_s.strip()
2242 bkms = self.shell.persist.get("bookmarks",{})
2216 bkms = self.shell.persist.get("bookmarks",{})
2243
2217
2244 numcd = re.match(r'(-)(\d+)$',parameter_s)
2218 numcd = re.match(r'(-)(\d+)$',parameter_s)
2245 # jump in directory history by number
2219 # jump in directory history by number
2246 if numcd:
2220 if numcd:
2247 nn = int(numcd.group(2))
2221 nn = int(numcd.group(2))
2248 try:
2222 try:
2249 ps = self.shell.user_ns['_dh'][nn]
2223 ps = self.shell.user_ns['_dh'][nn]
2250 except IndexError:
2224 except IndexError:
2251 print 'The requested directory does not exist in history.'
2225 print 'The requested directory does not exist in history.'
2252 return
2226 return
2253 else:
2227 else:
2254 opts = {}
2228 opts = {}
2255 else:
2229 else:
2256 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2230 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2257 # jump to previous
2231 # jump to previous
2258 if ps == '-':
2232 if ps == '-':
2259 try:
2233 try:
2260 ps = self.shell.user_ns['_dh'][-2]
2234 ps = self.shell.user_ns['_dh'][-2]
2261 except IndexError:
2235 except IndexError:
2262 print 'No previous directory to change to.'
2236 print 'No previous directory to change to.'
2263 return
2237 return
2264 # jump to bookmark
2238 # jump to bookmark
2265 elif opts.has_key('b') or (bkms.has_key(ps) and not os.path.isdir(ps)):
2239 elif opts.has_key('b') or (bkms.has_key(ps) and not os.path.isdir(ps)):
2266 if bkms.has_key(ps):
2240 if bkms.has_key(ps):
2267 target = bkms[ps]
2241 target = bkms[ps]
2268 print '(bookmark:%s) -> %s' % (ps,target)
2242 print '(bookmark:%s) -> %s' % (ps,target)
2269 ps = target
2243 ps = target
2270 else:
2244 else:
2271 if bkms:
2245 if bkms:
2272 error("Bookmark '%s' not found. "
2246 error("Bookmark '%s' not found. "
2273 "Use '%bookmark -l' to see your bookmarks." % ps)
2247 "Use '%bookmark -l' to see your bookmarks." % ps)
2274 else:
2248 else:
2275 print "Bookmarks not set - use %bookmark <bookmarkname>"
2249 print "Bookmarks not set - use %bookmark <bookmarkname>"
2276 return
2250 return
2277
2251
2278 # at this point ps should point to the target dir
2252 # at this point ps should point to the target dir
2279 if ps:
2253 if ps:
2280 try:
2254 try:
2281 os.chdir(os.path.expanduser(ps))
2255 os.chdir(os.path.expanduser(ps))
2282 except OSError:
2256 except OSError:
2283 print sys.exc_info()[1]
2257 print sys.exc_info()[1]
2284 else:
2258 else:
2285 self.shell.user_ns['_dh'].append(os.getcwd())
2259 self.shell.user_ns['_dh'].append(os.getcwd())
2286 else:
2260 else:
2287 os.chdir(self.home_dir)
2261 os.chdir(self.shell.home_dir)
2288 self.shell.user_ns['_dh'].append(os.getcwd())
2262 self.shell.user_ns['_dh'].append(os.getcwd())
2289 if not 'q' in opts:
2263 if not 'q' in opts:
2290 print self.shell.user_ns['_dh'][-1]
2264 print self.shell.user_ns['_dh'][-1]
2291
2265
2292 def magic_dhist(self, parameter_s=''):
2266 def magic_dhist(self, parameter_s=''):
2293 """Print your history of visited directories.
2267 """Print your history of visited directories.
2294
2268
2295 %dhist -> print full history\\
2269 %dhist -> print full history\\
2296 %dhist n -> print last n entries only\\
2270 %dhist n -> print last n entries only\\
2297 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2271 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2298
2272
2299 This history is automatically maintained by the %cd command, and
2273 This history is automatically maintained by the %cd command, and
2300 always available as the global list variable _dh. You can use %cd -<n>
2274 always available as the global list variable _dh. You can use %cd -<n>
2301 to go to directory number <n>."""
2275 to go to directory number <n>."""
2302
2276
2303 dh = self.shell.user_ns['_dh']
2277 dh = self.shell.user_ns['_dh']
2304 if parameter_s:
2278 if parameter_s:
2305 try:
2279 try:
2306 args = map(int,parameter_s.split())
2280 args = map(int,parameter_s.split())
2307 except:
2281 except:
2308 self.arg_err(Magic.magic_dhist)
2282 self.arg_err(Magic.magic_dhist)
2309 return
2283 return
2310 if len(args) == 1:
2284 if len(args) == 1:
2311 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2285 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2312 elif len(args) == 2:
2286 elif len(args) == 2:
2313 ini,fin = args
2287 ini,fin = args
2314 else:
2288 else:
2315 self.arg_err(Magic.magic_dhist)
2289 self.arg_err(Magic.magic_dhist)
2316 return
2290 return
2317 else:
2291 else:
2318 ini,fin = 0,len(dh)
2292 ini,fin = 0,len(dh)
2319 nlprint(dh,
2293 nlprint(dh,
2320 header = 'Directory history (kept in _dh)',
2294 header = 'Directory history (kept in _dh)',
2321 start=ini,stop=fin)
2295 start=ini,stop=fin)
2322
2296
2323 def magic_env(self, parameter_s=''):
2297 def magic_env(self, parameter_s=''):
2324 """List environment variables."""
2298 """List environment variables."""
2325
2299
2326 # environ is an instance of UserDict
2327 return os.environ.data
2300 return os.environ.data
2328
2301
2329 def magic_pushd(self, parameter_s=''):
2302 def magic_pushd(self, parameter_s=''):
2330 """Place the current dir on stack and change directory.
2303 """Place the current dir on stack and change directory.
2331
2304
2332 Usage:\\
2305 Usage:\\
2333 %pushd ['dirname']
2306 %pushd ['dirname']
2334
2307
2335 %pushd with no arguments does a %pushd to your home directory.
2308 %pushd with no arguments does a %pushd to your home directory.
2336 """
2309 """
2337 if parameter_s == '': parameter_s = '~'
2310 if parameter_s == '': parameter_s = '~'
2338 if len(self.dir_stack)>0 and os.path.expanduser(parameter_s) != \
2311 dir_s = self.shell.dir_stack
2339 os.path.expanduser(self.dir_stack[0]):
2312 if len(dir_s)>0 and os.path.expanduser(parameter_s) != \
2313 os.path.expanduser(self.shell.dir_stack[0]):
2340 try:
2314 try:
2341 self.magic_cd(parameter_s)
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 self.magic_dirs()
2317 self.magic_dirs()
2344 except:
2318 except:
2345 print 'Invalid directory'
2319 print 'Invalid directory'
2346 else:
2320 else:
2347 print 'You are already there!'
2321 print 'You are already there!'
2348
2322
2349 def magic_popd(self, parameter_s=''):
2323 def magic_popd(self, parameter_s=''):
2350 """Change to directory popped off the top of the stack.
2324 """Change to directory popped off the top of the stack.
2351 """
2325 """
2352 if len (self.dir_stack) > 1:
2326 if len (self.shell.dir_stack) > 1:
2353 self.dir_stack.pop(0)
2327 self.shell.dir_stack.pop(0)
2354 self.magic_cd(self.dir_stack[0])
2328 self.magic_cd(self.shell.dir_stack[0])
2355 print self.dir_stack[0]
2329 print self.shell.dir_stack[0]
2356 else:
2330 else:
2357 print "You can't remove the starting directory from the stack:",\
2331 print "You can't remove the starting directory from the stack:",\
2358 self.dir_stack
2332 self.shell.dir_stack
2359
2333
2360 def magic_dirs(self, parameter_s=''):
2334 def magic_dirs(self, parameter_s=''):
2361 """Return the current directory stack."""
2335 """Return the current directory stack."""
2362
2336
2363 return self.dir_stack[:]
2337 return self.shell.dir_stack[:]
2364
2338
2365 def magic_sc(self, parameter_s=''):
2339 def magic_sc(self, parameter_s=''):
2366 """Shell capture - execute a shell command and capture its output.
2340 """Shell capture - execute a shell command and capture its output.
2367
2341
2368 %sc [options] varname=command
2342 %sc [options] varname=command
2369
2343
2370 IPython will run the given command using commands.getoutput(), and
2344 IPython will run the given command using commands.getoutput(), and
2371 will then update the user's interactive namespace with a variable
2345 will then update the user's interactive namespace with a variable
2372 called varname, containing the value of the call. Your command can
2346 called varname, containing the value of the call. Your command can
2373 contain shell wildcards, pipes, etc.
2347 contain shell wildcards, pipes, etc.
2374
2348
2375 The '=' sign in the syntax is mandatory, and the variable name you
2349 The '=' sign in the syntax is mandatory, and the variable name you
2376 supply must follow Python's standard conventions for valid names.
2350 supply must follow Python's standard conventions for valid names.
2377
2351
2378 Options:
2352 Options:
2379
2353
2380 -l: list output. Split the output on newlines into a list before
2354 -l: list output. Split the output on newlines into a list before
2381 assigning it to the given variable. By default the output is stored
2355 assigning it to the given variable. By default the output is stored
2382 as a single string.
2356 as a single string.
2383
2357
2384 -v: verbose. Print the contents of the variable.
2358 -v: verbose. Print the contents of the variable.
2385
2359
2386 In most cases you should not need to split as a list, because the
2360 In most cases you should not need to split as a list, because the
2387 returned value is a special type of string which can automatically
2361 returned value is a special type of string which can automatically
2388 provide its contents either as a list (split on newlines) or as a
2362 provide its contents either as a list (split on newlines) or as a
2389 space-separated string. These are convenient, respectively, either
2363 space-separated string. These are convenient, respectively, either
2390 for sequential processing or to be passed to a shell command.
2364 for sequential processing or to be passed to a shell command.
2391
2365
2392 For example:
2366 For example:
2393
2367
2394 # Capture into variable a
2368 # Capture into variable a
2395 In [9]: sc a=ls *py
2369 In [9]: sc a=ls *py
2396
2370
2397 # a is a string with embedded newlines
2371 # a is a string with embedded newlines
2398 In [10]: a
2372 In [10]: a
2399 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2373 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2400
2374
2401 # which can be seen as a list:
2375 # which can be seen as a list:
2402 In [11]: a.l
2376 In [11]: a.l
2403 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2377 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2404
2378
2405 # or as a whitespace-separated string:
2379 # or as a whitespace-separated string:
2406 In [12]: a.s
2380 In [12]: a.s
2407 Out[12]: 'setup.py win32_manual_post_install.py'
2381 Out[12]: 'setup.py win32_manual_post_install.py'
2408
2382
2409 # a.s is useful to pass as a single command line:
2383 # a.s is useful to pass as a single command line:
2410 In [13]: !wc -l $a.s
2384 In [13]: !wc -l $a.s
2411 146 setup.py
2385 146 setup.py
2412 130 win32_manual_post_install.py
2386 130 win32_manual_post_install.py
2413 276 total
2387 276 total
2414
2388
2415 # while the list form is useful to loop over:
2389 # while the list form is useful to loop over:
2416 In [14]: for f in a.l:
2390 In [14]: for f in a.l:
2417 ....: !wc -l $f
2391 ....: !wc -l $f
2418 ....:
2392 ....:
2419 146 setup.py
2393 146 setup.py
2420 130 win32_manual_post_install.py
2394 130 win32_manual_post_install.py
2421
2395
2422 Similiarly, the lists returned by the -l option are also special, in
2396 Similiarly, the lists returned by the -l option are also special, in
2423 the sense that you can equally invoke the .s attribute on them to
2397 the sense that you can equally invoke the .s attribute on them to
2424 automatically get a whitespace-separated string from their contents:
2398 automatically get a whitespace-separated string from their contents:
2425
2399
2426 In [1]: sc -l b=ls *py
2400 In [1]: sc -l b=ls *py
2427
2401
2428 In [2]: b
2402 In [2]: b
2429 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2403 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2430
2404
2431 In [3]: b.s
2405 In [3]: b.s
2432 Out[3]: 'setup.py win32_manual_post_install.py'
2406 Out[3]: 'setup.py win32_manual_post_install.py'
2433
2407
2434 In summary, both the lists and strings used for ouptut capture have
2408 In summary, both the lists and strings used for ouptut capture have
2435 the following special attributes:
2409 the following special attributes:
2436
2410
2437 .l (or .list) : value as list.
2411 .l (or .list) : value as list.
2438 .n (or .nlstr): value as newline-separated string.
2412 .n (or .nlstr): value as newline-separated string.
2439 .s (or .spstr): value as space-separated string.
2413 .s (or .spstr): value as space-separated string.
2440 """
2414 """
2441
2415
2442 opts,args = self.parse_options(parameter_s,'lv')
2416 opts,args = self.parse_options(parameter_s,'lv')
2443 # Try to get a variable name and command to run
2417 # Try to get a variable name and command to run
2444 try:
2418 try:
2445 # the variable name must be obtained from the parse_options
2419 # the variable name must be obtained from the parse_options
2446 # output, which uses shlex.split to strip options out.
2420 # output, which uses shlex.split to strip options out.
2447 var,_ = args.split('=',1)
2421 var,_ = args.split('=',1)
2448 var = var.strip()
2422 var = var.strip()
2449 # But the the command has to be extracted from the original input
2423 # But the the command has to be extracted from the original input
2450 # parameter_s, not on what parse_options returns, to avoid the
2424 # parameter_s, not on what parse_options returns, to avoid the
2451 # quote stripping which shlex.split performs on it.
2425 # quote stripping which shlex.split performs on it.
2452 _,cmd = parameter_s.split('=',1)
2426 _,cmd = parameter_s.split('=',1)
2453 except ValueError:
2427 except ValueError:
2454 var,cmd = '',''
2428 var,cmd = '',''
2455 if not var:
2429 if not var:
2456 error('you must specify a variable to assign the command to.')
2430 error('you must specify a variable to assign the command to.')
2457 return
2431 return
2458 # If all looks ok, proceed
2432 # If all looks ok, proceed
2459 out,err = self.shell.getoutputerror(cmd)
2433 out,err = self.shell.getoutputerror(cmd)
2460 if err:
2434 if err:
2461 print >> Term.cerr,err
2435 print >> Term.cerr,err
2462 if opts.has_key('l'):
2436 if opts.has_key('l'):
2463 out = SList(out.split('\n'))
2437 out = SList(out.split('\n'))
2464 else:
2438 else:
2465 out = LSString(out)
2439 out = LSString(out)
2466 if opts.has_key('v'):
2440 if opts.has_key('v'):
2467 print '%s ==\n%s' % (var,pformat(out))
2441 print '%s ==\n%s' % (var,pformat(out))
2468 self.shell.user_ns.update({var:out})
2442 self.shell.user_ns.update({var:out})
2469
2443
2470 def magic_sx(self, parameter_s=''):
2444 def magic_sx(self, parameter_s=''):
2471 """Shell execute - run a shell command and capture its output.
2445 """Shell execute - run a shell command and capture its output.
2472
2446
2473 %sx command
2447 %sx command
2474
2448
2475 IPython will run the given command using commands.getoutput(), and
2449 IPython will run the given command using commands.getoutput(), and
2476 return the result formatted as a list (split on '\\n'). Since the
2450 return the result formatted as a list (split on '\\n'). Since the
2477 output is _returned_, it will be stored in ipython's regular output
2451 output is _returned_, it will be stored in ipython's regular output
2478 cache Out[N] and in the '_N' automatic variables.
2452 cache Out[N] and in the '_N' automatic variables.
2479
2453
2480 Notes:
2454 Notes:
2481
2455
2482 1) If an input line begins with '!!', then %sx is automatically
2456 1) If an input line begins with '!!', then %sx is automatically
2483 invoked. That is, while:
2457 invoked. That is, while:
2484 !ls
2458 !ls
2485 causes ipython to simply issue system('ls'), typing
2459 causes ipython to simply issue system('ls'), typing
2486 !!ls
2460 !!ls
2487 is a shorthand equivalent to:
2461 is a shorthand equivalent to:
2488 %sx ls
2462 %sx ls
2489
2463
2490 2) %sx differs from %sc in that %sx automatically splits into a list,
2464 2) %sx differs from %sc in that %sx automatically splits into a list,
2491 like '%sc -l'. The reason for this is to make it as easy as possible
2465 like '%sc -l'. The reason for this is to make it as easy as possible
2492 to process line-oriented shell output via further python commands.
2466 to process line-oriented shell output via further python commands.
2493 %sc is meant to provide much finer control, but requires more
2467 %sc is meant to provide much finer control, but requires more
2494 typing.
2468 typing.
2495
2469
2496 3) Just like %sc -l, this is a list with special attributes:
2470 3) Just like %sc -l, this is a list with special attributes:
2497
2471
2498 .l (or .list) : value as list.
2472 .l (or .list) : value as list.
2499 .n (or .nlstr): value as newline-separated string.
2473 .n (or .nlstr): value as newline-separated string.
2500 .s (or .spstr): value as whitespace-separated string.
2474 .s (or .spstr): value as whitespace-separated string.
2501
2475
2502 This is very useful when trying to use such lists as arguments to
2476 This is very useful when trying to use such lists as arguments to
2503 system commands."""
2477 system commands."""
2504
2478
2505 if parameter_s:
2479 if parameter_s:
2506 out,err = self.shell.getoutputerror(parameter_s)
2480 out,err = self.shell.getoutputerror(parameter_s)
2507 if err:
2481 if err:
2508 print >> Term.cerr,err
2482 print >> Term.cerr,err
2509 return SList(out.split('\n'))
2483 return SList(out.split('\n'))
2510
2484
2511 def magic_bg(self, parameter_s=''):
2485 def magic_bg(self, parameter_s=''):
2512 """Run a job in the background, in a separate thread.
2486 """Run a job in the background, in a separate thread.
2513
2487
2514 For example,
2488 For example,
2515
2489
2516 %bg myfunc(x,y,z=1)
2490 %bg myfunc(x,y,z=1)
2517
2491
2518 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2492 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2519 execution starts, a message will be printed indicating the job
2493 execution starts, a message will be printed indicating the job
2520 number. If your job number is 5, you can use
2494 number. If your job number is 5, you can use
2521
2495
2522 myvar = jobs.result(5) or myvar = jobs[5].result
2496 myvar = jobs.result(5) or myvar = jobs[5].result
2523
2497
2524 to assign this result to variable 'myvar'.
2498 to assign this result to variable 'myvar'.
2525
2499
2526 IPython has a job manager, accessible via the 'jobs' object. You can
2500 IPython has a job manager, accessible via the 'jobs' object. You can
2527 type jobs? to get more information about it, and use jobs.<TAB> to see
2501 type jobs? to get more information about it, and use jobs.<TAB> to see
2528 its attributes. All attributes not starting with an underscore are
2502 its attributes. All attributes not starting with an underscore are
2529 meant for public use.
2503 meant for public use.
2530
2504
2531 In particular, look at the jobs.new() method, which is used to create
2505 In particular, look at the jobs.new() method, which is used to create
2532 new jobs. This magic %bg function is just a convenience wrapper
2506 new jobs. This magic %bg function is just a convenience wrapper
2533 around jobs.new(), for expression-based jobs. If you want to create a
2507 around jobs.new(), for expression-based jobs. If you want to create a
2534 new job with an explicit function object and arguments, you must call
2508 new job with an explicit function object and arguments, you must call
2535 jobs.new() directly.
2509 jobs.new() directly.
2536
2510
2537 The jobs.new docstring also describes in detail several important
2511 The jobs.new docstring also describes in detail several important
2538 caveats associated with a thread-based model for background job
2512 caveats associated with a thread-based model for background job
2539 execution. Type jobs.new? for details.
2513 execution. Type jobs.new? for details.
2540
2514
2541 You can check the status of all jobs with jobs.status().
2515 You can check the status of all jobs with jobs.status().
2542
2516
2543 The jobs variable is set by IPython into the Python builtin namespace.
2517 The jobs variable is set by IPython into the Python builtin namespace.
2544 If you ever declare a variable named 'jobs', you will shadow this
2518 If you ever declare a variable named 'jobs', you will shadow this
2545 name. You can either delete your global jobs variable to regain
2519 name. You can either delete your global jobs variable to regain
2546 access to the job manager, or make a new name and assign it manually
2520 access to the job manager, or make a new name and assign it manually
2547 to the manager (stored in IPython's namespace). For example, to
2521 to the manager (stored in IPython's namespace). For example, to
2548 assign the job manager to the Jobs name, use:
2522 assign the job manager to the Jobs name, use:
2549
2523
2550 Jobs = __builtins__.jobs"""
2524 Jobs = __builtins__.jobs"""
2551
2525
2552 self.shell.jobs.new(parameter_s,self.shell.user_ns)
2526 self.shell.jobs.new(parameter_s,self.shell.user_ns)
2553
2527
2554 def magic_bookmark(self, parameter_s=''):
2528 def magic_bookmark(self, parameter_s=''):
2555 """Manage IPython's bookmark system.
2529 """Manage IPython's bookmark system.
2556
2530
2557 %bookmark <name> - set bookmark to current dir
2531 %bookmark <name> - set bookmark to current dir
2558 %bookmark <name> <dir> - set bookmark to <dir>
2532 %bookmark <name> <dir> - set bookmark to <dir>
2559 %bookmark -l - list all bookmarks
2533 %bookmark -l - list all bookmarks
2560 %bookmark -d <name> - remove bookmark
2534 %bookmark -d <name> - remove bookmark
2561 %bookmark -r - remove all bookmarks
2535 %bookmark -r - remove all bookmarks
2562
2536
2563 You can later on access a bookmarked folder with:
2537 You can later on access a bookmarked folder with:
2564 %cd -b <name>
2538 %cd -b <name>
2565 or simply '%cd <name>' if there is no directory called <name> AND
2539 or simply '%cd <name>' if there is no directory called <name> AND
2566 there is such a bookmark defined.
2540 there is such a bookmark defined.
2567
2541
2568 Your bookmarks persist through IPython sessions, but they are
2542 Your bookmarks persist through IPython sessions, but they are
2569 associated with each profile."""
2543 associated with each profile."""
2570
2544
2571 opts,args = self.parse_options(parameter_s,'drl',mode='list')
2545 opts,args = self.parse_options(parameter_s,'drl',mode='list')
2572 if len(args) > 2:
2546 if len(args) > 2:
2573 error('You can only give at most two arguments')
2547 error('You can only give at most two arguments')
2574 return
2548 return
2575
2549
2576 bkms = self.shell.persist.get('bookmarks',{})
2550 bkms = self.shell.persist.get('bookmarks',{})
2577
2551
2578 if opts.has_key('d'):
2552 if opts.has_key('d'):
2579 try:
2553 try:
2580 todel = args[0]
2554 todel = args[0]
2581 except IndexError:
2555 except IndexError:
2582 error('You must provide a bookmark to delete')
2556 error('You must provide a bookmark to delete')
2583 else:
2557 else:
2584 try:
2558 try:
2585 del bkms[todel]
2559 del bkms[todel]
2586 except:
2560 except:
2587 error("Can't delete bookmark '%s'" % todel)
2561 error("Can't delete bookmark '%s'" % todel)
2588 elif opts.has_key('r'):
2562 elif opts.has_key('r'):
2589 bkms = {}
2563 bkms = {}
2590 elif opts.has_key('l'):
2564 elif opts.has_key('l'):
2591 bks = bkms.keys()
2565 bks = bkms.keys()
2592 bks.sort()
2566 bks.sort()
2593 if bks:
2567 if bks:
2594 size = max(map(len,bks))
2568 size = max(map(len,bks))
2595 else:
2569 else:
2596 size = 0
2570 size = 0
2597 fmt = '%-'+str(size)+'s -> %s'
2571 fmt = '%-'+str(size)+'s -> %s'
2598 print 'Current bookmarks:'
2572 print 'Current bookmarks:'
2599 for bk in bks:
2573 for bk in bks:
2600 print fmt % (bk,bkms[bk])
2574 print fmt % (bk,bkms[bk])
2601 else:
2575 else:
2602 if not args:
2576 if not args:
2603 error("You must specify the bookmark name")
2577 error("You must specify the bookmark name")
2604 elif len(args)==1:
2578 elif len(args)==1:
2605 bkms[args[0]] = os.getcwd()
2579 bkms[args[0]] = os.getcwd()
2606 elif len(args)==2:
2580 elif len(args)==2:
2607 bkms[args[0]] = args[1]
2581 bkms[args[0]] = args[1]
2608 self.persist['bookmarks'] = bkms
2582 self.shell.persist['bookmarks'] = bkms
2609
2583
2610 def magic_pycat(self, parameter_s=''):
2584 def magic_pycat(self, parameter_s=''):
2611 """Show a syntax-highlighted file through a pager.
2585 """Show a syntax-highlighted file through a pager.
2612
2586
2613 This magic is similar to the cat utility, but it will assume the file
2587 This magic is similar to the cat utility, but it will assume the file
2614 to be Python source and will show it with syntax highlighting. """
2588 to be Python source and will show it with syntax highlighting. """
2615
2589
2616 filename = get_py_filename(parameter_s)
2590 filename = get_py_filename(parameter_s)
2617 page(self.shell.colorize(file_read(filename)),
2591 page(self.shell.colorize(file_read(filename)),
2618 screen_lines=self.shell.rc.screen_length)
2592 screen_lines=self.shell.rc.screen_length)
2619
2593
2620 # end Magic
2594 # end Magic
@@ -1,578 +1,583 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 Classes for handling input/output prompts.
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 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
8 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
9 #
9 #
10 # Distributed under the terms of the BSD License. The full license is in
10 # Distributed under the terms of the BSD License. The full license is in
11 # the file COPYING, distributed as part of this software.
11 # the file COPYING, distributed as part of this software.
12 #*****************************************************************************
12 #*****************************************************************************
13
13
14 from IPython import Release
14 from IPython import Release
15 __author__ = '%s <%s>' % Release.authors['Fernando']
15 __author__ = '%s <%s>' % Release.authors['Fernando']
16 __license__ = Release.license
16 __license__ = Release.license
17 __version__ = Release.version
17 __version__ = Release.version
18
18
19 #****************************************************************************
19 #****************************************************************************
20 # Required modules
20 # Required modules
21 import __builtin__
21 import __builtin__
22 import os
22 import os
23 import socket
23 import socket
24 import sys
24 import sys
25 import time
25 import time
26 from pprint import pprint,pformat
26 from pprint import pprint,pformat
27
27
28 # IPython's own
28 # IPython's own
29 from IPython.genutils import *
29 from IPython.genutils import *
30 from IPython.Struct import Struct
30 from IPython.Struct import Struct
31 from IPython.Magic import Macro
31 from IPython.Magic import Macro
32 from IPython.Itpl import ItplNS
32 from IPython.Itpl import ItplNS
33 from IPython import ColorANSI
33 from IPython import ColorANSI
34
34
35 #****************************************************************************
35 #****************************************************************************
36 #Color schemes for Prompts.
36 #Color schemes for Prompts.
37
37
38 PromptColors = ColorANSI.ColorSchemeTable()
38 PromptColors = ColorANSI.ColorSchemeTable()
39 InputColors = ColorANSI.InputTermColors # just a shorthand
39 InputColors = ColorANSI.InputTermColors # just a shorthand
40 Colors = ColorANSI.TermColors # just a shorthand
40 Colors = ColorANSI.TermColors # just a shorthand
41
41
42 PromptColors.add_scheme(ColorANSI.ColorScheme(
42 PromptColors.add_scheme(ColorANSI.ColorScheme(
43 'NoColor',
43 'NoColor',
44 in_prompt = InputColors.NoColor, # Input prompt
44 in_prompt = InputColors.NoColor, # Input prompt
45 in_number = InputColors.NoColor, # Input prompt number
45 in_number = InputColors.NoColor, # Input prompt number
46 in_prompt2 = InputColors.NoColor, # Continuation prompt
46 in_prompt2 = InputColors.NoColor, # Continuation prompt
47 in_normal = InputColors.NoColor, # color off (usu. Colors.Normal)
47 in_normal = InputColors.NoColor, # color off (usu. Colors.Normal)
48
48
49 out_prompt = Colors.NoColor, # Output prompt
49 out_prompt = Colors.NoColor, # Output prompt
50 out_number = Colors.NoColor, # Output prompt number
50 out_number = Colors.NoColor, # Output prompt number
51
51
52 normal = Colors.NoColor # color off (usu. Colors.Normal)
52 normal = Colors.NoColor # color off (usu. Colors.Normal)
53 ))
53 ))
54
54
55 # make some schemes as instances so we can copy them for modification easily:
55 # make some schemes as instances so we can copy them for modification easily:
56 __PColLinux = ColorANSI.ColorScheme(
56 __PColLinux = ColorANSI.ColorScheme(
57 'Linux',
57 'Linux',
58 in_prompt = InputColors.Green,
58 in_prompt = InputColors.Green,
59 in_number = InputColors.LightGreen,
59 in_number = InputColors.LightGreen,
60 in_prompt2 = InputColors.Green,
60 in_prompt2 = InputColors.Green,
61 in_normal = InputColors.Normal, # color off (usu. Colors.Normal)
61 in_normal = InputColors.Normal, # color off (usu. Colors.Normal)
62
62
63 out_prompt = Colors.Red,
63 out_prompt = Colors.Red,
64 out_number = Colors.LightRed,
64 out_number = Colors.LightRed,
65
65
66 normal = Colors.Normal
66 normal = Colors.Normal
67 )
67 )
68 # Don't forget to enter it into the table!
68 # Don't forget to enter it into the table!
69 PromptColors.add_scheme(__PColLinux)
69 PromptColors.add_scheme(__PColLinux)
70
70
71 # Slightly modified Linux for light backgrounds
71 # Slightly modified Linux for light backgrounds
72 __PColLightBG = __PColLinux.copy('LightBG')
72 __PColLightBG = __PColLinux.copy('LightBG')
73
73
74 __PColLightBG.colors.update(
74 __PColLightBG.colors.update(
75 in_prompt = InputColors.Blue,
75 in_prompt = InputColors.Blue,
76 in_number = InputColors.LightBlue,
76 in_number = InputColors.LightBlue,
77 in_prompt2 = InputColors.Blue
77 in_prompt2 = InputColors.Blue
78 )
78 )
79 PromptColors.add_scheme(__PColLightBG)
79 PromptColors.add_scheme(__PColLightBG)
80
80
81 del Colors,InputColors
81 del Colors,InputColors
82
82
83 #-----------------------------------------------------------------------------
83 #-----------------------------------------------------------------------------
84 def multiple_replace(dict, text):
84 def multiple_replace(dict, text):
85 """ Replace in 'text' all occurences of any key in the given
85 """ Replace in 'text' all occurences of any key in the given
86 dictionary by its corresponding value. Returns the new string."""
86 dictionary by its corresponding value. Returns the new string."""
87
87
88 # Function by Xavier Defrang, originally found at:
88 # Function by Xavier Defrang, originally found at:
89 # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/81330
89 # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/81330
90
90
91 # Create a regular expression from the dictionary keys
91 # Create a regular expression from the dictionary keys
92 regex = re.compile("(%s)" % "|".join(map(re.escape, dict.keys())))
92 regex = re.compile("(%s)" % "|".join(map(re.escape, dict.keys())))
93 # For each match, look-up corresponding value in dictionary
93 # For each match, look-up corresponding value in dictionary
94 return regex.sub(lambda mo: dict[mo.string[mo.start():mo.end()]], text)
94 return regex.sub(lambda mo: dict[mo.string[mo.start():mo.end()]], text)
95
95
96 #-----------------------------------------------------------------------------
96 #-----------------------------------------------------------------------------
97 # Special characters that can be used in prompt templates, mainly bash-like
97 # Special characters that can be used in prompt templates, mainly bash-like
98
98
99 # If $HOME isn't defined (Windows), make it an absurd string so that it can
99 # If $HOME isn't defined (Windows), make it an absurd string so that it can
100 # never be expanded out into '~'. Basically anything which can never be a
100 # never be expanded out into '~'. Basically anything which can never be a
101 # reasonable directory name will do, we just want the $HOME -> '~' operation
101 # reasonable directory name will do, we just want the $HOME -> '~' operation
102 # to become a no-op. We pre-compute $HOME here so it's not done on every
102 # to become a no-op. We pre-compute $HOME here so it's not done on every
103 # prompt call.
103 # prompt call.
104
104
105 # FIXME:
105 # FIXME:
106
106
107 # - This should be turned into a class which does proper namespace management,
107 # - This should be turned into a class which does proper namespace management,
108 # since the prompt specials need to be evaluated in a certain namespace.
108 # since the prompt specials need to be evaluated in a certain namespace.
109 # Currently it's just globals, which need to be managed manually by code
109 # Currently it's just globals, which need to be managed manually by code
110 # below.
110 # below.
111
111
112 # - I also need to split up the color schemes from the prompt specials
112 # - I also need to split up the color schemes from the prompt specials
113 # somehow. I don't have a clean design for that quite yet.
113 # somehow. I don't have a clean design for that quite yet.
114
114
115 HOME = os.environ.get("HOME","//////:::::ZZZZZ,,,~~~")
115 HOME = os.environ.get("HOME","//////:::::ZZZZZ,,,~~~")
116
116
117 # We precompute a few more strings here for the prompt_specials, which are
117 # We precompute a few more strings here for the prompt_specials, which are
118 # fixed once ipython starts. This reduces the runtime overhead of computing
118 # fixed once ipython starts. This reduces the runtime overhead of computing
119 # prompt strings.
119 # prompt strings.
120 USER = os.environ.get("USER")
120 USER = os.environ.get("USER")
121 HOSTNAME = socket.gethostname()
121 HOSTNAME = socket.gethostname()
122 HOSTNAME_SHORT = HOSTNAME.split(".")[0]
122 HOSTNAME_SHORT = HOSTNAME.split(".")[0]
123 ROOT_SYMBOL = "$#"[os.name=='nt' or os.getuid()==0]
123 ROOT_SYMBOL = "$#"[os.name=='nt' or os.getuid()==0]
124
124
125 prompt_specials_color = {
125 prompt_specials_color = {
126 # Prompt/history count
126 # Prompt/history count
127 '%n' : '${self.col_num}' '${self.cache.prompt_count}' '${self.col_p}',
127 '%n' : '${self.col_num}' '${self.cache.prompt_count}' '${self.col_p}',
128 '\\#': '${self.col_num}' '${self.cache.prompt_count}' '${self.col_p}',
128 '\\#': '${self.col_num}' '${self.cache.prompt_count}' '${self.col_p}',
129 # Prompt/history count, with the actual digits replaced by dots. Used
129 # Prompt/history count, with the actual digits replaced by dots. Used
130 # mainly in continuation prompts (prompt_in2)
130 # mainly in continuation prompts (prompt_in2)
131 '\\D': '${"."*len(str(self.cache.prompt_count))}',
131 '\\D': '${"."*len(str(self.cache.prompt_count))}',
132 # Current working directory
132 # Current working directory
133 '\\w': '${os.getcwd()}',
133 '\\w': '${os.getcwd()}',
134 # Current time
134 # Current time
135 '\\t' : '${time.strftime("%H:%M:%S")}',
135 '\\t' : '${time.strftime("%H:%M:%S")}',
136 # Basename of current working directory.
136 # Basename of current working directory.
137 # (use os.sep to make this portable across OSes)
137 # (use os.sep to make this portable across OSes)
138 '\\W' : '${os.getcwd().split("%s")[-1]}' % os.sep,
138 '\\W' : '${os.getcwd().split("%s")[-1]}' % os.sep,
139 # These X<N> are an extension to the normal bash prompts. They return
139 # These X<N> are an extension to the normal bash prompts. They return
140 # N terms of the path, after replacing $HOME with '~'
140 # N terms of the path, after replacing $HOME with '~'
141 '\\X0': '${os.getcwd().replace("%s","~")}' % HOME,
141 '\\X0': '${os.getcwd().replace("%s","~")}' % HOME,
142 '\\X1': '${self.cwd_filt(1)}',
142 '\\X1': '${self.cwd_filt(1)}',
143 '\\X2': '${self.cwd_filt(2)}',
143 '\\X2': '${self.cwd_filt(2)}',
144 '\\X3': '${self.cwd_filt(3)}',
144 '\\X3': '${self.cwd_filt(3)}',
145 '\\X4': '${self.cwd_filt(4)}',
145 '\\X4': '${self.cwd_filt(4)}',
146 '\\X5': '${self.cwd_filt(5)}',
146 '\\X5': '${self.cwd_filt(5)}',
147 # Y<N> are similar to X<N>, but they show '~' if it's the directory
147 # Y<N> are similar to X<N>, but they show '~' if it's the directory
148 # N+1 in the list. Somewhat like %cN in tcsh.
148 # N+1 in the list. Somewhat like %cN in tcsh.
149 '\\Y0': '${self.cwd_filt2(0)}',
149 '\\Y0': '${self.cwd_filt2(0)}',
150 '\\Y1': '${self.cwd_filt2(1)}',
150 '\\Y1': '${self.cwd_filt2(1)}',
151 '\\Y2': '${self.cwd_filt2(2)}',
151 '\\Y2': '${self.cwd_filt2(2)}',
152 '\\Y3': '${self.cwd_filt2(3)}',
152 '\\Y3': '${self.cwd_filt2(3)}',
153 '\\Y4': '${self.cwd_filt2(4)}',
153 '\\Y4': '${self.cwd_filt2(4)}',
154 '\\Y5': '${self.cwd_filt2(5)}',
154 '\\Y5': '${self.cwd_filt2(5)}',
155 # Hostname up to first .
155 # Hostname up to first .
156 '\\h': HOSTNAME_SHORT,
156 '\\h': HOSTNAME_SHORT,
157 # Full hostname
157 # Full hostname
158 '\\H': HOSTNAME,
158 '\\H': HOSTNAME,
159 # Username of current user
159 # Username of current user
160 '\\u': USER,
160 '\\u': USER,
161 # Escaped '\'
161 # Escaped '\'
162 '\\\\': '\\',
162 '\\\\': '\\',
163 # Newline
163 # Newline
164 '\\n': '\n',
164 '\\n': '\n',
165 # Carriage return
165 # Carriage return
166 '\\r': '\r',
166 '\\r': '\r',
167 # Release version
167 # Release version
168 '\\v': __version__,
168 '\\v': __version__,
169 # Root symbol ($ or #)
169 # Root symbol ($ or #)
170 '\\$': ROOT_SYMBOL,
170 '\\$': ROOT_SYMBOL,
171 }
171 }
172
172
173 # A copy of the prompt_specials dictionary but with all color escapes removed,
173 # A copy of the prompt_specials dictionary but with all color escapes removed,
174 # so we can correctly compute the prompt length for the auto_rewrite method.
174 # so we can correctly compute the prompt length for the auto_rewrite method.
175 prompt_specials_nocolor = prompt_specials_color.copy()
175 prompt_specials_nocolor = prompt_specials_color.copy()
176 prompt_specials_nocolor['%n'] = '${self.cache.prompt_count}'
176 prompt_specials_nocolor['%n'] = '${self.cache.prompt_count}'
177 prompt_specials_nocolor['\\#'] = '${self.cache.prompt_count}'
177 prompt_specials_nocolor['\\#'] = '${self.cache.prompt_count}'
178
178
179 # Add in all the InputTermColors color escapes as valid prompt characters.
179 # Add in all the InputTermColors color escapes as valid prompt characters.
180 # They all get added as \\C_COLORNAME, so that we don't have any conflicts
180 # They all get added as \\C_COLORNAME, so that we don't have any conflicts
181 # with a color name which may begin with a letter used by any other of the
181 # with a color name which may begin with a letter used by any other of the
182 # allowed specials. This of course means that \\C will never be allowed for
182 # allowed specials. This of course means that \\C will never be allowed for
183 # anything else.
183 # anything else.
184 input_colors = ColorANSI.InputTermColors
184 input_colors = ColorANSI.InputTermColors
185 for _color in dir(input_colors):
185 for _color in dir(input_colors):
186 if _color[0] != '_':
186 if _color[0] != '_':
187 c_name = '\\C_'+_color
187 c_name = '\\C_'+_color
188 prompt_specials_color[c_name] = getattr(input_colors,_color)
188 prompt_specials_color[c_name] = getattr(input_colors,_color)
189 prompt_specials_nocolor[c_name] = ''
189 prompt_specials_nocolor[c_name] = ''
190
190
191 # we default to no color for safety. Note that prompt_specials is a global
191 # we default to no color for safety. Note that prompt_specials is a global
192 # variable used by all prompt objects.
192 # variable used by all prompt objects.
193 prompt_specials = prompt_specials_nocolor
193 prompt_specials = prompt_specials_nocolor
194
194
195 #-----------------------------------------------------------------------------
195 #-----------------------------------------------------------------------------
196 def str_safe(arg):
196 def str_safe(arg):
197 """Convert to a string, without ever raising an exception.
197 """Convert to a string, without ever raising an exception.
198
198
199 If str(arg) fails, <ERROR: ... > is returned, where ... is the exception
199 If str(arg) fails, <ERROR: ... > is returned, where ... is the exception
200 error message."""
200 error message."""
201
201
202 try:
202 try:
203 out = str(arg)
203 out = str(arg)
204 except UnicodeError:
204 except UnicodeError:
205 try:
205 try:
206 out = arg.encode('utf_8','replace')
206 out = arg.encode('utf_8','replace')
207 except Exception,msg:
207 except Exception,msg:
208 # let's keep this little duplication here, so that the most common
208 # let's keep this little duplication here, so that the most common
209 # case doesn't suffer from a double try wrapping.
209 # case doesn't suffer from a double try wrapping.
210 out = '<ERROR: %s>' % msg
210 out = '<ERROR: %s>' % msg
211 except Exception,msg:
211 except Exception,msg:
212 out = '<ERROR: %s>' % msg
212 out = '<ERROR: %s>' % msg
213 return out
213 return out
214
214
215 class BasePrompt:
215 class BasePrompt:
216 """Interactive prompt similar to Mathematica's."""
216 """Interactive prompt similar to Mathematica's."""
217 def __init__(self,cache,sep,prompt,pad_left=False):
217 def __init__(self,cache,sep,prompt,pad_left=False):
218
218
219 # Hack: we access information about the primary prompt through the
219 # Hack: we access information about the primary prompt through the
220 # cache argument. We need this, because we want the secondary prompt
220 # cache argument. We need this, because we want the secondary prompt
221 # to be aligned with the primary one. Color table info is also shared
221 # to be aligned with the primary one. Color table info is also shared
222 # by all prompt classes through the cache. Nice OO spaghetti code!
222 # by all prompt classes through the cache. Nice OO spaghetti code!
223 self.cache = cache
223 self.cache = cache
224 self.sep = sep
224 self.sep = sep
225
225
226 # regexp to count the number of spaces at the end of a prompt
226 # regexp to count the number of spaces at the end of a prompt
227 # expression, useful for prompt auto-rewriting
227 # expression, useful for prompt auto-rewriting
228 self.rspace = re.compile(r'(\s*)$')
228 self.rspace = re.compile(r'(\s*)$')
229 # Flag to left-pad prompt strings to match the length of the primary
229 # Flag to left-pad prompt strings to match the length of the primary
230 # prompt
230 # prompt
231 self.pad_left = pad_left
231 self.pad_left = pad_left
232 # Set template to create each actual prompt (where numbers change)
232 # Set template to create each actual prompt (where numbers change)
233 self.p_template = prompt
233 self.p_template = prompt
234 self.set_p_str()
234 self.set_p_str()
235
235
236 def set_p_str(self):
236 def set_p_str(self):
237 """ Set the interpolating prompt strings.
237 """ Set the interpolating prompt strings.
238
238
239 This must be called every time the color settings change, because the
239 This must be called every time the color settings change, because the
240 prompt_specials global may have changed."""
240 prompt_specials global may have changed."""
241
241
242 import os,time # needed in locals for prompt string handling
242 import os,time # needed in locals for prompt string handling
243 loc = locals()
243 loc = locals()
244 self.p_str = ItplNS('%s%s%s' %
244 self.p_str = ItplNS('%s%s%s' %
245 ('${self.sep}${self.col_p}',
245 ('${self.sep}${self.col_p}',
246 multiple_replace(prompt_specials, self.p_template),
246 multiple_replace(prompt_specials, self.p_template),
247 '${self.col_norm}'),self.cache.user_ns,loc)
247 '${self.col_norm}'),self.cache.user_ns,loc)
248
248
249 self.p_str_nocolor = ItplNS(multiple_replace(prompt_specials_nocolor,
249 self.p_str_nocolor = ItplNS(multiple_replace(prompt_specials_nocolor,
250 self.p_template),
250 self.p_template),
251 self.cache.user_ns,loc)
251 self.cache.user_ns,loc)
252
252
253 def write(self,msg): # dbg
253 def write(self,msg): # dbg
254 sys.stdout.write(msg)
254 sys.stdout.write(msg)
255 return ''
255 return ''
256
256
257 def __str__(self):
257 def __str__(self):
258 """Return a string form of the prompt.
258 """Return a string form of the prompt.
259
259
260 This for is useful for continuation and output prompts, since it is
260 This for is useful for continuation and output prompts, since it is
261 left-padded to match lengths with the primary one (if the
261 left-padded to match lengths with the primary one (if the
262 self.pad_left attribute is set)."""
262 self.pad_left attribute is set)."""
263
263
264 out_str = str_safe(self.p_str)
264 out_str = str_safe(self.p_str)
265 if self.pad_left:
265 if self.pad_left:
266 # We must find the amount of padding required to match lengths,
266 # We must find the amount of padding required to match lengths,
267 # taking the color escapes (which are invisible on-screen) into
267 # taking the color escapes (which are invisible on-screen) into
268 # account.
268 # account.
269 esc_pad = len(out_str) - len(str_safe(self.p_str_nocolor))
269 esc_pad = len(out_str) - len(str_safe(self.p_str_nocolor))
270 format = '%%%ss' % (len(str(self.cache.last_prompt))+esc_pad)
270 format = '%%%ss' % (len(str(self.cache.last_prompt))+esc_pad)
271 return format % out_str
271 return format % out_str
272 else:
272 else:
273 return out_str
273 return out_str
274
274
275 # these path filters are put in as methods so that we can control the
275 # these path filters are put in as methods so that we can control the
276 # namespace where the prompt strings get evaluated
276 # namespace where the prompt strings get evaluated
277 def cwd_filt(self,depth):
277 def cwd_filt(self,depth):
278 """Return the last depth elements of the current working directory.
278 """Return the last depth elements of the current working directory.
279
279
280 $HOME is always replaced with '~'.
280 $HOME is always replaced with '~'.
281 If depth==0, the full path is returned."""
281 If depth==0, the full path is returned."""
282
282
283 cwd = os.getcwd().replace(HOME,"~")
283 cwd = os.getcwd().replace(HOME,"~")
284 out = os.sep.join(cwd.split(os.sep)[-depth:])
284 out = os.sep.join(cwd.split(os.sep)[-depth:])
285 if out:
285 if out:
286 return out
286 return out
287 else:
287 else:
288 return os.sep
288 return os.sep
289
289
290 def cwd_filt2(self,depth):
290 def cwd_filt2(self,depth):
291 """Return the last depth elements of the current working directory.
291 """Return the last depth elements of the current working directory.
292
292
293 $HOME is always replaced with '~'.
293 $HOME is always replaced with '~'.
294 If depth==0, the full path is returned."""
294 If depth==0, the full path is returned."""
295
295
296 cwd = os.getcwd().replace(HOME,"~").split(os.sep)
296 cwd = os.getcwd().replace(HOME,"~").split(os.sep)
297 if '~' in cwd and len(cwd) == depth+1:
297 if '~' in cwd and len(cwd) == depth+1:
298 depth += 1
298 depth += 1
299 out = os.sep.join(cwd[-depth:])
299 out = os.sep.join(cwd[-depth:])
300 if out:
300 if out:
301 return out
301 return out
302 else:
302 else:
303 return os.sep
303 return os.sep
304
304
305 class Prompt1(BasePrompt):
305 class Prompt1(BasePrompt):
306 """Input interactive prompt similar to Mathematica's."""
306 """Input interactive prompt similar to Mathematica's."""
307
307
308 def __init__(self,cache,sep='\n',prompt='In [\\#]: ',pad_left=True):
308 def __init__(self,cache,sep='\n',prompt='In [\\#]: ',pad_left=True):
309 BasePrompt.__init__(self,cache,sep,prompt,pad_left)
309 BasePrompt.__init__(self,cache,sep,prompt,pad_left)
310
310
311 def set_colors(self):
311 def set_colors(self):
312 self.set_p_str()
312 self.set_p_str()
313 Colors = self.cache.color_table.active_colors # shorthand
313 Colors = self.cache.color_table.active_colors # shorthand
314 self.col_p = Colors.in_prompt
314 self.col_p = Colors.in_prompt
315 self.col_num = Colors.in_number
315 self.col_num = Colors.in_number
316 self.col_norm = Colors.in_normal
316 self.col_norm = Colors.in_normal
317 # We need a non-input version of these escapes for the '--->'
317 # We need a non-input version of these escapes for the '--->'
318 # auto-call prompts used in the auto_rewrite() method.
318 # auto-call prompts used in the auto_rewrite() method.
319 self.col_p_ni = self.col_p.replace('\001','').replace('\002','')
319 self.col_p_ni = self.col_p.replace('\001','').replace('\002','')
320 self.col_norm_ni = Colors.normal
320 self.col_norm_ni = Colors.normal
321
321
322 def __str__(self):
322 def __str__(self):
323 self.cache.prompt_count += 1
323 self.cache.prompt_count += 1
324 self.cache.last_prompt = str_safe(self.p_str_nocolor).split('\n')[-1]
324 self.cache.last_prompt = str_safe(self.p_str_nocolor).split('\n')[-1]
325 return str_safe(self.p_str)
325 return str_safe(self.p_str)
326
326
327 def auto_rewrite(self):
327 def auto_rewrite(self):
328 """Print a string of the form '--->' which lines up with the previous
328 """Print a string of the form '--->' which lines up with the previous
329 input string. Useful for systems which re-write the user input when
329 input string. Useful for systems which re-write the user input when
330 handling automatically special syntaxes."""
330 handling automatically special syntaxes."""
331
331
332 curr = str(self.cache.last_prompt)
332 curr = str(self.cache.last_prompt)
333 nrspaces = len(self.rspace.search(curr).group())
333 nrspaces = len(self.rspace.search(curr).group())
334 return '%s%s>%s%s' % (self.col_p_ni,'-'*(len(curr)-nrspaces-1),
334 return '%s%s>%s%s' % (self.col_p_ni,'-'*(len(curr)-nrspaces-1),
335 ' '*nrspaces,self.col_norm_ni)
335 ' '*nrspaces,self.col_norm_ni)
336
336
337 class PromptOut(BasePrompt):
337 class PromptOut(BasePrompt):
338 """Output interactive prompt similar to Mathematica's."""
338 """Output interactive prompt similar to Mathematica's."""
339
339
340 def __init__(self,cache,sep='',prompt='Out[\\#]: ',pad_left=True):
340 def __init__(self,cache,sep='',prompt='Out[\\#]: ',pad_left=True):
341 BasePrompt.__init__(self,cache,sep,prompt,pad_left)
341 BasePrompt.__init__(self,cache,sep,prompt,pad_left)
342 if not self.p_template:
342 if not self.p_template:
343 self.__str__ = lambda: ''
343 self.__str__ = lambda: ''
344
344
345 def set_colors(self):
345 def set_colors(self):
346 self.set_p_str()
346 self.set_p_str()
347 Colors = self.cache.color_table.active_colors # shorthand
347 Colors = self.cache.color_table.active_colors # shorthand
348 self.col_p = Colors.out_prompt
348 self.col_p = Colors.out_prompt
349 self.col_num = Colors.out_number
349 self.col_num = Colors.out_number
350 self.col_norm = Colors.normal
350 self.col_norm = Colors.normal
351
351
352 class Prompt2(BasePrompt):
352 class Prompt2(BasePrompt):
353 """Interactive continuation prompt."""
353 """Interactive continuation prompt."""
354
354
355 def __init__(self,cache,prompt=' .\\D.: ',pad_left=True):
355 def __init__(self,cache,prompt=' .\\D.: ',pad_left=True):
356 self.cache = cache
356 self.cache = cache
357 self.p_template = prompt
357 self.p_template = prompt
358 self.pad_left = pad_left
358 self.pad_left = pad_left
359 self.set_p_str()
359 self.set_p_str()
360
360
361 def set_p_str(self):
361 def set_p_str(self):
362 import os,time # needed in locals for prompt string handling
362 import os,time # needed in locals for prompt string handling
363 loc = locals()
363 loc = locals()
364 self.p_str = ItplNS('%s%s%s' %
364 self.p_str = ItplNS('%s%s%s' %
365 ('${self.col_p2}',
365 ('${self.col_p2}',
366 multiple_replace(prompt_specials, self.p_template),
366 multiple_replace(prompt_specials, self.p_template),
367 '$self.col_norm'),
367 '$self.col_norm'),
368 self.cache.user_ns,loc)
368 self.cache.user_ns,loc)
369 self.p_str_nocolor = ItplNS(multiple_replace(prompt_specials_nocolor,
369 self.p_str_nocolor = ItplNS(multiple_replace(prompt_specials_nocolor,
370 self.p_template),
370 self.p_template),
371 self.cache.user_ns,loc)
371 self.cache.user_ns,loc)
372
372
373 def set_colors(self):
373 def set_colors(self):
374 self.set_p_str()
374 self.set_p_str()
375 Colors = self.cache.color_table.active_colors
375 Colors = self.cache.color_table.active_colors
376 self.col_p2 = Colors.in_prompt2
376 self.col_p2 = Colors.in_prompt2
377 self.col_norm = Colors.in_normal
377 self.col_norm = Colors.in_normal
378 # FIXME (2004-06-16) HACK: prevent crashes for users who haven't
378 # FIXME (2004-06-16) HACK: prevent crashes for users who haven't
379 # updated their prompt_in2 definitions. Remove eventually.
379 # updated their prompt_in2 definitions. Remove eventually.
380 self.col_p = Colors.out_prompt
380 self.col_p = Colors.out_prompt
381 self.col_num = Colors.out_number
381 self.col_num = Colors.out_number
382
382
383 #-----------------------------------------------------------------------------
383 #-----------------------------------------------------------------------------
384 class CachedOutput:
384 class CachedOutput:
385 """Class for printing output from calculations while keeping a cache of
385 """Class for printing output from calculations while keeping a cache of
386 reults. It dynamically creates global variables prefixed with _ which
386 reults. It dynamically creates global variables prefixed with _ which
387 contain these results.
387 contain these results.
388
388
389 Meant to be used as a sys.displayhook replacement, providing numbered
389 Meant to be used as a sys.displayhook replacement, providing numbered
390 prompts and cache services.
390 prompts and cache services.
391
391
392 Initialize with initial and final values for cache counter (this defines
392 Initialize with initial and final values for cache counter (this defines
393 the maximum size of the cache."""
393 the maximum size of the cache."""
394
394
395 def __init__(self,cache_size,Pprint,colors='NoColor',input_sep='\n',
395 def __init__(self,shell,cache_size,Pprint,
396 output_sep='\n',output_sep2='',user_ns={},
396 colors='NoColor',input_sep='\n',
397 ps1 = None, ps2 = None,ps_out = None,
397 output_sep='\n',output_sep2='',
398 input_hist = None,pad_left=True):
398 ps1 = None, ps2 = None,ps_out = None,pad_left=True):
399
399
400 cache_size_min = 20
400 cache_size_min = 20
401 if cache_size <= 0:
401 if cache_size <= 0:
402 self.do_full_cache = 0
402 self.do_full_cache = 0
403 cache_size = 0
403 cache_size = 0
404 elif cache_size < cache_size_min:
404 elif cache_size < cache_size_min:
405 self.do_full_cache = 0
405 self.do_full_cache = 0
406 cache_size = 0
406 cache_size = 0
407 warn('caching was disabled (min value for cache size is %s).' %
407 warn('caching was disabled (min value for cache size is %s).' %
408 cache_size_min,level=3)
408 cache_size_min,level=3)
409 else:
409 else:
410 self.do_full_cache = 1
410 self.do_full_cache = 1
411
411
412 self.cache_size = cache_size
412 self.cache_size = cache_size
413 self.input_sep = input_sep
413 self.input_sep = input_sep
414
414
415 # we need a reference to the user-level namespace
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 # and to the user's input
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 # Set input prompt strings and colors
423 # Set input prompt strings and colors
421 if cache_size == 0:
424 if cache_size == 0:
422 if ps1.find('%n') > -1 or ps1.find('\\#') > -1: ps1 = '>>> '
425 if ps1.find('%n') > -1 or ps1.find('\\#') > -1: ps1 = '>>> '
423 if ps2.find('%n') > -1 or ps2.find('\\#') > -1: ps2 = '... '
426 if ps2.find('%n') > -1 or ps2.find('\\#') > -1: ps2 = '... '
424 self.ps1_str = self._set_prompt_str(ps1,'In [\\#]: ','>>> ')
427 self.ps1_str = self._set_prompt_str(ps1,'In [\\#]: ','>>> ')
425 self.ps2_str = self._set_prompt_str(ps2,' .\\D.: ','... ')
428 self.ps2_str = self._set_prompt_str(ps2,' .\\D.: ','... ')
426 self.ps_out_str = self._set_prompt_str(ps_out,'Out[\\#]: ','')
429 self.ps_out_str = self._set_prompt_str(ps_out,'Out[\\#]: ','')
427
430
428 self.color_table = PromptColors
431 self.color_table = PromptColors
429 self.prompt1 = Prompt1(self,sep=input_sep,prompt=self.ps1_str,
432 self.prompt1 = Prompt1(self,sep=input_sep,prompt=self.ps1_str,
430 pad_left=pad_left)
433 pad_left=pad_left)
431 self.prompt2 = Prompt2(self,prompt=self.ps2_str,pad_left=pad_left)
434 self.prompt2 = Prompt2(self,prompt=self.ps2_str,pad_left=pad_left)
432 self.prompt_out = PromptOut(self,sep='',prompt=self.ps_out_str,
435 self.prompt_out = PromptOut(self,sep='',prompt=self.ps_out_str,
433 pad_left=pad_left)
436 pad_left=pad_left)
434 self.set_colors(colors)
437 self.set_colors(colors)
435
438
436 # other more normal stuff
439 # other more normal stuff
437 # b/c each call to the In[] prompt raises it by 1, even the first.
440 # b/c each call to the In[] prompt raises it by 1, even the first.
438 self.prompt_count = 0
441 self.prompt_count = 0
439 self.cache_count = 1
442 self.cache_count = 1
440 # Store the last prompt string each time, we need it for aligning
443 # Store the last prompt string each time, we need it for aligning
441 # continuation and auto-rewrite prompts
444 # continuation and auto-rewrite prompts
442 self.last_prompt = ''
445 self.last_prompt = ''
443 self.entries = [None] # output counter starts at 1 for the user
446 self.entries = [None] # output counter starts at 1 for the user
444 self.Pprint = Pprint
447 self.Pprint = Pprint
445 self.output_sep = output_sep
448 self.output_sep = output_sep
446 self.output_sep2 = output_sep2
449 self.output_sep2 = output_sep2
447 self._,self.__,self.___ = '','',''
450 self._,self.__,self.___ = '','',''
448 self.pprint_types = map(type,[(),[],{}])
451 self.pprint_types = map(type,[(),[],{}])
449
452
450 # these are deliberately global:
453 # these are deliberately global:
451 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
454 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
452 self.user_ns.update(to_user_ns)
455 self.user_ns.update(to_user_ns)
453
456
454 def _set_prompt_str(self,p_str,cache_def,no_cache_def):
457 def _set_prompt_str(self,p_str,cache_def,no_cache_def):
455 if p_str is None:
458 if p_str is None:
456 if self.do_full_cache:
459 if self.do_full_cache:
457 return cache_def
460 return cache_def
458 else:
461 else:
459 return no_cache_def
462 return no_cache_def
460 else:
463 else:
461 return p_str
464 return p_str
462
465
463 def set_colors(self,colors):
466 def set_colors(self,colors):
464 """Set the active color scheme and configure colors for the three
467 """Set the active color scheme and configure colors for the three
465 prompt subsystems."""
468 prompt subsystems."""
466
469
467 # FIXME: the prompt_specials global should be gobbled inside this
470 # FIXME: the prompt_specials global should be gobbled inside this
468 # class instead. Do it when cleaning up the whole 3-prompt system.
471 # class instead. Do it when cleaning up the whole 3-prompt system.
469 global prompt_specials
472 global prompt_specials
470 if colors.lower()=='nocolor':
473 if colors.lower()=='nocolor':
471 prompt_specials = prompt_specials_nocolor
474 prompt_specials = prompt_specials_nocolor
472 else:
475 else:
473 prompt_specials = prompt_specials_color
476 prompt_specials = prompt_specials_color
474
477
475 self.color_table.set_active_scheme(colors)
478 self.color_table.set_active_scheme(colors)
476 self.prompt1.set_colors()
479 self.prompt1.set_colors()
477 self.prompt2.set_colors()
480 self.prompt2.set_colors()
478 self.prompt_out.set_colors()
481 self.prompt_out.set_colors()
479
482
480 def __call__(self,arg=None):
483 def __call__(self,arg=None):
481 """Printing with history cache management.
484 """Printing with history cache management.
482
485
483 This is invoked everytime the interpreter needs to print, and is
486 This is invoked everytime the interpreter needs to print, and is
484 activated by setting the variable sys.displayhook to it."""
487 activated by setting the variable sys.displayhook to it."""
485
488
486 # If something injected a '_' variable in __builtin__, delete
489 # If something injected a '_' variable in __builtin__, delete
487 # ipython's automatic one so we don't clobber that. gettext() in
490 # ipython's automatic one so we don't clobber that. gettext() in
488 # particular uses _, so we need to stay away from it.
491 # particular uses _, so we need to stay away from it.
489 if '_' in __builtin__.__dict__:
492 if '_' in __builtin__.__dict__:
490 try:
493 try:
491 del self.user_ns['_']
494 del self.user_ns['_']
492 except KeyError:
495 except KeyError:
493 pass
496 pass
494 if arg is not None:
497 if arg is not None:
495 cout_write = Term.cout.write # fast lookup
498 cout_write = Term.cout.write # fast lookup
496 # first handle the cache and counters
499 # first handle the cache and counters
497 # but avoid recursive reference when displaying _oh/Out
500 # but avoid recursive reference when displaying _oh/Out
498 if arg is not self.user_ns['_oh']:
501 if arg is not self.user_ns['_oh']:
499 self.update(arg)
502 self.update(arg)
500 # do not print output if input ends in ';'
503 # do not print output if input ends in ';'
501 if self.input_hist[self.prompt_count].endswith(';\n'):
504 if self.input_hist[self.prompt_count].endswith(';\n'):
502 return
505 return
503 # don't use print, puts an extra space
506 # don't use print, puts an extra space
504 cout_write(self.output_sep)
507 cout_write(self.output_sep)
505 if self.do_full_cache:
508 if self.do_full_cache:
506 cout_write(str(self.prompt_out))
509 cout_write(str(self.prompt_out))
507
510
508 if isinstance(arg,Macro):
511 if isinstance(arg,Macro):
509 print 'Executing Macro...'
512 print 'Executing Macro...'
510 # in case the macro takes a long time to execute
513 # in case the macro takes a long time to execute
511 Term.cout.flush()
514 Term.cout.flush()
512 exec arg.value in self.user_ns
515 self.shell.runlines(arg.value)
513 return None
516 return None
514
517
515 # and now call a possibly user-defined print mechanism
518 # and now call a possibly user-defined print mechanism
516 self.display(arg)
519 self.display(arg)
520 if self.logger.log_output:
521 self.logger.log_write(repr(arg),'output')
517 cout_write(self.output_sep2)
522 cout_write(self.output_sep2)
518 Term.cout.flush()
523 Term.cout.flush()
519
524
520 def _display(self,arg):
525 def _display(self,arg):
521 """Default printer method, uses pprint.
526 """Default printer method, uses pprint.
522
527
523 This can be over-ridden by the users to implement special formatting
528 This can be over-ridden by the users to implement special formatting
524 of certain types of output."""
529 of certain types of output."""
525
530
526 if self.Pprint:
531 if self.Pprint:
527 out = pformat(arg)
532 out = pformat(arg)
528 if '\n' in out:
533 if '\n' in out:
529 # So that multi-line strings line up with the left column of
534 # So that multi-line strings line up with the left column of
530 # the screen, instead of having the output prompt mess up
535 # the screen, instead of having the output prompt mess up
531 # their first line.
536 # their first line.
532 Term.cout.write('\n')
537 Term.cout.write('\n')
533 print >>Term.cout, out
538 print >>Term.cout, out
534 else:
539 else:
535 print >>Term.cout, arg
540 print >>Term.cout, arg
536
541
537 # Assign the default display method:
542 # Assign the default display method:
538 display = _display
543 display = _display
539
544
540 def update(self,arg):
545 def update(self,arg):
541 #print '***cache_count', self.cache_count # dbg
546 #print '***cache_count', self.cache_count # dbg
542 if self.cache_count >= self.cache_size and self.do_full_cache:
547 if self.cache_count >= self.cache_size and self.do_full_cache:
543 self.flush()
548 self.flush()
544 # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
549 # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
545 # we cause buggy behavior for things like gettext).
550 # we cause buggy behavior for things like gettext).
546 if '_' not in __builtin__.__dict__:
551 if '_' not in __builtin__.__dict__:
547 self.___ = self.__
552 self.___ = self.__
548 self.__ = self._
553 self.__ = self._
549 self._ = arg
554 self._ = arg
550 self.user_ns.update({'_':self._,'__':self.__,'___':self.___})
555 self.user_ns.update({'_':self._,'__':self.__,'___':self.___})
551
556
552 # hackish access to top-level namespace to create _1,_2... dynamically
557 # hackish access to top-level namespace to create _1,_2... dynamically
553 to_main = {}
558 to_main = {}
554 if self.do_full_cache:
559 if self.do_full_cache:
555 self.cache_count += 1
560 self.cache_count += 1
556 self.entries.append(arg)
561 self.entries.append(arg)
557 new_result = '_'+`self.prompt_count`
562 new_result = '_'+`self.prompt_count`
558 to_main[new_result] = self.entries[-1]
563 to_main[new_result] = self.entries[-1]
559 self.user_ns.update(to_main)
564 self.user_ns.update(to_main)
560 self.user_ns['_oh'][self.prompt_count] = arg
565 self.user_ns['_oh'][self.prompt_count] = arg
561
566
562 def flush(self):
567 def flush(self):
563 if not self.do_full_cache:
568 if not self.do_full_cache:
564 raise ValueError,"You shouldn't have reached the cache flush "\
569 raise ValueError,"You shouldn't have reached the cache flush "\
565 "if full caching is not enabled!"
570 "if full caching is not enabled!"
566 warn('Output cache limit (currently '+\
571 warn('Output cache limit (currently '+\
567 `self.cache_count`+' entries) hit.\n'
572 `self.cache_count`+' entries) hit.\n'
568 'Flushing cache and resetting history counter...\n'
573 'Flushing cache and resetting history counter...\n'
569 'The only history variables available will be _,__,___ and _1\n'
574 'The only history variables available will be _,__,___ and _1\n'
570 'with the current result.')
575 'with the current result.')
571 # delete auto-generated vars from global namespace
576 # delete auto-generated vars from global namespace
572 for n in range(1,self.prompt_count + 1):
577 for n in range(1,self.prompt_count + 1):
573 key = '_'+`n`
578 key = '_'+`n`
574 try:
579 try:
575 del self.user_ns[key]
580 del self.user_ns[key]
576 except: pass
581 except: pass
577 self.prompt_count = 1
582 self.prompt_count = 1
578 self.cache_count = 1
583 self.cache_count = 1
@@ -1,1997 +1,2060 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 IPython -- An enhanced Interactive Python
3 IPython -- An enhanced Interactive Python
4
4
5 Requires Python 2.1 or newer.
5 Requires Python 2.1 or newer.
6
6
7 This file contains all the classes and helper functions specific to IPython.
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 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
13 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
14 # Copyright (C) 2001-2005 Fernando Perez. <fperez@colorado.edu>
14 # Copyright (C) 2001-2005 Fernando Perez. <fperez@colorado.edu>
15 #
15 #
16 # Distributed under the terms of the BSD License. The full license is in
16 # Distributed under the terms of the BSD License. The full license is in
17 # the file COPYING, distributed as part of this software.
17 # the file COPYING, distributed as part of this software.
18 #
18 #
19 # Note: this code originally subclassed code.InteractiveConsole from the
19 # Note: this code originally subclassed code.InteractiveConsole from the
20 # Python standard library. Over time, all of that class has been copied
20 # Python standard library. Over time, all of that class has been copied
21 # verbatim here for modifications which could not be accomplished by
21 # verbatim here for modifications which could not be accomplished by
22 # subclassing. At this point, there are no dependencies at all on the code
22 # subclassing. At this point, there are no dependencies at all on the code
23 # module anymore (it is not even imported). The Python License (sec. 2)
23 # module anymore (it is not even imported). The Python License (sec. 2)
24 # allows for this, but it's always nice to acknowledge credit where credit is
24 # allows for this, but it's always nice to acknowledge credit where credit is
25 # due.
25 # due.
26 #*****************************************************************************
26 #*****************************************************************************
27
27
28 #****************************************************************************
28 #****************************************************************************
29 # Modules and globals
29 # Modules and globals
30
30
31 from __future__ import generators # for 2.2 backwards-compatibility
31 from __future__ import generators # for 2.2 backwards-compatibility
32
32
33 from IPython import Release
33 from IPython import Release
34 __author__ = '%s <%s>\n%s <%s>' % \
34 __author__ = '%s <%s>\n%s <%s>' % \
35 ( Release.authors['Janko'] + Release.authors['Fernando'] )
35 ( Release.authors['Janko'] + Release.authors['Fernando'] )
36 __license__ = Release.license
36 __license__ = Release.license
37 __version__ = Release.version
37 __version__ = Release.version
38
38
39 # Python standard modules
39 # Python standard modules
40 import __main__
40 import __main__
41 import __builtin__
41 import __builtin__
42 import StringIO
42 import StringIO
43 import bdb
43 import bdb
44 import cPickle as pickle
44 import cPickle as pickle
45 import codeop
45 import codeop
46 import exceptions
46 import exceptions
47 import glob
47 import glob
48 import inspect
48 import inspect
49 import keyword
49 import keyword
50 import new
50 import new
51 import os
51 import os
52 import pdb
52 import pdb
53 import pydoc
53 import pydoc
54 import re
54 import re
55 import shutil
55 import shutil
56 import string
56 import string
57 import sys
57 import sys
58 import traceback
58 import traceback
59 import types
59 import types
60
60
61 from pprint import pprint, pformat
61 from pprint import pprint, pformat
62
62
63 # IPython's own modules
63 # IPython's own modules
64 import IPython
64 import IPython
65 from IPython import OInspect,PyColorize,ultraTB
65 from IPython import OInspect,PyColorize,ultraTB
66 from IPython.ColorANSI import ColorScheme,ColorSchemeTable # too long names
66 from IPython.ColorANSI import ColorScheme,ColorSchemeTable # too long names
67 from IPython.FakeModule import FakeModule
67 from IPython.FakeModule import FakeModule
68 from IPython.Itpl import Itpl,itpl,printpl,ItplNS,itplns
68 from IPython.Itpl import Itpl,itpl,printpl,ItplNS,itplns
69 from IPython.Logger import Logger
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 from IPython.Struct import Struct
72 from IPython.Struct import Struct
72 from IPython.background_jobs import BackgroundJobManager
73 from IPython.background_jobs import BackgroundJobManager
73 from IPython.usage import cmd_line_usage,interactive_usage
74 from IPython.usage import cmd_line_usage,interactive_usage
74 from IPython.genutils import *
75 from IPython.genutils import *
75
76
76 # store the builtin raw_input globally, and use this always, in case user code
77 # store the builtin raw_input globally, and use this always, in case user code
77 # overwrites it (like wx.py.PyShell does)
78 # overwrites it (like wx.py.PyShell does)
78 raw_input_original = raw_input
79 raw_input_original = raw_input
79
80
80 #****************************************************************************
81 #****************************************************************************
81 # Some utility function definitions
82 # Some utility function definitions
82
83
83 # This can be replaced with an isspace() call once we drop 2.2 compatibility
84 # This can be replaced with an isspace() call once we drop 2.2 compatibility
84 _isspace_match = re.compile(r'^\s+$').match
85 _isspace_match = re.compile(r'^\s+$').match
85 def isspace(s):
86 def isspace(s):
86 return bool(_isspace_match(s))
87 return bool(_isspace_match(s))
87
88
88 def esc_quotes(strng):
89 def esc_quotes(strng):
89 """Return the input string with single and double quotes escaped out"""
90 """Return the input string with single and double quotes escaped out"""
90
91
91 return strng.replace('"','\\"').replace("'","\\'")
92 return strng.replace('"','\\"').replace("'","\\'")
92
93
93 def import_fail_info(mod_name,fns=None):
94 def import_fail_info(mod_name,fns=None):
94 """Inform load failure for a module."""
95 """Inform load failure for a module."""
95
96
96 if fns == None:
97 if fns == None:
97 warn("Loading of %s failed.\n" % (mod_name,))
98 warn("Loading of %s failed.\n" % (mod_name,))
98 else:
99 else:
99 warn("Loading of %s from %s failed.\n" % (fns,mod_name))
100 warn("Loading of %s from %s failed.\n" % (fns,mod_name))
100
101
101 def qw_lol(indata):
102 def qw_lol(indata):
102 """qw_lol('a b') -> [['a','b']],
103 """qw_lol('a b') -> [['a','b']],
103 otherwise it's just a call to qw().
104 otherwise it's just a call to qw().
104
105
105 We need this to make sure the modules_some keys *always* end up as a
106 We need this to make sure the modules_some keys *always* end up as a
106 list of lists."""
107 list of lists."""
107
108
108 if type(indata) in StringTypes:
109 if type(indata) in StringTypes:
109 return [qw(indata)]
110 return [qw(indata)]
110 else:
111 else:
111 return qw(indata)
112 return qw(indata)
112
113
113 def ipmagic(arg_s):
114 def ipmagic(arg_s):
114 """Call a magic function by name.
115 """Call a magic function by name.
115
116
116 Input: a string containing the name of the magic function to call and any
117 Input: a string containing the name of the magic function to call and any
117 additional arguments to be passed to the magic.
118 additional arguments to be passed to the magic.
118
119
119 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
120 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
120 prompt:
121 prompt:
121
122
122 In[1]: %name -opt foo bar
123 In[1]: %name -opt foo bar
123
124
124 To call a magic without arguments, simply use ipmagic('name').
125 To call a magic without arguments, simply use ipmagic('name').
125
126
126 This provides a proper Python function to call IPython's magics in any
127 This provides a proper Python function to call IPython's magics in any
127 valid Python code you can type at the interpreter, including loops and
128 valid Python code you can type at the interpreter, including loops and
128 compound statements. It is added by IPython to the Python builtin
129 compound statements. It is added by IPython to the Python builtin
129 namespace upon initialization."""
130 namespace upon initialization."""
130
131
131 args = arg_s.split(' ',1)
132 args = arg_s.split(' ',1)
132 magic_name = args[0]
133 magic_name = args[0]
133 if magic_name.startswith(__IPYTHON__.ESC_MAGIC):
134 if magic_name.startswith(__IPYTHON__.ESC_MAGIC):
134 magic_name = magic_name[1:]
135 magic_name = magic_name[1:]
135 try:
136 try:
136 magic_args = args[1]
137 magic_args = args[1]
137 except IndexError:
138 except IndexError:
138 magic_args = ''
139 magic_args = ''
139 fn = getattr(__IPYTHON__,'magic_'+magic_name,None)
140 fn = getattr(__IPYTHON__,'magic_'+magic_name,None)
140 if fn is None:
141 if fn is None:
141 error("Magic function `%s` not found." % magic_name)
142 error("Magic function `%s` not found." % magic_name)
142 else:
143 else:
143 magic_args = __IPYTHON__.var_expand(magic_args)
144 magic_args = __IPYTHON__.var_expand(magic_args)
144 return fn(magic_args)
145 return fn(magic_args)
145
146
146 def ipalias(arg_s):
147 def ipalias(arg_s):
147 """Call an alias by name.
148 """Call an alias by name.
148
149
149 Input: a string containing the name of the alias to call and any
150 Input: a string containing the name of the alias to call and any
150 additional arguments to be passed to the magic.
151 additional arguments to be passed to the magic.
151
152
152 ipalias('name -opt foo bar') is equivalent to typing at the ipython
153 ipalias('name -opt foo bar') is equivalent to typing at the ipython
153 prompt:
154 prompt:
154
155
155 In[1]: name -opt foo bar
156 In[1]: name -opt foo bar
156
157
157 To call an alias without arguments, simply use ipalias('name').
158 To call an alias without arguments, simply use ipalias('name').
158
159
159 This provides a proper Python function to call IPython's aliases in any
160 This provides a proper Python function to call IPython's aliases in any
160 valid Python code you can type at the interpreter, including loops and
161 valid Python code you can type at the interpreter, including loops and
161 compound statements. It is added by IPython to the Python builtin
162 compound statements. It is added by IPython to the Python builtin
162 namespace upon initialization."""
163 namespace upon initialization."""
163
164
164 args = arg_s.split(' ',1)
165 args = arg_s.split(' ',1)
165 alias_name = args[0]
166 alias_name = args[0]
166 try:
167 try:
167 alias_args = args[1]
168 alias_args = args[1]
168 except IndexError:
169 except IndexError:
169 alias_args = ''
170 alias_args = ''
170 if alias_name in __IPYTHON__.alias_table:
171 if alias_name in __IPYTHON__.alias_table:
171 __IPYTHON__.call_alias(alias_name,alias_args)
172 __IPYTHON__.call_alias(alias_name,alias_args)
172 else:
173 else:
173 error("Alias `%s` not found." % alias_name)
174 error("Alias `%s` not found." % alias_name)
174
175
175 def softspace(file, newvalue):
176 def softspace(file, newvalue):
176 """Copied from code.py, to remove the dependency"""
177 """Copied from code.py, to remove the dependency"""
177 oldvalue = 0
178 oldvalue = 0
178 try:
179 try:
179 oldvalue = file.softspace
180 oldvalue = file.softspace
180 except AttributeError:
181 except AttributeError:
181 pass
182 pass
182 try:
183 try:
183 file.softspace = newvalue
184 file.softspace = newvalue
184 except (AttributeError, TypeError):
185 except (AttributeError, TypeError):
185 # "attribute-less object" or "read-only attributes"
186 # "attribute-less object" or "read-only attributes"
186 pass
187 pass
187 return oldvalue
188 return oldvalue
188
189
189
190
190 #****************************************************************************
191 #****************************************************************************
191 # Local use exceptions
192 # Local use exceptions
192 class SpaceInInput(exceptions.Exception): pass
193 class SpaceInInput(exceptions.Exception): pass
193
194
194 #****************************************************************************
195 #****************************************************************************
195 # Local use classes
196 # Local use classes
196 class Bunch: pass
197 class Bunch: pass
197
198
198 class InputList(list):
199 class InputList(list):
199 """Class to store user input.
200 """Class to store user input.
200
201
201 It's basically a list, but slices return a string instead of a list, thus
202 It's basically a list, but slices return a string instead of a list, thus
202 allowing things like (assuming 'In' is an instance):
203 allowing things like (assuming 'In' is an instance):
203
204
204 exec In[4:7]
205 exec In[4:7]
205
206
206 or
207 or
207
208
208 exec In[5:9] + In[14] + In[21:25]"""
209 exec In[5:9] + In[14] + In[21:25]"""
209
210
210 def __getslice__(self,i,j):
211 def __getslice__(self,i,j):
211 return ''.join(list.__getslice__(self,i,j))
212 return ''.join(list.__getslice__(self,i,j))
212
213
213 class SyntaxTB(ultraTB.ListTB):
214 class SyntaxTB(ultraTB.ListTB):
214 """Extension which holds some state: the last exception value"""
215 """Extension which holds some state: the last exception value"""
215
216
216 def __init__(self,color_scheme = 'NoColor'):
217 def __init__(self,color_scheme = 'NoColor'):
217 ultraTB.ListTB.__init__(self,color_scheme)
218 ultraTB.ListTB.__init__(self,color_scheme)
218 self.last_syntax_error = None
219 self.last_syntax_error = None
219
220
220 def __call__(self, etype, value, elist):
221 def __call__(self, etype, value, elist):
221 self.last_syntax_error = value
222 self.last_syntax_error = value
222 ultraTB.ListTB.__call__(self,etype,value,elist)
223 ultraTB.ListTB.__call__(self,etype,value,elist)
223
224
224 def clear_err_state(self):
225 def clear_err_state(self):
225 """Return the current error state and clear it"""
226 """Return the current error state and clear it"""
226 e = self.last_syntax_error
227 e = self.last_syntax_error
227 self.last_syntax_error = None
228 self.last_syntax_error = None
228 return e
229 return e
229
230
230 #****************************************************************************
231 #****************************************************************************
231 # Main IPython class
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 """An enhanced console for Python."""
254 """An enhanced console for Python."""
234
255
235 # class attribute to indicate whether the class supports threads or not.
256 # class attribute to indicate whether the class supports threads or not.
236 # Subclasses with thread support should override this as needed.
257 # Subclasses with thread support should override this as needed.
237 isthreaded = False
258 isthreaded = False
238
259
239 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
260 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
240 user_ns = None,user_global_ns=None,banner2='',
261 user_ns = None,user_global_ns=None,banner2='',
241 custom_exceptions=((),None),embedded=False):
262 custom_exceptions=((),None),embedded=False):
242
263
243 # some minimal strict typechecks. For some core data structures, I
264 # some minimal strict typechecks. For some core data structures, I
244 # want actual basic python types, not just anything that looks like
265 # want actual basic python types, not just anything that looks like
245 # one. This is especially true for namespaces.
266 # one. This is especially true for namespaces.
246 for ns in (user_ns,user_global_ns):
267 for ns in (user_ns,user_global_ns):
247 if ns is not None and type(ns) != types.DictType:
268 if ns is not None and type(ns) != types.DictType:
248 raise TypeError,'namespace must be a dictionary'
269 raise TypeError,'namespace must be a dictionary'
249
270
250 # Put a reference to self in builtins so that any form of embedded or
271 # Put a reference to self in builtins so that any form of embedded or
251 # imported code can test for being inside IPython.
272 # imported code can test for being inside IPython.
252 __builtin__.__IPYTHON__ = self
273 __builtin__.__IPYTHON__ = self
253
274
254 # And load into builtins ipmagic/ipalias as well
275 # And load into builtins ipmagic/ipalias as well
255 __builtin__.ipmagic = ipmagic
276 __builtin__.ipmagic = ipmagic
256 __builtin__.ipalias = ipalias
277 __builtin__.ipalias = ipalias
257
278
258 # Add to __builtin__ other parts of IPython's public API
279 # Add to __builtin__ other parts of IPython's public API
259 __builtin__.ip_set_hook = self.set_hook
280 __builtin__.ip_set_hook = self.set_hook
260
281
261 # Keep in the builtins a flag for when IPython is active. We set it
282 # Keep in the builtins a flag for when IPython is active. We set it
262 # with setdefault so that multiple nested IPythons don't clobber one
283 # with setdefault so that multiple nested IPythons don't clobber one
263 # another. Each will increase its value by one upon being activated,
284 # another. Each will increase its value by one upon being activated,
264 # which also gives us a way to determine the nesting level.
285 # which also gives us a way to determine the nesting level.
265 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
286 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
266
287
267 # Do the intuitively correct thing for quit/exit: we remove the
288 # Do the intuitively correct thing for quit/exit: we remove the
268 # builtins if they exist, and our own prefilter routine will handle
289 # builtins if they exist, and our own prefilter routine will handle
269 # these special cases
290 # these special cases
270 try:
291 try:
271 del __builtin__.exit, __builtin__.quit
292 del __builtin__.exit, __builtin__.quit
272 except AttributeError:
293 except AttributeError:
273 pass
294 pass
274
295
275 # Store the actual shell's name
296 # Store the actual shell's name
276 self.name = name
297 self.name = name
277
298
278 # We need to know whether the instance is meant for embedding, since
299 # We need to know whether the instance is meant for embedding, since
279 # global/local namespaces need to be handled differently in that case
300 # global/local namespaces need to be handled differently in that case
280 self.embedded = embedded
301 self.embedded = embedded
281
302
282 # command compiler
303 # command compiler
283 self.compile = codeop.CommandCompiler()
304 self.compile = codeop.CommandCompiler()
284
305
285 # User input buffer
306 # User input buffer
286 self.buffer = []
307 self.buffer = []
287
308
288 # Default name given in compilation of code
309 # Default name given in compilation of code
289 self.filename = '<ipython console>'
310 self.filename = '<ipython console>'
290
311
291 # Create the namespace where the user will operate. user_ns is
312 # Create the namespace where the user will operate. user_ns is
292 # normally the only one used, and it is passed to the exec calls as
313 # normally the only one used, and it is passed to the exec calls as
293 # the locals argument. But we do carry a user_global_ns namespace
314 # the locals argument. But we do carry a user_global_ns namespace
294 # given as the exec 'globals' argument, This is useful in embedding
315 # given as the exec 'globals' argument, This is useful in embedding
295 # situations where the ipython shell opens in a context where the
316 # situations where the ipython shell opens in a context where the
296 # distinction between locals and globals is meaningful.
317 # distinction between locals and globals is meaningful.
297
318
298 # FIXME. For some strange reason, __builtins__ is showing up at user
319 # FIXME. For some strange reason, __builtins__ is showing up at user
299 # level as a dict instead of a module. This is a manual fix, but I
320 # level as a dict instead of a module. This is a manual fix, but I
300 # should really track down where the problem is coming from. Alex
321 # should really track down where the problem is coming from. Alex
301 # Schmolck reported this problem first.
322 # Schmolck reported this problem first.
302
323
303 # A useful post by Alex Martelli on this topic:
324 # A useful post by Alex Martelli on this topic:
304 # Re: inconsistent value from __builtins__
325 # Re: inconsistent value from __builtins__
305 # Von: Alex Martelli <aleaxit@yahoo.com>
326 # Von: Alex Martelli <aleaxit@yahoo.com>
306 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
327 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
307 # Gruppen: comp.lang.python
328 # Gruppen: comp.lang.python
308 # Referenzen: 1
309
329
310 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
330 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
311 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
331 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
312 # > <type 'dict'>
332 # > <type 'dict'>
313 # > >>> print type(__builtins__)
333 # > >>> print type(__builtins__)
314 # > <type 'module'>
334 # > <type 'module'>
315 # > Is this difference in return value intentional?
335 # > Is this difference in return value intentional?
316
336
317 # Well, it's documented that '__builtins__' can be either a dictionary
337 # Well, it's documented that '__builtins__' can be either a dictionary
318 # or a module, and it's been that way for a long time. Whether it's
338 # or a module, and it's been that way for a long time. Whether it's
319 # intentional (or sensible), I don't know. In any case, the idea is
339 # intentional (or sensible), I don't know. In any case, the idea is
320 # that if you need to access the built-in namespace directly, you
340 # that if you need to access the built-in namespace directly, you
321 # should start with "import __builtin__" (note, no 's') which will
341 # should start with "import __builtin__" (note, no 's') which will
322 # definitely give you a module. Yeah, it's somewhat confusing:-(.
342 # definitely give you a module. Yeah, it's somewhat confusing:-(.
323
343
324 if user_ns is None:
344 if user_ns is None:
325 # Set __name__ to __main__ to better match the behavior of the
345 # Set __name__ to __main__ to better match the behavior of the
326 # normal interpreter.
346 # normal interpreter.
327 user_ns = {'__name__' :'__main__',
347 user_ns = {'__name__' :'__main__',
328 '__builtins__' : __builtin__,
348 '__builtins__' : __builtin__,
329 }
349 }
330
350
331 if user_global_ns is None:
351 if user_global_ns is None:
332 user_global_ns = {}
352 user_global_ns = {}
333
353
334 # Assign namespaces
354 # Assign namespaces
335 # This is the namespace where all normal user variables live
355 # This is the namespace where all normal user variables live
336 self.user_ns = user_ns
356 self.user_ns = user_ns
337 # Embedded instances require a separate namespace for globals.
357 # Embedded instances require a separate namespace for globals.
338 # Normally this one is unused by non-embedded instances.
358 # Normally this one is unused by non-embedded instances.
339 self.user_global_ns = user_global_ns
359 self.user_global_ns = user_global_ns
340 # A namespace to keep track of internal data structures to prevent
360 # A namespace to keep track of internal data structures to prevent
341 # them from cluttering user-visible stuff. Will be updated later
361 # them from cluttering user-visible stuff. Will be updated later
342 self.internal_ns = {}
362 self.internal_ns = {}
343
363
344 # Namespace of system aliases. Each entry in the alias
364 # Namespace of system aliases. Each entry in the alias
345 # table must be a 2-tuple of the form (N,name), where N is the number
365 # table must be a 2-tuple of the form (N,name), where N is the number
346 # of positional arguments of the alias.
366 # of positional arguments of the alias.
347 self.alias_table = {}
367 self.alias_table = {}
348
368
349 # A table holding all the namespaces IPython deals with, so that
369 # A table holding all the namespaces IPython deals with, so that
350 # introspection facilities can search easily.
370 # introspection facilities can search easily.
351 self.ns_table = {'user':user_ns,
371 self.ns_table = {'user':user_ns,
352 'user_global':user_global_ns,
372 'user_global':user_global_ns,
353 'alias':self.alias_table,
373 'alias':self.alias_table,
354 'internal':self.internal_ns,
374 'internal':self.internal_ns,
355 'builtin':__builtin__.__dict__
375 'builtin':__builtin__.__dict__
356 }
376 }
357
377
358 # The user namespace MUST have a pointer to the shell itself.
378 # The user namespace MUST have a pointer to the shell itself.
359 self.user_ns[name] = self
379 self.user_ns[name] = self
360
380
361 # We need to insert into sys.modules something that looks like a
381 # We need to insert into sys.modules something that looks like a
362 # module but which accesses the IPython namespace, for shelve and
382 # module but which accesses the IPython namespace, for shelve and
363 # pickle to work interactively. Normally they rely on getting
383 # pickle to work interactively. Normally they rely on getting
364 # everything out of __main__, but for embedding purposes each IPython
384 # everything out of __main__, but for embedding purposes each IPython
365 # instance has its own private namespace, so we can't go shoving
385 # instance has its own private namespace, so we can't go shoving
366 # everything into __main__.
386 # everything into __main__.
367
387
368 # note, however, that we should only do this for non-embedded
388 # note, however, that we should only do this for non-embedded
369 # ipythons, which really mimic the __main__.__dict__ with their own
389 # ipythons, which really mimic the __main__.__dict__ with their own
370 # namespace. Embedded instances, on the other hand, should not do
390 # namespace. Embedded instances, on the other hand, should not do
371 # this because they need to manage the user local/global namespaces
391 # this because they need to manage the user local/global namespaces
372 # only, but they live within a 'normal' __main__ (meaning, they
392 # only, but they live within a 'normal' __main__ (meaning, they
373 # shouldn't overtake the execution environment of the script they're
393 # shouldn't overtake the execution environment of the script they're
374 # embedded in).
394 # embedded in).
375
395
376 if not embedded:
396 if not embedded:
377 try:
397 try:
378 main_name = self.user_ns['__name__']
398 main_name = self.user_ns['__name__']
379 except KeyError:
399 except KeyError:
380 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
400 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
381 else:
401 else:
382 #print "pickle hack in place" # dbg
402 #print "pickle hack in place" # dbg
383 sys.modules[main_name] = FakeModule(self.user_ns)
403 sys.modules[main_name] = FakeModule(self.user_ns)
384
404
385 # List of input with multi-line handling.
405 # List of input with multi-line handling.
386 # Fill its zero entry, user counter starts at 1
406 # Fill its zero entry, user counter starts at 1
387 self.input_hist = InputList(['\n'])
407 self.input_hist = InputList(['\n'])
388
408
389 # list of visited directories
409 # list of visited directories
390 try:
410 try:
391 self.dir_hist = [os.getcwd()]
411 self.dir_hist = [os.getcwd()]
392 except IOError, e:
412 except IOError, e:
393 self.dir_hist = []
413 self.dir_hist = []
394
414
395 # dict of output history
415 # dict of output history
396 self.output_hist = {}
416 self.output_hist = {}
397
417
398 # dict of things NOT to alias (keywords, builtins and some magics)
418 # dict of things NOT to alias (keywords, builtins and some magics)
399 no_alias = {}
419 no_alias = {}
400 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
420 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
401 for key in keyword.kwlist + no_alias_magics:
421 for key in keyword.kwlist + no_alias_magics:
402 no_alias[key] = 1
422 no_alias[key] = 1
403 no_alias.update(__builtin__.__dict__)
423 no_alias.update(__builtin__.__dict__)
404 self.no_alias = no_alias
424 self.no_alias = no_alias
405
425
406 # make global variables for user access to these
426 # make global variables for user access to these
407 self.user_ns['_ih'] = self.input_hist
427 self.user_ns['_ih'] = self.input_hist
408 self.user_ns['_oh'] = self.output_hist
428 self.user_ns['_oh'] = self.output_hist
409 self.user_ns['_dh'] = self.dir_hist
429 self.user_ns['_dh'] = self.dir_hist
410
430
411 # user aliases to input and output histories
431 # user aliases to input and output histories
412 self.user_ns['In'] = self.input_hist
432 self.user_ns['In'] = self.input_hist
413 self.user_ns['Out'] = self.output_hist
433 self.user_ns['Out'] = self.output_hist
414
434
415 # Object variable to store code object waiting execution. This is
435 # Object variable to store code object waiting execution. This is
416 # used mainly by the multithreaded shells, but it can come in handy in
436 # used mainly by the multithreaded shells, but it can come in handy in
417 # other situations. No need to use a Queue here, since it's a single
437 # other situations. No need to use a Queue here, since it's a single
418 # item which gets cleared once run.
438 # item which gets cleared once run.
419 self.code_to_run = None
439 self.code_to_run = None
420
440
421 # Job manager (for jobs run as background threads)
441 # Job manager (for jobs run as background threads)
422 self.jobs = BackgroundJobManager()
442 self.jobs = BackgroundJobManager()
423 # Put the job manager into builtins so it's always there.
443 # Put the job manager into builtins so it's always there.
424 __builtin__.jobs = self.jobs
444 __builtin__.jobs = self.jobs
425
445
426 # escapes for automatic behavior on the command line
446 # escapes for automatic behavior on the command line
427 self.ESC_SHELL = '!'
447 self.ESC_SHELL = '!'
428 self.ESC_HELP = '?'
448 self.ESC_HELP = '?'
429 self.ESC_MAGIC = '%'
449 self.ESC_MAGIC = '%'
430 self.ESC_QUOTE = ','
450 self.ESC_QUOTE = ','
431 self.ESC_QUOTE2 = ';'
451 self.ESC_QUOTE2 = ';'
432 self.ESC_PAREN = '/'
452 self.ESC_PAREN = '/'
433
453
434 # And their associated handlers
454 # And their associated handlers
435 self.esc_handlers = {self.ESC_PAREN:self.handle_auto,
455 self.esc_handlers = {self.ESC_PAREN : self.handle_auto,
436 self.ESC_QUOTE:self.handle_auto,
456 self.ESC_QUOTE : self.handle_auto,
437 self.ESC_QUOTE2:self.handle_auto,
457 self.ESC_QUOTE2 : self.handle_auto,
438 self.ESC_MAGIC:self.handle_magic,
458 self.ESC_MAGIC : self.handle_magic,
439 self.ESC_HELP:self.handle_help,
459 self.ESC_HELP : self.handle_help,
440 self.ESC_SHELL:self.handle_shell_escape,
460 self.ESC_SHELL : self.handle_shell_escape,
441 }
461 }
442
462
443 # class initializations
463 # class initializations
444 Logger.__init__(self,log_ns = self.user_ns)
445 Magic.__init__(self,self)
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 # Python source parser/formatter for syntax highlighting
466 # Python source parser/formatter for syntax highlighting
452 pyformat = PyColorize.Parser().format
467 pyformat = PyColorize.Parser().format
453 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
468 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
454
469
455 # hooks holds pointers used for user-side customizations
470 # hooks holds pointers used for user-side customizations
456 self.hooks = Struct()
471 self.hooks = Struct()
457
472
458 # Set all default hooks, defined in the IPython.hooks module.
473 # Set all default hooks, defined in the IPython.hooks module.
459 hooks = IPython.hooks
474 hooks = IPython.hooks
460 for hook_name in hooks.__all__:
475 for hook_name in hooks.__all__:
461 self.set_hook(hook_name,getattr(hooks,hook_name))
476 self.set_hook(hook_name,getattr(hooks,hook_name))
462
477
463 # Flag to mark unconditional exit
478 # Flag to mark unconditional exit
464 self.exit_now = False
479 self.exit_now = False
465
480
466 self.usage_min = """\
481 self.usage_min = """\
467 An enhanced console for Python.
482 An enhanced console for Python.
468 Some of its features are:
483 Some of its features are:
469 - Readline support if the readline library is present.
484 - Readline support if the readline library is present.
470 - Tab completion in the local namespace.
485 - Tab completion in the local namespace.
471 - Logging of input, see command-line options.
486 - Logging of input, see command-line options.
472 - System shell escape via ! , eg !ls.
487 - System shell escape via ! , eg !ls.
473 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
488 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
474 - Keeps track of locally defined variables via %who, %whos.
489 - Keeps track of locally defined variables via %who, %whos.
475 - Show object information with a ? eg ?x or x? (use ?? for more info).
490 - Show object information with a ? eg ?x or x? (use ?? for more info).
476 """
491 """
477 if usage: self.usage = usage
492 if usage: self.usage = usage
478 else: self.usage = self.usage_min
493 else: self.usage = self.usage_min
479
494
480 # Storage
495 # Storage
481 self.rc = rc # This will hold all configuration information
496 self.rc = rc # This will hold all configuration information
482 self.inputcache = []
497 self.inputcache = []
483 self._boundcache = []
498 self._boundcache = []
484 self.pager = 'less'
499 self.pager = 'less'
485 # temporary files used for various purposes. Deleted at exit.
500 # temporary files used for various purposes. Deleted at exit.
486 self.tempfiles = []
501 self.tempfiles = []
487
502
488 # Keep track of readline usage (later set by init_readline)
503 # Keep track of readline usage (later set by init_readline)
489 self.has_readline = False
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 # for pushd/popd management
516 # for pushd/popd management
492 try:
517 try:
493 self.home_dir = get_home_dir()
518 self.home_dir = get_home_dir()
494 except HomeDirError,msg:
519 except HomeDirError,msg:
495 fatal(msg)
520 fatal(msg)
496
521
497 self.dir_stack = [os.getcwd().replace(self.home_dir,'~')]
522 self.dir_stack = [os.getcwd().replace(self.home_dir,'~')]
498
523
499 # Functions to call the underlying shell.
524 # Functions to call the underlying shell.
500
525
501 # utility to expand user variables via Itpl
526 # utility to expand user variables via Itpl
502 self.var_expand = lambda cmd: str(ItplNS(cmd.replace('#','\#'),
527 self.var_expand = lambda cmd: str(ItplNS(cmd.replace('#','\#'),
503 self.user_ns))
528 self.user_ns))
504 # The first is similar to os.system, but it doesn't return a value,
529 # The first is similar to os.system, but it doesn't return a value,
505 # and it allows interpolation of variables in the user's namespace.
530 # and it allows interpolation of variables in the user's namespace.
506 self.system = lambda cmd: shell(self.var_expand(cmd),
531 self.system = lambda cmd: shell(self.var_expand(cmd),
507 header='IPython system call: ',
532 header='IPython system call: ',
508 verbose=self.rc.system_verbose)
533 verbose=self.rc.system_verbose)
509 # These are for getoutput and getoutputerror:
534 # These are for getoutput and getoutputerror:
510 self.getoutput = lambda cmd: \
535 self.getoutput = lambda cmd: \
511 getoutput(self.var_expand(cmd),
536 getoutput(self.var_expand(cmd),
512 header='IPython system call: ',
537 header='IPython system call: ',
513 verbose=self.rc.system_verbose)
538 verbose=self.rc.system_verbose)
514 self.getoutputerror = lambda cmd: \
539 self.getoutputerror = lambda cmd: \
515 getoutputerror(str(ItplNS(cmd.replace('#','\#'),
540 getoutputerror(str(ItplNS(cmd.replace('#','\#'),
516 self.user_ns)),
541 self.user_ns)),
517 header='IPython system call: ',
542 header='IPython system call: ',
518 verbose=self.rc.system_verbose)
543 verbose=self.rc.system_verbose)
519
544
520 # RegExp for splitting line contents into pre-char//first
545 # RegExp for splitting line contents into pre-char//first
521 # word-method//rest. For clarity, each group in on one line.
546 # word-method//rest. For clarity, each group in on one line.
522
547
523 # WARNING: update the regexp if the above escapes are changed, as they
548 # WARNING: update the regexp if the above escapes are changed, as they
524 # are hardwired in.
549 # are hardwired in.
525
550
526 # Don't get carried away with trying to make the autocalling catch too
551 # Don't get carried away with trying to make the autocalling catch too
527 # much: it's better to be conservative rather than to trigger hidden
552 # much: it's better to be conservative rather than to trigger hidden
528 # evals() somewhere and end up causing side effects.
553 # evals() somewhere and end up causing side effects.
529
554
530 self.line_split = re.compile(r'^([\s*,;/])'
555 self.line_split = re.compile(r'^([\s*,;/])'
531 r'([\?\w\.]+\w*\s*)'
556 r'([\?\w\.]+\w*\s*)'
532 r'(\(?.*$)')
557 r'(\(?.*$)')
533
558
534 # Original re, keep around for a while in case changes break something
559 # Original re, keep around for a while in case changes break something
535 #self.line_split = re.compile(r'(^[\s*!\?%,/]?)'
560 #self.line_split = re.compile(r'(^[\s*!\?%,/]?)'
536 # r'(\s*[\?\w\.]+\w*\s*)'
561 # r'(\s*[\?\w\.]+\w*\s*)'
537 # r'(\(?.*$)')
562 # r'(\(?.*$)')
538
563
539 # RegExp to identify potential function names
564 # RegExp to identify potential function names
540 self.re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
565 self.re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
541 # RegExp to exclude strings with this start from autocalling
566 # RegExp to exclude strings with this start from autocalling
542 self.re_exclude_auto = re.compile('^[!=()<>,\*/\+-]|^is ')
567 self.re_exclude_auto = re.compile('^[!=()<>,\*/\+-]|^is ')
543
568
544 # try to catch also methods for stuff in lists/tuples/dicts: off
569 # try to catch also methods for stuff in lists/tuples/dicts: off
545 # (experimental). For this to work, the line_split regexp would need
570 # (experimental). For this to work, the line_split regexp would need
546 # to be modified so it wouldn't break things at '['. That line is
571 # to be modified so it wouldn't break things at '['. That line is
547 # nasty enough that I shouldn't change it until I can test it _well_.
572 # nasty enough that I shouldn't change it until I can test it _well_.
548 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
573 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
549
574
550 # keep track of where we started running (mainly for crash post-mortem)
575 # keep track of where we started running (mainly for crash post-mortem)
551 self.starting_dir = os.getcwd()
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 # Various switches which can be set
578 # Various switches which can be set
567 self.CACHELENGTH = 5000 # this is cheap, it's just text
579 self.CACHELENGTH = 5000 # this is cheap, it's just text
568 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
580 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
569 self.banner2 = banner2
581 self.banner2 = banner2
570
582
571 # TraceBack handlers:
583 # TraceBack handlers:
572
584
573 # Syntax error handler.
585 # Syntax error handler.
574 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
586 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
575
587
576 # The interactive one is initialized with an offset, meaning we always
588 # The interactive one is initialized with an offset, meaning we always
577 # want to remove the topmost item in the traceback, which is our own
589 # want to remove the topmost item in the traceback, which is our own
578 # internal code. Valid modes: ['Plain','Context','Verbose']
590 # internal code. Valid modes: ['Plain','Context','Verbose']
579 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
591 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
580 color_scheme='NoColor',
592 color_scheme='NoColor',
581 tb_offset = 1)
593 tb_offset = 1)
582
594
583 # IPython itself shouldn't crash. This will produce a detailed
595 # IPython itself shouldn't crash. This will produce a detailed
584 # post-mortem if it does. But we only install the crash handler for
596 # post-mortem if it does. But we only install the crash handler for
585 # non-threaded shells, the threaded ones use a normal verbose reporter
597 # non-threaded shells, the threaded ones use a normal verbose reporter
586 # and lose the crash handler. This is because exceptions in the main
598 # and lose the crash handler. This is because exceptions in the main
587 # thread (such as in GUI code) propagate directly to sys.excepthook,
599 # thread (such as in GUI code) propagate directly to sys.excepthook,
588 # and there's no point in printing crash dumps for every user exception.
600 # and there's no point in printing crash dumps for every user exception.
589 if self.isthreaded:
601 if self.isthreaded:
590 sys.excepthook = ultraTB.FormattedTB()
602 sys.excepthook = ultraTB.FormattedTB()
591 else:
603 else:
592 from IPython import CrashHandler
604 from IPython import CrashHandler
593 sys.excepthook = CrashHandler.CrashHandler(self)
605 sys.excepthook = CrashHandler.CrashHandler(self)
594
606
595 # The instance will store a pointer to this, so that runtime code
607 # The instance will store a pointer to this, so that runtime code
596 # (such as magics) can access it. This is because during the
608 # (such as magics) can access it. This is because during the
597 # read-eval loop, it gets temporarily overwritten (to deal with GUI
609 # read-eval loop, it gets temporarily overwritten (to deal with GUI
598 # frameworks).
610 # frameworks).
599 self.sys_excepthook = sys.excepthook
611 self.sys_excepthook = sys.excepthook
600
612
601 # and add any custom exception handlers the user may have specified
613 # and add any custom exception handlers the user may have specified
602 self.set_custom_exc(*custom_exceptions)
614 self.set_custom_exc(*custom_exceptions)
603
615
604 # Object inspector
616 # Object inspector
605 self.inspector = OInspect.Inspector(OInspect.InspectColors,
617 self.inspector = OInspect.Inspector(OInspect.InspectColors,
606 PyColorize.ANSICodeColors,
618 PyColorize.ANSICodeColors,
607 'NoColor')
619 'NoColor')
608 # indentation management
620 # indentation management
609 self.autoindent = False
621 self.autoindent = False
610 self.indent_current_nsp = 0
622 self.indent_current_nsp = 0
611 self.indent_current = '' # actual indent string
623 self.indent_current = '' # actual indent string
612
624
613 # Make some aliases automatically
625 # Make some aliases automatically
614 # Prepare list of shell aliases to auto-define
626 # Prepare list of shell aliases to auto-define
615 if os.name == 'posix':
627 if os.name == 'posix':
616 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
628 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
617 'mv mv -i','rm rm -i','cp cp -i',
629 'mv mv -i','rm rm -i','cp cp -i',
618 'cat cat','less less','clear clear',
630 'cat cat','less less','clear clear',
619 # a better ls
631 # a better ls
620 'ls ls -F',
632 'ls ls -F',
621 # long ls
633 # long ls
622 'll ls -lF',
634 'll ls -lF',
623 # color ls
635 # color ls
624 'lc ls -F -o --color',
636 'lc ls -F -o --color',
625 # ls normal files only
637 # ls normal files only
626 'lf ls -F -o --color %l | grep ^-',
638 'lf ls -F -o --color %l | grep ^-',
627 # ls symbolic links
639 # ls symbolic links
628 'lk ls -F -o --color %l | grep ^l',
640 'lk ls -F -o --color %l | grep ^l',
629 # directories or links to directories,
641 # directories or links to directories,
630 'ldir ls -F -o --color %l | grep /$',
642 'ldir ls -F -o --color %l | grep /$',
631 # things which are executable
643 # things which are executable
632 'lx ls -F -o --color %l | grep ^-..x',
644 'lx ls -F -o --color %l | grep ^-..x',
633 )
645 )
634 elif os.name in ['nt','dos']:
646 elif os.name in ['nt','dos']:
635 auto_alias = ('dir dir /on', 'ls dir /on',
647 auto_alias = ('dir dir /on', 'ls dir /on',
636 'ddir dir /ad /on', 'ldir dir /ad /on',
648 'ddir dir /ad /on', 'ldir dir /ad /on',
637 'mkdir mkdir','rmdir rmdir','echo echo',
649 'mkdir mkdir','rmdir rmdir','echo echo',
638 'ren ren','cls cls','copy copy')
650 'ren ren','cls cls','copy copy')
639 else:
651 else:
640 auto_alias = ()
652 auto_alias = ()
641 self.auto_alias = map(lambda s:s.split(None,1),auto_alias)
653 self.auto_alias = map(lambda s:s.split(None,1),auto_alias)
642 # Call the actual (public) initializer
654 # Call the actual (public) initializer
643 self.init_auto_alias()
655 self.init_auto_alias()
644 # end __init__
656 # end __init__
645
657
646 def post_config_initialization(self):
658 def post_config_initialization(self):
647 """Post configuration init method
659 """Post configuration init method
648
660
649 This is called after the configuration files have been processed to
661 This is called after the configuration files have been processed to
650 'finalize' the initialization."""
662 'finalize' the initialization."""
651
663
652 rc = self.rc
664 rc = self.rc
653
665
654 # Load readline proper
666 # Load readline proper
655 if rc.readline:
667 if rc.readline:
656 self.init_readline()
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 # Set user colors (don't do it in the constructor above so that it
699 # Set user colors (don't do it in the constructor above so that it
659 # doesn't crash if colors option is invalid)
700 # doesn't crash if colors option is invalid)
660 self.magic_colors(rc.colors)
701 self.magic_colors(rc.colors)
661
702
703 # Set calling of pdb on exceptions
704 self.call_pdb = rc.pdb
705
662 # Load user aliases
706 # Load user aliases
663 for alias in rc.alias:
707 for alias in rc.alias:
664 self.magic_alias(alias)
708 self.magic_alias(alias)
665
709
666 # dynamic data that survives through sessions
710 # dynamic data that survives through sessions
667 # XXX make the filename a config option?
711 # XXX make the filename a config option?
668 persist_base = 'persist'
712 persist_base = 'persist'
669 if rc.profile:
713 if rc.profile:
670 persist_base += '_%s' % rc.profile
714 persist_base += '_%s' % rc.profile
671 self.persist_fname = os.path.join(rc.ipythondir,persist_base)
715 self.persist_fname = os.path.join(rc.ipythondir,persist_base)
672
716
673 try:
717 try:
674 self.persist = pickle.load(file(self.persist_fname))
718 self.persist = pickle.load(file(self.persist_fname))
675 except:
719 except:
676 self.persist = {}
720 self.persist = {}
677
721
678 def set_hook(self,name,hook):
722 def set_hook(self,name,hook):
679 """set_hook(name,hook) -> sets an internal IPython hook.
723 """set_hook(name,hook) -> sets an internal IPython hook.
680
724
681 IPython exposes some of its internal API as user-modifiable hooks. By
725 IPython exposes some of its internal API as user-modifiable hooks. By
682 resetting one of these hooks, you can modify IPython's behavior to
726 resetting one of these hooks, you can modify IPython's behavior to
683 call at runtime your own routines."""
727 call at runtime your own routines."""
684
728
685 # At some point in the future, this should validate the hook before it
729 # At some point in the future, this should validate the hook before it
686 # accepts it. Probably at least check that the hook takes the number
730 # accepts it. Probably at least check that the hook takes the number
687 # of args it's supposed to.
731 # of args it's supposed to.
688 setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
732 setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
689
733
690 def set_custom_exc(self,exc_tuple,handler):
734 def set_custom_exc(self,exc_tuple,handler):
691 """set_custom_exc(exc_tuple,handler)
735 """set_custom_exc(exc_tuple,handler)
692
736
693 Set a custom exception handler, which will be called if any of the
737 Set a custom exception handler, which will be called if any of the
694 exceptions in exc_tuple occur in the mainloop (specifically, in the
738 exceptions in exc_tuple occur in the mainloop (specifically, in the
695 runcode() method.
739 runcode() method.
696
740
697 Inputs:
741 Inputs:
698
742
699 - exc_tuple: a *tuple* of valid exceptions to call the defined
743 - exc_tuple: a *tuple* of valid exceptions to call the defined
700 handler for. It is very important that you use a tuple, and NOT A
744 handler for. It is very important that you use a tuple, and NOT A
701 LIST here, because of the way Python's except statement works. If
745 LIST here, because of the way Python's except statement works. If
702 you only want to trap a single exception, use a singleton tuple:
746 you only want to trap a single exception, use a singleton tuple:
703
747
704 exc_tuple == (MyCustomException,)
748 exc_tuple == (MyCustomException,)
705
749
706 - handler: this must be defined as a function with the following
750 - handler: this must be defined as a function with the following
707 basic interface: def my_handler(self,etype,value,tb).
751 basic interface: def my_handler(self,etype,value,tb).
708
752
709 This will be made into an instance method (via new.instancemethod)
753 This will be made into an instance method (via new.instancemethod)
710 of IPython itself, and it will be called if any of the exceptions
754 of IPython itself, and it will be called if any of the exceptions
711 listed in the exc_tuple are caught. If the handler is None, an
755 listed in the exc_tuple are caught. If the handler is None, an
712 internal basic one is used, which just prints basic info.
756 internal basic one is used, which just prints basic info.
713
757
714 WARNING: by putting in your own exception handler into IPython's main
758 WARNING: by putting in your own exception handler into IPython's main
715 execution loop, you run a very good chance of nasty crashes. This
759 execution loop, you run a very good chance of nasty crashes. This
716 facility should only be used if you really know what you are doing."""
760 facility should only be used if you really know what you are doing."""
717
761
718 assert type(exc_tuple)==type(()) , \
762 assert type(exc_tuple)==type(()) , \
719 "The custom exceptions must be given AS A TUPLE."
763 "The custom exceptions must be given AS A TUPLE."
720
764
721 def dummy_handler(self,etype,value,tb):
765 def dummy_handler(self,etype,value,tb):
722 print '*** Simple custom exception handler ***'
766 print '*** Simple custom exception handler ***'
723 print 'Exception type :',etype
767 print 'Exception type :',etype
724 print 'Exception value:',value
768 print 'Exception value:',value
725 print 'Traceback :',tb
769 print 'Traceback :',tb
726 print 'Source code :','\n'.join(self.buffer)
770 print 'Source code :','\n'.join(self.buffer)
727
771
728 if handler is None: handler = dummy_handler
772 if handler is None: handler = dummy_handler
729
773
730 self.CustomTB = new.instancemethod(handler,self,self.__class__)
774 self.CustomTB = new.instancemethod(handler,self,self.__class__)
731 self.custom_exceptions = exc_tuple
775 self.custom_exceptions = exc_tuple
732
776
733 def set_custom_completer(self,completer,pos=0):
777 def set_custom_completer(self,completer,pos=0):
734 """set_custom_completer(completer,pos=0)
778 """set_custom_completer(completer,pos=0)
735
779
736 Adds a new custom completer function.
780 Adds a new custom completer function.
737
781
738 The position argument (defaults to 0) is the index in the completers
782 The position argument (defaults to 0) is the index in the completers
739 list where you want the completer to be inserted."""
783 list where you want the completer to be inserted."""
740
784
741 newcomp = new.instancemethod(completer,self.Completer,
785 newcomp = new.instancemethod(completer,self.Completer,
742 self.Completer.__class__)
786 self.Completer.__class__)
743 self.Completer.matchers.insert(pos,newcomp)
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 def complete(self,text):
811 def complete(self,text):
746 """Return a sorted list of all possible completions on text.
812 """Return a sorted list of all possible completions on text.
747
813
748 Inputs:
814 Inputs:
749
815
750 - text: a string of text to be completed on.
816 - text: a string of text to be completed on.
751
817
752 This is a wrapper around the completion mechanism, similar to what
818 This is a wrapper around the completion mechanism, similar to what
753 readline does at the command line when the TAB key is hit. By
819 readline does at the command line when the TAB key is hit. By
754 exposing it as a method, it can be used by other non-readline
820 exposing it as a method, it can be used by other non-readline
755 environments (such as GUIs) for text completion.
821 environments (such as GUIs) for text completion.
756
822
757 Simple usage example:
823 Simple usage example:
758
824
759 In [1]: x = 'hello'
825 In [1]: x = 'hello'
760
826
761 In [2]: __IP.complete('x.l')
827 In [2]: __IP.complete('x.l')
762 Out[2]: ['x.ljust', 'x.lower', 'x.lstrip']"""
828 Out[2]: ['x.ljust', 'x.lower', 'x.lstrip']"""
763
829
764 complete = self.Completer.complete
830 complete = self.Completer.complete
765 state = 0
831 state = 0
766 # use a dict so we get unique keys, since ipyhton's multiple
832 # use a dict so we get unique keys, since ipyhton's multiple
767 # completers can return duplicates.
833 # completers can return duplicates.
768 comps = {}
834 comps = {}
769 while True:
835 while True:
770 newcomp = complete(text,state)
836 newcomp = complete(text,state)
771 if newcomp is None:
837 if newcomp is None:
772 break
838 break
773 comps[newcomp] = 1
839 comps[newcomp] = 1
774 state += 1
840 state += 1
775 outcomps = comps.keys()
841 outcomps = comps.keys()
776 outcomps.sort()
842 outcomps.sort()
777 return outcomps
843 return outcomps
778
844
779 def set_completer_frame(self, frame):
845 def set_completer_frame(self, frame):
780 if frame:
846 if frame:
781 self.Completer.namespace = frame.f_locals
847 self.Completer.namespace = frame.f_locals
782 self.Completer.global_namespace = frame.f_globals
848 self.Completer.global_namespace = frame.f_globals
783 else:
849 else:
784 self.Completer.namespace = self.user_ns
850 self.Completer.namespace = self.user_ns
785 self.Completer.global_namespace = self.user_global_ns
851 self.Completer.global_namespace = self.user_global_ns
786
852
787 def init_auto_alias(self):
853 def init_auto_alias(self):
788 """Define some aliases automatically.
854 """Define some aliases automatically.
789
855
790 These are ALL parameter-less aliases"""
856 These are ALL parameter-less aliases"""
791 for alias,cmd in self.auto_alias:
857 for alias,cmd in self.auto_alias:
792 self.alias_table[alias] = (0,cmd)
858 self.alias_table[alias] = (0,cmd)
793
859
794 def alias_table_validate(self,verbose=0):
860 def alias_table_validate(self,verbose=0):
795 """Update information about the alias table.
861 """Update information about the alias table.
796
862
797 In particular, make sure no Python keywords/builtins are in it."""
863 In particular, make sure no Python keywords/builtins are in it."""
798
864
799 no_alias = self.no_alias
865 no_alias = self.no_alias
800 for k in self.alias_table.keys():
866 for k in self.alias_table.keys():
801 if k in no_alias:
867 if k in no_alias:
802 del self.alias_table[k]
868 del self.alias_table[k]
803 if verbose:
869 if verbose:
804 print ("Deleting alias <%s>, it's a Python "
870 print ("Deleting alias <%s>, it's a Python "
805 "keyword or builtin." % k)
871 "keyword or builtin." % k)
806
872
807 def set_autoindent(self,value=None):
873 def set_autoindent(self,value=None):
808 """Set the autoindent flag, checking for readline support.
874 """Set the autoindent flag, checking for readline support.
809
875
810 If called with no arguments, it acts as a toggle."""
876 If called with no arguments, it acts as a toggle."""
811
877
812 if not self.has_readline:
878 if not self.has_readline:
813 if os.name == 'posix':
879 if os.name == 'posix':
814 warn("The auto-indent feature requires the readline library")
880 warn("The auto-indent feature requires the readline library")
815 self.autoindent = 0
881 self.autoindent = 0
816 return
882 return
817 if value is None:
883 if value is None:
818 self.autoindent = not self.autoindent
884 self.autoindent = not self.autoindent
819 else:
885 else:
820 self.autoindent = value
886 self.autoindent = value
821
887
822 def rc_set_toggle(self,rc_field,value=None):
888 def rc_set_toggle(self,rc_field,value=None):
823 """Set or toggle a field in IPython's rc config. structure.
889 """Set or toggle a field in IPython's rc config. structure.
824
890
825 If called with no arguments, it acts as a toggle.
891 If called with no arguments, it acts as a toggle.
826
892
827 If called with a non-existent field, the resulting AttributeError
893 If called with a non-existent field, the resulting AttributeError
828 exception will propagate out."""
894 exception will propagate out."""
829
895
830 rc_val = getattr(self.rc,rc_field)
896 rc_val = getattr(self.rc,rc_field)
831 if value is None:
897 if value is None:
832 value = not rc_val
898 value = not rc_val
833 setattr(self.rc,rc_field,value)
899 setattr(self.rc,rc_field,value)
834
900
835 def user_setup(self,ipythondir,rc_suffix,mode='install'):
901 def user_setup(self,ipythondir,rc_suffix,mode='install'):
836 """Install the user configuration directory.
902 """Install the user configuration directory.
837
903
838 Can be called when running for the first time or to upgrade the user's
904 Can be called when running for the first time or to upgrade the user's
839 .ipython/ directory with the mode parameter. Valid modes are 'install'
905 .ipython/ directory with the mode parameter. Valid modes are 'install'
840 and 'upgrade'."""
906 and 'upgrade'."""
841
907
842 def wait():
908 def wait():
843 try:
909 try:
844 raw_input("Please press <RETURN> to start IPython.")
910 raw_input("Please press <RETURN> to start IPython.")
845 except EOFError:
911 except EOFError:
846 print >> Term.cout
912 print >> Term.cout
847 print '*'*70
913 print '*'*70
848
914
849 cwd = os.getcwd() # remember where we started
915 cwd = os.getcwd() # remember where we started
850 glb = glob.glob
916 glb = glob.glob
851 print '*'*70
917 print '*'*70
852 if mode == 'install':
918 if mode == 'install':
853 print \
919 print \
854 """Welcome to IPython. I will try to create a personal configuration directory
920 """Welcome to IPython. I will try to create a personal configuration directory
855 where you can customize many aspects of IPython's functionality in:\n"""
921 where you can customize many aspects of IPython's functionality in:\n"""
856 else:
922 else:
857 print 'I am going to upgrade your configuration in:'
923 print 'I am going to upgrade your configuration in:'
858
924
859 print ipythondir
925 print ipythondir
860
926
861 rcdirend = os.path.join('IPython','UserConfig')
927 rcdirend = os.path.join('IPython','UserConfig')
862 cfg = lambda d: os.path.join(d,rcdirend)
928 cfg = lambda d: os.path.join(d,rcdirend)
863 try:
929 try:
864 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
930 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
865 except IOError:
931 except IOError:
866 warning = """
932 warning = """
867 Installation error. IPython's directory was not found.
933 Installation error. IPython's directory was not found.
868
934
869 Check the following:
935 Check the following:
870
936
871 The ipython/IPython directory should be in a directory belonging to your
937 The ipython/IPython directory should be in a directory belonging to your
872 PYTHONPATH environment variable (that is, it should be in a directory
938 PYTHONPATH environment variable (that is, it should be in a directory
873 belonging to sys.path). You can copy it explicitly there or just link to it.
939 belonging to sys.path). You can copy it explicitly there or just link to it.
874
940
875 IPython will proceed with builtin defaults.
941 IPython will proceed with builtin defaults.
876 """
942 """
877 warn(warning)
943 warn(warning)
878 wait()
944 wait()
879 return
945 return
880
946
881 if mode == 'install':
947 if mode == 'install':
882 try:
948 try:
883 shutil.copytree(rcdir,ipythondir)
949 shutil.copytree(rcdir,ipythondir)
884 os.chdir(ipythondir)
950 os.chdir(ipythondir)
885 rc_files = glb("ipythonrc*")
951 rc_files = glb("ipythonrc*")
886 for rc_file in rc_files:
952 for rc_file in rc_files:
887 os.rename(rc_file,rc_file+rc_suffix)
953 os.rename(rc_file,rc_file+rc_suffix)
888 except:
954 except:
889 warning = """
955 warning = """
890
956
891 There was a problem with the installation:
957 There was a problem with the installation:
892 %s
958 %s
893 Try to correct it or contact the developers if you think it's a bug.
959 Try to correct it or contact the developers if you think it's a bug.
894 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
960 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
895 warn(warning)
961 warn(warning)
896 wait()
962 wait()
897 return
963 return
898
964
899 elif mode == 'upgrade':
965 elif mode == 'upgrade':
900 try:
966 try:
901 os.chdir(ipythondir)
967 os.chdir(ipythondir)
902 except:
968 except:
903 print """
969 print """
904 Can not upgrade: changing to directory %s failed. Details:
970 Can not upgrade: changing to directory %s failed. Details:
905 %s
971 %s
906 """ % (ipythondir,sys.exc_info()[1])
972 """ % (ipythondir,sys.exc_info()[1])
907 wait()
973 wait()
908 return
974 return
909 else:
975 else:
910 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
976 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
911 for new_full_path in sources:
977 for new_full_path in sources:
912 new_filename = os.path.basename(new_full_path)
978 new_filename = os.path.basename(new_full_path)
913 if new_filename.startswith('ipythonrc'):
979 if new_filename.startswith('ipythonrc'):
914 new_filename = new_filename + rc_suffix
980 new_filename = new_filename + rc_suffix
915 # The config directory should only contain files, skip any
981 # The config directory should only contain files, skip any
916 # directories which may be there (like CVS)
982 # directories which may be there (like CVS)
917 if os.path.isdir(new_full_path):
983 if os.path.isdir(new_full_path):
918 continue
984 continue
919 if os.path.exists(new_filename):
985 if os.path.exists(new_filename):
920 old_file = new_filename+'.old'
986 old_file = new_filename+'.old'
921 if os.path.exists(old_file):
987 if os.path.exists(old_file):
922 os.remove(old_file)
988 os.remove(old_file)
923 os.rename(new_filename,old_file)
989 os.rename(new_filename,old_file)
924 shutil.copy(new_full_path,new_filename)
990 shutil.copy(new_full_path,new_filename)
925 else:
991 else:
926 raise ValueError,'unrecognized mode for install:',`mode`
992 raise ValueError,'unrecognized mode for install:',`mode`
927
993
928 # Fix line-endings to those native to each platform in the config
994 # Fix line-endings to those native to each platform in the config
929 # directory.
995 # directory.
930 try:
996 try:
931 os.chdir(ipythondir)
997 os.chdir(ipythondir)
932 except:
998 except:
933 print """
999 print """
934 Problem: changing to directory %s failed.
1000 Problem: changing to directory %s failed.
935 Details:
1001 Details:
936 %s
1002 %s
937
1003
938 Some configuration files may have incorrect line endings. This should not
1004 Some configuration files may have incorrect line endings. This should not
939 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1])
1005 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1])
940 wait()
1006 wait()
941 else:
1007 else:
942 for fname in glb('ipythonrc*'):
1008 for fname in glb('ipythonrc*'):
943 try:
1009 try:
944 native_line_ends(fname,backup=0)
1010 native_line_ends(fname,backup=0)
945 except IOError:
1011 except IOError:
946 pass
1012 pass
947
1013
948 if mode == 'install':
1014 if mode == 'install':
949 print """
1015 print """
950 Successful installation!
1016 Successful installation!
951
1017
952 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
1018 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
953 IPython manual (there are both HTML and PDF versions supplied with the
1019 IPython manual (there are both HTML and PDF versions supplied with the
954 distribution) to make sure that your system environment is properly configured
1020 distribution) to make sure that your system environment is properly configured
955 to take advantage of IPython's features."""
1021 to take advantage of IPython's features."""
956 else:
1022 else:
957 print """
1023 print """
958 Successful upgrade!
1024 Successful upgrade!
959
1025
960 All files in your directory:
1026 All files in your directory:
961 %(ipythondir)s
1027 %(ipythondir)s
962 which would have been overwritten by the upgrade were backed up with a .old
1028 which would have been overwritten by the upgrade were backed up with a .old
963 extension. If you had made particular customizations in those files you may
1029 extension. If you had made particular customizations in those files you may
964 want to merge them back into the new files.""" % locals()
1030 want to merge them back into the new files.""" % locals()
965 wait()
1031 wait()
966 os.chdir(cwd)
1032 os.chdir(cwd)
967 # end user_setup()
1033 # end user_setup()
968
1034
969 def atexit_operations(self):
1035 def atexit_operations(self):
970 """This will be executed at the time of exit.
1036 """This will be executed at the time of exit.
971
1037
972 Saving of persistent data should be performed here. """
1038 Saving of persistent data should be performed here. """
973
1039
974 # input history
1040 # input history
975 self.savehist()
1041 self.savehist()
976
1042
977 # Cleanup all tempfiles left around
1043 # Cleanup all tempfiles left around
978 for tfile in self.tempfiles:
1044 for tfile in self.tempfiles:
979 try:
1045 try:
980 os.unlink(tfile)
1046 os.unlink(tfile)
981 except OSError:
1047 except OSError:
982 pass
1048 pass
983
1049
984 # save the "persistent data" catch-all dictionary
1050 # save the "persistent data" catch-all dictionary
985 try:
1051 try:
986 pickle.dump(self.persist, open(self.persist_fname,"w"))
1052 pickle.dump(self.persist, open(self.persist_fname,"w"))
987 except:
1053 except:
988 print "*** ERROR *** persistent data saving failed."
1054 print "*** ERROR *** persistent data saving failed."
989
1055
990 def savehist(self):
1056 def savehist(self):
991 """Save input history to a file (via readline library)."""
1057 """Save input history to a file (via readline library)."""
992 try:
1058 try:
993 self.readline.write_history_file(self.histfile)
1059 self.readline.write_history_file(self.histfile)
994 except:
1060 except:
995 print 'Unable to save IPython command history to file: ' + \
1061 print 'Unable to save IPython command history to file: ' + \
996 `self.histfile`
1062 `self.histfile`
997
1063
998 def pre_readline(self):
1064 def pre_readline(self):
999 """readline hook to be used at the start of each line.
1065 """readline hook to be used at the start of each line.
1000
1066
1001 Currently it handles auto-indent only."""
1067 Currently it handles auto-indent only."""
1002
1068
1003 self.readline.insert_text(self.indent_current)
1069 self.readline.insert_text(self.indent_current)
1004
1070
1005 def init_readline(self):
1071 def init_readline(self):
1006 """Command history completion/saving/reloading."""
1072 """Command history completion/saving/reloading."""
1007 try:
1073 try:
1008 import readline
1074 import readline
1009 except ImportError:
1075 except ImportError:
1010 self.has_readline = 0
1076 self.has_readline = 0
1011 self.readline = None
1077 self.readline = None
1012 # no point in bugging windows users with this every time:
1078 # no point in bugging windows users with this every time:
1013 if os.name == 'posix':
1079 if os.name == 'posix':
1014 warn('Readline services not available on this platform.')
1080 warn('Readline services not available on this platform.')
1015 else:
1081 else:
1016 import atexit
1082 import atexit
1017 from IPython.completer import IPCompleter
1083 from IPython.completer import IPCompleter
1018 self.Completer = IPCompleter(self,
1084 self.Completer = IPCompleter(self,
1019 self.user_ns,
1085 self.user_ns,
1020 self.user_global_ns,
1086 self.user_global_ns,
1021 self.rc.readline_omit__names,
1087 self.rc.readline_omit__names,
1022 self.alias_table)
1088 self.alias_table)
1023
1089
1024 # Platform-specific configuration
1090 # Platform-specific configuration
1025 if os.name == 'nt':
1091 if os.name == 'nt':
1026 self.readline_startup_hook = readline.set_pre_input_hook
1092 self.readline_startup_hook = readline.set_pre_input_hook
1027 else:
1093 else:
1028 self.readline_startup_hook = readline.set_startup_hook
1094 self.readline_startup_hook = readline.set_startup_hook
1029
1095
1030 # Load user's initrc file (readline config)
1096 # Load user's initrc file (readline config)
1031 inputrc_name = os.environ.get('INPUTRC')
1097 inputrc_name = os.environ.get('INPUTRC')
1032 if inputrc_name is None:
1098 if inputrc_name is None:
1033 home_dir = get_home_dir()
1099 home_dir = get_home_dir()
1034 if home_dir is not None:
1100 if home_dir is not None:
1035 inputrc_name = os.path.join(home_dir,'.inputrc')
1101 inputrc_name = os.path.join(home_dir,'.inputrc')
1036 if os.path.isfile(inputrc_name):
1102 if os.path.isfile(inputrc_name):
1037 try:
1103 try:
1038 readline.read_init_file(inputrc_name)
1104 readline.read_init_file(inputrc_name)
1039 except:
1105 except:
1040 warn('Problems reading readline initialization file <%s>'
1106 warn('Problems reading readline initialization file <%s>'
1041 % inputrc_name)
1107 % inputrc_name)
1042
1108
1043 self.has_readline = 1
1109 self.has_readline = 1
1044 self.readline = readline
1110 self.readline = readline
1045 # save this in sys so embedded copies can restore it properly
1111 # save this in sys so embedded copies can restore it properly
1046 sys.ipcompleter = self.Completer.complete
1112 sys.ipcompleter = self.Completer.complete
1047 readline.set_completer(self.Completer.complete)
1113 readline.set_completer(self.Completer.complete)
1048
1114
1049 # Configure readline according to user's prefs
1115 # Configure readline according to user's prefs
1050 for rlcommand in self.rc.readline_parse_and_bind:
1116 for rlcommand in self.rc.readline_parse_and_bind:
1051 readline.parse_and_bind(rlcommand)
1117 readline.parse_and_bind(rlcommand)
1052
1118
1053 # remove some chars from the delimiters list
1119 # remove some chars from the delimiters list
1054 delims = readline.get_completer_delims()
1120 delims = readline.get_completer_delims()
1055 delims = delims.translate(string._idmap,
1121 delims = delims.translate(string._idmap,
1056 self.rc.readline_remove_delims)
1122 self.rc.readline_remove_delims)
1057 readline.set_completer_delims(delims)
1123 readline.set_completer_delims(delims)
1058 # otherwise we end up with a monster history after a while:
1124 # otherwise we end up with a monster history after a while:
1059 readline.set_history_length(1000)
1125 readline.set_history_length(1000)
1060 try:
1126 try:
1061 #print '*** Reading readline history' # dbg
1127 #print '*** Reading readline history' # dbg
1062 readline.read_history_file(self.histfile)
1128 readline.read_history_file(self.histfile)
1063 except IOError:
1129 except IOError:
1064 pass # It doesn't exist yet.
1130 pass # It doesn't exist yet.
1065
1131
1066 atexit.register(self.atexit_operations)
1132 atexit.register(self.atexit_operations)
1067 del atexit
1133 del atexit
1068
1134
1069 # Configure auto-indent for all platforms
1135 # Configure auto-indent for all platforms
1070 self.set_autoindent(self.rc.autoindent)
1136 self.set_autoindent(self.rc.autoindent)
1071
1137
1072 def _should_recompile(self,e):
1138 def _should_recompile(self,e):
1073 """Utility routine for edit_syntax_error"""
1139 """Utility routine for edit_syntax_error"""
1074
1140
1075 if e.filename in ('<ipython console>','<input>','<string>',
1141 if e.filename in ('<ipython console>','<input>','<string>',
1076 '<console>'):
1142 '<console>'):
1077 return False
1143 return False
1078 try:
1144 try:
1079 if not ask_yes_no('Return to editor to correct syntax error? '
1145 if not ask_yes_no('Return to editor to correct syntax error? '
1080 '[Y/n] ','y'):
1146 '[Y/n] ','y'):
1081 return False
1147 return False
1082 except EOFError:
1148 except EOFError:
1083 return False
1149 return False
1084 self.hooks.fix_error_editor(e.filename,e.lineno,e.offset,e.msg)
1150 self.hooks.fix_error_editor(e.filename,e.lineno,e.offset,e.msg)
1085 return True
1151 return True
1086
1152
1087 def edit_syntax_error(self):
1153 def edit_syntax_error(self):
1088 """The bottom half of the syntax error handler called in the main loop.
1154 """The bottom half of the syntax error handler called in the main loop.
1089
1155
1090 Loop until syntax error is fixed or user cancels.
1156 Loop until syntax error is fixed or user cancels.
1091 """
1157 """
1092
1158
1093 while self.SyntaxTB.last_syntax_error:
1159 while self.SyntaxTB.last_syntax_error:
1094 # copy and clear last_syntax_error
1160 # copy and clear last_syntax_error
1095 err = self.SyntaxTB.clear_err_state()
1161 err = self.SyntaxTB.clear_err_state()
1096 if not self._should_recompile(err):
1162 if not self._should_recompile(err):
1097 return
1163 return
1098 try:
1164 try:
1099 # may set last_syntax_error again if a SyntaxError is raised
1165 # may set last_syntax_error again if a SyntaxError is raised
1100 self.safe_execfile(err.filename,self.shell.user_ns)
1166 self.safe_execfile(err.filename,self.shell.user_ns)
1101 except:
1167 except:
1102 self.showtraceback()
1168 self.showtraceback()
1103 else:
1169 else:
1104 f = file(err.filename)
1170 f = file(err.filename)
1105 try:
1171 try:
1106 sys.displayhook(f.read())
1172 sys.displayhook(f.read())
1107 finally:
1173 finally:
1108 f.close()
1174 f.close()
1109
1175
1110 def showsyntaxerror(self, filename=None):
1176 def showsyntaxerror(self, filename=None):
1111 """Display the syntax error that just occurred.
1177 """Display the syntax error that just occurred.
1112
1178
1113 This doesn't display a stack trace because there isn't one.
1179 This doesn't display a stack trace because there isn't one.
1114
1180
1115 If a filename is given, it is stuffed in the exception instead
1181 If a filename is given, it is stuffed in the exception instead
1116 of what was there before (because Python's parser always uses
1182 of what was there before (because Python's parser always uses
1117 "<string>" when reading from a string).
1183 "<string>" when reading from a string).
1118 """
1184 """
1119 type, value, sys.last_traceback = sys.exc_info()
1185 type, value, sys.last_traceback = sys.exc_info()
1120 sys.last_type = type
1186 sys.last_type = type
1121 sys.last_value = value
1187 sys.last_value = value
1122 if filename and type is SyntaxError:
1188 if filename and type is SyntaxError:
1123 # Work hard to stuff the correct filename in the exception
1189 # Work hard to stuff the correct filename in the exception
1124 try:
1190 try:
1125 msg, (dummy_filename, lineno, offset, line) = value
1191 msg, (dummy_filename, lineno, offset, line) = value
1126 except:
1192 except:
1127 # Not the format we expect; leave it alone
1193 # Not the format we expect; leave it alone
1128 pass
1194 pass
1129 else:
1195 else:
1130 # Stuff in the right filename
1196 # Stuff in the right filename
1131 try:
1197 try:
1132 # Assume SyntaxError is a class exception
1198 # Assume SyntaxError is a class exception
1133 value = SyntaxError(msg, (filename, lineno, offset, line))
1199 value = SyntaxError(msg, (filename, lineno, offset, line))
1134 except:
1200 except:
1135 # If that failed, assume SyntaxError is a string
1201 # If that failed, assume SyntaxError is a string
1136 value = msg, (filename, lineno, offset, line)
1202 value = msg, (filename, lineno, offset, line)
1137 self.SyntaxTB(type,value,[])
1203 self.SyntaxTB(type,value,[])
1138
1204
1139 def debugger(self):
1205 def debugger(self):
1140 """Call the pdb debugger."""
1206 """Call the pdb debugger."""
1141
1207
1142 if not self.rc.pdb:
1208 if not self.rc.pdb:
1143 return
1209 return
1144 pdb.pm()
1210 pdb.pm()
1145
1211
1146 def showtraceback(self,exc_tuple = None,filename=None):
1212 def showtraceback(self,exc_tuple = None,filename=None):
1147 """Display the exception that just occurred."""
1213 """Display the exception that just occurred."""
1148
1214
1149 # Though this won't be called by syntax errors in the input line,
1215 # Though this won't be called by syntax errors in the input line,
1150 # there may be SyntaxError cases whith imported code.
1216 # there may be SyntaxError cases whith imported code.
1151 if exc_tuple is None:
1217 if exc_tuple is None:
1152 type, value, tb = sys.exc_info()
1218 type, value, tb = sys.exc_info()
1153 else:
1219 else:
1154 type, value, tb = exc_tuple
1220 type, value, tb = exc_tuple
1155 if type is SyntaxError:
1221 if type is SyntaxError:
1156 self.showsyntaxerror(filename)
1222 self.showsyntaxerror(filename)
1157 else:
1223 else:
1158 sys.last_type = type
1224 sys.last_type = type
1159 sys.last_value = value
1225 sys.last_value = value
1160 sys.last_traceback = tb
1226 sys.last_traceback = tb
1161 self.InteractiveTB()
1227 self.InteractiveTB()
1162 if self.InteractiveTB.call_pdb and self.has_readline:
1228 if self.InteractiveTB.call_pdb and self.has_readline:
1163 # pdb mucks up readline, fix it back
1229 # pdb mucks up readline, fix it back
1164 self.readline.set_completer(self.Completer.complete)
1230 self.readline.set_completer(self.Completer.complete)
1165
1231
1166 def update_cache(self, line):
1232 def update_cache(self, line):
1167 """puts line into cache"""
1233 """puts line into cache"""
1168 self.inputcache.insert(0, line) # This copies the cache every time ... :-(
1234 self.inputcache.insert(0, line) # This copies the cache every time ... :-(
1169 if len(self.inputcache) >= self.CACHELENGTH:
1235 if len(self.inputcache) >= self.CACHELENGTH:
1170 self.inputcache.pop() # This doesn't :-)
1236 self.inputcache.pop() # This doesn't :-)
1171
1237
1172 def mainloop(self,banner=None):
1238 def mainloop(self,banner=None):
1173 """Creates the local namespace and starts the mainloop.
1239 """Creates the local namespace and starts the mainloop.
1174
1240
1175 If an optional banner argument is given, it will override the
1241 If an optional banner argument is given, it will override the
1176 internally created default banner."""
1242 internally created default banner."""
1177
1243
1178 if self.rc.c: # Emulate Python's -c option
1244 if self.rc.c: # Emulate Python's -c option
1179 self.exec_init_cmd()
1245 self.exec_init_cmd()
1180 if banner is None:
1246 if banner is None:
1181 if self.rc.banner:
1247 if self.rc.banner:
1182 banner = self.BANNER+self.banner2
1248 banner = self.BANNER+self.banner2
1183 else:
1249 else:
1184 banner = ''
1250 banner = ''
1185 self.interact(banner)
1251 self.interact(banner)
1186
1252
1187 def exec_init_cmd(self):
1253 def exec_init_cmd(self):
1188 """Execute a command given at the command line.
1254 """Execute a command given at the command line.
1189
1255
1190 This emulates Python's -c option."""
1256 This emulates Python's -c option."""
1191
1257
1192 sys.argv = ['-c']
1258 sys.argv = ['-c']
1193 self.push(self.rc.c)
1259 self.push(self.rc.c)
1194
1260
1195 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1261 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1196 """Embeds IPython into a running python program.
1262 """Embeds IPython into a running python program.
1197
1263
1198 Input:
1264 Input:
1199
1265
1200 - header: An optional header message can be specified.
1266 - header: An optional header message can be specified.
1201
1267
1202 - local_ns, global_ns: working namespaces. If given as None, the
1268 - local_ns, global_ns: working namespaces. If given as None, the
1203 IPython-initialized one is updated with __main__.__dict__, so that
1269 IPython-initialized one is updated with __main__.__dict__, so that
1204 program variables become visible but user-specific configuration
1270 program variables become visible but user-specific configuration
1205 remains possible.
1271 remains possible.
1206
1272
1207 - stack_depth: specifies how many levels in the stack to go to
1273 - stack_depth: specifies how many levels in the stack to go to
1208 looking for namespaces (when local_ns and global_ns are None). This
1274 looking for namespaces (when local_ns and global_ns are None). This
1209 allows an intermediate caller to make sure that this function gets
1275 allows an intermediate caller to make sure that this function gets
1210 the namespace from the intended level in the stack. By default (0)
1276 the namespace from the intended level in the stack. By default (0)
1211 it will get its locals and globals from the immediate caller.
1277 it will get its locals and globals from the immediate caller.
1212
1278
1213 Warning: it's possible to use this in a program which is being run by
1279 Warning: it's possible to use this in a program which is being run by
1214 IPython itself (via %run), but some funny things will happen (a few
1280 IPython itself (via %run), but some funny things will happen (a few
1215 globals get overwritten). In the future this will be cleaned up, as
1281 globals get overwritten). In the future this will be cleaned up, as
1216 there is no fundamental reason why it can't work perfectly."""
1282 there is no fundamental reason why it can't work perfectly."""
1217
1283
1218 # Get locals and globals from caller
1284 # Get locals and globals from caller
1219 if local_ns is None or global_ns is None:
1285 if local_ns is None or global_ns is None:
1220 call_frame = sys._getframe(stack_depth).f_back
1286 call_frame = sys._getframe(stack_depth).f_back
1221
1287
1222 if local_ns is None:
1288 if local_ns is None:
1223 local_ns = call_frame.f_locals
1289 local_ns = call_frame.f_locals
1224 if global_ns is None:
1290 if global_ns is None:
1225 global_ns = call_frame.f_globals
1291 global_ns = call_frame.f_globals
1226
1292
1227 # Update namespaces and fire up interpreter
1293 # Update namespaces and fire up interpreter
1228 self.user_ns = local_ns
1294 self.user_ns = local_ns
1229 self.user_global_ns = global_ns
1295 self.user_global_ns = global_ns
1230
1296
1231 # Patch for global embedding to make sure that things don't overwrite
1297 # Patch for global embedding to make sure that things don't overwrite
1232 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1298 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1233 # FIXME. Test this a bit more carefully (the if.. is new)
1299 # FIXME. Test this a bit more carefully (the if.. is new)
1234 if local_ns is None and global_ns is None:
1300 if local_ns is None and global_ns is None:
1235 self.user_global_ns.update(__main__.__dict__)
1301 self.user_global_ns.update(__main__.__dict__)
1236
1302
1237 # make sure the tab-completer has the correct frame information, so it
1303 # make sure the tab-completer has the correct frame information, so it
1238 # actually completes using the frame's locals/globals
1304 # actually completes using the frame's locals/globals
1239 self.set_completer_frame(call_frame)
1305 self.set_completer_frame(call_frame)
1240
1306
1241 self.interact(header)
1307 self.interact(header)
1242
1308
1243 def interact(self, banner=None):
1309 def interact(self, banner=None):
1244 """Closely emulate the interactive Python console.
1310 """Closely emulate the interactive Python console.
1245
1311
1246 The optional banner argument specify the banner to print
1312 The optional banner argument specify the banner to print
1247 before the first interaction; by default it prints a banner
1313 before the first interaction; by default it prints a banner
1248 similar to the one printed by the real Python interpreter,
1314 similar to the one printed by the real Python interpreter,
1249 followed by the current class name in parentheses (so as not
1315 followed by the current class name in parentheses (so as not
1250 to confuse this with the real interpreter -- since it's so
1316 to confuse this with the real interpreter -- since it's so
1251 close!).
1317 close!).
1252
1318
1253 """
1319 """
1254 cprt = 'Type "copyright", "credits" or "license" for more information.'
1320 cprt = 'Type "copyright", "credits" or "license" for more information.'
1255 if banner is None:
1321 if banner is None:
1256 self.write("Python %s on %s\n%s\n(%s)\n" %
1322 self.write("Python %s on %s\n%s\n(%s)\n" %
1257 (sys.version, sys.platform, cprt,
1323 (sys.version, sys.platform, cprt,
1258 self.__class__.__name__))
1324 self.__class__.__name__))
1259 else:
1325 else:
1260 self.write(banner)
1326 self.write(banner)
1261
1327
1262 more = 0
1328 more = 0
1263
1329
1264 # Mark activity in the builtins
1330 # Mark activity in the builtins
1265 __builtin__.__dict__['__IPYTHON__active'] += 1
1331 __builtin__.__dict__['__IPYTHON__active'] += 1
1266
1332
1267 # compiled regexps for autoindent management
1333 # compiled regexps for autoindent management
1268 ini_spaces_re = re.compile(r'^(\s+)')
1334 ini_spaces_re = re.compile(r'^(\s+)')
1269 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
1335 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
1270
1336
1271 # exit_now is set by a call to %Exit or %Quit
1337 # exit_now is set by a call to %Exit or %Quit
1272 while not self.exit_now:
1338 while not self.exit_now:
1273 try:
1339 try:
1274 if more:
1340 if more:
1275 prompt = self.outputcache.prompt2
1341 prompt = self.outputcache.prompt2
1276 if self.autoindent:
1342 if self.autoindent:
1277 self.readline_startup_hook(self.pre_readline)
1343 self.readline_startup_hook(self.pre_readline)
1278 else:
1344 else:
1279 prompt = self.outputcache.prompt1
1345 prompt = self.outputcache.prompt1
1280 try:
1346 try:
1281 line = self.raw_input(prompt,more)
1347 line = self.raw_input(prompt,more)
1282 if self.autoindent:
1348 if self.autoindent:
1283 self.readline_startup_hook(None)
1349 self.readline_startup_hook(None)
1284 except EOFError:
1350 except EOFError:
1285 if self.autoindent:
1351 if self.autoindent:
1286 self.readline_startup_hook(None)
1352 self.readline_startup_hook(None)
1287 self.write("\n")
1353 self.write("\n")
1288 self.exit()
1354 self.exit()
1289 else:
1355 else:
1290 more = self.push(line)
1356 more = self.push(line)
1291 # Auto-indent management
1357 # Auto-indent management
1292 if self.autoindent:
1358 if self.autoindent:
1293 if line:
1359 if line:
1294 ini_spaces = ini_spaces_re.match(line)
1360 ini_spaces = ini_spaces_re.match(line)
1295 if ini_spaces:
1361 if ini_spaces:
1296 nspaces = ini_spaces.end()
1362 nspaces = ini_spaces.end()
1297 else:
1363 else:
1298 nspaces = 0
1364 nspaces = 0
1299 self.indent_current_nsp = nspaces
1365 self.indent_current_nsp = nspaces
1300
1366
1301 if line[-1] == ':':
1367 if line[-1] == ':':
1302 self.indent_current_nsp += 4
1368 self.indent_current_nsp += 4
1303 elif dedent_re.match(line):
1369 elif dedent_re.match(line):
1304 self.indent_current_nsp -= 4
1370 self.indent_current_nsp -= 4
1305 else:
1371 else:
1306 self.indent_current_nsp = 0
1372 self.indent_current_nsp = 0
1307
1373
1308 # indent_current is the actual string to be inserted
1374 # indent_current is the actual string to be inserted
1309 # by the readline hooks for indentation
1375 # by the readline hooks for indentation
1310 self.indent_current = ' '* self.indent_current_nsp
1376 self.indent_current = ' '* self.indent_current_nsp
1311
1377
1312 if (self.SyntaxTB.last_syntax_error and
1378 if (self.SyntaxTB.last_syntax_error and
1313 self.rc.autoedit_syntax):
1379 self.rc.autoedit_syntax):
1314 self.edit_syntax_error()
1380 self.edit_syntax_error()
1315
1381
1316 except KeyboardInterrupt:
1382 except KeyboardInterrupt:
1317 self.write("\nKeyboardInterrupt\n")
1383 self.write("\nKeyboardInterrupt\n")
1318 self.resetbuffer()
1384 self.resetbuffer()
1319 more = 0
1385 more = 0
1320 # keep cache in sync with the prompt counter:
1386 # keep cache in sync with the prompt counter:
1321 self.outputcache.prompt_count -= 1
1387 self.outputcache.prompt_count -= 1
1322
1388
1323 if self.autoindent:
1389 if self.autoindent:
1324 self.indent_current_nsp = 0
1390 self.indent_current_nsp = 0
1325 self.indent_current = ' '* self.indent_current_nsp
1391 self.indent_current = ' '* self.indent_current_nsp
1326
1392
1327 except bdb.BdbQuit:
1393 except bdb.BdbQuit:
1328 warn("The Python debugger has exited with a BdbQuit exception.\n"
1394 warn("The Python debugger has exited with a BdbQuit exception.\n"
1329 "Because of how pdb handles the stack, it is impossible\n"
1395 "Because of how pdb handles the stack, it is impossible\n"
1330 "for IPython to properly format this particular exception.\n"
1396 "for IPython to properly format this particular exception.\n"
1331 "IPython will resume normal operation.")
1397 "IPython will resume normal operation.")
1332
1398
1333 # We are off again...
1399 # We are off again...
1334 __builtin__.__dict__['__IPYTHON__active'] -= 1
1400 __builtin__.__dict__['__IPYTHON__active'] -= 1
1335
1401
1336 def excepthook(self, type, value, tb):
1402 def excepthook(self, type, value, tb):
1337 """One more defense for GUI apps that call sys.excepthook.
1403 """One more defense for GUI apps that call sys.excepthook.
1338
1404
1339 GUI frameworks like wxPython trap exceptions and call
1405 GUI frameworks like wxPython trap exceptions and call
1340 sys.excepthook themselves. I guess this is a feature that
1406 sys.excepthook themselves. I guess this is a feature that
1341 enables them to keep running after exceptions that would
1407 enables them to keep running after exceptions that would
1342 otherwise kill their mainloop. This is a bother for IPython
1408 otherwise kill their mainloop. This is a bother for IPython
1343 which excepts to catch all of the program exceptions with a try:
1409 which excepts to catch all of the program exceptions with a try:
1344 except: statement.
1410 except: statement.
1345
1411
1346 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1412 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1347 any app directly invokes sys.excepthook, it will look to the user like
1413 any app directly invokes sys.excepthook, it will look to the user like
1348 IPython crashed. In order to work around this, we can disable the
1414 IPython crashed. In order to work around this, we can disable the
1349 CrashHandler and replace it with this excepthook instead, which prints a
1415 CrashHandler and replace it with this excepthook instead, which prints a
1350 regular traceback using our InteractiveTB. In this fashion, apps which
1416 regular traceback using our InteractiveTB. In this fashion, apps which
1351 call sys.excepthook will generate a regular-looking exception from
1417 call sys.excepthook will generate a regular-looking exception from
1352 IPython, and the CrashHandler will only be triggered by real IPython
1418 IPython, and the CrashHandler will only be triggered by real IPython
1353 crashes.
1419 crashes.
1354
1420
1355 This hook should be used sparingly, only in places which are not likely
1421 This hook should be used sparingly, only in places which are not likely
1356 to be true IPython errors.
1422 to be true IPython errors.
1357 """
1423 """
1358
1424
1359 self.InteractiveTB(type, value, tb, tb_offset=0)
1425 self.InteractiveTB(type, value, tb, tb_offset=0)
1360 if self.InteractiveTB.call_pdb and self.has_readline:
1426 if self.InteractiveTB.call_pdb and self.has_readline:
1361 self.readline.set_completer(self.Completer.complete)
1427 self.readline.set_completer(self.Completer.complete)
1362
1428
1363 def call_alias(self,alias,rest=''):
1429 def call_alias(self,alias,rest=''):
1364 """Call an alias given its name and the rest of the line.
1430 """Call an alias given its name and the rest of the line.
1365
1431
1366 This function MUST be given a proper alias, because it doesn't make
1432 This function MUST be given a proper alias, because it doesn't make
1367 any checks when looking up into the alias table. The caller is
1433 any checks when looking up into the alias table. The caller is
1368 responsible for invoking it only with a valid alias."""
1434 responsible for invoking it only with a valid alias."""
1369
1435
1370 #print 'ALIAS: <%s>+<%s>' % (alias,rest) # dbg
1436 #print 'ALIAS: <%s>+<%s>' % (alias,rest) # dbg
1371 nargs,cmd = self.alias_table[alias]
1437 nargs,cmd = self.alias_table[alias]
1372 # Expand the %l special to be the user's input line
1438 # Expand the %l special to be the user's input line
1373 if cmd.find('%l') >= 0:
1439 if cmd.find('%l') >= 0:
1374 cmd = cmd.replace('%l',rest)
1440 cmd = cmd.replace('%l',rest)
1375 rest = ''
1441 rest = ''
1376 if nargs==0:
1442 if nargs==0:
1377 # Simple, argument-less aliases
1443 # Simple, argument-less aliases
1378 cmd = '%s %s' % (cmd,rest)
1444 cmd = '%s %s' % (cmd,rest)
1379 else:
1445 else:
1380 # Handle aliases with positional arguments
1446 # Handle aliases with positional arguments
1381 args = rest.split(None,nargs)
1447 args = rest.split(None,nargs)
1382 if len(args)< nargs:
1448 if len(args)< nargs:
1383 error('Alias <%s> requires %s arguments, %s given.' %
1449 error('Alias <%s> requires %s arguments, %s given.' %
1384 (alias,nargs,len(args)))
1450 (alias,nargs,len(args)))
1385 return
1451 return
1386 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
1452 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
1387 # Now call the macro, evaluating in the user's namespace
1453 # Now call the macro, evaluating in the user's namespace
1388 try:
1454 try:
1389 self.system(cmd)
1455 self.system(cmd)
1390 except:
1456 except:
1391 self.showtraceback()
1457 self.showtraceback()
1392
1458
1393 def runlines(self,lines):
1459 def runlines(self,lines):
1394 """Run a string of one or more lines of source.
1460 """Run a string of one or more lines of source.
1395
1461
1396 This method is capable of running a string containing multiple source
1462 This method is capable of running a string containing multiple source
1397 lines, as if they had been entered at the IPython prompt. Since it
1463 lines, as if they had been entered at the IPython prompt. Since it
1398 exposes IPython's processing machinery, the given strings can contain
1464 exposes IPython's processing machinery, the given strings can contain
1399 magic calls (%magic), special shell access (!cmd), etc."""
1465 magic calls (%magic), special shell access (!cmd), etc."""
1400
1466
1401 # We must start with a clean buffer, in case this is run from an
1467 # We must start with a clean buffer, in case this is run from an
1402 # interactive IPython session (via a magic, for example).
1468 # interactive IPython session (via a magic, for example).
1403 self.resetbuffer()
1469 self.resetbuffer()
1404 lines = lines.split('\n')
1470 lines = lines.split('\n')
1405 more = 0
1471 more = 0
1406 for line in lines:
1472 for line in lines:
1407 # skip blank lines so we don't mess up the prompt counter, but do
1473 # skip blank lines so we don't mess up the prompt counter, but do
1408 # NOT skip even a blank line if we are in a code block (more is
1474 # NOT skip even a blank line if we are in a code block (more is
1409 # true)
1475 # true)
1410 if line or more:
1476 if line or more:
1411 more = self.push((self.prefilter(line,more)))
1477 more = self.push((self.prefilter(line,more)))
1412 # IPython's runsource returns None if there was an error
1478 # IPython's runsource returns None if there was an error
1413 # compiling the code. This allows us to stop processing right
1479 # compiling the code. This allows us to stop processing right
1414 # away, so the user gets the error message at the right place.
1480 # away, so the user gets the error message at the right place.
1415 if more is None:
1481 if more is None:
1416 break
1482 break
1417 # final newline in case the input didn't have it, so that the code
1483 # final newline in case the input didn't have it, so that the code
1418 # actually does get executed
1484 # actually does get executed
1419 if more:
1485 if more:
1420 self.push('\n')
1486 self.push('\n')
1421
1487
1422 def runsource(self, source, filename='<input>', symbol='single'):
1488 def runsource(self, source, filename='<input>', symbol='single'):
1423 """Compile and run some source in the interpreter.
1489 """Compile and run some source in the interpreter.
1424
1490
1425 Arguments are as for compile_command().
1491 Arguments are as for compile_command().
1426
1492
1427 One several things can happen:
1493 One several things can happen:
1428
1494
1429 1) The input is incorrect; compile_command() raised an
1495 1) The input is incorrect; compile_command() raised an
1430 exception (SyntaxError or OverflowError). A syntax traceback
1496 exception (SyntaxError or OverflowError). A syntax traceback
1431 will be printed by calling the showsyntaxerror() method.
1497 will be printed by calling the showsyntaxerror() method.
1432
1498
1433 2) The input is incomplete, and more input is required;
1499 2) The input is incomplete, and more input is required;
1434 compile_command() returned None. Nothing happens.
1500 compile_command() returned None. Nothing happens.
1435
1501
1436 3) The input is complete; compile_command() returned a code
1502 3) The input is complete; compile_command() returned a code
1437 object. The code is executed by calling self.runcode() (which
1503 object. The code is executed by calling self.runcode() (which
1438 also handles run-time exceptions, except for SystemExit).
1504 also handles run-time exceptions, except for SystemExit).
1439
1505
1440 The return value is:
1506 The return value is:
1441
1507
1442 - True in case 2
1508 - True in case 2
1443
1509
1444 - False in the other cases, unless an exception is raised, where
1510 - False in the other cases, unless an exception is raised, where
1445 None is returned instead. This can be used by external callers to
1511 None is returned instead. This can be used by external callers to
1446 know whether to continue feeding input or not.
1512 know whether to continue feeding input or not.
1447
1513
1448 The return value can be used to decide whether to use sys.ps1 or
1514 The return value can be used to decide whether to use sys.ps1 or
1449 sys.ps2 to prompt the next line."""
1515 sys.ps2 to prompt the next line."""
1450
1516
1451 try:
1517 try:
1452 code = self.compile(source,filename,symbol)
1518 code = self.compile(source,filename,symbol)
1453 except (OverflowError, SyntaxError, ValueError):
1519 except (OverflowError, SyntaxError, ValueError):
1454 # Case 1
1520 # Case 1
1455 self.showsyntaxerror(filename)
1521 self.showsyntaxerror(filename)
1456 return None
1522 return None
1457
1523
1458 if code is None:
1524 if code is None:
1459 # Case 2
1525 # Case 2
1460 return True
1526 return True
1461
1527
1462 # Case 3
1528 # Case 3
1463 # We store the code object so that threaded shells and
1529 # We store the code object so that threaded shells and
1464 # custom exception handlers can access all this info if needed.
1530 # custom exception handlers can access all this info if needed.
1465 # The source corresponding to this can be obtained from the
1531 # The source corresponding to this can be obtained from the
1466 # buffer attribute as '\n'.join(self.buffer).
1532 # buffer attribute as '\n'.join(self.buffer).
1467 self.code_to_run = code
1533 self.code_to_run = code
1468 # now actually execute the code object
1534 # now actually execute the code object
1469 if self.runcode(code) == 0:
1535 if self.runcode(code) == 0:
1470 return False
1536 return False
1471 else:
1537 else:
1472 return None
1538 return None
1473
1539
1474 def runcode(self,code_obj):
1540 def runcode(self,code_obj):
1475 """Execute a code object.
1541 """Execute a code object.
1476
1542
1477 When an exception occurs, self.showtraceback() is called to display a
1543 When an exception occurs, self.showtraceback() is called to display a
1478 traceback.
1544 traceback.
1479
1545
1480 Return value: a flag indicating whether the code to be run completed
1546 Return value: a flag indicating whether the code to be run completed
1481 successfully:
1547 successfully:
1482
1548
1483 - 0: successful execution.
1549 - 0: successful execution.
1484 - 1: an error occurred.
1550 - 1: an error occurred.
1485 """
1551 """
1486
1552
1487 # Set our own excepthook in case the user code tries to call it
1553 # Set our own excepthook in case the user code tries to call it
1488 # directly, so that the IPython crash handler doesn't get triggered
1554 # directly, so that the IPython crash handler doesn't get triggered
1489 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1555 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1490
1556
1491 # we save the original sys.excepthook in the instance, in case config
1557 # we save the original sys.excepthook in the instance, in case config
1492 # code (such as magics) needs access to it.
1558 # code (such as magics) needs access to it.
1493 self.sys_excepthook = old_excepthook
1559 self.sys_excepthook = old_excepthook
1494 outflag = 1 # happens in more places, so it's easier as default
1560 outflag = 1 # happens in more places, so it's easier as default
1495 try:
1561 try:
1496 try:
1562 try:
1497 # Embedded instances require separate global/local namespaces
1563 # Embedded instances require separate global/local namespaces
1498 # so they can see both the surrounding (local) namespace and
1564 # so they can see both the surrounding (local) namespace and
1499 # the module-level globals when called inside another function.
1565 # the module-level globals when called inside another function.
1500 if self.embedded:
1566 if self.embedded:
1501 exec code_obj in self.user_global_ns, self.user_ns
1567 exec code_obj in self.user_global_ns, self.user_ns
1502 # Normal (non-embedded) instances should only have a single
1568 # Normal (non-embedded) instances should only have a single
1503 # namespace for user code execution, otherwise functions won't
1569 # namespace for user code execution, otherwise functions won't
1504 # see interactive top-level globals.
1570 # see interactive top-level globals.
1505 else:
1571 else:
1506 exec code_obj in self.user_ns
1572 exec code_obj in self.user_ns
1507 finally:
1573 finally:
1508 # Reset our crash handler in place
1574 # Reset our crash handler in place
1509 sys.excepthook = old_excepthook
1575 sys.excepthook = old_excepthook
1510 except SystemExit:
1576 except SystemExit:
1511 self.resetbuffer()
1577 self.resetbuffer()
1512 self.showtraceback()
1578 self.showtraceback()
1513 warn("Type exit or quit to exit IPython "
1579 warn("Type exit or quit to exit IPython "
1514 "(%Exit or %Quit do so unconditionally).",level=1)
1580 "(%Exit or %Quit do so unconditionally).",level=1)
1515 except self.custom_exceptions:
1581 except self.custom_exceptions:
1516 etype,value,tb = sys.exc_info()
1582 etype,value,tb = sys.exc_info()
1517 self.CustomTB(etype,value,tb)
1583 self.CustomTB(etype,value,tb)
1518 except:
1584 except:
1519 self.showtraceback()
1585 self.showtraceback()
1520 else:
1586 else:
1521 outflag = 0
1587 outflag = 0
1522 if softspace(sys.stdout, 0):
1588 if softspace(sys.stdout, 0):
1523 print
1589 print
1524 # Flush out code object which has been run (and source)
1590 # Flush out code object which has been run (and source)
1525 self.code_to_run = None
1591 self.code_to_run = None
1526 return outflag
1592 return outflag
1527
1593
1528 def push(self, line):
1594 def push(self, line):
1529 """Push a line to the interpreter.
1595 """Push a line to the interpreter.
1530
1596
1531 The line should not have a trailing newline; it may have
1597 The line should not have a trailing newline; it may have
1532 internal newlines. The line is appended to a buffer and the
1598 internal newlines. The line is appended to a buffer and the
1533 interpreter's runsource() method is called with the
1599 interpreter's runsource() method is called with the
1534 concatenated contents of the buffer as source. If this
1600 concatenated contents of the buffer as source. If this
1535 indicates that the command was executed or invalid, the buffer
1601 indicates that the command was executed or invalid, the buffer
1536 is reset; otherwise, the command is incomplete, and the buffer
1602 is reset; otherwise, the command is incomplete, and the buffer
1537 is left as it was after the line was appended. The return
1603 is left as it was after the line was appended. The return
1538 value is 1 if more input is required, 0 if the line was dealt
1604 value is 1 if more input is required, 0 if the line was dealt
1539 with in some way (this is the same as runsource()).
1605 with in some way (this is the same as runsource()).
1540
1606
1541 """
1607 """
1542 self.buffer.append(line)
1608 self.buffer.append(line)
1543 more = self.runsource('\n'.join(self.buffer), self.filename)
1609 more = self.runsource('\n'.join(self.buffer), self.filename)
1544 if not more:
1610 if not more:
1545 self.resetbuffer()
1611 self.resetbuffer()
1546 return more
1612 return more
1547
1613
1548 def resetbuffer(self):
1614 def resetbuffer(self):
1549 """Reset the input buffer."""
1615 """Reset the input buffer."""
1550 self.buffer[:] = []
1616 self.buffer[:] = []
1551
1617
1552 def raw_input(self,prompt='',continue_prompt=False):
1618 def raw_input(self,prompt='',continue_prompt=False):
1553 """Write a prompt and read a line.
1619 """Write a prompt and read a line.
1554
1620
1555 The returned line does not include the trailing newline.
1621 The returned line does not include the trailing newline.
1556 When the user enters the EOF key sequence, EOFError is raised.
1622 When the user enters the EOF key sequence, EOFError is raised.
1557
1623
1558 Optional inputs:
1624 Optional inputs:
1559
1625
1560 - prompt(''): a string to be printed to prompt the user.
1626 - prompt(''): a string to be printed to prompt the user.
1561
1627
1562 - continue_prompt(False): whether this line is the first one or a
1628 - continue_prompt(False): whether this line is the first one or a
1563 continuation in a sequence of inputs.
1629 continuation in a sequence of inputs.
1564 """
1630 """
1565
1631
1566 line = raw_input_original(prompt)
1632 line = raw_input_original(prompt)
1567 # Try to be reasonably smart about not re-indenting pasted input more
1633 # Try to be reasonably smart about not re-indenting pasted input more
1568 # than necessary. We do this by trimming out the auto-indent initial
1634 # than necessary. We do this by trimming out the auto-indent initial
1569 # spaces, if the user's actual input started itself with whitespace.
1635 # spaces, if the user's actual input started itself with whitespace.
1570 if self.autoindent:
1636 if self.autoindent:
1571 line2 = line[self.indent_current_nsp:]
1637 line2 = line[self.indent_current_nsp:]
1572 if line2[0:1] in (' ','\t'):
1638 if line2[0:1] in (' ','\t'):
1573 line = line2
1639 line = line2
1574 return self.prefilter(line,continue_prompt)
1640 return self.prefilter(line,continue_prompt)
1575
1641
1576 def split_user_input(self,line):
1642 def split_user_input(self,line):
1577 """Split user input into pre-char, function part and rest."""
1643 """Split user input into pre-char, function part and rest."""
1578
1644
1579 lsplit = self.line_split.match(line)
1645 lsplit = self.line_split.match(line)
1580 if lsplit is None: # no regexp match returns None
1646 if lsplit is None: # no regexp match returns None
1581 try:
1647 try:
1582 iFun,theRest = line.split(None,1)
1648 iFun,theRest = line.split(None,1)
1583 except ValueError:
1649 except ValueError:
1584 iFun,theRest = line,''
1650 iFun,theRest = line,''
1585 pre = re.match('^(\s*)(.*)',line).groups()[0]
1651 pre = re.match('^(\s*)(.*)',line).groups()[0]
1586 else:
1652 else:
1587 pre,iFun,theRest = lsplit.groups()
1653 pre,iFun,theRest = lsplit.groups()
1588
1654
1589 #print 'line:<%s>' % line # dbg
1655 #print 'line:<%s>' % line # dbg
1590 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun.strip(),theRest) # dbg
1656 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun.strip(),theRest) # dbg
1591 return pre,iFun.strip(),theRest
1657 return pre,iFun.strip(),theRest
1592
1658
1593 def _prefilter(self, line, continue_prompt):
1659 def _prefilter(self, line, continue_prompt):
1594 """Calls different preprocessors, depending on the form of line."""
1660 """Calls different preprocessors, depending on the form of line."""
1595
1661
1596 # All handlers *must* return a value, even if it's blank ('').
1662 # All handlers *must* return a value, even if it's blank ('').
1597
1663
1598 # Lines are NOT logged here. Handlers should process the line as
1664 # Lines are NOT logged here. Handlers should process the line as
1599 # needed, update the cache AND log it (so that the input cache array
1665 # needed, update the cache AND log it (so that the input cache array
1600 # stays synced).
1666 # stays synced).
1601
1667
1602 # This function is _very_ delicate, and since it's also the one which
1668 # This function is _very_ delicate, and since it's also the one which
1603 # determines IPython's response to user input, it must be as efficient
1669 # determines IPython's response to user input, it must be as efficient
1604 # as possible. For this reason it has _many_ returns in it, trying
1670 # as possible. For this reason it has _many_ returns in it, trying
1605 # always to exit as quickly as it can figure out what it needs to do.
1671 # always to exit as quickly as it can figure out what it needs to do.
1606
1672
1607 # This function is the main responsible for maintaining IPython's
1673 # This function is the main responsible for maintaining IPython's
1608 # behavior respectful of Python's semantics. So be _very_ careful if
1674 # behavior respectful of Python's semantics. So be _very_ careful if
1609 # making changes to anything here.
1675 # making changes to anything here.
1610
1676
1611 #.....................................................................
1677 #.....................................................................
1612 # Code begins
1678 # Code begins
1613
1679
1614 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
1680 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
1615
1681
1616 # save the line away in case we crash, so the post-mortem handler can
1682 # save the line away in case we crash, so the post-mortem handler can
1617 # record it
1683 # record it
1618 self._last_input_line = line
1684 self._last_input_line = line
1619
1685
1620 #print '***line: <%s>' % line # dbg
1686 #print '***line: <%s>' % line # dbg
1621
1687
1622 # the input history needs to track even empty lines
1688 # the input history needs to track even empty lines
1623 if not line.strip():
1689 if not line.strip():
1624 if not continue_prompt:
1690 if not continue_prompt:
1625 self.outputcache.prompt_count -= 1
1691 self.outputcache.prompt_count -= 1
1626 return self.handle_normal(line,continue_prompt)
1692 return self.handle_normal(line,continue_prompt)
1627 #return self.handle_normal('',continue_prompt)
1693 #return self.handle_normal('',continue_prompt)
1628
1694
1629 # print '***cont',continue_prompt # dbg
1695 # print '***cont',continue_prompt # dbg
1630 # special handlers are only allowed for single line statements
1696 # special handlers are only allowed for single line statements
1631 if continue_prompt and not self.rc.multi_line_specials:
1697 if continue_prompt and not self.rc.multi_line_specials:
1632 return self.handle_normal(line,continue_prompt)
1698 return self.handle_normal(line,continue_prompt)
1633
1699
1634 # For the rest, we need the structure of the input
1700 # For the rest, we need the structure of the input
1635 pre,iFun,theRest = self.split_user_input(line)
1701 pre,iFun,theRest = self.split_user_input(line)
1636 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1702 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1637
1703
1638 # First check for explicit escapes in the last/first character
1704 # First check for explicit escapes in the last/first character
1639 handler = None
1705 handler = None
1640 if line[-1] == self.ESC_HELP:
1706 if line[-1] == self.ESC_HELP:
1641 handler = self.esc_handlers.get(line[-1]) # the ? can be at the end
1707 handler = self.esc_handlers.get(line[-1]) # the ? can be at the end
1642 if handler is None:
1708 if handler is None:
1643 # look at the first character of iFun, NOT of line, so we skip
1709 # look at the first character of iFun, NOT of line, so we skip
1644 # leading whitespace in multiline input
1710 # leading whitespace in multiline input
1645 handler = self.esc_handlers.get(iFun[0:1])
1711 handler = self.esc_handlers.get(iFun[0:1])
1646 if handler is not None:
1712 if handler is not None:
1647 return handler(line,continue_prompt,pre,iFun,theRest)
1713 return handler(line,continue_prompt,pre,iFun,theRest)
1648 # Emacs ipython-mode tags certain input lines
1714 # Emacs ipython-mode tags certain input lines
1649 if line.endswith('# PYTHON-MODE'):
1715 if line.endswith('# PYTHON-MODE'):
1650 return self.handle_emacs(line,continue_prompt)
1716 return self.handle_emacs(line,continue_prompt)
1651
1717
1652 # Next, check if we can automatically execute this thing
1718 # Next, check if we can automatically execute this thing
1653
1719
1654 # Allow ! in multi-line statements if multi_line_specials is on:
1720 # Allow ! in multi-line statements if multi_line_specials is on:
1655 if continue_prompt and self.rc.multi_line_specials and \
1721 if continue_prompt and self.rc.multi_line_specials and \
1656 iFun.startswith(self.ESC_SHELL):
1722 iFun.startswith(self.ESC_SHELL):
1657 return self.handle_shell_escape(line,continue_prompt,
1723 return self.handle_shell_escape(line,continue_prompt,
1658 pre=pre,iFun=iFun,
1724 pre=pre,iFun=iFun,
1659 theRest=theRest)
1725 theRest=theRest)
1660
1726
1661 # Let's try to find if the input line is a magic fn
1727 # Let's try to find if the input line is a magic fn
1662 oinfo = None
1728 oinfo = None
1663 if hasattr(self,'magic_'+iFun):
1729 if hasattr(self,'magic_'+iFun):
1664 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1730 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1665 if oinfo['ismagic']:
1731 if oinfo['ismagic']:
1666 # Be careful not to call magics when a variable assignment is
1732 # Be careful not to call magics when a variable assignment is
1667 # being made (ls='hi', for example)
1733 # being made (ls='hi', for example)
1668 if self.rc.automagic and \
1734 if self.rc.automagic and \
1669 (len(theRest)==0 or theRest[0] not in '!=()<>,') and \
1735 (len(theRest)==0 or theRest[0] not in '!=()<>,') and \
1670 (self.rc.multi_line_specials or not continue_prompt):
1736 (self.rc.multi_line_specials or not continue_prompt):
1671 return self.handle_magic(line,continue_prompt,
1737 return self.handle_magic(line,continue_prompt,
1672 pre,iFun,theRest)
1738 pre,iFun,theRest)
1673 else:
1739 else:
1674 return self.handle_normal(line,continue_prompt)
1740 return self.handle_normal(line,continue_prompt)
1675
1741
1676 # If the rest of the line begins with an (in)equality, assginment or
1742 # If the rest of the line begins with an (in)equality, assginment or
1677 # function call, we should not call _ofind but simply execute it.
1743 # function call, we should not call _ofind but simply execute it.
1678 # This avoids spurious geattr() accesses on objects upon assignment.
1744 # This avoids spurious geattr() accesses on objects upon assignment.
1679 #
1745 #
1680 # It also allows users to assign to either alias or magic names true
1746 # It also allows users to assign to either alias or magic names true
1681 # python variables (the magic/alias systems always take second seat to
1747 # python variables (the magic/alias systems always take second seat to
1682 # true python code).
1748 # true python code).
1683 if theRest and theRest[0] in '!=()':
1749 if theRest and theRest[0] in '!=()':
1684 return self.handle_normal(line,continue_prompt)
1750 return self.handle_normal(line,continue_prompt)
1685
1751
1686 if oinfo is None:
1752 if oinfo is None:
1687 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1753 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1688
1754
1689 if not oinfo['found']:
1755 if not oinfo['found']:
1690 return self.handle_normal(line,continue_prompt)
1756 return self.handle_normal(line,continue_prompt)
1691 else:
1757 else:
1692 #print 'iFun <%s> rest <%s>' % (iFun,theRest) # dbg
1758 #print 'iFun <%s> rest <%s>' % (iFun,theRest) # dbg
1693 if oinfo['isalias']:
1759 if oinfo['isalias']:
1694 return self.handle_alias(line,continue_prompt,
1760 return self.handle_alias(line,continue_prompt,
1695 pre,iFun,theRest)
1761 pre,iFun,theRest)
1696
1762
1697 if self.rc.autocall and \
1763 if self.rc.autocall and \
1698 not self.re_exclude_auto.match(theRest) and \
1764 not self.re_exclude_auto.match(theRest) and \
1699 self.re_fun_name.match(iFun) and \
1765 self.re_fun_name.match(iFun) and \
1700 callable(oinfo['obj']) :
1766 callable(oinfo['obj']) :
1701 #print 'going auto' # dbg
1767 #print 'going auto' # dbg
1702 return self.handle_auto(line,continue_prompt,pre,iFun,theRest)
1768 return self.handle_auto(line,continue_prompt,pre,iFun,theRest)
1703 else:
1769 else:
1704 #print 'was callable?', callable(oinfo['obj']) # dbg
1770 #print 'was callable?', callable(oinfo['obj']) # dbg
1705 return self.handle_normal(line,continue_prompt)
1771 return self.handle_normal(line,continue_prompt)
1706
1772
1707 # If we get here, we have a normal Python line. Log and return.
1773 # If we get here, we have a normal Python line. Log and return.
1708 return self.handle_normal(line,continue_prompt)
1774 return self.handle_normal(line,continue_prompt)
1709
1775
1710 def _prefilter_dumb(self, line, continue_prompt):
1776 def _prefilter_dumb(self, line, continue_prompt):
1711 """simple prefilter function, for debugging"""
1777 """simple prefilter function, for debugging"""
1712 return self.handle_normal(line,continue_prompt)
1778 return self.handle_normal(line,continue_prompt)
1713
1779
1714 # Set the default prefilter() function (this can be user-overridden)
1780 # Set the default prefilter() function (this can be user-overridden)
1715 prefilter = _prefilter
1781 prefilter = _prefilter
1716
1782
1717 def handle_normal(self,line,continue_prompt=None,
1783 def handle_normal(self,line,continue_prompt=None,
1718 pre=None,iFun=None,theRest=None):
1784 pre=None,iFun=None,theRest=None):
1719 """Handle normal input lines. Use as a template for handlers."""
1785 """Handle normal input lines. Use as a template for handlers."""
1720
1786
1721 # With autoindent on, we need some way to exit the input loop, and I
1787 # With autoindent on, we need some way to exit the input loop, and I
1722 # don't want to force the user to have to backspace all the way to
1788 # don't want to force the user to have to backspace all the way to
1723 # clear the line. The rule will be in this case, that either two
1789 # clear the line. The rule will be in this case, that either two
1724 # lines of pure whitespace in a row, or a line of pure whitespace but
1790 # lines of pure whitespace in a row, or a line of pure whitespace but
1725 # of a size different to the indent level, will exit the input loop.
1791 # of a size different to the indent level, will exit the input loop.
1726 if (continue_prompt and self.autoindent and isspace(line) and
1792 if (continue_prompt and self.autoindent and isspace(line) and
1727 (line != self.indent_current or isspace(self.buffer[-1]))):
1793 (line != self.indent_current or isspace(self.buffer[-1]))):
1728 line = ''
1794 line = ''
1729
1795
1730 self.log(line,continue_prompt)
1796 self.log(line,continue_prompt)
1731 self.update_cache(line)
1797 self.update_cache(line)
1732 return line
1798 return line
1733
1799
1734 def handle_alias(self,line,continue_prompt=None,
1800 def handle_alias(self,line,continue_prompt=None,
1735 pre=None,iFun=None,theRest=None):
1801 pre=None,iFun=None,theRest=None):
1736 """Handle alias input lines. """
1802 """Handle alias input lines. """
1737
1803
1738 theRest = esc_quotes(theRest)
1804 theRest = esc_quotes(theRest)
1739 line_out = "%s%s.call_alias('%s','%s')" % (pre,self.name,iFun,theRest)
1805 line_out = "%s%s.call_alias('%s','%s')" % (pre,self.name,iFun,theRest)
1740 self.log(line_out,continue_prompt)
1806 self.log(line_out,continue_prompt)
1741 self.update_cache(line_out)
1807 self.update_cache(line_out)
1742 return line_out
1808 return line_out
1743
1809
1744 def handle_shell_escape(self, line, continue_prompt=None,
1810 def handle_shell_escape(self, line, continue_prompt=None,
1745 pre=None,iFun=None,theRest=None):
1811 pre=None,iFun=None,theRest=None):
1746 """Execute the line in a shell, empty return value"""
1812 """Execute the line in a shell, empty return value"""
1747
1813
1748 #print 'line in :', `line` # dbg
1814 #print 'line in :', `line` # dbg
1749 # Example of a special handler. Others follow a similar pattern.
1815 # Example of a special handler. Others follow a similar pattern.
1750 if continue_prompt: # multi-line statements
1816 if continue_prompt: # multi-line statements
1751 if iFun.startswith('!!'):
1817 if iFun.startswith('!!'):
1752 print 'SyntaxError: !! is not allowed in multiline statements'
1818 print 'SyntaxError: !! is not allowed in multiline statements'
1753 return pre
1819 return pre
1754 else:
1820 else:
1755 cmd = ("%s %s" % (iFun[1:],theRest)) #.replace('"','\\"')
1821 cmd = ("%s %s" % (iFun[1:],theRest)) #.replace('"','\\"')
1756 #line_out = '%s%s.system("%s")' % (pre,self.name,cmd)
1822 #line_out = '%s%s.system("%s")' % (pre,self.name,cmd)
1757 line_out = '%s%s.system(r"""%s"""[:-1])' % (pre,self.name,cmd + "_")
1823 line_out = '%s%s.system(r"""%s"""[:-1])' % (pre,self.name,cmd + "_")
1758 #line_out = ('%s%s.system(' % (pre,self.name)) + repr(cmd) + ')'
1824 #line_out = ('%s%s.system(' % (pre,self.name)) + repr(cmd) + ')'
1759 else: # single-line input
1825 else: # single-line input
1760 if line.startswith('!!'):
1826 if line.startswith('!!'):
1761 # rewrite iFun/theRest to properly hold the call to %sx and
1827 # rewrite iFun/theRest to properly hold the call to %sx and
1762 # the actual command to be executed, so handle_magic can work
1828 # the actual command to be executed, so handle_magic can work
1763 # correctly
1829 # correctly
1764 theRest = '%s %s' % (iFun[2:],theRest)
1830 theRest = '%s %s' % (iFun[2:],theRest)
1765 iFun = 'sx'
1831 iFun = 'sx'
1766 return self.handle_magic('%ssx %s' % (self.ESC_MAGIC,line[2:]),
1832 return self.handle_magic('%ssx %s' % (self.ESC_MAGIC,line[2:]),
1767 continue_prompt,pre,iFun,theRest)
1833 continue_prompt,pre,iFun,theRest)
1768 else:
1834 else:
1769 #cmd = esc_quotes(line[1:])
1835 #cmd = esc_quotes(line[1:])
1770 cmd=line[1:]
1836 cmd=line[1:]
1771 #line_out = '%s.system("%s")' % (self.name,cmd)
1837 #line_out = '%s.system("%s")' % (self.name,cmd)
1772 line_out = '%s.system(r"""%s"""[:-1])' % (self.name,cmd +"_")
1838 line_out = '%s.system(r"""%s"""[:-1])' % (self.name,cmd +"_")
1773 #line_out = ('%s.system(' % self.name) + repr(cmd)+ ')'
1839 #line_out = ('%s.system(' % self.name) + repr(cmd)+ ')'
1774 # update cache/log and return
1840 # update cache/log and return
1775 self.log(line_out,continue_prompt)
1841 self.log(line_out,continue_prompt)
1776 self.update_cache(line_out) # readline cache gets normal line
1842 self.update_cache(line_out) # readline cache gets normal line
1777 #print 'line out r:', `line_out` # dbg
1843 #print 'line out r:', `line_out` # dbg
1778 #print 'line out s:', line_out # dbg
1844 #print 'line out s:', line_out # dbg
1779 return line_out
1845 return line_out
1780
1846
1781 def handle_magic(self, line, continue_prompt=None,
1847 def handle_magic(self, line, continue_prompt=None,
1782 pre=None,iFun=None,theRest=None):
1848 pre=None,iFun=None,theRest=None):
1783 """Execute magic functions.
1849 """Execute magic functions.
1784
1850
1785 Also log them with a prepended # so the log is clean Python."""
1851 Also log them with a prepended # so the log is clean Python."""
1786
1852
1787 cmd = '%sipmagic("%s")' % (pre,esc_quotes('%s %s' % (iFun,theRest)))
1853 cmd = '%sipmagic("%s")' % (pre,esc_quotes('%s %s' % (iFun,theRest)))
1788 self.log(cmd,continue_prompt)
1854 self.log(cmd,continue_prompt)
1789 self.update_cache(line)
1855 self.update_cache(line)
1790 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
1856 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
1791 return cmd
1857 return cmd
1792
1858
1793 def handle_auto(self, line, continue_prompt=None,
1859 def handle_auto(self, line, continue_prompt=None,
1794 pre=None,iFun=None,theRest=None):
1860 pre=None,iFun=None,theRest=None):
1795 """Hande lines which can be auto-executed, quoting if requested."""
1861 """Hande lines which can be auto-executed, quoting if requested."""
1796
1862
1797 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1863 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1798
1864
1799 # This should only be active for single-line input!
1865 # This should only be active for single-line input!
1800 if continue_prompt:
1866 if continue_prompt:
1801 return line
1867 return line
1802
1868
1803 if pre == self.ESC_QUOTE:
1869 if pre == self.ESC_QUOTE:
1804 # Auto-quote splitting on whitespace
1870 # Auto-quote splitting on whitespace
1805 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
1871 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
1806 elif pre == self.ESC_QUOTE2:
1872 elif pre == self.ESC_QUOTE2:
1807 # Auto-quote whole string
1873 # Auto-quote whole string
1808 newcmd = '%s("%s")' % (iFun,theRest)
1874 newcmd = '%s("%s")' % (iFun,theRest)
1809 else:
1875 else:
1810 # Auto-paren
1876 # Auto-paren
1811 if theRest[0:1] in ('=','['):
1877 if theRest[0:1] in ('=','['):
1812 # Don't autocall in these cases. They can be either
1878 # Don't autocall in these cases. They can be either
1813 # rebindings of an existing callable's name, or item access
1879 # rebindings of an existing callable's name, or item access
1814 # for an object which is BOTH callable and implements
1880 # for an object which is BOTH callable and implements
1815 # __getitem__.
1881 # __getitem__.
1816 return '%s %s' % (iFun,theRest)
1882 return '%s %s' % (iFun,theRest)
1817 if theRest.endswith(';'):
1883 if theRest.endswith(';'):
1818 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
1884 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
1819 else:
1885 else:
1820 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
1886 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
1821
1887
1822 print >>Term.cout, self.outputcache.prompt1.auto_rewrite() + newcmd
1888 print >>Term.cout, self.outputcache.prompt1.auto_rewrite() + newcmd
1823 # log what is now valid Python, not the actual user input (without the
1889 # log what is now valid Python, not the actual user input (without the
1824 # final newline)
1890 # final newline)
1825 self.log(newcmd,continue_prompt)
1891 self.log(newcmd,continue_prompt)
1826 return newcmd
1892 return newcmd
1827
1893
1828 def handle_help(self, line, continue_prompt=None,
1894 def handle_help(self, line, continue_prompt=None,
1829 pre=None,iFun=None,theRest=None):
1895 pre=None,iFun=None,theRest=None):
1830 """Try to get some help for the object.
1896 """Try to get some help for the object.
1831
1897
1832 obj? or ?obj -> basic information.
1898 obj? or ?obj -> basic information.
1833 obj?? or ??obj -> more details.
1899 obj?? or ??obj -> more details.
1834 """
1900 """
1835
1901
1836 # We need to make sure that we don't process lines which would be
1902 # We need to make sure that we don't process lines which would be
1837 # otherwise valid python, such as "x=1 # what?"
1903 # otherwise valid python, such as "x=1 # what?"
1838 try:
1904 try:
1839 codeop.compile_command(line)
1905 codeop.compile_command(line)
1840 except SyntaxError:
1906 except SyntaxError:
1841 # We should only handle as help stuff which is NOT valid syntax
1907 # We should only handle as help stuff which is NOT valid syntax
1842 if line[0]==self.ESC_HELP:
1908 if line[0]==self.ESC_HELP:
1843 line = line[1:]
1909 line = line[1:]
1844 elif line[-1]==self.ESC_HELP:
1910 elif line[-1]==self.ESC_HELP:
1845 line = line[:-1]
1911 line = line[:-1]
1846 self.log('#?'+line)
1912 self.log('#?'+line)
1847 self.update_cache(line)
1913 self.update_cache(line)
1848 if line:
1914 if line:
1849 self.magic_pinfo(line)
1915 self.magic_pinfo(line)
1850 else:
1916 else:
1851 page(self.usage,screen_lines=self.rc.screen_length)
1917 page(self.usage,screen_lines=self.rc.screen_length)
1852 return '' # Empty string is needed here!
1918 return '' # Empty string is needed here!
1853 except:
1919 except:
1854 # Pass any other exceptions through to the normal handler
1920 # Pass any other exceptions through to the normal handler
1855 return self.handle_normal(line,continue_prompt)
1921 return self.handle_normal(line,continue_prompt)
1856 else:
1922 else:
1857 # If the code compiles ok, we should handle it normally
1923 # If the code compiles ok, we should handle it normally
1858 return self.handle_normal(line,continue_prompt)
1924 return self.handle_normal(line,continue_prompt)
1859
1925
1860 def handle_emacs(self,line,continue_prompt=None,
1926 def handle_emacs(self,line,continue_prompt=None,
1861 pre=None,iFun=None,theRest=None):
1927 pre=None,iFun=None,theRest=None):
1862 """Handle input lines marked by python-mode."""
1928 """Handle input lines marked by python-mode."""
1863
1929
1864 # Currently, nothing is done. Later more functionality can be added
1930 # Currently, nothing is done. Later more functionality can be added
1865 # here if needed.
1931 # here if needed.
1866
1932
1867 # The input cache shouldn't be updated
1933 # The input cache shouldn't be updated
1868
1934
1869 return line
1935 return line
1870
1936
1871 def write(self,data):
1937 def write(self,data):
1872 """Write a string to the default output"""
1938 """Write a string to the default output"""
1873 Term.cout.write(data)
1939 Term.cout.write(data)
1874
1940
1875 def write_err(self,data):
1941 def write_err(self,data):
1876 """Write a string to the default error output"""
1942 """Write a string to the default error output"""
1877 Term.cerr.write(data)
1943 Term.cerr.write(data)
1878
1944
1879 def exit(self):
1945 def exit(self):
1880 """Handle interactive exit.
1946 """Handle interactive exit.
1881
1947
1882 This method sets the exit_now attribute."""
1948 This method sets the exit_now attribute."""
1883
1949
1884 if self.rc.confirm_exit:
1950 if self.rc.confirm_exit:
1885 if ask_yes_no('Do you really want to exit ([y]/n)?','y'):
1951 if ask_yes_no('Do you really want to exit ([y]/n)?','y'):
1886 self.exit_now = True
1952 self.exit_now = True
1887 else:
1953 else:
1888 self.exit_now = True
1954 self.exit_now = True
1889 return self.exit_now
1955 return self.exit_now
1890
1956
1891 def safe_execfile(self,fname,*where,**kw):
1957 def safe_execfile(self,fname,*where,**kw):
1892 fname = os.path.expanduser(fname)
1958 fname = os.path.expanduser(fname)
1893
1959
1894 # find things also in current directory
1960 # find things also in current directory
1895 dname = os.path.dirname(fname)
1961 dname = os.path.dirname(fname)
1896 if not sys.path.count(dname):
1962 if not sys.path.count(dname):
1897 sys.path.append(dname)
1963 sys.path.append(dname)
1898
1964
1899 try:
1965 try:
1900 xfile = open(fname)
1966 xfile = open(fname)
1901 except:
1967 except:
1902 print >> Term.cerr, \
1968 print >> Term.cerr, \
1903 'Could not open file <%s> for safe execution.' % fname
1969 'Could not open file <%s> for safe execution.' % fname
1904 return None
1970 return None
1905
1971
1906 kw.setdefault('islog',0)
1972 kw.setdefault('islog',0)
1907 kw.setdefault('quiet',1)
1973 kw.setdefault('quiet',1)
1908 kw.setdefault('exit_ignore',0)
1974 kw.setdefault('exit_ignore',0)
1909 first = xfile.readline()
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 xfile.close()
1977 xfile.close()
1912 # line by line execution
1978 # line by line execution
1913 if first.startswith(_LOGHEAD) or kw['islog']:
1979 if first.startswith(loghead) or kw['islog']:
1914 print 'Loading log file <%s> one line at a time...' % fname
1980 print 'Loading log file <%s> one line at a time...' % fname
1915 if kw['quiet']:
1981 if kw['quiet']:
1916 stdout_save = sys.stdout
1982 stdout_save = sys.stdout
1917 sys.stdout = StringIO.StringIO()
1983 sys.stdout = StringIO.StringIO()
1918 try:
1984 try:
1919 globs,locs = where[0:2]
1985 globs,locs = where[0:2]
1920 except:
1986 except:
1921 try:
1987 try:
1922 globs = locs = where[0]
1988 globs = locs = where[0]
1923 except:
1989 except:
1924 globs = locs = globals()
1990 globs = locs = globals()
1925 badblocks = []
1991 badblocks = []
1926
1992
1927 # we also need to identify indented blocks of code when replaying
1993 # we also need to identify indented blocks of code when replaying
1928 # logs and put them together before passing them to an exec
1994 # logs and put them together before passing them to an exec
1929 # statement. This takes a bit of regexp and look-ahead work in the
1995 # statement. This takes a bit of regexp and look-ahead work in the
1930 # file. It's easiest if we swallow the whole thing in memory
1996 # file. It's easiest if we swallow the whole thing in memory
1931 # first, and manually walk through the lines list moving the
1997 # first, and manually walk through the lines list moving the
1932 # counter ourselves.
1998 # counter ourselves.
1933 indent_re = re.compile('\s+\S')
1999 indent_re = re.compile('\s+\S')
1934 xfile = open(fname)
2000 xfile = open(fname)
1935 filelines = xfile.readlines()
2001 filelines = xfile.readlines()
1936 xfile.close()
2002 xfile.close()
1937 nlines = len(filelines)
2003 nlines = len(filelines)
1938 lnum = 0
2004 lnum = 0
1939 while lnum < nlines:
2005 while lnum < nlines:
1940 line = filelines[lnum]
2006 line = filelines[lnum]
1941 lnum += 1
2007 lnum += 1
1942 # don't re-insert logger status info into cache
2008 # don't re-insert logger status info into cache
1943 if line.startswith('#log#'):
2009 if line.startswith('#log#'):
1944 continue
2010 continue
1945 elif line.startswith('#%s'% self.ESC_MAGIC):
1946 self.update_cache(line[1:])
1947 line = magic2python(line)
1948 elif line.startswith('#!'):
2011 elif line.startswith('#!'):
1949 self.update_cache(line[1:])
2012 self.update_cache(line[1:])
1950 else:
2013 else:
1951 # build a block of code (maybe a single line) for execution
2014 # build a block of code (maybe a single line) for execution
1952 block = line
2015 block = line
1953 try:
2016 try:
1954 next = filelines[lnum] # lnum has already incremented
2017 next = filelines[lnum] # lnum has already incremented
1955 except:
2018 except:
1956 next = None
2019 next = None
1957 while next and indent_re.match(next):
2020 while next and indent_re.match(next):
1958 block += next
2021 block += next
1959 lnum += 1
2022 lnum += 1
1960 try:
2023 try:
1961 next = filelines[lnum]
2024 next = filelines[lnum]
1962 except:
2025 except:
1963 next = None
2026 next = None
1964 # now execute the block of one or more lines
2027 # now execute the block of one or more lines
1965 try:
2028 try:
1966 exec block in globs,locs
2029 exec block in globs,locs
1967 self.update_cache(block.rstrip())
2030 self.update_cache(block.rstrip())
1968 except SystemExit:
2031 except SystemExit:
1969 pass
2032 pass
1970 except:
2033 except:
1971 badblocks.append(block.rstrip())
2034 badblocks.append(block.rstrip())
1972 if kw['quiet']: # restore stdout
2035 if kw['quiet']: # restore stdout
1973 sys.stdout.close()
2036 sys.stdout.close()
1974 sys.stdout = stdout_save
2037 sys.stdout = stdout_save
1975 print 'Finished replaying log file <%s>' % fname
2038 print 'Finished replaying log file <%s>' % fname
1976 if badblocks:
2039 if badblocks:
1977 print >> sys.stderr, ('\nThe following lines/blocks in file '
2040 print >> sys.stderr, ('\nThe following lines/blocks in file '
1978 '<%s> reported errors:' % fname)
2041 '<%s> reported errors:' % fname)
1979
2042
1980 for badline in badblocks:
2043 for badline in badblocks:
1981 print >> sys.stderr, badline
2044 print >> sys.stderr, badline
1982 else: # regular file execution
2045 else: # regular file execution
1983 try:
2046 try:
1984 execfile(fname,*where)
2047 execfile(fname,*where)
1985 except SyntaxError:
2048 except SyntaxError:
1986 etype,evalue = sys.exc_info()[:2]
2049 etype,evalue = sys.exc_info()[:2]
1987 self.SyntaxTB(etype,evalue,[])
2050 self.SyntaxTB(etype,evalue,[])
1988 warn('Failure executing file: <%s>' % fname)
2051 warn('Failure executing file: <%s>' % fname)
1989 except SystemExit,status:
2052 except SystemExit,status:
1990 if not kw['exit_ignore']:
2053 if not kw['exit_ignore']:
1991 self.InteractiveTB()
2054 self.InteractiveTB()
1992 warn('Failure executing file: <%s>' % fname)
2055 warn('Failure executing file: <%s>' % fname)
1993 except:
2056 except:
1994 self.InteractiveTB()
2057 self.InteractiveTB()
1995 warn('Failure executing file: <%s>' % fname)
2058 warn('Failure executing file: <%s>' % fname)
1996
2059
1997 #************************* end of file <iplib.py> *****************************
2060 #************************* end of file <iplib.py> *****************************
@@ -1,735 +1,701 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 IPython -- An enhanced Interactive Python
3 IPython -- An enhanced Interactive Python
4
4
5 Requires Python 2.1 or better.
5 Requires Python 2.1 or better.
6
6
7 This file contains the main make_IPython() starter function.
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 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
12 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
13 #
13 #
14 # Distributed under the terms of the BSD License. The full license is in
14 # Distributed under the terms of the BSD License. The full license is in
15 # the file COPYING, distributed as part of this software.
15 # the file COPYING, distributed as part of this software.
16 #*****************************************************************************
16 #*****************************************************************************
17
17
18 from IPython import Release
18 from IPython import Release
19 __author__ = '%s <%s>' % Release.authors['Fernando']
19 __author__ = '%s <%s>' % Release.authors['Fernando']
20 __license__ = Release.license
20 __license__ = Release.license
21 __version__ = Release.version
21 __version__ = Release.version
22
22
23 credits._Printer__data = """
23 credits._Printer__data = """
24 Python: %s
24 Python: %s
25
25
26 IPython: Fernando Perez, Janko Hauser, Nathan Gray, and many users.
26 IPython: Fernando Perez, Janko Hauser, Nathan Gray, and many users.
27 See http://ipython.scipy.org for more information.""" \
27 See http://ipython.scipy.org for more information.""" \
28 % credits._Printer__data
28 % credits._Printer__data
29
29
30 copyright._Printer__data += """
30 copyright._Printer__data += """
31
31
32 Copyright (c) 2001-2004 Fernando Perez, Janko Hauser, Nathan Gray.
32 Copyright (c) 2001-2004 Fernando Perez, Janko Hauser, Nathan Gray.
33 All Rights Reserved."""
33 All Rights Reserved."""
34
34
35 #****************************************************************************
35 #****************************************************************************
36 # Required modules
36 # Required modules
37
37
38 # From the standard library
38 # From the standard library
39 import __main__
39 import __main__
40 import __builtin__
40 import __builtin__
41 import os
41 import os
42 import re
42 import re
43 import sys
43 import sys
44 import types
44 import types
45 from pprint import pprint,pformat
45 from pprint import pprint,pformat
46
46
47 # Our own
47 # Our own
48 from IPython import DPyGetOpt
48 from IPython import DPyGetOpt
49 from IPython.Struct import Struct
49 from IPython.Struct import Struct
50 from IPython.OutputTrap import OutputTrap
50 from IPython.OutputTrap import OutputTrap
51 from IPython.ConfigLoader import ConfigLoader
51 from IPython.ConfigLoader import ConfigLoader
52 from IPython.iplib import InteractiveShell,qw_lol,import_fail_info
52 from IPython.iplib import InteractiveShell,qw_lol,import_fail_info
53 from IPython.usage import cmd_line_usage,interactive_usage
53 from IPython.usage import cmd_line_usage,interactive_usage
54 from IPython.Prompts import CachedOutput
55 from IPython.genutils import *
54 from IPython.genutils import *
56
55
57 #-----------------------------------------------------------------------------
56 #-----------------------------------------------------------------------------
58 def make_IPython(argv=None,user_ns=None,user_global_ns=None,debug=1,
57 def make_IPython(argv=None,user_ns=None,user_global_ns=None,debug=1,
59 rc_override=None,shell_class=InteractiveShell,
58 rc_override=None,shell_class=InteractiveShell,
60 embedded=False,**kw):
59 embedded=False,**kw):
61 """This is a dump of IPython into a single function.
60 """This is a dump of IPython into a single function.
62
61
63 Later it will have to be broken up in a sensible manner.
62 Later it will have to be broken up in a sensible manner.
64
63
65 Arguments:
64 Arguments:
66
65
67 - argv: a list similar to sys.argv[1:]. It should NOT contain the desired
66 - argv: a list similar to sys.argv[1:]. It should NOT contain the desired
68 script name, b/c DPyGetOpt strips the first argument only for the real
67 script name, b/c DPyGetOpt strips the first argument only for the real
69 sys.argv.
68 sys.argv.
70
69
71 - user_ns: a dict to be used as the user's namespace."""
70 - user_ns: a dict to be used as the user's namespace."""
72
71
73 #----------------------------------------------------------------------
72 #----------------------------------------------------------------------
74 # Defaults and initialization
73 # Defaults and initialization
75
74
76 # For developer debugging, deactivates crash handler and uses pdb.
75 # For developer debugging, deactivates crash handler and uses pdb.
77 DEVDEBUG = False
76 DEVDEBUG = False
78
77
79 if argv is None:
78 if argv is None:
80 argv = sys.argv
79 argv = sys.argv
81
80
82 # __IP is the main global that lives throughout and represents the whole
81 # __IP is the main global that lives throughout and represents the whole
83 # application. If the user redefines it, all bets are off as to what
82 # application. If the user redefines it, all bets are off as to what
84 # happens.
83 # happens.
85
84
86 # __IP is the name of he global which the caller will have accessible as
85 # __IP is the name of he global which the caller will have accessible as
87 # __IP.name. We set its name via the first parameter passed to
86 # __IP.name. We set its name via the first parameter passed to
88 # InteractiveShell:
87 # InteractiveShell:
89
88
90 IP = shell_class('__IP',user_ns=user_ns,user_global_ns=user_global_ns,
89 IP = shell_class('__IP',user_ns=user_ns,user_global_ns=user_global_ns,
91 embedded=embedded,**kw)
90 embedded=embedded,**kw)
92
91
93 # Put 'help' in the user namespace
92 # Put 'help' in the user namespace
94 from site import _Helper
93 from site import _Helper
95 IP.user_ns['help'] = _Helper()
94 IP.user_ns['help'] = _Helper()
96
95
97
96
98 if DEVDEBUG:
97 if DEVDEBUG:
99 # For developer debugging only (global flag)
98 # For developer debugging only (global flag)
100 from IPython import ultraTB
99 from IPython import ultraTB
101 sys.excepthook = ultraTB.VerboseTB(call_pdb=1)
100 sys.excepthook = ultraTB.VerboseTB(call_pdb=1)
102
101
103 IP.BANNER_PARTS = ['Python %s\n'
102 IP.BANNER_PARTS = ['Python %s\n'
104 'Type "copyright", "credits" or "license" '
103 'Type "copyright", "credits" or "license" '
105 'for more information.\n'
104 'for more information.\n'
106 % (sys.version.split('\n')[0],),
105 % (sys.version.split('\n')[0],),
107 "IPython %s -- An enhanced Interactive Python."
106 "IPython %s -- An enhanced Interactive Python."
108 % (__version__,),
107 % (__version__,),
109 """? -> Introduction to IPython's features.
108 """? -> Introduction to IPython's features.
110 %magic -> Information about IPython's 'magic' % functions.
109 %magic -> Information about IPython's 'magic' % functions.
111 help -> Python's own help system.
110 help -> Python's own help system.
112 object? -> Details about 'object'. ?object also works, ?? prints more.
111 object? -> Details about 'object'. ?object also works, ?? prints more.
113 """ ]
112 """ ]
114
113
115 IP.usage = interactive_usage
114 IP.usage = interactive_usage
116
115
117 # Platform-dependent suffix and directory names. We use _ipython instead
116 # Platform-dependent suffix and directory names. We use _ipython instead
118 # of .ipython under win32 b/c there's software that breaks with .named
117 # of .ipython under win32 b/c there's software that breaks with .named
119 # directories on that platform.
118 # directories on that platform.
120 if os.name == 'posix':
119 if os.name == 'posix':
121 rc_suffix = ''
120 rc_suffix = ''
122 ipdir_def = '.ipython'
121 ipdir_def = '.ipython'
123 else:
122 else:
124 rc_suffix = '.ini'
123 rc_suffix = '.ini'
125 ipdir_def = '_ipython'
124 ipdir_def = '_ipython'
126
125
127 # default directory for configuration
126 # default directory for configuration
128 ipythondir = os.path.abspath(os.environ.get('IPYTHONDIR',
127 ipythondir = os.path.abspath(os.environ.get('IPYTHONDIR',
129 os.path.join(IP.home_dir,ipdir_def)))
128 os.path.join(IP.home_dir,ipdir_def)))
130
129
131 # we need the directory where IPython itself is installed
130 # we need the directory where IPython itself is installed
132 import IPython
131 import IPython
133 IPython_dir = os.path.dirname(IPython.__file__)
132 IPython_dir = os.path.dirname(IPython.__file__)
134 del IPython
133 del IPython
135
134
136 #-------------------------------------------------------------------------
135 #-------------------------------------------------------------------------
137 # Command line handling
136 # Command line handling
138
137
139 # Valid command line options (uses DPyGetOpt syntax, like Perl's
138 # Valid command line options (uses DPyGetOpt syntax, like Perl's
140 # GetOpt::Long)
139 # GetOpt::Long)
141
140
142 # Any key not listed here gets deleted even if in the file (like session
141 # Any key not listed here gets deleted even if in the file (like session
143 # or profile). That's deliberate, to maintain the rc namespace clean.
142 # or profile). That's deliberate, to maintain the rc namespace clean.
144
143
145 # Each set of options appears twice: under _conv only the names are
144 # Each set of options appears twice: under _conv only the names are
146 # listed, indicating which type they must be converted to when reading the
145 # listed, indicating which type they must be converted to when reading the
147 # ipythonrc file. And under DPyGetOpt they are listed with the regular
146 # ipythonrc file. And under DPyGetOpt they are listed with the regular
148 # DPyGetOpt syntax (=s,=i,:f,etc).
147 # DPyGetOpt syntax (=s,=i,:f,etc).
149
148
150 # Make sure there's a space before each end of line (they get auto-joined!)
149 # Make sure there's a space before each end of line (they get auto-joined!)
151 cmdline_opts = ('autocall! autoindent! automagic! banner! cache_size|cs=i '
150 cmdline_opts = ('autocall! autoindent! automagic! banner! cache_size|cs=i '
152 'c=s classic|cl color_info! colors=s confirm_exit! '
151 'c=s classic|cl color_info! colors=s confirm_exit! '
153 'debug! deep_reload! editor=s log|l messages! nosep pdb! '
152 'debug! deep_reload! editor=s log|l messages! nosep pdb! '
154 'pprint! prompt_in1|pi1=s prompt_in2|pi2=s prompt_out|po=s '
153 'pprint! prompt_in1|pi1=s prompt_in2|pi2=s prompt_out|po=s '
155 'quick screen_length|sl=i prompts_pad_left=i '
154 'quick screen_length|sl=i prompts_pad_left=i '
156 'logfile|lf=s logplay|lp=s profile|p=s '
155 'logfile|lf=s logplay|lp=s profile|p=s '
157 'readline! readline_merge_completions! '
156 'readline! readline_merge_completions! '
158 'readline_omit__names! '
157 'readline_omit__names! '
159 'rcfile=s separate_in|si=s separate_out|so=s '
158 'rcfile=s separate_in|si=s separate_out|so=s '
160 'separate_out2|so2=s xmode=s wildcards_case_sensitive! '
159 'separate_out2|so2=s xmode=s wildcards_case_sensitive! '
161 'magic_docstrings system_verbose! '
160 'magic_docstrings system_verbose! '
162 'multi_line_specials! '
161 'multi_line_specials! '
163 'autoedit_syntax!')
162 'autoedit_syntax!')
164
163
165 # Options that can *only* appear at the cmd line (not in rcfiles).
164 # Options that can *only* appear at the cmd line (not in rcfiles).
166
165
167 # The "ignore" option is a kludge so that Emacs buffers don't crash, since
166 # The "ignore" option is a kludge so that Emacs buffers don't crash, since
168 # the 'C-c !' command in emacs automatically appends a -i option at the end.
167 # the 'C-c !' command in emacs automatically appends a -i option at the end.
169 cmdline_only = ('help ignore|i ipythondir=s Version upgrade '
168 cmdline_only = ('help ignore|i ipythondir=s Version upgrade '
170 'gthread! qthread! wthread! pylab! tk!')
169 'gthread! qthread! wthread! pylab! tk!')
171
170
172 # Build the actual name list to be used by DPyGetOpt
171 # Build the actual name list to be used by DPyGetOpt
173 opts_names = qw(cmdline_opts) + qw(cmdline_only)
172 opts_names = qw(cmdline_opts) + qw(cmdline_only)
174
173
175 # Set sensible command line defaults.
174 # Set sensible command line defaults.
176 # This should have everything from cmdline_opts and cmdline_only
175 # This should have everything from cmdline_opts and cmdline_only
177 opts_def = Struct(autocall = 1,
176 opts_def = Struct(autocall = 1,
178 autoedit_syntax = 1,
177 autoedit_syntax = 1,
179 autoindent=0,
178 autoindent=0,
180 automagic = 1,
179 automagic = 1,
181 banner = 1,
180 banner = 1,
182 cache_size = 1000,
181 cache_size = 1000,
183 c = '',
182 c = '',
184 classic = 0,
183 classic = 0,
185 colors = 'NoColor',
184 colors = 'NoColor',
186 color_info = 0,
185 color_info = 0,
187 confirm_exit = 1,
186 confirm_exit = 1,
188 debug = 0,
187 debug = 0,
189 deep_reload = 0,
188 deep_reload = 0,
190 editor = '0',
189 editor = '0',
191 help = 0,
190 help = 0,
192 ignore = 0,
191 ignore = 0,
193 ipythondir = ipythondir,
192 ipythondir = ipythondir,
194 log = 0,
193 log = 0,
195 logfile = '',
194 logfile = '',
196 logplay = '',
195 logplay = '',
197 multi_line_specials = 1,
196 multi_line_specials = 1,
198 messages = 1,
197 messages = 1,
199 nosep = 0,
198 nosep = 0,
200 pdb = 0,
199 pdb = 0,
201 pprint = 0,
200 pprint = 0,
202 profile = '',
201 profile = '',
203 prompt_in1 = 'In [\\#]: ',
202 prompt_in1 = 'In [\\#]: ',
204 prompt_in2 = ' .\\D.: ',
203 prompt_in2 = ' .\\D.: ',
205 prompt_out = 'Out[\\#]: ',
204 prompt_out = 'Out[\\#]: ',
206 prompts_pad_left = 1,
205 prompts_pad_left = 1,
207 quick = 0,
206 quick = 0,
208 readline = 1,
207 readline = 1,
209 readline_merge_completions = 1,
208 readline_merge_completions = 1,
210 readline_omit__names = 0,
209 readline_omit__names = 0,
211 rcfile = 'ipythonrc' + rc_suffix,
210 rcfile = 'ipythonrc' + rc_suffix,
212 screen_length = 0,
211 screen_length = 0,
213 separate_in = '\n',
212 separate_in = '\n',
214 separate_out = '\n',
213 separate_out = '\n',
215 separate_out2 = '',
214 separate_out2 = '',
216 system_verbose = 0,
215 system_verbose = 0,
217 gthread = 0,
216 gthread = 0,
218 qthread = 0,
217 qthread = 0,
219 wthread = 0,
218 wthread = 0,
220 pylab = 0,
219 pylab = 0,
221 tk = 0,
220 tk = 0,
222 upgrade = 0,
221 upgrade = 0,
223 Version = 0,
222 Version = 0,
224 xmode = 'Verbose',
223 xmode = 'Verbose',
225 wildcards_case_sensitive = 1,
224 wildcards_case_sensitive = 1,
226 magic_docstrings = 0, # undocumented, for doc generation
225 magic_docstrings = 0, # undocumented, for doc generation
227 )
226 )
228
227
229 # Things that will *only* appear in rcfiles (not at the command line).
228 # Things that will *only* appear in rcfiles (not at the command line).
230 # Make sure there's a space before each end of line (they get auto-joined!)
229 # Make sure there's a space before each end of line (they get auto-joined!)
231 rcfile_opts = { qwflat: 'include import_mod import_all execfile ',
230 rcfile_opts = { qwflat: 'include import_mod import_all execfile ',
232 qw_lol: 'import_some ',
231 qw_lol: 'import_some ',
233 # for things with embedded whitespace:
232 # for things with embedded whitespace:
234 list_strings:'execute alias readline_parse_and_bind ',
233 list_strings:'execute alias readline_parse_and_bind ',
235 # Regular strings need no conversion:
234 # Regular strings need no conversion:
236 None:'readline_remove_delims ',
235 None:'readline_remove_delims ',
237 }
236 }
238 # Default values for these
237 # Default values for these
239 rc_def = Struct(include = [],
238 rc_def = Struct(include = [],
240 import_mod = [],
239 import_mod = [],
241 import_all = [],
240 import_all = [],
242 import_some = [[]],
241 import_some = [[]],
243 execute = [],
242 execute = [],
244 execfile = [],
243 execfile = [],
245 alias = [],
244 alias = [],
246 readline_parse_and_bind = [],
245 readline_parse_and_bind = [],
247 readline_remove_delims = '',
246 readline_remove_delims = '',
248 )
247 )
249
248
250 # Build the type conversion dictionary from the above tables:
249 # Build the type conversion dictionary from the above tables:
251 typeconv = rcfile_opts.copy()
250 typeconv = rcfile_opts.copy()
252 typeconv.update(optstr2types(cmdline_opts))
251 typeconv.update(optstr2types(cmdline_opts))
253
252
254 # FIXME: the None key appears in both, put that back together by hand. Ugly!
253 # FIXME: the None key appears in both, put that back together by hand. Ugly!
255 typeconv[None] += ' ' + rcfile_opts[None]
254 typeconv[None] += ' ' + rcfile_opts[None]
256
255
257 # Remove quotes at ends of all strings (used to protect spaces)
256 # Remove quotes at ends of all strings (used to protect spaces)
258 typeconv[unquote_ends] = typeconv[None]
257 typeconv[unquote_ends] = typeconv[None]
259 del typeconv[None]
258 del typeconv[None]
260
259
261 # Build the list we'll use to make all config decisions with defaults:
260 # Build the list we'll use to make all config decisions with defaults:
262 opts_all = opts_def.copy()
261 opts_all = opts_def.copy()
263 opts_all.update(rc_def)
262 opts_all.update(rc_def)
264
263
265 # Build conflict resolver for recursive loading of config files:
264 # Build conflict resolver for recursive loading of config files:
266 # - preserve means the outermost file maintains the value, it is not
265 # - preserve means the outermost file maintains the value, it is not
267 # overwritten if an included file has the same key.
266 # overwritten if an included file has the same key.
268 # - add_flip applies + to the two values, so it better make sense to add
267 # - add_flip applies + to the two values, so it better make sense to add
269 # those types of keys. But it flips them first so that things loaded
268 # those types of keys. But it flips them first so that things loaded
270 # deeper in the inclusion chain have lower precedence.
269 # deeper in the inclusion chain have lower precedence.
271 conflict = {'preserve': ' '.join([ typeconv[int],
270 conflict = {'preserve': ' '.join([ typeconv[int],
272 typeconv[unquote_ends] ]),
271 typeconv[unquote_ends] ]),
273 'add_flip': ' '.join([ typeconv[qwflat],
272 'add_flip': ' '.join([ typeconv[qwflat],
274 typeconv[qw_lol],
273 typeconv[qw_lol],
275 typeconv[list_strings] ])
274 typeconv[list_strings] ])
276 }
275 }
277
276
278 # Now actually process the command line
277 # Now actually process the command line
279 getopt = DPyGetOpt.DPyGetOpt()
278 getopt = DPyGetOpt.DPyGetOpt()
280 getopt.setIgnoreCase(0)
279 getopt.setIgnoreCase(0)
281
280
282 getopt.parseConfiguration(opts_names)
281 getopt.parseConfiguration(opts_names)
283
282
284 try:
283 try:
285 getopt.processArguments(argv)
284 getopt.processArguments(argv)
286 except:
285 except:
287 print cmd_line_usage
286 print cmd_line_usage
288 warn('\nError in Arguments: ' + `sys.exc_value`)
287 warn('\nError in Arguments: ' + `sys.exc_value`)
289 sys.exit(1)
288 sys.exit(1)
290
289
291 # convert the options dict to a struct for much lighter syntax later
290 # convert the options dict to a struct for much lighter syntax later
292 opts = Struct(getopt.optionValues)
291 opts = Struct(getopt.optionValues)
293 args = getopt.freeValues
292 args = getopt.freeValues
294
293
295 # this is the struct (which has default values at this point) with which
294 # this is the struct (which has default values at this point) with which
296 # we make all decisions:
295 # we make all decisions:
297 opts_all.update(opts)
296 opts_all.update(opts)
298
297
299 # Options that force an immediate exit
298 # Options that force an immediate exit
300 if opts_all.help:
299 if opts_all.help:
301 page(cmd_line_usage)
300 page(cmd_line_usage)
302 sys.exit()
301 sys.exit()
303
302
304 if opts_all.Version:
303 if opts_all.Version:
305 print __version__
304 print __version__
306 sys.exit()
305 sys.exit()
307
306
308 if opts_all.magic_docstrings:
307 if opts_all.magic_docstrings:
309 IP.magic_magic('-latex')
308 IP.magic_magic('-latex')
310 sys.exit()
309 sys.exit()
311
310
312 # Create user config directory if it doesn't exist. This must be done
311 # Create user config directory if it doesn't exist. This must be done
313 # *after* getting the cmd line options.
312 # *after* getting the cmd line options.
314 if not os.path.isdir(opts_all.ipythondir):
313 if not os.path.isdir(opts_all.ipythondir):
315 IP.user_setup(opts_all.ipythondir,rc_suffix,'install')
314 IP.user_setup(opts_all.ipythondir,rc_suffix,'install')
316
315
317 # upgrade user config files while preserving a copy of the originals
316 # upgrade user config files while preserving a copy of the originals
318 if opts_all.upgrade:
317 if opts_all.upgrade:
319 IP.user_setup(opts_all.ipythondir,rc_suffix,'upgrade')
318 IP.user_setup(opts_all.ipythondir,rc_suffix,'upgrade')
320
319
321 # check mutually exclusive options in the *original* command line
320 # check mutually exclusive options in the *original* command line
322 mutex_opts(opts,[qw('log logfile'),qw('rcfile profile'),
321 mutex_opts(opts,[qw('log logfile'),qw('rcfile profile'),
323 qw('classic profile'),qw('classic rcfile')])
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 # Log replay
325 # Log replay
330
326
331 # if -logplay, we need to 'become' the other session. That basically means
327 # if -logplay, we need to 'become' the other session. That basically means
332 # replacing the current command line environment with that of the old
328 # replacing the current command line environment with that of the old
333 # session and moving on.
329 # session and moving on.
334
330
335 # this is needed so that later we know we're in session reload mode, as
331 # this is needed so that later we know we're in session reload mode, as
336 # opts_all will get overwritten:
332 # opts_all will get overwritten:
337 load_logplay = 0
333 load_logplay = 0
338
334
339 if opts_all.logplay:
335 if opts_all.logplay:
340 load_logplay = opts_all.logplay
336 load_logplay = opts_all.logplay
341 opts_debug_save = opts_all.debug
337 opts_debug_save = opts_all.debug
342 try:
338 try:
343 logplay = open(opts_all.logplay)
339 logplay = open(opts_all.logplay)
344 except IOError:
340 except IOError:
345 if opts_all.debug: IP.InteractiveTB()
341 if opts_all.debug: IP.InteractiveTB()
346 warn('Could not open logplay file '+`opts_all.logplay`)
342 warn('Could not open logplay file '+`opts_all.logplay`)
347 # restore state as if nothing had happened and move on, but make
343 # restore state as if nothing had happened and move on, but make
348 # sure that later we don't try to actually load the session file
344 # sure that later we don't try to actually load the session file
349 logplay = None
345 logplay = None
350 load_logplay = 0
346 load_logplay = 0
351 del opts_all.logplay
347 del opts_all.logplay
352 else:
348 else:
353 try:
349 try:
354 logplay.readline()
350 logplay.readline()
355 logplay.readline();
351 logplay.readline();
356 # this reloads that session's command line
352 # this reloads that session's command line
357 cmd = logplay.readline()[6:]
353 cmd = logplay.readline()[6:]
358 exec cmd
354 exec cmd
359 # restore the true debug flag given so that the process of
355 # restore the true debug flag given so that the process of
360 # session loading itself can be monitored.
356 # session loading itself can be monitored.
361 opts.debug = opts_debug_save
357 opts.debug = opts_debug_save
362 # save the logplay flag so later we don't overwrite the log
358 # save the logplay flag so later we don't overwrite the log
363 opts.logplay = load_logplay
359 opts.logplay = load_logplay
364 # now we must update our own structure with defaults
360 # now we must update our own structure with defaults
365 opts_all.update(opts)
361 opts_all.update(opts)
366 # now load args
362 # now load args
367 cmd = logplay.readline()[6:]
363 cmd = logplay.readline()[6:]
368 exec cmd
364 exec cmd
369 logplay.close()
365 logplay.close()
370 except:
366 except:
371 logplay.close()
367 logplay.close()
372 if opts_all.debug: IP.InteractiveTB()
368 if opts_all.debug: IP.InteractiveTB()
373 warn("Logplay file lacking full configuration information.\n"
369 warn("Logplay file lacking full configuration information.\n"
374 "I'll try to read it, but some things may not work.")
370 "I'll try to read it, but some things may not work.")
375
371
376 #-------------------------------------------------------------------------
372 #-------------------------------------------------------------------------
377 # set up output traps: catch all output from files, being run, modules
373 # set up output traps: catch all output from files, being run, modules
378 # loaded, etc. Then give it to the user in a clean form at the end.
374 # loaded, etc. Then give it to the user in a clean form at the end.
379
375
380 msg_out = 'Output messages. '
376 msg_out = 'Output messages. '
381 msg_err = 'Error messages. '
377 msg_err = 'Error messages. '
382 msg_sep = '\n'
378 msg_sep = '\n'
383 msg = Struct(config = OutputTrap('Configuration Loader',msg_out,
379 msg = Struct(config = OutputTrap('Configuration Loader',msg_out,
384 msg_err,msg_sep,debug,
380 msg_err,msg_sep,debug,
385 quiet_out=1),
381 quiet_out=1),
386 user_exec = OutputTrap('User File Execution',msg_out,
382 user_exec = OutputTrap('User File Execution',msg_out,
387 msg_err,msg_sep,debug),
383 msg_err,msg_sep,debug),
388 logplay = OutputTrap('Log Loader',msg_out,
384 logplay = OutputTrap('Log Loader',msg_out,
389 msg_err,msg_sep,debug),
385 msg_err,msg_sep,debug),
390 summary = ''
386 summary = ''
391 )
387 )
392
388
393 #-------------------------------------------------------------------------
389 #-------------------------------------------------------------------------
394 # Process user ipythonrc-type configuration files
390 # Process user ipythonrc-type configuration files
395
391
396 # turn on output trapping and log to msg.config
392 # turn on output trapping and log to msg.config
397 # remember that with debug on, trapping is actually disabled
393 # remember that with debug on, trapping is actually disabled
398 msg.config.trap_all()
394 msg.config.trap_all()
399
395
400 # look for rcfile in current or default directory
396 # look for rcfile in current or default directory
401 try:
397 try:
402 opts_all.rcfile = filefind(opts_all.rcfile,opts_all.ipythondir)
398 opts_all.rcfile = filefind(opts_all.rcfile,opts_all.ipythondir)
403 except IOError:
399 except IOError:
404 if opts_all.debug: IP.InteractiveTB()
400 if opts_all.debug: IP.InteractiveTB()
405 warn('Configuration file %s not found. Ignoring request.'
401 warn('Configuration file %s not found. Ignoring request.'
406 % (opts_all.rcfile) )
402 % (opts_all.rcfile) )
407
403
408 # 'profiles' are a shorthand notation for config filenames
404 # 'profiles' are a shorthand notation for config filenames
409 if opts_all.profile:
405 if opts_all.profile:
410 try:
406 try:
411 opts_all.rcfile = filefind('ipythonrc-' + opts_all.profile
407 opts_all.rcfile = filefind('ipythonrc-' + opts_all.profile
412 + rc_suffix,
408 + rc_suffix,
413 opts_all.ipythondir)
409 opts_all.ipythondir)
414 except IOError:
410 except IOError:
415 if opts_all.debug: IP.InteractiveTB()
411 if opts_all.debug: IP.InteractiveTB()
416 opts.profile = '' # remove profile from options if invalid
412 opts.profile = '' # remove profile from options if invalid
417 warn('Profile configuration file %s not found. Ignoring request.'
413 warn('Profile configuration file %s not found. Ignoring request.'
418 % (opts_all.profile) )
414 % (opts_all.profile) )
419
415
420 # load the config file
416 # load the config file
421 rcfiledata = None
417 rcfiledata = None
422 if opts_all.quick:
418 if opts_all.quick:
423 print 'Launching IPython in quick mode. No config file read.'
419 print 'Launching IPython in quick mode. No config file read.'
424 elif opts_all.classic:
420 elif opts_all.classic:
425 print 'Launching IPython in classic mode. No config file read.'
421 print 'Launching IPython in classic mode. No config file read.'
426 elif opts_all.rcfile:
422 elif opts_all.rcfile:
427 try:
423 try:
428 cfg_loader = ConfigLoader(conflict)
424 cfg_loader = ConfigLoader(conflict)
429 rcfiledata = cfg_loader.load(opts_all.rcfile,typeconv,
425 rcfiledata = cfg_loader.load(opts_all.rcfile,typeconv,
430 'include',opts_all.ipythondir,
426 'include',opts_all.ipythondir,
431 purge = 1,
427 purge = 1,
432 unique = conflict['preserve'])
428 unique = conflict['preserve'])
433 except:
429 except:
434 IP.InteractiveTB()
430 IP.InteractiveTB()
435 warn('Problems loading configuration file '+
431 warn('Problems loading configuration file '+
436 `opts_all.rcfile`+
432 `opts_all.rcfile`+
437 '\nStarting with default -bare bones- configuration.')
433 '\nStarting with default -bare bones- configuration.')
438 else:
434 else:
439 warn('No valid configuration file found in either currrent directory\n'+
435 warn('No valid configuration file found in either currrent directory\n'+
440 'or in the IPython config. directory: '+`opts_all.ipythondir`+
436 'or in the IPython config. directory: '+`opts_all.ipythondir`+
441 '\nProceeding with internal defaults.')
437 '\nProceeding with internal defaults.')
442
438
443 #------------------------------------------------------------------------
439 #------------------------------------------------------------------------
444 # Set exception handlers in mode requested by user.
440 # Set exception handlers in mode requested by user.
445 otrap = OutputTrap(trap_out=1) # trap messages from magic_xmode
441 otrap = OutputTrap(trap_out=1) # trap messages from magic_xmode
446 IP.magic_xmode(opts_all.xmode)
442 IP.magic_xmode(opts_all.xmode)
447 otrap.release_out()
443 otrap.release_out()
448
444
449 #------------------------------------------------------------------------
445 #------------------------------------------------------------------------
450 # Execute user config
446 # Execute user config
451
447
452 # Create a valid config structure with the right precedence order:
448 # Create a valid config structure with the right precedence order:
453 # defaults < rcfile < command line. This needs to be in the instance, so
449 # defaults < rcfile < command line. This needs to be in the instance, so
454 # that method calls below that rely on it find it.
450 # that method calls below that rely on it find it.
455 IP.rc = rc_def.copy()
451 IP.rc = rc_def.copy()
456
452
457 # Work with a local alias inside this routine to avoid unnecessary
453 # Work with a local alias inside this routine to avoid unnecessary
458 # attribute lookups.
454 # attribute lookups.
459 IP_rc = IP.rc
455 IP_rc = IP.rc
460
456
461 IP_rc.update(opts_def)
457 IP_rc.update(opts_def)
462 if rcfiledata:
458 if rcfiledata:
463 # now we can update
459 # now we can update
464 IP_rc.update(rcfiledata)
460 IP_rc.update(rcfiledata)
465 IP_rc.update(opts)
461 IP_rc.update(opts)
466 IP_rc.update(rc_override)
462 IP_rc.update(rc_override)
467
463
468 # Store the original cmd line for reference:
464 # Store the original cmd line for reference:
469 IP_rc.opts = opts
465 IP_rc.opts = opts
470 IP_rc.args = args
466 IP_rc.args = args
471
467
472 # create a *runtime* Struct like rc for holding parameters which may be
468 # create a *runtime* Struct like rc for holding parameters which may be
473 # created and/or modified by runtime user extensions.
469 # created and/or modified by runtime user extensions.
474 IP.runtime_rc = Struct()
470 IP.runtime_rc = Struct()
475
471
476 # from this point on, all config should be handled through IP_rc,
472 # from this point on, all config should be handled through IP_rc,
477 # opts* shouldn't be used anymore.
473 # opts* shouldn't be used anymore.
478
474
479 # add personal .ipython dir to sys.path so that users can put things in
475 # add personal .ipython dir to sys.path so that users can put things in
480 # there for customization
476 # there for customization
481 sys.path.append(IP_rc.ipythondir)
477 sys.path.append(IP_rc.ipythondir)
482 sys.path.insert(0, '') # add . to sys.path. Fix from Prabhu Ramachandran
478 sys.path.insert(0, '') # add . to sys.path. Fix from Prabhu Ramachandran
483
479
484 # update IP_rc with some special things that need manual
480 # update IP_rc with some special things that need manual
485 # tweaks. Basically options which affect other options. I guess this
481 # tweaks. Basically options which affect other options. I guess this
486 # should just be written so that options are fully orthogonal and we
482 # should just be written so that options are fully orthogonal and we
487 # wouldn't worry about this stuff!
483 # wouldn't worry about this stuff!
488
484
489 if IP_rc.classic:
485 if IP_rc.classic:
490 IP_rc.quick = 1
486 IP_rc.quick = 1
491 IP_rc.cache_size = 0
487 IP_rc.cache_size = 0
492 IP_rc.pprint = 0
488 IP_rc.pprint = 0
493 IP_rc.prompt_in1 = '>>> '
489 IP_rc.prompt_in1 = '>>> '
494 IP_rc.prompt_in2 = '... '
490 IP_rc.prompt_in2 = '... '
495 IP_rc.prompt_out = ''
491 IP_rc.prompt_out = ''
496 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
492 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
497 IP_rc.colors = 'NoColor'
493 IP_rc.colors = 'NoColor'
498 IP_rc.xmode = 'Plain'
494 IP_rc.xmode = 'Plain'
499
495
500 # configure readline
496 # configure readline
501 # Define the history file for saving commands in between sessions
497 # Define the history file for saving commands in between sessions
502 if IP_rc.profile:
498 if IP_rc.profile:
503 histfname = 'history-%s' % IP_rc.profile
499 histfname = 'history-%s' % IP_rc.profile
504 else:
500 else:
505 histfname = 'history'
501 histfname = 'history'
506 IP.histfile = os.path.join(opts_all.ipythondir,histfname)
502 IP.histfile = os.path.join(opts_all.ipythondir,histfname)
507
503
508 # update exception handlers with rc file status
504 # update exception handlers with rc file status
509 otrap.trap_out() # I don't want these messages ever.
505 otrap.trap_out() # I don't want these messages ever.
510 IP.magic_xmode(IP_rc.xmode)
506 IP.magic_xmode(IP_rc.xmode)
511 otrap.release_out()
507 otrap.release_out()
512
508
513 # activate logging if requested and not reloading a log
509 # activate logging if requested and not reloading a log
514 if IP_rc.logplay:
510 if IP_rc.logplay:
515 IP.magic_logstart(IP_rc.logplay + ' append')
511 IP.magic_logstart(IP_rc.logplay + ' append')
516 elif IP_rc.logfile:
512 elif IP_rc.logfile:
517 IP.magic_logstart(IP_rc.logfile)
513 IP.magic_logstart(IP_rc.logfile)
518 elif IP_rc.log:
514 elif IP_rc.log:
519 IP.magic_logstart()
515 IP.magic_logstart()
520
516
521 # find user editor so that it we don't have to look it up constantly
517 # find user editor so that it we don't have to look it up constantly
522 if IP_rc.editor.strip()=='0':
518 if IP_rc.editor.strip()=='0':
523 try:
519 try:
524 ed = os.environ['EDITOR']
520 ed = os.environ['EDITOR']
525 except KeyError:
521 except KeyError:
526 if os.name == 'posix':
522 if os.name == 'posix':
527 ed = 'vi' # the only one guaranteed to be there!
523 ed = 'vi' # the only one guaranteed to be there!
528 else:
524 else:
529 ed = 'notepad' # same in Windows!
525 ed = 'notepad' # same in Windows!
530 IP_rc.editor = ed
526 IP_rc.editor = ed
531
527
532 # Keep track of whether this is an embedded instance or not (useful for
528 # Keep track of whether this is an embedded instance or not (useful for
533 # post-mortems).
529 # post-mortems).
534 IP_rc.embedded = IP.embedded
530 IP_rc.embedded = IP.embedded
535
531
536 # Recursive reload
532 # Recursive reload
537 try:
533 try:
538 from IPython import deep_reload
534 from IPython import deep_reload
539 if IP_rc.deep_reload:
535 if IP_rc.deep_reload:
540 __builtin__.reload = deep_reload.reload
536 __builtin__.reload = deep_reload.reload
541 else:
537 else:
542 __builtin__.dreload = deep_reload.reload
538 __builtin__.dreload = deep_reload.reload
543 del deep_reload
539 del deep_reload
544 except ImportError:
540 except ImportError:
545 pass
541 pass
546
542
547 # Save the current state of our namespace so that the interactive shell
543 # Save the current state of our namespace so that the interactive shell
548 # can later know which variables have been created by us from config files
544 # can later know which variables have been created by us from config files
549 # and loading. This way, loading a file (in any way) is treated just like
545 # and loading. This way, loading a file (in any way) is treated just like
550 # defining things on the command line, and %who works as expected.
546 # defining things on the command line, and %who works as expected.
551
547
552 # DON'T do anything that affects the namespace beyond this point!
548 # DON'T do anything that affects the namespace beyond this point!
553 IP.internal_ns.update(__main__.__dict__)
549 IP.internal_ns.update(__main__.__dict__)
554
550
555 #IP.internal_ns.update(locals()) # so our stuff doesn't show up in %who
551 #IP.internal_ns.update(locals()) # so our stuff doesn't show up in %who
556
552
557 # Now run through the different sections of the users's config
553 # Now run through the different sections of the users's config
558 if IP_rc.debug:
554 if IP_rc.debug:
559 print 'Trying to execute the following configuration structure:'
555 print 'Trying to execute the following configuration structure:'
560 print '(Things listed first are deeper in the inclusion tree and get'
556 print '(Things listed first are deeper in the inclusion tree and get'
561 print 'loaded first).\n'
557 print 'loaded first).\n'
562 pprint(IP_rc.__dict__)
558 pprint(IP_rc.__dict__)
563
559
564 for mod in IP_rc.import_mod:
560 for mod in IP_rc.import_mod:
565 try:
561 try:
566 exec 'import '+mod in IP.user_ns
562 exec 'import '+mod in IP.user_ns
567 except :
563 except :
568 IP.InteractiveTB()
564 IP.InteractiveTB()
569 import_fail_info(mod)
565 import_fail_info(mod)
570
566
571 for mod_fn in IP_rc.import_some:
567 for mod_fn in IP_rc.import_some:
572 if mod_fn == []: break
568 if mod_fn == []: break
573 mod,fn = mod_fn[0],','.join(mod_fn[1:])
569 mod,fn = mod_fn[0],','.join(mod_fn[1:])
574 try:
570 try:
575 exec 'from '+mod+' import '+fn in IP.user_ns
571 exec 'from '+mod+' import '+fn in IP.user_ns
576 except :
572 except :
577 IP.InteractiveTB()
573 IP.InteractiveTB()
578 import_fail_info(mod,fn)
574 import_fail_info(mod,fn)
579
575
580 for mod in IP_rc.import_all:
576 for mod in IP_rc.import_all:
581 try:
577 try:
582 exec 'from '+mod+' import *' in IP.user_ns
578 exec 'from '+mod+' import *' in IP.user_ns
583 except :
579 except :
584 IP.InteractiveTB()
580 IP.InteractiveTB()
585 import_fail_info(mod)
581 import_fail_info(mod)
586
582
587 for code in IP_rc.execute:
583 for code in IP_rc.execute:
588 try:
584 try:
589 exec code in IP.user_ns
585 exec code in IP.user_ns
590 except:
586 except:
591 IP.InteractiveTB()
587 IP.InteractiveTB()
592 warn('Failure executing code: ' + `code`)
588 warn('Failure executing code: ' + `code`)
593
589
594 # Execute the files the user wants in ipythonrc
590 # Execute the files the user wants in ipythonrc
595 for file in IP_rc.execfile:
591 for file in IP_rc.execfile:
596 try:
592 try:
597 file = filefind(file,sys.path+[IPython_dir])
593 file = filefind(file,sys.path+[IPython_dir])
598 except IOError:
594 except IOError:
599 warn(itpl('File $file not found. Skipping it.'))
595 warn(itpl('File $file not found. Skipping it.'))
600 else:
596 else:
601 IP.safe_execfile(os.path.expanduser(file),IP.user_ns)
597 IP.safe_execfile(os.path.expanduser(file),IP.user_ns)
602
598
603 # release stdout and stderr and save config log into a global summary
599 # release stdout and stderr and save config log into a global summary
604 msg.config.release_all()
600 msg.config.release_all()
605 if IP_rc.messages:
601 if IP_rc.messages:
606 msg.summary += msg.config.summary_all()
602 msg.summary += msg.config.summary_all()
607
603
608 #------------------------------------------------------------------------
604 #------------------------------------------------------------------------
609 # Setup interactive session
605 # Setup interactive session
610
606
611 # Now we should be fully configured. We can then execute files or load
607 # Now we should be fully configured. We can then execute files or load
612 # things only needed for interactive use. Then we'll open the shell.
608 # things only needed for interactive use. Then we'll open the shell.
613
609
614 # Take a snapshot of the user namespace before opening the shell. That way
610 # Take a snapshot of the user namespace before opening the shell. That way
615 # we'll be able to identify which things were interactively defined and
611 # we'll be able to identify which things were interactively defined and
616 # which were defined through config files.
612 # which were defined through config files.
617 IP.user_config_ns = IP.user_ns.copy()
613 IP.user_config_ns = IP.user_ns.copy()
618
614
619 # Force reading a file as if it were a session log. Slower but safer.
615 # Force reading a file as if it were a session log. Slower but safer.
620 if load_logplay:
616 if load_logplay:
621 print 'Replaying log...'
617 print 'Replaying log...'
622 try:
618 try:
623 if IP_rc.debug:
619 if IP_rc.debug:
624 logplay_quiet = 0
620 logplay_quiet = 0
625 else:
621 else:
626 logplay_quiet = 1
622 logplay_quiet = 1
627
623
628 msg.logplay.trap_all()
624 msg.logplay.trap_all()
629 IP.safe_execfile(load_logplay,IP.user_ns,
625 IP.safe_execfile(load_logplay,IP.user_ns,
630 islog = 1, quiet = logplay_quiet)
626 islog = 1, quiet = logplay_quiet)
631 msg.logplay.release_all()
627 msg.logplay.release_all()
632 if IP_rc.messages:
628 if IP_rc.messages:
633 msg.summary += msg.logplay.summary_all()
629 msg.summary += msg.logplay.summary_all()
634 except:
630 except:
635 warn('Problems replaying logfile %s.' % load_logplay)
631 warn('Problems replaying logfile %s.' % load_logplay)
636 IP.InteractiveTB()
632 IP.InteractiveTB()
637
633
638 # Load remaining files in command line
634 # Load remaining files in command line
639 msg.user_exec.trap_all()
635 msg.user_exec.trap_all()
640
636
641 # Do NOT execute files named in the command line as scripts to be loaded
637 # Do NOT execute files named in the command line as scripts to be loaded
642 # by embedded instances. Doing so has the potential for an infinite
638 # by embedded instances. Doing so has the potential for an infinite
643 # recursion if there are exceptions thrown in the process.
639 # recursion if there are exceptions thrown in the process.
644
640
645 # XXX FIXME: the execution of user files should be moved out to after
641 # XXX FIXME: the execution of user files should be moved out to after
646 # ipython is fully initialized, just as if they were run via %run at the
642 # ipython is fully initialized, just as if they were run via %run at the
647 # ipython prompt. This would also give them the benefit of ipython's
643 # ipython prompt. This would also give them the benefit of ipython's
648 # nice tracebacks.
644 # nice tracebacks.
649
645
650 if not embedded and IP_rc.args:
646 if not embedded and IP_rc.args:
651 name_save = IP.user_ns['__name__']
647 name_save = IP.user_ns['__name__']
652 IP.user_ns['__name__'] = '__main__'
648 IP.user_ns['__name__'] = '__main__'
653 try:
649 try:
654 # Set our own excepthook in case the user code tries to call it
650 # Set our own excepthook in case the user code tries to call it
655 # directly. This prevents triggering the IPython crash handler.
651 # directly. This prevents triggering the IPython crash handler.
656 old_excepthook,sys.excepthook = sys.excepthook, IP.excepthook
652 old_excepthook,sys.excepthook = sys.excepthook, IP.excepthook
657 for run in args:
653 for run in args:
658 IP.safe_execfile(run,IP.user_ns)
654 IP.safe_execfile(run,IP.user_ns)
659 finally:
655 finally:
660 # Reset our crash handler in place
656 # Reset our crash handler in place
661 sys.excepthook = old_excepthook
657 sys.excepthook = old_excepthook
662
658
663 IP.user_ns['__name__'] = name_save
659 IP.user_ns['__name__'] = name_save
664
660
665 msg.user_exec.release_all()
661 msg.user_exec.release_all()
666 if IP_rc.messages:
662 if IP_rc.messages:
667 msg.summary += msg.user_exec.summary_all()
663 msg.summary += msg.user_exec.summary_all()
668
664
669 # since we can't specify a null string on the cmd line, 0 is the equivalent:
665 # since we can't specify a null string on the cmd line, 0 is the equivalent:
670 if IP_rc.nosep:
666 if IP_rc.nosep:
671 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
667 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
672 if IP_rc.separate_in == '0': IP_rc.separate_in = ''
668 if IP_rc.separate_in == '0': IP_rc.separate_in = ''
673 if IP_rc.separate_out == '0': IP_rc.separate_out = ''
669 if IP_rc.separate_out == '0': IP_rc.separate_out = ''
674 if IP_rc.separate_out2 == '0': IP_rc.separate_out2 = ''
670 if IP_rc.separate_out2 == '0': IP_rc.separate_out2 = ''
675 IP_rc.separate_in = IP_rc.separate_in.replace('\\n','\n')
671 IP_rc.separate_in = IP_rc.separate_in.replace('\\n','\n')
676 IP_rc.separate_out = IP_rc.separate_out.replace('\\n','\n')
672 IP_rc.separate_out = IP_rc.separate_out.replace('\\n','\n')
677 IP_rc.separate_out2 = IP_rc.separate_out2.replace('\\n','\n')
673 IP_rc.separate_out2 = IP_rc.separate_out2.replace('\\n','\n')
678
674
679 # Determine how many lines at the bottom of the screen are needed for
675 # Determine how many lines at the bottom of the screen are needed for
680 # showing prompts, so we can know wheter long strings are to be printed or
676 # showing prompts, so we can know wheter long strings are to be printed or
681 # paged:
677 # paged:
682 num_lines_bot = IP_rc.separate_in.count('\n')+1
678 num_lines_bot = IP_rc.separate_in.count('\n')+1
683 IP_rc.screen_length = IP_rc.screen_length - num_lines_bot
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
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
680
715 # configure startup banner
681 # configure startup banner
716 if IP_rc.c: # regular python doesn't print the banner with -c
682 if IP_rc.c: # regular python doesn't print the banner with -c
717 IP_rc.banner = 0
683 IP_rc.banner = 0
718 if IP_rc.banner:
684 if IP_rc.banner:
719 BANN_P = IP.BANNER_PARTS
685 BANN_P = IP.BANNER_PARTS
720 else:
686 else:
721 BANN_P = []
687 BANN_P = []
722
688
723 if IP_rc.profile: BANN_P.append('IPython profile: %s\n' % IP_rc.profile)
689 if IP_rc.profile: BANN_P.append('IPython profile: %s\n' % IP_rc.profile)
724
690
725 # add message log (possibly empty)
691 # add message log (possibly empty)
726 if msg.summary: BANN_P.append(msg.summary)
692 if msg.summary: BANN_P.append(msg.summary)
727 # Final banner is a string
693 # Final banner is a string
728 IP.BANNER = '\n'.join(BANN_P)
694 IP.BANNER = '\n'.join(BANN_P)
729
695
730 # Finalize the IPython instance. This assumes the rc structure is fully
696 # Finalize the IPython instance. This assumes the rc structure is fully
731 # in place.
697 # in place.
732 IP.post_config_initialization()
698 IP.post_config_initialization()
733
699
734 return IP
700 return IP
735 #************************ end of file <ipmaker.py> **************************
701 #************************ end of file <ipmaker.py> **************************
@@ -1,585 +1,585 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 #*****************************************************************************
2 #*****************************************************************************
3 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
3 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
4 #
4 #
5 # Distributed under the terms of the BSD License. The full license is in
5 # Distributed under the terms of the BSD License. The full license is in
6 # the file COPYING, distributed as part of this software.
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 from IPython import Release
11 from IPython import Release
12 __author__ = '%s <%s>' % Release.authors['Fernando']
12 __author__ = '%s <%s>' % Release.authors['Fernando']
13 __license__ = Release.license
13 __license__ = Release.license
14 __version__ = Release.version
14 __version__ = Release.version
15
15
16 __doc__ = """
16 __doc__ = """
17 IPython -- An enhanced Interactive Python
17 IPython -- An enhanced Interactive Python
18 =========================================
18 =========================================
19
19
20 A Python shell with automatic history (input and output), dynamic object
20 A Python shell with automatic history (input and output), dynamic object
21 introspection, easier configuration, command completion, access to the system
21 introspection, easier configuration, command completion, access to the system
22 shell and more.
22 shell and more.
23
23
24 IPython can also be embedded in running programs. See EMBEDDING below.
24 IPython can also be embedded in running programs. See EMBEDDING below.
25
25
26
26
27 USAGE
27 USAGE
28 ipython [options] files
28 ipython [options] files
29
29
30 If invoked with no options, it executes all the files listed in
30 If invoked with no options, it executes all the files listed in
31 sequence and drops you into the interpreter while still acknowledging
31 sequence and drops you into the interpreter while still acknowledging
32 any options you may have set in your ipythonrc file. This behavior is
32 any options you may have set in your ipythonrc file. This behavior is
33 different from standard Python, which when called as python -i will
33 different from standard Python, which when called as python -i will
34 only execute one file and will ignore your configuration setup.
34 only execute one file and will ignore your configuration setup.
35
35
36 Please note that some of the configuration options are not available at
36 Please note that some of the configuration options are not available at
37 the command line, simply because they are not practical here. Look into
37 the command line, simply because they are not practical here. Look into
38 your ipythonrc configuration file for details on those. This file
38 your ipythonrc configuration file for details on those. This file
39 typically installed in the $HOME/.ipython directory.
39 typically installed in the $HOME/.ipython directory.
40
40
41 For Windows users, $HOME resolves to C:\\Documents and
41 For Windows users, $HOME resolves to C:\\Documents and
42 Settings\\YourUserName in most instances, and _ipython is used instead
42 Settings\\YourUserName in most instances, and _ipython is used instead
43 of .ipython, since some Win32 programs have problems with dotted names
43 of .ipython, since some Win32 programs have problems with dotted names
44 in directories.
44 in directories.
45
45
46 In the rest of this text, we will refer to this directory as
46 In the rest of this text, we will refer to this directory as
47 IPYTHONDIR.
47 IPYTHONDIR.
48
48
49
49
50 SPECIAL THREADING OPTIONS
50 SPECIAL THREADING OPTIONS
51 The following special options are ONLY valid at the beginning of the
51 The following special options are ONLY valid at the beginning of the
52 command line, and not later. This is because they control the initial-
52 command line, and not later. This is because they control the initial-
53 ization of ipython itself, before the normal option-handling mechanism
53 ization of ipython itself, before the normal option-handling mechanism
54 is active.
54 is active.
55
55
56 -gthread, -qthread, -wthread, -pylab
56 -gthread, -qthread, -wthread, -pylab
57
57
58 Only ONE of these can be given, and it can only be given as the
58 Only ONE of these can be given, and it can only be given as the
59 first option passed to IPython (it will have no effect in any
59 first option passed to IPython (it will have no effect in any
60 other position). They provide threading support for the GTK, QT
60 other position). They provide threading support for the GTK, QT
61 and WXWidgets toolkits, and for the matplotlib library.
61 and WXWidgets toolkits, and for the matplotlib library.
62
62
63 With any of the first three options, IPython starts running a
63 With any of the first three options, IPython starts running a
64 separate thread for the graphical toolkit's operation, so that
64 separate thread for the graphical toolkit's operation, so that
65 you can open and control graphical elements from within an
65 you can open and control graphical elements from within an
66 IPython command line, without blocking. All three provide
66 IPython command line, without blocking. All three provide
67 essentially the same functionality, respectively for GTK, QT and
67 essentially the same functionality, respectively for GTK, QT and
68 WXWidgets (via their Python interfaces).
68 WXWidgets (via their Python interfaces).
69
69
70 If -pylab is given, IPython loads special support for the mat-
70 If -pylab is given, IPython loads special support for the mat-
71 plotlib library (http://matplotlib.sourceforge.net), allowing
71 plotlib library (http://matplotlib.sourceforge.net), allowing
72 interactive usage of any of its backends as defined in the
72 interactive usage of any of its backends as defined in the
73 user's .matplotlibrc file. It automatically activates GTK, QT
73 user's .matplotlibrc file. It automatically activates GTK, QT
74 or WX threading for IPyhton if the choice of matplotlib backend
74 or WX threading for IPyhton if the choice of matplotlib backend
75 requires it. It also modifies the %run command to correctly
75 requires it. It also modifies the %run command to correctly
76 execute (without blocking) any matplotlib-based script which
76 execute (without blocking) any matplotlib-based script which
77 calls show() at the end.
77 calls show() at the end.
78
78
79 -tk The -g/q/wthread options, and -pylab (if matplotlib is
79 -tk The -g/q/wthread options, and -pylab (if matplotlib is
80 configured to use GTK, QT or WX), will normally block Tk
80 configured to use GTK, QT or WX), will normally block Tk
81 graphical interfaces. This means that when GTK, QT or WX
81 graphical interfaces. This means that when GTK, QT or WX
82 threading is active, any attempt to open a Tk GUI will result in
82 threading is active, any attempt to open a Tk GUI will result in
83 a dead window, and possibly cause the Python interpreter to
83 a dead window, and possibly cause the Python interpreter to
84 crash. An extra option, -tk, is available to address this
84 crash. An extra option, -tk, is available to address this
85 issue. It can ONLY be given as a SECOND option after any of the
85 issue. It can ONLY be given as a SECOND option after any of the
86 above (-gthread, -qthread, -wthread or -pylab).
86 above (-gthread, -qthread, -wthread or -pylab).
87
87
88 If -tk is given, IPython will try to coordinate Tk threading
88 If -tk is given, IPython will try to coordinate Tk threading
89 with GTK, QT or WX. This is however potentially unreliable, and
89 with GTK, QT or WX. This is however potentially unreliable, and
90 you will have to test on your platform and Python configuration
90 you will have to test on your platform and Python configuration
91 to determine whether it works for you. Debian users have
91 to determine whether it works for you. Debian users have
92 reported success, apparently due to the fact that Debian builds
92 reported success, apparently due to the fact that Debian builds
93 all of Tcl, Tk, Tkinter and Python with pthreads support. Under
93 all of Tcl, Tk, Tkinter and Python with pthreads support. Under
94 other Linux environments (such as Fedora Core 2/3), this option
94 other Linux environments (such as Fedora Core 2/3), this option
95 has caused random crashes and lockups of the Python interpreter.
95 has caused random crashes and lockups of the Python interpreter.
96 Under other operating systems (Mac OSX and Windows), you'll need
96 Under other operating systems (Mac OSX and Windows), you'll need
97 to try it to find out, since currently no user reports are
97 to try it to find out, since currently no user reports are
98 available.
98 available.
99
99
100 There is unfortunately no way for IPython to determine at run-
100 There is unfortunately no way for IPython to determine at run-
101 time whether -tk will work reliably or not, so you will need to
101 time whether -tk will work reliably or not, so you will need to
102 do some experiments before relying on it for regular work.
102 do some experiments before relying on it for regular work.
103
103
104 A WARNING ABOUT SIGNALS AND THREADS
104 A WARNING ABOUT SIGNALS AND THREADS
105
105
106 When any of the thread systems (GTK, QT or WX) are active, either
106 When any of the thread systems (GTK, QT or WX) are active, either
107 directly or via -pylab with a threaded backend, it is impossible to
107 directly or via -pylab with a threaded backend, it is impossible to
108 interrupt long-running Python code via Ctrl-C. IPython can not pass
108 interrupt long-running Python code via Ctrl-C. IPython can not pass
109 the KeyboardInterrupt exception (or the underlying SIGINT) across
109 the KeyboardInterrupt exception (or the underlying SIGINT) across
110 threads, so any long-running process started from IPython will run to
110 threads, so any long-running process started from IPython will run to
111 completion, or will have to be killed via an external (OS-based)
111 completion, or will have to be killed via an external (OS-based)
112 mechanism.
112 mechanism.
113
113
114 To the best of my knowledge, this limitation is imposed by the Python
114 To the best of my knowledge, this limitation is imposed by the Python
115 interpreter itself, and it comes from the difficulty of writing
115 interpreter itself, and it comes from the difficulty of writing
116 portable signal/threaded code. If any user is an expert on this topic
116 portable signal/threaded code. If any user is an expert on this topic
117 and can suggest a better solution, I would love to hear about it. In
117 and can suggest a better solution, I would love to hear about it. In
118 the IPython sources, look at the Shell.py module, and in particular at
118 the IPython sources, look at the Shell.py module, and in particular at
119 the runcode() method.
119 the runcode() method.
120
120
121 REGULAR OPTIONS
121 REGULAR OPTIONS
122 After the above threading options have been given, regular options can
122 After the above threading options have been given, regular options can
123 follow in any order. All options can be abbreviated to their shortest
123 follow in any order. All options can be abbreviated to their shortest
124 non-ambiguous form and are case-sensitive. One or two dashes can be
124 non-ambiguous form and are case-sensitive. One or two dashes can be
125 used. Some options have an alternate short form, indicated after a |.
125 used. Some options have an alternate short form, indicated after a |.
126
126
127 Most options can also be set from your ipythonrc configuration file.
127 Most options can also be set from your ipythonrc configuration file.
128 See the provided examples for assistance. Options given on the comman-
128 See the provided examples for assistance. Options given on the comman-
129 dline override the values set in the ipythonrc file.
129 dline override the values set in the ipythonrc file.
130
130
131 All options with a [no] prepended can be specified in negated form
131 All options with a [no] prepended can be specified in negated form
132 (using -nooption instead of -option) to turn the feature off.
132 (using -nooption instead of -option) to turn the feature off.
133
133
134 -h, --help
134 -h, --help
135 Show summary of options.
135 Show summary of options.
136
136
137 -pylab This can only be given as the first option passed to IPython (it
137 -pylab This can only be given as the first option passed to IPython (it
138 will have no effect in any other position). It adds special sup-
138 will have no effect in any other position). It adds special sup-
139 port for the matplotlib library (http://matplotlib.source-
139 port for the matplotlib library (http://matplotlib.source-
140 forge.net), allowing interactive usage of any of its backends as
140 forge.net), allowing interactive usage of any of its backends as
141 defined in the user’s .matplotlibrc file. It automatically
141 defined in the user’s .matplotlibrc file. It automatically
142 activates GTK or WX threading for IPyhton if the choice of mat-
142 activates GTK or WX threading for IPyhton if the choice of mat-
143 plotlib backend requires it. It also modifies the @run command
143 plotlib backend requires it. It also modifies the @run command
144 to correctly execute (without blocking) any matplotlib-based
144 to correctly execute (without blocking) any matplotlib-based
145 script which calls show() at the end.
145 script which calls show() at the end.
146
146
147 -[no]autocall
147 -[no]autocall
148 Make IPython automatically call any callable object even if you
148 Make IPython automatically call any callable object even if you
149 didn’t type explicit parentheses. For example, ’str 43’ becomes
149 didn’t type explicit parentheses. For example, ’str 43’ becomes
150 ’str(43)’ automatically.
150 ’str(43)’ automatically.
151
151
152 -[no]autoindent
152 -[no]autoindent
153 Turn automatic indentation on/off.
153 Turn automatic indentation on/off.
154
154
155 -[no]automagic
155 -[no]automagic
156 Make magic commands automatic (without needing their first char-
156 Make magic commands automatic (without needing their first char-
157 acter to be %). Type %magic at the IPython prompt for more
157 acter to be %). Type %magic at the IPython prompt for more
158 information.
158 information.
159
159
160 -[no]autoedit_syntax
160 -[no]autoedit_syntax
161 When a syntax error occurs after editing a file, automatically
161 When a syntax error occurs after editing a file, automatically
162 open the file to the trouble causing line for convenient fixing.
162 open the file to the trouble causing line for convenient fixing.
163
163
164 -[no]banner
164 -[no]banner
165 Print the intial information banner (default on).
165 Print the intial information banner (default on).
166
166
167 -c <command>
167 -c <command>
168 Execute the given command string, and set sys.argv to [’c’].
168 Execute the given command string, and set sys.argv to [’c’].
169 This is similar to the -c option in the normal Python inter-
169 This is similar to the -c option in the normal Python inter-
170 preter.
170 preter.
171
171
172 -cache_size|cs <n>
172 -cache_size|cs <n>
173 Size of the output cache (maximum number of entries to hold in
173 Size of the output cache (maximum number of entries to hold in
174 memory). The default is 1000, you can change it permanently in
174 memory). The default is 1000, you can change it permanently in
175 your config file. Setting it to 0 completely disables the
175 your config file. Setting it to 0 completely disables the
176 caching system, and the minimum value accepted is 20 (if you
176 caching system, and the minimum value accepted is 20 (if you
177 provide a value less than 20, it is reset to 0 and a warning is
177 provide a value less than 20, it is reset to 0 and a warning is
178 issued). This limit is defined because otherwise you’ll spend
178 issued). This limit is defined because otherwise you’ll spend
179 more time re-flushing a too small cache than working.
179 more time re-flushing a too small cache than working.
180
180
181 -classic|cl
181 -classic|cl
182 Gives IPython a similar feel to the classic Python prompt.
182 Gives IPython a similar feel to the classic Python prompt.
183
183
184 -colors <scheme>
184 -colors <scheme>
185 Color scheme for prompts and exception reporting. Currently
185 Color scheme for prompts and exception reporting. Currently
186 implemented: NoColor, Linux, and LightBG.
186 implemented: NoColor, Linux, and LightBG.
187
187
188 -[no]color_info
188 -[no]color_info
189 IPython can display information about objects via a set of func-
189 IPython can display information about objects via a set of func-
190 tions, and optionally can use colors for this, syntax highlight-
190 tions, and optionally can use colors for this, syntax highlight-
191 ing source code and various other elements. However, because
191 ing source code and various other elements. However, because
192 this information is passed through a pager (like ’less’) and
192 this information is passed through a pager (like ’less’) and
193 many pagers get confused with color codes, this option is off by
193 many pagers get confused with color codes, this option is off by
194 default. You can test it and turn it on permanently in your
194 default. You can test it and turn it on permanently in your
195 ipythonrc file if it works for you. As a reference, the ’less’
195 ipythonrc file if it works for you. As a reference, the ’less’
196 pager supplied with Mandrake 8.2 works ok, but that in RedHat
196 pager supplied with Mandrake 8.2 works ok, but that in RedHat
197 7.2 doesn’t.
197 7.2 doesn’t.
198
198
199 Test it and turn it on permanently if it works with your system.
199 Test it and turn it on permanently if it works with your system.
200 The magic function @color_info allows you to toggle this inter-
200 The magic function @color_info allows you to toggle this inter-
201 actively for testing.
201 actively for testing.
202
202
203 -[no]confirm_exit
203 -[no]confirm_exit
204 Set to confirm when you try to exit IPython with an EOF (Con-
204 Set to confirm when you try to exit IPython with an EOF (Con-
205 trol-D in Unix, Control-Z/Enter in Windows). Note that using the
205 trol-D in Unix, Control-Z/Enter in Windows). Note that using the
206 magic functions @Exit or @Quit you can force a direct exit,
206 magic functions @Exit or @Quit you can force a direct exit,
207 bypassing any confirmation.
207 bypassing any confirmation.
208
208
209 -[no]debug
209 -[no]debug
210 Show information about the loading process. Very useful to pin
210 Show information about the loading process. Very useful to pin
211 down problems with your configuration files or to get details
211 down problems with your configuration files or to get details
212 about session restores.
212 about session restores.
213
213
214 -[no]deep_reload
214 -[no]deep_reload
215 IPython can use the deep_reload module which reloads changes in
215 IPython can use the deep_reload module which reloads changes in
216 modules recursively (it replaces the reload() function, so you
216 modules recursively (it replaces the reload() function, so you
217 don’t need to change anything to use it). deep_reload() forces a
217 don’t need to change anything to use it). deep_reload() forces a
218 full reload of modules whose code may have changed, which the
218 full reload of modules whose code may have changed, which the
219 default reload() function does not.
219 default reload() function does not.
220
220
221 When deep_reload is off, IPython will use the normal reload(),
221 When deep_reload is off, IPython will use the normal reload(),
222 but deep_reload will still be available as dreload(). This fea-
222 but deep_reload will still be available as dreload(). This fea-
223 ture is off by default [which means that you have both normal
223 ture is off by default [which means that you have both normal
224 reload() and dreload()].
224 reload() and dreload()].
225
225
226 -editor <name>
226 -editor <name>
227 Which editor to use with the @edit command. By default, IPython
227 Which editor to use with the @edit command. By default, IPython
228 will honor your EDITOR environment variable (if not set, vi is
228 will honor your EDITOR environment variable (if not set, vi is
229 the Unix default and notepad the Windows one). Since this editor
229 the Unix default and notepad the Windows one). Since this editor
230 is invoked on the fly by IPython and is meant for editing small
230 is invoked on the fly by IPython and is meant for editing small
231 code snippets, you may want to use a small, lightweight editor
231 code snippets, you may want to use a small, lightweight editor
232 here (in case your default EDITOR is something like Emacs).
232 here (in case your default EDITOR is something like Emacs).
233
233
234 -ipythondir <name>
234 -ipythondir <name>
235 The name of your IPython configuration directory IPYTHONDIR.
235 The name of your IPython configuration directory IPYTHONDIR.
236 This can also be specified through the environment variable
236 This can also be specified through the environment variable
237 IPYTHONDIR.
237 IPYTHONDIR.
238
238
239 -log|l Generate a log file of all input. The file is named ipython.log
239 -log|l Generate a log file of all input. The file is named
240 in your current directory (which prevents logs from multiple
240 ipython_log.py in your current directory (which prevents logs
241 IPython sessions from trampling each other). You can use this to
241 from multiple IPython sessions from trampling each other). You
242 later restore a session by loading your logfile as a file to be
242 can use this to later restore a session by loading your logfile
243 executed with option -logplay (see below).
243 as a file to be executed with option -logplay (see below).
244
244
245 -logfile|lf
245 -logfile|lf
246 Specifu the name of your logfile.
246 Specify the name of your logfile.
247
247
248 -logplay|lp
248 -logplay|lp
249 Replay a previous log. For restoring a session as close as pos-
249 Replay a previous log. For restoring a session as close as pos-
250 sible to the state you left it in, use this option (don’t just
250 sible to the state you left it in, use this option (don’t just
251 run the logfile). With -logplay, IPython will try to reconstruct
251 run the logfile). With -logplay, IPython will try to reconstruct
252 the previous working environment in full, not just execute the
252 the previous working environment in full, not just execute the
253 commands in the logfile.
253 commands in the logfile.
254 When a session is restored, logging is automatically turned on
254 When a session is restored, logging is automatically turned on
255 again with the name of the logfile it was invoked with (it is
255 again with the name of the logfile it was invoked with (it is
256 read from the log header). So once you’ve turned logging on for
256 read from the log header). So once you’ve turned logging on for
257 a session, you can quit IPython and reload it as many times as
257 a session, you can quit IPython and reload it as many times as
258 you want and it will continue to log its history and restore
258 you want and it will continue to log its history and restore
259 from the beginning every time.
259 from the beginning every time.
260
260
261 Caveats: there are limitations in this option. The history vari-
261 Caveats: there are limitations in this option. The history vari-
262 ables _i*,_* and _dh don’t get restored properly. In the future
262 ables _i*,_* and _dh don’t get restored properly. In the future
263 we will try to implement full session saving by writing and
263 we will try to implement full session saving by writing and
264 retrieving a failed because of inherent limitations of Python’s
264 retrieving a failed because of inherent limitations of Python’s
265 Pickle module, so this may have to wait.
265 Pickle module, so this may have to wait.
266
266
267 -[no]messages
267 -[no]messages
268 Print messages which IPython collects about its startup process
268 Print messages which IPython collects about its startup process
269 (default on).
269 (default on).
270
270
271 -[no]pdb
271 -[no]pdb
272 Automatically call the pdb debugger after every uncaught excep-
272 Automatically call the pdb debugger after every uncaught excep-
273 tion. If you are used to debugging using pdb, this puts you
273 tion. If you are used to debugging using pdb, this puts you
274 automatically inside of it after any call (either in IPython or
274 automatically inside of it after any call (either in IPython or
275 in code called by it) which triggers an exception which goes
275 in code called by it) which triggers an exception which goes
276 uncaught.
276 uncaught.
277
277
278 -[no]pprint
278 -[no]pprint
279 IPython can optionally use the pprint (pretty printer) module
279 IPython can optionally use the pprint (pretty printer) module
280 for displaying results. pprint tends to give a nicer display of
280 for displaying results. pprint tends to give a nicer display of
281 nested data structures. If you like it, you can turn it on per-
281 nested data structures. If you like it, you can turn it on per-
282 manently in your config file (default off).
282 manently in your config file (default off).
283
283
284 -profile|p <name>
284 -profile|p <name>
285 Assume that your config file is ipythonrc-<name> (looks in cur-
285 Assume that your config file is ipythonrc-<name> (looks in cur-
286 rent dir first, then in IPYTHONDIR). This is a quick way to keep
286 rent dir first, then in IPYTHONDIR). This is a quick way to keep
287 and load multiple config files for different tasks, especially
287 and load multiple config files for different tasks, especially
288 if you use the include option of config files. You can keep a
288 if you use the include option of config files. You can keep a
289 basic IPYTHONDIR/ipythonrc file and then have other ’profiles’
289 basic IPYTHONDIR/ipythonrc file and then have other ’profiles’
290 which include this one and load extra things for particular
290 which include this one and load extra things for particular
291 tasks. For example:
291 tasks. For example:
292
292
293 1) $HOME/.ipython/ipythonrc : load basic things you always want.
293 1) $HOME/.ipython/ipythonrc : load basic things you always want.
294 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-
294 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-
295 related modules.
295 related modules.
296 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
296 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
297 plotting modules.
297 plotting modules.
298
298
299 Since it is possible to create an endless loop by having circu-
299 Since it is possible to create an endless loop by having circu-
300 lar file inclusions, IPython will stop if it reaches 15 recur-
300 lar file inclusions, IPython will stop if it reaches 15 recur-
301 sive inclusions.
301 sive inclusions.
302
302
303 -prompt_in1|pi1 <string>
303 -prompt_in1|pi1 <string>
304 Specify the string used for input prompts. Note that if you are
304 Specify the string used for input prompts. Note that if you are
305 using numbered prompts, the number is represented with a ’\#’ in
305 using numbered prompts, the number is represented with a ’\#’ in
306 the string. Don’t forget to quote strings with spaces embedded
306 the string. Don’t forget to quote strings with spaces embedded
307 in them. Default: ’In [\#]:’.
307 in them. Default: ’In [\#]:’.
308
308
309 Most bash-like escapes can be used to customize IPython’s
309 Most bash-like escapes can be used to customize IPython’s
310 prompts, as well as a few additional ones which are IPython-spe-
310 prompts, as well as a few additional ones which are IPython-spe-
311 cific. All valid prompt escapes are described in detail in the
311 cific. All valid prompt escapes are described in detail in the
312 Customization section of the IPython HTML/PDF manual.
312 Customization section of the IPython HTML/PDF manual.
313
313
314 -prompt_in2|pi2 <string>
314 -prompt_in2|pi2 <string>
315 Similar to the previous option, but used for the continuation
315 Similar to the previous option, but used for the continuation
316 prompts. The special sequence ’\D’ is similar to ’\#’, but with
316 prompts. The special sequence ’\D’ is similar to ’\#’, but with
317 all digits replaced dots (so you can have your continuation
317 all digits replaced dots (so you can have your continuation
318 prompt aligned with your input prompt). Default: ’ .\D.:’
318 prompt aligned with your input prompt). Default: ’ .\D.:’
319 (note three spaces at the start for alignment with ’In [\#]’).
319 (note three spaces at the start for alignment with ’In [\#]’).
320
320
321 -prompt_out|po <string>
321 -prompt_out|po <string>
322 String used for output prompts, also uses numbers like
322 String used for output prompts, also uses numbers like
323 prompt_in1. Default: ’Out[\#]:’.
323 prompt_in1. Default: ’Out[\#]:’.
324
324
325 -quick Start in bare bones mode (no config file loaded).
325 -quick Start in bare bones mode (no config file loaded).
326
326
327 -rcfile <name>
327 -rcfile <name>
328 Name of your IPython resource configuration file. normally
328 Name of your IPython resource configuration file. normally
329 IPython loads ipythonrc (from current directory) or
329 IPython loads ipythonrc (from current directory) or
330 IPYTHONDIR/ipythonrc. If the loading of your config file fails,
330 IPYTHONDIR/ipythonrc. If the loading of your config file fails,
331 IPython starts with a bare bones configuration (no modules
331 IPython starts with a bare bones configuration (no modules
332 loaded at all).
332 loaded at all).
333
333
334 -[no]readline
334 -[no]readline
335 Use the readline library, which is needed to support name com-
335 Use the readline library, which is needed to support name com-
336 pletion and command history, among other things. It is enabled
336 pletion and command history, among other things. It is enabled
337 by default, but may cause problems for users of X/Emacs in
337 by default, but may cause problems for users of X/Emacs in
338 Python comint or shell buffers.
338 Python comint or shell buffers.
339
339
340 Note that emacs ’eterm’ buffers (opened with M-x term) support
340 Note that emacs ’eterm’ buffers (opened with M-x term) support
341 IPython’s readline and syntax coloring fine, only ’emacs’ (M-x
341 IPython’s readline and syntax coloring fine, only ’emacs’ (M-x
342 shell and C-c !) buffers do not.
342 shell and C-c !) buffers do not.
343
343
344 -screen_length|sl <n>
344 -screen_length|sl <n>
345 Number of lines of your screen. This is used to control print-
345 Number of lines of your screen. This is used to control print-
346 ing of very long strings. Strings longer than this number of
346 ing of very long strings. Strings longer than this number of
347 lines will be sent through a pager instead of directly printed.
347 lines will be sent through a pager instead of directly printed.
348
348
349 The default value for this is 0, which means IPython will auto-
349 The default value for this is 0, which means IPython will auto-
350 detect your screen size every time it needs to print certain
350 detect your screen size every time it needs to print certain
351 potentially long strings (this doesn’t change the behavior of
351 potentially long strings (this doesn’t change the behavior of
352 the ’print’ keyword, it’s only triggered internally). If for
352 the ’print’ keyword, it’s only triggered internally). If for
353 some reason this isn’t working well (it needs curses support),
353 some reason this isn’t working well (it needs curses support),
354 specify it yourself. Otherwise don’t change the default.
354 specify it yourself. Otherwise don’t change the default.
355
355
356 -separate_in|si <string>
356 -separate_in|si <string>
357 Separator before input prompts. Default ’0.
357 Separator before input prompts. Default ’0.
358
358
359 -separate_out|so <string>
359 -separate_out|so <string>
360 Separator before output prompts. Default: 0 (nothing).
360 Separator before output prompts. Default: 0 (nothing).
361
361
362 -separate_out2|so2 <string>
362 -separate_out2|so2 <string>
363 Separator after output prompts. Default: 0 (nothing).
363 Separator after output prompts. Default: 0 (nothing).
364
364
365 -nosep Shorthand for ’-separate_in 0 -separate_out 0 -separate_out2 0’.
365 -nosep Shorthand for ’-separate_in 0 -separate_out 0 -separate_out2 0’.
366 Simply removes all input/output separators.
366 Simply removes all input/output separators.
367
367
368 -upgrade
368 -upgrade
369 Allows you to upgrade your IPYTHONDIR configuration when you
369 Allows you to upgrade your IPYTHONDIR configuration when you
370 install a new version of IPython. Since new versions may
370 install a new version of IPython. Since new versions may
371 include new command lines options or example files, this copies
371 include new command lines options or example files, this copies
372 updated ipythonrc-type files. However, it backs up (with a .old
372 updated ipythonrc-type files. However, it backs up (with a .old
373 extension) all files which it overwrites so that you can merge
373 extension) all files which it overwrites so that you can merge
374 back any custimizations you might have in your personal files.
374 back any custimizations you might have in your personal files.
375
375
376 -Version
376 -Version
377 Print version information and exit.
377 Print version information and exit.
378
378
379 -xmode <modename>
379 -xmode <modename>
380 Mode for exception reporting. The valid modes are Plain, Con-
380 Mode for exception reporting. The valid modes are Plain, Con-
381 text, and Verbose.
381 text, and Verbose.
382
382
383 - Plain: similar to python’s normal traceback printing.
383 - Plain: similar to python’s normal traceback printing.
384
384
385 - Context: prints 5 lines of context source code around each
385 - Context: prints 5 lines of context source code around each
386 line in the traceback.
386 line in the traceback.
387
387
388 - Verbose: similar to Context, but additionally prints the vari-
388 - Verbose: similar to Context, but additionally prints the vari-
389 ables currently visible where the exception happened (shortening
389 ables currently visible where the exception happened (shortening
390 their strings if too long). This can potentially be very slow,
390 their strings if too long). This can potentially be very slow,
391 if you happen to have a huge data structure whose string repre-
391 if you happen to have a huge data structure whose string repre-
392 sentation is complex to compute. Your computer may appear to
392 sentation is complex to compute. Your computer may appear to
393 freeze for a while with cpu usage at 100%. If this occurs, you
393 freeze for a while with cpu usage at 100%. If this occurs, you
394 can cancel the traceback with Ctrl-C (maybe hitting it more than
394 can cancel the traceback with Ctrl-C (maybe hitting it more than
395 once).
395 once).
396
396
397
397
398 EMBEDDING
398 EMBEDDING
399 It is possible to start an IPython instance inside your own Python pro-
399 It is possible to start an IPython instance inside your own Python pro-
400 grams. In the documentation example files there are some illustrations
400 grams. In the documentation example files there are some illustrations
401 on how to do this.
401 on how to do this.
402
402
403 This feature allows you to evalutate dynamically the state of your
403 This feature allows you to evalutate dynamically the state of your
404 code, operate with your variables, analyze them, etc. Note however
404 code, operate with your variables, analyze them, etc. Note however
405 that any changes you make to values while in the shell do NOT propagate
405 that any changes you make to values while in the shell do NOT propagate
406 back to the running code, so it is safe to modify your values because
406 back to the running code, so it is safe to modify your values because
407 you won’t break your code in bizarre ways by doing so.
407 you won’t break your code in bizarre ways by doing so.
408 """
408 """
409
409
410 cmd_line_usage = __doc__
410 cmd_line_usage = __doc__
411
411
412 #---------------------------------------------------------------------------
412 #---------------------------------------------------------------------------
413 interactive_usage = """
413 interactive_usage = """
414 IPython -- An enhanced Interactive Python
414 IPython -- An enhanced Interactive Python
415 =========================================
415 =========================================
416
416
417 IPython offers a combination of convenient shell features, special commands
417 IPython offers a combination of convenient shell features, special commands
418 and a history mechanism for both input (command history) and output (results
418 and a history mechanism for both input (command history) and output (results
419 caching, similar to Mathematica). It is intended to be a fully compatible
419 caching, similar to Mathematica). It is intended to be a fully compatible
420 replacement for the standard Python interpreter, while offering vastly
420 replacement for the standard Python interpreter, while offering vastly
421 improved functionality and flexibility.
421 improved functionality and flexibility.
422
422
423 At your system command line, type 'ipython -help' to see the command line
423 At your system command line, type 'ipython -help' to see the command line
424 options available. This document only describes interactive features.
424 options available. This document only describes interactive features.
425
425
426 Warning: IPython relies on the existence of a global variable called __IP which
426 Warning: IPython relies on the existence of a global variable called __IP which
427 controls the shell itself. If you redefine __IP to anything, bizarre behavior
427 controls the shell itself. If you redefine __IP to anything, bizarre behavior
428 will quickly occur.
428 will quickly occur.
429
429
430 MAIN FEATURES
430 MAIN FEATURES
431
431
432 * Access to the standard Python help. As of Python 2.1, a help system is
432 * Access to the standard Python help. As of Python 2.1, a help system is
433 available with access to object docstrings and the Python manuals. Simply
433 available with access to object docstrings and the Python manuals. Simply
434 type 'help' (no quotes) to access it.
434 type 'help' (no quotes) to access it.
435
435
436 * Magic commands: type %magic for information on the magic subsystem.
436 * Magic commands: type %magic for information on the magic subsystem.
437
437
438 * System command aliases, via the %alias command or the ipythonrc config file.
438 * System command aliases, via the %alias command or the ipythonrc config file.
439
439
440 * Dynamic object information:
440 * Dynamic object information:
441
441
442 Typing ?word or word? prints detailed information about an object. If
442 Typing ?word or word? prints detailed information about an object. If
443 certain strings in the object are too long (docstrings, code, etc.) they get
443 certain strings in the object are too long (docstrings, code, etc.) they get
444 snipped in the center for brevity.
444 snipped in the center for brevity.
445
445
446 Typing ??word or word?? gives access to the full information without
446 Typing ??word or word?? gives access to the full information without
447 snipping long strings. Long strings are sent to the screen through the less
447 snipping long strings. Long strings are sent to the screen through the less
448 pager if longer than the screen, printed otherwise.
448 pager if longer than the screen, printed otherwise.
449
449
450 The ?/?? system gives access to the full source code for any object (if
450 The ?/?? system gives access to the full source code for any object (if
451 available), shows function prototypes and other useful information.
451 available), shows function prototypes and other useful information.
452
452
453 If you just want to see an object's docstring, type '%pdoc object' (without
453 If you just want to see an object's docstring, type '%pdoc object' (without
454 quotes, and without % if you have automagic on).
454 quotes, and without % if you have automagic on).
455
455
456 Both %pdoc and ?/?? give you access to documentation even on things which are
456 Both %pdoc and ?/?? give you access to documentation even on things which are
457 not explicitely defined. Try for example typing {}.get? or after import os,
457 not explicitely defined. Try for example typing {}.get? or after import os,
458 type os.path.abspath??. The magic functions %pdef, %source and %file operate
458 type os.path.abspath??. The magic functions %pdef, %source and %file operate
459 similarly.
459 similarly.
460
460
461 * Completion in the local namespace, by typing TAB at the prompt.
461 * Completion in the local namespace, by typing TAB at the prompt.
462
462
463 At any time, hitting tab will complete any available python commands or
463 At any time, hitting tab will complete any available python commands or
464 variable names, and show you a list of the possible completions if there's
464 variable names, and show you a list of the possible completions if there's
465 no unambiguous one. It will also complete filenames in the current directory.
465 no unambiguous one. It will also complete filenames in the current directory.
466
466
467 This feature requires the readline and rlcomplete modules, so it won't work
467 This feature requires the readline and rlcomplete modules, so it won't work
468 if your Python lacks readline support (such as under Windows).
468 if your Python lacks readline support (such as under Windows).
469
469
470 * Search previous command history in two ways (also requires readline):
470 * Search previous command history in two ways (also requires readline):
471
471
472 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
472 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
473 search through only the history items that match what you've typed so
473 search through only the history items that match what you've typed so
474 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
474 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
475 normal arrow keys.
475 normal arrow keys.
476
476
477 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
477 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
478 your history for lines that match what you've typed so far, completing as
478 your history for lines that match what you've typed so far, completing as
479 much as it can.
479 much as it can.
480
480
481 * Persistent command history across sessions (readline required).
481 * Persistent command history across sessions (readline required).
482
482
483 * Logging of input with the ability to save and restore a working session.
483 * Logging of input with the ability to save and restore a working session.
484
484
485 * System escape with !. Typing !ls will run 'ls' in the current directory.
485 * System escape with !. Typing !ls will run 'ls' in the current directory.
486
486
487 * The reload command does a 'deep' reload of a module: changes made to the
487 * The reload command does a 'deep' reload of a module: changes made to the
488 module since you imported will actually be available without having to exit.
488 module since you imported will actually be available without having to exit.
489
489
490 * Verbose and colored exception traceback printouts. See the magic xmode and
490 * Verbose and colored exception traceback printouts. See the magic xmode and
491 xcolor functions for details (just type %magic).
491 xcolor functions for details (just type %magic).
492
492
493 * Input caching system:
493 * Input caching system:
494
494
495 IPython offers numbered prompts (In/Out) with input and output caching. All
495 IPython offers numbered prompts (In/Out) with input and output caching. All
496 input is saved and can be retrieved as variables (besides the usual arrow
496 input is saved and can be retrieved as variables (besides the usual arrow
497 key recall).
497 key recall).
498
498
499 The following GLOBAL variables always exist (so don't overwrite them!):
499 The following GLOBAL variables always exist (so don't overwrite them!):
500 _i: stores previous input.
500 _i: stores previous input.
501 _ii: next previous.
501 _ii: next previous.
502 _iii: next-next previous.
502 _iii: next-next previous.
503 _ih : a list of all input _ih[n] is the input from line n.
503 _ih : a list of all input _ih[n] is the input from line n.
504
504
505 Additionally, global variables named _i<n> are dynamically created (<n>
505 Additionally, global variables named _i<n> are dynamically created (<n>
506 being the prompt counter), such that _i<n> == _ih[<n>]
506 being the prompt counter), such that _i<n> == _ih[<n>]
507
507
508 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
508 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
509
509
510 You can create macros which contain multiple input lines from this history,
510 You can create macros which contain multiple input lines from this history,
511 for later re-execution, with the %macro function.
511 for later re-execution, with the %macro function.
512
512
513 The history function %hist allows you to see any part of your input history
513 The history function %hist allows you to see any part of your input history
514 by printing a range of the _i variables. Note that inputs which contain
514 by printing a range of the _i variables. Note that inputs which contain
515 magic functions (%) appear in the history with a prepended comment. This is
515 magic functions (%) appear in the history with a prepended comment. This is
516 because they aren't really valid Python code, so you can't exec them.
516 because they aren't really valid Python code, so you can't exec them.
517
517
518 * Output caching system:
518 * Output caching system:
519
519
520 For output that is returned from actions, a system similar to the input
520 For output that is returned from actions, a system similar to the input
521 cache exists but using _ instead of _i. Only actions that produce a result
521 cache exists but using _ instead of _i. Only actions that produce a result
522 (NOT assignments, for example) are cached. If you are familiar with
522 (NOT assignments, for example) are cached. If you are familiar with
523 Mathematica, IPython's _ variables behave exactly like Mathematica's %
523 Mathematica, IPython's _ variables behave exactly like Mathematica's %
524 variables.
524 variables.
525
525
526 The following GLOBAL variables always exist (so don't overwrite them!):
526 The following GLOBAL variables always exist (so don't overwrite them!):
527 _ (one underscore): previous output.
527 _ (one underscore): previous output.
528 __ (two underscores): next previous.
528 __ (two underscores): next previous.
529 ___ (three underscores): next-next previous.
529 ___ (three underscores): next-next previous.
530
530
531 Global variables named _<n> are dynamically created (<n> being the prompt
531 Global variables named _<n> are dynamically created (<n> being the prompt
532 counter), such that the result of output <n> is always available as _<n>.
532 counter), such that the result of output <n> is always available as _<n>.
533
533
534 Finally, a global dictionary named _oh exists with entries for all lines
534 Finally, a global dictionary named _oh exists with entries for all lines
535 which generated output.
535 which generated output.
536
536
537 * Directory history:
537 * Directory history:
538
538
539 Your history of visited directories is kept in the global list _dh, and the
539 Your history of visited directories is kept in the global list _dh, and the
540 magic %cd command can be used to go to any entry in that list.
540 magic %cd command can be used to go to any entry in that list.
541
541
542 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
542 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
543
543
544 1. Auto-parentheses
544 1. Auto-parentheses
545 Callable objects (i.e. functions, methods, etc) can be invoked like
545 Callable objects (i.e. functions, methods, etc) can be invoked like
546 this (notice the commas between the arguments):
546 this (notice the commas between the arguments):
547 >>> callable_ob arg1, arg2, arg3
547 >>> callable_ob arg1, arg2, arg3
548 and the input will be translated to this:
548 and the input will be translated to this:
549 --> callable_ob(arg1, arg2, arg3)
549 --> callable_ob(arg1, arg2, arg3)
550 You can force auto-parentheses by using '/' as the first character
550 You can force auto-parentheses by using '/' as the first character
551 of a line. For example:
551 of a line. For example:
552 >>> /globals # becomes 'globals()'
552 >>> /globals # becomes 'globals()'
553 Note that the '/' MUST be the first character on the line! This
553 Note that the '/' MUST be the first character on the line! This
554 won't work:
554 won't work:
555 >>> print /globals # syntax error
555 >>> print /globals # syntax error
556
556
557 In most cases the automatic algorithm should work, so you should
557 In most cases the automatic algorithm should work, so you should
558 rarely need to explicitly invoke /. One notable exception is if you
558 rarely need to explicitly invoke /. One notable exception is if you
559 are trying to call a function with a list of tuples as arguments (the
559 are trying to call a function with a list of tuples as arguments (the
560 parenthesis will confuse IPython):
560 parenthesis will confuse IPython):
561 In [1]: zip (1,2,3),(4,5,6) # won't work
561 In [1]: zip (1,2,3),(4,5,6) # won't work
562 but this will work:
562 but this will work:
563 In [2]: /zip (1,2,3),(4,5,6)
563 In [2]: /zip (1,2,3),(4,5,6)
564 ------> zip ((1,2,3),(4,5,6))
564 ------> zip ((1,2,3),(4,5,6))
565 Out[2]= [(1, 4), (2, 5), (3, 6)]
565 Out[2]= [(1, 4), (2, 5), (3, 6)]
566
566
567 IPython tells you that it has altered your command line by
567 IPython tells you that it has altered your command line by
568 displaying the new command line preceded by -->. e.g.:
568 displaying the new command line preceded by -->. e.g.:
569 In [18]: callable list
569 In [18]: callable list
570 -------> callable (list)
570 -------> callable (list)
571
571
572 2. Auto-Quoting
572 2. Auto-Quoting
573 You can force auto-quoting of a function's arguments by using ',' as
573 You can force auto-quoting of a function's arguments by using ',' as
574 the first character of a line. For example:
574 the first character of a line. For example:
575 >>> ,my_function /home/me # becomes my_function("/home/me")
575 >>> ,my_function /home/me # becomes my_function("/home/me")
576
576
577 If you use ';' instead, the whole argument is quoted as a single
577 If you use ';' instead, the whole argument is quoted as a single
578 string (while ',' splits on whitespace):
578 string (while ',' splits on whitespace):
579 >>> ,my_function a b c # becomes my_function("a","b","c")
579 >>> ,my_function a b c # becomes my_function("a","b","c")
580 >>> ;my_function a b c # becomes my_function("a b c")
580 >>> ;my_function a b c # becomes my_function("a b c")
581
581
582 Note that the ',' MUST be the first character on the line! This
582 Note that the ',' MUST be the first character on the line! This
583 won't work:
583 won't work:
584 >>> x = ,my_function /home/me # syntax error
584 >>> x = ,my_function /home/me # syntax error
585 """
585 """
1 NO CONTENT: modified file
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 .\" Hey, EMACS: -*- nroff -*-
1 .\" Hey, EMACS: -*- nroff -*-
2 .\" First parameter, NAME, should be all caps
2 .\" First parameter, NAME, should be all caps
3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
4 .\" other parameters are allowed: see man(7), man(1)
4 .\" other parameters are allowed: see man(7), man(1)
5 .TH IPYTHON 1 "November 30, 2004"
5 .TH IPYTHON 1 "November 30, 2004"
6 .\" Please adjust this date whenever revising the manpage.
6 .\" Please adjust this date whenever revising the manpage.
7 .\"
7 .\"
8 .\" Some roff macros, for reference:
8 .\" Some roff macros, for reference:
9 .\" .nh disable hyphenation
9 .\" .nh disable hyphenation
10 .\" .hy enable hyphenation
10 .\" .hy enable hyphenation
11 .\" .ad l left justify
11 .\" .ad l left justify
12 .\" .ad b justify to both left and right margins
12 .\" .ad b justify to both left and right margins
13 .\" .nf disable filling
13 .\" .nf disable filling
14 .\" .fi enable filling
14 .\" .fi enable filling
15 .\" .br insert line break
15 .\" .br insert line break
16 .\" .sp <n> insert n+1 empty lines
16 .\" .sp <n> insert n+1 empty lines
17 .\" for manpage-specific macros, see man(7) and groff_man(7)
17 .\" for manpage-specific macros, see man(7) and groff_man(7)
18 .\" .SH section heading
18 .\" .SH section heading
19 .\" .SS secondary section heading
19 .\" .SS secondary section heading
20 .\"
20 .\"
21 .\"
21 .\"
22 .\" To preview this page as plain text: nroff -man ipython.1
22 .\" To preview this page as plain text: nroff -man ipython.1
23 .\"
23 .\"
24 .SH NAME
24 .SH NAME
25 ipython \- An Enhanced Interactive Python
25 ipython \- An Enhanced Interactive Python
26 .SH SYNOPSIS
26 .SH SYNOPSIS
27 .B ipython
27 .B ipython
28 .RI [ options ] " files" ...
28 .RI [ options ] " files" ...
29 .SH DESCRIPTION
29 .SH DESCRIPTION
30 An interactive Python shell with automatic history (input and output),
30 An interactive Python shell with automatic history (input and output),
31 dynamic object introspection, easier configuration, command
31 dynamic object introspection, easier configuration, command
32 completion, access to the system shell, integration with numerical and
32 completion, access to the system shell, integration with numerical and
33 scientific computing tools, and more.
33 scientific computing tools, and more.
34 .SH SPECIAL THREADING OPTIONS
34 .SH SPECIAL THREADING OPTIONS
35 The following special options are ONLY valid at the beginning of the command
35 The following special options are ONLY valid at the beginning of the command
36 line, and not later. This is because they control the initialization of
36 line, and not later. This is because they control the initialization of
37 ipython itself, before the normal option-handling mechanism is active.
37 ipython itself, before the normal option-handling mechanism is active.
38 .TP
38 .TP
39 .B \-gthread, \-qthread, \-wthread, \-pylab
39 .B \-gthread, \-qthread, \-wthread, \-pylab
40 Only ONE of these can be given, and it can only be given as the first option
40 Only ONE of these can be given, and it can only be given as the first option
41 passed to IPython (it will have no effect in any other position). They
41 passed to IPython (it will have no effect in any other position). They
42 provide threading support for the GTK, QT and WXWidgets toolkits, and for the
42 provide threading support for the GTK, QT and WXWidgets toolkits, and for the
43 matplotlib library.
43 matplotlib library.
44 .br
44 .br
45 .sp 1
45 .sp 1
46 With any of the first three options, IPython starts running a separate thread
46 With any of the first three options, IPython starts running a separate thread
47 for the graphical toolkit's operation, so that you can open and control
47 for the graphical toolkit's operation, so that you can open and control
48 graphical elements from within an IPython command line, without blocking. All
48 graphical elements from within an IPython command line, without blocking. All
49 three provide essentially the same functionality, respectively for GTK, QT and
49 three provide essentially the same functionality, respectively for GTK, QT and
50 WXWidgets (via their Python interfaces).
50 WXWidgets (via their Python interfaces).
51 .br
51 .br
52 .sp 1
52 .sp 1
53 If \-pylab is given, IPython loads special support for the matplotlib library
53 If \-pylab is given, IPython loads special support for the matplotlib library
54 (http://matplotlib.sourceforge.net), allowing interactive usage of any of its
54 (http://matplotlib.sourceforge.net), allowing interactive usage of any of its
55 backends as defined in the user's .matplotlibrc file. It automatically
55 backends as defined in the user's .matplotlibrc file. It automatically
56 activates GTK, QT or WX threading for IPyhton if the choice of matplotlib
56 activates GTK, QT or WX threading for IPyhton if the choice of matplotlib
57 backend requires it. It also modifies the %run command to correctly execute
57 backend requires it. It also modifies the %run command to correctly execute
58 (without blocking) any matplotlib-based script which calls show() at the end.
58 (without blocking) any matplotlib-based script which calls show() at the end.
59 .TP
59 .TP
60 .B \-tk
60 .B \-tk
61 The \-g/q/wthread options, and \-pylab (if matplotlib is configured to use
61 The \-g/q/wthread options, and \-pylab (if matplotlib is configured to use
62 GTK, QT or WX), will normally block Tk graphical interfaces. This means that
62 GTK, QT or WX), will normally block Tk graphical interfaces. This means that
63 when GTK, QT or WX threading is active, any attempt to open a Tk GUI will
63 when GTK, QT or WX threading is active, any attempt to open a Tk GUI will
64 result in a dead window, and possibly cause the Python interpreter to crash.
64 result in a dead window, and possibly cause the Python interpreter to crash.
65 An extra option, \-tk, is available to address this issue. It can ONLY be
65 An extra option, \-tk, is available to address this issue. It can ONLY be
66 given as a SECOND option after any of the above (\-gthread, \-qthread,
66 given as a SECOND option after any of the above (\-gthread, \-qthread,
67 \-wthread or \-pylab).
67 \-wthread or \-pylab).
68 .br
68 .br
69 .sp 1
69 .sp 1
70 If \-tk is given, IPython will try to coordinate Tk threading with GTK, QT or
70 If \-tk is given, IPython will try to coordinate Tk threading with GTK, QT or
71 WX. This is however potentially unreliable, and you will have to test on your
71 WX. This is however potentially unreliable, and you will have to test on your
72 platform and Python configuration to determine whether it works for you.
72 platform and Python configuration to determine whether it works for you.
73 Debian users have reported success, apparently due to the fact that Debian
73 Debian users have reported success, apparently due to the fact that Debian
74 builds all of Tcl, Tk, Tkinter and Python with pthreads support. Under other
74 builds all of Tcl, Tk, Tkinter and Python with pthreads support. Under other
75 Linux environments (such as Fedora Core 2), this option has caused random
75 Linux environments (such as Fedora Core 2), this option has caused random
76 crashes and lockups of the Python interpreter. Under other operating systems
76 crashes and lockups of the Python interpreter. Under other operating systems
77 (Mac OSX and Windows), you'll need to try it to find out, since currently no
77 (Mac OSX and Windows), you'll need to try it to find out, since currently no
78 user reports are available.
78 user reports are available.
79 .br
79 .br
80 .sp 1
80 .sp 1
81 There is unfortunately no way for IPython to determine at runtime whether \-tk
81 There is unfortunately no way for IPython to determine at runtime whether \-tk
82 will work reliably or not, so you will need to do some experiments before
82 will work reliably or not, so you will need to do some experiments before
83 relying on it for regular work.
83 relying on it for regular work.
84 .
84 .
85 .SS A WARNING ABOUT SIGNALS AND THREADS
85 .SS A WARNING ABOUT SIGNALS AND THREADS
86 When any of the thread systems (GTK, QT or WX) are active, either directly or
86 When any of the thread systems (GTK, QT or WX) are active, either directly or
87 via \-pylab with a threaded backend, it is impossible to interrupt
87 via \-pylab with a threaded backend, it is impossible to interrupt
88 long-running Python code via Ctrl\-C. IPython can not pass the
88 long-running Python code via Ctrl\-C. IPython can not pass the
89 KeyboardInterrupt exception (or the underlying SIGINT) across threads, so any
89 KeyboardInterrupt exception (or the underlying SIGINT) across threads, so any
90 long-running process started from IPython will run to completion, or will have
90 long-running process started from IPython will run to completion, or will have
91 to be killed via an external (OS-based) mechanism.
91 to be killed via an external (OS-based) mechanism.
92 .br
92 .br
93 .sp 1
93 .sp 1
94 To the best of my knowledge, this limitation is imposed by the Python
94 To the best of my knowledge, this limitation is imposed by the Python
95 interpreter itself, and it comes from the difficulty of writing portable
95 interpreter itself, and it comes from the difficulty of writing portable
96 signal/threaded code. If any user is an expert on this topic and can suggest
96 signal/threaded code. If any user is an expert on this topic and can suggest
97 a better solution, I would love to hear about it. In the IPython sources,
97 a better solution, I would love to hear about it. In the IPython sources,
98 look at the Shell.py module, and in particular at the runcode() method.
98 look at the Shell.py module, and in particular at the runcode() method.
99 .
99 .
100 .SH REGULAR OPTIONS
100 .SH REGULAR OPTIONS
101 After the above threading options have been given, regular options can follow
101 After the above threading options have been given, regular options can follow
102 in any order. All options can be abbreviated to their shortest non-ambiguous
102 in any order. All options can be abbreviated to their shortest non-ambiguous
103 form and are case-sensitive. One or two dashes can be used. Some options
103 form and are case-sensitive. One or two dashes can be used. Some options
104 have an alternate short form, indicated after a |.
104 have an alternate short form, indicated after a |.
105 .br
105 .br
106 .sp 1
106 .sp 1
107 Most options can also be set from your ipythonrc configuration file.
107 Most options can also be set from your ipythonrc configuration file.
108 See the provided examples for assistance. Options given on the
108 See the provided examples for assistance. Options given on the
109 commandline override the values set in the ipythonrc file.
109 commandline override the values set in the ipythonrc file.
110 .br
110 .br
111 .sp 1
111 .sp 1
112 All options with a [no] prepended can be specified in negated form
112 All options with a [no] prepended can be specified in negated form
113 (\-nooption instead of \-option) to turn the feature off.
113 (\-nooption instead of \-option) to turn the feature off.
114 .TP
114 .TP
115 .B \-h, \-\-help
115 .B \-h, \-\-help
116 Show summary of options.
116 Show summary of options.
117 .TP
117 .TP
118 .B \-[no]autocall
118 .B \-[no]autocall
119 Make IPython automatically call any callable object even if you didn't type
119 Make IPython automatically call any callable object even if you didn't type
120 explicit parentheses. For example, 'str 43' becomes 'str(43)' automatically.
120 explicit parentheses. For example, 'str 43' becomes 'str(43)' automatically.
121 .TP
121 .TP
122 .B \-[no]autoindent
122 .B \-[no]autoindent
123 Turn automatic indentation on/off.
123 Turn automatic indentation on/off.
124 .TP
124 .TP
125 .B \-[no]automagic
125 .B \-[no]automagic
126 Make magic commands automatic (without needing their first character
126 Make magic commands automatic (without needing their first character
127 to be %). Type %magic at the IPython prompt for more information.
127 to be %). Type %magic at the IPython prompt for more information.
128 .TP
128 .TP
129 .B \-[no]autoedit_syntax
129 .B \-[no]autoedit_syntax
130 When a syntax error occurs after editing a file, automatically open the file
130 When a syntax error occurs after editing a file, automatically open the file
131 to the trouble causing line for convenient fixing.
131 to the trouble causing line for convenient fixing.
132 .TP
132 .TP
133 .B \-[no]banner
133 .B \-[no]banner
134 Print the intial information banner (default on).
134 Print the intial information banner (default on).
135 .TP
135 .TP
136 .B \-c <command>
136 .B \-c <command>
137 Execute the given command string, and set sys.argv to ['c']. This is similar
137 Execute the given command string, and set sys.argv to ['c']. This is similar
138 to the \-c option in the normal Python interpreter.
138 to the \-c option in the normal Python interpreter.
139 .TP
139 .TP
140 .B \-cache_size|cs <n>
140 .B \-cache_size|cs <n>
141 Size of the output cache (maximum number of entries to hold in
141 Size of the output cache (maximum number of entries to hold in
142 memory). The default is 1000, you can change it permanently in your
142 memory). The default is 1000, you can change it permanently in your
143 config file. Setting it to 0 completely disables the caching system,
143 config file. Setting it to 0 completely disables the caching system,
144 and the minimum value accepted is 20 (if you provide a value less than
144 and the minimum value accepted is 20 (if you provide a value less than
145 20, it is reset to 0 and a warning is issued). This limit is defined
145 20, it is reset to 0 and a warning is issued). This limit is defined
146 because otherwise you'll spend more time re-flushing a too small cache
146 because otherwise you'll spend more time re-flushing a too small cache
147 than working.
147 than working.
148 .TP
148 .TP
149 .B \-classic|cl
149 .B \-classic|cl
150 Gives IPython a similar feel to the classic Python prompt.
150 Gives IPython a similar feel to the classic Python prompt.
151 .TP
151 .TP
152 .B \-colors <scheme>
152 .B \-colors <scheme>
153 Color scheme for prompts and exception reporting. Currently
153 Color scheme for prompts and exception reporting. Currently
154 implemented: NoColor, Linux, and LightBG.
154 implemented: NoColor, Linux, and LightBG.
155 .TP
155 .TP
156 .B \-[no]color_info
156 .B \-[no]color_info
157 IPython can display information about objects via a set of functions,
157 IPython can display information about objects via a set of functions,
158 and optionally can use colors for this, syntax highlighting source
158 and optionally can use colors for this, syntax highlighting source
159 code and various other elements. However, because this information is
159 code and various other elements. However, because this information is
160 passed through a pager (like 'less') and many pagers get confused with
160 passed through a pager (like 'less') and many pagers get confused with
161 color codes, this option is off by default. You can test it and turn
161 color codes, this option is off by default. You can test it and turn
162 it on permanently in your ipythonrc file if it works for you. As a
162 it on permanently in your ipythonrc file if it works for you. As a
163 reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
163 reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
164 that in RedHat 7.2 doesn't.
164 that in RedHat 7.2 doesn't.
165 .br
165 .br
166 .sp 1
166 .sp 1
167 Test it and turn it on permanently if it works with your system. The
167 Test it and turn it on permanently if it works with your system. The
168 magic function @color_info allows you to toggle this interactively for
168 magic function @color_info allows you to toggle this interactively for
169 testing.
169 testing.
170 .TP
170 .TP
171 .B \-[no]confirm_exit
171 .B \-[no]confirm_exit
172 Set to confirm when you try to exit IPython with an EOF (Control-D in
172 Set to confirm when you try to exit IPython with an EOF (Control-D in
173 Unix, Control-Z/Enter in Windows). Note that using the magic functions
173 Unix, Control-Z/Enter in Windows). Note that using the magic functions
174 @Exit or @Quit you can force a direct exit, bypassing any
174 @Exit or @Quit you can force a direct exit, bypassing any
175 confirmation.
175 confirmation.
176 .TP
176 .TP
177 .B \-[no]debug
177 .B \-[no]debug
178 Show information about the loading process. Very useful to pin down
178 Show information about the loading process. Very useful to pin down
179 problems with your configuration files or to get details about session
179 problems with your configuration files or to get details about session
180 restores.
180 restores.
181 .TP
181 .TP
182 .B \-[no]deep_reload
182 .B \-[no]deep_reload
183 IPython can use the deep_reload module which reloads changes in
183 IPython can use the deep_reload module which reloads changes in
184 modules recursively (it replaces the reload() function, so you don't
184 modules recursively (it replaces the reload() function, so you don't
185 need to change anything to use it). deep_reload() forces a full reload
185 need to change anything to use it). deep_reload() forces a full reload
186 of modules whose code may have changed, which the default reload()
186 of modules whose code may have changed, which the default reload()
187 function does not.
187 function does not.
188 .br
188 .br
189 .sp 1
189 .sp 1
190 When deep_reload is off, IPython will use the normal reload(), but
190 When deep_reload is off, IPython will use the normal reload(), but
191 deep_reload will still be available as dreload(). This feature is off
191 deep_reload will still be available as dreload(). This feature is off
192 by default [which means that you have both normal reload() and
192 by default [which means that you have both normal reload() and
193 dreload()].
193 dreload()].
194 .TP
194 .TP
195 .B \-editor <name>
195 .B \-editor <name>
196 Which editor to use with the @edit command. By default, IPython will
196 Which editor to use with the @edit command. By default, IPython will
197 honor your EDITOR environment variable (if not set, vi is the Unix
197 honor your EDITOR environment variable (if not set, vi is the Unix
198 default and notepad the Windows one). Since this editor is invoked on
198 default and notepad the Windows one). Since this editor is invoked on
199 the fly by IPython and is meant for editing small code snippets, you
199 the fly by IPython and is meant for editing small code snippets, you
200 may want to use a small, lightweight editor here (in case your default
200 may want to use a small, lightweight editor here (in case your default
201 EDITOR is something like Emacs).
201 EDITOR is something like Emacs).
202 .TP
202 .TP
203 .B \-ipythondir <name>
203 .B \-ipythondir <name>
204 The name of your IPython configuration directory IPYTHONDIR. This can
204 The name of your IPython configuration directory IPYTHONDIR. This can
205 also be specified through the environment variable IPYTHONDIR.
205 also be specified through the environment variable IPYTHONDIR.
206 .TP
206 .TP
207 .B \-log|l
207 .B \-log|l
208 Generate a log file of all input. The file is named ipython.log in
208 Generate a log file of all input. The file is named ipython_log.py in your
209 your current directory (which prevents logs from multiple IPython
209 current directory (which prevents logs from multiple IPython sessions from
210 sessions from trampling each other). You can use this to later restore
210 trampling each other). You can use this to later restore a session by loading
211 a session by loading your logfile as a file to be executed with option
211 your logfile as a file to be executed with option -logplay (see below).
212 -logplay (see below).
213 .TP
212 .TP
214 .B \-logfile|lf
213 .B \-logfile|lf
215 Specifu the name of your logfile.
214 Specify the name of your logfile.
216 .TP
215 .TP
217 .B \-logplay|lp
216 .B \-logplay|lp
218 Replay a previous log. For restoring a session as close as possible to
217 Replay a previous log. For restoring a session as close as possible to
219 the state you left it in, use this option (don't just run the
218 the state you left it in, use this option (don't just run the
220 logfile). With \-logplay, IPython will try to reconstruct the previous
219 logfile). With \-logplay, IPython will try to reconstruct the previous
221 working environment in full, not just execute the commands in the
220 working environment in full, not just execute the commands in the
222 logfile.
221 logfile.
223 .br
222 .br
224 .sh 1
223 .sh 1
225 When a session is restored, logging is automatically turned on again
224 When a session is restored, logging is automatically turned on again
226 with the name of the logfile it was invoked with (it is read from the
225 with the name of the logfile it was invoked with (it is read from the
227 log header). So once you've turned logging on for a session, you can
226 log header). So once you've turned logging on for a session, you can
228 quit IPython and reload it as many times as you want and it will
227 quit IPython and reload it as many times as you want and it will
229 continue to log its history and restore from the beginning every time.
228 continue to log its history and restore from the beginning every time.
230 .br
229 .br
231 .sp 1
230 .sp 1
232 Caveats: there are limitations in this option. The history variables
231 Caveats: there are limitations in this option. The history variables
233 _i*,_* and _dh don't get restored properly. In the future we will try
232 _i*,_* and _dh don't get restored properly. In the future we will try
234 to implement full session saving by writing and retrieving a
233 to implement full session saving by writing and retrieving a
235 'snapshot' of the memory state of IPython. But our first attempts
234 'snapshot' of the memory state of IPython. But our first attempts
236 failed because of inherent limitations of Python's Pickle module, so
235 failed because of inherent limitations of Python's Pickle module, so
237 this may have to wait.
236 this may have to wait.
238 .TP
237 .TP
239 .B \-[no]messages
238 .B \-[no]messages
240 Print messages which IPython collects about its startup process
239 Print messages which IPython collects about its startup process
241 (default on).
240 (default on).
242 .TP
241 .TP
243 .B \-[no]pdb
242 .B \-[no]pdb
244 Automatically call the pdb debugger after every uncaught exception. If
243 Automatically call the pdb debugger after every uncaught exception. If
245 you are used to debugging using pdb, this puts you automatically
244 you are used to debugging using pdb, this puts you automatically
246 inside of it after any call (either in IPython or in code called by
245 inside of it after any call (either in IPython or in code called by
247 it) which triggers an exception which goes uncaught.
246 it) which triggers an exception which goes uncaught.
248 .TP
247 .TP
249 .B \-[no]pprint
248 .B \-[no]pprint
250 IPython can optionally use the pprint (pretty printer) module for
249 IPython can optionally use the pprint (pretty printer) module for
251 displaying results. pprint tends to give a nicer display of nested
250 displaying results. pprint tends to give a nicer display of nested
252 data structures. If you like it, you can turn it on permanently in
251 data structures. If you like it, you can turn it on permanently in
253 your config file (default off).
252 your config file (default off).
254 .TP
253 .TP
255 .B \-profile|p <name>
254 .B \-profile|p <name>
256 Assume that your config file is ipythonrc-<name> (looks in current dir
255 Assume that your config file is ipythonrc-<name> (looks in current dir
257 first, then in IPYTHONDIR). This is a quick way to keep and load
256 first, then in IPYTHONDIR). This is a quick way to keep and load
258 multiple config files for different tasks, especially if you use the
257 multiple config files for different tasks, especially if you use the
259 include option of config files. You can keep a basic
258 include option of config files. You can keep a basic
260 IPYTHONDIR/ipythonrc file and then have other 'profiles' which include
259 IPYTHONDIR/ipythonrc file and then have other 'profiles' which include
261 this one and load extra things for particular tasks. For example:
260 this one and load extra things for particular tasks. For example:
262 .br
261 .br
263 .sp 1
262 .sp 1
264 1) $HOME/.ipython/ipythonrc : load basic things you always want.
263 1) $HOME/.ipython/ipythonrc : load basic things you always want.
265 .br
264 .br
266 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-related
265 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-related
267 modules.
266 modules.
268 .br
267 .br
269 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
268 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
270 plotting modules.
269 plotting modules.
271 .br
270 .br
272 .sp 1
271 .sp 1
273 Since it is possible to create an endless loop by having circular file
272 Since it is possible to create an endless loop by having circular file
274 inclusions, IPython will stop if it reaches 15 recursive inclusions.
273 inclusions, IPython will stop if it reaches 15 recursive inclusions.
275 .TP
274 .TP
276 .B \-prompt_in1|pi1 <string>
275 .B \-prompt_in1|pi1 <string>
277 Specify the string used for input prompts. Note that if you are using
276 Specify the string used for input prompts. Note that if you are using
278 numbered prompts, the number is represented with a '\\#' in the
277 numbered prompts, the number is represented with a '\\#' in the
279 string. Don't forget to quote strings with spaces embedded in
278 string. Don't forget to quote strings with spaces embedded in
280 them. Default: 'In [\\#]:'.
279 them. Default: 'In [\\#]:'.
281 .br
280 .br
282 .sp 1
281 .sp 1
283 Most bash-like escapes can be used to customize IPython's prompts, as well as
282 Most bash-like escapes can be used to customize IPython's prompts, as well as
284 a few additional ones which are IPython-specific. All valid prompt escapes
283 a few additional ones which are IPython-specific. All valid prompt escapes
285 are described in detail in the Customization section of the IPython HTML/PDF
284 are described in detail in the Customization section of the IPython HTML/PDF
286 manual.
285 manual.
287 .TP
286 .TP
288 .B \-prompt_in2|pi2 <string>
287 .B \-prompt_in2|pi2 <string>
289 Similar to the previous option, but used for the continuation prompts. The
288 Similar to the previous option, but used for the continuation prompts. The
290 special sequence '\\D' is similar to '\\#', but with all digits replaced dots
289 special sequence '\\D' is similar to '\\#', but with all digits replaced dots
291 (so you can have your continuation prompt aligned with your input
290 (so you can have your continuation prompt aligned with your input
292 prompt). Default: ' .\\D.:' (note three spaces at the start for alignment
291 prompt). Default: ' .\\D.:' (note three spaces at the start for alignment
293 with 'In [\\#]').
292 with 'In [\\#]').
294 .TP
293 .TP
295 .B \-prompt_out|po <string>
294 .B \-prompt_out|po <string>
296 String used for output prompts, also uses numbers like prompt_in1.
295 String used for output prompts, also uses numbers like prompt_in1.
297 Default: 'Out[\\#]:'.
296 Default: 'Out[\\#]:'.
298 .TP
297 .TP
299 .B \-quick
298 .B \-quick
300 Start in bare bones mode (no config file loaded).
299 Start in bare bones mode (no config file loaded).
301 .TP
300 .TP
302 .B \-rcfile <name>
301 .B \-rcfile <name>
303 Name of your IPython resource configuration file. normally IPython
302 Name of your IPython resource configuration file. normally IPython
304 loads ipythonrc (from current directory) or IPYTHONDIR/ipythonrc. If
303 loads ipythonrc (from current directory) or IPYTHONDIR/ipythonrc. If
305 the loading of your config file fails, IPython starts with a bare
304 the loading of your config file fails, IPython starts with a bare
306 bones configuration (no modules loaded at all).
305 bones configuration (no modules loaded at all).
307 .TP
306 .TP
308 .B \-[no]readline
307 .B \-[no]readline
309 Use the readline library, which is needed to support name completion
308 Use the readline library, which is needed to support name completion
310 and command history, among other things. It is enabled by default, but
309 and command history, among other things. It is enabled by default, but
311 may cause problems for users of X/Emacs in Python comint or shell
310 may cause problems for users of X/Emacs in Python comint or shell
312 buffers.
311 buffers.
313 .br
312 .br
314 .sp 1
313 .sp 1
315 Note that emacs 'eterm' buffers (opened with M-x term) support
314 Note that emacs 'eterm' buffers (opened with M-x term) support
316 IPython's readline and syntax coloring fine, only 'emacs' (M-x shell
315 IPython's readline and syntax coloring fine, only 'emacs' (M-x shell
317 and C-c !) buffers do not.
316 and C-c !) buffers do not.
318 .TP
317 .TP
319 .B \-screen_length|sl <n>
318 .B \-screen_length|sl <n>
320 Number of lines of your screen. This is used to control printing of
319 Number of lines of your screen. This is used to control printing of
321 very long strings. Strings longer than this number of lines will be
320 very long strings. Strings longer than this number of lines will be
322 sent through a pager instead of directly printed.
321 sent through a pager instead of directly printed.
323 .br
322 .br
324 .sp 1
323 .sp 1
325 The default value for this is 0, which means IPython will auto-detect
324 The default value for this is 0, which means IPython will auto-detect
326 your screen size every time it needs to print certain potentially long
325 your screen size every time it needs to print certain potentially long
327 strings (this doesn't change the behavior of the 'print' keyword, it's
326 strings (this doesn't change the behavior of the 'print' keyword, it's
328 only triggered internally). If for some reason this isn't working well
327 only triggered internally). If for some reason this isn't working well
329 (it needs curses support), specify it yourself. Otherwise don't change
328 (it needs curses support), specify it yourself. Otherwise don't change
330 the default.
329 the default.
331 .TP
330 .TP
332 .B \-separate_in|si <string>
331 .B \-separate_in|si <string>
333 Separator before input prompts. Default '\n'.
332 Separator before input prompts. Default '\n'.
334 .TP
333 .TP
335 .B \-separate_out|so <string>
334 .B \-separate_out|so <string>
336 Separator before output prompts. Default: 0 (nothing).
335 Separator before output prompts. Default: 0 (nothing).
337 .TP
336 .TP
338 .B \-separate_out2|so2 <string>
337 .B \-separate_out2|so2 <string>
339 Separator after output prompts. Default: 0 (nothing).
338 Separator after output prompts. Default: 0 (nothing).
340 .TP
339 .TP
341 .B \-nosep
340 .B \-nosep
342 Shorthand for '\-separate_in 0 \-separate_out 0 \-separate_out2 0'.
341 Shorthand for '\-separate_in 0 \-separate_out 0 \-separate_out2 0'.
343 Simply removes all input/output separators.
342 Simply removes all input/output separators.
344 .TP
343 .TP
345 .B \-upgrade
344 .B \-upgrade
346 Allows you to upgrade your IPYTHONDIR configuration when you install a
345 Allows you to upgrade your IPYTHONDIR configuration when you install a
347 new version of IPython. Since new versions may include new command
346 new version of IPython. Since new versions may include new command
348 lines options or example files, this copies updated ipythonrc-type
347 lines options or example files, this copies updated ipythonrc-type
349 files. However, it backs up (with a .old extension) all files which
348 files. However, it backs up (with a .old extension) all files which
350 it overwrites so that you can merge back any custimizations you might
349 it overwrites so that you can merge back any custimizations you might
351 have in your personal files.
350 have in your personal files.
352 .TP
351 .TP
353 .B \-Version
352 .B \-Version
354 Print version information and exit.
353 Print version information and exit.
355 .TP
354 .TP
356 .B \-xmode <modename>
355 .B \-xmode <modename>
357 Mode for exception reporting. The valid modes are Plain, Context, and
356 Mode for exception reporting. The valid modes are Plain, Context, and
358 Verbose.
357 Verbose.
359 .br
358 .br
360 .sp 1
359 .sp 1
361 \- Plain: similar to python's normal traceback printing.
360 \- Plain: similar to python's normal traceback printing.
362 .br
361 .br
363 .sp 1
362 .sp 1
364 \- Context: prints 5 lines of context source code around each line in the
363 \- Context: prints 5 lines of context source code around each line in the
365 traceback.
364 traceback.
366 .br
365 .br
367 .sp 1
366 .sp 1
368 \- Verbose: similar to Context, but additionally prints the variables
367 \- Verbose: similar to Context, but additionally prints the variables
369 currently visible where the exception happened (shortening their strings if
368 currently visible where the exception happened (shortening their strings if
370 too long). This can potentially be very slow, if you happen to have a huge
369 too long). This can potentially be very slow, if you happen to have a huge
371 data structure whose string representation is complex to compute. Your
370 data structure whose string representation is complex to compute. Your
372 computer may appear to freeze for a while with cpu usage at 100%. If this
371 computer may appear to freeze for a while with cpu usage at 100%. If this
373 occurs, you can cancel the traceback with Ctrl-C (maybe hitting it more than
372 occurs, you can cancel the traceback with Ctrl-C (maybe hitting it more than
374 once).
373 once).
375 .
374 .
376 .SH EMBEDDING
375 .SH EMBEDDING
377 It is possible to start an IPython instance inside your own Python
376 It is possible to start an IPython instance inside your own Python
378 programs. In the documentation example files there are some
377 programs. In the documentation example files there are some
379 illustrations on how to do this.
378 illustrations on how to do this.
380 .br
379 .br
381 .sp 1
380 .sp 1
382 This feature allows you to evalutate dynamically the state of your
381 This feature allows you to evalutate dynamically the state of your
383 code, operate with your variables, analyze them, etc. Note however
382 code, operate with your variables, analyze them, etc. Note however
384 that any changes you make to values while in the shell do NOT
383 that any changes you make to values while in the shell do NOT
385 propagate back to the running code, so it is safe to modify your
384 propagate back to the running code, so it is safe to modify your
386 values because you won't break your code in bizarre ways by doing so.
385 values because you won't break your code in bizarre ways by doing so.
387 .SH AUTHOR
386 .SH AUTHOR
388 IPython was written by Fernando Perez <fperez@colorado.edu>, based on earlier
387 IPython was written by Fernando Perez <fperez@colorado.edu>, based on earlier
389 code by Janko Hauser <jh@comunit.de> and Nathaniel Gray
388 code by Janko Hauser <jh@comunit.de> and Nathaniel Gray
390 <n8gray@caltech.edu>. This manual page was written by Jack Moffitt
389 <n8gray@caltech.edu>. This manual page was written by Jack Moffitt
391 <jack@xiph.org>, for the Debian project (but may be used by others).
390 <jack@xiph.org>, for the Debian project (but may be used by others).
1 NO CONTENT: modified file
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