##// END OF EJS Templates
Added support for automatically reopening the editor if the file had a...
fperez -
Show More

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

@@ -1,2579 +1,2579 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 958 2005-12-27 23:17:51Z fperez $"""
4 $Id: Magic.py 960 2005-12-28 06:51:01Z 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
51 # Globals to be set later by Magic constructor
52 MAGIC_PREFIX = ''
52 MAGIC_PREFIX = ''
53 MAGIC_ESCAPE = ''
53 MAGIC_ESCAPE = ''
54
54
55 #***************************************************************************
55 #***************************************************************************
56 # Utility functions
56 # Utility functions
57 def magic2python(cmd):
57 def magic2python(cmd):
58 """Convert a command string of magic syntax to valid Python code."""
58 """Convert a command string of magic syntax to valid Python code."""
59
59
60 if cmd.startswith('#'+MAGIC_ESCAPE) or \
60 if cmd.startswith('#'+MAGIC_ESCAPE) or \
61 cmd.startswith(MAGIC_ESCAPE):
61 cmd.startswith(MAGIC_ESCAPE):
62 if cmd[0]=='#':
62 if cmd[0]=='#':
63 cmd = cmd[1:]
63 cmd = cmd[1:]
64 # we need to return the proper line end later
64 # we need to return the proper line end later
65 if cmd[-1] == '\n':
65 if cmd[-1] == '\n':
66 endl = '\n'
66 endl = '\n'
67 else:
67 else:
68 endl = ''
68 endl = ''
69 try:
69 try:
70 func,args = cmd[1:].split(' ',1)
70 func,args = cmd[1:].split(' ',1)
71 except:
71 except:
72 func,args = cmd[1:].rstrip(),''
72 func,args = cmd[1:].rstrip(),''
73 args = args.replace('"','\\"').replace("'","\\'").rstrip()
73 args = args.replace('"','\\"').replace("'","\\'").rstrip()
74 return '%s%s ("%s")%s' % (MAGIC_PREFIX,func,args,endl)
74 return '%s%s ("%s")%s' % (MAGIC_PREFIX,func,args,endl)
75 else:
75 else:
76 return cmd
76 return cmd
77
77
78 def on_off(tag):
78 def on_off(tag):
79 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
79 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
80 return ['OFF','ON'][tag]
80 return ['OFF','ON'][tag]
81
81
82
82
83 #****************************************************************************
83 #****************************************************************************
84 # Utility classes
84 # Utility classes
85 class Macro:
85 class Macro:
86 """Simple class to store the value of macros as strings.
86 """Simple class to store the value of macros as strings.
87
87
88 This allows us to later exec them by checking when something is an
88 This allows us to later exec them by checking when something is an
89 instance of this class."""
89 instance of this class."""
90
90
91 def __init__(self,cmds):
91 def __init__(self,cmds):
92 """Build a macro from a list of commands."""
92 """Build a macro from a list of commands."""
93
93
94 # Since the list may include multi-line entries, first make sure that
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
95 # they've been all broken up before passing it to magic2python
96 cmdlist = map(magic2python,''.join(cmds).split('\n'))
96 cmdlist = map(magic2python,''.join(cmds).split('\n'))
97 self.value = '\n'.join(cmdlist)
97 self.value = '\n'.join(cmdlist)
98
98
99 def __str__(self):
99 def __str__(self):
100 return self.value
100 return self.value
101
101
102 #***************************************************************************
102 #***************************************************************************
103 # Main class implementing Magic functionality
103 # Main class implementing Magic functionality
104 class Magic:
104 class Magic:
105 """Magic functions for InteractiveShell.
105 """Magic functions for InteractiveShell.
106
106
107 Shell functions which can be reached as %function_name. All magic
107 Shell functions which can be reached as %function_name. All magic
108 functions should accept a string, which they can parse for their own
108 functions should accept a string, which they can parse for their own
109 needs. This can make some functions easier to type, eg `%cd ../`
109 needs. This can make some functions easier to type, eg `%cd ../`
110 vs. `%cd("../")`
110 vs. `%cd("../")`
111
111
112 ALL definitions MUST begin with the prefix magic_. The user won't need it
112 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. """
113 at the command line, but it is is needed in the definition. """
114
114
115 # class globals
115 # class globals
116 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
116 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
117 'Automagic is ON, % prefix NOT needed for magic functions.']
117 'Automagic is ON, % prefix NOT needed for magic functions.']
118
118
119 #......................................................................
119 #......................................................................
120 # some utility functions
120 # some utility functions
121
121
122 def __init__(self,shell):
122 def __init__(self,shell):
123 # XXX This is hackish, clean up later to avoid these messy globals
123 # XXX This is hackish, clean up later to avoid these messy globals
124 global MAGIC_PREFIX, MAGIC_ESCAPE
124 global MAGIC_PREFIX, MAGIC_ESCAPE
125
125
126 self.options_table = {}
126 self.options_table = {}
127 MAGIC_PREFIX = shell.name+'.magic_'
127 MAGIC_PREFIX = shell.name+'.magic_'
128 MAGIC_ESCAPE = shell.ESC_MAGIC
128 MAGIC_ESCAPE = shell.ESC_MAGIC
129 if profile is None:
129 if profile is None:
130 self.magic_prun = self.profile_missing_notice
130 self.magic_prun = self.profile_missing_notice
131
131
132 def profile_missing_notice(self, *args, **kwargs):
132 def profile_missing_notice(self, *args, **kwargs):
133 error("""\
133 error("""\
134 The profile module could not be found. If you are a Debian user,
134 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
135 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.""")
136 license. To use profiling, please install"python2.3-profiler" from non-free.""")
137
137
138 def default_option(self,fn,optstr):
138 def default_option(self,fn,optstr):
139 """Make an entry in the options_table for fn, with value optstr"""
139 """Make an entry in the options_table for fn, with value optstr"""
140
140
141 if fn not in self.lsmagic():
141 if fn not in self.lsmagic():
142 error("%s is not a magic function" % fn)
142 error("%s is not a magic function" % fn)
143 self.options_table[fn] = optstr
143 self.options_table[fn] = optstr
144
144
145 def lsmagic(self):
145 def lsmagic(self):
146 """Return a list of currently available magic functions.
146 """Return a list of currently available magic functions.
147
147
148 Gives a list of the bare names after mangling (['ls','cd', ...], not
148 Gives a list of the bare names after mangling (['ls','cd', ...], not
149 ['magic_ls','magic_cd',...]"""
149 ['magic_ls','magic_cd',...]"""
150
150
151 # FIXME. This needs a cleanup, in the way the magics list is built.
151 # FIXME. This needs a cleanup, in the way the magics list is built.
152
152
153 # magics in class definition
153 # magics in class definition
154 class_magic = lambda fn: fn.startswith('magic_') and \
154 class_magic = lambda fn: fn.startswith('magic_') and \
155 callable(Magic.__dict__[fn])
155 callable(Magic.__dict__[fn])
156 # in instance namespace (run-time user additions)
156 # in instance namespace (run-time user additions)
157 inst_magic = lambda fn: fn.startswith('magic_') and \
157 inst_magic = lambda fn: fn.startswith('magic_') and \
158 callable(self.__dict__[fn])
158 callable(self.__dict__[fn])
159 # and bound magics by user (so they can access self):
159 # and bound magics by user (so they can access self):
160 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
160 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
161 callable(self.__class__.__dict__[fn])
161 callable(self.__class__.__dict__[fn])
162 magics = filter(class_magic,Magic.__dict__.keys()) + \
162 magics = filter(class_magic,Magic.__dict__.keys()) + \
163 filter(inst_magic,self.__dict__.keys()) + \
163 filter(inst_magic,self.__dict__.keys()) + \
164 filter(inst_bound_magic,self.__class__.__dict__.keys())
164 filter(inst_bound_magic,self.__class__.__dict__.keys())
165 out = []
165 out = []
166 for fn in magics:
166 for fn in magics:
167 out.append(fn.replace('magic_','',1))
167 out.append(fn.replace('magic_','',1))
168 out.sort()
168 out.sort()
169 return out
169 return out
170
170
171 def set_shell(self,shell):
171 def set_shell(self,shell):
172 self.shell = shell
172 self.shell = shell
173 self.alias_table = shell.alias_table
173 self.alias_table = shell.alias_table
174
174
175 def extract_input_slices(self,slices):
175 def extract_input_slices(self,slices):
176 """Return as a string a set of input history slices.
176 """Return as a string a set of input history slices.
177
177
178 The set of slices is given as a list of strings (like ['1','4:8','9'],
178 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
179 since this function is for use by magic functions which get their
180 arguments as strings."""
180 arguments as strings."""
181
181
182 cmds = []
182 cmds = []
183 for chunk in slices:
183 for chunk in slices:
184 if ':' in chunk:
184 if ':' in chunk:
185 ini,fin = map(int,chunk.split(':'))
185 ini,fin = map(int,chunk.split(':'))
186 else:
186 else:
187 ini = int(chunk)
187 ini = int(chunk)
188 fin = ini+1
188 fin = ini+1
189 cmds.append(self.shell.input_hist[ini:fin])
189 cmds.append(self.shell.input_hist[ini:fin])
190 return cmds
190 return cmds
191
191
192 def _ofind(self,oname):
192 def _ofind(self,oname):
193 """Find an object in the available namespaces.
193 """Find an object in the available namespaces.
194
194
195 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
195 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
196
196
197 Has special code to detect magic functions.
197 Has special code to detect magic functions.
198 """
198 """
199
199
200 oname = oname.strip()
200 oname = oname.strip()
201
201
202 # Namespaces to search in:
202 # Namespaces to search in:
203 user_ns = self.shell.user_ns
203 user_ns = self.shell.user_ns
204 internal_ns = self.shell.internal_ns
204 internal_ns = self.shell.internal_ns
205 builtin_ns = __builtin__.__dict__
205 builtin_ns = __builtin__.__dict__
206 alias_ns = self.shell.alias_table
206 alias_ns = self.shell.alias_table
207
207
208 # Put them in a list. The order is important so that we find things in
208 # Put them in a list. The order is important so that we find things in
209 # the same order that Python finds them.
209 # the same order that Python finds them.
210 namespaces = [ ('Interactive',user_ns),
210 namespaces = [ ('Interactive',user_ns),
211 ('IPython internal',internal_ns),
211 ('IPython internal',internal_ns),
212 ('Python builtin',builtin_ns),
212 ('Python builtin',builtin_ns),
213 ('Alias',alias_ns),
213 ('Alias',alias_ns),
214 ]
214 ]
215
215
216 # initialize results to 'null'
216 # initialize results to 'null'
217 found = 0; obj = None; ospace = None; ds = None;
217 found = 0; obj = None; ospace = None; ds = None;
218 ismagic = 0; isalias = 0
218 ismagic = 0; isalias = 0
219
219
220 # Look for the given name by splitting it in parts. If the head is
220 # 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
221 # found, then we look for all the remaining parts as members, and only
222 # declare success if we can find them all.
222 # declare success if we can find them all.
223 oname_parts = oname.split('.')
223 oname_parts = oname.split('.')
224 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
224 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
225 for nsname,ns in namespaces:
225 for nsname,ns in namespaces:
226 try:
226 try:
227 obj = ns[oname_head]
227 obj = ns[oname_head]
228 except KeyError:
228 except KeyError:
229 continue
229 continue
230 else:
230 else:
231 for part in oname_rest:
231 for part in oname_rest:
232 try:
232 try:
233 obj = getattr(obj,part)
233 obj = getattr(obj,part)
234 except:
234 except:
235 # Blanket except b/c some badly implemented objects
235 # Blanket except b/c some badly implemented objects
236 # allow __getattr__ to raise exceptions other than
236 # allow __getattr__ to raise exceptions other than
237 # AttributeError, which then crashes IPython.
237 # AttributeError, which then crashes IPython.
238 break
238 break
239 else:
239 else:
240 # If we finish the for loop (no break), we got all members
240 # If we finish the for loop (no break), we got all members
241 found = 1
241 found = 1
242 ospace = nsname
242 ospace = nsname
243 if ns == alias_ns:
243 if ns == alias_ns:
244 isalias = 1
244 isalias = 1
245 break # namespace loop
245 break # namespace loop
246
246
247 # Try to see if it's magic
247 # Try to see if it's magic
248 if not found:
248 if not found:
249 if oname.startswith(self.shell.ESC_MAGIC):
249 if oname.startswith(self.shell.ESC_MAGIC):
250 oname = oname[1:]
250 oname = oname[1:]
251 obj = getattr(self,'magic_'+oname,None)
251 obj = getattr(self,'magic_'+oname,None)
252 if obj is not None:
252 if obj is not None:
253 found = 1
253 found = 1
254 ospace = 'IPython internal'
254 ospace = 'IPython internal'
255 ismagic = 1
255 ismagic = 1
256
256
257 # Last try: special-case some literals like '', [], {}, etc:
257 # Last try: special-case some literals like '', [], {}, etc:
258 if not found and oname_head in ["''",'""','[]','{}','()']:
258 if not found and oname_head in ["''",'""','[]','{}','()']:
259 obj = eval(oname_head)
259 obj = eval(oname_head)
260 found = 1
260 found = 1
261 ospace = 'Interactive'
261 ospace = 'Interactive'
262
262
263 return {'found':found, 'obj':obj, 'namespace':ospace,
263 return {'found':found, 'obj':obj, 'namespace':ospace,
264 'ismagic':ismagic, 'isalias':isalias}
264 'ismagic':ismagic, 'isalias':isalias}
265
265
266 def arg_err(self,func):
266 def arg_err(self,func):
267 """Print docstring if incorrect arguments were passed"""
267 """Print docstring if incorrect arguments were passed"""
268 print 'Error in arguments:'
268 print 'Error in arguments:'
269 print OInspect.getdoc(func)
269 print OInspect.getdoc(func)
270
270
271
271
272 def format_latex(self,str):
272 def format_latex(self,str):
273 """Format a string for latex inclusion."""
273 """Format a string for latex inclusion."""
274
274
275 # Characters that need to be escaped for latex:
275 # Characters that need to be escaped for latex:
276 escape_re = re.compile(r'(%|_|\$)',re.MULTILINE)
276 escape_re = re.compile(r'(%|_|\$)',re.MULTILINE)
277 # Magic command names as headers:
277 # Magic command names as headers:
278 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
278 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
279 re.MULTILINE)
279 re.MULTILINE)
280 # Magic commands
280 # Magic commands
281 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
281 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
282 re.MULTILINE)
282 re.MULTILINE)
283 # Paragraph continue
283 # Paragraph continue
284 par_re = re.compile(r'\\$',re.MULTILINE)
284 par_re = re.compile(r'\\$',re.MULTILINE)
285
285
286 str = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',str)
286 str = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',str)
287 str = cmd_re.sub(r'\\texttt{\g<cmd>}',str)
287 str = cmd_re.sub(r'\\texttt{\g<cmd>}',str)
288 str = par_re.sub(r'\\\\',str)
288 str = par_re.sub(r'\\\\',str)
289 str = escape_re.sub(r'\\\1',str)
289 str = escape_re.sub(r'\\\1',str)
290 return str
290 return str
291
291
292 def format_screen(self,str):
292 def format_screen(self,str):
293 """Format a string for screen printing.
293 """Format a string for screen printing.
294
294
295 This removes some latex-type format codes."""
295 This removes some latex-type format codes."""
296 # Paragraph continue
296 # Paragraph continue
297 par_re = re.compile(r'\\$',re.MULTILINE)
297 par_re = re.compile(r'\\$',re.MULTILINE)
298 str = par_re.sub('',str)
298 str = par_re.sub('',str)
299 return str
299 return str
300
300
301 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
301 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
302 """Parse options passed to an argument string.
302 """Parse options passed to an argument string.
303
303
304 The interface is similar to that of getopt(), but it returns back a
304 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
305 Struct with the options as keys and the stripped argument string still
306 as a string.
306 as a string.
307
307
308 arg_str is quoted as a true sys.argv vector by using shlex.split.
308 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
309 This allows us to easily expand variables, glob files, quote
310 arguments, etc.
310 arguments, etc.
311
311
312 Options:
312 Options:
313 -mode: default 'string'. If given as 'list', the argument string is
313 -mode: default 'string'. If given as 'list', the argument string is
314 returned as a list (split on whitespace) instead of a string.
314 returned as a list (split on whitespace) instead of a string.
315
315
316 -list_all: put all option values in lists. Normally only options
316 -list_all: put all option values in lists. Normally only options
317 appearing more than once are put in a list."""
317 appearing more than once are put in a list."""
318
318
319 # inject default options at the beginning of the input line
319 # inject default options at the beginning of the input line
320 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
320 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
321 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
321 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
322
322
323 mode = kw.get('mode','string')
323 mode = kw.get('mode','string')
324 if mode not in ['string','list']:
324 if mode not in ['string','list']:
325 raise ValueError,'incorrect mode given: %s' % mode
325 raise ValueError,'incorrect mode given: %s' % mode
326 # Get options
326 # Get options
327 list_all = kw.get('list_all',0)
327 list_all = kw.get('list_all',0)
328
328
329 # Check if we have more than one argument to warrant extra processing:
329 # Check if we have more than one argument to warrant extra processing:
330 odict = {} # Dictionary with options
330 odict = {} # Dictionary with options
331 args = arg_str.split()
331 args = arg_str.split()
332 if len(args) >= 1:
332 if len(args) >= 1:
333 # If the list of inputs only has 0 or 1 thing in it, there's no
333 # If the list of inputs only has 0 or 1 thing in it, there's no
334 # need to look for options
334 # need to look for options
335 argv = shlex_split(arg_str)
335 argv = shlex_split(arg_str)
336 # Do regular option processing
336 # Do regular option processing
337 opts,args = getopt(argv,opt_str,*long_opts)
337 opts,args = getopt(argv,opt_str,*long_opts)
338 for o,a in opts:
338 for o,a in opts:
339 if o.startswith('--'):
339 if o.startswith('--'):
340 o = o[2:]
340 o = o[2:]
341 else:
341 else:
342 o = o[1:]
342 o = o[1:]
343 try:
343 try:
344 odict[o].append(a)
344 odict[o].append(a)
345 except AttributeError:
345 except AttributeError:
346 odict[o] = [odict[o],a]
346 odict[o] = [odict[o],a]
347 except KeyError:
347 except KeyError:
348 if list_all:
348 if list_all:
349 odict[o] = [a]
349 odict[o] = [a]
350 else:
350 else:
351 odict[o] = a
351 odict[o] = a
352
352
353 # Prepare opts,args for return
353 # Prepare opts,args for return
354 opts = Struct(odict)
354 opts = Struct(odict)
355 if mode == 'string':
355 if mode == 'string':
356 args = ' '.join(args)
356 args = ' '.join(args)
357
357
358 return opts,args
358 return opts,args
359
359
360 #......................................................................
360 #......................................................................
361 # And now the actual magic functions
361 # And now the actual magic functions
362
362
363 # Functions for IPython shell work (vars,funcs, config, etc)
363 # Functions for IPython shell work (vars,funcs, config, etc)
364 def magic_lsmagic(self, parameter_s = ''):
364 def magic_lsmagic(self, parameter_s = ''):
365 """List currently available magic functions."""
365 """List currently available magic functions."""
366 mesc = self.shell.ESC_MAGIC
366 mesc = self.shell.ESC_MAGIC
367 print 'Available magic functions:\n'+mesc+\
367 print 'Available magic functions:\n'+mesc+\
368 (' '+mesc).join(self.lsmagic())
368 (' '+mesc).join(self.lsmagic())
369 print '\n' + Magic.auto_status[self.shell.rc.automagic]
369 print '\n' + Magic.auto_status[self.shell.rc.automagic]
370 return None
370 return None
371
371
372 def magic_magic(self, parameter_s = ''):
372 def magic_magic(self, parameter_s = ''):
373 """Print information about the magic function system."""
373 """Print information about the magic function system."""
374
374
375 mode = ''
375 mode = ''
376 try:
376 try:
377 if parameter_s.split()[0] == '-latex':
377 if parameter_s.split()[0] == '-latex':
378 mode = 'latex'
378 mode = 'latex'
379 except:
379 except:
380 pass
380 pass
381
381
382 magic_docs = []
382 magic_docs = []
383 for fname in self.lsmagic():
383 for fname in self.lsmagic():
384 mname = 'magic_' + fname
384 mname = 'magic_' + fname
385 for space in (Magic,self,self.__class__):
385 for space in (Magic,self,self.__class__):
386 try:
386 try:
387 fn = space.__dict__[mname]
387 fn = space.__dict__[mname]
388 except KeyError:
388 except KeyError:
389 pass
389 pass
390 else:
390 else:
391 break
391 break
392 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
392 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
393 fname,fn.__doc__))
393 fname,fn.__doc__))
394 magic_docs = ''.join(magic_docs)
394 magic_docs = ''.join(magic_docs)
395
395
396 if mode == 'latex':
396 if mode == 'latex':
397 print self.format_latex(magic_docs)
397 print self.format_latex(magic_docs)
398 return
398 return
399 else:
399 else:
400 magic_docs = self.format_screen(magic_docs)
400 magic_docs = self.format_screen(magic_docs)
401
401
402 outmsg = """
402 outmsg = """
403 IPython's 'magic' functions
403 IPython's 'magic' functions
404 ===========================
404 ===========================
405
405
406 The magic function system provides a series of functions which allow you to
406 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
407 control the behavior of IPython itself, plus a lot of system-type
408 features. All these functions are prefixed with a % character, but parameters
408 features. All these functions are prefixed with a % character, but parameters
409 are given without parentheses or quotes.
409 are given without parentheses or quotes.
410
410
411 NOTE: If you have 'automagic' enabled (via the command line option or with the
411 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,
412 %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.
413 IPython ships with automagic on, so you should only rarely need the % escape.
414
414
415 Example: typing '%cd mydir' (without the quotes) changes you working directory
415 Example: typing '%cd mydir' (without the quotes) changes you working directory
416 to 'mydir', if it exists.
416 to 'mydir', if it exists.
417
417
418 You can define your own magic functions to extend the system. See the supplied
418 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
419 ipythonrc and example-magic.py files for details (in your ipython
420 configuration directory, typically $HOME/.ipython/).
420 configuration directory, typically $HOME/.ipython/).
421
421
422 You can also define your own aliased names for magic functions. In your
422 You can also define your own aliased names for magic functions. In your
423 ipythonrc file, placing a line like:
423 ipythonrc file, placing a line like:
424
424
425 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
425 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
426
426
427 will define %pf as a new name for %profile.
427 will define %pf as a new name for %profile.
428
428
429 You can also call magics in code using the ipmagic() function, which IPython
429 You can also call magics in code using the ipmagic() function, which IPython
430 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
430 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
431
431
432 For a list of the available magic functions, use %lsmagic. For a description
432 For a list of the available magic functions, use %lsmagic. For a description
433 of any of them, type %magic_name?, e.g. '%cd?'.
433 of any of them, type %magic_name?, e.g. '%cd?'.
434
434
435 Currently the magic system has the following functions:\n"""
435 Currently the magic system has the following functions:\n"""
436
436
437 mesc = self.shell.ESC_MAGIC
437 mesc = self.shell.ESC_MAGIC
438 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
438 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
439 "\n\n%s%s\n\n%s" % (outmsg,
439 "\n\n%s%s\n\n%s" % (outmsg,
440 magic_docs,mesc,mesc,
440 magic_docs,mesc,mesc,
441 (' '+mesc).join(self.lsmagic()),
441 (' '+mesc).join(self.lsmagic()),
442 Magic.auto_status[self.shell.rc.automagic] ) )
442 Magic.auto_status[self.shell.rc.automagic] ) )
443
443
444 page(outmsg,screen_lines=self.shell.rc.screen_length)
444 page(outmsg,screen_lines=self.shell.rc.screen_length)
445
445
446 def magic_automagic(self, parameter_s = ''):
446 def magic_automagic(self, parameter_s = ''):
447 """Make magic functions callable without having to type the initial %.
447 """Make magic functions callable without having to type the initial %.
448
448
449 Toggles on/off (when off, you must call it as %automagic, of
449 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
450 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
451 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,
452 won't work for that function (you get the variable instead). However,
453 if you delete the variable (del var), the previously shadowed magic
453 if you delete the variable (del var), the previously shadowed magic
454 function becomes visible to automagic again."""
454 function becomes visible to automagic again."""
455
455
456 rc = self.shell.rc
456 rc = self.shell.rc
457 rc.automagic = not rc.automagic
457 rc.automagic = not rc.automagic
458 print '\n' + Magic.auto_status[rc.automagic]
458 print '\n' + Magic.auto_status[rc.automagic]
459
459
460 def magic_autocall(self, parameter_s = ''):
460 def magic_autocall(self, parameter_s = ''):
461 """Make functions callable without having to type parentheses.
461 """Make functions callable without having to type parentheses.
462
462
463 This toggles the autocall command line option on and off."""
463 This toggles the autocall command line option on and off."""
464
464
465 rc = self.shell.rc
465 rc = self.shell.rc
466 rc.autocall = not rc.autocall
466 rc.autocall = not rc.autocall
467 print "Automatic calling is:",['OFF','ON'][rc.autocall]
467 print "Automatic calling is:",['OFF','ON'][rc.autocall]
468
468
469 def magic_autoindent(self, parameter_s = ''):
469 def magic_autoindent(self, parameter_s = ''):
470 """Toggle autoindent on/off (if available)."""
470 """Toggle autoindent on/off (if available)."""
471
471
472 self.shell.set_autoindent()
472 self.shell.set_autoindent()
473 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
473 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
474
474
475 def magic_system_verbose(self, parameter_s = ''):
475 def magic_system_verbose(self, parameter_s = ''):
476 """Toggle verbose printing of system calls on/off."""
476 """Toggle verbose printing of system calls on/off."""
477
477
478 self.shell.rc_set_toggle('system_verbose')
478 self.shell.rc_set_toggle('system_verbose')
479 print "System verbose printing is:",\
479 print "System verbose printing is:",\
480 ['OFF','ON'][self.shell.rc.system_verbose]
480 ['OFF','ON'][self.shell.rc.system_verbose]
481
481
482 def magic_history(self, parameter_s = ''):
482 def magic_history(self, parameter_s = ''):
483 """Print input history (_i<n> variables), with most recent last.
483 """Print input history (_i<n> variables), with most recent last.
484
484
485 %history [-n] -> print at most 40 inputs (some may be multi-line)\\
485 %history [-n] -> print at most 40 inputs (some may be multi-line)\\
486 %history [-n] n -> print at most n inputs\\
486 %history [-n] n -> print at most n inputs\\
487 %history [-n] n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
487 %history [-n] n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
488
488
489 Each input's number <n> is shown, and is accessible as the
489 Each input's number <n> is shown, and is accessible as the
490 automatically generated variable _i<n>. Multi-line statements are
490 automatically generated variable _i<n>. Multi-line statements are
491 printed starting at a new line for easy copy/paste.
491 printed starting at a new line for easy copy/paste.
492
492
493 If option -n is used, input numbers are not printed. This is useful if
493 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
494 you want to get a printout of many lines which can be directly pasted
495 into a text editor.
495 into a text editor.
496
496
497 This feature is only available if numbered prompts are in use."""
497 This feature is only available if numbered prompts are in use."""
498
498
499 if not self.do_full_cache:
499 if not self.do_full_cache:
500 print 'This feature is only available if numbered prompts are in use.'
500 print 'This feature is only available if numbered prompts are in use.'
501 return
501 return
502 opts,args = self.parse_options(parameter_s,'n',mode='list')
502 opts,args = self.parse_options(parameter_s,'n',mode='list')
503
503
504 default_length = 40
504 default_length = 40
505 if len(args) == 0:
505 if len(args) == 0:
506 final = self.outputcache.prompt_count
506 final = self.outputcache.prompt_count
507 init = max(1,final-default_length)
507 init = max(1,final-default_length)
508 elif len(args) == 1:
508 elif len(args) == 1:
509 final = self.outputcache.prompt_count
509 final = self.outputcache.prompt_count
510 init = max(1,final-int(args[0]))
510 init = max(1,final-int(args[0]))
511 elif len(args) == 2:
511 elif len(args) == 2:
512 init,final = map(int,args)
512 init,final = map(int,args)
513 else:
513 else:
514 warn('%hist takes 0, 1 or 2 arguments separated by spaces.')
514 warn('%hist takes 0, 1 or 2 arguments separated by spaces.')
515 print self.magic_hist.__doc__
515 print self.magic_hist.__doc__
516 return
516 return
517 width = len(str(final))
517 width = len(str(final))
518 line_sep = ['','\n']
518 line_sep = ['','\n']
519 input_hist = self.shell.input_hist
519 input_hist = self.shell.input_hist
520 print_nums = not opts.has_key('n')
520 print_nums = not opts.has_key('n')
521 for in_num in range(init,final):
521 for in_num in range(init,final):
522 inline = input_hist[in_num]
522 inline = input_hist[in_num]
523 multiline = inline.count('\n') > 1
523 multiline = inline.count('\n') > 1
524 if print_nums:
524 if print_nums:
525 print str(in_num).ljust(width)+':'+ line_sep[multiline],
525 print str(in_num).ljust(width)+':'+ line_sep[multiline],
526 if inline.startswith('#'+self.shell.ESC_MAGIC) or \
526 if inline.startswith('#'+self.shell.ESC_MAGIC) or \
527 inline.startswith('#!'):
527 inline.startswith('#!'):
528 print inline[1:],
528 print inline[1:],
529 else:
529 else:
530 print inline,
530 print inline,
531
531
532 def magic_hist(self, parameter_s=''):
532 def magic_hist(self, parameter_s=''):
533 """Alternate name for %history."""
533 """Alternate name for %history."""
534 return self.magic_history(parameter_s)
534 return self.magic_history(parameter_s)
535
535
536 def magic_p(self, parameter_s=''):
536 def magic_p(self, parameter_s=''):
537 """Just a short alias for Python's 'print'."""
537 """Just a short alias for Python's 'print'."""
538 exec 'print ' + parameter_s in self.shell.user_ns
538 exec 'print ' + parameter_s in self.shell.user_ns
539
539
540 def magic_r(self, parameter_s=''):
540 def magic_r(self, parameter_s=''):
541 """Repeat previous input.
541 """Repeat previous input.
542
542
543 If given an argument, repeats the previous command which starts with
543 If given an argument, repeats the previous command which starts with
544 the same string, otherwise it just repeats the previous input.
544 the same string, otherwise it just repeats the previous input.
545
545
546 Shell escaped commands (with ! as first character) are not recognized
546 Shell escaped commands (with ! as first character) are not recognized
547 by this system, only pure python code and magic commands.
547 by this system, only pure python code and magic commands.
548 """
548 """
549
549
550 start = parameter_s.strip()
550 start = parameter_s.strip()
551 esc_magic = self.shell.ESC_MAGIC
551 esc_magic = self.shell.ESC_MAGIC
552 # Identify magic commands even if automagic is on (which means
552 # Identify magic commands even if automagic is on (which means
553 # the in-memory version is different from that typed by the user).
553 # the in-memory version is different from that typed by the user).
554 if self.shell.rc.automagic:
554 if self.shell.rc.automagic:
555 start_magic = esc_magic+start
555 start_magic = esc_magic+start
556 else:
556 else:
557 start_magic = start
557 start_magic = start
558 # Look through the input history in reverse
558 # Look through the input history in reverse
559 for n in range(len(self.shell.input_hist)-2,0,-1):
559 for n in range(len(self.shell.input_hist)-2,0,-1):
560 input = self.shell.input_hist[n]
560 input = self.shell.input_hist[n]
561 # skip plain 'r' lines so we don't recurse to infinity
561 # skip plain 'r' lines so we don't recurse to infinity
562 if input != 'ipmagic("r")\n' and \
562 if input != 'ipmagic("r")\n' and \
563 (input.startswith(start) or input.startswith(start_magic)):
563 (input.startswith(start) or input.startswith(start_magic)):
564 #print 'match',`input` # dbg
564 #print 'match',`input` # dbg
565 if input.startswith(esc_magic):
565 if input.startswith(esc_magic):
566 input = magic2python(input)
566 input = magic2python(input)
567 #print 'modified',`input` # dbg
567 #print 'modified',`input` # dbg
568 print 'Executing:',input,
568 print 'Executing:',input,
569 exec input in self.shell.user_ns
569 exec input in self.shell.user_ns
570 return
570 return
571 print 'No previous input matching `%s` found.' % start
571 print 'No previous input matching `%s` found.' % start
572
572
573 def magic_page(self, parameter_s=''):
573 def magic_page(self, parameter_s=''):
574 """Pretty print the object and display it through a pager.
574 """Pretty print the object and display it through a pager.
575
575
576 If no parameter is given, use _ (last output)."""
576 If no parameter is given, use _ (last output)."""
577 # After a function contributed by Olivier Aubert, slightly modified.
577 # After a function contributed by Olivier Aubert, slightly modified.
578
578
579 oname = parameter_s and parameter_s or '_'
579 oname = parameter_s and parameter_s or '_'
580 info = self._ofind(oname)
580 info = self._ofind(oname)
581 if info['found']:
581 if info['found']:
582 page(pformat(info['obj']))
582 page(pformat(info['obj']))
583 else:
583 else:
584 print 'Object `%s` not found' % oname
584 print 'Object `%s` not found' % oname
585
585
586 def magic_profile(self, parameter_s=''):
586 def magic_profile(self, parameter_s=''):
587 """Print your currently active IPyhton profile."""
587 """Print your currently active IPyhton profile."""
588 if self.shell.rc.profile:
588 if self.shell.rc.profile:
589 printpl('Current IPython profile: $self.shell.rc.profile.')
589 printpl('Current IPython profile: $self.shell.rc.profile.')
590 else:
590 else:
591 print 'No profile active.'
591 print 'No profile active.'
592
592
593 def _inspect(self,meth,oname,**kw):
593 def _inspect(self,meth,oname,**kw):
594 """Generic interface to the inspector system.
594 """Generic interface to the inspector system.
595
595
596 This function is meant to be called by pdef, pdoc & friends."""
596 This function is meant to be called by pdef, pdoc & friends."""
597
597
598 oname = oname.strip()
598 oname = oname.strip()
599 info = Struct(self._ofind(oname))
599 info = Struct(self._ofind(oname))
600 if info.found:
600 if info.found:
601 pmethod = getattr(self.shell.inspector,meth)
601 pmethod = getattr(self.shell.inspector,meth)
602 formatter = info.ismagic and self.format_screen or None
602 formatter = info.ismagic and self.format_screen or None
603 if meth == 'pdoc':
603 if meth == 'pdoc':
604 pmethod(info.obj,oname,formatter)
604 pmethod(info.obj,oname,formatter)
605 elif meth == 'pinfo':
605 elif meth == 'pinfo':
606 pmethod(info.obj,oname,formatter,info,**kw)
606 pmethod(info.obj,oname,formatter,info,**kw)
607 else:
607 else:
608 pmethod(info.obj,oname)
608 pmethod(info.obj,oname)
609 else:
609 else:
610 print 'Object `%s` not found.' % oname
610 print 'Object `%s` not found.' % oname
611 return 'not found' # so callers can take other action
611 return 'not found' # so callers can take other action
612
612
613 def magic_pdef(self, parameter_s=''):
613 def magic_pdef(self, parameter_s=''):
614 """Print the definition header for any callable object.
614 """Print the definition header for any callable object.
615
615
616 If the object is a class, print the constructor information."""
616 If the object is a class, print the constructor information."""
617 self._inspect('pdef',parameter_s)
617 self._inspect('pdef',parameter_s)
618
618
619 def magic_pdoc(self, parameter_s=''):
619 def magic_pdoc(self, parameter_s=''):
620 """Print the docstring for an object.
620 """Print the docstring for an object.
621
621
622 If the given object is a class, it will print both the class and the
622 If the given object is a class, it will print both the class and the
623 constructor docstrings."""
623 constructor docstrings."""
624 self._inspect('pdoc',parameter_s)
624 self._inspect('pdoc',parameter_s)
625
625
626 def magic_psource(self, parameter_s=''):
626 def magic_psource(self, parameter_s=''):
627 """Print (or run through pager) the source code for an object."""
627 """Print (or run through pager) the source code for an object."""
628 self._inspect('psource',parameter_s)
628 self._inspect('psource',parameter_s)
629
629
630 def magic_pfile(self, parameter_s=''):
630 def magic_pfile(self, parameter_s=''):
631 """Print (or run through pager) the file where an object is defined.
631 """Print (or run through pager) the file where an object is defined.
632
632
633 The file opens at the line where the object definition begins. IPython
633 The file opens at the line where the object definition begins. IPython
634 will honor the environment variable PAGER if set, and otherwise will
634 will honor the environment variable PAGER if set, and otherwise will
635 do its best to print the file in a convenient form.
635 do its best to print the file in a convenient form.
636
636
637 If the given argument is not an object currently defined, IPython will
637 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
638 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
639 if needed). You can thus use %pfile as a syntax highlighting code
640 viewer."""
640 viewer."""
641
641
642 # first interpret argument as an object name
642 # first interpret argument as an object name
643 out = self._inspect('pfile',parameter_s)
643 out = self._inspect('pfile',parameter_s)
644 # if not, try the input as a filename
644 # if not, try the input as a filename
645 if out == 'not found':
645 if out == 'not found':
646 try:
646 try:
647 filename = get_py_filename(parameter_s)
647 filename = get_py_filename(parameter_s)
648 except IOError,msg:
648 except IOError,msg:
649 print msg
649 print msg
650 return
650 return
651 page(self.shell.inspector.format(file(filename).read()))
651 page(self.shell.inspector.format(file(filename).read()))
652
652
653 def magic_pinfo(self, parameter_s=''):
653 def magic_pinfo(self, parameter_s=''):
654 """Provide detailed information about an object.
654 """Provide detailed information about an object.
655
655
656 '%pinfo object' is just a synonym for object? or ?object."""
656 '%pinfo object' is just a synonym for object? or ?object."""
657
657
658 #print 'pinfo par: <%s>' % parameter_s # dbg
658 #print 'pinfo par: <%s>' % parameter_s # dbg
659
659
660 # detail_level: 0 -> obj? , 1 -> obj??
660 # detail_level: 0 -> obj? , 1 -> obj??
661 detail_level = 0
661 detail_level = 0
662 # We need to detect if we got called as 'pinfo pinfo foo', which can
662 # 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.
663 # happen if the user types 'pinfo foo?' at the cmd line.
664 pinfo,qmark1,oname,qmark2 = \
664 pinfo,qmark1,oname,qmark2 = \
665 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
665 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
666 if pinfo or qmark1 or qmark2:
666 if pinfo or qmark1 or qmark2:
667 detail_level = 1
667 detail_level = 1
668 if "*" in oname:
668 if "*" in oname:
669 self.magic_psearch(oname)
669 self.magic_psearch(oname)
670 else:
670 else:
671 self._inspect('pinfo',oname,detail_level=detail_level)
671 self._inspect('pinfo',oname,detail_level=detail_level)
672
672
673 def magic_psearch(self, parameter_s=''):
673 def magic_psearch(self, parameter_s=''):
674 """Search for object in namespaces by wildcard.
674 """Search for object in namespaces by wildcard.
675
675
676 %psearch [options] PATTERN [OBJECT TYPE]
676 %psearch [options] PATTERN [OBJECT TYPE]
677
677
678 Note: ? can be used as a synonym for %psearch, at the beginning or at
678 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
679 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
680 rest of the command line must be unchanged (options come first), so
681 for example the following forms are equivalent
681 for example the following forms are equivalent
682
682
683 %psearch -i a* function
683 %psearch -i a* function
684 -i a* function?
684 -i a* function?
685 ?-i a* function
685 ?-i a* function
686
686
687 Arguments:
687 Arguments:
688
688
689 PATTERN
689 PATTERN
690
690
691 where PATTERN is a string containing * as a wildcard similar to its
691 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
692 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
693 search path. By default objects starting with a single _ are not
694 matched, many IPython generated objects have a single
694 matched, many IPython generated objects have a single
695 underscore. The default is case insensitive matching. Matching is
695 underscore. The default is case insensitive matching. Matching is
696 also done on the attributes of objects and not only on the objects
696 also done on the attributes of objects and not only on the objects
697 in a module.
697 in a module.
698
698
699 [OBJECT TYPE]
699 [OBJECT TYPE]
700
700
701 Is the name of a python type from the types module. The name is
701 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
702 given in lowercase without the ending type, ex. StringType is
703 written string. By adding a type here only objects matching the
703 written string. By adding a type here only objects matching the
704 given type are matched. Using all here makes the pattern match all
704 given type are matched. Using all here makes the pattern match all
705 types (this is the default).
705 types (this is the default).
706
706
707 Options:
707 Options:
708
708
709 -a: makes the pattern match even objects whose names start with a
709 -a: makes the pattern match even objects whose names start with a
710 single underscore. These names are normally ommitted from the
710 single underscore. These names are normally ommitted from the
711 search.
711 search.
712
712
713 -i/-c: make the pattern case insensitive/sensitive. If neither of
713 -i/-c: make the pattern case insensitive/sensitive. If neither of
714 these options is given, the default is read from your ipythonrc
714 these options is given, the default is read from your ipythonrc
715 file. The option name which sets this value is
715 file. The option name which sets this value is
716 'wildcards_case_sensitive'. If this option is not specified in your
716 'wildcards_case_sensitive'. If this option is not specified in your
717 ipythonrc file, IPython's internal default is to do a case sensitive
717 ipythonrc file, IPython's internal default is to do a case sensitive
718 search.
718 search.
719
719
720 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
720 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
721 specifiy can be searched in any of the following namespaces:
721 specifiy can be searched in any of the following namespaces:
722 'builtin', 'user', 'user_global','internal', 'alias', where
722 'builtin', 'user', 'user_global','internal', 'alias', where
723 'builtin' and 'user' are the search defaults. Note that you should
723 'builtin' and 'user' are the search defaults. Note that you should
724 not use quotes when specifying namespaces.
724 not use quotes when specifying namespaces.
725
725
726 'Builtin' contains the python module builtin, 'user' contains all
726 'Builtin' contains the python module builtin, 'user' contains all
727 user data, 'alias' only contain the shell aliases and no python
727 user data, 'alias' only contain the shell aliases and no python
728 objects, 'internal' contains objects used by IPython. The
728 objects, 'internal' contains objects used by IPython. The
729 'user_global' namespace is only used by embedded IPython instances,
729 'user_global' namespace is only used by embedded IPython instances,
730 and it contains module-level globals. You can add namespaces to the
730 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
731 search with -s or exclude them with -e (these options can be given
732 more than once).
732 more than once).
733
733
734 Examples:
734 Examples:
735
735
736 %psearch a* -> objects beginning with an a
736 %psearch a* -> objects beginning with an a
737 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
737 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
738 %psearch a* function -> all functions beginning with an a
738 %psearch a* function -> all functions beginning with an a
739 %psearch re.e* -> objects beginning with an e in module re
739 %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
740 %psearch r*.e* -> objects that start with e in modules starting in r
741 %psearch r*.* string -> all strings in modules beginning with r
741 %psearch r*.* string -> all strings in modules beginning with r
742
742
743 Case sensitve search:
743 Case sensitve search:
744
744
745 %psearch -c a* list all object beginning with lower case a
745 %psearch -c a* list all object beginning with lower case a
746
746
747 Show objects beginning with a single _:
747 Show objects beginning with a single _:
748
748
749 %psearch -a _* list objects beginning with a single underscore"""
749 %psearch -a _* list objects beginning with a single underscore"""
750
750
751 # default namespaces to be searched
751 # default namespaces to be searched
752 def_search = ['user','builtin']
752 def_search = ['user','builtin']
753
753
754 # Process options/args
754 # Process options/args
755 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
755 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
756 opt = opts.get
756 opt = opts.get
757 shell = self.shell
757 shell = self.shell
758 psearch = shell.inspector.psearch
758 psearch = shell.inspector.psearch
759
759
760 # select case options
760 # select case options
761 if opts.has_key('i'):
761 if opts.has_key('i'):
762 ignore_case = True
762 ignore_case = True
763 elif opts.has_key('c'):
763 elif opts.has_key('c'):
764 ignore_case = False
764 ignore_case = False
765 else:
765 else:
766 ignore_case = not shell.rc.wildcards_case_sensitive
766 ignore_case = not shell.rc.wildcards_case_sensitive
767
767
768 # Build list of namespaces to search from user options
768 # Build list of namespaces to search from user options
769 def_search.extend(opt('s',[]))
769 def_search.extend(opt('s',[]))
770 ns_exclude = ns_exclude=opt('e',[])
770 ns_exclude = ns_exclude=opt('e',[])
771 ns_search = [nm for nm in def_search if nm not in ns_exclude]
771 ns_search = [nm for nm in def_search if nm not in ns_exclude]
772
772
773 # Call the actual search
773 # Call the actual search
774 try:
774 try:
775 psearch(args,shell.ns_table,ns_search,
775 psearch(args,shell.ns_table,ns_search,
776 show_all=opt('a'),ignore_case=ignore_case)
776 show_all=opt('a'),ignore_case=ignore_case)
777 except:
777 except:
778 shell.showtraceback()
778 shell.showtraceback()
779
779
780 def magic_who_ls(self, parameter_s=''):
780 def magic_who_ls(self, parameter_s=''):
781 """Return a sorted list of all interactive variables.
781 """Return a sorted list of all interactive variables.
782
782
783 If arguments are given, only variables of types matching these
783 If arguments are given, only variables of types matching these
784 arguments are returned."""
784 arguments are returned."""
785
785
786 user_ns = self.shell.user_ns
786 user_ns = self.shell.user_ns
787 out = []
787 out = []
788 typelist = parameter_s.split()
788 typelist = parameter_s.split()
789 for i in self.shell.user_ns.keys():
789 for i in self.shell.user_ns.keys():
790 if not (i.startswith('_') or i.startswith('_i')) \
790 if not (i.startswith('_') or i.startswith('_i')) \
791 and not (self.internal_ns.has_key(i) or
791 and not (self.internal_ns.has_key(i) or
792 self.user_config_ns.has_key(i)):
792 self.user_config_ns.has_key(i)):
793 if typelist:
793 if typelist:
794 if type(user_ns[i]).__name__ in typelist:
794 if type(user_ns[i]).__name__ in typelist:
795 out.append(i)
795 out.append(i)
796 else:
796 else:
797 out.append(i)
797 out.append(i)
798 out.sort()
798 out.sort()
799 return out
799 return out
800
800
801 def magic_who(self, parameter_s=''):
801 def magic_who(self, parameter_s=''):
802 """Print all interactive variables, with some minimal formatting.
802 """Print all interactive variables, with some minimal formatting.
803
803
804 If any arguments are given, only variables whose type matches one of
804 If any arguments are given, only variables whose type matches one of
805 these are printed. For example:
805 these are printed. For example:
806
806
807 %who function str
807 %who function str
808
808
809 will only list functions and strings, excluding all other types of
809 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
810 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:
811 command line to see how python prints type names. For example:
812
812
813 In [1]: type('hello')\\
813 In [1]: type('hello')\\
814 Out[1]: <type 'str'>
814 Out[1]: <type 'str'>
815
815
816 indicates that the type name for strings is 'str'.
816 indicates that the type name for strings is 'str'.
817
817
818 %who always excludes executed names loaded through your configuration
818 %who always excludes executed names loaded through your configuration
819 file and things which are internal to IPython.
819 file and things which are internal to IPython.
820
820
821 This is deliberate, as typically you may load many modules and the
821 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."""
822 purpose of %who is to show you only what you've manually defined."""
823
823
824 varlist = self.magic_who_ls(parameter_s)
824 varlist = self.magic_who_ls(parameter_s)
825 if not varlist:
825 if not varlist:
826 print 'Interactive namespace is empty.'
826 print 'Interactive namespace is empty.'
827 return
827 return
828
828
829 # if we have variables, move on...
829 # if we have variables, move on...
830
830
831 # stupid flushing problem: when prompts have no separators, stdout is
831 # 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
832 # 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
833 # to force a flush with a print because even a sys.stdout.flush
834 # doesn't seem to do anything!
834 # doesn't seem to do anything!
835
835
836 count = 0
836 count = 0
837 for i in varlist:
837 for i in varlist:
838 print i+'\t',
838 print i+'\t',
839 count += 1
839 count += 1
840 if count > 8:
840 if count > 8:
841 count = 0
841 count = 0
842 print
842 print
843 sys.stdout.flush() # FIXME. Why the hell isn't this flushing???
843 sys.stdout.flush() # FIXME. Why the hell isn't this flushing???
844
844
845 print # well, this does force a flush at the expense of an extra \n
845 print # well, this does force a flush at the expense of an extra \n
846
846
847 def magic_whos(self, parameter_s=''):
847 def magic_whos(self, parameter_s=''):
848 """Like %who, but gives some extra information about each variable.
848 """Like %who, but gives some extra information about each variable.
849
849
850 The same type filtering of %who can be applied here.
850 The same type filtering of %who can be applied here.
851
851
852 For all variables, the type is printed. Additionally it prints:
852 For all variables, the type is printed. Additionally it prints:
853
853
854 - For {},[],(): their length.
854 - For {},[],(): their length.
855
855
856 - For Numeric arrays, a summary with shape, number of elements,
856 - For Numeric arrays, a summary with shape, number of elements,
857 typecode and size in memory.
857 typecode and size in memory.
858
858
859 - Everything else: a string representation, snipping their middle if
859 - Everything else: a string representation, snipping their middle if
860 too long."""
860 too long."""
861
861
862 varnames = self.magic_who_ls(parameter_s)
862 varnames = self.magic_who_ls(parameter_s)
863 if not varnames:
863 if not varnames:
864 print 'Interactive namespace is empty.'
864 print 'Interactive namespace is empty.'
865 return
865 return
866
866
867 # if we have variables, move on...
867 # if we have variables, move on...
868
868
869 # for these types, show len() instead of data:
869 # for these types, show len() instead of data:
870 seq_types = [types.DictType,types.ListType,types.TupleType]
870 seq_types = [types.DictType,types.ListType,types.TupleType]
871
871
872 # for Numeric arrays, display summary info
872 # for Numeric arrays, display summary info
873 try:
873 try:
874 import Numeric
874 import Numeric
875 except ImportError:
875 except ImportError:
876 array_type = None
876 array_type = None
877 else:
877 else:
878 array_type = Numeric.ArrayType.__name__
878 array_type = Numeric.ArrayType.__name__
879
879
880 # Find all variable names and types so we can figure out column sizes
880 # Find all variable names and types so we can figure out column sizes
881 get_vars = lambda i: self.shell.user_ns[i]
881 get_vars = lambda i: self.shell.user_ns[i]
882 type_name = lambda v: type(v).__name__
882 type_name = lambda v: type(v).__name__
883 varlist = map(get_vars,varnames)
883 varlist = map(get_vars,varnames)
884 typelist = map(type_name,varlist)
884 typelist = map(type_name,varlist)
885 # column labels and # of spaces as separator
885 # column labels and # of spaces as separator
886 varlabel = 'Variable'
886 varlabel = 'Variable'
887 typelabel = 'Type'
887 typelabel = 'Type'
888 datalabel = 'Data/Info'
888 datalabel = 'Data/Info'
889 colsep = 3
889 colsep = 3
890 # variable format strings
890 # variable format strings
891 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
891 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
892 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
892 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
893 aformat = "%s: %s elems, type `%s`, %s bytes"
893 aformat = "%s: %s elems, type `%s`, %s bytes"
894 # find the size of the columns to format the output nicely
894 # find the size of the columns to format the output nicely
895 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
895 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
896 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
896 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
897 # table header
897 # table header
898 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
898 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
899 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
899 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
900 # and the table itself
900 # and the table itself
901 kb = 1024
901 kb = 1024
902 Mb = 1048576 # kb**2
902 Mb = 1048576 # kb**2
903 for vname,var,vtype in zip(varnames,varlist,typelist):
903 for vname,var,vtype in zip(varnames,varlist,typelist):
904 print itpl(vformat),
904 print itpl(vformat),
905 if vtype in seq_types:
905 if vtype in seq_types:
906 print len(var)
906 print len(var)
907 elif vtype==array_type:
907 elif vtype==array_type:
908 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
908 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
909 vsize = Numeric.size(var)
909 vsize = Numeric.size(var)
910 vbytes = vsize*var.itemsize()
910 vbytes = vsize*var.itemsize()
911 if vbytes < 100000:
911 if vbytes < 100000:
912 print aformat % (vshape,vsize,var.typecode(),vbytes)
912 print aformat % (vshape,vsize,var.typecode(),vbytes)
913 else:
913 else:
914 print aformat % (vshape,vsize,var.typecode(),vbytes),
914 print aformat % (vshape,vsize,var.typecode(),vbytes),
915 if vbytes < Mb:
915 if vbytes < Mb:
916 print '(%s kb)' % (vbytes/kb,)
916 print '(%s kb)' % (vbytes/kb,)
917 else:
917 else:
918 print '(%s Mb)' % (vbytes/Mb,)
918 print '(%s Mb)' % (vbytes/Mb,)
919 else:
919 else:
920 vstr = str(var)
920 vstr = str(var)
921 if len(vstr) < 50:
921 if len(vstr) < 50:
922 print vstr
922 print vstr
923 else:
923 else:
924 printpl(vfmt_short)
924 printpl(vfmt_short)
925
925
926 def magic_reset(self, parameter_s=''):
926 def magic_reset(self, parameter_s=''):
927 """Resets the namespace by removing all names defined by the user.
927 """Resets the namespace by removing all names defined by the user.
928
928
929 Input/Output history are left around in case you need them."""
929 Input/Output history are left around in case you need them."""
930
930
931 ans = raw_input(
931 ans = raw_input(
932 "Once deleted, variables cannot be recovered. Proceed (y/n)? ")
932 "Once deleted, variables cannot be recovered. Proceed (y/n)? ")
933 if not ans.lower() == 'y':
933 if not ans.lower() == 'y':
934 print 'Nothing done.'
934 print 'Nothing done.'
935 return
935 return
936 user_ns = self.shell.user_ns
936 user_ns = self.shell.user_ns
937 for i in self.magic_who_ls():
937 for i in self.magic_who_ls():
938 del(user_ns[i])
938 del(user_ns[i])
939
939
940 def magic_config(self,parameter_s=''):
940 def magic_config(self,parameter_s=''):
941 """Show IPython's internal configuration."""
941 """Show IPython's internal configuration."""
942
942
943 page('Current configuration structure:\n'+
943 page('Current configuration structure:\n'+
944 pformat(self.shell.rc.dict()))
944 pformat(self.shell.rc.dict()))
945
945
946 def magic_logstart(self,parameter_s=''):
946 def magic_logstart(self,parameter_s=''):
947 """Start logging anywhere in a session.
947 """Start logging anywhere in a session.
948
948
949 %logstart [log_name [log_mode]]
949 %logstart [log_name [log_mode]]
950
950
951 If no name is given, it defaults to a file named 'ipython.log' in your
951 If no name is given, it defaults to a file named 'ipython.log' in your
952 current directory, in 'rotate' mode (see below).
952 current directory, in 'rotate' mode (see below).
953
953
954 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
954 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
955 history up to that point and then continues logging.
955 history up to that point and then continues logging.
956
956
957 %logstart takes a second optional parameter: logging mode. This can be one
957 %logstart takes a second optional parameter: logging mode. This can be one
958 of (note that the modes are given unquoted):\\
958 of (note that the modes are given unquoted):\\
959 over: overwrite existing log.\\
959 over: overwrite existing log.\\
960 backup: rename (if exists) to name~ and start name.\\
960 backup: rename (if exists) to name~ and start name.\\
961 append: well, that says it.\\
961 append: well, that says it.\\
962 rotate: create rotating logs name.1~, name.2~, etc.
962 rotate: create rotating logs name.1~, name.2~, etc.
963 """
963 """
964
964
965 #FIXME. This function should all be moved to the Logger class.
965 #FIXME. This function should all be moved to the Logger class.
966
966
967 valid_modes = qw('over backup append rotate')
967 valid_modes = qw('over backup append rotate')
968 if self.LOG:
968 if self.LOG:
969 print 'Logging is already in place. Logfile:',self.LOG
969 print 'Logging is already in place. Logfile:',self.LOG
970 return
970 return
971
971
972 par = parameter_s.strip()
972 par = parameter_s.strip()
973 if not par:
973 if not par:
974 logname = self.LOGDEF
974 logname = self.LOGDEF
975 logmode = 'rotate' # use rotate for the auto-generated logs
975 logmode = 'rotate' # use rotate for the auto-generated logs
976 else:
976 else:
977 try:
977 try:
978 logname,logmode = par.split()
978 logname,logmode = par.split()
979 except:
979 except:
980 try:
980 try:
981 logname = par
981 logname = par
982 logmode = 'backup'
982 logmode = 'backup'
983 except:
983 except:
984 warn('Usage: %log [log_name [log_mode]]')
984 warn('Usage: %log [log_name [log_mode]]')
985 return
985 return
986 if not logmode in valid_modes:
986 if not logmode in valid_modes:
987 warn('Logging NOT activated.\n'
987 warn('Logging NOT activated.\n'
988 'Usage: %log [log_name [log_mode]]\n'
988 'Usage: %log [log_name [log_mode]]\n'
989 'Valid modes: '+str(valid_modes))
989 'Valid modes: '+str(valid_modes))
990 return
990 return
991
991
992 # If we made it this far, I think we're ok:
992 # If we made it this far, I think we're ok:
993 print 'Activating auto-logging.'
993 print 'Activating auto-logging.'
994 print 'Current session state plus future input saved to:',logname
994 print 'Current session state plus future input saved to:',logname
995 print 'Logging mode: ',logmode
995 print 'Logging mode: ',logmode
996 # put logname into rc struct as if it had been called on the command line,
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
997 # so it ends up saved in the log header
998 # Save it in case we need to restore it...
998 # Save it in case we need to restore it...
999 old_logfile = self.shell.rc.opts.get('logfile','')
999 old_logfile = self.shell.rc.opts.get('logfile','')
1000 logname = os.path.expanduser(logname)
1000 logname = os.path.expanduser(logname)
1001 self.shell.rc.opts.logfile = logname
1001 self.shell.rc.opts.logfile = logname
1002 self.LOGMODE = logmode # FIXME: this should be set through a function.
1002 self.LOGMODE = logmode # FIXME: this should be set through a function.
1003 try:
1003 try:
1004 header = str(self.LOGHEAD)
1004 header = str(self.LOGHEAD)
1005 self.create_log(header,logname)
1005 self.create_log(header,logname)
1006 self.logstart(header,logname)
1006 self.logstart(header,logname)
1007 except:
1007 except:
1008 self.LOG = '' # we are NOT logging, something went wrong
1008 self.LOG = '' # we are NOT logging, something went wrong
1009 self.shell.rc.opts.logfile = old_logfile
1009 self.shell.rc.opts.logfile = old_logfile
1010 warn("Couldn't start log: "+str(sys.exc_info()[1]))
1010 warn("Couldn't start log: "+str(sys.exc_info()[1]))
1011 else: # log input history up to this point
1011 else: # log input history up to this point
1012 self.logfile.write(self.shell.user_ns['_ih'][1:])
1012 self.logfile.write(self.shell.user_ns['_ih'][1:])
1013 self.logfile.flush()
1013 self.logfile.flush()
1014
1014
1015 def magic_logoff(self,parameter_s=''):
1015 def magic_logoff(self,parameter_s=''):
1016 """Temporarily stop logging.
1016 """Temporarily stop logging.
1017
1017
1018 You must have previously started logging."""
1018 You must have previously started logging."""
1019 self.switch_log(0)
1019 self.switch_log(0)
1020
1020
1021 def magic_logon(self,parameter_s=''):
1021 def magic_logon(self,parameter_s=''):
1022 """Restart logging.
1022 """Restart logging.
1023
1023
1024 This function is for restarting logging which you've temporarily
1024 This function is for restarting logging which you've temporarily
1025 stopped with %logoff. For starting logging for the first time, you
1025 stopped with %logoff. For starting logging for the first time, you
1026 must use the %logstart function, which allows you to specify an
1026 must use the %logstart function, which allows you to specify an
1027 optional log filename."""
1027 optional log filename."""
1028
1028
1029 self.switch_log(1)
1029 self.switch_log(1)
1030
1030
1031 def magic_logstate(self,parameter_s=''):
1031 def magic_logstate(self,parameter_s=''):
1032 """Print the status of the logging system."""
1032 """Print the status of the logging system."""
1033
1033
1034 self.logstate()
1034 self.logstate()
1035
1035
1036 def magic_pdb(self, parameter_s=''):
1036 def magic_pdb(self, parameter_s=''):
1037 """Control the calling of the pdb interactive debugger.
1037 """Control the calling of the pdb interactive debugger.
1038
1038
1039 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1039 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1040 argument it works as a toggle.
1040 argument it works as a toggle.
1041
1041
1042 When an exception is triggered, IPython can optionally call the
1042 When an exception is triggered, IPython can optionally call the
1043 interactive pdb debugger after the traceback printout. %pdb toggles
1043 interactive pdb debugger after the traceback printout. %pdb toggles
1044 this feature on and off."""
1044 this feature on and off."""
1045
1045
1046 par = parameter_s.strip().lower()
1046 par = parameter_s.strip().lower()
1047
1047
1048 if par:
1048 if par:
1049 try:
1049 try:
1050 pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1050 pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1051 except KeyError:
1051 except KeyError:
1052 print 'Incorrect argument. Use on/1, off/0 or nothing for a toggle.'
1052 print 'Incorrect argument. Use on/1, off/0 or nothing for a toggle.'
1053 return
1053 return
1054 else:
1054 else:
1055 self.shell.InteractiveTB.call_pdb = pdb
1055 self.shell.InteractiveTB.call_pdb = pdb
1056 else:
1056 else:
1057 self.shell.InteractiveTB.call_pdb = 1 - self.shell.InteractiveTB.call_pdb
1057 self.shell.InteractiveTB.call_pdb = 1 - self.shell.InteractiveTB.call_pdb
1058 print 'Automatic pdb calling has been turned',\
1058 print 'Automatic pdb calling has been turned',\
1059 on_off(self.shell.InteractiveTB.call_pdb)
1059 on_off(self.shell.InteractiveTB.call_pdb)
1060
1060
1061
1061
1062 def magic_prun(self, parameter_s ='',user_mode=1,
1062 def magic_prun(self, parameter_s ='',user_mode=1,
1063 opts=None,arg_lst=None,prog_ns=None):
1063 opts=None,arg_lst=None,prog_ns=None):
1064
1064
1065 """Run a statement through the python code profiler.
1065 """Run a statement through the python code profiler.
1066
1066
1067 Usage:\\
1067 Usage:\\
1068 %prun [options] statement
1068 %prun [options] statement
1069
1069
1070 The given statement (which doesn't require quote marks) is run via the
1070 The given statement (which doesn't require quote marks) is run via the
1071 python profiler in a manner similar to the profile.run() function.
1071 python profiler in a manner similar to the profile.run() function.
1072 Namespaces are internally managed to work correctly; profile.run
1072 Namespaces are internally managed to work correctly; profile.run
1073 cannot be used in IPython because it makes certain assumptions about
1073 cannot be used in IPython because it makes certain assumptions about
1074 namespaces which do not hold under IPython.
1074 namespaces which do not hold under IPython.
1075
1075
1076 Options:
1076 Options:
1077
1077
1078 -l <limit>: you can place restrictions on what or how much of the
1078 -l <limit>: you can place restrictions on what or how much of the
1079 profile gets printed. The limit value can be:
1079 profile gets printed. The limit value can be:
1080
1080
1081 * A string: only information for function names containing this string
1081 * A string: only information for function names containing this string
1082 is printed.
1082 is printed.
1083
1083
1084 * An integer: only these many lines are printed.
1084 * An integer: only these many lines are printed.
1085
1085
1086 * A float (between 0 and 1): this fraction of the report is printed
1086 * A float (between 0 and 1): this fraction of the report is printed
1087 (for example, use a limit of 0.4 to see the topmost 40% only).
1087 (for example, use a limit of 0.4 to see the topmost 40% only).
1088
1088
1089 You can combine several limits with repeated use of the option. For
1089 You can combine several limits with repeated use of the option. For
1090 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1090 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1091 information about class constructors.
1091 information about class constructors.
1092
1092
1093 -r: return the pstats.Stats object generated by the profiling. This
1093 -r: return the pstats.Stats object generated by the profiling. This
1094 object has all the information about the profile in it, and you can
1094 object has all the information about the profile in it, and you can
1095 later use it for further analysis or in other functions.
1095 later use it for further analysis or in other functions.
1096
1096
1097 Since magic functions have a particular form of calling which prevents
1097 Since magic functions have a particular form of calling which prevents
1098 you from writing something like:\\
1098 you from writing something like:\\
1099 In [1]: p = %prun -r print 4 # invalid!\\
1099 In [1]: p = %prun -r print 4 # invalid!\\
1100 you must instead use IPython's automatic variables to assign this:\\
1100 you must instead use IPython's automatic variables to assign this:\\
1101 In [1]: %prun -r print 4 \\
1101 In [1]: %prun -r print 4 \\
1102 Out[1]: <pstats.Stats instance at 0x8222cec>\\
1102 Out[1]: <pstats.Stats instance at 0x8222cec>\\
1103 In [2]: stats = _
1103 In [2]: stats = _
1104
1104
1105 If you really need to assign this value via an explicit function call,
1105 If you really need to assign this value via an explicit function call,
1106 you can always tap directly into the true name of the magic function
1106 you can always tap directly into the true name of the magic function
1107 by using the ipmagic function (which IPython automatically adds to the
1107 by using the ipmagic function (which IPython automatically adds to the
1108 builtins):\\
1108 builtins):\\
1109 In [3]: stats = ipmagic('prun','-r print 4')
1109 In [3]: stats = ipmagic('prun','-r print 4')
1110
1110
1111 You can type ipmagic? for more details on ipmagic.
1111 You can type ipmagic? for more details on ipmagic.
1112
1112
1113 -s <key>: sort profile by given key. You can provide more than one key
1113 -s <key>: sort profile by given key. You can provide more than one key
1114 by using the option several times: '-s key1 -s key2 -s key3...'. The
1114 by using the option several times: '-s key1 -s key2 -s key3...'. The
1115 default sorting key is 'time'.
1115 default sorting key is 'time'.
1116
1116
1117 The following is copied verbatim from the profile documentation
1117 The following is copied verbatim from the profile documentation
1118 referenced below:
1118 referenced below:
1119
1119
1120 When more than one key is provided, additional keys are used as
1120 When more than one key is provided, additional keys are used as
1121 secondary criteria when the there is equality in all keys selected
1121 secondary criteria when the there is equality in all keys selected
1122 before them.
1122 before them.
1123
1123
1124 Abbreviations can be used for any key names, as long as the
1124 Abbreviations can be used for any key names, as long as the
1125 abbreviation is unambiguous. The following are the keys currently
1125 abbreviation is unambiguous. The following are the keys currently
1126 defined:
1126 defined:
1127
1127
1128 Valid Arg Meaning\\
1128 Valid Arg Meaning\\
1129 "calls" call count\\
1129 "calls" call count\\
1130 "cumulative" cumulative time\\
1130 "cumulative" cumulative time\\
1131 "file" file name\\
1131 "file" file name\\
1132 "module" file name\\
1132 "module" file name\\
1133 "pcalls" primitive call count\\
1133 "pcalls" primitive call count\\
1134 "line" line number\\
1134 "line" line number\\
1135 "name" function name\\
1135 "name" function name\\
1136 "nfl" name/file/line\\
1136 "nfl" name/file/line\\
1137 "stdname" standard name\\
1137 "stdname" standard name\\
1138 "time" internal time
1138 "time" internal time
1139
1139
1140 Note that all sorts on statistics are in descending order (placing
1140 Note that all sorts on statistics are in descending order (placing
1141 most time consuming items first), where as name, file, and line number
1141 most time consuming items first), where as name, file, and line number
1142 searches are in ascending order (i.e., alphabetical). The subtle
1142 searches are in ascending order (i.e., alphabetical). The subtle
1143 distinction between "nfl" and "stdname" is that the standard name is a
1143 distinction between "nfl" and "stdname" is that the standard name is a
1144 sort of the name as printed, which means that the embedded line
1144 sort of the name as printed, which means that the embedded line
1145 numbers get compared in an odd way. For example, lines 3, 20, and 40
1145 numbers get compared in an odd way. For example, lines 3, 20, and 40
1146 would (if the file names were the same) appear in the string order
1146 would (if the file names were the same) appear in the string order
1147 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1147 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1148 line numbers. In fact, sort_stats("nfl") is the same as
1148 line numbers. In fact, sort_stats("nfl") is the same as
1149 sort_stats("name", "file", "line").
1149 sort_stats("name", "file", "line").
1150
1150
1151 -T <filename>: save profile results as shown on screen to a text
1151 -T <filename>: save profile results as shown on screen to a text
1152 file. The profile is still shown on screen.
1152 file. The profile is still shown on screen.
1153
1153
1154 -D <filename>: save (via dump_stats) profile statistics to given
1154 -D <filename>: save (via dump_stats) profile statistics to given
1155 filename. This data is in a format understod by the pstats module, and
1155 filename. This data is in a format understod by the pstats module, and
1156 is generated by a call to the dump_stats() method of profile
1156 is generated by a call to the dump_stats() method of profile
1157 objects. The profile is still shown on screen.
1157 objects. The profile is still shown on screen.
1158
1158
1159 If you want to run complete programs under the profiler's control, use
1159 If you want to run complete programs under the profiler's control, use
1160 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1160 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1161 contains profiler specific options as described here.
1161 contains profiler specific options as described here.
1162
1162
1163 You can read the complete documentation for the profile module with:\\
1163 You can read the complete documentation for the profile module with:\\
1164 In [1]: import profile; profile.help() """
1164 In [1]: import profile; profile.help() """
1165
1165
1166 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1166 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1167 # protect user quote marks
1167 # protect user quote marks
1168 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1168 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1169
1169
1170 if user_mode: # regular user call
1170 if user_mode: # regular user call
1171 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1171 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1172 list_all=1)
1172 list_all=1)
1173 namespace = self.shell.user_ns
1173 namespace = self.shell.user_ns
1174 else: # called to run a program by %run -p
1174 else: # called to run a program by %run -p
1175 try:
1175 try:
1176 filename = get_py_filename(arg_lst[0])
1176 filename = get_py_filename(arg_lst[0])
1177 except IOError,msg:
1177 except IOError,msg:
1178 error(msg)
1178 error(msg)
1179 return
1179 return
1180
1180
1181 arg_str = 'execfile(filename,prog_ns)'
1181 arg_str = 'execfile(filename,prog_ns)'
1182 namespace = locals()
1182 namespace = locals()
1183
1183
1184 opts.merge(opts_def)
1184 opts.merge(opts_def)
1185
1185
1186 prof = profile.Profile()
1186 prof = profile.Profile()
1187 try:
1187 try:
1188 prof = prof.runctx(arg_str,namespace,namespace)
1188 prof = prof.runctx(arg_str,namespace,namespace)
1189 sys_exit = ''
1189 sys_exit = ''
1190 except SystemExit:
1190 except SystemExit:
1191 sys_exit = """*** SystemExit exception caught in code being profiled."""
1191 sys_exit = """*** SystemExit exception caught in code being profiled."""
1192
1192
1193 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1193 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1194
1194
1195 lims = opts.l
1195 lims = opts.l
1196 if lims:
1196 if lims:
1197 lims = [] # rebuild lims with ints/floats/strings
1197 lims = [] # rebuild lims with ints/floats/strings
1198 for lim in opts.l:
1198 for lim in opts.l:
1199 try:
1199 try:
1200 lims.append(int(lim))
1200 lims.append(int(lim))
1201 except ValueError:
1201 except ValueError:
1202 try:
1202 try:
1203 lims.append(float(lim))
1203 lims.append(float(lim))
1204 except ValueError:
1204 except ValueError:
1205 lims.append(lim)
1205 lims.append(lim)
1206
1206
1207 # trap output
1207 # trap output
1208 sys_stdout = sys.stdout
1208 sys_stdout = sys.stdout
1209 stdout_trap = StringIO()
1209 stdout_trap = StringIO()
1210 try:
1210 try:
1211 sys.stdout = stdout_trap
1211 sys.stdout = stdout_trap
1212 stats.print_stats(*lims)
1212 stats.print_stats(*lims)
1213 finally:
1213 finally:
1214 sys.stdout = sys_stdout
1214 sys.stdout = sys_stdout
1215 output = stdout_trap.getvalue()
1215 output = stdout_trap.getvalue()
1216 output = output.rstrip()
1216 output = output.rstrip()
1217
1217
1218 page(output,screen_lines=self.shell.rc.screen_length)
1218 page(output,screen_lines=self.shell.rc.screen_length)
1219 print sys_exit,
1219 print sys_exit,
1220
1220
1221 dump_file = opts.D[0]
1221 dump_file = opts.D[0]
1222 text_file = opts.T[0]
1222 text_file = opts.T[0]
1223 if dump_file:
1223 if dump_file:
1224 prof.dump_stats(dump_file)
1224 prof.dump_stats(dump_file)
1225 print '\n*** Profile stats marshalled to file',\
1225 print '\n*** Profile stats marshalled to file',\
1226 `dump_file`+'.',sys_exit
1226 `dump_file`+'.',sys_exit
1227 if text_file:
1227 if text_file:
1228 file(text_file,'w').write(output)
1228 file(text_file,'w').write(output)
1229 print '\n*** Profile printout saved to text file',\
1229 print '\n*** Profile printout saved to text file',\
1230 `text_file`+'.',sys_exit
1230 `text_file`+'.',sys_exit
1231
1231
1232 if opts.has_key('r'):
1232 if opts.has_key('r'):
1233 return stats
1233 return stats
1234 else:
1234 else:
1235 return None
1235 return None
1236
1236
1237 def magic_run(self, parameter_s ='',runner=None):
1237 def magic_run(self, parameter_s ='',runner=None):
1238 """Run the named file inside IPython as a program.
1238 """Run the named file inside IPython as a program.
1239
1239
1240 Usage:\\
1240 Usage:\\
1241 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1241 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1242
1242
1243 Parameters after the filename are passed as command-line arguments to
1243 Parameters after the filename are passed as command-line arguments to
1244 the program (put in sys.argv). Then, control returns to IPython's
1244 the program (put in sys.argv). Then, control returns to IPython's
1245 prompt.
1245 prompt.
1246
1246
1247 This is similar to running at a system prompt:\\
1247 This is similar to running at a system prompt:\\
1248 $ python file args\\
1248 $ python file args\\
1249 but with the advantage of giving you IPython's tracebacks, and of
1249 but with the advantage of giving you IPython's tracebacks, and of
1250 loading all variables into your interactive namespace for further use
1250 loading all variables into your interactive namespace for further use
1251 (unless -p is used, see below).
1251 (unless -p is used, see below).
1252
1252
1253 The file is executed in a namespace initially consisting only of
1253 The file is executed in a namespace initially consisting only of
1254 __name__=='__main__' and sys.argv constructed as indicated. It thus
1254 __name__=='__main__' and sys.argv constructed as indicated. It thus
1255 sees its environment as if it were being run as a stand-alone
1255 sees its environment as if it were being run as a stand-alone
1256 program. But after execution, the IPython interactive namespace gets
1256 program. But after execution, the IPython interactive namespace gets
1257 updated with all variables defined in the program (except for __name__
1257 updated with all variables defined in the program (except for __name__
1258 and sys.argv). This allows for very convenient loading of code for
1258 and sys.argv). This allows for very convenient loading of code for
1259 interactive work, while giving each program a 'clean sheet' to run in.
1259 interactive work, while giving each program a 'clean sheet' to run in.
1260
1260
1261 Options:
1261 Options:
1262
1262
1263 -n: __name__ is NOT set to '__main__', but to the running file's name
1263 -n: __name__ is NOT set to '__main__', but to the running file's name
1264 without extension (as python does under import). This allows running
1264 without extension (as python does under import). This allows running
1265 scripts and reloading the definitions in them without calling code
1265 scripts and reloading the definitions in them without calling code
1266 protected by an ' if __name__ == "__main__" ' clause.
1266 protected by an ' if __name__ == "__main__" ' clause.
1267
1267
1268 -i: run the file in IPython's namespace instead of an empty one. This
1268 -i: run the file in IPython's namespace instead of an empty one. This
1269 is useful if you are experimenting with code written in a text editor
1269 is useful if you are experimenting with code written in a text editor
1270 which depends on variables defined interactively.
1270 which depends on variables defined interactively.
1271
1271
1272 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1272 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1273 being run. This is particularly useful if IPython is being used to
1273 being run. This is particularly useful if IPython is being used to
1274 run unittests, which always exit with a sys.exit() call. In such
1274 run unittests, which always exit with a sys.exit() call. In such
1275 cases you are interested in the output of the test results, not in
1275 cases you are interested in the output of the test results, not in
1276 seeing a traceback of the unittest module.
1276 seeing a traceback of the unittest module.
1277
1277
1278 -t: print timing information at the end of the run. IPython will give
1278 -t: print timing information at the end of the run. IPython will give
1279 you an estimated CPU time consumption for your script, which under
1279 you an estimated CPU time consumption for your script, which under
1280 Unix uses the resource module to avoid the wraparound problems of
1280 Unix uses the resource module to avoid the wraparound problems of
1281 time.clock(). Under Unix, an estimate of time spent on system tasks
1281 time.clock(). Under Unix, an estimate of time spent on system tasks
1282 is also given (for Windows platforms this is reported as 0.0).
1282 is also given (for Windows platforms this is reported as 0.0).
1283
1283
1284 If -t is given, an additional -N<N> option can be given, where <N>
1284 If -t is given, an additional -N<N> option can be given, where <N>
1285 must be an integer indicating how many times you want the script to
1285 must be an integer indicating how many times you want the script to
1286 run. The final timing report will include total and per run results.
1286 run. The final timing report will include total and per run results.
1287
1287
1288 For example (testing the script uniq_stable.py):
1288 For example (testing the script uniq_stable.py):
1289
1289
1290 In [1]: run -t uniq_stable
1290 In [1]: run -t uniq_stable
1291
1291
1292 IPython CPU timings (estimated):\\
1292 IPython CPU timings (estimated):\\
1293 User : 0.19597 s.\\
1293 User : 0.19597 s.\\
1294 System: 0.0 s.\\
1294 System: 0.0 s.\\
1295
1295
1296 In [2]: run -t -N5 uniq_stable
1296 In [2]: run -t -N5 uniq_stable
1297
1297
1298 IPython CPU timings (estimated):\\
1298 IPython CPU timings (estimated):\\
1299 Total runs performed: 5\\
1299 Total runs performed: 5\\
1300 Times : Total Per run\\
1300 Times : Total Per run\\
1301 User : 0.910862 s, 0.1821724 s.\\
1301 User : 0.910862 s, 0.1821724 s.\\
1302 System: 0.0 s, 0.0 s.
1302 System: 0.0 s, 0.0 s.
1303
1303
1304 -d: run your program under the control of pdb, the Python debugger.
1304 -d: run your program under the control of pdb, the Python debugger.
1305 This allows you to execute your program step by step, watch variables,
1305 This allows you to execute your program step by step, watch variables,
1306 etc. Internally, what IPython does is similar to calling:
1306 etc. Internally, what IPython does is similar to calling:
1307
1307
1308 pdb.run('execfile("YOURFILENAME")')
1308 pdb.run('execfile("YOURFILENAME")')
1309
1309
1310 with a breakpoint set on line 1 of your file. You can change the line
1310 with a breakpoint set on line 1 of your file. You can change the line
1311 number for this automatic breakpoint to be <N> by using the -bN option
1311 number for this automatic breakpoint to be <N> by using the -bN option
1312 (where N must be an integer). For example:
1312 (where N must be an integer). For example:
1313
1313
1314 %run -d -b40 myscript
1314 %run -d -b40 myscript
1315
1315
1316 will set the first breakpoint at line 40 in myscript.py. Note that
1316 will set the first breakpoint at line 40 in myscript.py. Note that
1317 the first breakpoint must be set on a line which actually does
1317 the first breakpoint must be set on a line which actually does
1318 something (not a comment or docstring) for it to stop execution.
1318 something (not a comment or docstring) for it to stop execution.
1319
1319
1320 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1320 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1321 first enter 'c' (without qoutes) to start execution up to the first
1321 first enter 'c' (without qoutes) to start execution up to the first
1322 breakpoint.
1322 breakpoint.
1323
1323
1324 Entering 'help' gives information about the use of the debugger. You
1324 Entering 'help' gives information about the use of the debugger. You
1325 can easily see pdb's full documentation with "import pdb;pdb.help()"
1325 can easily see pdb's full documentation with "import pdb;pdb.help()"
1326 at a prompt.
1326 at a prompt.
1327
1327
1328 -p: run program under the control of the Python profiler module (which
1328 -p: run program under the control of the Python profiler module (which
1329 prints a detailed report of execution times, function calls, etc).
1329 prints a detailed report of execution times, function calls, etc).
1330
1330
1331 You can pass other options after -p which affect the behavior of the
1331 You can pass other options after -p which affect the behavior of the
1332 profiler itself. See the docs for %prun for details.
1332 profiler itself. See the docs for %prun for details.
1333
1333
1334 In this mode, the program's variables do NOT propagate back to the
1334 In this mode, the program's variables do NOT propagate back to the
1335 IPython interactive namespace (because they remain in the namespace
1335 IPython interactive namespace (because they remain in the namespace
1336 where the profiler executes them).
1336 where the profiler executes them).
1337
1337
1338 Internally this triggers a call to %prun, see its documentation for
1338 Internally this triggers a call to %prun, see its documentation for
1339 details on the options available specifically for profiling."""
1339 details on the options available specifically for profiling."""
1340
1340
1341 # get arguments and set sys.argv for program to be run.
1341 # get arguments and set sys.argv for program to be run.
1342 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1342 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1343 mode='list',list_all=1)
1343 mode='list',list_all=1)
1344
1344
1345 try:
1345 try:
1346 filename = get_py_filename(arg_lst[0])
1346 filename = get_py_filename(arg_lst[0])
1347 except IndexError:
1347 except IndexError:
1348 warn('you must provide at least a filename.')
1348 warn('you must provide at least a filename.')
1349 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1349 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1350 return
1350 return
1351 except IOError,msg:
1351 except IOError,msg:
1352 error(msg)
1352 error(msg)
1353 return
1353 return
1354
1354
1355 # Control the response to exit() calls made by the script being run
1355 # Control the response to exit() calls made by the script being run
1356 exit_ignore = opts.has_key('e')
1356 exit_ignore = opts.has_key('e')
1357
1357
1358 # Make sure that the running script gets a proper sys.argv as if it
1358 # Make sure that the running script gets a proper sys.argv as if it
1359 # were run from a system shell.
1359 # were run from a system shell.
1360 save_argv = sys.argv # save it for later restoring
1360 save_argv = sys.argv # save it for later restoring
1361 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1361 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1362
1362
1363 if opts.has_key('i'):
1363 if opts.has_key('i'):
1364 prog_ns = self.shell.user_ns
1364 prog_ns = self.shell.user_ns
1365 __name__save = self.shell.user_ns['__name__']
1365 __name__save = self.shell.user_ns['__name__']
1366 prog_ns['__name__'] = '__main__'
1366 prog_ns['__name__'] = '__main__'
1367 else:
1367 else:
1368 if opts.has_key('n'):
1368 if opts.has_key('n'):
1369 name = os.path.splitext(os.path.basename(filename))[0]
1369 name = os.path.splitext(os.path.basename(filename))[0]
1370 else:
1370 else:
1371 name = '__main__'
1371 name = '__main__'
1372 prog_ns = {'__name__':name}
1372 prog_ns = {'__name__':name}
1373
1373
1374 # pickle fix. See iplib for an explanation
1374 # pickle fix. See iplib for an explanation
1375 sys.modules[prog_ns['__name__']] = FakeModule(prog_ns)
1375 sys.modules[prog_ns['__name__']] = FakeModule(prog_ns)
1376
1376
1377 stats = None
1377 stats = None
1378 try:
1378 try:
1379 if opts.has_key('p'):
1379 if opts.has_key('p'):
1380 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1380 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1381 else:
1381 else:
1382 if opts.has_key('d'):
1382 if opts.has_key('d'):
1383 deb = Debugger.Pdb(self.shell.rc.colors)
1383 deb = Debugger.Pdb(self.shell.rc.colors)
1384 # reset Breakpoint state, which is moronically kept
1384 # reset Breakpoint state, which is moronically kept
1385 # in a class
1385 # in a class
1386 bdb.Breakpoint.next = 1
1386 bdb.Breakpoint.next = 1
1387 bdb.Breakpoint.bplist = {}
1387 bdb.Breakpoint.bplist = {}
1388 bdb.Breakpoint.bpbynumber = [None]
1388 bdb.Breakpoint.bpbynumber = [None]
1389 # Set an initial breakpoint to stop execution
1389 # Set an initial breakpoint to stop execution
1390 maxtries = 10
1390 maxtries = 10
1391 bp = int(opts.get('b',[1])[0])
1391 bp = int(opts.get('b',[1])[0])
1392 checkline = deb.checkline(filename,bp)
1392 checkline = deb.checkline(filename,bp)
1393 if not checkline:
1393 if not checkline:
1394 for bp in range(bp+1,bp+maxtries+1):
1394 for bp in range(bp+1,bp+maxtries+1):
1395 if deb.checkline(filename,bp):
1395 if deb.checkline(filename,bp):
1396 break
1396 break
1397 else:
1397 else:
1398 msg = ("\nI failed to find a valid line to set "
1398 msg = ("\nI failed to find a valid line to set "
1399 "a breakpoint\n"
1399 "a breakpoint\n"
1400 "after trying up to line: %s.\n"
1400 "after trying up to line: %s.\n"
1401 "Please set a valid breakpoint manually "
1401 "Please set a valid breakpoint manually "
1402 "with the -b option." % bp)
1402 "with the -b option." % bp)
1403 error(msg)
1403 error(msg)
1404 return
1404 return
1405 # if we find a good linenumber, set the breakpoint
1405 # if we find a good linenumber, set the breakpoint
1406 deb.do_break('%s:%s' % (filename,bp))
1406 deb.do_break('%s:%s' % (filename,bp))
1407 # Start file run
1407 # Start file run
1408 print "NOTE: Enter 'c' at the",
1408 print "NOTE: Enter 'c' at the",
1409 print "ipdb> prompt to start your script."
1409 print "ipdb> prompt to start your script."
1410 try:
1410 try:
1411 deb.run('execfile("%s")' % filename,prog_ns)
1411 deb.run('execfile("%s")' % filename,prog_ns)
1412 except:
1412 except:
1413 etype, value, tb = sys.exc_info()
1413 etype, value, tb = sys.exc_info()
1414 # Skip three frames in the traceback: the %run one,
1414 # Skip three frames in the traceback: the %run one,
1415 # one inside bdb.py, and the command-line typed by the
1415 # one inside bdb.py, and the command-line typed by the
1416 # user (run by exec in pdb itself).
1416 # user (run by exec in pdb itself).
1417 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1417 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1418 else:
1418 else:
1419 if runner is None:
1419 if runner is None:
1420 runner = self.shell.safe_execfile
1420 runner = self.shell.safe_execfile
1421 if opts.has_key('t'):
1421 if opts.has_key('t'):
1422 try:
1422 try:
1423 nruns = int(opts['N'][0])
1423 nruns = int(opts['N'][0])
1424 if nruns < 1:
1424 if nruns < 1:
1425 error('Number of runs must be >=1')
1425 error('Number of runs must be >=1')
1426 return
1426 return
1427 except (KeyError):
1427 except (KeyError):
1428 nruns = 1
1428 nruns = 1
1429 if nruns == 1:
1429 if nruns == 1:
1430 t0 = clock2()
1430 t0 = clock2()
1431 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1431 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1432 t1 = clock2()
1432 t1 = clock2()
1433 t_usr = t1[0]-t0[0]
1433 t_usr = t1[0]-t0[0]
1434 t_sys = t1[1]-t1[1]
1434 t_sys = t1[1]-t1[1]
1435 print "\nIPython CPU timings (estimated):"
1435 print "\nIPython CPU timings (estimated):"
1436 print " User : %10s s." % t_usr
1436 print " User : %10s s." % t_usr
1437 print " System: %10s s." % t_sys
1437 print " System: %10s s." % t_sys
1438 else:
1438 else:
1439 runs = range(nruns)
1439 runs = range(nruns)
1440 t0 = clock2()
1440 t0 = clock2()
1441 for nr in runs:
1441 for nr in runs:
1442 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1442 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1443 t1 = clock2()
1443 t1 = clock2()
1444 t_usr = t1[0]-t0[0]
1444 t_usr = t1[0]-t0[0]
1445 t_sys = t1[1]-t1[1]
1445 t_sys = t1[1]-t1[1]
1446 print "\nIPython CPU timings (estimated):"
1446 print "\nIPython CPU timings (estimated):"
1447 print "Total runs performed:",nruns
1447 print "Total runs performed:",nruns
1448 print " Times : %10s %10s" % ('Total','Per run')
1448 print " Times : %10s %10s" % ('Total','Per run')
1449 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1449 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1450 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1450 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1451
1451
1452 else:
1452 else:
1453 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1453 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1454 if opts.has_key('i'):
1454 if opts.has_key('i'):
1455 self.shell.user_ns['__name__'] = __name__save
1455 self.shell.user_ns['__name__'] = __name__save
1456 else:
1456 else:
1457 # update IPython interactive namespace
1457 # update IPython interactive namespace
1458 del prog_ns['__name__']
1458 del prog_ns['__name__']
1459 self.shell.user_ns.update(prog_ns)
1459 self.shell.user_ns.update(prog_ns)
1460 finally:
1460 finally:
1461 sys.argv = save_argv
1461 sys.argv = save_argv
1462 return stats
1462 return stats
1463
1463
1464 def magic_runlog(self, parameter_s =''):
1464 def magic_runlog(self, parameter_s =''):
1465 """Run files as logs.
1465 """Run files as logs.
1466
1466
1467 Usage:\\
1467 Usage:\\
1468 %runlog file1 file2 ...
1468 %runlog file1 file2 ...
1469
1469
1470 Run the named files (treating them as log files) in sequence inside
1470 Run the named files (treating them as log files) in sequence inside
1471 the interpreter, and return to the prompt. This is much slower than
1471 the interpreter, and return to the prompt. This is much slower than
1472 %run because each line is executed in a try/except block, but it
1472 %run because each line is executed in a try/except block, but it
1473 allows running files with syntax errors in them.
1473 allows running files with syntax errors in them.
1474
1474
1475 Normally IPython will guess when a file is one of its own logfiles, so
1475 Normally IPython will guess when a file is one of its own logfiles, so
1476 you can typically use %run even for logs. This shorthand allows you to
1476 you can typically use %run even for logs. This shorthand allows you to
1477 force any file to be treated as a log file."""
1477 force any file to be treated as a log file."""
1478
1478
1479 for f in parameter_s.split():
1479 for f in parameter_s.split():
1480 self.shell.safe_execfile(f,self.shell.user_ns,
1480 self.shell.safe_execfile(f,self.shell.user_ns,
1481 self.shell.user_ns,islog=1)
1481 self.shell.user_ns,islog=1)
1482
1482
1483 def magic_time(self,parameter_s = ''):
1483 def magic_time(self,parameter_s = ''):
1484 """Time execution of a Python statement or expression.
1484 """Time execution of a Python statement or expression.
1485
1485
1486 The CPU and wall clock times are printed, and the value of the
1486 The CPU and wall clock times are printed, and the value of the
1487 expression (if any) is returned. Note that under Win32, system time
1487 expression (if any) is returned. Note that under Win32, system time
1488 is always reported as 0, since it can not be measured.
1488 is always reported as 0, since it can not be measured.
1489
1489
1490 This function provides very basic timing functionality. In Python
1490 This function provides very basic timing functionality. In Python
1491 2.3, the timeit module offers more control and sophistication, but for
1491 2.3, the timeit module offers more control and sophistication, but for
1492 now IPython supports Python 2.2, so we can not rely on timeit being
1492 now IPython supports Python 2.2, so we can not rely on timeit being
1493 present.
1493 present.
1494
1494
1495 Some examples:
1495 Some examples:
1496
1496
1497 In [1]: time 2**128
1497 In [1]: time 2**128
1498 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1498 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1499 Wall time: 0.00
1499 Wall time: 0.00
1500 Out[1]: 340282366920938463463374607431768211456L
1500 Out[1]: 340282366920938463463374607431768211456L
1501
1501
1502 In [2]: n = 1000000
1502 In [2]: n = 1000000
1503
1503
1504 In [3]: time sum(range(n))
1504 In [3]: time sum(range(n))
1505 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1505 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1506 Wall time: 1.37
1506 Wall time: 1.37
1507 Out[3]: 499999500000L
1507 Out[3]: 499999500000L
1508
1508
1509 In [4]: time print 'hello world'
1509 In [4]: time print 'hello world'
1510 hello world
1510 hello world
1511 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1511 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1512 Wall time: 0.00
1512 Wall time: 0.00
1513 """
1513 """
1514
1514
1515 # fail immediately if the given expression can't be compiled
1515 # fail immediately if the given expression can't be compiled
1516 try:
1516 try:
1517 mode = 'eval'
1517 mode = 'eval'
1518 code = compile(parameter_s,'<timed eval>',mode)
1518 code = compile(parameter_s,'<timed eval>',mode)
1519 except SyntaxError:
1519 except SyntaxError:
1520 mode = 'exec'
1520 mode = 'exec'
1521 code = compile(parameter_s,'<timed exec>',mode)
1521 code = compile(parameter_s,'<timed exec>',mode)
1522 # skew measurement as little as possible
1522 # skew measurement as little as possible
1523 glob = self.shell.user_ns
1523 glob = self.shell.user_ns
1524 clk = clock2
1524 clk = clock2
1525 wtime = time.time
1525 wtime = time.time
1526 # time execution
1526 # time execution
1527 wall_st = wtime()
1527 wall_st = wtime()
1528 if mode=='eval':
1528 if mode=='eval':
1529 st = clk()
1529 st = clk()
1530 out = eval(code,glob)
1530 out = eval(code,glob)
1531 end = clk()
1531 end = clk()
1532 else:
1532 else:
1533 st = clk()
1533 st = clk()
1534 exec code in glob
1534 exec code in glob
1535 end = clk()
1535 end = clk()
1536 out = None
1536 out = None
1537 wall_end = wtime()
1537 wall_end = wtime()
1538 # Compute actual times and report
1538 # Compute actual times and report
1539 wall_time = wall_end-wall_st
1539 wall_time = wall_end-wall_st
1540 cpu_user = end[0]-st[0]
1540 cpu_user = end[0]-st[0]
1541 cpu_sys = end[1]-st[1]
1541 cpu_sys = end[1]-st[1]
1542 cpu_tot = cpu_user+cpu_sys
1542 cpu_tot = cpu_user+cpu_sys
1543 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1543 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1544 (cpu_user,cpu_sys,cpu_tot)
1544 (cpu_user,cpu_sys,cpu_tot)
1545 print "Wall time: %.2f" % wall_time
1545 print "Wall time: %.2f" % wall_time
1546 return out
1546 return out
1547
1547
1548 def magic_macro(self,parameter_s = ''):
1548 def magic_macro(self,parameter_s = ''):
1549 """Define a set of input lines as a macro for future re-execution.
1549 """Define a set of input lines as a macro for future re-execution.
1550
1550
1551 Usage:\\
1551 Usage:\\
1552 %macro name n1:n2 n3:n4 ... n5 .. n6 ...
1552 %macro name n1:n2 n3:n4 ... n5 .. n6 ...
1553
1553
1554 This will define a global variable called `name` which is a string
1554 This will define a global variable called `name` which is a string
1555 made of joining the slices and lines you specify (n1,n2,... numbers
1555 made of joining the slices and lines you specify (n1,n2,... numbers
1556 above) from your input history into a single string. This variable
1556 above) from your input history into a single string. This variable
1557 acts like an automatic function which re-executes those lines as if
1557 acts like an automatic function which re-executes those lines as if
1558 you had typed them. You just type 'name' at the prompt and the code
1558 you had typed them. You just type 'name' at the prompt and the code
1559 executes.
1559 executes.
1560
1560
1561 Note that the slices use the standard Python slicing notation (5:8
1561 Note that the slices use the standard Python slicing notation (5:8
1562 means include lines numbered 5,6,7).
1562 means include lines numbered 5,6,7).
1563
1563
1564 For example, if your history contains (%hist prints it):
1564 For example, if your history contains (%hist prints it):
1565
1565
1566 44: x=1\\
1566 44: x=1\\
1567 45: y=3\\
1567 45: y=3\\
1568 46: z=x+y\\
1568 46: z=x+y\\
1569 47: print x\\
1569 47: print x\\
1570 48: a=5\\
1570 48: a=5\\
1571 49: print 'x',x,'y',y\\
1571 49: print 'x',x,'y',y\\
1572
1572
1573 you can create a macro with lines 44 through 47 (included) and line 49
1573 you can create a macro with lines 44 through 47 (included) and line 49
1574 called my_macro with:
1574 called my_macro with:
1575
1575
1576 In [51]: %macro my_macro 44:48 49
1576 In [51]: %macro my_macro 44:48 49
1577
1577
1578 Now, typing `my_macro` (without quotes) will re-execute all this code
1578 Now, typing `my_macro` (without quotes) will re-execute all this code
1579 in one pass.
1579 in one pass.
1580
1580
1581 You don't need to give the line-numbers in order, and any given line
1581 You don't need to give the line-numbers in order, and any given line
1582 number can appear multiple times. You can assemble macros with any
1582 number can appear multiple times. You can assemble macros with any
1583 lines from your input history in any order.
1583 lines from your input history in any order.
1584
1584
1585 The macro is a simple object which holds its value in an attribute,
1585 The macro is a simple object which holds its value in an attribute,
1586 but IPython's display system checks for macros and executes them as
1586 but IPython's display system checks for macros and executes them as
1587 code instead of printing them when you type their name.
1587 code instead of printing them when you type their name.
1588
1588
1589 You can view a macro's contents by explicitly printing it with:
1589 You can view a macro's contents by explicitly printing it with:
1590
1590
1591 'print macro_name'.
1591 'print macro_name'.
1592
1592
1593 For one-off cases which DON'T contain magic function calls in them you
1593 For one-off cases which DON'T contain magic function calls in them you
1594 can obtain similar results by explicitly executing slices from your
1594 can obtain similar results by explicitly executing slices from your
1595 input history with:
1595 input history with:
1596
1596
1597 In [60]: exec In[44:48]+In[49]"""
1597 In [60]: exec In[44:48]+In[49]"""
1598
1598
1599 args = parameter_s.split()
1599 args = parameter_s.split()
1600 name,ranges = args[0], args[1:]
1600 name,ranges = args[0], args[1:]
1601 #print 'rng',ranges # dbg
1601 #print 'rng',ranges # dbg
1602 cmds = self.extract_input_slices(ranges)
1602 cmds = self.extract_input_slices(ranges)
1603 macro = Macro(cmds)
1603 macro = Macro(cmds)
1604 self.shell.user_ns.update({name:macro})
1604 self.shell.user_ns.update({name:macro})
1605 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1605 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1606 print 'Macro contents:'
1606 print 'Macro contents:'
1607 print str(macro).rstrip(),
1607 print str(macro).rstrip(),
1608
1608
1609 def magic_save(self,parameter_s = ''):
1609 def magic_save(self,parameter_s = ''):
1610 """Save a set of lines to a given filename.
1610 """Save a set of lines to a given filename.
1611
1611
1612 Usage:\\
1612 Usage:\\
1613 %save filename n1:n2 n3:n4 ... n5 .. n6 ...
1613 %save filename n1:n2 n3:n4 ... n5 .. n6 ...
1614
1614
1615 This function uses the same syntax as %macro for line extraction, but
1615 This function uses the same syntax as %macro for line extraction, but
1616 instead of creating a macro it saves the resulting string to the
1616 instead of creating a macro it saves the resulting string to the
1617 filename you specify.
1617 filename you specify.
1618
1618
1619 It adds a '.py' extension to the file if you don't do so yourself, and
1619 It adds a '.py' extension to the file if you don't do so yourself, and
1620 it asks for confirmation before overwriting existing files."""
1620 it asks for confirmation before overwriting existing files."""
1621
1621
1622 args = parameter_s.split()
1622 args = parameter_s.split()
1623 fname,ranges = args[0], args[1:]
1623 fname,ranges = args[0], args[1:]
1624 if not fname.endswith('.py'):
1624 if not fname.endswith('.py'):
1625 fname += '.py'
1625 fname += '.py'
1626 if os.path.isfile(fname):
1626 if os.path.isfile(fname):
1627 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1627 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1628 if ans.lower() not in ['y','yes']:
1628 if ans.lower() not in ['y','yes']:
1629 print 'Operation cancelled.'
1629 print 'Operation cancelled.'
1630 return
1630 return
1631 cmds = ''.join(self.extract_input_slices(ranges))
1631 cmds = ''.join(self.extract_input_slices(ranges))
1632 f = file(fname,'w')
1632 f = file(fname,'w')
1633 f.write(cmds)
1633 f.write(cmds)
1634 f.close()
1634 f.close()
1635 print 'The following commands were written to file `%s`:' % fname
1635 print 'The following commands were written to file `%s`:' % fname
1636 print cmds
1636 print cmds
1637
1637
1638 def magic_ed(self,parameter_s = ''):
1638 def magic_ed(self,parameter_s = ''):
1639 """Alias to %edit."""
1639 """Alias to %edit."""
1640 return self.magic_edit(parameter_s)
1640 return self.magic_edit(parameter_s)
1641
1641
1642 def magic_edit(self,parameter_s = '',last_call=['','']):
1642 def magic_edit(self,parameter_s = '',last_call=['','']):
1643 """Bring up an editor and execute the resulting code.
1643 """Bring up an editor and execute the resulting code.
1644
1644
1645 Usage:
1645 Usage:
1646 %edit [options] [args]
1646 %edit [options] [args]
1647
1647
1648 %edit runs IPython's editor hook. The default version of this hook is
1648 %edit runs IPython's editor hook. The default version of this hook is
1649 set to call the __IPYTHON__.rc.editor command. This is read from your
1649 set to call the __IPYTHON__.rc.editor command. This is read from your
1650 environment variable $EDITOR. If this isn't found, it will default to
1650 environment variable $EDITOR. If this isn't found, it will default to
1651 vi under Linux/Unix and to notepad under Windows. See the end of this
1651 vi under Linux/Unix and to notepad under Windows. See the end of this
1652 docstring for how to change the editor hook.
1652 docstring for how to change the editor hook.
1653
1653
1654 You can also set the value of this editor via the command line option
1654 You can also set the value of this editor via the command line option
1655 '-editor' or in your ipythonrc file. This is useful if you wish to use
1655 '-editor' or in your ipythonrc file. This is useful if you wish to use
1656 specifically for IPython an editor different from your typical default
1656 specifically for IPython an editor different from your typical default
1657 (and for Windows users who typically don't set environment variables).
1657 (and for Windows users who typically don't set environment variables).
1658
1658
1659 This command allows you to conveniently edit multi-line code right in
1659 This command allows you to conveniently edit multi-line code right in
1660 your IPython session.
1660 your IPython session.
1661
1661
1662 If called without arguments, %edit opens up an empty editor with a
1662 If called without arguments, %edit opens up an empty editor with a
1663 temporary file and will execute the contents of this file when you
1663 temporary file and will execute the contents of this file when you
1664 close it (don't forget to save it!).
1664 close it (don't forget to save it!).
1665
1665
1666 Options:
1666 Options:
1667
1667
1668 -p: this will call the editor with the same data as the previous time
1668 -p: this will call the editor with the same data as the previous time
1669 it was used, regardless of how long ago (in your current session) it
1669 it was used, regardless of how long ago (in your current session) it
1670 was.
1670 was.
1671
1671
1672 -x: do not execute the edited code immediately upon exit. This is
1672 -x: do not execute the edited code immediately upon exit. This is
1673 mainly useful if you are editing programs which need to be called with
1673 mainly useful if you are editing programs which need to be called with
1674 command line arguments, which you can then do using %run.
1674 command line arguments, which you can then do using %run.
1675
1675
1676 Arguments:
1676 Arguments:
1677
1677
1678 If arguments are given, the following possibilites exist:
1678 If arguments are given, the following possibilites exist:
1679
1679
1680 - The arguments are numbers or pairs of colon-separated numbers (like
1680 - The arguments are numbers or pairs of colon-separated numbers (like
1681 1 4:8 9). These are interpreted as lines of previous input to be
1681 1 4:8 9). These are interpreted as lines of previous input to be
1682 loaded into the editor. The syntax is the same of the %macro command.
1682 loaded into the editor. The syntax is the same of the %macro command.
1683
1683
1684 - If the argument doesn't start with a number, it is evaluated as a
1684 - If the argument doesn't start with a number, it is evaluated as a
1685 variable and its contents loaded into the editor. You can thus edit
1685 variable and its contents loaded into the editor. You can thus edit
1686 any string which contains python code (including the result of
1686 any string which contains python code (including the result of
1687 previous edits).
1687 previous edits).
1688
1688
1689 - If the argument is the name of an object (other than a string),
1689 - If the argument is the name of an object (other than a string),
1690 IPython will try to locate the file where it was defined and open the
1690 IPython will try to locate the file where it was defined and open the
1691 editor at the point where it is defined. You can use `%edit function`
1691 editor at the point where it is defined. You can use `%edit function`
1692 to load an editor exactly at the point where 'function' is defined,
1692 to load an editor exactly at the point where 'function' is defined,
1693 edit it and have the file be executed automatically.
1693 edit it and have the file be executed automatically.
1694
1694
1695 Note: opening at an exact line is only supported under Unix, and some
1695 Note: opening at an exact line is only supported under Unix, and some
1696 editors (like kedit and gedit up to Gnome 2.8) do not understand the
1696 editors (like kedit and gedit up to Gnome 2.8) do not understand the
1697 '+NUMBER' parameter necessary for this feature. Good editors like
1697 '+NUMBER' parameter necessary for this feature. Good editors like
1698 (X)Emacs, vi, jed, pico and joe all do.
1698 (X)Emacs, vi, jed, pico and joe all do.
1699
1699
1700 - If the argument is not found as a variable, IPython will look for a
1700 - If the argument is not found as a variable, IPython will look for a
1701 file with that name (adding .py if necessary) and load it into the
1701 file with that name (adding .py if necessary) and load it into the
1702 editor. It will execute its contents with execfile() when you exit,
1702 editor. It will execute its contents with execfile() when you exit,
1703 loading any code in the file into your interactive namespace.
1703 loading any code in the file into your interactive namespace.
1704
1704
1705 After executing your code, %edit will return as output the code you
1705 After executing your code, %edit will return as output the code you
1706 typed in the editor (except when it was an existing file). This way
1706 typed in the editor (except when it was an existing file). This way
1707 you can reload the code in further invocations of %edit as a variable,
1707 you can reload the code in further invocations of %edit as a variable,
1708 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
1708 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
1709 the output.
1709 the output.
1710
1710
1711 Note that %edit is also available through the alias %ed.
1711 Note that %edit is also available through the alias %ed.
1712
1712
1713 This is an example of creating a simple function inside the editor and
1713 This is an example of creating a simple function inside the editor and
1714 then modifying it. First, start up the editor:
1714 then modifying it. First, start up the editor:
1715
1715
1716 In [1]: ed\\
1716 In [1]: ed\\
1717 Editing... done. Executing edited code...\\
1717 Editing... done. Executing edited code...\\
1718 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
1718 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
1719
1719
1720 We can then call the function foo():
1720 We can then call the function foo():
1721
1721
1722 In [2]: foo()\\
1722 In [2]: foo()\\
1723 foo() was defined in an editing session
1723 foo() was defined in an editing session
1724
1724
1725 Now we edit foo. IPython automatically loads the editor with the
1725 Now we edit foo. IPython automatically loads the editor with the
1726 (temporary) file where foo() was previously defined:
1726 (temporary) file where foo() was previously defined:
1727
1727
1728 In [3]: ed foo\\
1728 In [3]: ed foo\\
1729 Editing... done. Executing edited code...
1729 Editing... done. Executing edited code...
1730
1730
1731 And if we call foo() again we get the modified version:
1731 And if we call foo() again we get the modified version:
1732
1732
1733 In [4]: foo()\\
1733 In [4]: foo()\\
1734 foo() has now been changed!
1734 foo() has now been changed!
1735
1735
1736 Here is an example of how to edit a code snippet successive
1736 Here is an example of how to edit a code snippet successive
1737 times. First we call the editor:
1737 times. First we call the editor:
1738
1738
1739 In [8]: ed\\
1739 In [8]: ed\\
1740 Editing... done. Executing edited code...\\
1740 Editing... done. Executing edited code...\\
1741 hello\\
1741 hello\\
1742 Out[8]: "print 'hello'\\n"
1742 Out[8]: "print 'hello'\\n"
1743
1743
1744 Now we call it again with the previous output (stored in _):
1744 Now we call it again with the previous output (stored in _):
1745
1745
1746 In [9]: ed _\\
1746 In [9]: ed _\\
1747 Editing... done. Executing edited code...\\
1747 Editing... done. Executing edited code...\\
1748 hello world\\
1748 hello world\\
1749 Out[9]: "print 'hello world'\\n"
1749 Out[9]: "print 'hello world'\\n"
1750
1750
1751 Now we call it with the output #8 (stored in _8, also as Out[8]):
1751 Now we call it with the output #8 (stored in _8, also as Out[8]):
1752
1752
1753 In [10]: ed _8\\
1753 In [10]: ed _8\\
1754 Editing... done. Executing edited code...\\
1754 Editing... done. Executing edited code...\\
1755 hello again\\
1755 hello again\\
1756 Out[10]: "print 'hello again'\\n"
1756 Out[10]: "print 'hello again'\\n"
1757
1757
1758
1758
1759 Changing the default editor hook:
1759 Changing the default editor hook:
1760
1760
1761 If you wish to write your own editor hook, you can put it in a
1761 If you wish to write your own editor hook, you can put it in a
1762 configuration file which you load at startup time. The default hook
1762 configuration file which you load at startup time. The default hook
1763 is defined in the IPython.hooks module, and you can use that as a
1763 is defined in the IPython.hooks module, and you can use that as a
1764 starting example for further modifications. That file also has
1764 starting example for further modifications. That file also has
1765 general instructions on how to set a new hook for use once you've
1765 general instructions on how to set a new hook for use once you've
1766 defined it."""
1766 defined it."""
1767
1767
1768 # FIXME: This function has become a convoluted mess. It needs a
1768 # FIXME: This function has become a convoluted mess. It needs a
1769 # ground-up rewrite with clean, simple logic.
1769 # ground-up rewrite with clean, simple logic.
1770
1770
1771 def make_filename(arg):
1771 def make_filename(arg):
1772 "Make a filename from the given args"
1772 "Make a filename from the given args"
1773 try:
1773 try:
1774 filename = get_py_filename(arg)
1774 filename = get_py_filename(arg)
1775 except IOError:
1775 except IOError:
1776 if args.endswith('.py'):
1776 if args.endswith('.py'):
1777 filename = arg
1777 filename = arg
1778 else:
1778 else:
1779 filename = None
1779 filename = None
1780 return filename
1780 return filename
1781
1781
1782 # custom exceptions
1782 # custom exceptions
1783 class DataIsObject(Exception): pass
1783 class DataIsObject(Exception): pass
1784
1784
1785 opts,args = self.parse_options(parameter_s,'px')
1785 opts,args = self.parse_options(parameter_s,'px')
1786
1786
1787 # Default line number value
1787 # Default line number value
1788 lineno = None
1788 lineno = None
1789 if opts.has_key('p'):
1789 if opts.has_key('p'):
1790 args = '_%s' % last_call[0]
1790 args = '_%s' % last_call[0]
1791 if not self.shell.user_ns.has_key(args):
1791 if not self.shell.user_ns.has_key(args):
1792 args = last_call[1]
1792 args = last_call[1]
1793
1793
1794 # use last_call to remember the state of the previous call, but don't
1794 # use last_call to remember the state of the previous call, but don't
1795 # let it be clobbered by successive '-p' calls.
1795 # let it be clobbered by successive '-p' calls.
1796 try:
1796 try:
1797 last_call[0] = self.shell.outputcache.prompt_count
1797 last_call[0] = self.shell.outputcache.prompt_count
1798 if not opts.has_key('p'):
1798 if not opts.has_key('p'):
1799 last_call[1] = parameter_s
1799 last_call[1] = parameter_s
1800 except:
1800 except:
1801 pass
1801 pass
1802
1802
1803 # by default this is done with temp files, except when the given
1803 # by default this is done with temp files, except when the given
1804 # arg is a filename
1804 # arg is a filename
1805 use_temp = 1
1805 use_temp = 1
1806
1806
1807 if re.match(r'\d',args):
1807 if re.match(r'\d',args):
1808 # Mode where user specifies ranges of lines, like in %macro.
1808 # Mode where user specifies ranges of lines, like in %macro.
1809 # This means that you can't edit files whose names begin with
1809 # This means that you can't edit files whose names begin with
1810 # numbers this way. Tough.
1810 # numbers this way. Tough.
1811 ranges = args.split()
1811 ranges = args.split()
1812 data = ''.join(self.extract_input_slices(ranges))
1812 data = ''.join(self.extract_input_slices(ranges))
1813 elif args.endswith('.py'):
1813 elif args.endswith('.py'):
1814 filename = make_filename(args)
1814 filename = make_filename(args)
1815 data = ''
1815 data = ''
1816 use_temp = 0
1816 use_temp = 0
1817 elif args:
1817 elif args:
1818 try:
1818 try:
1819 # Load the parameter given as a variable. If not a string,
1819 # Load the parameter given as a variable. If not a string,
1820 # process it as an object instead (below)
1820 # process it as an object instead (below)
1821
1821
1822 #print '*** args',args,'type',type(args) # dbg
1822 #print '*** args',args,'type',type(args) # dbg
1823 data = eval(args,self.shell.user_ns)
1823 data = eval(args,self.shell.user_ns)
1824 if not type(data) in StringTypes:
1824 if not type(data) in StringTypes:
1825 raise DataIsObject
1825 raise DataIsObject
1826 except (NameError,SyntaxError):
1826 except (NameError,SyntaxError):
1827 # given argument is not a variable, try as a filename
1827 # given argument is not a variable, try as a filename
1828 filename = make_filename(args)
1828 filename = make_filename(args)
1829 if filename is None:
1829 if filename is None:
1830 warn("Argument given (%s) can't be found as a variable "
1830 warn("Argument given (%s) can't be found as a variable "
1831 "or as a filename." % args)
1831 "or as a filename." % args)
1832 return
1832 return
1833 data = ''
1833 data = ''
1834 use_temp = 0
1834 use_temp = 0
1835 except DataIsObject:
1835 except DataIsObject:
1836 # For objects, try to edit the file where they are defined
1836 # For objects, try to edit the file where they are defined
1837 try:
1837 try:
1838 filename = inspect.getabsfile(data)
1838 filename = inspect.getabsfile(data)
1839 datafile = 1
1839 datafile = 1
1840 except TypeError:
1840 except TypeError:
1841 filename = make_filename(args)
1841 filename = make_filename(args)
1842 datafile = 1
1842 datafile = 1
1843 warn('Could not find file where `%s` is defined.\n'
1843 warn('Could not find file where `%s` is defined.\n'
1844 'Opening a file named `%s`' % (args,filename))
1844 'Opening a file named `%s`' % (args,filename))
1845 # Now, make sure we can actually read the source (if it was in
1845 # Now, make sure we can actually read the source (if it was in
1846 # a temp file it's gone by now).
1846 # a temp file it's gone by now).
1847 if datafile:
1847 if datafile:
1848 try:
1848 try:
1849 lineno = inspect.getsourcelines(data)[1]
1849 lineno = inspect.getsourcelines(data)[1]
1850 except IOError:
1850 except IOError:
1851 filename = make_filename(args)
1851 filename = make_filename(args)
1852 if filename is None:
1852 if filename is None:
1853 warn('The file `%s` where `%s` was defined cannot '
1853 warn('The file `%s` where `%s` was defined cannot '
1854 'be read.' % (filename,data))
1854 'be read.' % (filename,data))
1855 return
1855 return
1856 use_temp = 0
1856 use_temp = 0
1857 else:
1857 else:
1858 data = ''
1858 data = ''
1859
1859
1860 if use_temp:
1860 if use_temp:
1861 filename = tempfile.mktemp('.py')
1861 filename = tempfile.mktemp('.py')
1862 self.shell.tempfiles.append(filename)
1862 self.shell.tempfiles.append(filename)
1863
1863
1864 if data and use_temp:
1864 if data and use_temp:
1865 tmp_file = open(filename,'w')
1865 tmp_file = open(filename,'w')
1866 tmp_file.write(data)
1866 tmp_file.write(data)
1867 tmp_file.close()
1867 tmp_file.close()
1868
1868
1869 # do actual editing here
1869 # do actual editing here
1870 print 'Editing...',
1870 print 'Editing...',
1871 sys.stdout.flush()
1871 sys.stdout.flush()
1872 self.shell.hooks.editor(filename,lineno)
1872 self.shell.hooks.editor(filename,lineno)
1873 if opts.has_key('x'): # -x prevents actual execution
1873 if opts.has_key('x'): # -x prevents actual execution
1874 print
1874 print
1875 else:
1875 else:
1876 print 'done. Executing edited code...'
1876 print 'done. Executing edited code...'
1877 try:
1877 try:
1878 execfile(filename,self.shell.user_ns)
1878 self.shell.safe_execfile(filename,self.shell.user_ns)
1879 except IOError,msg:
1879 except IOError,msg:
1880 if msg.filename == filename:
1880 if msg.filename == filename:
1881 warn('File not found. Did you forget to save?')
1881 warn('File not found. Did you forget to save?')
1882 return
1882 return
1883 else:
1883 else:
1884 self.shell.showtraceback()
1884 self.shell.showtraceback()
1885 except:
1885 except:
1886 self.shell.showtraceback()
1886 self.shell.showtraceback()
1887 if use_temp:
1887 if use_temp:
1888 contents = open(filename).read()
1888 contents = open(filename).read()
1889 return contents
1889 return contents
1890
1890
1891 def magic_xmode(self,parameter_s = ''):
1891 def magic_xmode(self,parameter_s = ''):
1892 """Switch modes for the exception handlers.
1892 """Switch modes for the exception handlers.
1893
1893
1894 Valid modes: Plain, Context and Verbose.
1894 Valid modes: Plain, Context and Verbose.
1895
1895
1896 If called without arguments, acts as a toggle."""
1896 If called without arguments, acts as a toggle."""
1897
1897
1898 new_mode = parameter_s.strip().capitalize()
1898 new_mode = parameter_s.strip().capitalize()
1899 try:
1899 try:
1900 self.InteractiveTB.set_mode(mode = new_mode)
1900 self.InteractiveTB.set_mode(mode = new_mode)
1901 print 'Exception reporting mode:',self.InteractiveTB.mode
1901 print 'Exception reporting mode:',self.InteractiveTB.mode
1902 except:
1902 except:
1903 warn('Error changing exception modes.\n' + str(sys.exc_info()[1]))
1903 warn('Error changing exception modes.\n' + str(sys.exc_info()[1]))
1904
1904
1905 def magic_colors(self,parameter_s = ''):
1905 def magic_colors(self,parameter_s = ''):
1906 """Switch color scheme for prompts, info system and exception handlers.
1906 """Switch color scheme for prompts, info system and exception handlers.
1907
1907
1908 Currently implemented schemes: NoColor, Linux, LightBG.
1908 Currently implemented schemes: NoColor, Linux, LightBG.
1909
1909
1910 Color scheme names are not case-sensitive."""
1910 Color scheme names are not case-sensitive."""
1911
1911
1912 new_scheme = parameter_s.strip()
1912 new_scheme = parameter_s.strip()
1913 if not new_scheme:
1913 if not new_scheme:
1914 print 'You must specify a color scheme.'
1914 print 'You must specify a color scheme.'
1915 return
1915 return
1916 # Under Windows, check for Gary Bishop's readline, which is necessary
1916 # Under Windows, check for Gary Bishop's readline, which is necessary
1917 # for ANSI coloring
1917 # for ANSI coloring
1918 if os.name in ['nt','dos']:
1918 if os.name in ['nt','dos']:
1919 try:
1919 try:
1920 import readline
1920 import readline
1921 except ImportError:
1921 except ImportError:
1922 has_readline = 0
1922 has_readline = 0
1923 else:
1923 else:
1924 try:
1924 try:
1925 readline.GetOutputFile()
1925 readline.GetOutputFile()
1926 except AttributeError:
1926 except AttributeError:
1927 has_readline = 0
1927 has_readline = 0
1928 else:
1928 else:
1929 has_readline = 1
1929 has_readline = 1
1930 if not has_readline:
1930 if not has_readline:
1931 msg = """\
1931 msg = """\
1932 Proper color support under MS Windows requires Gary Bishop's readline library.
1932 Proper color support under MS Windows requires Gary Bishop's readline library.
1933 You can find it at:
1933 You can find it at:
1934 http://sourceforge.net/projects/uncpythontools
1934 http://sourceforge.net/projects/uncpythontools
1935 Gary's readline needs the ctypes module, from:
1935 Gary's readline needs the ctypes module, from:
1936 http://starship.python.net/crew/theller/ctypes
1936 http://starship.python.net/crew/theller/ctypes
1937
1937
1938 Defaulting color scheme to 'NoColor'"""
1938 Defaulting color scheme to 'NoColor'"""
1939 new_scheme = 'NoColor'
1939 new_scheme = 'NoColor'
1940 warn(msg)
1940 warn(msg)
1941
1941
1942 # Set prompt colors
1942 # Set prompt colors
1943 try:
1943 try:
1944 self.shell.outputcache.set_colors(new_scheme)
1944 self.shell.outputcache.set_colors(new_scheme)
1945 except:
1945 except:
1946 warn('Error changing prompt color schemes.\n'
1946 warn('Error changing prompt color schemes.\n'
1947 + str(sys.exc_info()[1]))
1947 + str(sys.exc_info()[1]))
1948 else:
1948 else:
1949 self.shell.rc.colors = \
1949 self.shell.rc.colors = \
1950 self.shell.outputcache.color_table.active_scheme_name
1950 self.shell.outputcache.color_table.active_scheme_name
1951 # Set exception colors
1951 # Set exception colors
1952 try:
1952 try:
1953 self.shell.InteractiveTB.set_colors(scheme = new_scheme)
1953 self.shell.InteractiveTB.set_colors(scheme = new_scheme)
1954 self.shell.SyntaxTB.set_colors(scheme = new_scheme)
1954 self.shell.SyntaxTB.set_colors(scheme = new_scheme)
1955 except:
1955 except:
1956 warn('Error changing exception color schemes.\n'
1956 warn('Error changing exception color schemes.\n'
1957 + str(sys.exc_info()[1]))
1957 + str(sys.exc_info()[1]))
1958 # Set info (for 'object?') colors
1958 # Set info (for 'object?') colors
1959 if self.shell.rc.color_info:
1959 if self.shell.rc.color_info:
1960 try:
1960 try:
1961 self.shell.inspector.set_active_scheme(new_scheme)
1961 self.shell.inspector.set_active_scheme(new_scheme)
1962 except:
1962 except:
1963 warn('Error changing object inspector color schemes.\n'
1963 warn('Error changing object inspector color schemes.\n'
1964 + str(sys.exc_info()[1]))
1964 + str(sys.exc_info()[1]))
1965 else:
1965 else:
1966 self.shell.inspector.set_active_scheme('NoColor')
1966 self.shell.inspector.set_active_scheme('NoColor')
1967
1967
1968 def magic_color_info(self,parameter_s = ''):
1968 def magic_color_info(self,parameter_s = ''):
1969 """Toggle color_info.
1969 """Toggle color_info.
1970
1970
1971 The color_info configuration parameter controls whether colors are
1971 The color_info configuration parameter controls whether colors are
1972 used for displaying object details (by things like %psource, %pfile or
1972 used for displaying object details (by things like %psource, %pfile or
1973 the '?' system). This function toggles this value with each call.
1973 the '?' system). This function toggles this value with each call.
1974
1974
1975 Note that unless you have a fairly recent pager (less works better
1975 Note that unless you have a fairly recent pager (less works better
1976 than more) in your system, using colored object information displays
1976 than more) in your system, using colored object information displays
1977 will not work properly. Test it and see."""
1977 will not work properly. Test it and see."""
1978
1978
1979 self.shell.rc.color_info = 1 - self.shell.rc.color_info
1979 self.shell.rc.color_info = 1 - self.shell.rc.color_info
1980 self.magic_colors(self.shell.rc.colors)
1980 self.magic_colors(self.shell.rc.colors)
1981 print 'Object introspection functions have now coloring:',
1981 print 'Object introspection functions have now coloring:',
1982 print ['OFF','ON'][self.shell.rc.color_info]
1982 print ['OFF','ON'][self.shell.rc.color_info]
1983
1983
1984 def magic_Pprint(self, parameter_s=''):
1984 def magic_Pprint(self, parameter_s=''):
1985 """Toggle pretty printing on/off."""
1985 """Toggle pretty printing on/off."""
1986
1986
1987 self.shell.outputcache.Pprint = 1 - self.shell.outputcache.Pprint
1987 self.shell.outputcache.Pprint = 1 - self.shell.outputcache.Pprint
1988 print 'Pretty printing has been turned', \
1988 print 'Pretty printing has been turned', \
1989 ['OFF','ON'][self.shell.outputcache.Pprint]
1989 ['OFF','ON'][self.shell.outputcache.Pprint]
1990
1990
1991 def magic_Exit(self, parameter_s=''):
1991 def magic_Exit(self, parameter_s=''):
1992 """Exit IPython without confirmation."""
1992 """Exit IPython without confirmation."""
1993
1993
1994 self.shell.exit_now = True
1994 self.shell.exit_now = True
1995
1995
1996 def magic_Quit(self, parameter_s=''):
1996 def magic_Quit(self, parameter_s=''):
1997 """Exit IPython without confirmation (like %Exit)."""
1997 """Exit IPython without confirmation (like %Exit)."""
1998
1998
1999 self.shell.exit_now = True
1999 self.shell.exit_now = True
2000
2000
2001 #......................................................................
2001 #......................................................................
2002 # Functions to implement unix shell-type things
2002 # Functions to implement unix shell-type things
2003
2003
2004 def magic_alias(self, parameter_s = ''):
2004 def magic_alias(self, parameter_s = ''):
2005 """Define an alias for a system command.
2005 """Define an alias for a system command.
2006
2006
2007 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2007 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2008
2008
2009 Then, typing 'alias_name params' will execute the system command 'cmd
2009 Then, typing 'alias_name params' will execute the system command 'cmd
2010 params' (from your underlying operating system).
2010 params' (from your underlying operating system).
2011
2011
2012 Aliases have lower precedence than magic functions and Python normal
2012 Aliases have lower precedence than magic functions and Python normal
2013 variables, so if 'foo' is both a Python variable and an alias, the
2013 variables, so if 'foo' is both a Python variable and an alias, the
2014 alias can not be executed until 'del foo' removes the Python variable.
2014 alias can not be executed until 'del foo' removes the Python variable.
2015
2015
2016 You can use the %l specifier in an alias definition to represent the
2016 You can use the %l specifier in an alias definition to represent the
2017 whole line when the alias is called. For example:
2017 whole line when the alias is called. For example:
2018
2018
2019 In [2]: alias all echo "Input in brackets: <%l>"\\
2019 In [2]: alias all echo "Input in brackets: <%l>"\\
2020 In [3]: all hello world\\
2020 In [3]: all hello world\\
2021 Input in brackets: <hello world>
2021 Input in brackets: <hello world>
2022
2022
2023 You can also define aliases with parameters using %s specifiers (one
2023 You can also define aliases with parameters using %s specifiers (one
2024 per parameter):
2024 per parameter):
2025
2025
2026 In [1]: alias parts echo first %s second %s\\
2026 In [1]: alias parts echo first %s second %s\\
2027 In [2]: %parts A B\\
2027 In [2]: %parts A B\\
2028 first A second B\\
2028 first A second B\\
2029 In [3]: %parts A\\
2029 In [3]: %parts A\\
2030 Incorrect number of arguments: 2 expected.\\
2030 Incorrect number of arguments: 2 expected.\\
2031 parts is an alias to: 'echo first %s second %s'
2031 parts is an alias to: 'echo first %s second %s'
2032
2032
2033 Note that %l and %s are mutually exclusive. You can only use one or
2033 Note that %l and %s are mutually exclusive. You can only use one or
2034 the other in your aliases.
2034 the other in your aliases.
2035
2035
2036 Aliases expand Python variables just like system calls using ! or !!
2036 Aliases expand Python variables just like system calls using ! or !!
2037 do: all expressions prefixed with '$' get expanded. For details of
2037 do: all expressions prefixed with '$' get expanded. For details of
2038 the semantic rules, see PEP-215:
2038 the semantic rules, see PEP-215:
2039 http://www.python.org/peps/pep-0215.html. This is the library used by
2039 http://www.python.org/peps/pep-0215.html. This is the library used by
2040 IPython for variable expansion. If you want to access a true shell
2040 IPython for variable expansion. If you want to access a true shell
2041 variable, an extra $ is necessary to prevent its expansion by IPython:
2041 variable, an extra $ is necessary to prevent its expansion by IPython:
2042
2042
2043 In [6]: alias show echo\\
2043 In [6]: alias show echo\\
2044 In [7]: PATH='A Python string'\\
2044 In [7]: PATH='A Python string'\\
2045 In [8]: show $PATH\\
2045 In [8]: show $PATH\\
2046 A Python string\\
2046 A Python string\\
2047 In [9]: show $$PATH\\
2047 In [9]: show $$PATH\\
2048 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2048 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2049
2049
2050 You can use the alias facility to acess all of $PATH. See the %rehash
2050 You can use the alias facility to acess all of $PATH. See the %rehash
2051 and %rehashx functions, which automatically create aliases for the
2051 and %rehashx functions, which automatically create aliases for the
2052 contents of your $PATH.
2052 contents of your $PATH.
2053
2053
2054 If called with no parameters, %alias prints the current alias table."""
2054 If called with no parameters, %alias prints the current alias table."""
2055
2055
2056 par = parameter_s.strip()
2056 par = parameter_s.strip()
2057 if not par:
2057 if not par:
2058 if self.shell.rc.automagic:
2058 if self.shell.rc.automagic:
2059 prechar = ''
2059 prechar = ''
2060 else:
2060 else:
2061 prechar = self.shell.ESC_MAGIC
2061 prechar = self.shell.ESC_MAGIC
2062 print 'Alias\t\tSystem Command\n'+'-'*30
2062 print 'Alias\t\tSystem Command\n'+'-'*30
2063 atab = self.shell.alias_table
2063 atab = self.shell.alias_table
2064 aliases = atab.keys()
2064 aliases = atab.keys()
2065 aliases.sort()
2065 aliases.sort()
2066 for alias in aliases:
2066 for alias in aliases:
2067 print prechar+alias+'\t\t'+atab[alias][1]
2067 print prechar+alias+'\t\t'+atab[alias][1]
2068 print '-'*30+'\nTotal number of aliases:',len(aliases)
2068 print '-'*30+'\nTotal number of aliases:',len(aliases)
2069 return
2069 return
2070 try:
2070 try:
2071 alias,cmd = par.split(None,1)
2071 alias,cmd = par.split(None,1)
2072 except:
2072 except:
2073 print OInspect.getdoc(self.magic_alias)
2073 print OInspect.getdoc(self.magic_alias)
2074 else:
2074 else:
2075 nargs = cmd.count('%s')
2075 nargs = cmd.count('%s')
2076 if nargs>0 and cmd.find('%l')>=0:
2076 if nargs>0 and cmd.find('%l')>=0:
2077 error('The %s and %l specifiers are mutually exclusive '
2077 error('The %s and %l specifiers are mutually exclusive '
2078 'in alias definitions.')
2078 'in alias definitions.')
2079 else: # all looks OK
2079 else: # all looks OK
2080 self.shell.alias_table[alias] = (nargs,cmd)
2080 self.shell.alias_table[alias] = (nargs,cmd)
2081 self.shell.alias_table_validate(verbose=1)
2081 self.shell.alias_table_validate(verbose=1)
2082 # end magic_alias
2082 # end magic_alias
2083
2083
2084 def magic_unalias(self, parameter_s = ''):
2084 def magic_unalias(self, parameter_s = ''):
2085 """Remove an alias"""
2085 """Remove an alias"""
2086
2086
2087 aname = parameter_s.strip()
2087 aname = parameter_s.strip()
2088 if aname in self.shell.alias_table:
2088 if aname in self.shell.alias_table:
2089 del self.shell.alias_table[aname]
2089 del self.shell.alias_table[aname]
2090
2090
2091 def magic_rehash(self, parameter_s = ''):
2091 def magic_rehash(self, parameter_s = ''):
2092 """Update the alias table with all entries in $PATH.
2092 """Update the alias table with all entries in $PATH.
2093
2093
2094 This version does no checks on execute permissions or whether the
2094 This version does no checks on execute permissions or whether the
2095 contents of $PATH are truly files (instead of directories or something
2095 contents of $PATH are truly files (instead of directories or something
2096 else). For such a safer (but slower) version, use %rehashx."""
2096 else). For such a safer (but slower) version, use %rehashx."""
2097
2097
2098 # This function (and rehashx) manipulate the alias_table directly
2098 # This function (and rehashx) manipulate the alias_table directly
2099 # rather than calling magic_alias, for speed reasons. A rehash on a
2099 # rather than calling magic_alias, for speed reasons. A rehash on a
2100 # typical Linux box involves several thousand entries, so efficiency
2100 # typical Linux box involves several thousand entries, so efficiency
2101 # here is a top concern.
2101 # here is a top concern.
2102
2102
2103 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2103 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2104 alias_table = self.shell.alias_table
2104 alias_table = self.shell.alias_table
2105 for pdir in path:
2105 for pdir in path:
2106 for ff in os.listdir(pdir):
2106 for ff in os.listdir(pdir):
2107 # each entry in the alias table must be (N,name), where
2107 # each entry in the alias table must be (N,name), where
2108 # N is the number of positional arguments of the alias.
2108 # N is the number of positional arguments of the alias.
2109 alias_table[ff] = (0,ff)
2109 alias_table[ff] = (0,ff)
2110 # Make sure the alias table doesn't contain keywords or builtins
2110 # Make sure the alias table doesn't contain keywords or builtins
2111 self.shell.alias_table_validate()
2111 self.shell.alias_table_validate()
2112 # Call again init_auto_alias() so we get 'rm -i' and other modified
2112 # Call again init_auto_alias() so we get 'rm -i' and other modified
2113 # aliases since %rehash will probably clobber them
2113 # aliases since %rehash will probably clobber them
2114 self.shell.init_auto_alias()
2114 self.shell.init_auto_alias()
2115
2115
2116 def magic_rehashx(self, parameter_s = ''):
2116 def magic_rehashx(self, parameter_s = ''):
2117 """Update the alias table with all executable files in $PATH.
2117 """Update the alias table with all executable files in $PATH.
2118
2118
2119 This version explicitly checks that every entry in $PATH is a file
2119 This version explicitly checks that every entry in $PATH is a file
2120 with execute access (os.X_OK), so it is much slower than %rehash.
2120 with execute access (os.X_OK), so it is much slower than %rehash.
2121
2121
2122 Under Windows, it checks executability as a match agains a
2122 Under Windows, it checks executability as a match agains a
2123 '|'-separated string of extensions, stored in the IPython config
2123 '|'-separated string of extensions, stored in the IPython config
2124 variable win_exec_ext. This defaults to 'exe|com|bat'. """
2124 variable win_exec_ext. This defaults to 'exe|com|bat'. """
2125
2125
2126 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2126 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2127 alias_table = self.shell.alias_table
2127 alias_table = self.shell.alias_table
2128
2128
2129 if os.name == 'posix':
2129 if os.name == 'posix':
2130 isexec = lambda fname:os.path.isfile(fname) and \
2130 isexec = lambda fname:os.path.isfile(fname) and \
2131 os.access(fname,os.X_OK)
2131 os.access(fname,os.X_OK)
2132 else:
2132 else:
2133
2133
2134 try:
2134 try:
2135 winext = os.environ['pathext'].replace(';','|').replace('.','')
2135 winext = os.environ['pathext'].replace(';','|').replace('.','')
2136 except KeyError:
2136 except KeyError:
2137 winext = 'exe|com|bat'
2137 winext = 'exe|com|bat'
2138
2138
2139 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2139 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2140 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2140 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2141 savedir = os.getcwd()
2141 savedir = os.getcwd()
2142 try:
2142 try:
2143 # write the whole loop for posix/Windows so we don't have an if in
2143 # write the whole loop for posix/Windows so we don't have an if in
2144 # the innermost part
2144 # the innermost part
2145 if os.name == 'posix':
2145 if os.name == 'posix':
2146 for pdir in path:
2146 for pdir in path:
2147 os.chdir(pdir)
2147 os.chdir(pdir)
2148 for ff in os.listdir(pdir):
2148 for ff in os.listdir(pdir):
2149 if isexec(ff):
2149 if isexec(ff):
2150 # each entry in the alias table must be (N,name),
2150 # each entry in the alias table must be (N,name),
2151 # where N is the number of positional arguments of the
2151 # where N is the number of positional arguments of the
2152 # alias.
2152 # alias.
2153 alias_table[ff] = (0,ff)
2153 alias_table[ff] = (0,ff)
2154 else:
2154 else:
2155 for pdir in path:
2155 for pdir in path:
2156 os.chdir(pdir)
2156 os.chdir(pdir)
2157 for ff in os.listdir(pdir):
2157 for ff in os.listdir(pdir):
2158 if isexec(ff):
2158 if isexec(ff):
2159 alias_table[execre.sub(r'\1',ff)] = (0,ff)
2159 alias_table[execre.sub(r'\1',ff)] = (0,ff)
2160 # Make sure the alias table doesn't contain keywords or builtins
2160 # Make sure the alias table doesn't contain keywords or builtins
2161 self.shell.alias_table_validate()
2161 self.shell.alias_table_validate()
2162 # Call again init_auto_alias() so we get 'rm -i' and other
2162 # Call again init_auto_alias() so we get 'rm -i' and other
2163 # modified aliases since %rehashx will probably clobber them
2163 # modified aliases since %rehashx will probably clobber them
2164 self.shell.init_auto_alias()
2164 self.shell.init_auto_alias()
2165 finally:
2165 finally:
2166 os.chdir(savedir)
2166 os.chdir(savedir)
2167
2167
2168 def magic_pwd(self, parameter_s = ''):
2168 def magic_pwd(self, parameter_s = ''):
2169 """Return the current working directory path."""
2169 """Return the current working directory path."""
2170 return os.getcwd()
2170 return os.getcwd()
2171
2171
2172 def magic_cd(self, parameter_s=''):
2172 def magic_cd(self, parameter_s=''):
2173 """Change the current working directory.
2173 """Change the current working directory.
2174
2174
2175 This command automatically maintains an internal list of directories
2175 This command automatically maintains an internal list of directories
2176 you visit during your IPython session, in the variable _dh. The
2176 you visit during your IPython session, in the variable _dh. The
2177 command %dhist shows this history nicely formatted.
2177 command %dhist shows this history nicely formatted.
2178
2178
2179 Usage:
2179 Usage:
2180
2180
2181 cd 'dir': changes to directory 'dir'.
2181 cd 'dir': changes to directory 'dir'.
2182
2182
2183 cd -: changes to the last visited directory.
2183 cd -: changes to the last visited directory.
2184
2184
2185 cd -<n>: changes to the n-th directory in the directory history.
2185 cd -<n>: changes to the n-th directory in the directory history.
2186
2186
2187 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2187 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2188 (note: cd <bookmark_name> is enough if there is no
2188 (note: cd <bookmark_name> is enough if there is no
2189 directory <bookmark_name>, but a bookmark with the name exists.)
2189 directory <bookmark_name>, but a bookmark with the name exists.)
2190
2190
2191 Options:
2191 Options:
2192
2192
2193 -q: quiet. Do not print the working directory after the cd command is
2193 -q: quiet. Do not print the working directory after the cd command is
2194 executed. By default IPython's cd command does print this directory,
2194 executed. By default IPython's cd command does print this directory,
2195 since the default prompts do not display path information.
2195 since the default prompts do not display path information.
2196
2196
2197 Note that !cd doesn't work for this purpose because the shell where
2197 Note that !cd doesn't work for this purpose because the shell where
2198 !command runs is immediately discarded after executing 'command'."""
2198 !command runs is immediately discarded after executing 'command'."""
2199
2199
2200 parameter_s = parameter_s.strip()
2200 parameter_s = parameter_s.strip()
2201 bkms = self.shell.persist.get("bookmarks",{})
2201 bkms = self.shell.persist.get("bookmarks",{})
2202
2202
2203 numcd = re.match(r'(-)(\d+)$',parameter_s)
2203 numcd = re.match(r'(-)(\d+)$',parameter_s)
2204 # jump in directory history by number
2204 # jump in directory history by number
2205 if numcd:
2205 if numcd:
2206 nn = int(numcd.group(2))
2206 nn = int(numcd.group(2))
2207 try:
2207 try:
2208 ps = self.shell.user_ns['_dh'][nn]
2208 ps = self.shell.user_ns['_dh'][nn]
2209 except IndexError:
2209 except IndexError:
2210 print 'The requested directory does not exist in history.'
2210 print 'The requested directory does not exist in history.'
2211 return
2211 return
2212 else:
2212 else:
2213 opts = {}
2213 opts = {}
2214 else:
2214 else:
2215 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2215 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2216 # jump to previous
2216 # jump to previous
2217 if ps == '-':
2217 if ps == '-':
2218 try:
2218 try:
2219 ps = self.shell.user_ns['_dh'][-2]
2219 ps = self.shell.user_ns['_dh'][-2]
2220 except IndexError:
2220 except IndexError:
2221 print 'No previous directory to change to.'
2221 print 'No previous directory to change to.'
2222 return
2222 return
2223 # jump to bookmark
2223 # jump to bookmark
2224 elif opts.has_key('b') or (bkms.has_key(ps) and not os.path.isdir(ps)):
2224 elif opts.has_key('b') or (bkms.has_key(ps) and not os.path.isdir(ps)):
2225 if bkms.has_key(ps):
2225 if bkms.has_key(ps):
2226 target = bkms[ps]
2226 target = bkms[ps]
2227 print '(bookmark:%s) -> %s' % (ps,target)
2227 print '(bookmark:%s) -> %s' % (ps,target)
2228 ps = target
2228 ps = target
2229 else:
2229 else:
2230 if bkms:
2230 if bkms:
2231 error("Bookmark '%s' not found. "
2231 error("Bookmark '%s' not found. "
2232 "Use '%bookmark -l' to see your bookmarks." % ps)
2232 "Use '%bookmark -l' to see your bookmarks." % ps)
2233 else:
2233 else:
2234 print "Bookmarks not set - use %bookmark <bookmarkname>"
2234 print "Bookmarks not set - use %bookmark <bookmarkname>"
2235 return
2235 return
2236
2236
2237 # at this point ps should point to the target dir
2237 # at this point ps should point to the target dir
2238 if ps:
2238 if ps:
2239 try:
2239 try:
2240 os.chdir(os.path.expanduser(ps))
2240 os.chdir(os.path.expanduser(ps))
2241 except OSError:
2241 except OSError:
2242 print sys.exc_info()[1]
2242 print sys.exc_info()[1]
2243 else:
2243 else:
2244 self.shell.user_ns['_dh'].append(os.getcwd())
2244 self.shell.user_ns['_dh'].append(os.getcwd())
2245 else:
2245 else:
2246 os.chdir(self.home_dir)
2246 os.chdir(self.home_dir)
2247 self.shell.user_ns['_dh'].append(os.getcwd())
2247 self.shell.user_ns['_dh'].append(os.getcwd())
2248 if not 'q' in opts:
2248 if not 'q' in opts:
2249 print self.shell.user_ns['_dh'][-1]
2249 print self.shell.user_ns['_dh'][-1]
2250
2250
2251 def magic_dhist(self, parameter_s=''):
2251 def magic_dhist(self, parameter_s=''):
2252 """Print your history of visited directories.
2252 """Print your history of visited directories.
2253
2253
2254 %dhist -> print full history\\
2254 %dhist -> print full history\\
2255 %dhist n -> print last n entries only\\
2255 %dhist n -> print last n entries only\\
2256 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2256 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2257
2257
2258 This history is automatically maintained by the %cd command, and
2258 This history is automatically maintained by the %cd command, and
2259 always available as the global list variable _dh. You can use %cd -<n>
2259 always available as the global list variable _dh. You can use %cd -<n>
2260 to go to directory number <n>."""
2260 to go to directory number <n>."""
2261
2261
2262 dh = self.shell.user_ns['_dh']
2262 dh = self.shell.user_ns['_dh']
2263 if parameter_s:
2263 if parameter_s:
2264 try:
2264 try:
2265 args = map(int,parameter_s.split())
2265 args = map(int,parameter_s.split())
2266 except:
2266 except:
2267 self.arg_err(Magic.magic_dhist)
2267 self.arg_err(Magic.magic_dhist)
2268 return
2268 return
2269 if len(args) == 1:
2269 if len(args) == 1:
2270 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2270 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2271 elif len(args) == 2:
2271 elif len(args) == 2:
2272 ini,fin = args
2272 ini,fin = args
2273 else:
2273 else:
2274 self.arg_err(Magic.magic_dhist)
2274 self.arg_err(Magic.magic_dhist)
2275 return
2275 return
2276 else:
2276 else:
2277 ini,fin = 0,len(dh)
2277 ini,fin = 0,len(dh)
2278 nlprint(dh,
2278 nlprint(dh,
2279 header = 'Directory history (kept in _dh)',
2279 header = 'Directory history (kept in _dh)',
2280 start=ini,stop=fin)
2280 start=ini,stop=fin)
2281
2281
2282 def magic_env(self, parameter_s=''):
2282 def magic_env(self, parameter_s=''):
2283 """List environment variables."""
2283 """List environment variables."""
2284
2284
2285 # environ is an instance of UserDict
2285 # environ is an instance of UserDict
2286 return os.environ.data
2286 return os.environ.data
2287
2287
2288 def magic_pushd(self, parameter_s=''):
2288 def magic_pushd(self, parameter_s=''):
2289 """Place the current dir on stack and change directory.
2289 """Place the current dir on stack and change directory.
2290
2290
2291 Usage:\\
2291 Usage:\\
2292 %pushd ['dirname']
2292 %pushd ['dirname']
2293
2293
2294 %pushd with no arguments does a %pushd to your home directory.
2294 %pushd with no arguments does a %pushd to your home directory.
2295 """
2295 """
2296 if parameter_s == '': parameter_s = '~'
2296 if parameter_s == '': parameter_s = '~'
2297 if len(self.dir_stack)>0 and os.path.expanduser(parameter_s) != \
2297 if len(self.dir_stack)>0 and os.path.expanduser(parameter_s) != \
2298 os.path.expanduser(self.dir_stack[0]):
2298 os.path.expanduser(self.dir_stack[0]):
2299 try:
2299 try:
2300 self.magic_cd(parameter_s)
2300 self.magic_cd(parameter_s)
2301 self.dir_stack.insert(0,os.getcwd().replace(self.home_dir,'~'))
2301 self.dir_stack.insert(0,os.getcwd().replace(self.home_dir,'~'))
2302 self.magic_dirs()
2302 self.magic_dirs()
2303 except:
2303 except:
2304 print 'Invalid directory'
2304 print 'Invalid directory'
2305 else:
2305 else:
2306 print 'You are already there!'
2306 print 'You are already there!'
2307
2307
2308 def magic_popd(self, parameter_s=''):
2308 def magic_popd(self, parameter_s=''):
2309 """Change to directory popped off the top of the stack.
2309 """Change to directory popped off the top of the stack.
2310 """
2310 """
2311 if len (self.dir_stack) > 1:
2311 if len (self.dir_stack) > 1:
2312 self.dir_stack.pop(0)
2312 self.dir_stack.pop(0)
2313 self.magic_cd(self.dir_stack[0])
2313 self.magic_cd(self.dir_stack[0])
2314 print self.dir_stack[0]
2314 print self.dir_stack[0]
2315 else:
2315 else:
2316 print "You can't remove the starting directory from the stack:",\
2316 print "You can't remove the starting directory from the stack:",\
2317 self.dir_stack
2317 self.dir_stack
2318
2318
2319 def magic_dirs(self, parameter_s=''):
2319 def magic_dirs(self, parameter_s=''):
2320 """Return the current directory stack."""
2320 """Return the current directory stack."""
2321
2321
2322 return self.dir_stack[:]
2322 return self.dir_stack[:]
2323
2323
2324 def magic_sc(self, parameter_s=''):
2324 def magic_sc(self, parameter_s=''):
2325 """Shell capture - execute a shell command and capture its output.
2325 """Shell capture - execute a shell command and capture its output.
2326
2326
2327 %sc [options] varname=command
2327 %sc [options] varname=command
2328
2328
2329 IPython will run the given command using commands.getoutput(), and
2329 IPython will run the given command using commands.getoutput(), and
2330 will then update the user's interactive namespace with a variable
2330 will then update the user's interactive namespace with a variable
2331 called varname, containing the value of the call. Your command can
2331 called varname, containing the value of the call. Your command can
2332 contain shell wildcards, pipes, etc.
2332 contain shell wildcards, pipes, etc.
2333
2333
2334 The '=' sign in the syntax is mandatory, and the variable name you
2334 The '=' sign in the syntax is mandatory, and the variable name you
2335 supply must follow Python's standard conventions for valid names.
2335 supply must follow Python's standard conventions for valid names.
2336
2336
2337 Options:
2337 Options:
2338
2338
2339 -l: list output. Split the output on newlines into a list before
2339 -l: list output. Split the output on newlines into a list before
2340 assigning it to the given variable. By default the output is stored
2340 assigning it to the given variable. By default the output is stored
2341 as a single string.
2341 as a single string.
2342
2342
2343 -v: verbose. Print the contents of the variable.
2343 -v: verbose. Print the contents of the variable.
2344
2344
2345 In most cases you should not need to split as a list, because the
2345 In most cases you should not need to split as a list, because the
2346 returned value is a special type of string which can automatically
2346 returned value is a special type of string which can automatically
2347 provide its contents either as a list (split on newlines) or as a
2347 provide its contents either as a list (split on newlines) or as a
2348 space-separated string. These are convenient, respectively, either
2348 space-separated string. These are convenient, respectively, either
2349 for sequential processing or to be passed to a shell command.
2349 for sequential processing or to be passed to a shell command.
2350
2350
2351 For example:
2351 For example:
2352
2352
2353 # Capture into variable a
2353 # Capture into variable a
2354 In [9]: sc a=ls *py
2354 In [9]: sc a=ls *py
2355
2355
2356 # a is a string with embedded newlines
2356 # a is a string with embedded newlines
2357 In [10]: a
2357 In [10]: a
2358 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2358 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2359
2359
2360 # which can be seen as a list:
2360 # which can be seen as a list:
2361 In [11]: a.l
2361 In [11]: a.l
2362 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2362 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2363
2363
2364 # or as a whitespace-separated string:
2364 # or as a whitespace-separated string:
2365 In [12]: a.s
2365 In [12]: a.s
2366 Out[12]: 'setup.py win32_manual_post_install.py'
2366 Out[12]: 'setup.py win32_manual_post_install.py'
2367
2367
2368 # a.s is useful to pass as a single command line:
2368 # a.s is useful to pass as a single command line:
2369 In [13]: !wc -l $a.s
2369 In [13]: !wc -l $a.s
2370 146 setup.py
2370 146 setup.py
2371 130 win32_manual_post_install.py
2371 130 win32_manual_post_install.py
2372 276 total
2372 276 total
2373
2373
2374 # while the list form is useful to loop over:
2374 # while the list form is useful to loop over:
2375 In [14]: for f in a.l:
2375 In [14]: for f in a.l:
2376 ....: !wc -l $f
2376 ....: !wc -l $f
2377 ....:
2377 ....:
2378 146 setup.py
2378 146 setup.py
2379 130 win32_manual_post_install.py
2379 130 win32_manual_post_install.py
2380
2380
2381 Similiarly, the lists returned by the -l option are also special, in
2381 Similiarly, the lists returned by the -l option are also special, in
2382 the sense that you can equally invoke the .s attribute on them to
2382 the sense that you can equally invoke the .s attribute on them to
2383 automatically get a whitespace-separated string from their contents:
2383 automatically get a whitespace-separated string from their contents:
2384
2384
2385 In [1]: sc -l b=ls *py
2385 In [1]: sc -l b=ls *py
2386
2386
2387 In [2]: b
2387 In [2]: b
2388 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2388 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2389
2389
2390 In [3]: b.s
2390 In [3]: b.s
2391 Out[3]: 'setup.py win32_manual_post_install.py'
2391 Out[3]: 'setup.py win32_manual_post_install.py'
2392
2392
2393 In summary, both the lists and strings used for ouptut capture have
2393 In summary, both the lists and strings used for ouptut capture have
2394 the following special attributes:
2394 the following special attributes:
2395
2395
2396 .l (or .list) : value as list.
2396 .l (or .list) : value as list.
2397 .n (or .nlstr): value as newline-separated string.
2397 .n (or .nlstr): value as newline-separated string.
2398 .s (or .spstr): value as space-separated string.
2398 .s (or .spstr): value as space-separated string.
2399 """
2399 """
2400
2400
2401 opts,args = self.parse_options(parameter_s,'lv')
2401 opts,args = self.parse_options(parameter_s,'lv')
2402 # Try to get a variable name and command to run
2402 # Try to get a variable name and command to run
2403 try:
2403 try:
2404 # the variable name must be obtained from the parse_options
2404 # the variable name must be obtained from the parse_options
2405 # output, which uses shlex.split to strip options out.
2405 # output, which uses shlex.split to strip options out.
2406 var,_ = args.split('=',1)
2406 var,_ = args.split('=',1)
2407 var = var.strip()
2407 var = var.strip()
2408 # But the the command has to be extracted from the original input
2408 # But the the command has to be extracted from the original input
2409 # parameter_s, not on what parse_options returns, to avoid the
2409 # parameter_s, not on what parse_options returns, to avoid the
2410 # quote stripping which shlex.split performs on it.
2410 # quote stripping which shlex.split performs on it.
2411 _,cmd = parameter_s.split('=',1)
2411 _,cmd = parameter_s.split('=',1)
2412 except ValueError:
2412 except ValueError:
2413 var,cmd = '',''
2413 var,cmd = '',''
2414 if not var:
2414 if not var:
2415 error('you must specify a variable to assign the command to.')
2415 error('you must specify a variable to assign the command to.')
2416 return
2416 return
2417 # If all looks ok, proceed
2417 # If all looks ok, proceed
2418 out,err = self.shell.getoutputerror(cmd)
2418 out,err = self.shell.getoutputerror(cmd)
2419 if err:
2419 if err:
2420 print >> Term.cerr,err
2420 print >> Term.cerr,err
2421 if opts.has_key('l'):
2421 if opts.has_key('l'):
2422 out = SList(out.split('\n'))
2422 out = SList(out.split('\n'))
2423 else:
2423 else:
2424 out = LSString(out)
2424 out = LSString(out)
2425 if opts.has_key('v'):
2425 if opts.has_key('v'):
2426 print '%s ==\n%s' % (var,pformat(out))
2426 print '%s ==\n%s' % (var,pformat(out))
2427 self.shell.user_ns.update({var:out})
2427 self.shell.user_ns.update({var:out})
2428
2428
2429 def magic_sx(self, parameter_s=''):
2429 def magic_sx(self, parameter_s=''):
2430 """Shell execute - run a shell command and capture its output.
2430 """Shell execute - run a shell command and capture its output.
2431
2431
2432 %sx command
2432 %sx command
2433
2433
2434 IPython will run the given command using commands.getoutput(), and
2434 IPython will run the given command using commands.getoutput(), and
2435 return the result formatted as a list (split on '\\n'). Since the
2435 return the result formatted as a list (split on '\\n'). Since the
2436 output is _returned_, it will be stored in ipython's regular output
2436 output is _returned_, it will be stored in ipython's regular output
2437 cache Out[N] and in the '_N' automatic variables.
2437 cache Out[N] and in the '_N' automatic variables.
2438
2438
2439 Notes:
2439 Notes:
2440
2440
2441 1) If an input line begins with '!!', then %sx is automatically
2441 1) If an input line begins with '!!', then %sx is automatically
2442 invoked. That is, while:
2442 invoked. That is, while:
2443 !ls
2443 !ls
2444 causes ipython to simply issue system('ls'), typing
2444 causes ipython to simply issue system('ls'), typing
2445 !!ls
2445 !!ls
2446 is a shorthand equivalent to:
2446 is a shorthand equivalent to:
2447 %sx ls
2447 %sx ls
2448
2448
2449 2) %sx differs from %sc in that %sx automatically splits into a list,
2449 2) %sx differs from %sc in that %sx automatically splits into a list,
2450 like '%sc -l'. The reason for this is to make it as easy as possible
2450 like '%sc -l'. The reason for this is to make it as easy as possible
2451 to process line-oriented shell output via further python commands.
2451 to process line-oriented shell output via further python commands.
2452 %sc is meant to provide much finer control, but requires more
2452 %sc is meant to provide much finer control, but requires more
2453 typing.
2453 typing.
2454
2454
2455 3) Just like %sc -l, this is a list with special attributes:
2455 3) Just like %sc -l, this is a list with special attributes:
2456
2456
2457 .l (or .list) : value as list.
2457 .l (or .list) : value as list.
2458 .n (or .nlstr): value as newline-separated string.
2458 .n (or .nlstr): value as newline-separated string.
2459 .s (or .spstr): value as whitespace-separated string.
2459 .s (or .spstr): value as whitespace-separated string.
2460
2460
2461 This is very useful when trying to use such lists as arguments to
2461 This is very useful when trying to use such lists as arguments to
2462 system commands."""
2462 system commands."""
2463
2463
2464 if parameter_s:
2464 if parameter_s:
2465 out,err = self.shell.getoutputerror(parameter_s)
2465 out,err = self.shell.getoutputerror(parameter_s)
2466 if err:
2466 if err:
2467 print >> Term.cerr,err
2467 print >> Term.cerr,err
2468 return SList(out.split('\n'))
2468 return SList(out.split('\n'))
2469
2469
2470 def magic_bg(self, parameter_s=''):
2470 def magic_bg(self, parameter_s=''):
2471 """Run a job in the background, in a separate thread.
2471 """Run a job in the background, in a separate thread.
2472
2472
2473 For example,
2473 For example,
2474
2474
2475 %bg myfunc(x,y,z=1)
2475 %bg myfunc(x,y,z=1)
2476
2476
2477 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2477 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2478 execution starts, a message will be printed indicating the job
2478 execution starts, a message will be printed indicating the job
2479 number. If your job number is 5, you can use
2479 number. If your job number is 5, you can use
2480
2480
2481 myvar = jobs.result(5) or myvar = jobs[5].result
2481 myvar = jobs.result(5) or myvar = jobs[5].result
2482
2482
2483 to assign this result to variable 'myvar'.
2483 to assign this result to variable 'myvar'.
2484
2484
2485 IPython has a job manager, accessible via the 'jobs' object. You can
2485 IPython has a job manager, accessible via the 'jobs' object. You can
2486 type jobs? to get more information about it, and use jobs.<TAB> to see
2486 type jobs? to get more information about it, and use jobs.<TAB> to see
2487 its attributes. All attributes not starting with an underscore are
2487 its attributes. All attributes not starting with an underscore are
2488 meant for public use.
2488 meant for public use.
2489
2489
2490 In particular, look at the jobs.new() method, which is used to create
2490 In particular, look at the jobs.new() method, which is used to create
2491 new jobs. This magic %bg function is just a convenience wrapper
2491 new jobs. This magic %bg function is just a convenience wrapper
2492 around jobs.new(), for expression-based jobs. If you want to create a
2492 around jobs.new(), for expression-based jobs. If you want to create a
2493 new job with an explicit function object and arguments, you must call
2493 new job with an explicit function object and arguments, you must call
2494 jobs.new() directly.
2494 jobs.new() directly.
2495
2495
2496 The jobs.new docstring also describes in detail several important
2496 The jobs.new docstring also describes in detail several important
2497 caveats associated with a thread-based model for background job
2497 caveats associated with a thread-based model for background job
2498 execution. Type jobs.new? for details.
2498 execution. Type jobs.new? for details.
2499
2499
2500 You can check the status of all jobs with jobs.status().
2500 You can check the status of all jobs with jobs.status().
2501
2501
2502 The jobs variable is set by IPython into the Python builtin namespace.
2502 The jobs variable is set by IPython into the Python builtin namespace.
2503 If you ever declare a variable named 'jobs', you will shadow this
2503 If you ever declare a variable named 'jobs', you will shadow this
2504 name. You can either delete your global jobs variable to regain
2504 name. You can either delete your global jobs variable to regain
2505 access to the job manager, or make a new name and assign it manually
2505 access to the job manager, or make a new name and assign it manually
2506 to the manager (stored in IPython's namespace). For example, to
2506 to the manager (stored in IPython's namespace). For example, to
2507 assign the job manager to the Jobs name, use:
2507 assign the job manager to the Jobs name, use:
2508
2508
2509 Jobs = __builtins__.jobs"""
2509 Jobs = __builtins__.jobs"""
2510
2510
2511 self.shell.jobs.new(parameter_s,self.shell.user_ns)
2511 self.shell.jobs.new(parameter_s,self.shell.user_ns)
2512
2512
2513 def magic_bookmark(self, parameter_s=''):
2513 def magic_bookmark(self, parameter_s=''):
2514 """Manage IPython's bookmark system.
2514 """Manage IPython's bookmark system.
2515
2515
2516 %bookmark <name> - set bookmark to current dir
2516 %bookmark <name> - set bookmark to current dir
2517 %bookmark <name> <dir> - set bookmark to <dir>
2517 %bookmark <name> <dir> - set bookmark to <dir>
2518 %bookmark -l - list all bookmarks
2518 %bookmark -l - list all bookmarks
2519 %bookmark -d <name> - remove bookmark
2519 %bookmark -d <name> - remove bookmark
2520 %bookmark -r - remove all bookmarks
2520 %bookmark -r - remove all bookmarks
2521
2521
2522 You can later on access a bookmarked folder with:
2522 You can later on access a bookmarked folder with:
2523 %cd -b <name>
2523 %cd -b <name>
2524 or simply '%cd <name>' if there is no directory called <name> AND
2524 or simply '%cd <name>' if there is no directory called <name> AND
2525 there is such a bookmark defined.
2525 there is such a bookmark defined.
2526
2526
2527 Your bookmarks persist through IPython sessions, but they are
2527 Your bookmarks persist through IPython sessions, but they are
2528 associated with each profile."""
2528 associated with each profile."""
2529
2529
2530 opts,args = self.parse_options(parameter_s,'drl',mode='list')
2530 opts,args = self.parse_options(parameter_s,'drl',mode='list')
2531 if len(args) > 2:
2531 if len(args) > 2:
2532 error('You can only give at most two arguments')
2532 error('You can only give at most two arguments')
2533 return
2533 return
2534
2534
2535 bkms = self.shell.persist.get('bookmarks',{})
2535 bkms = self.shell.persist.get('bookmarks',{})
2536
2536
2537 if opts.has_key('d'):
2537 if opts.has_key('d'):
2538 try:
2538 try:
2539 todel = args[0]
2539 todel = args[0]
2540 except IndexError:
2540 except IndexError:
2541 error('You must provide a bookmark to delete')
2541 error('You must provide a bookmark to delete')
2542 else:
2542 else:
2543 try:
2543 try:
2544 del bkms[todel]
2544 del bkms[todel]
2545 except:
2545 except:
2546 error("Can't delete bookmark '%s'" % todel)
2546 error("Can't delete bookmark '%s'" % todel)
2547 elif opts.has_key('r'):
2547 elif opts.has_key('r'):
2548 bkms = {}
2548 bkms = {}
2549 elif opts.has_key('l'):
2549 elif opts.has_key('l'):
2550 bks = bkms.keys()
2550 bks = bkms.keys()
2551 bks.sort()
2551 bks.sort()
2552 if bks:
2552 if bks:
2553 size = max(map(len,bks))
2553 size = max(map(len,bks))
2554 else:
2554 else:
2555 size = 0
2555 size = 0
2556 fmt = '%-'+str(size)+'s -> %s'
2556 fmt = '%-'+str(size)+'s -> %s'
2557 print 'Current bookmarks:'
2557 print 'Current bookmarks:'
2558 for bk in bks:
2558 for bk in bks:
2559 print fmt % (bk,bkms[bk])
2559 print fmt % (bk,bkms[bk])
2560 else:
2560 else:
2561 if not args:
2561 if not args:
2562 error("You must specify the bookmark name")
2562 error("You must specify the bookmark name")
2563 elif len(args)==1:
2563 elif len(args)==1:
2564 bkms[args[0]] = os.getcwd()
2564 bkms[args[0]] = os.getcwd()
2565 elif len(args)==2:
2565 elif len(args)==2:
2566 bkms[args[0]] = args[1]
2566 bkms[args[0]] = args[1]
2567 self.persist['bookmarks'] = bkms
2567 self.persist['bookmarks'] = bkms
2568
2568
2569 def magic_pycat(self, parameter_s=''):
2569 def magic_pycat(self, parameter_s=''):
2570 """Show a syntax-highlighted file through a pager.
2570 """Show a syntax-highlighted file through a pager.
2571
2571
2572 This magic is similar to the cat utility, but it will assume the file
2572 This magic is similar to the cat utility, but it will assume the file
2573 to be Python source and will show it with syntax highlighting. """
2573 to be Python source and will show it with syntax highlighting. """
2574
2574
2575 filename = get_py_filename(parameter_s)
2575 filename = get_py_filename(parameter_s)
2576 page(self.shell.colorize(file_read(filename)),
2576 page(self.shell.colorize(file_read(filename)),
2577 screen_lines=self.shell.rc.screen_length)
2577 screen_lines=self.shell.rc.screen_length)
2578
2578
2579 # end Magic
2579 # end Magic
@@ -1,576 +1,578 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 958 2005-12-27 23:17:51Z fperez $"""
5 $Id: Prompts.py 960 2005-12-28 06:51:01Z 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,cache_size,Pprint,colors='NoColor',input_sep='\n',
396 output_sep='\n',output_sep2='',user_ns={},
396 output_sep='\n',output_sep2='',user_ns={},
397 ps1 = None, ps2 = None,ps_out = None,
397 ps1 = None, ps2 = None,ps_out = None,
398 input_hist = None,pad_left=True):
398 input_hist = 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.user_ns = user_ns
417 # and to the user's input
417 # and to the user's input
418 self.input_hist = input_hist
418 self.input_hist = input_hist
419
419
420 # Set input prompt strings and colors
420 # Set input prompt strings and colors
421 if cache_size == 0:
421 if cache_size == 0:
422 if ps1.find('%n') > -1 or ps1.find('\\#') > -1: ps1 = '>>> '
422 if ps1.find('%n') > -1 or ps1.find('\\#') > -1: ps1 = '>>> '
423 if ps2.find('%n') > -1 or ps2.find('\\#') > -1: ps2 = '... '
423 if ps2.find('%n') > -1 or ps2.find('\\#') > -1: ps2 = '... '
424 self.ps1_str = self._set_prompt_str(ps1,'In [\\#]: ','>>> ')
424 self.ps1_str = self._set_prompt_str(ps1,'In [\\#]: ','>>> ')
425 self.ps2_str = self._set_prompt_str(ps2,' .\\D.: ','... ')
425 self.ps2_str = self._set_prompt_str(ps2,' .\\D.: ','... ')
426 self.ps_out_str = self._set_prompt_str(ps_out,'Out[\\#]: ','')
426 self.ps_out_str = self._set_prompt_str(ps_out,'Out[\\#]: ','')
427
427
428 self.color_table = PromptColors
428 self.color_table = PromptColors
429 self.prompt1 = Prompt1(self,sep=input_sep,prompt=self.ps1_str,
429 self.prompt1 = Prompt1(self,sep=input_sep,prompt=self.ps1_str,
430 pad_left=pad_left)
430 pad_left=pad_left)
431 self.prompt2 = Prompt2(self,prompt=self.ps2_str,pad_left=pad_left)
431 self.prompt2 = Prompt2(self,prompt=self.ps2_str,pad_left=pad_left)
432 self.prompt_out = PromptOut(self,sep='',prompt=self.ps_out_str,
432 self.prompt_out = PromptOut(self,sep='',prompt=self.ps_out_str,
433 pad_left=pad_left)
433 pad_left=pad_left)
434 self.set_colors(colors)
434 self.set_colors(colors)
435
435
436 # other more normal stuff
436 # other more normal stuff
437 # b/c each call to the In[] prompt raises it by 1, even the first.
437 # b/c each call to the In[] prompt raises it by 1, even the first.
438 self.prompt_count = 0
438 self.prompt_count = 0
439 self.cache_count = 1
439 self.cache_count = 1
440 # Store the last prompt string each time, we need it for aligning
440 # Store the last prompt string each time, we need it for aligning
441 # continuation and auto-rewrite prompts
441 # continuation and auto-rewrite prompts
442 self.last_prompt = ''
442 self.last_prompt = ''
443 self.entries = [None] # output counter starts at 1 for the user
443 self.entries = [None] # output counter starts at 1 for the user
444 self.Pprint = Pprint
444 self.Pprint = Pprint
445 self.output_sep = output_sep
445 self.output_sep = output_sep
446 self.output_sep2 = output_sep2
446 self.output_sep2 = output_sep2
447 self._,self.__,self.___ = '','',''
447 self._,self.__,self.___ = '','',''
448 self.pprint_types = map(type,[(),[],{}])
448 self.pprint_types = map(type,[(),[],{}])
449
449
450 # these are deliberately global:
450 # these are deliberately global:
451 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
451 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
452 self.user_ns.update(to_user_ns)
452 self.user_ns.update(to_user_ns)
453
453
454 def _set_prompt_str(self,p_str,cache_def,no_cache_def):
454 def _set_prompt_str(self,p_str,cache_def,no_cache_def):
455 if p_str is None:
455 if p_str is None:
456 if self.do_full_cache:
456 if self.do_full_cache:
457 return cache_def
457 return cache_def
458 else:
458 else:
459 return no_cache_def
459 return no_cache_def
460 else:
460 else:
461 return p_str
461 return p_str
462
462
463 def set_colors(self,colors):
463 def set_colors(self,colors):
464 """Set the active color scheme and configure colors for the three
464 """Set the active color scheme and configure colors for the three
465 prompt subsystems."""
465 prompt subsystems."""
466
466
467 # FIXME: the prompt_specials global should be gobbled inside this
467 # FIXME: the prompt_specials global should be gobbled inside this
468 # class instead. Do it when cleaning up the whole 3-prompt system.
468 # class instead. Do it when cleaning up the whole 3-prompt system.
469 global prompt_specials
469 global prompt_specials
470 if colors.lower()=='nocolor':
470 if colors.lower()=='nocolor':
471 prompt_specials = prompt_specials_nocolor
471 prompt_specials = prompt_specials_nocolor
472 else:
472 else:
473 prompt_specials = prompt_specials_color
473 prompt_specials = prompt_specials_color
474
474
475 self.color_table.set_active_scheme(colors)
475 self.color_table.set_active_scheme(colors)
476 self.prompt1.set_colors()
476 self.prompt1.set_colors()
477 self.prompt2.set_colors()
477 self.prompt2.set_colors()
478 self.prompt_out.set_colors()
478 self.prompt_out.set_colors()
479
479
480 def __call__(self,arg=None):
480 def __call__(self,arg=None):
481 """Printing with history cache management.
481 """Printing with history cache management.
482
482
483 This is invoked everytime the interpreter needs to print, and is
483 This is invoked everytime the interpreter needs to print, and is
484 activated by setting the variable sys.displayhook to it."""
484 activated by setting the variable sys.displayhook to it."""
485
485
486 # If something injected a '_' variable in __builtin__, delete
486 # If something injected a '_' variable in __builtin__, delete
487 # ipython's automatic one so we don't clobber that. gettext() in
487 # ipython's automatic one so we don't clobber that. gettext() in
488 # particular uses _, so we need to stay away from it.
488 # particular uses _, so we need to stay away from it.
489 if '_' in __builtin__.__dict__:
489 if '_' in __builtin__.__dict__:
490 try:
490 try:
491 del self.user_ns['_']
491 del self.user_ns['_']
492 except KeyError:
492 except KeyError:
493 pass
493 pass
494 if arg is not None:
494 if arg is not None:
495 cout_write = Term.cout.write # fast lookup
495 cout_write = Term.cout.write # fast lookup
496 # first handle the cache and counters
496 # first handle the cache and counters
497 # but avoid recursive reference when displaying _oh/Out
498 if arg is not self.user_ns['_oh']:
497 self.update(arg)
499 self.update(arg)
498 # do not print output if input ends in ';'
500 # do not print output if input ends in ';'
499 if self.input_hist[self.prompt_count].endswith(';\n'):
501 if self.input_hist[self.prompt_count].endswith(';\n'):
500 return
502 return
501 # don't use print, puts an extra space
503 # don't use print, puts an extra space
502 cout_write(self.output_sep)
504 cout_write(self.output_sep)
503 if self.do_full_cache:
505 if self.do_full_cache:
504 cout_write(str(self.prompt_out))
506 cout_write(str(self.prompt_out))
505
507
506 if isinstance(arg,Macro):
508 if isinstance(arg,Macro):
507 print 'Executing Macro...'
509 print 'Executing Macro...'
508 # in case the macro takes a long time to execute
510 # in case the macro takes a long time to execute
509 Term.cout.flush()
511 Term.cout.flush()
510 exec arg.value in self.user_ns
512 exec arg.value in self.user_ns
511 return None
513 return None
512
514
513 # and now call a possibly user-defined print mechanism
515 # and now call a possibly user-defined print mechanism
514 self.display(arg)
516 self.display(arg)
515 cout_write(self.output_sep2)
517 cout_write(self.output_sep2)
516 Term.cout.flush()
518 Term.cout.flush()
517
519
518 def _display(self,arg):
520 def _display(self,arg):
519 """Default printer method, uses pprint.
521 """Default printer method, uses pprint.
520
522
521 This can be over-ridden by the users to implement special formatting
523 This can be over-ridden by the users to implement special formatting
522 of certain types of output."""
524 of certain types of output."""
523
525
524 if self.Pprint:
526 if self.Pprint:
525 out = pformat(arg)
527 out = pformat(arg)
526 if '\n' in out:
528 if '\n' in out:
527 # So that multi-line strings line up with the left column of
529 # So that multi-line strings line up with the left column of
528 # the screen, instead of having the output prompt mess up
530 # the screen, instead of having the output prompt mess up
529 # their first line.
531 # their first line.
530 Term.cout.write('\n')
532 Term.cout.write('\n')
531 print >>Term.cout, out
533 print >>Term.cout, out
532 else:
534 else:
533 print >>Term.cout, arg
535 print >>Term.cout, arg
534
536
535 # Assign the default display method:
537 # Assign the default display method:
536 display = _display
538 display = _display
537
539
538 def update(self,arg):
540 def update(self,arg):
539 #print '***cache_count', self.cache_count # dbg
541 #print '***cache_count', self.cache_count # dbg
540 if self.cache_count >= self.cache_size and self.do_full_cache:
542 if self.cache_count >= self.cache_size and self.do_full_cache:
541 self.flush()
543 self.flush()
542 # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
544 # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
543 # we cause buggy behavior for things like gettext).
545 # we cause buggy behavior for things like gettext).
544 if '_' not in __builtin__.__dict__:
546 if '_' not in __builtin__.__dict__:
545 self.___ = self.__
547 self.___ = self.__
546 self.__ = self._
548 self.__ = self._
547 self._ = arg
549 self._ = arg
548 self.user_ns.update({'_':self._,'__':self.__,'___':self.___})
550 self.user_ns.update({'_':self._,'__':self.__,'___':self.___})
549
551
550 # hackish access to top-level namespace to create _1,_2... dynamically
552 # hackish access to top-level namespace to create _1,_2... dynamically
551 to_main = {}
553 to_main = {}
552 if self.do_full_cache:
554 if self.do_full_cache:
553 self.cache_count += 1
555 self.cache_count += 1
554 self.entries.append(arg)
556 self.entries.append(arg)
555 new_result = '_'+`self.prompt_count`
557 new_result = '_'+`self.prompt_count`
556 to_main[new_result] = self.entries[-1]
558 to_main[new_result] = self.entries[-1]
557 self.user_ns.update(to_main)
559 self.user_ns.update(to_main)
558 self.user_ns['_oh'][self.prompt_count] = arg
560 self.user_ns['_oh'][self.prompt_count] = arg
559
561
560 def flush(self):
562 def flush(self):
561 if not self.do_full_cache:
563 if not self.do_full_cache:
562 raise ValueError,"You shouldn't have reached the cache flush "\
564 raise ValueError,"You shouldn't have reached the cache flush "\
563 "if full caching is not enabled!"
565 "if full caching is not enabled!"
564 warn('Output cache limit (currently '+\
566 warn('Output cache limit (currently '+\
565 `self.cache_count`+' entries) hit.\n'
567 `self.cache_count`+' entries) hit.\n'
566 'Flushing cache and resetting history counter...\n'
568 'Flushing cache and resetting history counter...\n'
567 'The only history variables available will be _,__,___ and _1\n'
569 'The only history variables available will be _,__,___ and _1\n'
568 'with the current result.')
570 'with the current result.')
569 # delete auto-generated vars from global namespace
571 # delete auto-generated vars from global namespace
570 for n in range(1,self.prompt_count + 1):
572 for n in range(1,self.prompt_count + 1):
571 key = '_'+`n`
573 key = '_'+`n`
572 try:
574 try:
573 del self.user_ns[key]
575 del self.user_ns[key]
574 except: pass
576 except: pass
575 self.prompt_count = 1
577 self.prompt_count = 1
576 self.cache_count = 1
578 self.cache_count = 1
@@ -1,1609 +1,1609 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 General purpose utilities.
3 General purpose utilities.
4
4
5 This is a grab-bag of stuff I find useful in most programs I write. Some of
5 This is a grab-bag of stuff I find useful in most programs I write. Some of
6 these things are also convenient when working at the command line.
6 these things are also convenient when working at the command line.
7
7
8 $Id: genutils.py 958 2005-12-27 23:17:51Z fperez $"""
8 $Id: genutils.py 960 2005-12-28 06:51:01Z fperez $"""
9
9
10 #*****************************************************************************
10 #*****************************************************************************
11 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
11 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
12 #
12 #
13 # Distributed under the terms of the BSD License. The full license is in
13 # Distributed under the terms of the BSD License. The full license is in
14 # the file COPYING, distributed as part of this software.
14 # the file COPYING, distributed as part of this software.
15 #*****************************************************************************
15 #*****************************************************************************
16
16
17 from __future__ import generators # 2.2 compatibility
17 from __future__ import generators # 2.2 compatibility
18
18
19 from IPython import Release
19 from IPython import Release
20 __author__ = '%s <%s>' % Release.authors['Fernando']
20 __author__ = '%s <%s>' % Release.authors['Fernando']
21 __license__ = Release.license
21 __license__ = Release.license
22
22
23 #****************************************************************************
23 #****************************************************************************
24 # required modules from the Python standard library
24 # required modules from the Python standard library
25 import __main__
25 import __main__
26 import commands
26 import commands
27 import os
27 import os
28 import re
28 import re
29 import shlex
29 import shlex
30 import shutil
30 import shutil
31 import sys
31 import sys
32 import tempfile
32 import tempfile
33 import time
33 import time
34 import types
34 import types
35
35
36 # Other IPython utilities
36 # Other IPython utilities
37 from IPython.Itpl import Itpl,itpl,printpl
37 from IPython.Itpl import Itpl,itpl,printpl
38 from IPython import DPyGetOpt
38 from IPython import DPyGetOpt
39
39
40 # Build objects which appeared in Python 2.3 for 2.2, to make ipython
40 # Build objects which appeared in Python 2.3 for 2.2, to make ipython
41 # 2.2-friendly
41 # 2.2-friendly
42 try:
42 try:
43 basestring
43 basestring
44 except NameError:
44 except NameError:
45 import types
45 import types
46 basestring = (types.StringType, types.UnicodeType)
46 basestring = (types.StringType, types.UnicodeType)
47 True = 1==1
47 True = 1==1
48 False = 1==0
48 False = 1==0
49
49
50 def enumerate(obj):
50 def enumerate(obj):
51 i = -1
51 i = -1
52 for item in obj:
52 for item in obj:
53 i += 1
53 i += 1
54 yield i, item
54 yield i, item
55
55
56 # add these to the builtin namespace, so that all modules find them
56 # add these to the builtin namespace, so that all modules find them
57 import __builtin__
57 import __builtin__
58 __builtin__.basestring = basestring
58 __builtin__.basestring = basestring
59 __builtin__.True = True
59 __builtin__.True = True
60 __builtin__.False = False
60 __builtin__.False = False
61 __builtin__.enumerate = enumerate
61 __builtin__.enumerate = enumerate
62
62
63 # Try to use shlex.split for converting an input string into a sys.argv-type
63 # Try to use shlex.split for converting an input string into a sys.argv-type
64 # list. This appeared in Python 2.3, so here's a quick backport for 2.2.
64 # list. This appeared in Python 2.3, so here's a quick backport for 2.2.
65 try:
65 try:
66 shlex_split = shlex.split
66 shlex_split = shlex.split
67 except AttributeError:
67 except AttributeError:
68 _quotesre = re.compile(r'[\'"](.*)[\'"]')
68 _quotesre = re.compile(r'[\'"](.*)[\'"]')
69 _wordchars = ('abcdfeghijklmnopqrstuvwxyz'
69 _wordchars = ('abcdfeghijklmnopqrstuvwxyz'
70 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.~*?'
70 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.~*?'
71 'ßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ'
71 'ßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ'
72 'ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ%s'
72 'ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ%s'
73 % os.sep)
73 % os.sep)
74
74
75 def shlex_split(s):
75 def shlex_split(s):
76 """Simplified backport to Python 2.2 of shlex.split().
76 """Simplified backport to Python 2.2 of shlex.split().
77
77
78 This is a quick and dirty hack, since the shlex module under 2.2 lacks
78 This is a quick and dirty hack, since the shlex module under 2.2 lacks
79 several of the features needed to really match the functionality of
79 several of the features needed to really match the functionality of
80 shlex.split() in 2.3."""
80 shlex.split() in 2.3."""
81
81
82 lex = shlex.shlex(StringIO(s))
82 lex = shlex.shlex(StringIO(s))
83 # Try to get options, extensions and path separators as characters
83 # Try to get options, extensions and path separators as characters
84 lex.wordchars = _wordchars
84 lex.wordchars = _wordchars
85 lex.commenters = ''
85 lex.commenters = ''
86 # Make a list out of the lexer by hand, since in 2.2 it's not an
86 # Make a list out of the lexer by hand, since in 2.2 it's not an
87 # iterator.
87 # iterator.
88 lout = []
88 lout = []
89 while 1:
89 while 1:
90 token = lex.get_token()
90 token = lex.get_token()
91 if token == '':
91 if token == '':
92 break
92 break
93 # Try to handle quoted tokens correctly
93 # Try to handle quoted tokens correctly
94 quotes = _quotesre.match(token)
94 quotes = _quotesre.match(token)
95 if quotes:
95 if quotes:
96 token = quotes.group(1)
96 token = quotes.group(1)
97 lout.append(token)
97 lout.append(token)
98 return lout
98 return lout
99
99
100 #****************************************************************************
100 #****************************************************************************
101 # Exceptions
101 # Exceptions
102 class Error(Exception):
102 class Error(Exception):
103 """Base class for exceptions in this module."""
103 """Base class for exceptions in this module."""
104 pass
104 pass
105
105
106 #----------------------------------------------------------------------------
106 #----------------------------------------------------------------------------
107 class IOStream:
107 class IOStream:
108 def __init__(self,stream,fallback):
108 def __init__(self,stream,fallback):
109 if not hasattr(stream,'write') or not hasattr(stream,'flush'):
109 if not hasattr(stream,'write') or not hasattr(stream,'flush'):
110 stream = fallback
110 stream = fallback
111 self.stream = stream
111 self.stream = stream
112 self._swrite = stream.write
112 self._swrite = stream.write
113 self.flush = stream.flush
113 self.flush = stream.flush
114
114
115 def write(self,data):
115 def write(self,data):
116 try:
116 try:
117 self._swrite(data)
117 self._swrite(data)
118 except:
118 except:
119 try:
119 try:
120 # print handles some unicode issues which may trip a plain
120 # print handles some unicode issues which may trip a plain
121 # write() call. Attempt to emulate write() by using a
121 # write() call. Attempt to emulate write() by using a
122 # trailing comma
122 # trailing comma
123 print >> self.stream, data,
123 print >> self.stream, data,
124 except:
124 except:
125 # if we get here, something is seriously broken.
125 # if we get here, something is seriously broken.
126 print >> sys.stderr, \
126 print >> sys.stderr, \
127 'ERROR - failed to write data to stream:', stream
127 'ERROR - failed to write data to stream:', stream
128
128
129 class IOTerm:
129 class IOTerm:
130 """ Term holds the file or file-like objects for handling I/O operations.
130 """ Term holds the file or file-like objects for handling I/O operations.
131
131
132 These are normally just sys.stdin, sys.stdout and sys.stderr but for
132 These are normally just sys.stdin, sys.stdout and sys.stderr but for
133 Windows they can can replaced to allow editing the strings before they are
133 Windows they can can replaced to allow editing the strings before they are
134 displayed."""
134 displayed."""
135
135
136 # In the future, having IPython channel all its I/O operations through
136 # In the future, having IPython channel all its I/O operations through
137 # this class will make it easier to embed it into other environments which
137 # this class will make it easier to embed it into other environments which
138 # are not a normal terminal (such as a GUI-based shell)
138 # are not a normal terminal (such as a GUI-based shell)
139 def __init__(self,cin=None,cout=None,cerr=None):
139 def __init__(self,cin=None,cout=None,cerr=None):
140 self.cin = IOStream(cin,sys.stdin)
140 self.cin = IOStream(cin,sys.stdin)
141 self.cout = IOStream(cout,sys.stdout)
141 self.cout = IOStream(cout,sys.stdout)
142 self.cerr = IOStream(cerr,sys.stderr)
142 self.cerr = IOStream(cerr,sys.stderr)
143
143
144 # Global variable to be used for all I/O
144 # Global variable to be used for all I/O
145 Term = IOTerm()
145 Term = IOTerm()
146
146
147 # Windows-specific code to load Gary Bishop's readline and configure it
147 # Windows-specific code to load Gary Bishop's readline and configure it
148 # automatically for the users
148 # automatically for the users
149 # Note: os.name on cygwin returns posix, so this should only pick up 'native'
149 # Note: os.name on cygwin returns posix, so this should only pick up 'native'
150 # windows. Cygwin returns 'cygwin' for sys.platform.
150 # windows. Cygwin returns 'cygwin' for sys.platform.
151 if os.name == 'nt':
151 if os.name == 'nt':
152 try:
152 try:
153 import readline
153 import readline
154 except ImportError:
154 except ImportError:
155 pass
155 pass
156 else:
156 else:
157 try:
157 try:
158 _out = readline.GetOutputFile()
158 _out = readline.GetOutputFile()
159 except AttributeError:
159 except AttributeError:
160 pass
160 pass
161 else:
161 else:
162 # Remake Term to use the readline i/o facilities
162 # Remake Term to use the readline i/o facilities
163 Term = IOTerm(cout=_out,cerr=_out)
163 Term = IOTerm(cout=_out,cerr=_out)
164 del _out
164 del _out
165
165
166 #****************************************************************************
166 #****************************************************************************
167 # Generic warning/error printer, used by everything else
167 # Generic warning/error printer, used by everything else
168 def warn(msg,level=2,exit_val=1):
168 def warn(msg,level=2,exit_val=1):
169 """Standard warning printer. Gives formatting consistency.
169 """Standard warning printer. Gives formatting consistency.
170
170
171 Output is sent to Term.cerr (sys.stderr by default).
171 Output is sent to Term.cerr (sys.stderr by default).
172
172
173 Options:
173 Options:
174
174
175 -level(2): allows finer control:
175 -level(2): allows finer control:
176 0 -> Do nothing, dummy function.
176 0 -> Do nothing, dummy function.
177 1 -> Print message.
177 1 -> Print message.
178 2 -> Print 'WARNING:' + message. (Default level).
178 2 -> Print 'WARNING:' + message. (Default level).
179 3 -> Print 'ERROR:' + message.
179 3 -> Print 'ERROR:' + message.
180 4 -> Print 'FATAL ERROR:' + message and trigger a sys.exit(exit_val).
180 4 -> Print 'FATAL ERROR:' + message and trigger a sys.exit(exit_val).
181
181
182 -exit_val (1): exit value returned by sys.exit() for a level 4
182 -exit_val (1): exit value returned by sys.exit() for a level 4
183 warning. Ignored for all other levels."""
183 warning. Ignored for all other levels."""
184
184
185 if level>0:
185 if level>0:
186 header = ['','','WARNING: ','ERROR: ','FATAL ERROR: ']
186 header = ['','','WARNING: ','ERROR: ','FATAL ERROR: ']
187 print >> Term.cerr, '%s%s' % (header[level],msg)
187 print >> Term.cerr, '%s%s' % (header[level],msg)
188 if level == 4:
188 if level == 4:
189 print >> Term.cerr,'Exiting.\n'
189 print >> Term.cerr,'Exiting.\n'
190 sys.exit(exit_val)
190 sys.exit(exit_val)
191
191
192 def info(msg):
192 def info(msg):
193 """Equivalent to warn(msg,level=1)."""
193 """Equivalent to warn(msg,level=1)."""
194
194
195 warn(msg,level=1)
195 warn(msg,level=1)
196
196
197 def error(msg):
197 def error(msg):
198 """Equivalent to warn(msg,level=3)."""
198 """Equivalent to warn(msg,level=3)."""
199
199
200 warn(msg,level=3)
200 warn(msg,level=3)
201
201
202 def fatal(msg,exit_val=1):
202 def fatal(msg,exit_val=1):
203 """Equivalent to warn(msg,exit_val=exit_val,level=4)."""
203 """Equivalent to warn(msg,exit_val=exit_val,level=4)."""
204
204
205 warn(msg,exit_val=exit_val,level=4)
205 warn(msg,exit_val=exit_val,level=4)
206
206
207 #----------------------------------------------------------------------------
207 #----------------------------------------------------------------------------
208 StringTypes = types.StringTypes
208 StringTypes = types.StringTypes
209
209
210 # Basic timing functionality
210 # Basic timing functionality
211
211
212 # If possible (Unix), use the resource module instead of time.clock()
212 # If possible (Unix), use the resource module instead of time.clock()
213 try:
213 try:
214 import resource
214 import resource
215 def clock():
215 def clock():
216 """clock() -> floating point number
216 """clock() -> floating point number
217
217
218 Return the CPU time in seconds (user time only, system time is
218 Return the CPU time in seconds (user time only, system time is
219 ignored) since the start of the process. This is done via a call to
219 ignored) since the start of the process. This is done via a call to
220 resource.getrusage, so it avoids the wraparound problems in
220 resource.getrusage, so it avoids the wraparound problems in
221 time.clock()."""
221 time.clock()."""
222
222
223 return resource.getrusage(resource.RUSAGE_SELF)[0]
223 return resource.getrusage(resource.RUSAGE_SELF)[0]
224
224
225 def clock2():
225 def clock2():
226 """clock2() -> (t_user,t_system)
226 """clock2() -> (t_user,t_system)
227
227
228 Similar to clock(), but return a tuple of user/system times."""
228 Similar to clock(), but return a tuple of user/system times."""
229 return resource.getrusage(resource.RUSAGE_SELF)[:2]
229 return resource.getrusage(resource.RUSAGE_SELF)[:2]
230
230
231 except ImportError:
231 except ImportError:
232 clock = time.clock
232 clock = time.clock
233 def clock2():
233 def clock2():
234 """Under windows, system CPU time can't be measured.
234 """Under windows, system CPU time can't be measured.
235
235
236 This just returns clock() and zero."""
236 This just returns clock() and zero."""
237 return time.clock(),0.0
237 return time.clock(),0.0
238
238
239 def timings_out(reps,func,*args,**kw):
239 def timings_out(reps,func,*args,**kw):
240 """timings_out(reps,func,*args,**kw) -> (t_total,t_per_call,output)
240 """timings_out(reps,func,*args,**kw) -> (t_total,t_per_call,output)
241
241
242 Execute a function reps times, return a tuple with the elapsed total
242 Execute a function reps times, return a tuple with the elapsed total
243 CPU time in seconds, the time per call and the function's output.
243 CPU time in seconds, the time per call and the function's output.
244
244
245 Under Unix, the return value is the sum of user+system time consumed by
245 Under Unix, the return value is the sum of user+system time consumed by
246 the process, computed via the resource module. This prevents problems
246 the process, computed via the resource module. This prevents problems
247 related to the wraparound effect which the time.clock() function has.
247 related to the wraparound effect which the time.clock() function has.
248
248
249 Under Windows the return value is in wall clock seconds. See the
249 Under Windows the return value is in wall clock seconds. See the
250 documentation for the time module for more details."""
250 documentation for the time module for more details."""
251
251
252 reps = int(reps)
252 reps = int(reps)
253 assert reps >=1, 'reps must be >= 1'
253 assert reps >=1, 'reps must be >= 1'
254 if reps==1:
254 if reps==1:
255 start = clock()
255 start = clock()
256 out = func(*args,**kw)
256 out = func(*args,**kw)
257 tot_time = clock()-start
257 tot_time = clock()-start
258 else:
258 else:
259 rng = xrange(reps-1) # the last time is executed separately to store output
259 rng = xrange(reps-1) # the last time is executed separately to store output
260 start = clock()
260 start = clock()
261 for dummy in rng: func(*args,**kw)
261 for dummy in rng: func(*args,**kw)
262 out = func(*args,**kw) # one last time
262 out = func(*args,**kw) # one last time
263 tot_time = clock()-start
263 tot_time = clock()-start
264 av_time = tot_time / reps
264 av_time = tot_time / reps
265 return tot_time,av_time,out
265 return tot_time,av_time,out
266
266
267 def timings(reps,func,*args,**kw):
267 def timings(reps,func,*args,**kw):
268 """timings(reps,func,*args,**kw) -> (t_total,t_per_call)
268 """timings(reps,func,*args,**kw) -> (t_total,t_per_call)
269
269
270 Execute a function reps times, return a tuple with the elapsed total CPU
270 Execute a function reps times, return a tuple with the elapsed total CPU
271 time in seconds and the time per call. These are just the first two values
271 time in seconds and the time per call. These are just the first two values
272 in timings_out()."""
272 in timings_out()."""
273
273
274 return timings_out(reps,func,*args,**kw)[0:2]
274 return timings_out(reps,func,*args,**kw)[0:2]
275
275
276 def timing(func,*args,**kw):
276 def timing(func,*args,**kw):
277 """timing(func,*args,**kw) -> t_total
277 """timing(func,*args,**kw) -> t_total
278
278
279 Execute a function once, return the elapsed total CPU time in
279 Execute a function once, return the elapsed total CPU time in
280 seconds. This is just the first value in timings_out()."""
280 seconds. This is just the first value in timings_out()."""
281
281
282 return timings_out(1,func,*args,**kw)[0]
282 return timings_out(1,func,*args,**kw)[0]
283
283
284 #****************************************************************************
284 #****************************************************************************
285 # file and system
285 # file and system
286
286
287 def system(cmd,verbose=0,debug=0,header=''):
287 def system(cmd,verbose=0,debug=0,header=''):
288 """Execute a system command, return its exit status.
288 """Execute a system command, return its exit status.
289
289
290 Options:
290 Options:
291
291
292 - verbose (0): print the command to be executed.
292 - verbose (0): print the command to be executed.
293
293
294 - debug (0): only print, do not actually execute.
294 - debug (0): only print, do not actually execute.
295
295
296 - header (''): Header to print on screen prior to the executed command (it
296 - header (''): Header to print on screen prior to the executed command (it
297 is only prepended to the command, no newlines are added).
297 is only prepended to the command, no newlines are added).
298
298
299 Note: a stateful version of this function is available through the
299 Note: a stateful version of this function is available through the
300 SystemExec class."""
300 SystemExec class."""
301
301
302 stat = 0
302 stat = 0
303 if verbose or debug: print header+cmd
303 if verbose or debug: print header+cmd
304 sys.stdout.flush()
304 sys.stdout.flush()
305 if not debug: stat = os.system(cmd)
305 if not debug: stat = os.system(cmd)
306 return stat
306 return stat
307
307
308 def shell(cmd,verbose=0,debug=0,header=''):
308 def shell(cmd,verbose=0,debug=0,header=''):
309 """Execute a command in the system shell, always return None.
309 """Execute a command in the system shell, always return None.
310
310
311 Options:
311 Options:
312
312
313 - verbose (0): print the command to be executed.
313 - verbose (0): print the command to be executed.
314
314
315 - debug (0): only print, do not actually execute.
315 - debug (0): only print, do not actually execute.
316
316
317 - header (''): Header to print on screen prior to the executed command (it
317 - header (''): Header to print on screen prior to the executed command (it
318 is only prepended to the command, no newlines are added).
318 is only prepended to the command, no newlines are added).
319
319
320 Note: this is similar to genutils.system(), but it returns None so it can
320 Note: this is similar to genutils.system(), but it returns None so it can
321 be conveniently used in interactive loops without getting the return value
321 be conveniently used in interactive loops without getting the return value
322 (typically 0) printed many times."""
322 (typically 0) printed many times."""
323
323
324 stat = 0
324 stat = 0
325 if verbose or debug: print header+cmd
325 if verbose or debug: print header+cmd
326 # flush stdout so we don't mangle python's buffering
326 # flush stdout so we don't mangle python's buffering
327 sys.stdout.flush()
327 sys.stdout.flush()
328 if not debug:
328 if not debug:
329 os.system(cmd)
329 os.system(cmd)
330
330
331 def getoutput(cmd,verbose=0,debug=0,header='',split=0):
331 def getoutput(cmd,verbose=0,debug=0,header='',split=0):
332 """Dummy substitute for perl's backquotes.
332 """Dummy substitute for perl's backquotes.
333
333
334 Executes a command and returns the output.
334 Executes a command and returns the output.
335
335
336 Accepts the same arguments as system(), plus:
336 Accepts the same arguments as system(), plus:
337
337
338 - split(0): if true, the output is returned as a list split on newlines.
338 - split(0): if true, the output is returned as a list split on newlines.
339
339
340 Note: a stateful version of this function is available through the
340 Note: a stateful version of this function is available through the
341 SystemExec class."""
341 SystemExec class."""
342
342
343 if verbose or debug: print header+cmd
343 if verbose or debug: print header+cmd
344 if not debug:
344 if not debug:
345 output = commands.getoutput(cmd)
345 output = commands.getoutput(cmd)
346 if split:
346 if split:
347 return output.split('\n')
347 return output.split('\n')
348 else:
348 else:
349 return output
349 return output
350
350
351 def getoutputerror(cmd,verbose=0,debug=0,header='',split=0):
351 def getoutputerror(cmd,verbose=0,debug=0,header='',split=0):
352 """Return (standard output,standard error) of executing cmd in a shell.
352 """Return (standard output,standard error) of executing cmd in a shell.
353
353
354 Accepts the same arguments as system(), plus:
354 Accepts the same arguments as system(), plus:
355
355
356 - split(0): if true, each of stdout/err is returned as a list split on
356 - split(0): if true, each of stdout/err is returned as a list split on
357 newlines.
357 newlines.
358
358
359 Note: a stateful version of this function is available through the
359 Note: a stateful version of this function is available through the
360 SystemExec class."""
360 SystemExec class."""
361
361
362 if verbose or debug: print header+cmd
362 if verbose or debug: print header+cmd
363 if not cmd:
363 if not cmd:
364 if split:
364 if split:
365 return [],[]
365 return [],[]
366 else:
366 else:
367 return '',''
367 return '',''
368 if not debug:
368 if not debug:
369 pin,pout,perr = os.popen3(cmd)
369 pin,pout,perr = os.popen3(cmd)
370 tout = pout.read().rstrip()
370 tout = pout.read().rstrip()
371 terr = perr.read().rstrip()
371 terr = perr.read().rstrip()
372 pin.close()
372 pin.close()
373 pout.close()
373 pout.close()
374 perr.close()
374 perr.close()
375 if split:
375 if split:
376 return tout.split('\n'),terr.split('\n')
376 return tout.split('\n'),terr.split('\n')
377 else:
377 else:
378 return tout,terr
378 return tout,terr
379
379
380 # for compatibility with older naming conventions
380 # for compatibility with older naming conventions
381 xsys = system
381 xsys = system
382 bq = getoutput
382 bq = getoutput
383
383
384 class SystemExec:
384 class SystemExec:
385 """Access the system and getoutput functions through a stateful interface.
385 """Access the system and getoutput functions through a stateful interface.
386
386
387 Note: here we refer to the system and getoutput functions from this
387 Note: here we refer to the system and getoutput functions from this
388 library, not the ones from the standard python library.
388 library, not the ones from the standard python library.
389
389
390 This class offers the system and getoutput functions as methods, but the
390 This class offers the system and getoutput functions as methods, but the
391 verbose, debug and header parameters can be set for the instance (at
391 verbose, debug and header parameters can be set for the instance (at
392 creation time or later) so that they don't need to be specified on each
392 creation time or later) so that they don't need to be specified on each
393 call.
393 call.
394
394
395 For efficiency reasons, there's no way to override the parameters on a
395 For efficiency reasons, there's no way to override the parameters on a
396 per-call basis other than by setting instance attributes. If you need
396 per-call basis other than by setting instance attributes. If you need
397 local overrides, it's best to directly call system() or getoutput().
397 local overrides, it's best to directly call system() or getoutput().
398
398
399 The following names are provided as alternate options:
399 The following names are provided as alternate options:
400 - xsys: alias to system
400 - xsys: alias to system
401 - bq: alias to getoutput
401 - bq: alias to getoutput
402
402
403 An instance can then be created as:
403 An instance can then be created as:
404 >>> sysexec = SystemExec(verbose=1,debug=0,header='Calling: ')
404 >>> sysexec = SystemExec(verbose=1,debug=0,header='Calling: ')
405
405
406 And used as:
406 And used as:
407 >>> sysexec.xsys('pwd')
407 >>> sysexec.xsys('pwd')
408 >>> dirlist = sysexec.bq('ls -l')
408 >>> dirlist = sysexec.bq('ls -l')
409 """
409 """
410
410
411 def __init__(self,verbose=0,debug=0,header='',split=0):
411 def __init__(self,verbose=0,debug=0,header='',split=0):
412 """Specify the instance's values for verbose, debug and header."""
412 """Specify the instance's values for verbose, debug and header."""
413 setattr_list(self,'verbose debug header split')
413 setattr_list(self,'verbose debug header split')
414
414
415 def system(self,cmd):
415 def system(self,cmd):
416 """Stateful interface to system(), with the same keyword parameters."""
416 """Stateful interface to system(), with the same keyword parameters."""
417
417
418 system(cmd,self.verbose,self.debug,self.header)
418 system(cmd,self.verbose,self.debug,self.header)
419
419
420 def shell(self,cmd):
420 def shell(self,cmd):
421 """Stateful interface to shell(), with the same keyword parameters."""
421 """Stateful interface to shell(), with the same keyword parameters."""
422
422
423 shell(cmd,self.verbose,self.debug,self.header)
423 shell(cmd,self.verbose,self.debug,self.header)
424
424
425 xsys = system # alias
425 xsys = system # alias
426
426
427 def getoutput(self,cmd):
427 def getoutput(self,cmd):
428 """Stateful interface to getoutput()."""
428 """Stateful interface to getoutput()."""
429
429
430 return getoutput(cmd,self.verbose,self.debug,self.header,self.split)
430 return getoutput(cmd,self.verbose,self.debug,self.header,self.split)
431
431
432 def getoutputerror(self,cmd):
432 def getoutputerror(self,cmd):
433 """Stateful interface to getoutputerror()."""
433 """Stateful interface to getoutputerror()."""
434
434
435 return getoutputerror(cmd,self.verbose,self.debug,self.header,self.split)
435 return getoutputerror(cmd,self.verbose,self.debug,self.header,self.split)
436
436
437 bq = getoutput # alias
437 bq = getoutput # alias
438
438
439 #-----------------------------------------------------------------------------
439 #-----------------------------------------------------------------------------
440 def mutex_opts(dict,ex_op):
440 def mutex_opts(dict,ex_op):
441 """Check for presence of mutually exclusive keys in a dict.
441 """Check for presence of mutually exclusive keys in a dict.
442
442
443 Call: mutex_opts(dict,[[op1a,op1b],[op2a,op2b]...]"""
443 Call: mutex_opts(dict,[[op1a,op1b],[op2a,op2b]...]"""
444 for op1,op2 in ex_op:
444 for op1,op2 in ex_op:
445 if op1 in dict and op2 in dict:
445 if op1 in dict and op2 in dict:
446 raise ValueError,'\n*** ERROR in Arguments *** '\
446 raise ValueError,'\n*** ERROR in Arguments *** '\
447 'Options '+op1+' and '+op2+' are mutually exclusive.'
447 'Options '+op1+' and '+op2+' are mutually exclusive.'
448
448
449 #-----------------------------------------------------------------------------
449 #-----------------------------------------------------------------------------
450 def get_py_filename(name):
450 def get_py_filename(name):
451 """Return a valid python filename in the current directory.
451 """Return a valid python filename in the current directory.
452
452
453 If the given name is not a file, it adds '.py' and searches again.
453 If the given name is not a file, it adds '.py' and searches again.
454 Raises IOError with an informative message if the file isn't found."""
454 Raises IOError with an informative message if the file isn't found."""
455
455
456 name = os.path.expanduser(name)
456 name = os.path.expanduser(name)
457 if not os.path.isfile(name) and not name.endswith('.py'):
457 if not os.path.isfile(name) and not name.endswith('.py'):
458 name += '.py'
458 name += '.py'
459 if os.path.isfile(name):
459 if os.path.isfile(name):
460 return name
460 return name
461 else:
461 else:
462 raise IOError,'File `%s` not found.' % name
462 raise IOError,'File `%s` not found.' % name
463
463
464 #-----------------------------------------------------------------------------
464 #-----------------------------------------------------------------------------
465 def filefind(fname,alt_dirs = None):
465 def filefind(fname,alt_dirs = None):
466 """Return the given filename either in the current directory, if it
466 """Return the given filename either in the current directory, if it
467 exists, or in a specified list of directories.
467 exists, or in a specified list of directories.
468
468
469 ~ expansion is done on all file and directory names.
469 ~ expansion is done on all file and directory names.
470
470
471 Upon an unsuccessful search, raise an IOError exception."""
471 Upon an unsuccessful search, raise an IOError exception."""
472
472
473 if alt_dirs is None:
473 if alt_dirs is None:
474 try:
474 try:
475 alt_dirs = get_home_dir()
475 alt_dirs = get_home_dir()
476 except HomeDirError:
476 except HomeDirError:
477 alt_dirs = os.getcwd()
477 alt_dirs = os.getcwd()
478 search = [fname] + list_strings(alt_dirs)
478 search = [fname] + list_strings(alt_dirs)
479 search = map(os.path.expanduser,search)
479 search = map(os.path.expanduser,search)
480 #print 'search list for',fname,'list:',search # dbg
480 #print 'search list for',fname,'list:',search # dbg
481 fname = search[0]
481 fname = search[0]
482 if os.path.isfile(fname):
482 if os.path.isfile(fname):
483 return fname
483 return fname
484 for direc in search[1:]:
484 for direc in search[1:]:
485 testname = os.path.join(direc,fname)
485 testname = os.path.join(direc,fname)
486 #print 'testname',testname # dbg
486 #print 'testname',testname # dbg
487 if os.path.isfile(testname):
487 if os.path.isfile(testname):
488 return testname
488 return testname
489 raise IOError,'File' + `fname` + \
489 raise IOError,'File' + `fname` + \
490 ' not found in current or supplied directories:' + `alt_dirs`
490 ' not found in current or supplied directories:' + `alt_dirs`
491
491
492 #----------------------------------------------------------------------------
492 #----------------------------------------------------------------------------
493 def file_read(filename):
493 def file_read(filename):
494 """Read a file and close it. Returns the file source."""
494 """Read a file and close it. Returns the file source."""
495 fobj=open(filename,'r');
495 fobj=open(filename,'r');
496 source = fobj.read();
496 source = fobj.read();
497 fobj.close()
497 fobj.close()
498 return source
498 return source
499
499
500 #----------------------------------------------------------------------------
500 #----------------------------------------------------------------------------
501 def target_outdated(target,deps):
501 def target_outdated(target,deps):
502 """Determine whether a target is out of date.
502 """Determine whether a target is out of date.
503
503
504 target_outdated(target,deps) -> 1/0
504 target_outdated(target,deps) -> 1/0
505
505
506 deps: list of filenames which MUST exist.
506 deps: list of filenames which MUST exist.
507 target: single filename which may or may not exist.
507 target: single filename which may or may not exist.
508
508
509 If target doesn't exist or is older than any file listed in deps, return
509 If target doesn't exist or is older than any file listed in deps, return
510 true, otherwise return false.
510 true, otherwise return false.
511 """
511 """
512 try:
512 try:
513 target_time = os.path.getmtime(target)
513 target_time = os.path.getmtime(target)
514 except os.error:
514 except os.error:
515 return 1
515 return 1
516 for dep in deps:
516 for dep in deps:
517 dep_time = os.path.getmtime(dep)
517 dep_time = os.path.getmtime(dep)
518 if dep_time > target_time:
518 if dep_time > target_time:
519 #print "For target",target,"Dep failed:",dep # dbg
519 #print "For target",target,"Dep failed:",dep # dbg
520 #print "times (dep,tar):",dep_time,target_time # dbg
520 #print "times (dep,tar):",dep_time,target_time # dbg
521 return 1
521 return 1
522 return 0
522 return 0
523
523
524 #-----------------------------------------------------------------------------
524 #-----------------------------------------------------------------------------
525 def target_update(target,deps,cmd):
525 def target_update(target,deps,cmd):
526 """Update a target with a given command given a list of dependencies.
526 """Update a target with a given command given a list of dependencies.
527
527
528 target_update(target,deps,cmd) -> runs cmd if target is outdated.
528 target_update(target,deps,cmd) -> runs cmd if target is outdated.
529
529
530 This is just a wrapper around target_outdated() which calls the given
530 This is just a wrapper around target_outdated() which calls the given
531 command if target is outdated."""
531 command if target is outdated."""
532
532
533 if target_outdated(target,deps):
533 if target_outdated(target,deps):
534 xsys(cmd)
534 xsys(cmd)
535
535
536 #----------------------------------------------------------------------------
536 #----------------------------------------------------------------------------
537 def unquote_ends(istr):
537 def unquote_ends(istr):
538 """Remove a single pair of quotes from the endpoints of a string."""
538 """Remove a single pair of quotes from the endpoints of a string."""
539
539
540 if not istr:
540 if not istr:
541 return istr
541 return istr
542 if (istr[0]=="'" and istr[-1]=="'") or \
542 if (istr[0]=="'" and istr[-1]=="'") or \
543 (istr[0]=='"' and istr[-1]=='"'):
543 (istr[0]=='"' and istr[-1]=='"'):
544 return istr[1:-1]
544 return istr[1:-1]
545 else:
545 else:
546 return istr
546 return istr
547
547
548 #----------------------------------------------------------------------------
548 #----------------------------------------------------------------------------
549 def process_cmdline(argv,names=[],defaults={},usage=''):
549 def process_cmdline(argv,names=[],defaults={},usage=''):
550 """ Process command-line options and arguments.
550 """ Process command-line options and arguments.
551
551
552 Arguments:
552 Arguments:
553
553
554 - argv: list of arguments, typically sys.argv.
554 - argv: list of arguments, typically sys.argv.
555
555
556 - names: list of option names. See DPyGetOpt docs for details on options
556 - names: list of option names. See DPyGetOpt docs for details on options
557 syntax.
557 syntax.
558
558
559 - defaults: dict of default values.
559 - defaults: dict of default values.
560
560
561 - usage: optional usage notice to print if a wrong argument is passed.
561 - usage: optional usage notice to print if a wrong argument is passed.
562
562
563 Return a dict of options and a list of free arguments."""
563 Return a dict of options and a list of free arguments."""
564
564
565 getopt = DPyGetOpt.DPyGetOpt()
565 getopt = DPyGetOpt.DPyGetOpt()
566 getopt.setIgnoreCase(0)
566 getopt.setIgnoreCase(0)
567 getopt.parseConfiguration(names)
567 getopt.parseConfiguration(names)
568
568
569 try:
569 try:
570 getopt.processArguments(argv)
570 getopt.processArguments(argv)
571 except:
571 except:
572 print usage
572 print usage
573 warn(`sys.exc_value`,level=4)
573 warn(`sys.exc_value`,level=4)
574
574
575 defaults.update(getopt.optionValues)
575 defaults.update(getopt.optionValues)
576 args = getopt.freeValues
576 args = getopt.freeValues
577
577
578 return defaults,args
578 return defaults,args
579
579
580 #----------------------------------------------------------------------------
580 #----------------------------------------------------------------------------
581 def optstr2types(ostr):
581 def optstr2types(ostr):
582 """Convert a string of option names to a dict of type mappings.
582 """Convert a string of option names to a dict of type mappings.
583
583
584 optstr2types(str) -> {None:'string_opts',int:'int_opts',float:'float_opts'}
584 optstr2types(str) -> {None:'string_opts',int:'int_opts',float:'float_opts'}
585
585
586 This is used to get the types of all the options in a string formatted
586 This is used to get the types of all the options in a string formatted
587 with the conventions of DPyGetOpt. The 'type' None is used for options
587 with the conventions of DPyGetOpt. The 'type' None is used for options
588 which are strings (they need no further conversion). This function's main
588 which are strings (they need no further conversion). This function's main
589 use is to get a typemap for use with read_dict().
589 use is to get a typemap for use with read_dict().
590 """
590 """
591
591
592 typeconv = {None:'',int:'',float:''}
592 typeconv = {None:'',int:'',float:''}
593 typemap = {'s':None,'i':int,'f':float}
593 typemap = {'s':None,'i':int,'f':float}
594 opt_re = re.compile(r'([\w]*)([^:=]*:?=?)([sif]?)')
594 opt_re = re.compile(r'([\w]*)([^:=]*:?=?)([sif]?)')
595
595
596 for w in ostr.split():
596 for w in ostr.split():
597 oname,alias,otype = opt_re.match(w).groups()
597 oname,alias,otype = opt_re.match(w).groups()
598 if otype == '' or alias == '!': # simple switches are integers too
598 if otype == '' or alias == '!': # simple switches are integers too
599 otype = 'i'
599 otype = 'i'
600 typeconv[typemap[otype]] += oname + ' '
600 typeconv[typemap[otype]] += oname + ' '
601 return typeconv
601 return typeconv
602
602
603 #----------------------------------------------------------------------------
603 #----------------------------------------------------------------------------
604 def read_dict(filename,type_conv=None,**opt):
604 def read_dict(filename,type_conv=None,**opt):
605
605
606 """Read a dictionary of key=value pairs from an input file, optionally
606 """Read a dictionary of key=value pairs from an input file, optionally
607 performing conversions on the resulting values.
607 performing conversions on the resulting values.
608
608
609 read_dict(filename,type_conv,**opt) -> dict
609 read_dict(filename,type_conv,**opt) -> dict
610
610
611 Only one value per line is accepted, the format should be
611 Only one value per line is accepted, the format should be
612 # optional comments are ignored
612 # optional comments are ignored
613 key value\n
613 key value\n
614
614
615 Args:
615 Args:
616
616
617 - type_conv: A dictionary specifying which keys need to be converted to
617 - type_conv: A dictionary specifying which keys need to be converted to
618 which types. By default all keys are read as strings. This dictionary
618 which types. By default all keys are read as strings. This dictionary
619 should have as its keys valid conversion functions for strings
619 should have as its keys valid conversion functions for strings
620 (int,long,float,complex, or your own). The value for each key
620 (int,long,float,complex, or your own). The value for each key
621 (converter) should be a whitespace separated string containing the names
621 (converter) should be a whitespace separated string containing the names
622 of all the entries in the file to be converted using that function. For
622 of all the entries in the file to be converted using that function. For
623 keys to be left alone, use None as the conversion function (only needed
623 keys to be left alone, use None as the conversion function (only needed
624 with purge=1, see below).
624 with purge=1, see below).
625
625
626 - opt: dictionary with extra options as below (default in parens)
626 - opt: dictionary with extra options as below (default in parens)
627
627
628 purge(0): if set to 1, all keys *not* listed in type_conv are purged out
628 purge(0): if set to 1, all keys *not* listed in type_conv are purged out
629 of the dictionary to be returned. If purge is going to be used, the
629 of the dictionary to be returned. If purge is going to be used, the
630 set of keys to be left as strings also has to be explicitly specified
630 set of keys to be left as strings also has to be explicitly specified
631 using the (non-existent) conversion function None.
631 using the (non-existent) conversion function None.
632
632
633 fs(None): field separator. This is the key/value separator to be used
633 fs(None): field separator. This is the key/value separator to be used
634 when parsing the file. The None default means any whitespace [behavior
634 when parsing the file. The None default means any whitespace [behavior
635 of string.split()].
635 of string.split()].
636
636
637 strip(0): if 1, strip string values of leading/trailinig whitespace.
637 strip(0): if 1, strip string values of leading/trailinig whitespace.
638
638
639 warn(1): warning level if requested keys are not found in file.
639 warn(1): warning level if requested keys are not found in file.
640 - 0: silently ignore.
640 - 0: silently ignore.
641 - 1: inform but proceed.
641 - 1: inform but proceed.
642 - 2: raise KeyError exception.
642 - 2: raise KeyError exception.
643
643
644 no_empty(0): if 1, remove keys with whitespace strings as a value.
644 no_empty(0): if 1, remove keys with whitespace strings as a value.
645
645
646 unique([]): list of keys (or space separated string) which can't be
646 unique([]): list of keys (or space separated string) which can't be
647 repeated. If one such key is found in the file, each new instance
647 repeated. If one such key is found in the file, each new instance
648 overwrites the previous one. For keys not listed here, the behavior is
648 overwrites the previous one. For keys not listed here, the behavior is
649 to make a list of all appearances.
649 to make a list of all appearances.
650
650
651 Example:
651 Example:
652 If the input file test.ini has:
652 If the input file test.ini has:
653 i 3
653 i 3
654 x 4.5
654 x 4.5
655 y 5.5
655 y 5.5
656 s hi ho
656 s hi ho
657 Then:
657 Then:
658
658
659 >>> type_conv={int:'i',float:'x',None:'s'}
659 >>> type_conv={int:'i',float:'x',None:'s'}
660 >>> read_dict('test.ini')
660 >>> read_dict('test.ini')
661 {'i': '3', 's': 'hi ho', 'x': '4.5', 'y': '5.5'}
661 {'i': '3', 's': 'hi ho', 'x': '4.5', 'y': '5.5'}
662 >>> read_dict('test.ini',type_conv)
662 >>> read_dict('test.ini',type_conv)
663 {'i': 3, 's': 'hi ho', 'x': 4.5, 'y': '5.5'}
663 {'i': 3, 's': 'hi ho', 'x': 4.5, 'y': '5.5'}
664 >>> read_dict('test.ini',type_conv,purge=1)
664 >>> read_dict('test.ini',type_conv,purge=1)
665 {'i': 3, 's': 'hi ho', 'x': 4.5}
665 {'i': 3, 's': 'hi ho', 'x': 4.5}
666 """
666 """
667
667
668 # starting config
668 # starting config
669 opt.setdefault('purge',0)
669 opt.setdefault('purge',0)
670 opt.setdefault('fs',None) # field sep defaults to any whitespace
670 opt.setdefault('fs',None) # field sep defaults to any whitespace
671 opt.setdefault('strip',0)
671 opt.setdefault('strip',0)
672 opt.setdefault('warn',1)
672 opt.setdefault('warn',1)
673 opt.setdefault('no_empty',0)
673 opt.setdefault('no_empty',0)
674 opt.setdefault('unique','')
674 opt.setdefault('unique','')
675 if type(opt['unique']) in StringTypes:
675 if type(opt['unique']) in StringTypes:
676 unique_keys = qw(opt['unique'])
676 unique_keys = qw(opt['unique'])
677 elif type(opt['unique']) in (types.TupleType,types.ListType):
677 elif type(opt['unique']) in (types.TupleType,types.ListType):
678 unique_keys = opt['unique']
678 unique_keys = opt['unique']
679 else:
679 else:
680 raise ValueError, 'Unique keys must be given as a string, List or Tuple'
680 raise ValueError, 'Unique keys must be given as a string, List or Tuple'
681
681
682 dict = {}
682 dict = {}
683 # first read in table of values as strings
683 # first read in table of values as strings
684 file = open(filename,'r')
684 file = open(filename,'r')
685 for line in file.readlines():
685 for line in file.readlines():
686 line = line.strip()
686 line = line.strip()
687 if len(line) and line[0]=='#': continue
687 if len(line) and line[0]=='#': continue
688 if len(line)>0:
688 if len(line)>0:
689 lsplit = line.split(opt['fs'],1)
689 lsplit = line.split(opt['fs'],1)
690 try:
690 try:
691 key,val = lsplit
691 key,val = lsplit
692 except ValueError:
692 except ValueError:
693 key,val = lsplit[0],''
693 key,val = lsplit[0],''
694 key = key.strip()
694 key = key.strip()
695 if opt['strip']: val = val.strip()
695 if opt['strip']: val = val.strip()
696 if val == "''" or val == '""': val = ''
696 if val == "''" or val == '""': val = ''
697 if opt['no_empty'] and (val=='' or val.isspace()):
697 if opt['no_empty'] and (val=='' or val.isspace()):
698 continue
698 continue
699 # if a key is found more than once in the file, build a list
699 # if a key is found more than once in the file, build a list
700 # unless it's in the 'unique' list. In that case, last found in file
700 # unless it's in the 'unique' list. In that case, last found in file
701 # takes precedence. User beware.
701 # takes precedence. User beware.
702 try:
702 try:
703 if dict[key] and key in unique_keys:
703 if dict[key] and key in unique_keys:
704 dict[key] = val
704 dict[key] = val
705 elif type(dict[key]) is types.ListType:
705 elif type(dict[key]) is types.ListType:
706 dict[key].append(val)
706 dict[key].append(val)
707 else:
707 else:
708 dict[key] = [dict[key],val]
708 dict[key] = [dict[key],val]
709 except KeyError:
709 except KeyError:
710 dict[key] = val
710 dict[key] = val
711 # purge if requested
711 # purge if requested
712 if opt['purge']:
712 if opt['purge']:
713 accepted_keys = qwflat(type_conv.values())
713 accepted_keys = qwflat(type_conv.values())
714 for key in dict.keys():
714 for key in dict.keys():
715 if key in accepted_keys: continue
715 if key in accepted_keys: continue
716 del(dict[key])
716 del(dict[key])
717 # now convert if requested
717 # now convert if requested
718 if type_conv==None: return dict
718 if type_conv==None: return dict
719 conversions = type_conv.keys()
719 conversions = type_conv.keys()
720 try: conversions.remove(None)
720 try: conversions.remove(None)
721 except: pass
721 except: pass
722 for convert in conversions:
722 for convert in conversions:
723 for val in qw(type_conv[convert]):
723 for val in qw(type_conv[convert]):
724 try:
724 try:
725 dict[val] = convert(dict[val])
725 dict[val] = convert(dict[val])
726 except KeyError,e:
726 except KeyError,e:
727 if opt['warn'] == 0:
727 if opt['warn'] == 0:
728 pass
728 pass
729 elif opt['warn'] == 1:
729 elif opt['warn'] == 1:
730 print >>sys.stderr, 'Warning: key',val,\
730 print >>sys.stderr, 'Warning: key',val,\
731 'not found in file',filename
731 'not found in file',filename
732 elif opt['warn'] == 2:
732 elif opt['warn'] == 2:
733 raise KeyError,e
733 raise KeyError,e
734 else:
734 else:
735 raise ValueError,'Warning level must be 0,1 or 2'
735 raise ValueError,'Warning level must be 0,1 or 2'
736
736
737 return dict
737 return dict
738
738
739 #----------------------------------------------------------------------------
739 #----------------------------------------------------------------------------
740 def flag_calls(func):
740 def flag_calls(func):
741 """Wrap a function to detect and flag when it gets called.
741 """Wrap a function to detect and flag when it gets called.
742
742
743 This is a decorator which takes a function and wraps it in a function with
743 This is a decorator which takes a function and wraps it in a function with
744 a 'called' attribute. wrapper.called is initialized to False.
744 a 'called' attribute. wrapper.called is initialized to False.
745
745
746 The wrapper.called attribute is set to False right before each call to the
746 The wrapper.called attribute is set to False right before each call to the
747 wrapped function, so if the call fails it remains False. After the call
747 wrapped function, so if the call fails it remains False. After the call
748 completes, wrapper.called is set to True and the output is returned.
748 completes, wrapper.called is set to True and the output is returned.
749
749
750 Testing for truth in wrapper.called allows you to determine if a call to
750 Testing for truth in wrapper.called allows you to determine if a call to
751 func() was attempted and succeeded."""
751 func() was attempted and succeeded."""
752
752
753 def wrapper(*args,**kw):
753 def wrapper(*args,**kw):
754 wrapper.called = False
754 wrapper.called = False
755 out = func(*args,**kw)
755 out = func(*args,**kw)
756 wrapper.called = True
756 wrapper.called = True
757 return out
757 return out
758
758
759 wrapper.called = False
759 wrapper.called = False
760 wrapper.__doc__ = func.__doc__
760 wrapper.__doc__ = func.__doc__
761 return wrapper
761 return wrapper
762
762
763 #----------------------------------------------------------------------------
763 #----------------------------------------------------------------------------
764 class HomeDirError(Error):
764 class HomeDirError(Error):
765 pass
765 pass
766
766
767 def get_home_dir():
767 def get_home_dir():
768 """Return the closest possible equivalent to a 'home' directory.
768 """Return the closest possible equivalent to a 'home' directory.
769
769
770 We first try $HOME. Absent that, on NT it's $HOMEDRIVE\$HOMEPATH.
770 We first try $HOME. Absent that, on NT it's $HOMEDRIVE\$HOMEPATH.
771
771
772 Currently only Posix and NT are implemented, a HomeDirError exception is
772 Currently only Posix and NT are implemented, a HomeDirError exception is
773 raised for all other OSes. """
773 raised for all other OSes. """
774
774
775 isdir = os.path.isdir
775 isdir = os.path.isdir
776 env = os.environ
776 env = os.environ
777 try:
777 try:
778 homedir = env['HOME']
778 homedir = env['HOME']
779 if not isdir(homedir):
779 if not isdir(homedir):
780 # in case a user stuck some string which does NOT resolve to a
780 # in case a user stuck some string which does NOT resolve to a
781 # valid path, it's as good as if we hadn't foud it
781 # valid path, it's as good as if we hadn't foud it
782 raise KeyError
782 raise KeyError
783 return homedir
783 return homedir
784 except KeyError:
784 except KeyError:
785 if os.name == 'posix':
785 if os.name == 'posix':
786 raise HomeDirError,'undefined $HOME, IPython can not proceed.'
786 raise HomeDirError,'undefined $HOME, IPython can not proceed.'
787 elif os.name == 'nt':
787 elif os.name == 'nt':
788 # For some strange reason, win9x returns 'nt' for os.name.
788 # For some strange reason, win9x returns 'nt' for os.name.
789 try:
789 try:
790 homedir = os.path.join(env['HOMEDRIVE'],env['HOMEPATH'])
790 homedir = os.path.join(env['HOMEDRIVE'],env['HOMEPATH'])
791 if not isdir(homedir):
791 if not isdir(homedir):
792 homedir = os.path.join(env['USERPROFILE'])
792 homedir = os.path.join(env['USERPROFILE'])
793 if not isdir(homedir):
793 if not isdir(homedir):
794 raise HomeDirError
794 raise HomeDirError
795 return homedir
795 return homedir
796 except:
796 except:
797 try:
797 try:
798 # Use the registry to get the 'My Documents' folder.
798 # Use the registry to get the 'My Documents' folder.
799 import _winreg as wreg
799 import _winreg as wreg
800 key = wreg.OpenKey(wreg.HKEY_CURRENT_USER,
800 key = wreg.OpenKey(wreg.HKEY_CURRENT_USER,
801 "Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
801 "Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
802 homedir = wreg.QueryValueEx(key,'Personal')[0]
802 homedir = wreg.QueryValueEx(key,'Personal')[0]
803 key.Close()
803 key.Close()
804 if not isdir(homedir):
804 if not isdir(homedir):
805 e = ('Invalid "Personal" folder registry key '
805 e = ('Invalid "Personal" folder registry key '
806 'typically "My Documents".\n'
806 'typically "My Documents".\n'
807 'Value: %s\n'
807 'Value: %s\n'
808 'This is not a valid directory on your system.' %
808 'This is not a valid directory on your system.' %
809 homedir)
809 homedir)
810 raise HomeDirError(e)
810 raise HomeDirError(e)
811 return homedir
811 return homedir
812 except HomeDirError:
812 except HomeDirError:
813 raise
813 raise
814 except:
814 except:
815 return 'C:\\'
815 return 'C:\\'
816 elif os.name == 'dos':
816 elif os.name == 'dos':
817 # Desperate, may do absurd things in classic MacOS. May work under DOS.
817 # Desperate, may do absurd things in classic MacOS. May work under DOS.
818 return 'C:\\'
818 return 'C:\\'
819 else:
819 else:
820 raise HomeDirError,'support for your operating system not implemented.'
820 raise HomeDirError,'support for your operating system not implemented.'
821
821
822 #****************************************************************************
822 #****************************************************************************
823 # strings and text
823 # strings and text
824
824
825 class LSString(str):
825 class LSString(str):
826 """String derivative with a special access attributes.
826 """String derivative with a special access attributes.
827
827
828 These are normal strings, but with the special attributes:
828 These are normal strings, but with the special attributes:
829
829
830 .l (or .list) : value as list (split on newlines).
830 .l (or .list) : value as list (split on newlines).
831 .n (or .nlstr): original value (the string itself).
831 .n (or .nlstr): original value (the string itself).
832 .s (or .spstr): value as whitespace-separated string.
832 .s (or .spstr): value as whitespace-separated string.
833
833
834 Any values which require transformations are computed only once and
834 Any values which require transformations are computed only once and
835 cached.
835 cached.
836
836
837 Such strings are very useful to efficiently interact with the shell, which
837 Such strings are very useful to efficiently interact with the shell, which
838 typically only understands whitespace-separated options for commands."""
838 typically only understands whitespace-separated options for commands."""
839
839
840 def get_list(self):
840 def get_list(self):
841 try:
841 try:
842 return self.__list
842 return self.__list
843 except AttributeError:
843 except AttributeError:
844 self.__list = self.split('\n')
844 self.__list = self.split('\n')
845 return self.__list
845 return self.__list
846
846
847 l = list = property(get_list)
847 l = list = property(get_list)
848
848
849 def get_spstr(self):
849 def get_spstr(self):
850 try:
850 try:
851 return self.__spstr
851 return self.__spstr
852 except AttributeError:
852 except AttributeError:
853 self.__spstr = self.replace('\n',' ')
853 self.__spstr = self.replace('\n',' ')
854 return self.__spstr
854 return self.__spstr
855
855
856 s = spstr = property(get_spstr)
856 s = spstr = property(get_spstr)
857
857
858 def get_nlstr(self):
858 def get_nlstr(self):
859 return self
859 return self
860
860
861 n = nlstr = property(get_nlstr)
861 n = nlstr = property(get_nlstr)
862
862
863 class SList(list):
863 class SList(list):
864 """List derivative with a special access attributes.
864 """List derivative with a special access attributes.
865
865
866 These are normal lists, but with the special attributes:
866 These are normal lists, but with the special attributes:
867
867
868 .l (or .list) : value as list (the list itself).
868 .l (or .list) : value as list (the list itself).
869 .n (or .nlstr): value as a string, joined on newlines.
869 .n (or .nlstr): value as a string, joined on newlines.
870 .s (or .spstr): value as a string, joined on spaces.
870 .s (or .spstr): value as a string, joined on spaces.
871
871
872 Any values which require transformations are computed only once and
872 Any values which require transformations are computed only once and
873 cached."""
873 cached."""
874
874
875 def get_list(self):
875 def get_list(self):
876 return self
876 return self
877
877
878 l = list = property(get_list)
878 l = list = property(get_list)
879
879
880 def get_spstr(self):
880 def get_spstr(self):
881 try:
881 try:
882 return self.__spstr
882 return self.__spstr
883 except AttributeError:
883 except AttributeError:
884 self.__spstr = ' '.join(self)
884 self.__spstr = ' '.join(self)
885 return self.__spstr
885 return self.__spstr
886
886
887 s = spstr = property(get_spstr)
887 s = spstr = property(get_spstr)
888
888
889 def get_nlstr(self):
889 def get_nlstr(self):
890 try:
890 try:
891 return self.__nlstr
891 return self.__nlstr
892 except AttributeError:
892 except AttributeError:
893 self.__nlstr = '\n'.join(self)
893 self.__nlstr = '\n'.join(self)
894 return self.__nlstr
894 return self.__nlstr
895
895
896 n = nlstr = property(get_nlstr)
896 n = nlstr = property(get_nlstr)
897
897
898 def raw_input_multi(header='', ps1='==> ', ps2='..> ',terminate_str = '.'):
898 def raw_input_multi(header='', ps1='==> ', ps2='..> ',terminate_str = '.'):
899 """Take multiple lines of input.
899 """Take multiple lines of input.
900
900
901 A list with each line of input as a separate element is returned when a
901 A list with each line of input as a separate element is returned when a
902 termination string is entered (defaults to a single '.'). Input can also
902 termination string is entered (defaults to a single '.'). Input can also
903 terminate via EOF (^D in Unix, ^Z-RET in Windows).
903 terminate via EOF (^D in Unix, ^Z-RET in Windows).
904
904
905 Lines of input which end in \\ are joined into single entries (and a
905 Lines of input which end in \\ are joined into single entries (and a
906 secondary continuation prompt is issued as long as the user terminates
906 secondary continuation prompt is issued as long as the user terminates
907 lines with \\). This allows entering very long strings which are still
907 lines with \\). This allows entering very long strings which are still
908 meant to be treated as single entities.
908 meant to be treated as single entities.
909 """
909 """
910
910
911 try:
911 try:
912 if header:
912 if header:
913 header += '\n'
913 header += '\n'
914 lines = [raw_input(header + ps1)]
914 lines = [raw_input(header + ps1)]
915 except EOFError:
915 except EOFError:
916 return []
916 return []
917 terminate = [terminate_str]
917 terminate = [terminate_str]
918 try:
918 try:
919 while lines[-1:] != terminate:
919 while lines[-1:] != terminate:
920 new_line = raw_input(ps1)
920 new_line = raw_input(ps1)
921 while new_line.endswith('\\'):
921 while new_line.endswith('\\'):
922 new_line = new_line[:-1] + raw_input(ps2)
922 new_line = new_line[:-1] + raw_input(ps2)
923 lines.append(new_line)
923 lines.append(new_line)
924
924
925 return lines[:-1] # don't return the termination command
925 return lines[:-1] # don't return the termination command
926 except EOFError:
926 except EOFError:
927 print
927 print
928 return lines
928 return lines
929
929
930 #----------------------------------------------------------------------------
930 #----------------------------------------------------------------------------
931 def raw_input_ext(prompt='', ps2='... '):
931 def raw_input_ext(prompt='', ps2='... '):
932 """Similar to raw_input(), but accepts extended lines if input ends with \\."""
932 """Similar to raw_input(), but accepts extended lines if input ends with \\."""
933
933
934 line = raw_input(prompt)
934 line = raw_input(prompt)
935 while line.endswith('\\'):
935 while line.endswith('\\'):
936 line = line[:-1] + raw_input(ps2)
936 line = line[:-1] + raw_input(ps2)
937 return line
937 return line
938
938
939 #----------------------------------------------------------------------------
939 #----------------------------------------------------------------------------
940 def ask_yes_no(prompt,default=None):
940 def ask_yes_no(prompt,default=None):
941 """Asks a question and returns an integer 1/0 (y/n) answer.
941 """Asks a question and returns an integer 1/0 (y/n) answer.
942
942
943 If default is given (one of 'y','n'), it is used if the user input is
943 If default is given (one of 'y','n'), it is used if the user input is
944 empty. Otherwise the question is repeated until an answer is given.
944 empty. Otherwise the question is repeated until an answer is given.
945 If EOF occurs 20 times consecutively, the default answer is assumed,
945 If EOF occurs 20 times consecutively, the default answer is assumed,
946 or if there is no default, an exception is raised to prevent infinite
946 or if there is no default, an exception is raised to prevent infinite
947 loops.
947 loops.
948
948
949 Valid answers are: y/yes/n/no (match is not case sensitive)."""
949 Valid answers are: y/yes/n/no (match is not case sensitive)."""
950
950
951 answers = {'y':1,'n':0,'yes':1,'no':0}
951 answers = {'y':True,'n':False,'yes':True,'no':False}
952 ans = None
952 ans = None
953 eofs, max_eofs = 0, 20
953 eofs, max_eofs = 0, 20
954 while ans not in answers.keys():
954 while ans not in answers.keys():
955 try:
955 try:
956 ans = raw_input(prompt+' ').lower()
956 ans = raw_input(prompt+' ').lower()
957 if not ans: # response was an empty string
957 if not ans: # response was an empty string
958 ans = default
958 ans = default
959 eofs = 0
959 eofs = 0
960 except (EOFError,KeyboardInterrupt):
960 except (EOFError,KeyboardInterrupt):
961 eofs = eofs + 1
961 eofs = eofs + 1
962 if eofs >= max_eofs:
962 if eofs >= max_eofs:
963 if default in answers.keys():
963 if default in answers.keys():
964 ans = default
964 ans = default
965 else:
965 else:
966 raise
966 raise
967
967
968 return answers[ans]
968 return answers[ans]
969
969
970 #----------------------------------------------------------------------------
970 #----------------------------------------------------------------------------
971 def marquee(txt='',width=78,mark='*'):
971 def marquee(txt='',width=78,mark='*'):
972 """Return the input string centered in a 'marquee'."""
972 """Return the input string centered in a 'marquee'."""
973 if not txt:
973 if not txt:
974 return (mark*width)[:width]
974 return (mark*width)[:width]
975 nmark = (width-len(txt)-2)/len(mark)/2
975 nmark = (width-len(txt)-2)/len(mark)/2
976 if nmark < 0: nmark =0
976 if nmark < 0: nmark =0
977 marks = mark*nmark
977 marks = mark*nmark
978 return '%s %s %s' % (marks,txt,marks)
978 return '%s %s %s' % (marks,txt,marks)
979
979
980 #----------------------------------------------------------------------------
980 #----------------------------------------------------------------------------
981 class EvalDict:
981 class EvalDict:
982 """
982 """
983 Emulate a dict which evaluates its contents in the caller's frame.
983 Emulate a dict which evaluates its contents in the caller's frame.
984
984
985 Usage:
985 Usage:
986 >>>number = 19
986 >>>number = 19
987 >>>text = "python"
987 >>>text = "python"
988 >>>print "%(text.capitalize())s %(number/9.0).1f rules!" % EvalDict()
988 >>>print "%(text.capitalize())s %(number/9.0).1f rules!" % EvalDict()
989 """
989 """
990
990
991 # This version is due to sismex01@hebmex.com on c.l.py, and is basically a
991 # This version is due to sismex01@hebmex.com on c.l.py, and is basically a
992 # modified (shorter) version of:
992 # modified (shorter) version of:
993 # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/66018 by
993 # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/66018 by
994 # Skip Montanaro (skip@pobox.com).
994 # Skip Montanaro (skip@pobox.com).
995
995
996 def __getitem__(self, name):
996 def __getitem__(self, name):
997 frame = sys._getframe(1)
997 frame = sys._getframe(1)
998 return eval(name, frame.f_globals, frame.f_locals)
998 return eval(name, frame.f_globals, frame.f_locals)
999
999
1000 EvalString = EvalDict # for backwards compatibility
1000 EvalString = EvalDict # for backwards compatibility
1001 #----------------------------------------------------------------------------
1001 #----------------------------------------------------------------------------
1002 def qw(words,flat=0,sep=None,maxsplit=-1):
1002 def qw(words,flat=0,sep=None,maxsplit=-1):
1003 """Similar to Perl's qw() operator, but with some more options.
1003 """Similar to Perl's qw() operator, but with some more options.
1004
1004
1005 qw(words,flat=0,sep=' ',maxsplit=-1) -> words.split(sep,maxsplit)
1005 qw(words,flat=0,sep=' ',maxsplit=-1) -> words.split(sep,maxsplit)
1006
1006
1007 words can also be a list itself, and with flat=1, the output will be
1007 words can also be a list itself, and with flat=1, the output will be
1008 recursively flattened. Examples:
1008 recursively flattened. Examples:
1009
1009
1010 >>> qw('1 2')
1010 >>> qw('1 2')
1011 ['1', '2']
1011 ['1', '2']
1012 >>> qw(['a b','1 2',['m n','p q']])
1012 >>> qw(['a b','1 2',['m n','p q']])
1013 [['a', 'b'], ['1', '2'], [['m', 'n'], ['p', 'q']]]
1013 [['a', 'b'], ['1', '2'], [['m', 'n'], ['p', 'q']]]
1014 >>> qw(['a b','1 2',['m n','p q']],flat=1)
1014 >>> qw(['a b','1 2',['m n','p q']],flat=1)
1015 ['a', 'b', '1', '2', 'm', 'n', 'p', 'q'] """
1015 ['a', 'b', '1', '2', 'm', 'n', 'p', 'q'] """
1016
1016
1017 if type(words) in StringTypes:
1017 if type(words) in StringTypes:
1018 return [word.strip() for word in words.split(sep,maxsplit)
1018 return [word.strip() for word in words.split(sep,maxsplit)
1019 if word and not word.isspace() ]
1019 if word and not word.isspace() ]
1020 if flat:
1020 if flat:
1021 return flatten(map(qw,words,[1]*len(words)))
1021 return flatten(map(qw,words,[1]*len(words)))
1022 return map(qw,words)
1022 return map(qw,words)
1023
1023
1024 #----------------------------------------------------------------------------
1024 #----------------------------------------------------------------------------
1025 def qwflat(words,sep=None,maxsplit=-1):
1025 def qwflat(words,sep=None,maxsplit=-1):
1026 """Calls qw(words) in flat mode. It's just a convenient shorthand."""
1026 """Calls qw(words) in flat mode. It's just a convenient shorthand."""
1027 return qw(words,1,sep,maxsplit)
1027 return qw(words,1,sep,maxsplit)
1028
1028
1029 #-----------------------------------------------------------------------------
1029 #-----------------------------------------------------------------------------
1030 def list_strings(arg):
1030 def list_strings(arg):
1031 """Always return a list of strings, given a string or list of strings
1031 """Always return a list of strings, given a string or list of strings
1032 as input."""
1032 as input."""
1033
1033
1034 if type(arg) in StringTypes: return [arg]
1034 if type(arg) in StringTypes: return [arg]
1035 else: return arg
1035 else: return arg
1036
1036
1037 #----------------------------------------------------------------------------
1037 #----------------------------------------------------------------------------
1038 def grep(pat,list,case=1):
1038 def grep(pat,list,case=1):
1039 """Simple minded grep-like function.
1039 """Simple minded grep-like function.
1040 grep(pat,list) returns occurrences of pat in list, None on failure.
1040 grep(pat,list) returns occurrences of pat in list, None on failure.
1041
1041
1042 It only does simple string matching, with no support for regexps. Use the
1042 It only does simple string matching, with no support for regexps. Use the
1043 option case=0 for case-insensitive matching."""
1043 option case=0 for case-insensitive matching."""
1044
1044
1045 # This is pretty crude. At least it should implement copying only references
1045 # This is pretty crude. At least it should implement copying only references
1046 # to the original data in case it's big. Now it copies the data for output.
1046 # to the original data in case it's big. Now it copies the data for output.
1047 out=[]
1047 out=[]
1048 if case:
1048 if case:
1049 for term in list:
1049 for term in list:
1050 if term.find(pat)>-1: out.append(term)
1050 if term.find(pat)>-1: out.append(term)
1051 else:
1051 else:
1052 lpat=pat.lower()
1052 lpat=pat.lower()
1053 for term in list:
1053 for term in list:
1054 if term.lower().find(lpat)>-1: out.append(term)
1054 if term.lower().find(lpat)>-1: out.append(term)
1055
1055
1056 if len(out): return out
1056 if len(out): return out
1057 else: return None
1057 else: return None
1058
1058
1059 #----------------------------------------------------------------------------
1059 #----------------------------------------------------------------------------
1060 def dgrep(pat,*opts):
1060 def dgrep(pat,*opts):
1061 """Return grep() on dir()+dir(__builtins__).
1061 """Return grep() on dir()+dir(__builtins__).
1062
1062
1063 A very common use of grep() when working interactively."""
1063 A very common use of grep() when working interactively."""
1064
1064
1065 return grep(pat,dir(__main__)+dir(__main__.__builtins__),*opts)
1065 return grep(pat,dir(__main__)+dir(__main__.__builtins__),*opts)
1066
1066
1067 #----------------------------------------------------------------------------
1067 #----------------------------------------------------------------------------
1068 def idgrep(pat):
1068 def idgrep(pat):
1069 """Case-insensitive dgrep()"""
1069 """Case-insensitive dgrep()"""
1070
1070
1071 return dgrep(pat,0)
1071 return dgrep(pat,0)
1072
1072
1073 #----------------------------------------------------------------------------
1073 #----------------------------------------------------------------------------
1074 def igrep(pat,list):
1074 def igrep(pat,list):
1075 """Synonym for case-insensitive grep."""
1075 """Synonym for case-insensitive grep."""
1076
1076
1077 return grep(pat,list,case=0)
1077 return grep(pat,list,case=0)
1078
1078
1079 #----------------------------------------------------------------------------
1079 #----------------------------------------------------------------------------
1080 def indent(str,nspaces=4,ntabs=0):
1080 def indent(str,nspaces=4,ntabs=0):
1081 """Indent a string a given number of spaces or tabstops.
1081 """Indent a string a given number of spaces or tabstops.
1082
1082
1083 indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.
1083 indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.
1084 """
1084 """
1085 if str is None:
1085 if str is None:
1086 return
1086 return
1087 ind = '\t'*ntabs+' '*nspaces
1087 ind = '\t'*ntabs+' '*nspaces
1088 outstr = '%s%s' % (ind,str.replace(os.linesep,os.linesep+ind))
1088 outstr = '%s%s' % (ind,str.replace(os.linesep,os.linesep+ind))
1089 if outstr.endswith(os.linesep+ind):
1089 if outstr.endswith(os.linesep+ind):
1090 return outstr[:-len(ind)]
1090 return outstr[:-len(ind)]
1091 else:
1091 else:
1092 return outstr
1092 return outstr
1093
1093
1094 #-----------------------------------------------------------------------------
1094 #-----------------------------------------------------------------------------
1095 def native_line_ends(filename,backup=1):
1095 def native_line_ends(filename,backup=1):
1096 """Convert (in-place) a file to line-ends native to the current OS.
1096 """Convert (in-place) a file to line-ends native to the current OS.
1097
1097
1098 If the optional backup argument is given as false, no backup of the
1098 If the optional backup argument is given as false, no backup of the
1099 original file is left. """
1099 original file is left. """
1100
1100
1101 backup_suffixes = {'posix':'~','dos':'.bak','nt':'.bak','mac':'.bak'}
1101 backup_suffixes = {'posix':'~','dos':'.bak','nt':'.bak','mac':'.bak'}
1102
1102
1103 bak_filename = filename + backup_suffixes[os.name]
1103 bak_filename = filename + backup_suffixes[os.name]
1104
1104
1105 original = open(filename).read()
1105 original = open(filename).read()
1106 shutil.copy2(filename,bak_filename)
1106 shutil.copy2(filename,bak_filename)
1107 try:
1107 try:
1108 new = open(filename,'wb')
1108 new = open(filename,'wb')
1109 new.write(os.linesep.join(original.splitlines()))
1109 new.write(os.linesep.join(original.splitlines()))
1110 new.write(os.linesep) # ALWAYS put an eol at the end of the file
1110 new.write(os.linesep) # ALWAYS put an eol at the end of the file
1111 new.close()
1111 new.close()
1112 except:
1112 except:
1113 os.rename(bak_filename,filename)
1113 os.rename(bak_filename,filename)
1114 if not backup:
1114 if not backup:
1115 try:
1115 try:
1116 os.remove(bak_filename)
1116 os.remove(bak_filename)
1117 except:
1117 except:
1118 pass
1118 pass
1119
1119
1120 #----------------------------------------------------------------------------
1120 #----------------------------------------------------------------------------
1121 def get_pager_cmd(pager_cmd = None):
1121 def get_pager_cmd(pager_cmd = None):
1122 """Return a pager command.
1122 """Return a pager command.
1123
1123
1124 Makes some attempts at finding an OS-correct one."""
1124 Makes some attempts at finding an OS-correct one."""
1125
1125
1126 if os.name == 'posix':
1126 if os.name == 'posix':
1127 default_pager_cmd = 'less -r' # -r for color control sequences
1127 default_pager_cmd = 'less -r' # -r for color control sequences
1128 elif os.name in ['nt','dos']:
1128 elif os.name in ['nt','dos']:
1129 default_pager_cmd = 'type'
1129 default_pager_cmd = 'type'
1130
1130
1131 if pager_cmd is None:
1131 if pager_cmd is None:
1132 try:
1132 try:
1133 pager_cmd = os.environ['PAGER']
1133 pager_cmd = os.environ['PAGER']
1134 except:
1134 except:
1135 pager_cmd = default_pager_cmd
1135 pager_cmd = default_pager_cmd
1136 return pager_cmd
1136 return pager_cmd
1137
1137
1138 #-----------------------------------------------------------------------------
1138 #-----------------------------------------------------------------------------
1139 def get_pager_start(pager,start):
1139 def get_pager_start(pager,start):
1140 """Return the string for paging files with an offset.
1140 """Return the string for paging files with an offset.
1141
1141
1142 This is the '+N' argument which less and more (under Unix) accept.
1142 This is the '+N' argument which less and more (under Unix) accept.
1143 """
1143 """
1144
1144
1145 if pager in ['less','more']:
1145 if pager in ['less','more']:
1146 if start:
1146 if start:
1147 start_string = '+' + str(start)
1147 start_string = '+' + str(start)
1148 else:
1148 else:
1149 start_string = ''
1149 start_string = ''
1150 else:
1150 else:
1151 start_string = ''
1151 start_string = ''
1152 return start_string
1152 return start_string
1153
1153
1154 #----------------------------------------------------------------------------
1154 #----------------------------------------------------------------------------
1155 def page_dumb(strng,start=0,screen_lines=25):
1155 def page_dumb(strng,start=0,screen_lines=25):
1156 """Very dumb 'pager' in Python, for when nothing else works.
1156 """Very dumb 'pager' in Python, for when nothing else works.
1157
1157
1158 Only moves forward, same interface as page(), except for pager_cmd and
1158 Only moves forward, same interface as page(), except for pager_cmd and
1159 mode."""
1159 mode."""
1160
1160
1161 out_ln = strng.splitlines()[start:]
1161 out_ln = strng.splitlines()[start:]
1162 screens = chop(out_ln,screen_lines-1)
1162 screens = chop(out_ln,screen_lines-1)
1163 if len(screens) == 1:
1163 if len(screens) == 1:
1164 print >>Term.cout, os.linesep.join(screens[0])
1164 print >>Term.cout, os.linesep.join(screens[0])
1165 else:
1165 else:
1166 for scr in screens[0:-1]:
1166 for scr in screens[0:-1]:
1167 print >>Term.cout, os.linesep.join(scr)
1167 print >>Term.cout, os.linesep.join(scr)
1168 ans = raw_input('---Return to continue, q to quit--- ')
1168 ans = raw_input('---Return to continue, q to quit--- ')
1169 if ans.lower().startswith('q'):
1169 if ans.lower().startswith('q'):
1170 return
1170 return
1171 print >>Term.cout, os.linesep.join(screens[-1])
1171 print >>Term.cout, os.linesep.join(screens[-1])
1172
1172
1173 #----------------------------------------------------------------------------
1173 #----------------------------------------------------------------------------
1174 def page(strng,start=0,screen_lines=0,pager_cmd = None):
1174 def page(strng,start=0,screen_lines=0,pager_cmd = None):
1175 """Print a string, piping through a pager after a certain length.
1175 """Print a string, piping through a pager after a certain length.
1176
1176
1177 The screen_lines parameter specifies the number of *usable* lines of your
1177 The screen_lines parameter specifies the number of *usable* lines of your
1178 terminal screen (total lines minus lines you need to reserve to show other
1178 terminal screen (total lines minus lines you need to reserve to show other
1179 information).
1179 information).
1180
1180
1181 If you set screen_lines to a number <=0, page() will try to auto-determine
1181 If you set screen_lines to a number <=0, page() will try to auto-determine
1182 your screen size and will only use up to (screen_size+screen_lines) for
1182 your screen size and will only use up to (screen_size+screen_lines) for
1183 printing, paging after that. That is, if you want auto-detection but need
1183 printing, paging after that. That is, if you want auto-detection but need
1184 to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
1184 to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
1185 auto-detection without any lines reserved simply use screen_lines = 0.
1185 auto-detection without any lines reserved simply use screen_lines = 0.
1186
1186
1187 If a string won't fit in the allowed lines, it is sent through the
1187 If a string won't fit in the allowed lines, it is sent through the
1188 specified pager command. If none given, look for PAGER in the environment,
1188 specified pager command. If none given, look for PAGER in the environment,
1189 and ultimately default to less.
1189 and ultimately default to less.
1190
1190
1191 If no system pager works, the string is sent through a 'dumb pager'
1191 If no system pager works, the string is sent through a 'dumb pager'
1192 written in python, very simplistic.
1192 written in python, very simplistic.
1193 """
1193 """
1194
1194
1195 # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
1195 # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
1196 TERM = os.environ.get('TERM','dumb')
1196 TERM = os.environ.get('TERM','dumb')
1197 if TERM in ['dumb','emacs'] and os.name != 'nt':
1197 if TERM in ['dumb','emacs'] and os.name != 'nt':
1198 print strng
1198 print strng
1199 return
1199 return
1200 # chop off the topmost part of the string we don't want to see
1200 # chop off the topmost part of the string we don't want to see
1201 str_lines = strng.split(os.linesep)[start:]
1201 str_lines = strng.split(os.linesep)[start:]
1202 str_toprint = os.linesep.join(str_lines)
1202 str_toprint = os.linesep.join(str_lines)
1203 num_newlines = len(str_lines)
1203 num_newlines = len(str_lines)
1204 len_str = len(str_toprint)
1204 len_str = len(str_toprint)
1205
1205
1206 # Dumb heuristics to guesstimate number of on-screen lines the string
1206 # Dumb heuristics to guesstimate number of on-screen lines the string
1207 # takes. Very basic, but good enough for docstrings in reasonable
1207 # takes. Very basic, but good enough for docstrings in reasonable
1208 # terminals. If someone later feels like refining it, it's not hard.
1208 # terminals. If someone later feels like refining it, it's not hard.
1209 numlines = max(num_newlines,int(len_str/80)+1)
1209 numlines = max(num_newlines,int(len_str/80)+1)
1210
1210
1211 screen_lines_def = 25 # default value if we can't auto-determine
1211 screen_lines_def = 25 # default value if we can't auto-determine
1212
1212
1213 # auto-determine screen size
1213 # auto-determine screen size
1214 if screen_lines <= 0:
1214 if screen_lines <= 0:
1215 if TERM=='xterm':
1215 if TERM=='xterm':
1216 try:
1216 try:
1217 import curses
1217 import curses
1218 if hasattr(curses,'initscr'):
1218 if hasattr(curses,'initscr'):
1219 use_curses = 1
1219 use_curses = 1
1220 else:
1220 else:
1221 use_curses = 0
1221 use_curses = 0
1222 except ImportError:
1222 except ImportError:
1223 use_curses = 0
1223 use_curses = 0
1224 else:
1224 else:
1225 # curses causes problems on many terminals other than xterm.
1225 # curses causes problems on many terminals other than xterm.
1226 use_curses = 0
1226 use_curses = 0
1227 if use_curses:
1227 if use_curses:
1228 scr = curses.initscr()
1228 scr = curses.initscr()
1229 screen_lines_real,screen_cols = scr.getmaxyx()
1229 screen_lines_real,screen_cols = scr.getmaxyx()
1230 curses.endwin()
1230 curses.endwin()
1231 screen_lines += screen_lines_real
1231 screen_lines += screen_lines_real
1232 #print '***Screen size:',screen_lines_real,'lines x',\
1232 #print '***Screen size:',screen_lines_real,'lines x',\
1233 #screen_cols,'columns.' # dbg
1233 #screen_cols,'columns.' # dbg
1234 else:
1234 else:
1235 screen_lines += screen_lines_def
1235 screen_lines += screen_lines_def
1236
1236
1237 #print 'numlines',numlines,'screenlines',screen_lines # dbg
1237 #print 'numlines',numlines,'screenlines',screen_lines # dbg
1238 if numlines <= screen_lines :
1238 if numlines <= screen_lines :
1239 #print '*** normal print' # dbg
1239 #print '*** normal print' # dbg
1240 print >>Term.cout, str_toprint
1240 print >>Term.cout, str_toprint
1241 else:
1241 else:
1242 # Try to open pager and default to internal one if that fails.
1242 # Try to open pager and default to internal one if that fails.
1243 # All failure modes are tagged as 'retval=1', to match the return
1243 # All failure modes are tagged as 'retval=1', to match the return
1244 # value of a failed system command. If any intermediate attempt
1244 # value of a failed system command. If any intermediate attempt
1245 # sets retval to 1, at the end we resort to our own page_dumb() pager.
1245 # sets retval to 1, at the end we resort to our own page_dumb() pager.
1246 pager_cmd = get_pager_cmd(pager_cmd)
1246 pager_cmd = get_pager_cmd(pager_cmd)
1247 pager_cmd += ' ' + get_pager_start(pager_cmd,start)
1247 pager_cmd += ' ' + get_pager_start(pager_cmd,start)
1248 if os.name == 'nt':
1248 if os.name == 'nt':
1249 if pager_cmd.startswith('type'):
1249 if pager_cmd.startswith('type'):
1250 # The default WinXP 'type' command is failing on complex strings.
1250 # The default WinXP 'type' command is failing on complex strings.
1251 retval = 1
1251 retval = 1
1252 else:
1252 else:
1253 tmpname = tempfile.mktemp('.txt')
1253 tmpname = tempfile.mktemp('.txt')
1254 tmpfile = file(tmpname,'wt')
1254 tmpfile = file(tmpname,'wt')
1255 tmpfile.write(strng)
1255 tmpfile.write(strng)
1256 tmpfile.close()
1256 tmpfile.close()
1257 cmd = "%s < %s" % (pager_cmd,tmpname)
1257 cmd = "%s < %s" % (pager_cmd,tmpname)
1258 if os.system(cmd):
1258 if os.system(cmd):
1259 retval = 1
1259 retval = 1
1260 else:
1260 else:
1261 retval = None
1261 retval = None
1262 os.remove(tmpname)
1262 os.remove(tmpname)
1263 else:
1263 else:
1264 try:
1264 try:
1265 retval = None
1265 retval = None
1266 # if I use popen4, things hang. No idea why.
1266 # if I use popen4, things hang. No idea why.
1267 #pager,shell_out = os.popen4(pager_cmd)
1267 #pager,shell_out = os.popen4(pager_cmd)
1268 pager = os.popen(pager_cmd,'w')
1268 pager = os.popen(pager_cmd,'w')
1269 pager.write(strng)
1269 pager.write(strng)
1270 pager.close()
1270 pager.close()
1271 retval = pager.close() # success returns None
1271 retval = pager.close() # success returns None
1272 except IOError,msg: # broken pipe when user quits
1272 except IOError,msg: # broken pipe when user quits
1273 if msg.args == (32,'Broken pipe'):
1273 if msg.args == (32,'Broken pipe'):
1274 retval = None
1274 retval = None
1275 else:
1275 else:
1276 retval = 1
1276 retval = 1
1277 except OSError:
1277 except OSError:
1278 # Other strange problems, sometimes seen in Win2k/cygwin
1278 # Other strange problems, sometimes seen in Win2k/cygwin
1279 retval = 1
1279 retval = 1
1280 if retval is not None:
1280 if retval is not None:
1281 page_dumb(strng,screen_lines=screen_lines)
1281 page_dumb(strng,screen_lines=screen_lines)
1282
1282
1283 #----------------------------------------------------------------------------
1283 #----------------------------------------------------------------------------
1284 def page_file(fname,start = 0, pager_cmd = None):
1284 def page_file(fname,start = 0, pager_cmd = None):
1285 """Page a file, using an optional pager command and starting line.
1285 """Page a file, using an optional pager command and starting line.
1286 """
1286 """
1287
1287
1288 pager_cmd = get_pager_cmd(pager_cmd)
1288 pager_cmd = get_pager_cmd(pager_cmd)
1289 pager_cmd += ' ' + get_pager_start(pager_cmd,start)
1289 pager_cmd += ' ' + get_pager_start(pager_cmd,start)
1290
1290
1291 try:
1291 try:
1292 if os.environ['TERM'] in ['emacs','dumb']:
1292 if os.environ['TERM'] in ['emacs','dumb']:
1293 raise EnvironmentError
1293 raise EnvironmentError
1294 xsys(pager_cmd + ' ' + fname)
1294 xsys(pager_cmd + ' ' + fname)
1295 except:
1295 except:
1296 try:
1296 try:
1297 if start > 0:
1297 if start > 0:
1298 start -= 1
1298 start -= 1
1299 page(open(fname).read(),start)
1299 page(open(fname).read(),start)
1300 except:
1300 except:
1301 print 'Unable to show file',`fname`
1301 print 'Unable to show file',`fname`
1302
1302
1303 #----------------------------------------------------------------------------
1303 #----------------------------------------------------------------------------
1304 def snip_print(str,width = 75,print_full = 0,header = ''):
1304 def snip_print(str,width = 75,print_full = 0,header = ''):
1305 """Print a string snipping the midsection to fit in width.
1305 """Print a string snipping the midsection to fit in width.
1306
1306
1307 print_full: mode control:
1307 print_full: mode control:
1308 - 0: only snip long strings
1308 - 0: only snip long strings
1309 - 1: send to page() directly.
1309 - 1: send to page() directly.
1310 - 2: snip long strings and ask for full length viewing with page()
1310 - 2: snip long strings and ask for full length viewing with page()
1311 Return 1 if snipping was necessary, 0 otherwise."""
1311 Return 1 if snipping was necessary, 0 otherwise."""
1312
1312
1313 if print_full == 1:
1313 if print_full == 1:
1314 page(header+str)
1314 page(header+str)
1315 return 0
1315 return 0
1316
1316
1317 print header,
1317 print header,
1318 if len(str) < width:
1318 if len(str) < width:
1319 print str
1319 print str
1320 snip = 0
1320 snip = 0
1321 else:
1321 else:
1322 whalf = int((width -5)/2)
1322 whalf = int((width -5)/2)
1323 print str[:whalf] + ' <...> ' + str[-whalf:]
1323 print str[:whalf] + ' <...> ' + str[-whalf:]
1324 snip = 1
1324 snip = 1
1325 if snip and print_full == 2:
1325 if snip and print_full == 2:
1326 if raw_input(header+' Snipped. View (y/n)? [N]').lower() == 'y':
1326 if raw_input(header+' Snipped. View (y/n)? [N]').lower() == 'y':
1327 page(str)
1327 page(str)
1328 return snip
1328 return snip
1329
1329
1330 #****************************************************************************
1330 #****************************************************************************
1331 # lists, dicts and structures
1331 # lists, dicts and structures
1332
1332
1333 def belong(candidates,checklist):
1333 def belong(candidates,checklist):
1334 """Check whether a list of items appear in a given list of options.
1334 """Check whether a list of items appear in a given list of options.
1335
1335
1336 Returns a list of 1 and 0, one for each candidate given."""
1336 Returns a list of 1 and 0, one for each candidate given."""
1337
1337
1338 return [x in checklist for x in candidates]
1338 return [x in checklist for x in candidates]
1339
1339
1340 #----------------------------------------------------------------------------
1340 #----------------------------------------------------------------------------
1341 def uniq_stable(elems):
1341 def uniq_stable(elems):
1342 """uniq_stable(elems) -> list
1342 """uniq_stable(elems) -> list
1343
1343
1344 Return from an iterable, a list of all the unique elements in the input,
1344 Return from an iterable, a list of all the unique elements in the input,
1345 but maintaining the order in which they first appear.
1345 but maintaining the order in which they first appear.
1346
1346
1347 A naive solution to this problem which just makes a dictionary with the
1347 A naive solution to this problem which just makes a dictionary with the
1348 elements as keys fails to respect the stability condition, since
1348 elements as keys fails to respect the stability condition, since
1349 dictionaries are unsorted by nature.
1349 dictionaries are unsorted by nature.
1350
1350
1351 Note: All elements in the input must be valid dictionary keys for this
1351 Note: All elements in the input must be valid dictionary keys for this
1352 routine to work, as it internally uses a dictionary for efficiency
1352 routine to work, as it internally uses a dictionary for efficiency
1353 reasons."""
1353 reasons."""
1354
1354
1355 unique = []
1355 unique = []
1356 unique_dict = {}
1356 unique_dict = {}
1357 for nn in elems:
1357 for nn in elems:
1358 if nn not in unique_dict:
1358 if nn not in unique_dict:
1359 unique.append(nn)
1359 unique.append(nn)
1360 unique_dict[nn] = None
1360 unique_dict[nn] = None
1361 return unique
1361 return unique
1362
1362
1363 #----------------------------------------------------------------------------
1363 #----------------------------------------------------------------------------
1364 class NLprinter:
1364 class NLprinter:
1365 """Print an arbitrarily nested list, indicating index numbers.
1365 """Print an arbitrarily nested list, indicating index numbers.
1366
1366
1367 An instance of this class called nlprint is available and callable as a
1367 An instance of this class called nlprint is available and callable as a
1368 function.
1368 function.
1369
1369
1370 nlprint(list,indent=' ',sep=': ') -> prints indenting each level by 'indent'
1370 nlprint(list,indent=' ',sep=': ') -> prints indenting each level by 'indent'
1371 and using 'sep' to separate the index from the value. """
1371 and using 'sep' to separate the index from the value. """
1372
1372
1373 def __init__(self):
1373 def __init__(self):
1374 self.depth = 0
1374 self.depth = 0
1375
1375
1376 def __call__(self,lst,pos='',**kw):
1376 def __call__(self,lst,pos='',**kw):
1377 """Prints the nested list numbering levels."""
1377 """Prints the nested list numbering levels."""
1378 kw.setdefault('indent',' ')
1378 kw.setdefault('indent',' ')
1379 kw.setdefault('sep',': ')
1379 kw.setdefault('sep',': ')
1380 kw.setdefault('start',0)
1380 kw.setdefault('start',0)
1381 kw.setdefault('stop',len(lst))
1381 kw.setdefault('stop',len(lst))
1382 # we need to remove start and stop from kw so they don't propagate
1382 # we need to remove start and stop from kw so they don't propagate
1383 # into a recursive call for a nested list.
1383 # into a recursive call for a nested list.
1384 start = kw['start']; del kw['start']
1384 start = kw['start']; del kw['start']
1385 stop = kw['stop']; del kw['stop']
1385 stop = kw['stop']; del kw['stop']
1386 if self.depth == 0 and 'header' in kw.keys():
1386 if self.depth == 0 and 'header' in kw.keys():
1387 print kw['header']
1387 print kw['header']
1388
1388
1389 for idx in range(start,stop):
1389 for idx in range(start,stop):
1390 elem = lst[idx]
1390 elem = lst[idx]
1391 if type(elem)==type([]):
1391 if type(elem)==type([]):
1392 self.depth += 1
1392 self.depth += 1
1393 self.__call__(elem,itpl('$pos$idx,'),**kw)
1393 self.__call__(elem,itpl('$pos$idx,'),**kw)
1394 self.depth -= 1
1394 self.depth -= 1
1395 else:
1395 else:
1396 printpl(kw['indent']*self.depth+'$pos$idx$kw["sep"]$elem')
1396 printpl(kw['indent']*self.depth+'$pos$idx$kw["sep"]$elem')
1397
1397
1398 nlprint = NLprinter()
1398 nlprint = NLprinter()
1399 #----------------------------------------------------------------------------
1399 #----------------------------------------------------------------------------
1400 def all_belong(candidates,checklist):
1400 def all_belong(candidates,checklist):
1401 """Check whether a list of items ALL appear in a given list of options.
1401 """Check whether a list of items ALL appear in a given list of options.
1402
1402
1403 Returns a single 1 or 0 value."""
1403 Returns a single 1 or 0 value."""
1404
1404
1405 return 1-(0 in [x in checklist for x in candidates])
1405 return 1-(0 in [x in checklist for x in candidates])
1406
1406
1407 #----------------------------------------------------------------------------
1407 #----------------------------------------------------------------------------
1408 def sort_compare(lst1,lst2,inplace = 1):
1408 def sort_compare(lst1,lst2,inplace = 1):
1409 """Sort and compare two lists.
1409 """Sort and compare two lists.
1410
1410
1411 By default it does it in place, thus modifying the lists. Use inplace = 0
1411 By default it does it in place, thus modifying the lists. Use inplace = 0
1412 to avoid that (at the cost of temporary copy creation)."""
1412 to avoid that (at the cost of temporary copy creation)."""
1413 if not inplace:
1413 if not inplace:
1414 lst1 = lst1[:]
1414 lst1 = lst1[:]
1415 lst2 = lst2[:]
1415 lst2 = lst2[:]
1416 lst1.sort(); lst2.sort()
1416 lst1.sort(); lst2.sort()
1417 return lst1 == lst2
1417 return lst1 == lst2
1418
1418
1419 #----------------------------------------------------------------------------
1419 #----------------------------------------------------------------------------
1420 def mkdict(**kwargs):
1420 def mkdict(**kwargs):
1421 """Return a dict from a keyword list.
1421 """Return a dict from a keyword list.
1422
1422
1423 It's just syntactic sugar for making ditcionary creation more convenient:
1423 It's just syntactic sugar for making ditcionary creation more convenient:
1424 # the standard way
1424 # the standard way
1425 >>>data = { 'red' : 1, 'green' : 2, 'blue' : 3 }
1425 >>>data = { 'red' : 1, 'green' : 2, 'blue' : 3 }
1426 # a cleaner way
1426 # a cleaner way
1427 >>>data = dict(red=1, green=2, blue=3)
1427 >>>data = dict(red=1, green=2, blue=3)
1428
1428
1429 If you need more than this, look at the Struct() class."""
1429 If you need more than this, look at the Struct() class."""
1430
1430
1431 return kwargs
1431 return kwargs
1432
1432
1433 #----------------------------------------------------------------------------
1433 #----------------------------------------------------------------------------
1434 def list2dict(lst):
1434 def list2dict(lst):
1435 """Takes a list of (key,value) pairs and turns it into a dict."""
1435 """Takes a list of (key,value) pairs and turns it into a dict."""
1436
1436
1437 dic = {}
1437 dic = {}
1438 for k,v in lst: dic[k] = v
1438 for k,v in lst: dic[k] = v
1439 return dic
1439 return dic
1440
1440
1441 #----------------------------------------------------------------------------
1441 #----------------------------------------------------------------------------
1442 def list2dict2(lst,default=''):
1442 def list2dict2(lst,default=''):
1443 """Takes a list and turns it into a dict.
1443 """Takes a list and turns it into a dict.
1444 Much slower than list2dict, but more versatile. This version can take
1444 Much slower than list2dict, but more versatile. This version can take
1445 lists with sublists of arbitrary length (including sclars)."""
1445 lists with sublists of arbitrary length (including sclars)."""
1446
1446
1447 dic = {}
1447 dic = {}
1448 for elem in lst:
1448 for elem in lst:
1449 if type(elem) in (types.ListType,types.TupleType):
1449 if type(elem) in (types.ListType,types.TupleType):
1450 size = len(elem)
1450 size = len(elem)
1451 if size == 0:
1451 if size == 0:
1452 pass
1452 pass
1453 elif size == 1:
1453 elif size == 1:
1454 dic[elem] = default
1454 dic[elem] = default
1455 else:
1455 else:
1456 k,v = elem[0], elem[1:]
1456 k,v = elem[0], elem[1:]
1457 if len(v) == 1: v = v[0]
1457 if len(v) == 1: v = v[0]
1458 dic[k] = v
1458 dic[k] = v
1459 else:
1459 else:
1460 dic[elem] = default
1460 dic[elem] = default
1461 return dic
1461 return dic
1462
1462
1463 #----------------------------------------------------------------------------
1463 #----------------------------------------------------------------------------
1464 def flatten(seq):
1464 def flatten(seq):
1465 """Flatten a list of lists (NOT recursive, only works for 2d lists)."""
1465 """Flatten a list of lists (NOT recursive, only works for 2d lists)."""
1466
1466
1467 # bug in python??? (YES. Fixed in 2.2, let's leave the kludgy fix in).
1467 # bug in python??? (YES. Fixed in 2.2, let's leave the kludgy fix in).
1468
1468
1469 # if the x=0 isn't made, a *global* variable x is left over after calling
1469 # if the x=0 isn't made, a *global* variable x is left over after calling
1470 # this function, with the value of the last element in the return
1470 # this function, with the value of the last element in the return
1471 # list. This does seem like a bug big time to me.
1471 # list. This does seem like a bug big time to me.
1472
1472
1473 # the problem is fixed with the x=0, which seems to force the creation of
1473 # the problem is fixed with the x=0, which seems to force the creation of
1474 # a local name
1474 # a local name
1475
1475
1476 x = 0
1476 x = 0
1477 return [x for subseq in seq for x in subseq]
1477 return [x for subseq in seq for x in subseq]
1478
1478
1479 #----------------------------------------------------------------------------
1479 #----------------------------------------------------------------------------
1480 def get_slice(seq,start=0,stop=None,step=1):
1480 def get_slice(seq,start=0,stop=None,step=1):
1481 """Get a slice of a sequence with variable step. Specify start,stop,step."""
1481 """Get a slice of a sequence with variable step. Specify start,stop,step."""
1482 if stop == None:
1482 if stop == None:
1483 stop = len(seq)
1483 stop = len(seq)
1484 item = lambda i: seq[i]
1484 item = lambda i: seq[i]
1485 return map(item,xrange(start,stop,step))
1485 return map(item,xrange(start,stop,step))
1486
1486
1487 #----------------------------------------------------------------------------
1487 #----------------------------------------------------------------------------
1488 def chop(seq,size):
1488 def chop(seq,size):
1489 """Chop a sequence into chunks of the given size."""
1489 """Chop a sequence into chunks of the given size."""
1490 chunk = lambda i: seq[i:i+size]
1490 chunk = lambda i: seq[i:i+size]
1491 return map(chunk,xrange(0,len(seq),size))
1491 return map(chunk,xrange(0,len(seq),size))
1492
1492
1493 #----------------------------------------------------------------------------
1493 #----------------------------------------------------------------------------
1494 def with(object, **args):
1494 def with(object, **args):
1495 """Set multiple attributes for an object, similar to Pascal's with.
1495 """Set multiple attributes for an object, similar to Pascal's with.
1496
1496
1497 Example:
1497 Example:
1498 with(jim,
1498 with(jim,
1499 born = 1960,
1499 born = 1960,
1500 haircolour = 'Brown',
1500 haircolour = 'Brown',
1501 eyecolour = 'Green')
1501 eyecolour = 'Green')
1502
1502
1503 Credit: Greg Ewing, in
1503 Credit: Greg Ewing, in
1504 http://mail.python.org/pipermail/python-list/2001-May/040703.html"""
1504 http://mail.python.org/pipermail/python-list/2001-May/040703.html"""
1505
1505
1506 object.__dict__.update(args)
1506 object.__dict__.update(args)
1507
1507
1508 #----------------------------------------------------------------------------
1508 #----------------------------------------------------------------------------
1509 def setattr_list(obj,alist,nspace = None):
1509 def setattr_list(obj,alist,nspace = None):
1510 """Set a list of attributes for an object taken from a namespace.
1510 """Set a list of attributes for an object taken from a namespace.
1511
1511
1512 setattr_list(obj,alist,nspace) -> sets in obj all the attributes listed in
1512 setattr_list(obj,alist,nspace) -> sets in obj all the attributes listed in
1513 alist with their values taken from nspace, which must be a dict (something
1513 alist with their values taken from nspace, which must be a dict (something
1514 like locals() will often do) If nspace isn't given, locals() of the
1514 like locals() will often do) If nspace isn't given, locals() of the
1515 *caller* is used, so in most cases you can omit it.
1515 *caller* is used, so in most cases you can omit it.
1516
1516
1517 Note that alist can be given as a string, which will be automatically
1517 Note that alist can be given as a string, which will be automatically
1518 split into a list on whitespace. If given as a list, it must be a list of
1518 split into a list on whitespace. If given as a list, it must be a list of
1519 *strings* (the variable names themselves), not of variables."""
1519 *strings* (the variable names themselves), not of variables."""
1520
1520
1521 # this grabs the local variables from the *previous* call frame -- that is
1521 # this grabs the local variables from the *previous* call frame -- that is
1522 # the locals from the function that called setattr_list().
1522 # the locals from the function that called setattr_list().
1523 # - snipped from weave.inline()
1523 # - snipped from weave.inline()
1524 if nspace is None:
1524 if nspace is None:
1525 call_frame = sys._getframe().f_back
1525 call_frame = sys._getframe().f_back
1526 nspace = call_frame.f_locals
1526 nspace = call_frame.f_locals
1527
1527
1528 if type(alist) in StringTypes:
1528 if type(alist) in StringTypes:
1529 alist = alist.split()
1529 alist = alist.split()
1530 for attr in alist:
1530 for attr in alist:
1531 val = eval(attr,nspace)
1531 val = eval(attr,nspace)
1532 setattr(obj,attr,val)
1532 setattr(obj,attr,val)
1533
1533
1534 #----------------------------------------------------------------------------
1534 #----------------------------------------------------------------------------
1535 def getattr_list(obj,alist,*args):
1535 def getattr_list(obj,alist,*args):
1536 """getattr_list(obj,alist[, default]) -> attribute list.
1536 """getattr_list(obj,alist[, default]) -> attribute list.
1537
1537
1538 Get a list of named attributes for an object. When a default argument is
1538 Get a list of named attributes for an object. When a default argument is
1539 given, it is returned when the attribute doesn't exist; without it, an
1539 given, it is returned when the attribute doesn't exist; without it, an
1540 exception is raised in that case.
1540 exception is raised in that case.
1541
1541
1542 Note that alist can be given as a string, which will be automatically
1542 Note that alist can be given as a string, which will be automatically
1543 split into a list on whitespace. If given as a list, it must be a list of
1543 split into a list on whitespace. If given as a list, it must be a list of
1544 *strings* (the variable names themselves), not of variables."""
1544 *strings* (the variable names themselves), not of variables."""
1545
1545
1546 if type(alist) in StringTypes:
1546 if type(alist) in StringTypes:
1547 alist = alist.split()
1547 alist = alist.split()
1548 if args:
1548 if args:
1549 if len(args)==1:
1549 if len(args)==1:
1550 default = args[0]
1550 default = args[0]
1551 return map(lambda attr: getattr(obj,attr,default),alist)
1551 return map(lambda attr: getattr(obj,attr,default),alist)
1552 else:
1552 else:
1553 raise ValueError,'getattr_list() takes only one optional argument'
1553 raise ValueError,'getattr_list() takes only one optional argument'
1554 else:
1554 else:
1555 return map(lambda attr: getattr(obj,attr),alist)
1555 return map(lambda attr: getattr(obj,attr),alist)
1556
1556
1557 #----------------------------------------------------------------------------
1557 #----------------------------------------------------------------------------
1558 def map_method(method,object_list,*argseq,**kw):
1558 def map_method(method,object_list,*argseq,**kw):
1559 """map_method(method,object_list,*args,**kw) -> list
1559 """map_method(method,object_list,*args,**kw) -> list
1560
1560
1561 Return a list of the results of applying the methods to the items of the
1561 Return a list of the results of applying the methods to the items of the
1562 argument sequence(s). If more than one sequence is given, the method is
1562 argument sequence(s). If more than one sequence is given, the method is
1563 called with an argument list consisting of the corresponding item of each
1563 called with an argument list consisting of the corresponding item of each
1564 sequence. All sequences must be of the same length.
1564 sequence. All sequences must be of the same length.
1565
1565
1566 Keyword arguments are passed verbatim to all objects called.
1566 Keyword arguments are passed verbatim to all objects called.
1567
1567
1568 This is Python code, so it's not nearly as fast as the builtin map()."""
1568 This is Python code, so it's not nearly as fast as the builtin map()."""
1569
1569
1570 out_list = []
1570 out_list = []
1571 idx = 0
1571 idx = 0
1572 for object in object_list:
1572 for object in object_list:
1573 try:
1573 try:
1574 handler = getattr(object, method)
1574 handler = getattr(object, method)
1575 except AttributeError:
1575 except AttributeError:
1576 out_list.append(None)
1576 out_list.append(None)
1577 else:
1577 else:
1578 if argseq:
1578 if argseq:
1579 args = map(lambda lst:lst[idx],argseq)
1579 args = map(lambda lst:lst[idx],argseq)
1580 #print 'ob',object,'hand',handler,'ar',args # dbg
1580 #print 'ob',object,'hand',handler,'ar',args # dbg
1581 out_list.append(handler(args,**kw))
1581 out_list.append(handler(args,**kw))
1582 else:
1582 else:
1583 out_list.append(handler(**kw))
1583 out_list.append(handler(**kw))
1584 idx += 1
1584 idx += 1
1585 return out_list
1585 return out_list
1586
1586
1587 #----------------------------------------------------------------------------
1587 #----------------------------------------------------------------------------
1588 # Proposed popitem() extension, written as a method
1588 # Proposed popitem() extension, written as a method
1589
1589
1590 class NotGiven: pass
1590 class NotGiven: pass
1591
1591
1592 def popkey(dct,key,default=NotGiven):
1592 def popkey(dct,key,default=NotGiven):
1593 """Return dct[key] and delete dct[key].
1593 """Return dct[key] and delete dct[key].
1594
1594
1595 If default is given, return it if dct[key] doesn't exist, otherwise raise
1595 If default is given, return it if dct[key] doesn't exist, otherwise raise
1596 KeyError. """
1596 KeyError. """
1597
1597
1598 try:
1598 try:
1599 val = dct[key]
1599 val = dct[key]
1600 except KeyError:
1600 except KeyError:
1601 if default is NotGiven:
1601 if default is NotGiven:
1602 raise
1602 raise
1603 else:
1603 else:
1604 return default
1604 return default
1605 else:
1605 else:
1606 del dct[key]
1606 del dct[key]
1607 return val
1607 return val
1608 #*************************** end of file <genutils.py> **********************
1608 #*************************** end of file <genutils.py> **********************
1609
1609
@@ -1,72 +1,95 b''
1 """hooks for IPython.
1 """hooks for IPython.
2
2
3 In Python, it is possible to overwrite any method of any object if you really
3 In Python, it is possible to overwrite any method of any object if you really
4 want to. But IPython exposes a few 'hooks', methods which are _designed_ to
4 want to. But IPython exposes a few 'hooks', methods which are _designed_ to
5 be overwritten by users for customization purposes. This module defines the
5 be overwritten by users for customization purposes. This module defines the
6 default versions of all such hooks, which get used by IPython if not
6 default versions of all such hooks, which get used by IPython if not
7 overridden by the user.
7 overridden by the user.
8
8
9 hooks are simple functions, but they should be declared with 'self' as their
9 hooks are simple functions, but they should be declared with 'self' as their
10 first argument, because when activated they are registered into IPython as
10 first argument, because when activated they are registered into IPython as
11 instance methods. The self argument will be the IPython running instance
11 instance methods. The self argument will be the IPython running instance
12 itself, so hooks have full access to the entire IPython object.
12 itself, so hooks have full access to the entire IPython object.
13
13
14 If you wish to define a new hook and activate it, you need to put the
14 If you wish to define a new hook and activate it, you need to put the
15 necessary code into a python file which can be either imported or execfile()'d
15 necessary code into a python file which can be either imported or execfile()'d
16 from within your ipythonrc configuration.
16 from within your ipythonrc configuration.
17
17
18 For example, suppose that you have a module called 'myiphooks' in your
18 For example, suppose that you have a module called 'myiphooks' in your
19 PYTHONPATH, which contains the following definition:
19 PYTHONPATH, which contains the following definition:
20
20
21 import os
21 import os
22 def calljed(self,filename, linenum):
22 def calljed(self,filename, linenum):
23 "My editor hook calls the jed editor directly."
23 "My editor hook calls the jed editor directly."
24 print "Calling my own editor, jed ..."
24 print "Calling my own editor, jed ..."
25 os.system('jed +%d %s' % (linenum,filename))
25 os.system('jed +%d %s' % (linenum,filename))
26
26
27 You can then execute the following line of code to make it the new IPython
27 You can then execute the following line of code to make it the new IPython
28 editor hook, after having imported 'myiphooks':
28 editor hook, after having imported 'myiphooks':
29
29
30 ip_set_hook('editor',myiphooks.calljed)
30 ip_set_hook('editor',myiphooks.calljed)
31
31
32 The ip_set_hook function is put by IPython into the builtin namespace, so it
32 The ip_set_hook function is put by IPython into the builtin namespace, so it
33 is always available from all running code.
33 is always available from all running code.
34
34
35 $Id: hooks.py 535 2005-03-02 08:42:25Z fperez $"""
35 $Id: hooks.py 960 2005-12-28 06:51:01Z fperez $"""
36
36
37 #*****************************************************************************
37 #*****************************************************************************
38 # Copyright (C) 2005 Fernando Perez. <fperez@colorado.edu>
38 # Copyright (C) 2005 Fernando Perez. <fperez@colorado.edu>
39 #
39 #
40 # Distributed under the terms of the BSD License. The full license is in
40 # Distributed under the terms of the BSD License. The full license is in
41 # the file COPYING, distributed as part of this software.
41 # the file COPYING, distributed as part of this software.
42 #*****************************************************************************
42 #*****************************************************************************
43
43
44 from IPython import Release
44 from IPython import Release
45 __author__ = '%s <%s>' % Release.authors['Fernando']
45 __author__ = '%s <%s>' % Release.authors['Fernando']
46 __license__ = Release.license
46 __license__ = Release.license
47 __version__ = Release.version
47 __version__ = Release.version
48
48
49 import os
49 import os
50
50
51 # List here all the default hooks. For now it's just the editor, but over
51 # List here all the default hooks. For now it's just the editor functions
52 # time we'll move here all the public API for user-accessible things.
52 # but over time we'll move here all the public API for user-accessible things.
53 __all__ = ['editor']
53 __all__ = ['editor', 'fix_error_editor']
54
54
55 def editor(self,filename, linenum):
55 def editor(self,filename, linenum):
56 """Open the default editor at the given filename and linenumber.
56 """Open the default editor at the given filename and linenumber.
57
57
58 This is IPython's default editor hook, you can use it as an example to
58 This is IPython's default editor hook, you can use it as an example to
59 write your own modified one. To set your own editor function as the
59 write your own modified one. To set your own editor function as the
60 new editor hook, call ip_set_hook('editor',yourfunc)."""
60 new editor hook, call ip_set_hook('editor',yourfunc)."""
61
61
62 # IPython configures a default editor at startup by reading $EDITOR from
62 # IPython configures a default editor at startup by reading $EDITOR from
63 # the environment, and falling back on vi (unix) or notepad (win32).
63 # the environment, and falling back on vi (unix) or notepad (win32).
64 editor = self.rc.editor
64 editor = self.rc.editor
65
65
66 # marker for at which line to open the file (for existing objects)
66 # marker for at which line to open the file (for existing objects)
67 if linenum is None or editor=='notepad':
67 if linenum is None or editor=='notepad':
68 linemark = ''
68 linemark = ''
69 else:
69 else:
70 linemark = '+%d' % linenum
70 linemark = '+%d' % linenum
71 # Call the actual editor
71 # Call the actual editor
72 os.system('%s %s %s' % (editor,linemark,filename))
72 os.system('%s %s %s' % (editor,linemark,filename))
73
74 import tempfile
75 def fix_error_editor(self,filename,linenum,column,msg):
76 """Open the editor at the given filename, linenumber, column and
77 show an error message. This is used for correcting syntax errors.
78 The current implementation only has special support for the VIM editor,
79 and falls back on the 'editor' hook if VIM is not used.
80
81 Call ip_set_hook('fix_error_editor',youfunc) to use your own function,
82 """
83 def vim_quickfix_file():
84 t = tempfile.NamedTemporaryFile()
85 t.write('%s:%d:%d:%s\n' % (filename,linenum,column,msg))
86 t.flush()
87 return t
88 if os.path.basename(self.rc.editor) != 'vim':
89 self.hooks.editor(filename,linenum)
90 return
91 t = vim_quickfix_file()
92 try:
93 os.system('vim --cmd "set errorformat=%f:%l:%c:%m" -q ' + t.name)
94 finally:
95 t.close()
@@ -1,1904 +1,1964 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 959 2005-12-28 02:04:41Z fperez $
9 $Id: iplib.py 960 2005-12-28 06:51:01Z 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,magic2python
71 from IPython.Struct import Struct
71 from IPython.Struct import Struct
72 from IPython.background_jobs import BackgroundJobManager
72 from IPython.background_jobs import BackgroundJobManager
73 from IPython.usage import cmd_line_usage,interactive_usage
73 from IPython.usage import cmd_line_usage,interactive_usage
74 from IPython.genutils import *
74 from IPython.genutils import *
75
75
76 # store the builtin raw_input globally, and use this always, in case user code
76 # store the builtin raw_input globally, and use this always, in case user code
77 # overwrites it (like wx.py.PyShell does)
77 # overwrites it (like wx.py.PyShell does)
78 raw_input_original = raw_input
78 raw_input_original = raw_input
79
79
80 #****************************************************************************
80 #****************************************************************************
81 # Some utility function definitions
81 # Some utility function definitions
82
82
83 # This can be replaced with an isspace() call once we drop 2.2 compatibility
83 # This can be replaced with an isspace() call once we drop 2.2 compatibility
84 _isspace_match = re.compile(r'^\s+$').match
84 _isspace_match = re.compile(r'^\s+$').match
85 def isspace(s):
85 def isspace(s):
86 return bool(_isspace_match(s))
86 return bool(_isspace_match(s))
87
87
88 def esc_quotes(strng):
88 def esc_quotes(strng):
89 """Return the input string with single and double quotes escaped out"""
89 """Return the input string with single and double quotes escaped out"""
90
90
91 return strng.replace('"','\\"').replace("'","\\'")
91 return strng.replace('"','\\"').replace("'","\\'")
92
92
93 def import_fail_info(mod_name,fns=None):
93 def import_fail_info(mod_name,fns=None):
94 """Inform load failure for a module."""
94 """Inform load failure for a module."""
95
95
96 if fns == None:
96 if fns == None:
97 warn("Loading of %s failed.\n" % (mod_name,))
97 warn("Loading of %s failed.\n" % (mod_name,))
98 else:
98 else:
99 warn("Loading of %s from %s failed.\n" % (fns,mod_name))
99 warn("Loading of %s from %s failed.\n" % (fns,mod_name))
100
100
101 def qw_lol(indata):
101 def qw_lol(indata):
102 """qw_lol('a b') -> [['a','b']],
102 """qw_lol('a b') -> [['a','b']],
103 otherwise it's just a call to qw().
103 otherwise it's just a call to qw().
104
104
105 We need this to make sure the modules_some keys *always* end up as a
105 We need this to make sure the modules_some keys *always* end up as a
106 list of lists."""
106 list of lists."""
107
107
108 if type(indata) in StringTypes:
108 if type(indata) in StringTypes:
109 return [qw(indata)]
109 return [qw(indata)]
110 else:
110 else:
111 return qw(indata)
111 return qw(indata)
112
112
113 def ipmagic(arg_s):
113 def ipmagic(arg_s):
114 """Call a magic function by name.
114 """Call a magic function by name.
115
115
116 Input: a string containing the name of the magic function to call and any
116 Input: a string containing the name of the magic function to call and any
117 additional arguments to be passed to the magic.
117 additional arguments to be passed to the magic.
118
118
119 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
119 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
120 prompt:
120 prompt:
121
121
122 In[1]: %name -opt foo bar
122 In[1]: %name -opt foo bar
123
123
124 To call a magic without arguments, simply use ipmagic('name').
124 To call a magic without arguments, simply use ipmagic('name').
125
125
126 This provides a proper Python function to call IPython's magics in any
126 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
127 valid Python code you can type at the interpreter, including loops and
128 compound statements. It is added by IPython to the Python builtin
128 compound statements. It is added by IPython to the Python builtin
129 namespace upon initialization."""
129 namespace upon initialization."""
130
130
131 args = arg_s.split(' ',1)
131 args = arg_s.split(' ',1)
132 magic_name = args[0]
132 magic_name = args[0]
133 if magic_name.startswith(__IPYTHON__.ESC_MAGIC):
133 if magic_name.startswith(__IPYTHON__.ESC_MAGIC):
134 magic_name = magic_name[1:]
134 magic_name = magic_name[1:]
135 try:
135 try:
136 magic_args = args[1]
136 magic_args = args[1]
137 except IndexError:
137 except IndexError:
138 magic_args = ''
138 magic_args = ''
139 fn = getattr(__IPYTHON__,'magic_'+magic_name,None)
139 fn = getattr(__IPYTHON__,'magic_'+magic_name,None)
140 if fn is None:
140 if fn is None:
141 error("Magic function `%s` not found." % magic_name)
141 error("Magic function `%s` not found." % magic_name)
142 else:
142 else:
143 magic_args = __IPYTHON__.var_expand(magic_args)
143 magic_args = __IPYTHON__.var_expand(magic_args)
144 return fn(magic_args)
144 return fn(magic_args)
145
145
146 def ipalias(arg_s):
146 def ipalias(arg_s):
147 """Call an alias by name.
147 """Call an alias by name.
148
148
149 Input: a string containing the name of the alias to call and any
149 Input: a string containing the name of the alias to call and any
150 additional arguments to be passed to the magic.
150 additional arguments to be passed to the magic.
151
151
152 ipalias('name -opt foo bar') is equivalent to typing at the ipython
152 ipalias('name -opt foo bar') is equivalent to typing at the ipython
153 prompt:
153 prompt:
154
154
155 In[1]: name -opt foo bar
155 In[1]: name -opt foo bar
156
156
157 To call an alias without arguments, simply use ipalias('name').
157 To call an alias without arguments, simply use ipalias('name').
158
158
159 This provides a proper Python function to call IPython's aliases in any
159 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
160 valid Python code you can type at the interpreter, including loops and
161 compound statements. It is added by IPython to the Python builtin
161 compound statements. It is added by IPython to the Python builtin
162 namespace upon initialization."""
162 namespace upon initialization."""
163
163
164 args = arg_s.split(' ',1)
164 args = arg_s.split(' ',1)
165 alias_name = args[0]
165 alias_name = args[0]
166 try:
166 try:
167 alias_args = args[1]
167 alias_args = args[1]
168 except IndexError:
168 except IndexError:
169 alias_args = ''
169 alias_args = ''
170 if alias_name in __IPYTHON__.alias_table:
170 if alias_name in __IPYTHON__.alias_table:
171 __IPYTHON__.call_alias(alias_name,alias_args)
171 __IPYTHON__.call_alias(alias_name,alias_args)
172 else:
172 else:
173 error("Alias `%s` not found." % alias_name)
173 error("Alias `%s` not found." % alias_name)
174
174
175 def softspace(file, newvalue):
175 def softspace(file, newvalue):
176 """Copied from code.py, to remove the dependency"""
176 """Copied from code.py, to remove the dependency"""
177 oldvalue = 0
177 oldvalue = 0
178 try:
178 try:
179 oldvalue = file.softspace
179 oldvalue = file.softspace
180 except AttributeError:
180 except AttributeError:
181 pass
181 pass
182 try:
182 try:
183 file.softspace = newvalue
183 file.softspace = newvalue
184 except (AttributeError, TypeError):
184 except (AttributeError, TypeError):
185 # "attribute-less object" or "read-only attributes"
185 # "attribute-less object" or "read-only attributes"
186 pass
186 pass
187 return oldvalue
187 return oldvalue
188
188
189
189
190 #****************************************************************************
190 #****************************************************************************
191 # Local use exceptions
191 # Local use exceptions
192 class SpaceInInput(exceptions.Exception): pass
192 class SpaceInInput(exceptions.Exception): pass
193
193
194 class IPythonExit(exceptions.Exception): pass
194 class IPythonExit(exceptions.Exception): pass
195
195
196 #****************************************************************************
196 #****************************************************************************
197 # Local use classes
197 # Local use classes
198 class Bunch: pass
198 class Bunch: pass
199
199
200 class InputList(list):
200 class InputList(list):
201 """Class to store user input.
201 """Class to store user input.
202
202
203 It's basically a list, but slices return a string instead of a list, thus
203 It's basically a list, but slices return a string instead of a list, thus
204 allowing things like (assuming 'In' is an instance):
204 allowing things like (assuming 'In' is an instance):
205
205
206 exec In[4:7]
206 exec In[4:7]
207
207
208 or
208 or
209
209
210 exec In[5:9] + In[14] + In[21:25]"""
210 exec In[5:9] + In[14] + In[21:25]"""
211
211
212 def __getslice__(self,i,j):
212 def __getslice__(self,i,j):
213 return ''.join(list.__getslice__(self,i,j))
213 return ''.join(list.__getslice__(self,i,j))
214
214
215 class SyntaxTB(ultraTB.ListTB):
216 """Extension which holds some state: the last exception value"""
217
218 def __init__(self,color_scheme = 'NoColor'):
219 ultraTB.ListTB.__init__(self,color_scheme)
220 self.last_syntax_error = None
221
222 def __call__(self, etype, value, elist):
223 self.last_syntax_error = value
224 ultraTB.ListTB.__call__(self,etype,value,elist)
225
226 def clear_err_state(self):
227 """Return the current error state and clear it"""
228 e = self.last_syntax_error
229 self.last_syntax_error = None
230 return e
231
215 #****************************************************************************
232 #****************************************************************************
216 # Main IPython class
233 # Main IPython class
217 class InteractiveShell(Logger, Magic):
234 class InteractiveShell(Logger, Magic):
218 """An enhanced console for Python."""
235 """An enhanced console for Python."""
219
236
220 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
237 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
221 user_ns = None,user_global_ns=None,banner2='',
238 user_ns = None,user_global_ns=None,banner2='',
222 custom_exceptions=((),None),embedded=False):
239 custom_exceptions=((),None),embedded=False):
223
240
224 # Put a reference to self in builtins so that any form of embedded or
241 # Put a reference to self in builtins so that any form of embedded or
225 # imported code can test for being inside IPython.
242 # imported code can test for being inside IPython.
226 __builtin__.__IPYTHON__ = self
243 __builtin__.__IPYTHON__ = self
227
244
228 # And load into builtins ipmagic/ipalias as well
245 # And load into builtins ipmagic/ipalias as well
229 __builtin__.ipmagic = ipmagic
246 __builtin__.ipmagic = ipmagic
230 __builtin__.ipalias = ipalias
247 __builtin__.ipalias = ipalias
231
248
232 # Add to __builtin__ other parts of IPython's public API
249 # Add to __builtin__ other parts of IPython's public API
233 __builtin__.ip_set_hook = self.set_hook
250 __builtin__.ip_set_hook = self.set_hook
234
251
235 # Keep in the builtins a flag for when IPython is active. We set it
252 # Keep in the builtins a flag for when IPython is active. We set it
236 # with setdefault so that multiple nested IPythons don't clobber one
253 # with setdefault so that multiple nested IPythons don't clobber one
237 # another. Each will increase its value by one upon being activated,
254 # another. Each will increase its value by one upon being activated,
238 # which also gives us a way to determine the nesting level.
255 # which also gives us a way to determine the nesting level.
239 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
256 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
240
257
241 # Do the intuitively correct thing for quit/exit: we remove the
258 # Do the intuitively correct thing for quit/exit: we remove the
242 # builtins if they exist, and our own prefilter routine will handle
259 # builtins if they exist, and our own prefilter routine will handle
243 # these special cases
260 # these special cases
244 try:
261 try:
245 del __builtin__.exit, __builtin__.quit
262 del __builtin__.exit, __builtin__.quit
246 except AttributeError:
263 except AttributeError:
247 pass
264 pass
248
265
249 # We need to know whether the instance is meant for embedding, since
266 # We need to know whether the instance is meant for embedding, since
250 # global/local namespaces need to be handled differently in that case
267 # global/local namespaces need to be handled differently in that case
251 self.embedded = embedded
268 self.embedded = embedded
252
269
253 # command compiler
270 # command compiler
254 self.compile = codeop.CommandCompiler()
271 self.compile = codeop.CommandCompiler()
255
272
256 # User input buffer
273 # User input buffer
257 self.buffer = []
274 self.buffer = []
258
275
259 # Default name given in compilation of code
276 # Default name given in compilation of code
260 self.filename = '<ipython console>'
277 self.filename = '<ipython console>'
261
278
262 # Create the namespace where the user will operate. user_ns is
279 # Create the namespace where the user will operate. user_ns is
263 # normally the only one used, and it is passed to the exec calls as
280 # normally the only one used, and it is passed to the exec calls as
264 # the locals argument. But we do carry a user_global_ns namespace
281 # the locals argument. But we do carry a user_global_ns namespace
265 # given as the exec 'globals' argument, This is useful in embedding
282 # given as the exec 'globals' argument, This is useful in embedding
266 # situations where the ipython shell opens in a context where the
283 # situations where the ipython shell opens in a context where the
267 # distinction between locals and globals is meaningful.
284 # distinction between locals and globals is meaningful.
268
285
269 # FIXME. For some strange reason, __builtins__ is showing up at user
286 # FIXME. For some strange reason, __builtins__ is showing up at user
270 # level as a dict instead of a module. This is a manual fix, but I
287 # level as a dict instead of a module. This is a manual fix, but I
271 # should really track down where the problem is coming from. Alex
288 # should really track down where the problem is coming from. Alex
272 # Schmolck reported this problem first.
289 # Schmolck reported this problem first.
273
290
274 # A useful post by Alex Martelli on this topic:
291 # A useful post by Alex Martelli on this topic:
275 # Re: inconsistent value from __builtins__
292 # Re: inconsistent value from __builtins__
276 # Von: Alex Martelli <aleaxit@yahoo.com>
293 # Von: Alex Martelli <aleaxit@yahoo.com>
277 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
294 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
278 # Gruppen: comp.lang.python
295 # Gruppen: comp.lang.python
279 # Referenzen: 1
296 # Referenzen: 1
280
297
281 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
298 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
282 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
299 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
283 # > <type 'dict'>
300 # > <type 'dict'>
284 # > >>> print type(__builtins__)
301 # > >>> print type(__builtins__)
285 # > <type 'module'>
302 # > <type 'module'>
286 # > Is this difference in return value intentional?
303 # > Is this difference in return value intentional?
287
304
288 # Well, it's documented that '__builtins__' can be either a dictionary
305 # Well, it's documented that '__builtins__' can be either a dictionary
289 # or a module, and it's been that way for a long time. Whether it's
306 # or a module, and it's been that way for a long time. Whether it's
290 # intentional (or sensible), I don't know. In any case, the idea is
307 # intentional (or sensible), I don't know. In any case, the idea is
291 # that if you need to access the built-in namespace directly, you
308 # that if you need to access the built-in namespace directly, you
292 # should start with "import __builtin__" (note, no 's') which will
309 # should start with "import __builtin__" (note, no 's') which will
293 # definitely give you a module. Yeah, it's somewhat confusing:-(.
310 # definitely give you a module. Yeah, it's somewhat confusing:-(.
294
311
295 if user_ns is None:
312 if user_ns is None:
296 # Set __name__ to __main__ to better match the behavior of the
313 # Set __name__ to __main__ to better match the behavior of the
297 # normal interpreter.
314 # normal interpreter.
298 user_ns = {'__name__' :'__main__',
315 user_ns = {'__name__' :'__main__',
299 '__builtins__' : __builtin__,
316 '__builtins__' : __builtin__,
300 }
317 }
301
318
302 if user_global_ns is None:
319 if user_global_ns is None:
303 user_global_ns = {}
320 user_global_ns = {}
304
321
305 # Assign namespaces
322 # Assign namespaces
306 # This is the namespace where all normal user variables live
323 # This is the namespace where all normal user variables live
307 self.user_ns = user_ns
324 self.user_ns = user_ns
308 # Embedded instances require a separate namespace for globals.
325 # Embedded instances require a separate namespace for globals.
309 # Normally this one is unused by non-embedded instances.
326 # Normally this one is unused by non-embedded instances.
310 self.user_global_ns = user_global_ns
327 self.user_global_ns = user_global_ns
311 # A namespace to keep track of internal data structures to prevent
328 # A namespace to keep track of internal data structures to prevent
312 # them from cluttering user-visible stuff. Will be updated later
329 # them from cluttering user-visible stuff. Will be updated later
313 self.internal_ns = {}
330 self.internal_ns = {}
314
331
315 # Namespace of system aliases. Each entry in the alias
332 # Namespace of system aliases. Each entry in the alias
316 # table must be a 2-tuple of the form (N,name), where N is the number
333 # table must be a 2-tuple of the form (N,name), where N is the number
317 # of positional arguments of the alias.
334 # of positional arguments of the alias.
318 self.alias_table = {}
335 self.alias_table = {}
319
336
320 # A table holding all the namespaces IPython deals with, so that
337 # A table holding all the namespaces IPython deals with, so that
321 # introspection facilities can search easily.
338 # introspection facilities can search easily.
322 self.ns_table = {'user':user_ns,
339 self.ns_table = {'user':user_ns,
323 'user_global':user_global_ns,
340 'user_global':user_global_ns,
324 'alias':self.alias_table,
341 'alias':self.alias_table,
325 'internal':self.internal_ns,
342 'internal':self.internal_ns,
326 'builtin':__builtin__.__dict__
343 'builtin':__builtin__.__dict__
327 }
344 }
328
345
329 # The user namespace MUST have a pointer to the shell itself.
346 # The user namespace MUST have a pointer to the shell itself.
330 self.user_ns[name] = self
347 self.user_ns[name] = self
331
348
332 # We need to insert into sys.modules something that looks like a
349 # We need to insert into sys.modules something that looks like a
333 # module but which accesses the IPython namespace, for shelve and
350 # module but which accesses the IPython namespace, for shelve and
334 # pickle to work interactively. Normally they rely on getting
351 # pickle to work interactively. Normally they rely on getting
335 # everything out of __main__, but for embedding purposes each IPython
352 # everything out of __main__, but for embedding purposes each IPython
336 # instance has its own private namespace, so we can't go shoving
353 # instance has its own private namespace, so we can't go shoving
337 # everything into __main__.
354 # everything into __main__.
338
355
339 # note, however, that we should only do this for non-embedded
356 # note, however, that we should only do this for non-embedded
340 # ipythons, which really mimic the __main__.__dict__ with their own
357 # ipythons, which really mimic the __main__.__dict__ with their own
341 # namespace. Embedded instances, on the other hand, should not do
358 # namespace. Embedded instances, on the other hand, should not do
342 # this because they need to manage the user local/global namespaces
359 # this because they need to manage the user local/global namespaces
343 # only, but they live within a 'normal' __main__ (meaning, they
360 # only, but they live within a 'normal' __main__ (meaning, they
344 # shouldn't overtake the execution environment of the script they're
361 # shouldn't overtake the execution environment of the script they're
345 # embedded in).
362 # embedded in).
346
363
347 if not embedded:
364 if not embedded:
348 try:
365 try:
349 main_name = self.user_ns['__name__']
366 main_name = self.user_ns['__name__']
350 except KeyError:
367 except KeyError:
351 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
368 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
352 else:
369 else:
353 #print "pickle hack in place" # dbg
370 #print "pickle hack in place" # dbg
354 sys.modules[main_name] = FakeModule(self.user_ns)
371 sys.modules[main_name] = FakeModule(self.user_ns)
355
372
356 # List of input with multi-line handling.
373 # List of input with multi-line handling.
357 # Fill its zero entry, user counter starts at 1
374 # Fill its zero entry, user counter starts at 1
358 self.input_hist = InputList(['\n'])
375 self.input_hist = InputList(['\n'])
359
376
360 # list of visited directories
377 # list of visited directories
361 try:
378 try:
362 self.dir_hist = [os.getcwd()]
379 self.dir_hist = [os.getcwd()]
363 except IOError, e:
380 except IOError, e:
364 self.dir_hist = []
381 self.dir_hist = []
365
382
366 # dict of output history
383 # dict of output history
367 self.output_hist = {}
384 self.output_hist = {}
368
385
369 # dict of things NOT to alias (keywords, builtins and some magics)
386 # dict of things NOT to alias (keywords, builtins and some magics)
370 no_alias = {}
387 no_alias = {}
371 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
388 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
372 for key in keyword.kwlist + no_alias_magics:
389 for key in keyword.kwlist + no_alias_magics:
373 no_alias[key] = 1
390 no_alias[key] = 1
374 no_alias.update(__builtin__.__dict__)
391 no_alias.update(__builtin__.__dict__)
375 self.no_alias = no_alias
392 self.no_alias = no_alias
376
393
377 # make global variables for user access to these
394 # make global variables for user access to these
378 self.user_ns['_ih'] = self.input_hist
395 self.user_ns['_ih'] = self.input_hist
379 self.user_ns['_oh'] = self.output_hist
396 self.user_ns['_oh'] = self.output_hist
380 self.user_ns['_dh'] = self.dir_hist
397 self.user_ns['_dh'] = self.dir_hist
381
398
382 # user aliases to input and output histories
399 # user aliases to input and output histories
383 self.user_ns['In'] = self.input_hist
400 self.user_ns['In'] = self.input_hist
384 self.user_ns['Out'] = self.output_hist
401 self.user_ns['Out'] = self.output_hist
385
402
386 # Store the actual shell's name
403 # Store the actual shell's name
387 self.name = name
404 self.name = name
388
405
389 # Object variable to store code object waiting execution. This is
406 # Object variable to store code object waiting execution. This is
390 # used mainly by the multithreaded shells, but it can come in handy in
407 # used mainly by the multithreaded shells, but it can come in handy in
391 # other situations. No need to use a Queue here, since it's a single
408 # other situations. No need to use a Queue here, since it's a single
392 # item which gets cleared once run.
409 # item which gets cleared once run.
393 self.code_to_run = None
410 self.code_to_run = None
394
411
395 # Job manager (for jobs run as background threads)
412 # Job manager (for jobs run as background threads)
396 self.jobs = BackgroundJobManager()
413 self.jobs = BackgroundJobManager()
397 # Put the job manager into builtins so it's always there.
414 # Put the job manager into builtins so it's always there.
398 __builtin__.jobs = self.jobs
415 __builtin__.jobs = self.jobs
399
416
400 # escapes for automatic behavior on the command line
417 # escapes for automatic behavior on the command line
401 self.ESC_SHELL = '!'
418 self.ESC_SHELL = '!'
402 self.ESC_HELP = '?'
419 self.ESC_HELP = '?'
403 self.ESC_MAGIC = '%'
420 self.ESC_MAGIC = '%'
404 self.ESC_QUOTE = ','
421 self.ESC_QUOTE = ','
405 self.ESC_QUOTE2 = ';'
422 self.ESC_QUOTE2 = ';'
406 self.ESC_PAREN = '/'
423 self.ESC_PAREN = '/'
407
424
408 # And their associated handlers
425 # And their associated handlers
409 self.esc_handlers = {self.ESC_PAREN:self.handle_auto,
426 self.esc_handlers = {self.ESC_PAREN:self.handle_auto,
410 self.ESC_QUOTE:self.handle_auto,
427 self.ESC_QUOTE:self.handle_auto,
411 self.ESC_QUOTE2:self.handle_auto,
428 self.ESC_QUOTE2:self.handle_auto,
412 self.ESC_MAGIC:self.handle_magic,
429 self.ESC_MAGIC:self.handle_magic,
413 self.ESC_HELP:self.handle_help,
430 self.ESC_HELP:self.handle_help,
414 self.ESC_SHELL:self.handle_shell_escape,
431 self.ESC_SHELL:self.handle_shell_escape,
415 }
432 }
416
433
417 # class initializations
434 # class initializations
418 Logger.__init__(self,log_ns = self.user_ns)
435 Logger.__init__(self,log_ns = self.user_ns)
419 Magic.__init__(self,self)
436 Magic.__init__(self,self)
420
437
421 # an ugly hack to get a pointer to the shell, so I can start writing
438 # an ugly hack to get a pointer to the shell, so I can start writing
422 # magic code via this pointer instead of the current mixin salad.
439 # magic code via this pointer instead of the current mixin salad.
423 Magic.set_shell(self,self)
440 Magic.set_shell(self,self)
424
441
425 # Python source parser/formatter for syntax highlighting
442 # Python source parser/formatter for syntax highlighting
426 pyformat = PyColorize.Parser().format
443 pyformat = PyColorize.Parser().format
427 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
444 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
428
445
429 # hooks holds pointers used for user-side customizations
446 # hooks holds pointers used for user-side customizations
430 self.hooks = Struct()
447 self.hooks = Struct()
431
448
432 # Set all default hooks, defined in the IPython.hooks module.
449 # Set all default hooks, defined in the IPython.hooks module.
433 hooks = IPython.hooks
450 hooks = IPython.hooks
434 for hook_name in hooks.__all__:
451 for hook_name in hooks.__all__:
435 self.set_hook(hook_name,getattr(hooks,hook_name))
452 self.set_hook(hook_name,getattr(hooks,hook_name))
436
453
437 # Flag to mark unconditional exit
454 # Flag to mark unconditional exit
438 self.exit_now = False
455 self.exit_now = False
439
456
440 self.usage_min = """\
457 self.usage_min = """\
441 An enhanced console for Python.
458 An enhanced console for Python.
442 Some of its features are:
459 Some of its features are:
443 - Readline support if the readline library is present.
460 - Readline support if the readline library is present.
444 - Tab completion in the local namespace.
461 - Tab completion in the local namespace.
445 - Logging of input, see command-line options.
462 - Logging of input, see command-line options.
446 - System shell escape via ! , eg !ls.
463 - System shell escape via ! , eg !ls.
447 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
464 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
448 - Keeps track of locally defined variables via %who, %whos.
465 - Keeps track of locally defined variables via %who, %whos.
449 - Show object information with a ? eg ?x or x? (use ?? for more info).
466 - Show object information with a ? eg ?x or x? (use ?? for more info).
450 """
467 """
451 if usage: self.usage = usage
468 if usage: self.usage = usage
452 else: self.usage = self.usage_min
469 else: self.usage = self.usage_min
453
470
454 # Storage
471 # Storage
455 self.rc = rc # This will hold all configuration information
472 self.rc = rc # This will hold all configuration information
456 self.inputcache = []
473 self.inputcache = []
457 self._boundcache = []
474 self._boundcache = []
458 self.pager = 'less'
475 self.pager = 'less'
459 # temporary files used for various purposes. Deleted at exit.
476 # temporary files used for various purposes. Deleted at exit.
460 self.tempfiles = []
477 self.tempfiles = []
461
478
462 # Keep track of readline usage (later set by init_readline)
479 # Keep track of readline usage (later set by init_readline)
463 self.has_readline = False
480 self.has_readline = False
464
481
465 # for pushd/popd management
482 # for pushd/popd management
466 try:
483 try:
467 self.home_dir = get_home_dir()
484 self.home_dir = get_home_dir()
468 except HomeDirError,msg:
485 except HomeDirError,msg:
469 fatal(msg)
486 fatal(msg)
470
487
471 self.dir_stack = [os.getcwd().replace(self.home_dir,'~')]
488 self.dir_stack = [os.getcwd().replace(self.home_dir,'~')]
472
489
473 # Functions to call the underlying shell.
490 # Functions to call the underlying shell.
474
491
475 # utility to expand user variables via Itpl
492 # utility to expand user variables via Itpl
476 self.var_expand = lambda cmd: str(ItplNS(cmd.replace('#','\#'),
493 self.var_expand = lambda cmd: str(ItplNS(cmd.replace('#','\#'),
477 self.user_ns))
494 self.user_ns))
478 # The first is similar to os.system, but it doesn't return a value,
495 # The first is similar to os.system, but it doesn't return a value,
479 # and it allows interpolation of variables in the user's namespace.
496 # and it allows interpolation of variables in the user's namespace.
480 self.system = lambda cmd: shell(self.var_expand(cmd),
497 self.system = lambda cmd: shell(self.var_expand(cmd),
481 header='IPython system call: ',
498 header='IPython system call: ',
482 verbose=self.rc.system_verbose)
499 verbose=self.rc.system_verbose)
483 # These are for getoutput and getoutputerror:
500 # These are for getoutput and getoutputerror:
484 self.getoutput = lambda cmd: \
501 self.getoutput = lambda cmd: \
485 getoutput(self.var_expand(cmd),
502 getoutput(self.var_expand(cmd),
486 header='IPython system call: ',
503 header='IPython system call: ',
487 verbose=self.rc.system_verbose)
504 verbose=self.rc.system_verbose)
488 self.getoutputerror = lambda cmd: \
505 self.getoutputerror = lambda cmd: \
489 getoutputerror(str(ItplNS(cmd.replace('#','\#'),
506 getoutputerror(str(ItplNS(cmd.replace('#','\#'),
490 self.user_ns)),
507 self.user_ns)),
491 header='IPython system call: ',
508 header='IPython system call: ',
492 verbose=self.rc.system_verbose)
509 verbose=self.rc.system_verbose)
493
510
494 # RegExp for splitting line contents into pre-char//first
511 # RegExp for splitting line contents into pre-char//first
495 # word-method//rest. For clarity, each group in on one line.
512 # word-method//rest. For clarity, each group in on one line.
496
513
497 # WARNING: update the regexp if the above escapes are changed, as they
514 # WARNING: update the regexp if the above escapes are changed, as they
498 # are hardwired in.
515 # are hardwired in.
499
516
500 # Don't get carried away with trying to make the autocalling catch too
517 # Don't get carried away with trying to make the autocalling catch too
501 # much: it's better to be conservative rather than to trigger hidden
518 # much: it's better to be conservative rather than to trigger hidden
502 # evals() somewhere and end up causing side effects.
519 # evals() somewhere and end up causing side effects.
503
520
504 self.line_split = re.compile(r'^([\s*,;/])'
521 self.line_split = re.compile(r'^([\s*,;/])'
505 r'([\?\w\.]+\w*\s*)'
522 r'([\?\w\.]+\w*\s*)'
506 r'(\(?.*$)')
523 r'(\(?.*$)')
507
524
508 # Original re, keep around for a while in case changes break something
525 # Original re, keep around for a while in case changes break something
509 #self.line_split = re.compile(r'(^[\s*!\?%,/]?)'
526 #self.line_split = re.compile(r'(^[\s*!\?%,/]?)'
510 # r'(\s*[\?\w\.]+\w*\s*)'
527 # r'(\s*[\?\w\.]+\w*\s*)'
511 # r'(\(?.*$)')
528 # r'(\(?.*$)')
512
529
513 # RegExp to identify potential function names
530 # RegExp to identify potential function names
514 self.re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
531 self.re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
515 # RegExp to exclude strings with this start from autocalling
532 # RegExp to exclude strings with this start from autocalling
516 self.re_exclude_auto = re.compile('^[!=()<>,\*/\+-]|^is ')
533 self.re_exclude_auto = re.compile('^[!=()<>,\*/\+-]|^is ')
517
534
518 # try to catch also methods for stuff in lists/tuples/dicts: off
535 # try to catch also methods for stuff in lists/tuples/dicts: off
519 # (experimental). For this to work, the line_split regexp would need
536 # (experimental). For this to work, the line_split regexp would need
520 # to be modified so it wouldn't break things at '['. That line is
537 # to be modified so it wouldn't break things at '['. That line is
521 # nasty enough that I shouldn't change it until I can test it _well_.
538 # nasty enough that I shouldn't change it until I can test it _well_.
522 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
539 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
523
540
524 # keep track of where we started running (mainly for crash post-mortem)
541 # keep track of where we started running (mainly for crash post-mortem)
525 self.starting_dir = os.getcwd()
542 self.starting_dir = os.getcwd()
526
543
527 # Attributes for Logger mixin class, make defaults here
544 # Attributes for Logger mixin class, make defaults here
528 self._dolog = False
545 self._dolog = False
529 self.LOG = ''
546 self.LOG = ''
530 self.LOGDEF = '.InteractiveShell.log'
547 self.LOGDEF = '.InteractiveShell.log'
531 self.LOGMODE = 'over'
548 self.LOGMODE = 'over'
532 self.LOGHEAD = Itpl(
549 self.LOGHEAD = Itpl(
533 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
550 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
534 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
551 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
535 #log# opts = $self.rc.opts
552 #log# opts = $self.rc.opts
536 #log# args = $self.rc.args
553 #log# args = $self.rc.args
537 #log# It is safe to make manual edits below here.
554 #log# It is safe to make manual edits below here.
538 #log#-----------------------------------------------------------------------
555 #log#-----------------------------------------------------------------------
539 """)
556 """)
540 # Various switches which can be set
557 # Various switches which can be set
541 self.CACHELENGTH = 5000 # this is cheap, it's just text
558 self.CACHELENGTH = 5000 # this is cheap, it's just text
542 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
559 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
543 self.banner2 = banner2
560 self.banner2 = banner2
544
561
545 # TraceBack handlers:
562 # TraceBack handlers:
546 # Need two, one for syntax errors and one for other exceptions.
563 # Need two, one for syntax errors and one for other exceptions.
547 self.SyntaxTB = ultraTB.ListTB(color_scheme='NoColor')
564 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
548 # This one is initialized with an offset, meaning we always want to
565 # The interactive one is initialized with an offset, meaning we always
549 # remove the topmost item in the traceback, which is our own internal
566 # want to remove the topmost item in the traceback, which is our own
550 # code. Valid modes: ['Plain','Context','Verbose']
567 # internal code. Valid modes: ['Plain','Context','Verbose']
551 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
568 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
552 color_scheme='NoColor',
569 color_scheme='NoColor',
553 tb_offset = 1)
570 tb_offset = 1)
554 # and add any custom exception handlers the user may have specified
571 # and add any custom exception handlers the user may have specified
555 self.set_custom_exc(*custom_exceptions)
572 self.set_custom_exc(*custom_exceptions)
556
573
557 # Object inspector
574 # Object inspector
558 self.inspector = OInspect.Inspector(OInspect.InspectColors,
575 self.inspector = OInspect.Inspector(OInspect.InspectColors,
559 PyColorize.ANSICodeColors,
576 PyColorize.ANSICodeColors,
560 'NoColor')
577 'NoColor')
561 # indentation management
578 # indentation management
562 self.autoindent = False
579 self.autoindent = False
563 self.indent_current_nsp = 0
580 self.indent_current_nsp = 0
564 self.indent_current = '' # actual indent string
581 self.indent_current = '' # actual indent string
565
582
566 # Make some aliases automatically
583 # Make some aliases automatically
567 # Prepare list of shell aliases to auto-define
584 # Prepare list of shell aliases to auto-define
568 if os.name == 'posix':
585 if os.name == 'posix':
569 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
586 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
570 'mv mv -i','rm rm -i','cp cp -i',
587 'mv mv -i','rm rm -i','cp cp -i',
571 'cat cat','less less','clear clear',
588 'cat cat','less less','clear clear',
572 # a better ls
589 # a better ls
573 'ls ls -F',
590 'ls ls -F',
574 # long ls
591 # long ls
575 'll ls -lF',
592 'll ls -lF',
576 # color ls
593 # color ls
577 'lc ls -F -o --color',
594 'lc ls -F -o --color',
578 # ls normal files only
595 # ls normal files only
579 'lf ls -F -o --color %l | grep ^-',
596 'lf ls -F -o --color %l | grep ^-',
580 # ls symbolic links
597 # ls symbolic links
581 'lk ls -F -o --color %l | grep ^l',
598 'lk ls -F -o --color %l | grep ^l',
582 # directories or links to directories,
599 # directories or links to directories,
583 'ldir ls -F -o --color %l | grep /$',
600 'ldir ls -F -o --color %l | grep /$',
584 # things which are executable
601 # things which are executable
585 'lx ls -F -o --color %l | grep ^-..x',
602 'lx ls -F -o --color %l | grep ^-..x',
586 )
603 )
587 elif os.name in ['nt','dos']:
604 elif os.name in ['nt','dos']:
588 auto_alias = ('dir dir /on', 'ls dir /on',
605 auto_alias = ('dir dir /on', 'ls dir /on',
589 'ddir dir /ad /on', 'ldir dir /ad /on',
606 'ddir dir /ad /on', 'ldir dir /ad /on',
590 'mkdir mkdir','rmdir rmdir','echo echo',
607 'mkdir mkdir','rmdir rmdir','echo echo',
591 'ren ren','cls cls','copy copy')
608 'ren ren','cls cls','copy copy')
592 else:
609 else:
593 auto_alias = ()
610 auto_alias = ()
594 self.auto_alias = map(lambda s:s.split(None,1),auto_alias)
611 self.auto_alias = map(lambda s:s.split(None,1),auto_alias)
595 # Call the actual (public) initializer
612 # Call the actual (public) initializer
596 self.init_auto_alias()
613 self.init_auto_alias()
597 # end __init__
614 # end __init__
598
615
599 def set_hook(self,name,hook):
616 def set_hook(self,name,hook):
600 """set_hook(name,hook) -> sets an internal IPython hook.
617 """set_hook(name,hook) -> sets an internal IPython hook.
601
618
602 IPython exposes some of its internal API as user-modifiable hooks. By
619 IPython exposes some of its internal API as user-modifiable hooks. By
603 resetting one of these hooks, you can modify IPython's behavior to
620 resetting one of these hooks, you can modify IPython's behavior to
604 call at runtime your own routines."""
621 call at runtime your own routines."""
605
622
606 # At some point in the future, this should validate the hook before it
623 # At some point in the future, this should validate the hook before it
607 # accepts it. Probably at least check that the hook takes the number
624 # accepts it. Probably at least check that the hook takes the number
608 # of args it's supposed to.
625 # of args it's supposed to.
609 setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
626 setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
610
627
611 def set_custom_exc(self,exc_tuple,handler):
628 def set_custom_exc(self,exc_tuple,handler):
612 """set_custom_exc(exc_tuple,handler)
629 """set_custom_exc(exc_tuple,handler)
613
630
614 Set a custom exception handler, which will be called if any of the
631 Set a custom exception handler, which will be called if any of the
615 exceptions in exc_tuple occur in the mainloop (specifically, in the
632 exceptions in exc_tuple occur in the mainloop (specifically, in the
616 runcode() method.
633 runcode() method.
617
634
618 Inputs:
635 Inputs:
619
636
620 - exc_tuple: a *tuple* of valid exceptions to call the defined
637 - exc_tuple: a *tuple* of valid exceptions to call the defined
621 handler for. It is very important that you use a tuple, and NOT A
638 handler for. It is very important that you use a tuple, and NOT A
622 LIST here, because of the way Python's except statement works. If
639 LIST here, because of the way Python's except statement works. If
623 you only want to trap a single exception, use a singleton tuple:
640 you only want to trap a single exception, use a singleton tuple:
624
641
625 exc_tuple == (MyCustomException,)
642 exc_tuple == (MyCustomException,)
626
643
627 - handler: this must be defined as a function with the following
644 - handler: this must be defined as a function with the following
628 basic interface: def my_handler(self,etype,value,tb).
645 basic interface: def my_handler(self,etype,value,tb).
629
646
630 This will be made into an instance method (via new.instancemethod)
647 This will be made into an instance method (via new.instancemethod)
631 of IPython itself, and it will be called if any of the exceptions
648 of IPython itself, and it will be called if any of the exceptions
632 listed in the exc_tuple are caught. If the handler is None, an
649 listed in the exc_tuple are caught. If the handler is None, an
633 internal basic one is used, which just prints basic info.
650 internal basic one is used, which just prints basic info.
634
651
635 WARNING: by putting in your own exception handler into IPython's main
652 WARNING: by putting in your own exception handler into IPython's main
636 execution loop, you run a very good chance of nasty crashes. This
653 execution loop, you run a very good chance of nasty crashes. This
637 facility should only be used if you really know what you are doing."""
654 facility should only be used if you really know what you are doing."""
638
655
639 assert type(exc_tuple)==type(()) , \
656 assert type(exc_tuple)==type(()) , \
640 "The custom exceptions must be given AS A TUPLE."
657 "The custom exceptions must be given AS A TUPLE."
641
658
642 def dummy_handler(self,etype,value,tb):
659 def dummy_handler(self,etype,value,tb):
643 print '*** Simple custom exception handler ***'
660 print '*** Simple custom exception handler ***'
644 print 'Exception type :',etype
661 print 'Exception type :',etype
645 print 'Exception value:',value
662 print 'Exception value:',value
646 print 'Traceback :',tb
663 print 'Traceback :',tb
647 print 'Source code :','\n'.join(self.buffer)
664 print 'Source code :','\n'.join(self.buffer)
648
665
649 if handler is None: handler = dummy_handler
666 if handler is None: handler = dummy_handler
650
667
651 self.CustomTB = new.instancemethod(handler,self,self.__class__)
668 self.CustomTB = new.instancemethod(handler,self,self.__class__)
652 self.custom_exceptions = exc_tuple
669 self.custom_exceptions = exc_tuple
653
670
654 def set_custom_completer(self,completer,pos=0):
671 def set_custom_completer(self,completer,pos=0):
655 """set_custom_completer(completer,pos=0)
672 """set_custom_completer(completer,pos=0)
656
673
657 Adds a new custom completer function.
674 Adds a new custom completer function.
658
675
659 The position argument (defaults to 0) is the index in the completers
676 The position argument (defaults to 0) is the index in the completers
660 list where you want the completer to be inserted."""
677 list where you want the completer to be inserted."""
661
678
662 newcomp = new.instancemethod(completer,self.Completer,
679 newcomp = new.instancemethod(completer,self.Completer,
663 self.Completer.__class__)
680 self.Completer.__class__)
664 self.Completer.matchers.insert(pos,newcomp)
681 self.Completer.matchers.insert(pos,newcomp)
665
682
666 def complete(self,text):
683 def complete(self,text):
667 """Return a sorted list of all possible completions on text.
684 """Return a sorted list of all possible completions on text.
668
685
669 Inputs:
686 Inputs:
670
687
671 - text: a string of text to be completed on.
688 - text: a string of text to be completed on.
672
689
673 This is a wrapper around the completion mechanism, similar to what
690 This is a wrapper around the completion mechanism, similar to what
674 readline does at the command line when the TAB key is hit. By
691 readline does at the command line when the TAB key is hit. By
675 exposing it as a method, it can be used by other non-readline
692 exposing it as a method, it can be used by other non-readline
676 environments (such as GUIs) for text completion.
693 environments (such as GUIs) for text completion.
677
694
678 Simple usage example:
695 Simple usage example:
679
696
680 In [1]: x = 'hello'
697 In [1]: x = 'hello'
681
698
682 In [2]: __IP.complete('x.l')
699 In [2]: __IP.complete('x.l')
683 Out[2]: ['x.ljust', 'x.lower', 'x.lstrip']"""
700 Out[2]: ['x.ljust', 'x.lower', 'x.lstrip']"""
684
701
685 complete = self.Completer.complete
702 complete = self.Completer.complete
686 state = 0
703 state = 0
687 # use a dict so we get unique keys, since ipyhton's multiple
704 # use a dict so we get unique keys, since ipyhton's multiple
688 # completers can return duplicates.
705 # completers can return duplicates.
689 comps = {}
706 comps = {}
690 while True:
707 while True:
691 newcomp = complete(text,state)
708 newcomp = complete(text,state)
692 if newcomp is None:
709 if newcomp is None:
693 break
710 break
694 comps[newcomp] = 1
711 comps[newcomp] = 1
695 state += 1
712 state += 1
696 outcomps = comps.keys()
713 outcomps = comps.keys()
697 outcomps.sort()
714 outcomps.sort()
698 return outcomps
715 return outcomps
699
716
700 def set_completer_frame(self, frame):
717 def set_completer_frame(self, frame):
701 if frame:
718 if frame:
702 self.Completer.namespace = frame.f_locals
719 self.Completer.namespace = frame.f_locals
703 self.Completer.global_namespace = frame.f_globals
720 self.Completer.global_namespace = frame.f_globals
704 else:
721 else:
705 self.Completer.namespace = self.user_ns
722 self.Completer.namespace = self.user_ns
706 self.Completer.global_namespace = self.user_global_ns
723 self.Completer.global_namespace = self.user_global_ns
707
724
708 def post_config_initialization(self):
725 def post_config_initialization(self):
709 """Post configuration init method
726 """Post configuration init method
710
727
711 This is called after the configuration files have been processed to
728 This is called after the configuration files have been processed to
712 'finalize' the initialization."""
729 'finalize' the initialization."""
713
730
714 rc = self.rc
731 rc = self.rc
715
732
716 # Load readline proper
733 # Load readline proper
717 if rc.readline:
734 if rc.readline:
718 self.init_readline()
735 self.init_readline()
719
736
720 # Set user colors (don't do it in the constructor above so that it
737 # Set user colors (don't do it in the constructor above so that it
721 # doesn't crash if colors option is invalid)
738 # doesn't crash if colors option is invalid)
722 self.magic_colors(rc.colors)
739 self.magic_colors(rc.colors)
723
740
724 # Load user aliases
741 # Load user aliases
725 for alias in rc.alias:
742 for alias in rc.alias:
726 self.magic_alias(alias)
743 self.magic_alias(alias)
727
744
728 # dynamic data that survives through sessions
745 # dynamic data that survives through sessions
729 # XXX make the filename a config option?
746 # XXX make the filename a config option?
730 persist_base = 'persist'
747 persist_base = 'persist'
731 if rc.profile:
748 if rc.profile:
732 persist_base += '_%s' % rc.profile
749 persist_base += '_%s' % rc.profile
733 self.persist_fname = os.path.join(rc.ipythondir,persist_base)
750 self.persist_fname = os.path.join(rc.ipythondir,persist_base)
734
751
735 try:
752 try:
736 self.persist = pickle.load(file(self.persist_fname))
753 self.persist = pickle.load(file(self.persist_fname))
737 except:
754 except:
738 self.persist = {}
755 self.persist = {}
739
756
740 def init_auto_alias(self):
757 def init_auto_alias(self):
741 """Define some aliases automatically.
758 """Define some aliases automatically.
742
759
743 These are ALL parameter-less aliases"""
760 These are ALL parameter-less aliases"""
744 for alias,cmd in self.auto_alias:
761 for alias,cmd in self.auto_alias:
745 self.alias_table[alias] = (0,cmd)
762 self.alias_table[alias] = (0,cmd)
746
763
747 def alias_table_validate(self,verbose=0):
764 def alias_table_validate(self,verbose=0):
748 """Update information about the alias table.
765 """Update information about the alias table.
749
766
750 In particular, make sure no Python keywords/builtins are in it."""
767 In particular, make sure no Python keywords/builtins are in it."""
751
768
752 no_alias = self.no_alias
769 no_alias = self.no_alias
753 for k in self.alias_table.keys():
770 for k in self.alias_table.keys():
754 if k in no_alias:
771 if k in no_alias:
755 del self.alias_table[k]
772 del self.alias_table[k]
756 if verbose:
773 if verbose:
757 print ("Deleting alias <%s>, it's a Python "
774 print ("Deleting alias <%s>, it's a Python "
758 "keyword or builtin." % k)
775 "keyword or builtin." % k)
759
776
760 def set_autoindent(self,value=None):
777 def set_autoindent(self,value=None):
761 """Set the autoindent flag, checking for readline support.
778 """Set the autoindent flag, checking for readline support.
762
779
763 If called with no arguments, it acts as a toggle."""
780 If called with no arguments, it acts as a toggle."""
764
781
765 if not self.has_readline:
782 if not self.has_readline:
766 if os.name == 'posix':
783 if os.name == 'posix':
767 warn("The auto-indent feature requires the readline library")
784 warn("The auto-indent feature requires the readline library")
768 self.autoindent = 0
785 self.autoindent = 0
769 return
786 return
770 if value is None:
787 if value is None:
771 self.autoindent = not self.autoindent
788 self.autoindent = not self.autoindent
772 else:
789 else:
773 self.autoindent = value
790 self.autoindent = value
774
791
775 def rc_set_toggle(self,rc_field,value=None):
792 def rc_set_toggle(self,rc_field,value=None):
776 """Set or toggle a field in IPython's rc config. structure.
793 """Set or toggle a field in IPython's rc config. structure.
777
794
778 If called with no arguments, it acts as a toggle.
795 If called with no arguments, it acts as a toggle.
779
796
780 If called with a non-existent field, the resulting AttributeError
797 If called with a non-existent field, the resulting AttributeError
781 exception will propagate out."""
798 exception will propagate out."""
782
799
783 rc_val = getattr(self.rc,rc_field)
800 rc_val = getattr(self.rc,rc_field)
784 if value is None:
801 if value is None:
785 value = not rc_val
802 value = not rc_val
786 setattr(self.rc,rc_field,value)
803 setattr(self.rc,rc_field,value)
787
804
788 def user_setup(self,ipythondir,rc_suffix,mode='install'):
805 def user_setup(self,ipythondir,rc_suffix,mode='install'):
789 """Install the user configuration directory.
806 """Install the user configuration directory.
790
807
791 Can be called when running for the first time or to upgrade the user's
808 Can be called when running for the first time or to upgrade the user's
792 .ipython/ directory with the mode parameter. Valid modes are 'install'
809 .ipython/ directory with the mode parameter. Valid modes are 'install'
793 and 'upgrade'."""
810 and 'upgrade'."""
794
811
795 def wait():
812 def wait():
796 try:
813 try:
797 raw_input("Please press <RETURN> to start IPython.")
814 raw_input("Please press <RETURN> to start IPython.")
798 except EOFError:
815 except EOFError:
799 print >> Term.cout
816 print >> Term.cout
800 print '*'*70
817 print '*'*70
801
818
802 cwd = os.getcwd() # remember where we started
819 cwd = os.getcwd() # remember where we started
803 glb = glob.glob
820 glb = glob.glob
804 print '*'*70
821 print '*'*70
805 if mode == 'install':
822 if mode == 'install':
806 print \
823 print \
807 """Welcome to IPython. I will try to create a personal configuration directory
824 """Welcome to IPython. I will try to create a personal configuration directory
808 where you can customize many aspects of IPython's functionality in:\n"""
825 where you can customize many aspects of IPython's functionality in:\n"""
809 else:
826 else:
810 print 'I am going to upgrade your configuration in:'
827 print 'I am going to upgrade your configuration in:'
811
828
812 print ipythondir
829 print ipythondir
813
830
814 rcdirend = os.path.join('IPython','UserConfig')
831 rcdirend = os.path.join('IPython','UserConfig')
815 cfg = lambda d: os.path.join(d,rcdirend)
832 cfg = lambda d: os.path.join(d,rcdirend)
816 try:
833 try:
817 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
834 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
818 except IOError:
835 except IOError:
819 warning = """
836 warning = """
820 Installation error. IPython's directory was not found.
837 Installation error. IPython's directory was not found.
821
838
822 Check the following:
839 Check the following:
823
840
824 The ipython/IPython directory should be in a directory belonging to your
841 The ipython/IPython directory should be in a directory belonging to your
825 PYTHONPATH environment variable (that is, it should be in a directory
842 PYTHONPATH environment variable (that is, it should be in a directory
826 belonging to sys.path). You can copy it explicitly there or just link to it.
843 belonging to sys.path). You can copy it explicitly there or just link to it.
827
844
828 IPython will proceed with builtin defaults.
845 IPython will proceed with builtin defaults.
829 """
846 """
830 warn(warning)
847 warn(warning)
831 wait()
848 wait()
832 return
849 return
833
850
834 if mode == 'install':
851 if mode == 'install':
835 try:
852 try:
836 shutil.copytree(rcdir,ipythondir)
853 shutil.copytree(rcdir,ipythondir)
837 os.chdir(ipythondir)
854 os.chdir(ipythondir)
838 rc_files = glb("ipythonrc*")
855 rc_files = glb("ipythonrc*")
839 for rc_file in rc_files:
856 for rc_file in rc_files:
840 os.rename(rc_file,rc_file+rc_suffix)
857 os.rename(rc_file,rc_file+rc_suffix)
841 except:
858 except:
842 warning = """
859 warning = """
843
860
844 There was a problem with the installation:
861 There was a problem with the installation:
845 %s
862 %s
846 Try to correct it or contact the developers if you think it's a bug.
863 Try to correct it or contact the developers if you think it's a bug.
847 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
864 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
848 warn(warning)
865 warn(warning)
849 wait()
866 wait()
850 return
867 return
851
868
852 elif mode == 'upgrade':
869 elif mode == 'upgrade':
853 try:
870 try:
854 os.chdir(ipythondir)
871 os.chdir(ipythondir)
855 except:
872 except:
856 print """
873 print """
857 Can not upgrade: changing to directory %s failed. Details:
874 Can not upgrade: changing to directory %s failed. Details:
858 %s
875 %s
859 """ % (ipythondir,sys.exc_info()[1])
876 """ % (ipythondir,sys.exc_info()[1])
860 wait()
877 wait()
861 return
878 return
862 else:
879 else:
863 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
880 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
864 for new_full_path in sources:
881 for new_full_path in sources:
865 new_filename = os.path.basename(new_full_path)
882 new_filename = os.path.basename(new_full_path)
866 if new_filename.startswith('ipythonrc'):
883 if new_filename.startswith('ipythonrc'):
867 new_filename = new_filename + rc_suffix
884 new_filename = new_filename + rc_suffix
868 # The config directory should only contain files, skip any
885 # The config directory should only contain files, skip any
869 # directories which may be there (like CVS)
886 # directories which may be there (like CVS)
870 if os.path.isdir(new_full_path):
887 if os.path.isdir(new_full_path):
871 continue
888 continue
872 if os.path.exists(new_filename):
889 if os.path.exists(new_filename):
873 old_file = new_filename+'.old'
890 old_file = new_filename+'.old'
874 if os.path.exists(old_file):
891 if os.path.exists(old_file):
875 os.remove(old_file)
892 os.remove(old_file)
876 os.rename(new_filename,old_file)
893 os.rename(new_filename,old_file)
877 shutil.copy(new_full_path,new_filename)
894 shutil.copy(new_full_path,new_filename)
878 else:
895 else:
879 raise ValueError,'unrecognized mode for install:',`mode`
896 raise ValueError,'unrecognized mode for install:',`mode`
880
897
881 # Fix line-endings to those native to each platform in the config
898 # Fix line-endings to those native to each platform in the config
882 # directory.
899 # directory.
883 try:
900 try:
884 os.chdir(ipythondir)
901 os.chdir(ipythondir)
885 except:
902 except:
886 print """
903 print """
887 Problem: changing to directory %s failed.
904 Problem: changing to directory %s failed.
888 Details:
905 Details:
889 %s
906 %s
890
907
891 Some configuration files may have incorrect line endings. This should not
908 Some configuration files may have incorrect line endings. This should not
892 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1])
909 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1])
893 wait()
910 wait()
894 else:
911 else:
895 for fname in glb('ipythonrc*'):
912 for fname in glb('ipythonrc*'):
896 try:
913 try:
897 native_line_ends(fname,backup=0)
914 native_line_ends(fname,backup=0)
898 except IOError:
915 except IOError:
899 pass
916 pass
900
917
901 if mode == 'install':
918 if mode == 'install':
902 print """
919 print """
903 Successful installation!
920 Successful installation!
904
921
905 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
922 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
906 IPython manual (there are both HTML and PDF versions supplied with the
923 IPython manual (there are both HTML and PDF versions supplied with the
907 distribution) to make sure that your system environment is properly configured
924 distribution) to make sure that your system environment is properly configured
908 to take advantage of IPython's features."""
925 to take advantage of IPython's features."""
909 else:
926 else:
910 print """
927 print """
911 Successful upgrade!
928 Successful upgrade!
912
929
913 All files in your directory:
930 All files in your directory:
914 %(ipythondir)s
931 %(ipythondir)s
915 which would have been overwritten by the upgrade were backed up with a .old
932 which would have been overwritten by the upgrade were backed up with a .old
916 extension. If you had made particular customizations in those files you may
933 extension. If you had made particular customizations in those files you may
917 want to merge them back into the new files.""" % locals()
934 want to merge them back into the new files.""" % locals()
918 wait()
935 wait()
919 os.chdir(cwd)
936 os.chdir(cwd)
920 # end user_setup()
937 # end user_setup()
921
938
922 def atexit_operations(self):
939 def atexit_operations(self):
923 """This will be executed at the time of exit.
940 """This will be executed at the time of exit.
924
941
925 Saving of persistent data should be performed here. """
942 Saving of persistent data should be performed here. """
926
943
927 # input history
944 # input history
928 self.savehist()
945 self.savehist()
929
946
930 # Cleanup all tempfiles left around
947 # Cleanup all tempfiles left around
931 for tfile in self.tempfiles:
948 for tfile in self.tempfiles:
932 try:
949 try:
933 os.unlink(tfile)
950 os.unlink(tfile)
934 except OSError:
951 except OSError:
935 pass
952 pass
936
953
937 # save the "persistent data" catch-all dictionary
954 # save the "persistent data" catch-all dictionary
938 try:
955 try:
939 pickle.dump(self.persist, open(self.persist_fname,"w"))
956 pickle.dump(self.persist, open(self.persist_fname,"w"))
940 except:
957 except:
941 print "*** ERROR *** persistent data saving failed."
958 print "*** ERROR *** persistent data saving failed."
942
959
943 def savehist(self):
960 def savehist(self):
944 """Save input history to a file (via readline library)."""
961 """Save input history to a file (via readline library)."""
945 try:
962 try:
946 self.readline.write_history_file(self.histfile)
963 self.readline.write_history_file(self.histfile)
947 except:
964 except:
948 print 'Unable to save IPython command history to file: ' + \
965 print 'Unable to save IPython command history to file: ' + \
949 `self.histfile`
966 `self.histfile`
950
967
951 def pre_readline(self):
968 def pre_readline(self):
952 """readline hook to be used at the start of each line.
969 """readline hook to be used at the start of each line.
953
970
954 Currently it handles auto-indent only."""
971 Currently it handles auto-indent only."""
955
972
956 self.readline.insert_text(self.indent_current)
973 self.readline.insert_text(self.indent_current)
957
974
958 def init_readline(self):
975 def init_readline(self):
959 """Command history completion/saving/reloading."""
976 """Command history completion/saving/reloading."""
960 try:
977 try:
961 import readline
978 import readline
962 except ImportError:
979 except ImportError:
963 self.has_readline = 0
980 self.has_readline = 0
964 self.readline = None
981 self.readline = None
965 # no point in bugging windows users with this every time:
982 # no point in bugging windows users with this every time:
966 if os.name == 'posix':
983 if os.name == 'posix':
967 warn('Readline services not available on this platform.')
984 warn('Readline services not available on this platform.')
968 else:
985 else:
969 import atexit
986 import atexit
970 from IPython.completer import IPCompleter
987 from IPython.completer import IPCompleter
971 self.Completer = IPCompleter(self,
988 self.Completer = IPCompleter(self,
972 self.user_ns,
989 self.user_ns,
973 self.user_global_ns,
990 self.user_global_ns,
974 self.rc.readline_omit__names,
991 self.rc.readline_omit__names,
975 self.alias_table)
992 self.alias_table)
976
993
977 # Platform-specific configuration
994 # Platform-specific configuration
978 if os.name == 'nt':
995 if os.name == 'nt':
979 self.readline_startup_hook = readline.set_pre_input_hook
996 self.readline_startup_hook = readline.set_pre_input_hook
980 else:
997 else:
981 self.readline_startup_hook = readline.set_startup_hook
998 self.readline_startup_hook = readline.set_startup_hook
982
999
983 # Load user's initrc file (readline config)
1000 # Load user's initrc file (readline config)
984 inputrc_name = os.environ.get('INPUTRC')
1001 inputrc_name = os.environ.get('INPUTRC')
985 if inputrc_name is None:
1002 if inputrc_name is None:
986 home_dir = get_home_dir()
1003 home_dir = get_home_dir()
987 if home_dir is not None:
1004 if home_dir is not None:
988 inputrc_name = os.path.join(home_dir,'.inputrc')
1005 inputrc_name = os.path.join(home_dir,'.inputrc')
989 if os.path.isfile(inputrc_name):
1006 if os.path.isfile(inputrc_name):
990 try:
1007 try:
991 readline.read_init_file(inputrc_name)
1008 readline.read_init_file(inputrc_name)
992 except:
1009 except:
993 warn('Problems reading readline initialization file <%s>'
1010 warn('Problems reading readline initialization file <%s>'
994 % inputrc_name)
1011 % inputrc_name)
995
1012
996 self.has_readline = 1
1013 self.has_readline = 1
997 self.readline = readline
1014 self.readline = readline
998 # save this in sys so embedded copies can restore it properly
1015 # save this in sys so embedded copies can restore it properly
999 sys.ipcompleter = self.Completer.complete
1016 sys.ipcompleter = self.Completer.complete
1000 readline.set_completer(self.Completer.complete)
1017 readline.set_completer(self.Completer.complete)
1001
1018
1002 # Configure readline according to user's prefs
1019 # Configure readline according to user's prefs
1003 for rlcommand in self.rc.readline_parse_and_bind:
1020 for rlcommand in self.rc.readline_parse_and_bind:
1004 readline.parse_and_bind(rlcommand)
1021 readline.parse_and_bind(rlcommand)
1005
1022
1006 # remove some chars from the delimiters list
1023 # remove some chars from the delimiters list
1007 delims = readline.get_completer_delims()
1024 delims = readline.get_completer_delims()
1008 delims = delims.translate(string._idmap,
1025 delims = delims.translate(string._idmap,
1009 self.rc.readline_remove_delims)
1026 self.rc.readline_remove_delims)
1010 readline.set_completer_delims(delims)
1027 readline.set_completer_delims(delims)
1011 # otherwise we end up with a monster history after a while:
1028 # otherwise we end up with a monster history after a while:
1012 readline.set_history_length(1000)
1029 readline.set_history_length(1000)
1013 try:
1030 try:
1014 #print '*** Reading readline history' # dbg
1031 #print '*** Reading readline history' # dbg
1015 readline.read_history_file(self.histfile)
1032 readline.read_history_file(self.histfile)
1016 except IOError:
1033 except IOError:
1017 pass # It doesn't exist yet.
1034 pass # It doesn't exist yet.
1018
1035
1019 atexit.register(self.atexit_operations)
1036 atexit.register(self.atexit_operations)
1020 del atexit
1037 del atexit
1021
1038
1022 # Configure auto-indent for all platforms
1039 # Configure auto-indent for all platforms
1023 self.set_autoindent(self.rc.autoindent)
1040 self.set_autoindent(self.rc.autoindent)
1024
1041
1042 def _should_recompile(self,e):
1043 """Utility routine for edit_syntax_error"""
1044
1045 if e.filename in ('<ipython console>','<input>','<string>',
1046 '<console>'):
1047 return False
1048 try:
1049 if not ask_yes_no('Return to editor to correct syntax error? '
1050 '[Y/n] ','y'):
1051 return False
1052 except EOFError:
1053 return False
1054 self.hooks.fix_error_editor(e.filename,e.lineno,e.offset,e.msg)
1055 return True
1056
1057 def edit_syntax_error(self):
1058 """The bottom half of the syntax error handler called in the main loop.
1059
1060 Loop until syntax error is fixed or user cancels.
1061 """
1062
1063 while self.SyntaxTB.last_syntax_error:
1064 # copy and clear last_syntax_error
1065 err = self.SyntaxTB.clear_err_state()
1066 if not self._should_recompile(err):
1067 return
1068 try:
1069 # may set last_syntax_error again if a SyntaxError is raised
1070 self.safe_execfile(err.filename,self.shell.user_ns)
1071 except:
1072 self.showtraceback()
1073 else:
1074 f = file(err.filename)
1075 try:
1076 sys.displayhook(f.read())
1077 finally:
1078 f.close()
1079
1025 def showsyntaxerror(self, filename=None):
1080 def showsyntaxerror(self, filename=None):
1026 """Display the syntax error that just occurred.
1081 """Display the syntax error that just occurred.
1027
1082
1028 This doesn't display a stack trace because there isn't one.
1083 This doesn't display a stack trace because there isn't one.
1029
1084
1030 If a filename is given, it is stuffed in the exception instead
1085 If a filename is given, it is stuffed in the exception instead
1031 of what was there before (because Python's parser always uses
1086 of what was there before (because Python's parser always uses
1032 "<string>" when reading from a string).
1087 "<string>" when reading from a string).
1033 """
1088 """
1034 type, value, sys.last_traceback = sys.exc_info()
1089 type, value, sys.last_traceback = sys.exc_info()
1035 sys.last_type = type
1090 sys.last_type = type
1036 sys.last_value = value
1091 sys.last_value = value
1037 if filename and type is SyntaxError:
1092 if filename and type is SyntaxError:
1038 # Work hard to stuff the correct filename in the exception
1093 # Work hard to stuff the correct filename in the exception
1039 try:
1094 try:
1040 msg, (dummy_filename, lineno, offset, line) = value
1095 msg, (dummy_filename, lineno, offset, line) = value
1041 except:
1096 except:
1042 # Not the format we expect; leave it alone
1097 # Not the format we expect; leave it alone
1043 pass
1098 pass
1044 else:
1099 else:
1045 # Stuff in the right filename
1100 # Stuff in the right filename
1046 try:
1101 try:
1047 # Assume SyntaxError is a class exception
1102 # Assume SyntaxError is a class exception
1048 value = SyntaxError(msg, (filename, lineno, offset, line))
1103 value = SyntaxError(msg, (filename, lineno, offset, line))
1049 except:
1104 except:
1050 # If that failed, assume SyntaxError is a string
1105 # If that failed, assume SyntaxError is a string
1051 value = msg, (filename, lineno, offset, line)
1106 value = msg, (filename, lineno, offset, line)
1052 self.SyntaxTB(type,value,[])
1107 self.SyntaxTB(type,value,[])
1053
1108
1054 def debugger(self):
1109 def debugger(self):
1055 """Call the pdb debugger."""
1110 """Call the pdb debugger."""
1056
1111
1057 if not self.rc.pdb:
1112 if not self.rc.pdb:
1058 return
1113 return
1059 pdb.pm()
1114 pdb.pm()
1060
1115
1061 def showtraceback(self,exc_tuple = None,filename=None):
1116 def showtraceback(self,exc_tuple = None,filename=None):
1062 """Display the exception that just occurred."""
1117 """Display the exception that just occurred."""
1063
1118
1064 # Though this won't be called by syntax errors in the input line,
1119 # Though this won't be called by syntax errors in the input line,
1065 # there may be SyntaxError cases whith imported code.
1120 # there may be SyntaxError cases whith imported code.
1066 if exc_tuple is None:
1121 if exc_tuple is None:
1067 type, value, tb = sys.exc_info()
1122 type, value, tb = sys.exc_info()
1068 else:
1123 else:
1069 type, value, tb = exc_tuple
1124 type, value, tb = exc_tuple
1070 if type is SyntaxError:
1125 if type is SyntaxError:
1071 self.showsyntaxerror(filename)
1126 self.showsyntaxerror(filename)
1072 else:
1127 else:
1073 sys.last_type = type
1128 sys.last_type = type
1074 sys.last_value = value
1129 sys.last_value = value
1075 sys.last_traceback = tb
1130 sys.last_traceback = tb
1076 self.InteractiveTB()
1131 self.InteractiveTB()
1077 if self.InteractiveTB.call_pdb and self.has_readline:
1132 if self.InteractiveTB.call_pdb and self.has_readline:
1078 # pdb mucks up readline, fix it back
1133 # pdb mucks up readline, fix it back
1079 self.readline.set_completer(self.Completer.complete)
1134 self.readline.set_completer(self.Completer.complete)
1080
1135
1081 def update_cache(self, line):
1136 def update_cache(self, line):
1082 """puts line into cache"""
1137 """puts line into cache"""
1083 self.inputcache.insert(0, line) # This copies the cache every time ... :-(
1138 self.inputcache.insert(0, line) # This copies the cache every time ... :-(
1084 if len(self.inputcache) >= self.CACHELENGTH:
1139 if len(self.inputcache) >= self.CACHELENGTH:
1085 self.inputcache.pop() # This doesn't :-)
1140 self.inputcache.pop() # This doesn't :-)
1086
1141
1087 def mainloop(self,banner=None):
1142 def mainloop(self,banner=None):
1088 """Creates the local namespace and starts the mainloop.
1143 """Creates the local namespace and starts the mainloop.
1089
1144
1090 If an optional banner argument is given, it will override the
1145 If an optional banner argument is given, it will override the
1091 internally created default banner."""
1146 internally created default banner."""
1092
1147
1093 if self.rc.c: # Emulate Python's -c option
1148 if self.rc.c: # Emulate Python's -c option
1094 self.exec_init_cmd()
1149 self.exec_init_cmd()
1095 if banner is None:
1150 if banner is None:
1096 if self.rc.banner:
1151 if self.rc.banner:
1097 banner = self.BANNER+self.banner2
1152 banner = self.BANNER+self.banner2
1098 else:
1153 else:
1099 banner = ''
1154 banner = ''
1100 self.interact(banner)
1155 self.interact(banner)
1101
1156
1102 def exec_init_cmd(self):
1157 def exec_init_cmd(self):
1103 """Execute a command given at the command line.
1158 """Execute a command given at the command line.
1104
1159
1105 This emulates Python's -c option."""
1160 This emulates Python's -c option."""
1106
1161
1107 sys.argv = ['-c']
1162 sys.argv = ['-c']
1108 self.push(self.rc.c)
1163 self.push(self.rc.c)
1109
1164
1110 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1165 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1111 """Embeds IPython into a running python program.
1166 """Embeds IPython into a running python program.
1112
1167
1113 Input:
1168 Input:
1114
1169
1115 - header: An optional header message can be specified.
1170 - header: An optional header message can be specified.
1116
1171
1117 - local_ns, global_ns: working namespaces. If given as None, the
1172 - local_ns, global_ns: working namespaces. If given as None, the
1118 IPython-initialized one is updated with __main__.__dict__, so that
1173 IPython-initialized one is updated with __main__.__dict__, so that
1119 program variables become visible but user-specific configuration
1174 program variables become visible but user-specific configuration
1120 remains possible.
1175 remains possible.
1121
1176
1122 - stack_depth: specifies how many levels in the stack to go to
1177 - stack_depth: specifies how many levels in the stack to go to
1123 looking for namespaces (when local_ns and global_ns are None). This
1178 looking for namespaces (when local_ns and global_ns are None). This
1124 allows an intermediate caller to make sure that this function gets
1179 allows an intermediate caller to make sure that this function gets
1125 the namespace from the intended level in the stack. By default (0)
1180 the namespace from the intended level in the stack. By default (0)
1126 it will get its locals and globals from the immediate caller.
1181 it will get its locals and globals from the immediate caller.
1127
1182
1128 Warning: it's possible to use this in a program which is being run by
1183 Warning: it's possible to use this in a program which is being run by
1129 IPython itself (via %run), but some funny things will happen (a few
1184 IPython itself (via %run), but some funny things will happen (a few
1130 globals get overwritten). In the future this will be cleaned up, as
1185 globals get overwritten). In the future this will be cleaned up, as
1131 there is no fundamental reason why it can't work perfectly."""
1186 there is no fundamental reason why it can't work perfectly."""
1132
1187
1133 # Get locals and globals from caller
1188 # Get locals and globals from caller
1134 if local_ns is None or global_ns is None:
1189 if local_ns is None or global_ns is None:
1135 call_frame = sys._getframe(stack_depth).f_back
1190 call_frame = sys._getframe(stack_depth).f_back
1136
1191
1137 if local_ns is None:
1192 if local_ns is None:
1138 local_ns = call_frame.f_locals
1193 local_ns = call_frame.f_locals
1139 if global_ns is None:
1194 if global_ns is None:
1140 global_ns = call_frame.f_globals
1195 global_ns = call_frame.f_globals
1141
1196
1142 # Update namespaces and fire up interpreter
1197 # Update namespaces and fire up interpreter
1143 self.user_ns = local_ns
1198 self.user_ns = local_ns
1144 self.user_global_ns = global_ns
1199 self.user_global_ns = global_ns
1145
1200
1146 # Patch for global embedding to make sure that things don't overwrite
1201 # Patch for global embedding to make sure that things don't overwrite
1147 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1202 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1148 # FIXME. Test this a bit more carefully (the if.. is new)
1203 # FIXME. Test this a bit more carefully (the if.. is new)
1149 if local_ns is None and global_ns is None:
1204 if local_ns is None and global_ns is None:
1150 self.user_global_ns.update(__main__.__dict__)
1205 self.user_global_ns.update(__main__.__dict__)
1151
1206
1152 # make sure the tab-completer has the correct frame information, so it
1207 # make sure the tab-completer has the correct frame information, so it
1153 # actually completes using the frame's locals/globals
1208 # actually completes using the frame's locals/globals
1154 self.set_completer_frame(call_frame)
1209 self.set_completer_frame(call_frame)
1155
1210
1156 self.interact(header)
1211 self.interact(header)
1157
1212
1158 def interact(self, banner=None):
1213 def interact(self, banner=None):
1159 """Closely emulate the interactive Python console.
1214 """Closely emulate the interactive Python console.
1160
1215
1161 The optional banner argument specify the banner to print
1216 The optional banner argument specify the banner to print
1162 before the first interaction; by default it prints a banner
1217 before the first interaction; by default it prints a banner
1163 similar to the one printed by the real Python interpreter,
1218 similar to the one printed by the real Python interpreter,
1164 followed by the current class name in parentheses (so as not
1219 followed by the current class name in parentheses (so as not
1165 to confuse this with the real interpreter -- since it's so
1220 to confuse this with the real interpreter -- since it's so
1166 close!).
1221 close!).
1167
1222
1168 """
1223 """
1169 cprt = 'Type "copyright", "credits" or "license" for more information.'
1224 cprt = 'Type "copyright", "credits" or "license" for more information.'
1170 if banner is None:
1225 if banner is None:
1171 self.write("Python %s on %s\n%s\n(%s)\n" %
1226 self.write("Python %s on %s\n%s\n(%s)\n" %
1172 (sys.version, sys.platform, cprt,
1227 (sys.version, sys.platform, cprt,
1173 self.__class__.__name__))
1228 self.__class__.__name__))
1174 else:
1229 else:
1175 self.write(banner)
1230 self.write(banner)
1176
1231
1177 more = 0
1232 more = 0
1178
1233
1179 # Mark activity in the builtins
1234 # Mark activity in the builtins
1180 __builtin__.__dict__['__IPYTHON__active'] += 1
1235 __builtin__.__dict__['__IPYTHON__active'] += 1
1181
1236
1182 # compiled regexps for autoindent management
1237 # compiled regexps for autoindent management
1183 ini_spaces_re = re.compile(r'^(\s+)')
1238 ini_spaces_re = re.compile(r'^(\s+)')
1184 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
1239 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
1185
1240
1186 # exit_now is set by a call to %Exit or %Quit
1241 # exit_now is set by a call to %Exit or %Quit
1187 while not self.exit_now:
1242 while not self.exit_now:
1188 try:
1243 try:
1189 if more:
1244 if more:
1190 prompt = self.outputcache.prompt2
1245 prompt = self.outputcache.prompt2
1191 if self.autoindent:
1246 if self.autoindent:
1192 self.readline_startup_hook(self.pre_readline)
1247 self.readline_startup_hook(self.pre_readline)
1193 else:
1248 else:
1194 prompt = self.outputcache.prompt1
1249 prompt = self.outputcache.prompt1
1195 try:
1250 try:
1196 line = self.raw_input(prompt,more)
1251 line = self.raw_input(prompt,more)
1197 if self.autoindent:
1252 if self.autoindent:
1198 self.readline_startup_hook(None)
1253 self.readline_startup_hook(None)
1199 except EOFError:
1254 except EOFError:
1200 if self.autoindent:
1255 if self.autoindent:
1201 self.readline_startup_hook(None)
1256 self.readline_startup_hook(None)
1202 self.write("\n")
1257 self.write("\n")
1203 self.exit()
1258 self.exit()
1204 except IPythonExit:
1259 except IPythonExit:
1205 self.exit()
1260 self.exit()
1206 else:
1261 else:
1207 more = self.push(line)
1262 more = self.push(line)
1208 # Auto-indent management
1263 # Auto-indent management
1209 if self.autoindent:
1264 if self.autoindent:
1210 if line:
1265 if line:
1211 ini_spaces = ini_spaces_re.match(line)
1266 ini_spaces = ini_spaces_re.match(line)
1212 if ini_spaces:
1267 if ini_spaces:
1213 nspaces = ini_spaces.end()
1268 nspaces = ini_spaces.end()
1214 else:
1269 else:
1215 nspaces = 0
1270 nspaces = 0
1216 self.indent_current_nsp = nspaces
1271 self.indent_current_nsp = nspaces
1217
1272
1218 if line[-1] == ':':
1273 if line[-1] == ':':
1219 self.indent_current_nsp += 4
1274 self.indent_current_nsp += 4
1220 elif dedent_re.match(line):
1275 elif dedent_re.match(line):
1221 self.indent_current_nsp -= 4
1276 self.indent_current_nsp -= 4
1222 else:
1277 else:
1223 self.indent_current_nsp = 0
1278 self.indent_current_nsp = 0
1279
1224 # indent_current is the actual string to be inserted
1280 # indent_current is the actual string to be inserted
1225 # by the readline hooks for indentation
1281 # by the readline hooks for indentation
1226 self.indent_current = ' '* self.indent_current_nsp
1282 self.indent_current = ' '* self.indent_current_nsp
1227
1283
1284 if (self.SyntaxTB.last_syntax_error and
1285 self.rc.autoedit_syntax):
1286 self.edit_syntax_error()
1287
1228 except KeyboardInterrupt:
1288 except KeyboardInterrupt:
1229 self.write("\nKeyboardInterrupt\n")
1289 self.write("\nKeyboardInterrupt\n")
1230 self.resetbuffer()
1290 self.resetbuffer()
1231 more = 0
1291 more = 0
1232 # keep cache in sync with the prompt counter:
1292 # keep cache in sync with the prompt counter:
1233 self.outputcache.prompt_count -= 1
1293 self.outputcache.prompt_count -= 1
1234
1294
1235 if self.autoindent:
1295 if self.autoindent:
1236 self.indent_current_nsp = 0
1296 self.indent_current_nsp = 0
1237 self.indent_current = ' '* self.indent_current_nsp
1297 self.indent_current = ' '* self.indent_current_nsp
1238
1298
1239 except bdb.BdbQuit:
1299 except bdb.BdbQuit:
1240 warn("The Python debugger has exited with a BdbQuit exception.\n"
1300 warn("The Python debugger has exited with a BdbQuit exception.\n"
1241 "Because of how pdb handles the stack, it is impossible\n"
1301 "Because of how pdb handles the stack, it is impossible\n"
1242 "for IPython to properly format this particular exception.\n"
1302 "for IPython to properly format this particular exception.\n"
1243 "IPython will resume normal operation.")
1303 "IPython will resume normal operation.")
1244
1304
1245 # We are off again...
1305 # We are off again...
1246 __builtin__.__dict__['__IPYTHON__active'] -= 1
1306 __builtin__.__dict__['__IPYTHON__active'] -= 1
1247
1307
1248 def excepthook(self, type, value, tb):
1308 def excepthook(self, type, value, tb):
1249 """One more defense for GUI apps that call sys.excepthook.
1309 """One more defense for GUI apps that call sys.excepthook.
1250
1310
1251 GUI frameworks like wxPython trap exceptions and call
1311 GUI frameworks like wxPython trap exceptions and call
1252 sys.excepthook themselves. I guess this is a feature that
1312 sys.excepthook themselves. I guess this is a feature that
1253 enables them to keep running after exceptions that would
1313 enables them to keep running after exceptions that would
1254 otherwise kill their mainloop. This is a bother for IPython
1314 otherwise kill their mainloop. This is a bother for IPython
1255 which excepts to catch all of the program exceptions with a try:
1315 which excepts to catch all of the program exceptions with a try:
1256 except: statement.
1316 except: statement.
1257
1317
1258 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1318 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1259 any app directly invokes sys.excepthook, it will look to the user like
1319 any app directly invokes sys.excepthook, it will look to the user like
1260 IPython crashed. In order to work around this, we can disable the
1320 IPython crashed. In order to work around this, we can disable the
1261 CrashHandler and replace it with this excepthook instead, which prints a
1321 CrashHandler and replace it with this excepthook instead, which prints a
1262 regular traceback using our InteractiveTB. In this fashion, apps which
1322 regular traceback using our InteractiveTB. In this fashion, apps which
1263 call sys.excepthook will generate a regular-looking exception from
1323 call sys.excepthook will generate a regular-looking exception from
1264 IPython, and the CrashHandler will only be triggered by real IPython
1324 IPython, and the CrashHandler will only be triggered by real IPython
1265 crashes.
1325 crashes.
1266
1326
1267 This hook should be used sparingly, only in places which are not likely
1327 This hook should be used sparingly, only in places which are not likely
1268 to be true IPython errors.
1328 to be true IPython errors.
1269 """
1329 """
1270
1330
1271 self.InteractiveTB(type, value, tb, tb_offset=0)
1331 self.InteractiveTB(type, value, tb, tb_offset=0)
1272 if self.InteractiveTB.call_pdb and self.has_readline:
1332 if self.InteractiveTB.call_pdb and self.has_readline:
1273 self.readline.set_completer(self.Completer.complete)
1333 self.readline.set_completer(self.Completer.complete)
1274
1334
1275 def call_alias(self,alias,rest=''):
1335 def call_alias(self,alias,rest=''):
1276 """Call an alias given its name and the rest of the line.
1336 """Call an alias given its name and the rest of the line.
1277
1337
1278 This function MUST be given a proper alias, because it doesn't make
1338 This function MUST be given a proper alias, because it doesn't make
1279 any checks when looking up into the alias table. The caller is
1339 any checks when looking up into the alias table. The caller is
1280 responsible for invoking it only with a valid alias."""
1340 responsible for invoking it only with a valid alias."""
1281
1341
1282 #print 'ALIAS: <%s>+<%s>' % (alias,rest) # dbg
1342 #print 'ALIAS: <%s>+<%s>' % (alias,rest) # dbg
1283 nargs,cmd = self.alias_table[alias]
1343 nargs,cmd = self.alias_table[alias]
1284 # Expand the %l special to be the user's input line
1344 # Expand the %l special to be the user's input line
1285 if cmd.find('%l') >= 0:
1345 if cmd.find('%l') >= 0:
1286 cmd = cmd.replace('%l',rest)
1346 cmd = cmd.replace('%l',rest)
1287 rest = ''
1347 rest = ''
1288 if nargs==0:
1348 if nargs==0:
1289 # Simple, argument-less aliases
1349 # Simple, argument-less aliases
1290 cmd = '%s %s' % (cmd,rest)
1350 cmd = '%s %s' % (cmd,rest)
1291 else:
1351 else:
1292 # Handle aliases with positional arguments
1352 # Handle aliases with positional arguments
1293 args = rest.split(None,nargs)
1353 args = rest.split(None,nargs)
1294 if len(args)< nargs:
1354 if len(args)< nargs:
1295 error('Alias <%s> requires %s arguments, %s given.' %
1355 error('Alias <%s> requires %s arguments, %s given.' %
1296 (alias,nargs,len(args)))
1356 (alias,nargs,len(args)))
1297 return
1357 return
1298 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
1358 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
1299 # Now call the macro, evaluating in the user's namespace
1359 # Now call the macro, evaluating in the user's namespace
1300 try:
1360 try:
1301 self.system(cmd)
1361 self.system(cmd)
1302 except:
1362 except:
1303 self.showtraceback()
1363 self.showtraceback()
1304
1364
1305 def runlines(self,lines):
1365 def runlines(self,lines):
1306 """Run a string of one or more lines of source.
1366 """Run a string of one or more lines of source.
1307
1367
1308 This method is capable of running a string containing multiple source
1368 This method is capable of running a string containing multiple source
1309 lines, as if they had been entered at the IPython prompt. Since it
1369 lines, as if they had been entered at the IPython prompt. Since it
1310 exposes IPython's processing machinery, the given strings can contain
1370 exposes IPython's processing machinery, the given strings can contain
1311 magic calls (%magic), special shell access (!cmd), etc."""
1371 magic calls (%magic), special shell access (!cmd), etc."""
1312
1372
1313 # We must start with a clean buffer, in case this is run from an
1373 # We must start with a clean buffer, in case this is run from an
1314 # interactive IPython session (via a magic, for example).
1374 # interactive IPython session (via a magic, for example).
1315 self.resetbuffer()
1375 self.resetbuffer()
1316 lines = lines.split('\n')
1376 lines = lines.split('\n')
1317 more = 0
1377 more = 0
1318 for line in lines:
1378 for line in lines:
1319 # skip blank lines so we don't mess up the prompt counter, but do
1379 # skip blank lines so we don't mess up the prompt counter, but do
1320 # NOT skip even a blank line if we are in a code block (more is
1380 # NOT skip even a blank line if we are in a code block (more is
1321 # true)
1381 # true)
1322 if line or more:
1382 if line or more:
1323 more = self.push((self.prefilter(line,more)))
1383 more = self.push((self.prefilter(line,more)))
1324 # IPython's runsource returns None if there was an error
1384 # IPython's runsource returns None if there was an error
1325 # compiling the code. This allows us to stop processing right
1385 # compiling the code. This allows us to stop processing right
1326 # away, so the user gets the error message at the right place.
1386 # away, so the user gets the error message at the right place.
1327 if more is None:
1387 if more is None:
1328 break
1388 break
1329 # final newline in case the input didn't have it, so that the code
1389 # final newline in case the input didn't have it, so that the code
1330 # actually does get executed
1390 # actually does get executed
1331 if more:
1391 if more:
1332 self.push('\n')
1392 self.push('\n')
1333
1393
1334 def runsource(self, source, filename='<input>', symbol='single'):
1394 def runsource(self, source, filename='<input>', symbol='single'):
1335 """Compile and run some source in the interpreter.
1395 """Compile and run some source in the interpreter.
1336
1396
1337 Arguments are as for compile_command().
1397 Arguments are as for compile_command().
1338
1398
1339 One several things can happen:
1399 One several things can happen:
1340
1400
1341 1) The input is incorrect; compile_command() raised an
1401 1) The input is incorrect; compile_command() raised an
1342 exception (SyntaxError or OverflowError). A syntax traceback
1402 exception (SyntaxError or OverflowError). A syntax traceback
1343 will be printed by calling the showsyntaxerror() method.
1403 will be printed by calling the showsyntaxerror() method.
1344
1404
1345 2) The input is incomplete, and more input is required;
1405 2) The input is incomplete, and more input is required;
1346 compile_command() returned None. Nothing happens.
1406 compile_command() returned None. Nothing happens.
1347
1407
1348 3) The input is complete; compile_command() returned a code
1408 3) The input is complete; compile_command() returned a code
1349 object. The code is executed by calling self.runcode() (which
1409 object. The code is executed by calling self.runcode() (which
1350 also handles run-time exceptions, except for SystemExit).
1410 also handles run-time exceptions, except for SystemExit).
1351
1411
1352 The return value is:
1412 The return value is:
1353
1413
1354 - True in case 2
1414 - True in case 2
1355
1415
1356 - False in the other cases, unless an exception is raised, where
1416 - False in the other cases, unless an exception is raised, where
1357 None is returned instead. This can be used by external callers to
1417 None is returned instead. This can be used by external callers to
1358 know whether to continue feeding input or not.
1418 know whether to continue feeding input or not.
1359
1419
1360 The return value can be used to decide whether to use sys.ps1 or
1420 The return value can be used to decide whether to use sys.ps1 or
1361 sys.ps2 to prompt the next line."""
1421 sys.ps2 to prompt the next line."""
1362
1422
1363 try:
1423 try:
1364 code = self.compile(source,filename,symbol)
1424 code = self.compile(source,filename,symbol)
1365 except (OverflowError, SyntaxError, ValueError):
1425 except (OverflowError, SyntaxError, ValueError):
1366 # Case 1
1426 # Case 1
1367 self.showsyntaxerror(filename)
1427 self.showsyntaxerror(filename)
1368 return None
1428 return None
1369
1429
1370 if code is None:
1430 if code is None:
1371 # Case 2
1431 # Case 2
1372 return True
1432 return True
1373
1433
1374 # Case 3
1434 # Case 3
1375 # We store the code object so that threaded shells and
1435 # We store the code object so that threaded shells and
1376 # custom exception handlers can access all this info if needed.
1436 # custom exception handlers can access all this info if needed.
1377 # The source corresponding to this can be obtained from the
1437 # The source corresponding to this can be obtained from the
1378 # buffer attribute as '\n'.join(self.buffer).
1438 # buffer attribute as '\n'.join(self.buffer).
1379 self.code_to_run = code
1439 self.code_to_run = code
1380 # now actually execute the code object
1440 # now actually execute the code object
1381 if self.runcode(code) == 0:
1441 if self.runcode(code) == 0:
1382 return False
1442 return False
1383 else:
1443 else:
1384 return None
1444 return None
1385
1445
1386 def runcode(self,code_obj):
1446 def runcode(self,code_obj):
1387 """Execute a code object.
1447 """Execute a code object.
1388
1448
1389 When an exception occurs, self.showtraceback() is called to display a
1449 When an exception occurs, self.showtraceback() is called to display a
1390 traceback.
1450 traceback.
1391
1451
1392 Return value: a flag indicating whether the code to be run completed
1452 Return value: a flag indicating whether the code to be run completed
1393 successfully:
1453 successfully:
1394
1454
1395 - 0: successful execution.
1455 - 0: successful execution.
1396 - 1: an error occurred.
1456 - 1: an error occurred.
1397 """
1457 """
1398
1458
1399 # Set our own excepthook in case the user code tries to call it
1459 # Set our own excepthook in case the user code tries to call it
1400 # directly, so that the IPython crash handler doesn't get triggered
1460 # directly, so that the IPython crash handler doesn't get triggered
1401 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1461 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1402 outflag = 1 # happens in more places, so it's easier as default
1462 outflag = 1 # happens in more places, so it's easier as default
1403 try:
1463 try:
1404 try:
1464 try:
1405 # Embedded instances require separate global/local namespaces
1465 # Embedded instances require separate global/local namespaces
1406 # so they can see both the surrounding (local) namespace and
1466 # so they can see both the surrounding (local) namespace and
1407 # the module-level globals when called inside another function.
1467 # the module-level globals when called inside another function.
1408 if self.embedded:
1468 if self.embedded:
1409 exec code_obj in self.user_global_ns, self.user_ns
1469 exec code_obj in self.user_global_ns, self.user_ns
1410 # Normal (non-embedded) instances should only have a single
1470 # Normal (non-embedded) instances should only have a single
1411 # namespace for user code execution, otherwise functions won't
1471 # namespace for user code execution, otherwise functions won't
1412 # see interactive top-level globals.
1472 # see interactive top-level globals.
1413 else:
1473 else:
1414 exec code_obj in self.user_ns
1474 exec code_obj in self.user_ns
1415 finally:
1475 finally:
1416 # Reset our crash handler in place
1476 # Reset our crash handler in place
1417 sys.excepthook = old_excepthook
1477 sys.excepthook = old_excepthook
1418 except SystemExit:
1478 except SystemExit:
1419 self.resetbuffer()
1479 self.resetbuffer()
1420 self.showtraceback()
1480 self.showtraceback()
1421 warn("Type exit or quit to exit IPython "
1481 warn("Type exit or quit to exit IPython "
1422 "(%Exit or %Quit do so unconditionally).",level=1)
1482 "(%Exit or %Quit do so unconditionally).",level=1)
1423 except self.custom_exceptions:
1483 except self.custom_exceptions:
1424 etype,value,tb = sys.exc_info()
1484 etype,value,tb = sys.exc_info()
1425 self.CustomTB(etype,value,tb)
1485 self.CustomTB(etype,value,tb)
1426 except:
1486 except:
1427 self.showtraceback()
1487 self.showtraceback()
1428 else:
1488 else:
1429 outflag = 0
1489 outflag = 0
1430 if softspace(sys.stdout, 0):
1490 if softspace(sys.stdout, 0):
1431 print
1491 print
1432 # Flush out code object which has been run (and source)
1492 # Flush out code object which has been run (and source)
1433 self.code_to_run = None
1493 self.code_to_run = None
1434 return outflag
1494 return outflag
1435
1495
1436 def push(self, line):
1496 def push(self, line):
1437 """Push a line to the interpreter.
1497 """Push a line to the interpreter.
1438
1498
1439 The line should not have a trailing newline; it may have
1499 The line should not have a trailing newline; it may have
1440 internal newlines. The line is appended to a buffer and the
1500 internal newlines. The line is appended to a buffer and the
1441 interpreter's runsource() method is called with the
1501 interpreter's runsource() method is called with the
1442 concatenated contents of the buffer as source. If this
1502 concatenated contents of the buffer as source. If this
1443 indicates that the command was executed or invalid, the buffer
1503 indicates that the command was executed or invalid, the buffer
1444 is reset; otherwise, the command is incomplete, and the buffer
1504 is reset; otherwise, the command is incomplete, and the buffer
1445 is left as it was after the line was appended. The return
1505 is left as it was after the line was appended. The return
1446 value is 1 if more input is required, 0 if the line was dealt
1506 value is 1 if more input is required, 0 if the line was dealt
1447 with in some way (this is the same as runsource()).
1507 with in some way (this is the same as runsource()).
1448
1508
1449 """
1509 """
1450 self.buffer.append(line)
1510 self.buffer.append(line)
1451 more = self.runsource('\n'.join(self.buffer), self.filename)
1511 more = self.runsource('\n'.join(self.buffer), self.filename)
1452 if not more:
1512 if not more:
1453 self.resetbuffer()
1513 self.resetbuffer()
1454 return more
1514 return more
1455
1515
1456 def resetbuffer(self):
1516 def resetbuffer(self):
1457 """Reset the input buffer."""
1517 """Reset the input buffer."""
1458 self.buffer[:] = []
1518 self.buffer[:] = []
1459
1519
1460 def raw_input(self,prompt='',continue_prompt=False):
1520 def raw_input(self,prompt='',continue_prompt=False):
1461 """Write a prompt and read a line.
1521 """Write a prompt and read a line.
1462
1522
1463 The returned line does not include the trailing newline.
1523 The returned line does not include the trailing newline.
1464 When the user enters the EOF key sequence, EOFError is raised.
1524 When the user enters the EOF key sequence, EOFError is raised.
1465
1525
1466 Optional inputs:
1526 Optional inputs:
1467
1527
1468 - prompt(''): a string to be printed to prompt the user.
1528 - prompt(''): a string to be printed to prompt the user.
1469
1529
1470 - continue_prompt(False): whether this line is the first one or a
1530 - continue_prompt(False): whether this line is the first one or a
1471 continuation in a sequence of inputs.
1531 continuation in a sequence of inputs.
1472 """
1532 """
1473
1533
1474 line = raw_input_original(prompt)
1534 line = raw_input_original(prompt)
1475 # Try to be reasonably smart about not re-indenting pasted input more
1535 # Try to be reasonably smart about not re-indenting pasted input more
1476 # than necessary. We do this by trimming out the auto-indent initial
1536 # than necessary. We do this by trimming out the auto-indent initial
1477 # spaces, if the user's actual input started itself with whitespace.
1537 # spaces, if the user's actual input started itself with whitespace.
1478 if self.autoindent:
1538 if self.autoindent:
1479 line2 = line[self.indent_current_nsp:]
1539 line2 = line[self.indent_current_nsp:]
1480 if line2[0:1] in (' ','\t'):
1540 if line2[0:1] in (' ','\t'):
1481 line = line2
1541 line = line2
1482 return self.prefilter(line,continue_prompt)
1542 return self.prefilter(line,continue_prompt)
1483
1543
1484 def split_user_input(self,line):
1544 def split_user_input(self,line):
1485 """Split user input into pre-char, function part and rest."""
1545 """Split user input into pre-char, function part and rest."""
1486
1546
1487 lsplit = self.line_split.match(line)
1547 lsplit = self.line_split.match(line)
1488 if lsplit is None: # no regexp match returns None
1548 if lsplit is None: # no regexp match returns None
1489 try:
1549 try:
1490 iFun,theRest = line.split(None,1)
1550 iFun,theRest = line.split(None,1)
1491 except ValueError:
1551 except ValueError:
1492 iFun,theRest = line,''
1552 iFun,theRest = line,''
1493 pre = re.match('^(\s*)(.*)',line).groups()[0]
1553 pre = re.match('^(\s*)(.*)',line).groups()[0]
1494 else:
1554 else:
1495 pre,iFun,theRest = lsplit.groups()
1555 pre,iFun,theRest = lsplit.groups()
1496
1556
1497 #print 'line:<%s>' % line # dbg
1557 #print 'line:<%s>' % line # dbg
1498 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun.strip(),theRest) # dbg
1558 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun.strip(),theRest) # dbg
1499 return pre,iFun.strip(),theRest
1559 return pre,iFun.strip(),theRest
1500
1560
1501 def _prefilter(self, line, continue_prompt):
1561 def _prefilter(self, line, continue_prompt):
1502 """Calls different preprocessors, depending on the form of line."""
1562 """Calls different preprocessors, depending on the form of line."""
1503
1563
1504 # All handlers *must* return a value, even if it's blank ('').
1564 # All handlers *must* return a value, even if it's blank ('').
1505
1565
1506 # Lines are NOT logged here. Handlers should process the line as
1566 # Lines are NOT logged here. Handlers should process the line as
1507 # needed, update the cache AND log it (so that the input cache array
1567 # needed, update the cache AND log it (so that the input cache array
1508 # stays synced).
1568 # stays synced).
1509
1569
1510 # This function is _very_ delicate, and since it's also the one which
1570 # This function is _very_ delicate, and since it's also the one which
1511 # determines IPython's response to user input, it must be as efficient
1571 # determines IPython's response to user input, it must be as efficient
1512 # as possible. For this reason it has _many_ returns in it, trying
1572 # as possible. For this reason it has _many_ returns in it, trying
1513 # always to exit as quickly as it can figure out what it needs to do.
1573 # always to exit as quickly as it can figure out what it needs to do.
1514
1574
1515 # This function is the main responsible for maintaining IPython's
1575 # This function is the main responsible for maintaining IPython's
1516 # behavior respectful of Python's semantics. So be _very_ careful if
1576 # behavior respectful of Python's semantics. So be _very_ careful if
1517 # making changes to anything here.
1577 # making changes to anything here.
1518
1578
1519 #.....................................................................
1579 #.....................................................................
1520 # Code begins
1580 # Code begins
1521
1581
1522 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
1582 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
1523
1583
1524 # save the line away in case we crash, so the post-mortem handler can
1584 # save the line away in case we crash, so the post-mortem handler can
1525 # record it
1585 # record it
1526 self._last_input_line = line
1586 self._last_input_line = line
1527
1587
1528 #print '***line: <%s>' % line # dbg
1588 #print '***line: <%s>' % line # dbg
1529
1589
1530 # the input history needs to track even empty lines
1590 # the input history needs to track even empty lines
1531 if not line.strip():
1591 if not line.strip():
1532 if not continue_prompt:
1592 if not continue_prompt:
1533 self.outputcache.prompt_count -= 1
1593 self.outputcache.prompt_count -= 1
1534 return self.handle_normal(line,continue_prompt)
1594 return self.handle_normal(line,continue_prompt)
1535 #return self.handle_normal('',continue_prompt)
1595 #return self.handle_normal('',continue_prompt)
1536
1596
1537 # print '***cont',continue_prompt # dbg
1597 # print '***cont',continue_prompt # dbg
1538 # special handlers are only allowed for single line statements
1598 # special handlers are only allowed for single line statements
1539 if continue_prompt and not self.rc.multi_line_specials:
1599 if continue_prompt and not self.rc.multi_line_specials:
1540 return self.handle_normal(line,continue_prompt)
1600 return self.handle_normal(line,continue_prompt)
1541
1601
1542 # For the rest, we need the structure of the input
1602 # For the rest, we need the structure of the input
1543 pre,iFun,theRest = self.split_user_input(line)
1603 pre,iFun,theRest = self.split_user_input(line)
1544 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1604 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1545
1605
1546 # First check for explicit escapes in the last/first character
1606 # First check for explicit escapes in the last/first character
1547 handler = None
1607 handler = None
1548 if line[-1] == self.ESC_HELP:
1608 if line[-1] == self.ESC_HELP:
1549 handler = self.esc_handlers.get(line[-1]) # the ? can be at the end
1609 handler = self.esc_handlers.get(line[-1]) # the ? can be at the end
1550 if handler is None:
1610 if handler is None:
1551 # look at the first character of iFun, NOT of line, so we skip
1611 # look at the first character of iFun, NOT of line, so we skip
1552 # leading whitespace in multiline input
1612 # leading whitespace in multiline input
1553 handler = self.esc_handlers.get(iFun[0:1])
1613 handler = self.esc_handlers.get(iFun[0:1])
1554 if handler is not None:
1614 if handler is not None:
1555 return handler(line,continue_prompt,pre,iFun,theRest)
1615 return handler(line,continue_prompt,pre,iFun,theRest)
1556 # Emacs ipython-mode tags certain input lines
1616 # Emacs ipython-mode tags certain input lines
1557 if line.endswith('# PYTHON-MODE'):
1617 if line.endswith('# PYTHON-MODE'):
1558 return self.handle_emacs(line,continue_prompt)
1618 return self.handle_emacs(line,continue_prompt)
1559
1619
1560 # Next, check if we can automatically execute this thing
1620 # Next, check if we can automatically execute this thing
1561
1621
1562 # Allow ! in multi-line statements if multi_line_specials is on:
1622 # Allow ! in multi-line statements if multi_line_specials is on:
1563 if continue_prompt and self.rc.multi_line_specials and \
1623 if continue_prompt and self.rc.multi_line_specials and \
1564 iFun.startswith(self.ESC_SHELL):
1624 iFun.startswith(self.ESC_SHELL):
1565 return self.handle_shell_escape(line,continue_prompt,
1625 return self.handle_shell_escape(line,continue_prompt,
1566 pre=pre,iFun=iFun,
1626 pre=pre,iFun=iFun,
1567 theRest=theRest)
1627 theRest=theRest)
1568
1628
1569 # Let's try to find if the input line is a magic fn
1629 # Let's try to find if the input line is a magic fn
1570 oinfo = None
1630 oinfo = None
1571 if hasattr(self,'magic_'+iFun):
1631 if hasattr(self,'magic_'+iFun):
1572 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1632 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1573 if oinfo['ismagic']:
1633 if oinfo['ismagic']:
1574 # Be careful not to call magics when a variable assignment is
1634 # Be careful not to call magics when a variable assignment is
1575 # being made (ls='hi', for example)
1635 # being made (ls='hi', for example)
1576 if self.rc.automagic and \
1636 if self.rc.automagic and \
1577 (len(theRest)==0 or theRest[0] not in '!=()<>,') and \
1637 (len(theRest)==0 or theRest[0] not in '!=()<>,') and \
1578 (self.rc.multi_line_specials or not continue_prompt):
1638 (self.rc.multi_line_specials or not continue_prompt):
1579 return self.handle_magic(line,continue_prompt,
1639 return self.handle_magic(line,continue_prompt,
1580 pre,iFun,theRest)
1640 pre,iFun,theRest)
1581 else:
1641 else:
1582 return self.handle_normal(line,continue_prompt)
1642 return self.handle_normal(line,continue_prompt)
1583
1643
1584 # If the rest of the line begins with an (in)equality, assginment or
1644 # If the rest of the line begins with an (in)equality, assginment or
1585 # function call, we should not call _ofind but simply execute it.
1645 # function call, we should not call _ofind but simply execute it.
1586 # This avoids spurious geattr() accesses on objects upon assignment.
1646 # This avoids spurious geattr() accesses on objects upon assignment.
1587 #
1647 #
1588 # It also allows users to assign to either alias or magic names true
1648 # It also allows users to assign to either alias or magic names true
1589 # python variables (the magic/alias systems always take second seat to
1649 # python variables (the magic/alias systems always take second seat to
1590 # true python code).
1650 # true python code).
1591 if theRest and theRest[0] in '!=()':
1651 if theRest and theRest[0] in '!=()':
1592 return self.handle_normal(line,continue_prompt)
1652 return self.handle_normal(line,continue_prompt)
1593
1653
1594 if oinfo is None:
1654 if oinfo is None:
1595 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1655 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1596
1656
1597 if not oinfo['found']:
1657 if not oinfo['found']:
1598 if iFun in ('quit','exit'):
1658 if iFun in ('quit','exit'):
1599 raise IPythonExit
1659 raise IPythonExit
1600 return self.handle_normal(line,continue_prompt)
1660 return self.handle_normal(line,continue_prompt)
1601 else:
1661 else:
1602 #print 'iFun <%s> rest <%s>' % (iFun,theRest) # dbg
1662 #print 'iFun <%s> rest <%s>' % (iFun,theRest) # dbg
1603 if oinfo['isalias']:
1663 if oinfo['isalias']:
1604 return self.handle_alias(line,continue_prompt,
1664 return self.handle_alias(line,continue_prompt,
1605 pre,iFun,theRest)
1665 pre,iFun,theRest)
1606
1666
1607 if self.rc.autocall and \
1667 if self.rc.autocall and \
1608 not self.re_exclude_auto.match(theRest) and \
1668 not self.re_exclude_auto.match(theRest) and \
1609 self.re_fun_name.match(iFun) and \
1669 self.re_fun_name.match(iFun) and \
1610 callable(oinfo['obj']) :
1670 callable(oinfo['obj']) :
1611 #print 'going auto' # dbg
1671 #print 'going auto' # dbg
1612 return self.handle_auto(line,continue_prompt,pre,iFun,theRest)
1672 return self.handle_auto(line,continue_prompt,pre,iFun,theRest)
1613 else:
1673 else:
1614 #print 'was callable?', callable(oinfo['obj']) # dbg
1674 #print 'was callable?', callable(oinfo['obj']) # dbg
1615 return self.handle_normal(line,continue_prompt)
1675 return self.handle_normal(line,continue_prompt)
1616
1676
1617 # If we get here, we have a normal Python line. Log and return.
1677 # If we get here, we have a normal Python line. Log and return.
1618 return self.handle_normal(line,continue_prompt)
1678 return self.handle_normal(line,continue_prompt)
1619
1679
1620 def _prefilter_dumb(self, line, continue_prompt):
1680 def _prefilter_dumb(self, line, continue_prompt):
1621 """simple prefilter function, for debugging"""
1681 """simple prefilter function, for debugging"""
1622 return self.handle_normal(line,continue_prompt)
1682 return self.handle_normal(line,continue_prompt)
1623
1683
1624 # Set the default prefilter() function (this can be user-overridden)
1684 # Set the default prefilter() function (this can be user-overridden)
1625 prefilter = _prefilter
1685 prefilter = _prefilter
1626
1686
1627 def handle_normal(self,line,continue_prompt=None,
1687 def handle_normal(self,line,continue_prompt=None,
1628 pre=None,iFun=None,theRest=None):
1688 pre=None,iFun=None,theRest=None):
1629 """Handle normal input lines. Use as a template for handlers."""
1689 """Handle normal input lines. Use as a template for handlers."""
1630
1690
1631 # With autoindent on, we need some way to exit the input loop, and I
1691 # With autoindent on, we need some way to exit the input loop, and I
1632 # don't want to force the user to have to backspace all the way to
1692 # don't want to force the user to have to backspace all the way to
1633 # clear the line. The rule will be in this case, that either two
1693 # clear the line. The rule will be in this case, that either two
1634 # lines of pure whitespace in a row, or a line of pure whitespace but
1694 # lines of pure whitespace in a row, or a line of pure whitespace but
1635 # of a size different to the indent level, will exit the input loop.
1695 # of a size different to the indent level, will exit the input loop.
1636 if (continue_prompt and self.autoindent and isspace(line) and
1696 if (continue_prompt and self.autoindent and isspace(line) and
1637 (line != self.indent_current or isspace(self.buffer[-1]))):
1697 (line != self.indent_current or isspace(self.buffer[-1]))):
1638 line = ''
1698 line = ''
1639
1699
1640 self.log(line,continue_prompt)
1700 self.log(line,continue_prompt)
1641 self.update_cache(line)
1701 self.update_cache(line)
1642 return line
1702 return line
1643
1703
1644 def handle_alias(self,line,continue_prompt=None,
1704 def handle_alias(self,line,continue_prompt=None,
1645 pre=None,iFun=None,theRest=None):
1705 pre=None,iFun=None,theRest=None):
1646 """Handle alias input lines. """
1706 """Handle alias input lines. """
1647
1707
1648 theRest = esc_quotes(theRest)
1708 theRest = esc_quotes(theRest)
1649 line_out = "%s%s.call_alias('%s','%s')" % (pre,self.name,iFun,theRest)
1709 line_out = "%s%s.call_alias('%s','%s')" % (pre,self.name,iFun,theRest)
1650 self.log(line_out,continue_prompt)
1710 self.log(line_out,continue_prompt)
1651 self.update_cache(line_out)
1711 self.update_cache(line_out)
1652 return line_out
1712 return line_out
1653
1713
1654 def handle_shell_escape(self, line, continue_prompt=None,
1714 def handle_shell_escape(self, line, continue_prompt=None,
1655 pre=None,iFun=None,theRest=None):
1715 pre=None,iFun=None,theRest=None):
1656 """Execute the line in a shell, empty return value"""
1716 """Execute the line in a shell, empty return value"""
1657
1717
1658 #print 'line in :', `line` # dbg
1718 #print 'line in :', `line` # dbg
1659 # Example of a special handler. Others follow a similar pattern.
1719 # Example of a special handler. Others follow a similar pattern.
1660 if continue_prompt: # multi-line statements
1720 if continue_prompt: # multi-line statements
1661 if iFun.startswith('!!'):
1721 if iFun.startswith('!!'):
1662 print 'SyntaxError: !! is not allowed in multiline statements'
1722 print 'SyntaxError: !! is not allowed in multiline statements'
1663 return pre
1723 return pre
1664 else:
1724 else:
1665 cmd = ("%s %s" % (iFun[1:],theRest)).replace('"','\\"')
1725 cmd = ("%s %s" % (iFun[1:],theRest)).replace('"','\\"')
1666 line_out = '%s%s.system("%s")' % (pre,self.name,cmd)
1726 line_out = '%s%s.system("%s")' % (pre,self.name,cmd)
1667 #line_out = ('%s%s.system(' % (pre,self.name)) + repr(cmd) + ')'
1727 #line_out = ('%s%s.system(' % (pre,self.name)) + repr(cmd) + ')'
1668 else: # single-line input
1728 else: # single-line input
1669 if line.startswith('!!'):
1729 if line.startswith('!!'):
1670 # rewrite iFun/theRest to properly hold the call to %sx and
1730 # rewrite iFun/theRest to properly hold the call to %sx and
1671 # the actual command to be executed, so handle_magic can work
1731 # the actual command to be executed, so handle_magic can work
1672 # correctly
1732 # correctly
1673 theRest = '%s %s' % (iFun[2:],theRest)
1733 theRest = '%s %s' % (iFun[2:],theRest)
1674 iFun = 'sx'
1734 iFun = 'sx'
1675 return self.handle_magic('%ssx %s' % (self.ESC_MAGIC,line[2:]),
1735 return self.handle_magic('%ssx %s' % (self.ESC_MAGIC,line[2:]),
1676 continue_prompt,pre,iFun,theRest)
1736 continue_prompt,pre,iFun,theRest)
1677 else:
1737 else:
1678 cmd = esc_quotes(line[1:])
1738 cmd = esc_quotes(line[1:])
1679 line_out = '%s.system("%s")' % (self.name,cmd)
1739 line_out = '%s.system("%s")' % (self.name,cmd)
1680 #line_out = ('%s.system(' % self.name) + repr(cmd)+ ')'
1740 #line_out = ('%s.system(' % self.name) + repr(cmd)+ ')'
1681 # update cache/log and return
1741 # update cache/log and return
1682 self.log(line_out,continue_prompt)
1742 self.log(line_out,continue_prompt)
1683 self.update_cache(line_out) # readline cache gets normal line
1743 self.update_cache(line_out) # readline cache gets normal line
1684 #print 'line out r:', `line_out` # dbg
1744 #print 'line out r:', `line_out` # dbg
1685 #print 'line out s:', line_out # dbg
1745 #print 'line out s:', line_out # dbg
1686 return line_out
1746 return line_out
1687
1747
1688 def handle_magic(self, line, continue_prompt=None,
1748 def handle_magic(self, line, continue_prompt=None,
1689 pre=None,iFun=None,theRest=None):
1749 pre=None,iFun=None,theRest=None):
1690 """Execute magic functions.
1750 """Execute magic functions.
1691
1751
1692 Also log them with a prepended # so the log is clean Python."""
1752 Also log them with a prepended # so the log is clean Python."""
1693
1753
1694 cmd = '%sipmagic("%s")' % (pre,esc_quotes('%s %s' % (iFun,theRest)))
1754 cmd = '%sipmagic("%s")' % (pre,esc_quotes('%s %s' % (iFun,theRest)))
1695 self.log(cmd,continue_prompt)
1755 self.log(cmd,continue_prompt)
1696 self.update_cache(line)
1756 self.update_cache(line)
1697 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
1757 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
1698 return cmd
1758 return cmd
1699
1759
1700 def handle_auto(self, line, continue_prompt=None,
1760 def handle_auto(self, line, continue_prompt=None,
1701 pre=None,iFun=None,theRest=None):
1761 pre=None,iFun=None,theRest=None):
1702 """Hande lines which can be auto-executed, quoting if requested."""
1762 """Hande lines which can be auto-executed, quoting if requested."""
1703
1763
1704 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1764 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1705
1765
1706 # This should only be active for single-line input!
1766 # This should only be active for single-line input!
1707 if continue_prompt:
1767 if continue_prompt:
1708 return line
1768 return line
1709
1769
1710 if pre == self.ESC_QUOTE:
1770 if pre == self.ESC_QUOTE:
1711 # Auto-quote splitting on whitespace
1771 # Auto-quote splitting on whitespace
1712 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
1772 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
1713 elif pre == self.ESC_QUOTE2:
1773 elif pre == self.ESC_QUOTE2:
1714 # Auto-quote whole string
1774 # Auto-quote whole string
1715 newcmd = '%s("%s")' % (iFun,theRest)
1775 newcmd = '%s("%s")' % (iFun,theRest)
1716 else:
1776 else:
1717 # Auto-paren
1777 # Auto-paren
1718 if theRest[0:1] in ('=','['):
1778 if theRest[0:1] in ('=','['):
1719 # Don't autocall in these cases. They can be either
1779 # Don't autocall in these cases. They can be either
1720 # rebindings of an existing callable's name, or item access
1780 # rebindings of an existing callable's name, or item access
1721 # for an object which is BOTH callable and implements
1781 # for an object which is BOTH callable and implements
1722 # __getitem__.
1782 # __getitem__.
1723 return '%s %s' % (iFun,theRest)
1783 return '%s %s' % (iFun,theRest)
1724 if theRest.endswith(';'):
1784 if theRest.endswith(';'):
1725 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
1785 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
1726 else:
1786 else:
1727 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
1787 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
1728
1788
1729 print >>Term.cout, self.outputcache.prompt1.auto_rewrite() + newcmd
1789 print >>Term.cout, self.outputcache.prompt1.auto_rewrite() + newcmd
1730 # log what is now valid Python, not the actual user input (without the
1790 # log what is now valid Python, not the actual user input (without the
1731 # final newline)
1791 # final newline)
1732 self.log(newcmd,continue_prompt)
1792 self.log(newcmd,continue_prompt)
1733 return newcmd
1793 return newcmd
1734
1794
1735 def handle_help(self, line, continue_prompt=None,
1795 def handle_help(self, line, continue_prompt=None,
1736 pre=None,iFun=None,theRest=None):
1796 pre=None,iFun=None,theRest=None):
1737 """Try to get some help for the object.
1797 """Try to get some help for the object.
1738
1798
1739 obj? or ?obj -> basic information.
1799 obj? or ?obj -> basic information.
1740 obj?? or ??obj -> more details.
1800 obj?? or ??obj -> more details.
1741 """
1801 """
1742
1802
1743 # We need to make sure that we don't process lines which would be
1803 # We need to make sure that we don't process lines which would be
1744 # otherwise valid python, such as "x=1 # what?"
1804 # otherwise valid python, such as "x=1 # what?"
1745 try:
1805 try:
1746 codeop.compile_command(line)
1806 codeop.compile_command(line)
1747 except SyntaxError:
1807 except SyntaxError:
1748 # We should only handle as help stuff which is NOT valid syntax
1808 # We should only handle as help stuff which is NOT valid syntax
1749 if line[0]==self.ESC_HELP:
1809 if line[0]==self.ESC_HELP:
1750 line = line[1:]
1810 line = line[1:]
1751 elif line[-1]==self.ESC_HELP:
1811 elif line[-1]==self.ESC_HELP:
1752 line = line[:-1]
1812 line = line[:-1]
1753 self.log('#?'+line)
1813 self.log('#?'+line)
1754 self.update_cache(line)
1814 self.update_cache(line)
1755 if line:
1815 if line:
1756 self.magic_pinfo(line)
1816 self.magic_pinfo(line)
1757 else:
1817 else:
1758 page(self.usage,screen_lines=self.rc.screen_length)
1818 page(self.usage,screen_lines=self.rc.screen_length)
1759 return '' # Empty string is needed here!
1819 return '' # Empty string is needed here!
1760 except:
1820 except:
1761 # Pass any other exceptions through to the normal handler
1821 # Pass any other exceptions through to the normal handler
1762 return self.handle_normal(line,continue_prompt)
1822 return self.handle_normal(line,continue_prompt)
1763 else:
1823 else:
1764 # If the code compiles ok, we should handle it normally
1824 # If the code compiles ok, we should handle it normally
1765 return self.handle_normal(line,continue_prompt)
1825 return self.handle_normal(line,continue_prompt)
1766
1826
1767 def handle_emacs(self,line,continue_prompt=None,
1827 def handle_emacs(self,line,continue_prompt=None,
1768 pre=None,iFun=None,theRest=None):
1828 pre=None,iFun=None,theRest=None):
1769 """Handle input lines marked by python-mode."""
1829 """Handle input lines marked by python-mode."""
1770
1830
1771 # Currently, nothing is done. Later more functionality can be added
1831 # Currently, nothing is done. Later more functionality can be added
1772 # here if needed.
1832 # here if needed.
1773
1833
1774 # The input cache shouldn't be updated
1834 # The input cache shouldn't be updated
1775
1835
1776 return line
1836 return line
1777
1837
1778 def write(self,data):
1838 def write(self,data):
1779 """Write a string to the default output"""
1839 """Write a string to the default output"""
1780 Term.cout.write(data)
1840 Term.cout.write(data)
1781
1841
1782 def write_err(self,data):
1842 def write_err(self,data):
1783 """Write a string to the default error output"""
1843 """Write a string to the default error output"""
1784 Term.cerr.write(data)
1844 Term.cerr.write(data)
1785
1845
1786 def exit(self):
1846 def exit(self):
1787 """Handle interactive exit.
1847 """Handle interactive exit.
1788
1848
1789 This method sets the exit_now attribute."""
1849 This method sets the exit_now attribute."""
1790
1850
1791 if self.rc.confirm_exit:
1851 if self.rc.confirm_exit:
1792 if ask_yes_no('Do you really want to exit ([y]/n)?','y'):
1852 if ask_yes_no('Do you really want to exit ([y]/n)?','y'):
1793 self.exit_now = True
1853 self.exit_now = True
1794 else:
1854 else:
1795 self.exit_now = True
1855 self.exit_now = True
1796 return self.exit_now
1856 return self.exit_now
1797
1857
1798 def safe_execfile(self,fname,*where,**kw):
1858 def safe_execfile(self,fname,*where,**kw):
1799 fname = os.path.expanduser(fname)
1859 fname = os.path.expanduser(fname)
1800
1860
1801 # find things also in current directory
1861 # find things also in current directory
1802 dname = os.path.dirname(fname)
1862 dname = os.path.dirname(fname)
1803 if not sys.path.count(dname):
1863 if not sys.path.count(dname):
1804 sys.path.append(dname)
1864 sys.path.append(dname)
1805
1865
1806 try:
1866 try:
1807 xfile = open(fname)
1867 xfile = open(fname)
1808 except:
1868 except:
1809 print >> Term.cerr, \
1869 print >> Term.cerr, \
1810 'Could not open file <%s> for safe execution.' % fname
1870 'Could not open file <%s> for safe execution.' % fname
1811 return None
1871 return None
1812
1872
1813 kw.setdefault('islog',0)
1873 kw.setdefault('islog',0)
1814 kw.setdefault('quiet',1)
1874 kw.setdefault('quiet',1)
1815 kw.setdefault('exit_ignore',0)
1875 kw.setdefault('exit_ignore',0)
1816 first = xfile.readline()
1876 first = xfile.readline()
1817 _LOGHEAD = str(self.LOGHEAD).split('\n',1)[0].strip()
1877 _LOGHEAD = str(self.LOGHEAD).split('\n',1)[0].strip()
1818 xfile.close()
1878 xfile.close()
1819 # line by line execution
1879 # line by line execution
1820 if first.startswith(_LOGHEAD) or kw['islog']:
1880 if first.startswith(_LOGHEAD) or kw['islog']:
1821 print 'Loading log file <%s> one line at a time...' % fname
1881 print 'Loading log file <%s> one line at a time...' % fname
1822 if kw['quiet']:
1882 if kw['quiet']:
1823 stdout_save = sys.stdout
1883 stdout_save = sys.stdout
1824 sys.stdout = StringIO.StringIO()
1884 sys.stdout = StringIO.StringIO()
1825 try:
1885 try:
1826 globs,locs = where[0:2]
1886 globs,locs = where[0:2]
1827 except:
1887 except:
1828 try:
1888 try:
1829 globs = locs = where[0]
1889 globs = locs = where[0]
1830 except:
1890 except:
1831 globs = locs = globals()
1891 globs = locs = globals()
1832 badblocks = []
1892 badblocks = []
1833
1893
1834 # we also need to identify indented blocks of code when replaying
1894 # we also need to identify indented blocks of code when replaying
1835 # logs and put them together before passing them to an exec
1895 # logs and put them together before passing them to an exec
1836 # statement. This takes a bit of regexp and look-ahead work in the
1896 # statement. This takes a bit of regexp and look-ahead work in the
1837 # file. It's easiest if we swallow the whole thing in memory
1897 # file. It's easiest if we swallow the whole thing in memory
1838 # first, and manually walk through the lines list moving the
1898 # first, and manually walk through the lines list moving the
1839 # counter ourselves.
1899 # counter ourselves.
1840 indent_re = re.compile('\s+\S')
1900 indent_re = re.compile('\s+\S')
1841 xfile = open(fname)
1901 xfile = open(fname)
1842 filelines = xfile.readlines()
1902 filelines = xfile.readlines()
1843 xfile.close()
1903 xfile.close()
1844 nlines = len(filelines)
1904 nlines = len(filelines)
1845 lnum = 0
1905 lnum = 0
1846 while lnum < nlines:
1906 while lnum < nlines:
1847 line = filelines[lnum]
1907 line = filelines[lnum]
1848 lnum += 1
1908 lnum += 1
1849 # don't re-insert logger status info into cache
1909 # don't re-insert logger status info into cache
1850 if line.startswith('#log#'):
1910 if line.startswith('#log#'):
1851 continue
1911 continue
1852 elif line.startswith('#%s'% self.ESC_MAGIC):
1912 elif line.startswith('#%s'% self.ESC_MAGIC):
1853 self.update_cache(line[1:])
1913 self.update_cache(line[1:])
1854 line = magic2python(line)
1914 line = magic2python(line)
1855 elif line.startswith('#!'):
1915 elif line.startswith('#!'):
1856 self.update_cache(line[1:])
1916 self.update_cache(line[1:])
1857 else:
1917 else:
1858 # build a block of code (maybe a single line) for execution
1918 # build a block of code (maybe a single line) for execution
1859 block = line
1919 block = line
1860 try:
1920 try:
1861 next = filelines[lnum] # lnum has already incremented
1921 next = filelines[lnum] # lnum has already incremented
1862 except:
1922 except:
1863 next = None
1923 next = None
1864 while next and indent_re.match(next):
1924 while next and indent_re.match(next):
1865 block += next
1925 block += next
1866 lnum += 1
1926 lnum += 1
1867 try:
1927 try:
1868 next = filelines[lnum]
1928 next = filelines[lnum]
1869 except:
1929 except:
1870 next = None
1930 next = None
1871 # now execute the block of one or more lines
1931 # now execute the block of one or more lines
1872 try:
1932 try:
1873 exec block in globs,locs
1933 exec block in globs,locs
1874 self.update_cache(block.rstrip())
1934 self.update_cache(block.rstrip())
1875 except SystemExit:
1935 except SystemExit:
1876 pass
1936 pass
1877 except:
1937 except:
1878 badblocks.append(block.rstrip())
1938 badblocks.append(block.rstrip())
1879 if kw['quiet']: # restore stdout
1939 if kw['quiet']: # restore stdout
1880 sys.stdout.close()
1940 sys.stdout.close()
1881 sys.stdout = stdout_save
1941 sys.stdout = stdout_save
1882 print 'Finished replaying log file <%s>' % fname
1942 print 'Finished replaying log file <%s>' % fname
1883 if badblocks:
1943 if badblocks:
1884 print >> sys.stderr, ('\nThe following lines/blocks in file '
1944 print >> sys.stderr, ('\nThe following lines/blocks in file '
1885 '<%s> reported errors:' % fname)
1945 '<%s> reported errors:' % fname)
1886
1946
1887 for badline in badblocks:
1947 for badline in badblocks:
1888 print >> sys.stderr, badline
1948 print >> sys.stderr, badline
1889 else: # regular file execution
1949 else: # regular file execution
1890 try:
1950 try:
1891 execfile(fname,*where)
1951 execfile(fname,*where)
1892 except SyntaxError:
1952 except SyntaxError:
1893 etype, evalue = sys.exc_info()[0:2]
1953 etype, evalue = sys.exc_info()[0:2]
1894 self.SyntaxTB(etype,evalue,[])
1954 self.SyntaxTB(etype,evalue,[])
1895 warn('Failure executing file: <%s>' % fname)
1955 warn('Failure executing file: <%s>' % fname)
1896 except SystemExit,status:
1956 except SystemExit,status:
1897 if not kw['exit_ignore']:
1957 if not kw['exit_ignore']:
1898 self.InteractiveTB()
1958 self.InteractiveTB()
1899 warn('Failure executing file: <%s>' % fname)
1959 warn('Failure executing file: <%s>' % fname)
1900 except:
1960 except:
1901 self.InteractiveTB()
1961 self.InteractiveTB()
1902 warn('Failure executing file: <%s>' % fname)
1962 warn('Failure executing file: <%s>' % fname)
1903
1963
1904 #************************* end of file <iplib.py> *****************************
1964 #************************* end of file <iplib.py> *****************************
@@ -1,735 +1,737 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 958 2005-12-27 23:17:51Z fperez $"""
9 $Id: ipmaker.py 960 2005-12-28 06:51:01Z 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
54 from IPython.Prompts import CachedOutput
55 from IPython.genutils import *
55 from IPython.genutils import *
56
56
57 #-----------------------------------------------------------------------------
57 #-----------------------------------------------------------------------------
58 def make_IPython(argv=None,user_ns=None,debug=1,rc_override=None,
58 def make_IPython(argv=None,user_ns=None,debug=1,rc_override=None,
59 shell_class=InteractiveShell,embedded=False,**kw):
59 shell_class=InteractiveShell,embedded=False,**kw):
60 """This is a dump of IPython into a single function.
60 """This is a dump of IPython into a single function.
61
61
62 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.
63
63
64 Arguments:
64 Arguments:
65
65
66 - 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
67 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
68 sys.argv.
68 sys.argv.
69
69
70 - 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."""
71
71
72 #----------------------------------------------------------------------
72 #----------------------------------------------------------------------
73 # Defaults and initialization
73 # Defaults and initialization
74
74
75 # For developer debugging, deactivates crash handler and uses pdb.
75 # For developer debugging, deactivates crash handler and uses pdb.
76 DEVDEBUG = False
76 DEVDEBUG = False
77
77
78 if argv is None:
78 if argv is None:
79 argv = sys.argv
79 argv = sys.argv
80
80
81 # __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
82 # 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
83 # happens.
83 # happens.
84
84
85 # __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
86 # __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
87 # InteractiveShell:
87 # InteractiveShell:
88
88
89 IP = shell_class('__IP',user_ns=user_ns,embedded=embedded,**kw)
89 IP = shell_class('__IP',user_ns=user_ns,embedded=embedded,**kw)
90
90
91 # Put 'help' in the user namespace
91 # Put 'help' in the user namespace
92 from site import _Helper
92 from site import _Helper
93 IP.user_ns['help'] = _Helper()
93 IP.user_ns['help'] = _Helper()
94
94
95 if DEVDEBUG:
95 if DEVDEBUG:
96 # For developer debugging only (global flag)
96 # For developer debugging only (global flag)
97 from IPython import ultraTB
97 from IPython import ultraTB
98 sys.excepthook = ultraTB.VerboseTB(call_pdb=1)
98 sys.excepthook = ultraTB.VerboseTB(call_pdb=1)
99 else:
99 else:
100 # IPython itself shouldn't crash. This will produce a detailed
100 # IPython itself shouldn't crash. This will produce a detailed
101 # post-mortem if it does
101 # post-mortem if it does
102 from IPython import CrashHandler
102 from IPython import CrashHandler
103 sys.excepthook = CrashHandler.CrashHandler(IP)
103 sys.excepthook = CrashHandler.CrashHandler(IP)
104
104
105 IP.BANNER_PARTS = ['Python %s\n'
105 IP.BANNER_PARTS = ['Python %s\n'
106 'Type "copyright", "credits" or "license" '
106 'Type "copyright", "credits" or "license" '
107 'for more information.\n'
107 'for more information.\n'
108 % (sys.version.split('\n')[0],),
108 % (sys.version.split('\n')[0],),
109 "IPython %s -- An enhanced Interactive Python."
109 "IPython %s -- An enhanced Interactive Python."
110 % (__version__,),
110 % (__version__,),
111 """? -> Introduction to IPython's features.
111 """? -> Introduction to IPython's features.
112 %magic -> Information about IPython's 'magic' % functions.
112 %magic -> Information about IPython's 'magic' % functions.
113 help -> Python's own help system.
113 help -> Python's own help system.
114 object? -> Details about 'object'. ?object also works, ?? prints more.
114 object? -> Details about 'object'. ?object also works, ?? prints more.
115 """ ]
115 """ ]
116
116
117 IP.usage = interactive_usage
117 IP.usage = interactive_usage
118
118
119 # Platform-dependent suffix and directory names. We use _ipython instead
119 # Platform-dependent suffix and directory names. We use _ipython instead
120 # of .ipython under win32 b/c there's software that breaks with .named
120 # of .ipython under win32 b/c there's software that breaks with .named
121 # directories on that platform.
121 # directories on that platform.
122 if os.name == 'posix':
122 if os.name == 'posix':
123 rc_suffix = ''
123 rc_suffix = ''
124 ipdir_def = '.ipython'
124 ipdir_def = '.ipython'
125 else:
125 else:
126 rc_suffix = '.ini'
126 rc_suffix = '.ini'
127 ipdir_def = '_ipython'
127 ipdir_def = '_ipython'
128
128
129 # default directory for configuration
129 # default directory for configuration
130 ipythondir = os.path.abspath(os.environ.get('IPYTHONDIR',
130 ipythondir = os.path.abspath(os.environ.get('IPYTHONDIR',
131 os.path.join(IP.home_dir,ipdir_def)))
131 os.path.join(IP.home_dir,ipdir_def)))
132
132
133 # we need the directory where IPython itself is installed
133 # we need the directory where IPython itself is installed
134 import IPython
134 import IPython
135 IPython_dir = os.path.dirname(IPython.__file__)
135 IPython_dir = os.path.dirname(IPython.__file__)
136 del IPython
136 del IPython
137
137
138 #-------------------------------------------------------------------------
138 #-------------------------------------------------------------------------
139 # Command line handling
139 # Command line handling
140
140
141 # Valid command line options (uses DPyGetOpt syntax, like Perl's
141 # Valid command line options (uses DPyGetOpt syntax, like Perl's
142 # GetOpt::Long)
142 # GetOpt::Long)
143
143
144 # Any key not listed here gets deleted even if in the file (like session
144 # Any key not listed here gets deleted even if in the file (like session
145 # or profile). That's deliberate, to maintain the rc namespace clean.
145 # or profile). That's deliberate, to maintain the rc namespace clean.
146
146
147 # Each set of options appears twice: under _conv only the names are
147 # Each set of options appears twice: under _conv only the names are
148 # listed, indicating which type they must be converted to when reading the
148 # listed, indicating which type they must be converted to when reading the
149 # ipythonrc file. And under DPyGetOpt they are listed with the regular
149 # ipythonrc file. And under DPyGetOpt they are listed with the regular
150 # DPyGetOpt syntax (=s,=i,:f,etc).
150 # DPyGetOpt syntax (=s,=i,:f,etc).
151
151
152 # Make sure there's a space before each end of line (they get auto-joined!)
152 # Make sure there's a space before each end of line (they get auto-joined!)
153 cmdline_opts = ('autocall! autoindent! automagic! banner! cache_size|cs=i '
153 cmdline_opts = ('autocall! autoindent! automagic! banner! cache_size|cs=i '
154 'c=s classic|cl color_info! colors=s confirm_exit! '
154 'c=s classic|cl color_info! colors=s confirm_exit! '
155 'debug! deep_reload! editor=s log|l messages! nosep pdb! '
155 'debug! deep_reload! editor=s log|l messages! nosep pdb! '
156 'pprint! prompt_in1|pi1=s prompt_in2|pi2=s prompt_out|po=s '
156 'pprint! prompt_in1|pi1=s prompt_in2|pi2=s prompt_out|po=s '
157 'quick screen_length|sl=i prompts_pad_left=i '
157 'quick screen_length|sl=i prompts_pad_left=i '
158 'logfile|lf=s logplay|lp=s profile|p=s '
158 'logfile|lf=s logplay|lp=s profile|p=s '
159 'readline! readline_merge_completions! '
159 'readline! readline_merge_completions! '
160 'readline_omit__names! '
160 'readline_omit__names! '
161 'rcfile=s separate_in|si=s separate_out|so=s '
161 'rcfile=s separate_in|si=s separate_out|so=s '
162 'separate_out2|so2=s xmode=s wildcards_case_sensitive! '
162 'separate_out2|so2=s xmode=s wildcards_case_sensitive! '
163 'magic_docstrings system_verbose! '
163 'magic_docstrings system_verbose! '
164 'multi_line_specials!')
164 'multi_line_specials! '
165 'autoedit_syntax!')
165
166
166 # Options that can *only* appear at the cmd line (not in rcfiles).
167 # Options that can *only* appear at the cmd line (not in rcfiles).
167
168
168 # The "ignore" option is a kludge so that Emacs buffers don't crash, since
169 # The "ignore" option is a kludge so that Emacs buffers don't crash, since
169 # the 'C-c !' command in emacs automatically appends a -i option at the end.
170 # the 'C-c !' command in emacs automatically appends a -i option at the end.
170 cmdline_only = ('help ignore|i ipythondir=s Version upgrade '
171 cmdline_only = ('help ignore|i ipythondir=s Version upgrade '
171 'gthread! qthread! wthread! pylab! tk!')
172 'gthread! qthread! wthread! pylab! tk!')
172
173
173 # Build the actual name list to be used by DPyGetOpt
174 # Build the actual name list to be used by DPyGetOpt
174 opts_names = qw(cmdline_opts) + qw(cmdline_only)
175 opts_names = qw(cmdline_opts) + qw(cmdline_only)
175
176
176 # Set sensible command line defaults.
177 # Set sensible command line defaults.
177 # This should have everything from cmdline_opts and cmdline_only
178 # This should have everything from cmdline_opts and cmdline_only
178 opts_def = Struct(autocall = 1,
179 opts_def = Struct(autocall = 1,
179 autoindent=0,
180 autoindent=0,
180 automagic = 1,
181 automagic = 1,
181 banner = 1,
182 banner = 1,
182 cache_size = 1000,
183 cache_size = 1000,
183 c = '',
184 c = '',
184 classic = 0,
185 classic = 0,
185 colors = 'NoColor',
186 colors = 'NoColor',
186 color_info = 0,
187 color_info = 0,
187 confirm_exit = 1,
188 confirm_exit = 1,
188 debug = 0,
189 debug = 0,
189 deep_reload = 0,
190 deep_reload = 0,
190 editor = '0',
191 editor = '0',
191 help = 0,
192 help = 0,
192 ignore = 0,
193 ignore = 0,
193 ipythondir = ipythondir,
194 ipythondir = ipythondir,
194 log = 0,
195 log = 0,
195 logfile = '',
196 logfile = '',
196 logplay = '',
197 logplay = '',
197 multi_line_specials = 1,
198 multi_line_specials = 1,
198 messages = 1,
199 messages = 1,
199 nosep = 0,
200 nosep = 0,
200 pdb = 0,
201 pdb = 0,
201 pprint = 0,
202 pprint = 0,
202 profile = '',
203 profile = '',
203 prompt_in1 = 'In [\\#]: ',
204 prompt_in1 = 'In [\\#]: ',
204 prompt_in2 = ' .\\D.: ',
205 prompt_in2 = ' .\\D.: ',
205 prompt_out = 'Out[\\#]: ',
206 prompt_out = 'Out[\\#]: ',
206 prompts_pad_left = 1,
207 prompts_pad_left = 1,
207 quick = 0,
208 quick = 0,
208 readline = 1,
209 readline = 1,
209 readline_merge_completions = 1,
210 readline_merge_completions = 1,
210 readline_omit__names = 0,
211 readline_omit__names = 0,
211 rcfile = 'ipythonrc' + rc_suffix,
212 rcfile = 'ipythonrc' + rc_suffix,
212 screen_length = 0,
213 screen_length = 0,
213 separate_in = '\n',
214 separate_in = '\n',
214 separate_out = '\n',
215 separate_out = '\n',
215 separate_out2 = '',
216 separate_out2 = '',
216 system_verbose = 0,
217 system_verbose = 0,
217 gthread = 0,
218 gthread = 0,
218 qthread = 0,
219 qthread = 0,
219 wthread = 0,
220 wthread = 0,
220 pylab = 0,
221 pylab = 0,
221 tk = 0,
222 tk = 0,
222 upgrade = 0,
223 upgrade = 0,
223 Version = 0,
224 Version = 0,
224 xmode = 'Verbose',
225 xmode = 'Verbose',
225 wildcards_case_sensitive = 1,
226 wildcards_case_sensitive = 1,
226 magic_docstrings = 0, # undocumented, for doc generation
227 magic_docstrings = 0, # undocumented, for doc generation
228 autoedit_syntax = 0,
227 )
229 )
228
230
229 # Things that will *only* appear in rcfiles (not at the command line).
231 # 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!)
232 # 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 ',
233 rcfile_opts = { qwflat: 'include import_mod import_all execfile ',
232 qw_lol: 'import_some ',
234 qw_lol: 'import_some ',
233 # for things with embedded whitespace:
235 # for things with embedded whitespace:
234 list_strings:'execute alias readline_parse_and_bind ',
236 list_strings:'execute alias readline_parse_and_bind ',
235 # Regular strings need no conversion:
237 # Regular strings need no conversion:
236 None:'readline_remove_delims ',
238 None:'readline_remove_delims ',
237 }
239 }
238 # Default values for these
240 # Default values for these
239 rc_def = Struct(include = [],
241 rc_def = Struct(include = [],
240 import_mod = [],
242 import_mod = [],
241 import_all = [],
243 import_all = [],
242 import_some = [[]],
244 import_some = [[]],
243 execute = [],
245 execute = [],
244 execfile = [],
246 execfile = [],
245 alias = [],
247 alias = [],
246 readline_parse_and_bind = [],
248 readline_parse_and_bind = [],
247 readline_remove_delims = '',
249 readline_remove_delims = '',
248 )
250 )
249
251
250 # Build the type conversion dictionary from the above tables:
252 # Build the type conversion dictionary from the above tables:
251 typeconv = rcfile_opts.copy()
253 typeconv = rcfile_opts.copy()
252 typeconv.update(optstr2types(cmdline_opts))
254 typeconv.update(optstr2types(cmdline_opts))
253
255
254 # FIXME: the None key appears in both, put that back together by hand. Ugly!
256 # FIXME: the None key appears in both, put that back together by hand. Ugly!
255 typeconv[None] += ' ' + rcfile_opts[None]
257 typeconv[None] += ' ' + rcfile_opts[None]
256
258
257 # Remove quotes at ends of all strings (used to protect spaces)
259 # Remove quotes at ends of all strings (used to protect spaces)
258 typeconv[unquote_ends] = typeconv[None]
260 typeconv[unquote_ends] = typeconv[None]
259 del typeconv[None]
261 del typeconv[None]
260
262
261 # Build the list we'll use to make all config decisions with defaults:
263 # Build the list we'll use to make all config decisions with defaults:
262 opts_all = opts_def.copy()
264 opts_all = opts_def.copy()
263 opts_all.update(rc_def)
265 opts_all.update(rc_def)
264
266
265 # Build conflict resolver for recursive loading of config files:
267 # Build conflict resolver for recursive loading of config files:
266 # - preserve means the outermost file maintains the value, it is not
268 # - preserve means the outermost file maintains the value, it is not
267 # overwritten if an included file has the same key.
269 # overwritten if an included file has the same key.
268 # - add_flip applies + to the two values, so it better make sense to add
270 # - 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
271 # those types of keys. But it flips them first so that things loaded
270 # deeper in the inclusion chain have lower precedence.
272 # deeper in the inclusion chain have lower precedence.
271 conflict = {'preserve': ' '.join([ typeconv[int],
273 conflict = {'preserve': ' '.join([ typeconv[int],
272 typeconv[unquote_ends] ]),
274 typeconv[unquote_ends] ]),
273 'add_flip': ' '.join([ typeconv[qwflat],
275 'add_flip': ' '.join([ typeconv[qwflat],
274 typeconv[qw_lol],
276 typeconv[qw_lol],
275 typeconv[list_strings] ])
277 typeconv[list_strings] ])
276 }
278 }
277
279
278 # Now actually process the command line
280 # Now actually process the command line
279 getopt = DPyGetOpt.DPyGetOpt()
281 getopt = DPyGetOpt.DPyGetOpt()
280 getopt.setIgnoreCase(0)
282 getopt.setIgnoreCase(0)
281
283
282 getopt.parseConfiguration(opts_names)
284 getopt.parseConfiguration(opts_names)
283
285
284 try:
286 try:
285 getopt.processArguments(argv)
287 getopt.processArguments(argv)
286 except:
288 except:
287 print cmd_line_usage
289 print cmd_line_usage
288 warn('\nError in Arguments: ' + `sys.exc_value`)
290 warn('\nError in Arguments: ' + `sys.exc_value`)
289 sys.exit(1)
291 sys.exit(1)
290
292
291 # convert the options dict to a struct for much lighter syntax later
293 # convert the options dict to a struct for much lighter syntax later
292 opts = Struct(getopt.optionValues)
294 opts = Struct(getopt.optionValues)
293 args = getopt.freeValues
295 args = getopt.freeValues
294
296
295 # this is the struct (which has default values at this point) with which
297 # this is the struct (which has default values at this point) with which
296 # we make all decisions:
298 # we make all decisions:
297 opts_all.update(opts)
299 opts_all.update(opts)
298
300
299 # Options that force an immediate exit
301 # Options that force an immediate exit
300 if opts_all.help:
302 if opts_all.help:
301 page(cmd_line_usage)
303 page(cmd_line_usage)
302 sys.exit()
304 sys.exit()
303
305
304 if opts_all.Version:
306 if opts_all.Version:
305 print __version__
307 print __version__
306 sys.exit()
308 sys.exit()
307
309
308 if opts_all.magic_docstrings:
310 if opts_all.magic_docstrings:
309 IP.magic_magic('-latex')
311 IP.magic_magic('-latex')
310 sys.exit()
312 sys.exit()
311
313
312 # Create user config directory if it doesn't exist. This must be done
314 # Create user config directory if it doesn't exist. This must be done
313 # *after* getting the cmd line options.
315 # *after* getting the cmd line options.
314 if not os.path.isdir(opts_all.ipythondir):
316 if not os.path.isdir(opts_all.ipythondir):
315 IP.user_setup(opts_all.ipythondir,rc_suffix,'install')
317 IP.user_setup(opts_all.ipythondir,rc_suffix,'install')
316
318
317 # upgrade user config files while preserving a copy of the originals
319 # upgrade user config files while preserving a copy of the originals
318 if opts_all.upgrade:
320 if opts_all.upgrade:
319 IP.user_setup(opts_all.ipythondir,rc_suffix,'upgrade')
321 IP.user_setup(opts_all.ipythondir,rc_suffix,'upgrade')
320
322
321 # check mutually exclusive options in the *original* command line
323 # check mutually exclusive options in the *original* command line
322 mutex_opts(opts,[qw('log logfile'),qw('rcfile profile'),
324 mutex_opts(opts,[qw('log logfile'),qw('rcfile profile'),
323 qw('classic profile'),qw('classic rcfile')])
325 qw('classic profile'),qw('classic rcfile')])
324
326
325 # default logfilename used when -log is called.
327 # default logfilename used when -log is called.
326 IP.LOGDEF = 'ipython.log'
328 IP.LOGDEF = 'ipython.log'
327
329
328 #---------------------------------------------------------------------------
330 #---------------------------------------------------------------------------
329 # Log replay
331 # Log replay
330
332
331 # if -logplay, we need to 'become' the other session. That basically means
333 # if -logplay, we need to 'become' the other session. That basically means
332 # replacing the current command line environment with that of the old
334 # replacing the current command line environment with that of the old
333 # session and moving on.
335 # session and moving on.
334
336
335 # this is needed so that later we know we're in session reload mode, as
337 # this is needed so that later we know we're in session reload mode, as
336 # opts_all will get overwritten:
338 # opts_all will get overwritten:
337 load_logplay = 0
339 load_logplay = 0
338
340
339 if opts_all.logplay:
341 if opts_all.logplay:
340 load_logplay = opts_all.logplay
342 load_logplay = opts_all.logplay
341 opts_debug_save = opts_all.debug
343 opts_debug_save = opts_all.debug
342 try:
344 try:
343 logplay = open(opts_all.logplay)
345 logplay = open(opts_all.logplay)
344 except IOError:
346 except IOError:
345 if opts_all.debug: IP.InteractiveTB()
347 if opts_all.debug: IP.InteractiveTB()
346 warn('Could not open logplay file '+`opts_all.logplay`)
348 warn('Could not open logplay file '+`opts_all.logplay`)
347 # restore state as if nothing had happened and move on, but make
349 # 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
350 # sure that later we don't try to actually load the session file
349 logplay = None
351 logplay = None
350 load_logplay = 0
352 load_logplay = 0
351 del opts_all.logplay
353 del opts_all.logplay
352 else:
354 else:
353 try:
355 try:
354 logplay.readline()
356 logplay.readline()
355 logplay.readline();
357 logplay.readline();
356 # this reloads that session's command line
358 # this reloads that session's command line
357 cmd = logplay.readline()[6:]
359 cmd = logplay.readline()[6:]
358 exec cmd
360 exec cmd
359 # restore the true debug flag given so that the process of
361 # restore the true debug flag given so that the process of
360 # session loading itself can be monitored.
362 # session loading itself can be monitored.
361 opts.debug = opts_debug_save
363 opts.debug = opts_debug_save
362 # save the logplay flag so later we don't overwrite the log
364 # save the logplay flag so later we don't overwrite the log
363 opts.logplay = load_logplay
365 opts.logplay = load_logplay
364 # now we must update our own structure with defaults
366 # now we must update our own structure with defaults
365 opts_all.update(opts)
367 opts_all.update(opts)
366 # now load args
368 # now load args
367 cmd = logplay.readline()[6:]
369 cmd = logplay.readline()[6:]
368 exec cmd
370 exec cmd
369 logplay.close()
371 logplay.close()
370 except:
372 except:
371 logplay.close()
373 logplay.close()
372 if opts_all.debug: IP.InteractiveTB()
374 if opts_all.debug: IP.InteractiveTB()
373 warn("Logplay file lacking full configuration information.\n"
375 warn("Logplay file lacking full configuration information.\n"
374 "I'll try to read it, but some things may not work.")
376 "I'll try to read it, but some things may not work.")
375
377
376 #-------------------------------------------------------------------------
378 #-------------------------------------------------------------------------
377 # set up output traps: catch all output from files, being run, modules
379 # 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.
380 # loaded, etc. Then give it to the user in a clean form at the end.
379
381
380 msg_out = 'Output messages. '
382 msg_out = 'Output messages. '
381 msg_err = 'Error messages. '
383 msg_err = 'Error messages. '
382 msg_sep = '\n'
384 msg_sep = '\n'
383 msg = Struct(config = OutputTrap('Configuration Loader',msg_out,
385 msg = Struct(config = OutputTrap('Configuration Loader',msg_out,
384 msg_err,msg_sep,debug,
386 msg_err,msg_sep,debug,
385 quiet_out=1),
387 quiet_out=1),
386 user_exec = OutputTrap('User File Execution',msg_out,
388 user_exec = OutputTrap('User File Execution',msg_out,
387 msg_err,msg_sep,debug),
389 msg_err,msg_sep,debug),
388 logplay = OutputTrap('Log Loader',msg_out,
390 logplay = OutputTrap('Log Loader',msg_out,
389 msg_err,msg_sep,debug),
391 msg_err,msg_sep,debug),
390 summary = ''
392 summary = ''
391 )
393 )
392
394
393 #-------------------------------------------------------------------------
395 #-------------------------------------------------------------------------
394 # Process user ipythonrc-type configuration files
396 # Process user ipythonrc-type configuration files
395
397
396 # turn on output trapping and log to msg.config
398 # turn on output trapping and log to msg.config
397 # remember that with debug on, trapping is actually disabled
399 # remember that with debug on, trapping is actually disabled
398 msg.config.trap_all()
400 msg.config.trap_all()
399
401
400 # look for rcfile in current or default directory
402 # look for rcfile in current or default directory
401 try:
403 try:
402 opts_all.rcfile = filefind(opts_all.rcfile,opts_all.ipythondir)
404 opts_all.rcfile = filefind(opts_all.rcfile,opts_all.ipythondir)
403 except IOError:
405 except IOError:
404 if opts_all.debug: IP.InteractiveTB()
406 if opts_all.debug: IP.InteractiveTB()
405 warn('Configuration file %s not found. Ignoring request.'
407 warn('Configuration file %s not found. Ignoring request.'
406 % (opts_all.rcfile) )
408 % (opts_all.rcfile) )
407
409
408 # 'profiles' are a shorthand notation for config filenames
410 # 'profiles' are a shorthand notation for config filenames
409 if opts_all.profile:
411 if opts_all.profile:
410 try:
412 try:
411 opts_all.rcfile = filefind('ipythonrc-' + opts_all.profile
413 opts_all.rcfile = filefind('ipythonrc-' + opts_all.profile
412 + rc_suffix,
414 + rc_suffix,
413 opts_all.ipythondir)
415 opts_all.ipythondir)
414 except IOError:
416 except IOError:
415 if opts_all.debug: IP.InteractiveTB()
417 if opts_all.debug: IP.InteractiveTB()
416 opts.profile = '' # remove profile from options if invalid
418 opts.profile = '' # remove profile from options if invalid
417 warn('Profile configuration file %s not found. Ignoring request.'
419 warn('Profile configuration file %s not found. Ignoring request.'
418 % (opts_all.profile) )
420 % (opts_all.profile) )
419
421
420 # load the config file
422 # load the config file
421 rcfiledata = None
423 rcfiledata = None
422 if opts_all.quick:
424 if opts_all.quick:
423 print 'Launching IPython in quick mode. No config file read.'
425 print 'Launching IPython in quick mode. No config file read.'
424 elif opts_all.classic:
426 elif opts_all.classic:
425 print 'Launching IPython in classic mode. No config file read.'
427 print 'Launching IPython in classic mode. No config file read.'
426 elif opts_all.rcfile:
428 elif opts_all.rcfile:
427 try:
429 try:
428 cfg_loader = ConfigLoader(conflict)
430 cfg_loader = ConfigLoader(conflict)
429 rcfiledata = cfg_loader.load(opts_all.rcfile,typeconv,
431 rcfiledata = cfg_loader.load(opts_all.rcfile,typeconv,
430 'include',opts_all.ipythondir,
432 'include',opts_all.ipythondir,
431 purge = 1,
433 purge = 1,
432 unique = conflict['preserve'])
434 unique = conflict['preserve'])
433 except:
435 except:
434 IP.InteractiveTB()
436 IP.InteractiveTB()
435 warn('Problems loading configuration file '+
437 warn('Problems loading configuration file '+
436 `opts_all.rcfile`+
438 `opts_all.rcfile`+
437 '\nStarting with default -bare bones- configuration.')
439 '\nStarting with default -bare bones- configuration.')
438 else:
440 else:
439 warn('No valid configuration file found in either currrent directory\n'+
441 warn('No valid configuration file found in either currrent directory\n'+
440 'or in the IPython config. directory: '+`opts_all.ipythondir`+
442 'or in the IPython config. directory: '+`opts_all.ipythondir`+
441 '\nProceeding with internal defaults.')
443 '\nProceeding with internal defaults.')
442
444
443 #------------------------------------------------------------------------
445 #------------------------------------------------------------------------
444 # Set exception handlers in mode requested by user.
446 # Set exception handlers in mode requested by user.
445 otrap = OutputTrap(trap_out=1) # trap messages from magic_xmode
447 otrap = OutputTrap(trap_out=1) # trap messages from magic_xmode
446 IP.magic_xmode(opts_all.xmode)
448 IP.magic_xmode(opts_all.xmode)
447 otrap.release_out()
449 otrap.release_out()
448
450
449 #------------------------------------------------------------------------
451 #------------------------------------------------------------------------
450 # Execute user config
452 # Execute user config
451
453
452 # Create a valid config structure with the right precedence order:
454 # Create a valid config structure with the right precedence order:
453 # defaults < rcfile < command line. This needs to be in the instance, so
455 # defaults < rcfile < command line. This needs to be in the instance, so
454 # that method calls below that rely on it find it.
456 # that method calls below that rely on it find it.
455 IP.rc = rc_def.copy()
457 IP.rc = rc_def.copy()
456
458
457 # Work with a local alias inside this routine to avoid unnecessary
459 # Work with a local alias inside this routine to avoid unnecessary
458 # attribute lookups.
460 # attribute lookups.
459 IP_rc = IP.rc
461 IP_rc = IP.rc
460
462
461 IP_rc.update(opts_def)
463 IP_rc.update(opts_def)
462 if rcfiledata:
464 if rcfiledata:
463 # now we can update
465 # now we can update
464 IP_rc.update(rcfiledata)
466 IP_rc.update(rcfiledata)
465 IP_rc.update(opts)
467 IP_rc.update(opts)
466 IP_rc.update(rc_override)
468 IP_rc.update(rc_override)
467
469
468 # Store the original cmd line for reference:
470 # Store the original cmd line for reference:
469 IP_rc.opts = opts
471 IP_rc.opts = opts
470 IP_rc.args = args
472 IP_rc.args = args
471
473
472 # create a *runtime* Struct like rc for holding parameters which may be
474 # create a *runtime* Struct like rc for holding parameters which may be
473 # created and/or modified by runtime user extensions.
475 # created and/or modified by runtime user extensions.
474 IP.runtime_rc = Struct()
476 IP.runtime_rc = Struct()
475
477
476 # from this point on, all config should be handled through IP_rc,
478 # from this point on, all config should be handled through IP_rc,
477 # opts* shouldn't be used anymore.
479 # opts* shouldn't be used anymore.
478
480
479 # add personal .ipython dir to sys.path so that users can put things in
481 # add personal .ipython dir to sys.path so that users can put things in
480 # there for customization
482 # there for customization
481 sys.path.append(IP_rc.ipythondir)
483 sys.path.append(IP_rc.ipythondir)
482 sys.path.insert(0, '') # add . to sys.path. Fix from Prabhu Ramachandran
484 sys.path.insert(0, '') # add . to sys.path. Fix from Prabhu Ramachandran
483
485
484 # update IP_rc with some special things that need manual
486 # update IP_rc with some special things that need manual
485 # tweaks. Basically options which affect other options. I guess this
487 # tweaks. Basically options which affect other options. I guess this
486 # should just be written so that options are fully orthogonal and we
488 # should just be written so that options are fully orthogonal and we
487 # wouldn't worry about this stuff!
489 # wouldn't worry about this stuff!
488
490
489 if IP_rc.classic:
491 if IP_rc.classic:
490 IP_rc.quick = 1
492 IP_rc.quick = 1
491 IP_rc.cache_size = 0
493 IP_rc.cache_size = 0
492 IP_rc.pprint = 0
494 IP_rc.pprint = 0
493 IP_rc.prompt_in1 = '>>> '
495 IP_rc.prompt_in1 = '>>> '
494 IP_rc.prompt_in2 = '... '
496 IP_rc.prompt_in2 = '... '
495 IP_rc.prompt_out = ''
497 IP_rc.prompt_out = ''
496 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
498 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
497 IP_rc.colors = 'NoColor'
499 IP_rc.colors = 'NoColor'
498 IP_rc.xmode = 'Plain'
500 IP_rc.xmode = 'Plain'
499
501
500 # configure readline
502 # configure readline
501 # Define the history file for saving commands in between sessions
503 # Define the history file for saving commands in between sessions
502 if IP_rc.profile:
504 if IP_rc.profile:
503 histfname = 'history-%s' % IP_rc.profile
505 histfname = 'history-%s' % IP_rc.profile
504 else:
506 else:
505 histfname = 'history'
507 histfname = 'history'
506 IP.histfile = os.path.join(opts_all.ipythondir,histfname)
508 IP.histfile = os.path.join(opts_all.ipythondir,histfname)
507
509
508 # update exception handlers with rc file status
510 # update exception handlers with rc file status
509 otrap.trap_out() # I don't want these messages ever.
511 otrap.trap_out() # I don't want these messages ever.
510 IP.magic_xmode(IP_rc.xmode)
512 IP.magic_xmode(IP_rc.xmode)
511 otrap.release_out()
513 otrap.release_out()
512
514
513 # activate logging if requested and not reloading a log
515 # activate logging if requested and not reloading a log
514 if IP_rc.logplay:
516 if IP_rc.logplay:
515 IP.magic_logstart(IP_rc.logplay + ' append')
517 IP.magic_logstart(IP_rc.logplay + ' append')
516 elif IP_rc.logfile:
518 elif IP_rc.logfile:
517 IP.magic_logstart(IP_rc.logfile)
519 IP.magic_logstart(IP_rc.logfile)
518 elif IP_rc.log:
520 elif IP_rc.log:
519 IP.magic_logstart()
521 IP.magic_logstart()
520
522
521 # find user editor so that it we don't have to look it up constantly
523 # find user editor so that it we don't have to look it up constantly
522 if IP_rc.editor.strip()=='0':
524 if IP_rc.editor.strip()=='0':
523 try:
525 try:
524 ed = os.environ['EDITOR']
526 ed = os.environ['EDITOR']
525 except KeyError:
527 except KeyError:
526 if os.name == 'posix':
528 if os.name == 'posix':
527 ed = 'vi' # the only one guaranteed to be there!
529 ed = 'vi' # the only one guaranteed to be there!
528 else:
530 else:
529 ed = 'notepad' # same in Windows!
531 ed = 'notepad' # same in Windows!
530 IP_rc.editor = ed
532 IP_rc.editor = ed
531
533
532 # Keep track of whether this is an embedded instance or not (useful for
534 # Keep track of whether this is an embedded instance or not (useful for
533 # post-mortems).
535 # post-mortems).
534 IP_rc.embedded = IP.embedded
536 IP_rc.embedded = IP.embedded
535
537
536 # Recursive reload
538 # Recursive reload
537 try:
539 try:
538 from IPython import deep_reload
540 from IPython import deep_reload
539 if IP_rc.deep_reload:
541 if IP_rc.deep_reload:
540 __builtin__.reload = deep_reload.reload
542 __builtin__.reload = deep_reload.reload
541 else:
543 else:
542 __builtin__.dreload = deep_reload.reload
544 __builtin__.dreload = deep_reload.reload
543 del deep_reload
545 del deep_reload
544 except ImportError:
546 except ImportError:
545 pass
547 pass
546
548
547 # Save the current state of our namespace so that the interactive shell
549 # 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
550 # 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
551 # 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.
552 # defining things on the command line, and %who works as expected.
551
553
552 # DON'T do anything that affects the namespace beyond this point!
554 # DON'T do anything that affects the namespace beyond this point!
553 IP.internal_ns.update(__main__.__dict__)
555 IP.internal_ns.update(__main__.__dict__)
554
556
555 #IP.internal_ns.update(locals()) # so our stuff doesn't show up in %who
557 #IP.internal_ns.update(locals()) # so our stuff doesn't show up in %who
556
558
557 # Now run through the different sections of the users's config
559 # Now run through the different sections of the users's config
558 if IP_rc.debug:
560 if IP_rc.debug:
559 print 'Trying to execute the following configuration structure:'
561 print 'Trying to execute the following configuration structure:'
560 print '(Things listed first are deeper in the inclusion tree and get'
562 print '(Things listed first are deeper in the inclusion tree and get'
561 print 'loaded first).\n'
563 print 'loaded first).\n'
562 pprint(IP_rc.__dict__)
564 pprint(IP_rc.__dict__)
563
565
564 for mod in IP_rc.import_mod:
566 for mod in IP_rc.import_mod:
565 try:
567 try:
566 exec 'import '+mod in IP.user_ns
568 exec 'import '+mod in IP.user_ns
567 except :
569 except :
568 IP.InteractiveTB()
570 IP.InteractiveTB()
569 import_fail_info(mod)
571 import_fail_info(mod)
570
572
571 for mod_fn in IP_rc.import_some:
573 for mod_fn in IP_rc.import_some:
572 if mod_fn == []: break
574 if mod_fn == []: break
573 mod,fn = mod_fn[0],','.join(mod_fn[1:])
575 mod,fn = mod_fn[0],','.join(mod_fn[1:])
574 try:
576 try:
575 exec 'from '+mod+' import '+fn in IP.user_ns
577 exec 'from '+mod+' import '+fn in IP.user_ns
576 except :
578 except :
577 IP.InteractiveTB()
579 IP.InteractiveTB()
578 import_fail_info(mod,fn)
580 import_fail_info(mod,fn)
579
581
580 for mod in IP_rc.import_all:
582 for mod in IP_rc.import_all:
581 try:
583 try:
582 exec 'from '+mod+' import *' in IP.user_ns
584 exec 'from '+mod+' import *' in IP.user_ns
583 except :
585 except :
584 IP.InteractiveTB()
586 IP.InteractiveTB()
585 import_fail_info(mod)
587 import_fail_info(mod)
586
588
587 for code in IP_rc.execute:
589 for code in IP_rc.execute:
588 try:
590 try:
589 exec code in IP.user_ns
591 exec code in IP.user_ns
590 except:
592 except:
591 IP.InteractiveTB()
593 IP.InteractiveTB()
592 warn('Failure executing code: ' + `code`)
594 warn('Failure executing code: ' + `code`)
593
595
594 # Execute the files the user wants in ipythonrc
596 # Execute the files the user wants in ipythonrc
595 for file in IP_rc.execfile:
597 for file in IP_rc.execfile:
596 try:
598 try:
597 file = filefind(file,sys.path+[IPython_dir])
599 file = filefind(file,sys.path+[IPython_dir])
598 except IOError:
600 except IOError:
599 warn(itpl('File $file not found. Skipping it.'))
601 warn(itpl('File $file not found. Skipping it.'))
600 else:
602 else:
601 IP.safe_execfile(os.path.expanduser(file),IP.user_ns)
603 IP.safe_execfile(os.path.expanduser(file),IP.user_ns)
602
604
603 # release stdout and stderr and save config log into a global summary
605 # release stdout and stderr and save config log into a global summary
604 msg.config.release_all()
606 msg.config.release_all()
605 if IP_rc.messages:
607 if IP_rc.messages:
606 msg.summary += msg.config.summary_all()
608 msg.summary += msg.config.summary_all()
607
609
608 #------------------------------------------------------------------------
610 #------------------------------------------------------------------------
609 # Setup interactive session
611 # Setup interactive session
610
612
611 # Now we should be fully configured. We can then execute files or load
613 # 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.
614 # things only needed for interactive use. Then we'll open the shell.
613
615
614 # Take a snapshot of the user namespace before opening the shell. That way
616 # 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
617 # we'll be able to identify which things were interactively defined and
616 # which were defined through config files.
618 # which were defined through config files.
617 IP.user_config_ns = IP.user_ns.copy()
619 IP.user_config_ns = IP.user_ns.copy()
618
620
619 # Force reading a file as if it were a session log. Slower but safer.
621 # Force reading a file as if it were a session log. Slower but safer.
620 if load_logplay:
622 if load_logplay:
621 print 'Replaying log...'
623 print 'Replaying log...'
622 try:
624 try:
623 if IP_rc.debug:
625 if IP_rc.debug:
624 logplay_quiet = 0
626 logplay_quiet = 0
625 else:
627 else:
626 logplay_quiet = 1
628 logplay_quiet = 1
627
629
628 msg.logplay.trap_all()
630 msg.logplay.trap_all()
629 IP.safe_execfile(load_logplay,IP.user_ns,
631 IP.safe_execfile(load_logplay,IP.user_ns,
630 islog = 1, quiet = logplay_quiet)
632 islog = 1, quiet = logplay_quiet)
631 msg.logplay.release_all()
633 msg.logplay.release_all()
632 if IP_rc.messages:
634 if IP_rc.messages:
633 msg.summary += msg.logplay.summary_all()
635 msg.summary += msg.logplay.summary_all()
634 except:
636 except:
635 warn('Problems replaying logfile %s.' % load_logplay)
637 warn('Problems replaying logfile %s.' % load_logplay)
636 IP.InteractiveTB()
638 IP.InteractiveTB()
637
639
638 # Load remaining files in command line
640 # Load remaining files in command line
639 msg.user_exec.trap_all()
641 msg.user_exec.trap_all()
640
642
641 # Do NOT execute files named in the command line as scripts to be loaded
643 # 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
644 # by embedded instances. Doing so has the potential for an infinite
643 # recursion if there are exceptions thrown in the process.
645 # recursion if there are exceptions thrown in the process.
644
646
645 # XXX FIXME: the execution of user files should be moved out to after
647 # 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
648 # 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
649 # ipython prompt. This would also give them the benefit of ipython's
648 # nice tracebacks.
650 # nice tracebacks.
649
651
650 if not embedded and IP_rc.args:
652 if not embedded and IP_rc.args:
651 name_save = IP.user_ns['__name__']
653 name_save = IP.user_ns['__name__']
652 IP.user_ns['__name__'] = '__main__'
654 IP.user_ns['__name__'] = '__main__'
653 try:
655 try:
654 # Set our own excepthook in case the user code tries to call it
656 # Set our own excepthook in case the user code tries to call it
655 # directly. This prevents triggering the IPython crash handler.
657 # directly. This prevents triggering the IPython crash handler.
656 old_excepthook,sys.excepthook = sys.excepthook, IP.excepthook
658 old_excepthook,sys.excepthook = sys.excepthook, IP.excepthook
657 for run in args:
659 for run in args:
658 IP.safe_execfile(run,IP.user_ns)
660 IP.safe_execfile(run,IP.user_ns)
659 finally:
661 finally:
660 # Reset our crash handler in place
662 # Reset our crash handler in place
661 sys.excepthook = old_excepthook
663 sys.excepthook = old_excepthook
662
664
663 IP.user_ns['__name__'] = name_save
665 IP.user_ns['__name__'] = name_save
664
666
665 msg.user_exec.release_all()
667 msg.user_exec.release_all()
666 if IP_rc.messages:
668 if IP_rc.messages:
667 msg.summary += msg.user_exec.summary_all()
669 msg.summary += msg.user_exec.summary_all()
668
670
669 # since we can't specify a null string on the cmd line, 0 is the equivalent:
671 # since we can't specify a null string on the cmd line, 0 is the equivalent:
670 if IP_rc.nosep:
672 if IP_rc.nosep:
671 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
673 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
672 if IP_rc.separate_in == '0': IP_rc.separate_in = ''
674 if IP_rc.separate_in == '0': IP_rc.separate_in = ''
673 if IP_rc.separate_out == '0': IP_rc.separate_out = ''
675 if IP_rc.separate_out == '0': IP_rc.separate_out = ''
674 if IP_rc.separate_out2 == '0': IP_rc.separate_out2 = ''
676 if IP_rc.separate_out2 == '0': IP_rc.separate_out2 = ''
675 IP_rc.separate_in = IP_rc.separate_in.replace('\\n','\n')
677 IP_rc.separate_in = IP_rc.separate_in.replace('\\n','\n')
676 IP_rc.separate_out = IP_rc.separate_out.replace('\\n','\n')
678 IP_rc.separate_out = IP_rc.separate_out.replace('\\n','\n')
677 IP_rc.separate_out2 = IP_rc.separate_out2.replace('\\n','\n')
679 IP_rc.separate_out2 = IP_rc.separate_out2.replace('\\n','\n')
678
680
679 # Determine how many lines at the bottom of the screen are needed for
681 # 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
682 # showing prompts, so we can know wheter long strings are to be printed or
681 # paged:
683 # paged:
682 num_lines_bot = IP_rc.separate_in.count('\n')+1
684 num_lines_bot = IP_rc.separate_in.count('\n')+1
683 IP_rc.screen_length = IP_rc.screen_length - num_lines_bot
685 IP_rc.screen_length = IP_rc.screen_length - num_lines_bot
684 # Initialize cache, set in/out prompts and printing system
686 # Initialize cache, set in/out prompts and printing system
685 IP.outputcache = CachedOutput(IP_rc.cache_size,
687 IP.outputcache = CachedOutput(IP_rc.cache_size,
686 IP_rc.pprint,
688 IP_rc.pprint,
687 input_sep = IP_rc.separate_in,
689 input_sep = IP_rc.separate_in,
688 output_sep = IP_rc.separate_out,
690 output_sep = IP_rc.separate_out,
689 output_sep2 = IP_rc.separate_out2,
691 output_sep2 = IP_rc.separate_out2,
690 ps1 = IP_rc.prompt_in1,
692 ps1 = IP_rc.prompt_in1,
691 ps2 = IP_rc.prompt_in2,
693 ps2 = IP_rc.prompt_in2,
692 ps_out = IP_rc.prompt_out,
694 ps_out = IP_rc.prompt_out,
693 user_ns = IP.user_ns,
695 user_ns = IP.user_ns,
694 input_hist = IP.input_hist,
696 input_hist = IP.input_hist,
695 pad_left = IP_rc.prompts_pad_left)
697 pad_left = IP_rc.prompts_pad_left)
696
698
697 # user may have over-ridden the default print hook:
699 # user may have over-ridden the default print hook:
698 try:
700 try:
699 IP.outputcache.__class__.display = IP.hooks.display
701 IP.outputcache.__class__.display = IP.hooks.display
700 except AttributeError:
702 except AttributeError:
701 pass
703 pass
702
704
703 # Set calling of pdb on exceptions
705 # Set calling of pdb on exceptions
704 IP.InteractiveTB.call_pdb = IP_rc.pdb
706 IP.InteractiveTB.call_pdb = IP_rc.pdb
705
707
706 # I don't like assigning globally to sys, because it means when embedding
708 # I don't like assigning globally to sys, because it means when embedding
707 # instances, each embedded instance overrides the previous choice. But
709 # 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
710 # sys.displayhook seems to be called internally by exec, so I don't see a
709 # way around it.
711 # way around it.
710 sys.displayhook = IP.outputcache
712 sys.displayhook = IP.outputcache
711
713
712 # we need to know globally if we're caching i/o or not
714 # we need to know globally if we're caching i/o or not
713 IP.do_full_cache = IP.outputcache.do_full_cache
715 IP.do_full_cache = IP.outputcache.do_full_cache
714
716
715 # configure startup banner
717 # configure startup banner
716 if IP_rc.c: # regular python doesn't print the banner with -c
718 if IP_rc.c: # regular python doesn't print the banner with -c
717 IP_rc.banner = 0
719 IP_rc.banner = 0
718 if IP_rc.banner:
720 if IP_rc.banner:
719 BANN_P = IP.BANNER_PARTS
721 BANN_P = IP.BANNER_PARTS
720 else:
722 else:
721 BANN_P = []
723 BANN_P = []
722
724
723 if IP_rc.profile: BANN_P.append('IPython profile: %s\n' % IP_rc.profile)
725 if IP_rc.profile: BANN_P.append('IPython profile: %s\n' % IP_rc.profile)
724
726
725 # add message log (possibly empty)
727 # add message log (possibly empty)
726 if msg.summary: BANN_P.append(msg.summary)
728 if msg.summary: BANN_P.append(msg.summary)
727 # Final banner is a string
729 # Final banner is a string
728 IP.BANNER = '\n'.join(BANN_P)
730 IP.BANNER = '\n'.join(BANN_P)
729
731
730 # Finalize the IPython instance. This assumes the rc structure is fully
732 # Finalize the IPython instance. This assumes the rc structure is fully
731 # in place.
733 # in place.
732 IP.post_config_initialization()
734 IP.post_config_initialization()
733
735
734 return IP
736 return IP
735 #************************ end of file <ipmaker.py> **************************
737 #************************ end of file <ipmaker.py> **************************
@@ -1,586 +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 926 2005-12-01 18:14:21Z fperez $
9 # $Id: usage.py 960 2005-12-28 06:51:01Z 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]autoparens
160 -[no]autoedit_syntax
161 Make IPython automatically call any callable object even if you
161 When a syntax error occurs after editing a file, automatically
162 didn’t type explicit parentheses. For example, ’str 43’ becomes
162 open the file to the trouble causing line for convenient fixing.
163 ’str(43)’ automatically.
164
163
165 -[no]banner
164 -[no]banner
166 Print the intial information banner (default on).
165 Print the intial information banner (default on).
167
166
168 -c <command>
167 -c <command>
169 Execute the given command string, and set sys.argv to [’c’].
168 Execute the given command string, and set sys.argv to [’c’].
170 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-
171 preter.
170 preter.
172
171
173 -cache_size|cs <n>
172 -cache_size|cs <n>
174 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
175 memory). The default is 1000, you can change it permanently in
174 memory). The default is 1000, you can change it permanently in
176 your config file. Setting it to 0 completely disables the
175 your config file. Setting it to 0 completely disables the
177 caching system, and the minimum value accepted is 20 (if you
176 caching system, and the minimum value accepted is 20 (if you
178 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
179 issued). This limit is defined because otherwise you’ll spend
178 issued). This limit is defined because otherwise you’ll spend
180 more time re-flushing a too small cache than working.
179 more time re-flushing a too small cache than working.
181
180
182 -classic|cl
181 -classic|cl
183 Gives IPython a similar feel to the classic Python prompt.
182 Gives IPython a similar feel to the classic Python prompt.
184
183
185 -colors <scheme>
184 -colors <scheme>
186 Color scheme for prompts and exception reporting. Currently
185 Color scheme for prompts and exception reporting. Currently
187 implemented: NoColor, Linux, and LightBG.
186 implemented: NoColor, Linux, and LightBG.
188
187
189 -[no]color_info
188 -[no]color_info
190 IPython can display information about objects via a set of func-
189 IPython can display information about objects via a set of func-
191 tions, and optionally can use colors for this, syntax highlight-
190 tions, and optionally can use colors for this, syntax highlight-
192 ing source code and various other elements. However, because
191 ing source code and various other elements. However, because
193 this information is passed through a pager (like ’less’) and
192 this information is passed through a pager (like ’less’) and
194 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
195 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
196 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’
197 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
198 7.2 doesn’t.
197 7.2 doesn’t.
199
198
200 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.
201 The magic function @color_info allows you to toggle this inter-
200 The magic function @color_info allows you to toggle this inter-
202 actively for testing.
201 actively for testing.
203
202
204 -[no]confirm_exit
203 -[no]confirm_exit
205 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-
206 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
207 magic functions @Exit or @Quit you can force a direct exit,
206 magic functions @Exit or @Quit you can force a direct exit,
208 bypassing any confirmation.
207 bypassing any confirmation.
209
208
210 -[no]debug
209 -[no]debug
211 Show information about the loading process. Very useful to pin
210 Show information about the loading process. Very useful to pin
212 down problems with your configuration files or to get details
211 down problems with your configuration files or to get details
213 about session restores.
212 about session restores.
214
213
215 -[no]deep_reload
214 -[no]deep_reload
216 IPython can use the deep_reload module which reloads changes in
215 IPython can use the deep_reload module which reloads changes in
217 modules recursively (it replaces the reload() function, so you
216 modules recursively (it replaces the reload() function, so you
218 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
219 full reload of modules whose code may have changed, which the
218 full reload of modules whose code may have changed, which the
220 default reload() function does not.
219 default reload() function does not.
221
220
222 When deep_reload is off, IPython will use the normal reload(),
221 When deep_reload is off, IPython will use the normal reload(),
223 but deep_reload will still be available as dreload(). This fea-
222 but deep_reload will still be available as dreload(). This fea-
224 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
225 reload() and dreload()].
224 reload() and dreload()].
226
225
227 -editor <name>
226 -editor <name>
228 Which editor to use with the @edit command. By default, IPython
227 Which editor to use with the @edit command. By default, IPython
229 will honor your EDITOR environment variable (if not set, vi is
228 will honor your EDITOR environment variable (if not set, vi is
230 the Unix default and notepad the Windows one). Since this editor
229 the Unix default and notepad the Windows one). Since this editor
231 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
232 code snippets, you may want to use a small, lightweight editor
231 code snippets, you may want to use a small, lightweight editor
233 here (in case your default EDITOR is something like Emacs).
232 here (in case your default EDITOR is something like Emacs).
234
233
235 -ipythondir <name>
234 -ipythondir <name>
236 The name of your IPython configuration directory IPYTHONDIR.
235 The name of your IPython configuration directory IPYTHONDIR.
237 This can also be specified through the environment variable
236 This can also be specified through the environment variable
238 IPYTHONDIR.
237 IPYTHONDIR.
239
238
240 -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 ipython.log
241 in your current directory (which prevents logs from multiple
240 in your current directory (which prevents logs from multiple
242 IPython sessions from trampling each other). You can use this to
241 IPython sessions from trampling each other). You can use this to
243 later restore a session by loading your logfile as a file to be
242 later restore a session by loading your logfile as a file to be
244 executed with option -logplay (see below).
243 executed with option -logplay (see below).
245
244
246 -logfile|lf
245 -logfile|lf
247 Specifu the name of your logfile.
246 Specifu the name of your logfile.
248
247
249 -logplay|lp
248 -logplay|lp
250 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-
251 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
252 run the logfile). With -logplay, IPython will try to reconstruct
251 run the logfile). With -logplay, IPython will try to reconstruct
253 the previous working environment in full, not just execute the
252 the previous working environment in full, not just execute the
254 commands in the logfile.
253 commands in the logfile.
255 When a session is restored, logging is automatically turned on
254 When a session is restored, logging is automatically turned on
256 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
257 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
258 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
259 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
260 from the beginning every time.
259 from the beginning every time.
261
260
262 Caveats: there are limitations in this option. The history vari-
261 Caveats: there are limitations in this option. The history vari-
263 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
264 we will try to implement full session saving by writing and
263 we will try to implement full session saving by writing and
265 retrieving a failed because of inherent limitations of Python’s
264 retrieving a failed because of inherent limitations of Python’s
266 Pickle module, so this may have to wait.
265 Pickle module, so this may have to wait.
267
266
268 -[no]messages
267 -[no]messages
269 Print messages which IPython collects about its startup process
268 Print messages which IPython collects about its startup process
270 (default on).
269 (default on).
271
270
272 -[no]pdb
271 -[no]pdb
273 Automatically call the pdb debugger after every uncaught excep-
272 Automatically call the pdb debugger after every uncaught excep-
274 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
275 automatically inside of it after any call (either in IPython or
274 automatically inside of it after any call (either in IPython or
276 in code called by it) which triggers an exception which goes
275 in code called by it) which triggers an exception which goes
277 uncaught.
276 uncaught.
278
277
279 -[no]pprint
278 -[no]pprint
280 IPython can optionally use the pprint (pretty printer) module
279 IPython can optionally use the pprint (pretty printer) module
281 for displaying results. pprint tends to give a nicer display of
280 for displaying results. pprint tends to give a nicer display of
282 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-
283 manently in your config file (default off).
282 manently in your config file (default off).
284
283
285 -profile|p <name>
284 -profile|p <name>
286 Assume that your config file is ipythonrc-<name> (looks in cur-
285 Assume that your config file is ipythonrc-<name> (looks in cur-
287 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
288 and load multiple config files for different tasks, especially
287 and load multiple config files for different tasks, especially
289 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
290 basic IPYTHONDIR/ipythonrc file and then have other ’profiles’
289 basic IPYTHONDIR/ipythonrc file and then have other ’profiles’
291 which include this one and load extra things for particular
290 which include this one and load extra things for particular
292 tasks. For example:
291 tasks. For example:
293
292
294 1) $HOME/.ipython/ipythonrc : load basic things you always want.
293 1) $HOME/.ipython/ipythonrc : load basic things you always want.
295 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-
294 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-
296 related modules.
295 related modules.
297 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
296 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
298 plotting modules.
297 plotting modules.
299
298
300 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-
301 lar file inclusions, IPython will stop if it reaches 15 recur-
300 lar file inclusions, IPython will stop if it reaches 15 recur-
302 sive inclusions.
301 sive inclusions.
303
302
304 -prompt_in1|pi1 <string>
303 -prompt_in1|pi1 <string>
305 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
306 using numbered prompts, the number is represented with a ’\#’ in
305 using numbered prompts, the number is represented with a ’\#’ in
307 the string. Don’t forget to quote strings with spaces embedded
306 the string. Don’t forget to quote strings with spaces embedded
308 in them. Default: ’In [\#]:’.
307 in them. Default: ’In [\#]:’.
309
308
310 Most bash-like escapes can be used to customize IPython’s
309 Most bash-like escapes can be used to customize IPython’s
311 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-
312 cific. All valid prompt escapes are described in detail in the
311 cific. All valid prompt escapes are described in detail in the
313 Customization section of the IPython HTML/PDF manual.
312 Customization section of the IPython HTML/PDF manual.
314
313
315 -prompt_in2|pi2 <string>
314 -prompt_in2|pi2 <string>
316 Similar to the previous option, but used for the continuation
315 Similar to the previous option, but used for the continuation
317 prompts. The special sequence ’\D’ is similar to ’\#’, but with
316 prompts. The special sequence ’\D’ is similar to ’\#’, but with
318 all digits replaced dots (so you can have your continuation
317 all digits replaced dots (so you can have your continuation
319 prompt aligned with your input prompt). Default: ’ .\D.:’
318 prompt aligned with your input prompt). Default: ’ .\D.:’
320 (note three spaces at the start for alignment with ’In [\#]’).
319 (note three spaces at the start for alignment with ’In [\#]’).
321
320
322 -prompt_out|po <string>
321 -prompt_out|po <string>
323 String used for output prompts, also uses numbers like
322 String used for output prompts, also uses numbers like
324 prompt_in1. Default: ’Out[\#]:’.
323 prompt_in1. Default: ’Out[\#]:’.
325
324
326 -quick Start in bare bones mode (no config file loaded).
325 -quick Start in bare bones mode (no config file loaded).
327
326
328 -rcfile <name>
327 -rcfile <name>
329 Name of your IPython resource configuration file. normally
328 Name of your IPython resource configuration file. normally
330 IPython loads ipythonrc (from current directory) or
329 IPython loads ipythonrc (from current directory) or
331 IPYTHONDIR/ipythonrc. If the loading of your config file fails,
330 IPYTHONDIR/ipythonrc. If the loading of your config file fails,
332 IPython starts with a bare bones configuration (no modules
331 IPython starts with a bare bones configuration (no modules
333 loaded at all).
332 loaded at all).
334
333
335 -[no]readline
334 -[no]readline
336 Use the readline library, which is needed to support name com-
335 Use the readline library, which is needed to support name com-
337 pletion and command history, among other things. It is enabled
336 pletion and command history, among other things. It is enabled
338 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
339 Python comint or shell buffers.
338 Python comint or shell buffers.
340
339
341 Note that emacs ’eterm’ buffers (opened with M-x term) support
340 Note that emacs ’eterm’ buffers (opened with M-x term) support
342 IPython’s readline and syntax coloring fine, only ’emacs’ (M-x
341 IPython’s readline and syntax coloring fine, only ’emacs’ (M-x
343 shell and C-c !) buffers do not.
342 shell and C-c !) buffers do not.
344
343
345 -screen_length|sl <n>
344 -screen_length|sl <n>
346 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-
347 ing of very long strings. Strings longer than this number of
346 ing of very long strings. Strings longer than this number of
348 lines will be sent through a pager instead of directly printed.
347 lines will be sent through a pager instead of directly printed.
349
348
350 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-
351 detect your screen size every time it needs to print certain
350 detect your screen size every time it needs to print certain
352 potentially long strings (this doesn’t change the behavior of
351 potentially long strings (this doesn’t change the behavior of
353 the ’print’ keyword, it’s only triggered internally). If for
352 the ’print’ keyword, it’s only triggered internally). If for
354 some reason this isn’t working well (it needs curses support),
353 some reason this isn’t working well (it needs curses support),
355 specify it yourself. Otherwise don’t change the default.
354 specify it yourself. Otherwise don’t change the default.
356
355
357 -separate_in|si <string>
356 -separate_in|si <string>
358 Separator before input prompts. Default ’0.
357 Separator before input prompts. Default ’0.
359
358
360 -separate_out|so <string>
359 -separate_out|so <string>
361 Separator before output prompts. Default: 0 (nothing).
360 Separator before output prompts. Default: 0 (nothing).
362
361
363 -separate_out2|so2 <string>
362 -separate_out2|so2 <string>
364 Separator after output prompts. Default: 0 (nothing).
363 Separator after output prompts. Default: 0 (nothing).
365
364
366 -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’.
367 Simply removes all input/output separators.
366 Simply removes all input/output separators.
368
367
369 -upgrade
368 -upgrade
370 Allows you to upgrade your IPYTHONDIR configuration when you
369 Allows you to upgrade your IPYTHONDIR configuration when you
371 install a new version of IPython. Since new versions may
370 install a new version of IPython. Since new versions may
372 include new command lines options or example files, this copies
371 include new command lines options or example files, this copies
373 updated ipythonrc-type files. However, it backs up (with a .old
372 updated ipythonrc-type files. However, it backs up (with a .old
374 extension) all files which it overwrites so that you can merge
373 extension) all files which it overwrites so that you can merge
375 back any custimizations you might have in your personal files.
374 back any custimizations you might have in your personal files.
376
375
377 -Version
376 -Version
378 Print version information and exit.
377 Print version information and exit.
379
378
380 -xmode <modename>
379 -xmode <modename>
381 Mode for exception reporting. The valid modes are Plain, Con-
380 Mode for exception reporting. The valid modes are Plain, Con-
382 text, and Verbose.
381 text, and Verbose.
383
382
384 - Plain: similar to python’s normal traceback printing.
383 - Plain: similar to python’s normal traceback printing.
385
384
386 - Context: prints 5 lines of context source code around each
385 - Context: prints 5 lines of context source code around each
387 line in the traceback.
386 line in the traceback.
388
387
389 - Verbose: similar to Context, but additionally prints the vari-
388 - Verbose: similar to Context, but additionally prints the vari-
390 ables currently visible where the exception happened (shortening
389 ables currently visible where the exception happened (shortening
391 their strings if too long). This can potentially be very slow,
390 their strings if too long). This can potentially be very slow,
392 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-
393 sentation is complex to compute. Your computer may appear to
392 sentation is complex to compute. Your computer may appear to
394 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
395 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
396 once).
395 once).
397
396
398
397
399 EMBEDDING
398 EMBEDDING
400 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-
401 grams. In the documentation example files there are some illustrations
400 grams. In the documentation example files there are some illustrations
402 on how to do this.
401 on how to do this.
403
402
404 This feature allows you to evalutate dynamically the state of your
403 This feature allows you to evalutate dynamically the state of your
405 code, operate with your variables, analyze them, etc. Note however
404 code, operate with your variables, analyze them, etc. Note however
406 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
407 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
408 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.
409 """
408 """
410
409
411 cmd_line_usage = __doc__
410 cmd_line_usage = __doc__
412
411
413 #---------------------------------------------------------------------------
412 #---------------------------------------------------------------------------
414 interactive_usage = """
413 interactive_usage = """
415 IPython -- An enhanced Interactive Python
414 IPython -- An enhanced Interactive Python
416 =========================================
415 =========================================
417
416
418 IPython offers a combination of convenient shell features, special commands
417 IPython offers a combination of convenient shell features, special commands
419 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
420 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
421 replacement for the standard Python interpreter, while offering vastly
420 replacement for the standard Python interpreter, while offering vastly
422 improved functionality and flexibility.
421 improved functionality and flexibility.
423
422
424 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
425 options available. This document only describes interactive features.
424 options available. This document only describes interactive features.
426
425
427 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
428 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
429 will quickly occur.
428 will quickly occur.
430
429
431 MAIN FEATURES
430 MAIN FEATURES
432
431
433 * 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
434 available with access to object docstrings and the Python manuals. Simply
433 available with access to object docstrings and the Python manuals. Simply
435 type 'help' (no quotes) to access it.
434 type 'help' (no quotes) to access it.
436
435
437 * Magic commands: type %magic for information on the magic subsystem.
436 * Magic commands: type %magic for information on the magic subsystem.
438
437
439 * 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.
440
439
441 * Dynamic object information:
440 * Dynamic object information:
442
441
443 Typing ?word or word? prints detailed information about an object. If
442 Typing ?word or word? prints detailed information about an object. If
444 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
445 snipped in the center for brevity.
444 snipped in the center for brevity.
446
445
447 Typing ??word or word?? gives access to the full information without
446 Typing ??word or word?? gives access to the full information without
448 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
449 pager if longer than the screen, printed otherwise.
448 pager if longer than the screen, printed otherwise.
450
449
451 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
452 available), shows function prototypes and other useful information.
451 available), shows function prototypes and other useful information.
453
452
454 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
455 quotes, and without % if you have automagic on).
454 quotes, and without % if you have automagic on).
456
455
457 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
458 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,
459 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
460 similarly.
459 similarly.
461
460
462 * Completion in the local namespace, by typing TAB at the prompt.
461 * Completion in the local namespace, by typing TAB at the prompt.
463
462
464 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
465 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
466 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.
467
466
468 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
469 if your Python lacks readline support (such as under Windows).
468 if your Python lacks readline support (such as under Windows).
470
469
471 * Search previous command history in two ways (also requires readline):
470 * Search previous command history in two ways (also requires readline):
472
471
473 - 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
474 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
475 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
476 normal arrow keys.
475 normal arrow keys.
477
476
478 - 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
479 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
480 much as it can.
479 much as it can.
481
480
482 * Persistent command history across sessions (readline required).
481 * Persistent command history across sessions (readline required).
483
482
484 * 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.
485
484
486 * 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.
487
486
488 * 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
489 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.
490
489
491 * Verbose and colored exception traceback printouts. See the magic xmode and
490 * Verbose and colored exception traceback printouts. See the magic xmode and
492 xcolor functions for details (just type %magic).
491 xcolor functions for details (just type %magic).
493
492
494 * Input caching system:
493 * Input caching system:
495
494
496 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
497 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
498 key recall).
497 key recall).
499
498
500 The following GLOBAL variables always exist (so don't overwrite them!):
499 The following GLOBAL variables always exist (so don't overwrite them!):
501 _i: stores previous input.
500 _i: stores previous input.
502 _ii: next previous.
501 _ii: next previous.
503 _iii: next-next previous.
502 _iii: next-next previous.
504 _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.
505
504
506 Additionally, global variables named _i<n> are dynamically created (<n>
505 Additionally, global variables named _i<n> are dynamically created (<n>
507 being the prompt counter), such that _i<n> == _ih[<n>]
506 being the prompt counter), such that _i<n> == _ih[<n>]
508
507
509 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].
510
509
511 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,
512 for later re-execution, with the %macro function.
511 for later re-execution, with the %macro function.
513
512
514 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
515 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
516 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
517 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.
518
517
519 * Output caching system:
518 * Output caching system:
520
519
521 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
522 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
523 (NOT assignments, for example) are cached. If you are familiar with
522 (NOT assignments, for example) are cached. If you are familiar with
524 Mathematica, IPython's _ variables behave exactly like Mathematica's %
523 Mathematica, IPython's _ variables behave exactly like Mathematica's %
525 variables.
524 variables.
526
525
527 The following GLOBAL variables always exist (so don't overwrite them!):
526 The following GLOBAL variables always exist (so don't overwrite them!):
528 _ (one underscore): previous output.
527 _ (one underscore): previous output.
529 __ (two underscores): next previous.
528 __ (two underscores): next previous.
530 ___ (three underscores): next-next previous.
529 ___ (three underscores): next-next previous.
531
530
532 Global variables named _<n> are dynamically created (<n> being the prompt
531 Global variables named _<n> are dynamically created (<n> being the prompt
533 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>.
534
533
535 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
536 which generated output.
535 which generated output.
537
536
538 * Directory history:
537 * Directory history:
539
538
540 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
541 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.
542
541
543 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
542 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
544
543
545 1. Auto-parentheses
544 1. Auto-parentheses
546 Callable objects (i.e. functions, methods, etc) can be invoked like
545 Callable objects (i.e. functions, methods, etc) can be invoked like
547 this (notice the commas between the arguments):
546 this (notice the commas between the arguments):
548 >>> callable_ob arg1, arg2, arg3
547 >>> callable_ob arg1, arg2, arg3
549 and the input will be translated to this:
548 and the input will be translated to this:
550 --> callable_ob(arg1, arg2, arg3)
549 --> callable_ob(arg1, arg2, arg3)
551 You can force auto-parentheses by using '/' as the first character
550 You can force auto-parentheses by using '/' as the first character
552 of a line. For example:
551 of a line. For example:
553 >>> /globals # becomes 'globals()'
552 >>> /globals # becomes 'globals()'
554 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
555 won't work:
554 won't work:
556 >>> print /globals # syntax error
555 >>> print /globals # syntax error
557
556
558 In most cases the automatic algorithm should work, so you should
557 In most cases the automatic algorithm should work, so you should
559 rarely need to explicitly invoke /. One notable exception is if you
558 rarely need to explicitly invoke /. One notable exception is if you
560 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
561 parenthesis will confuse IPython):
560 parenthesis will confuse IPython):
562 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
563 but this will work:
562 but this will work:
564 In [2]: /zip (1,2,3),(4,5,6)
563 In [2]: /zip (1,2,3),(4,5,6)
565 ------> zip ((1,2,3),(4,5,6))
564 ------> zip ((1,2,3),(4,5,6))
566 Out[2]= [(1, 4), (2, 5), (3, 6)]
565 Out[2]= [(1, 4), (2, 5), (3, 6)]
567
566
568 IPython tells you that it has altered your command line by
567 IPython tells you that it has altered your command line by
569 displaying the new command line preceded by -->. e.g.:
568 displaying the new command line preceded by -->. e.g.:
570 In [18]: callable list
569 In [18]: callable list
571 -------> callable (list)
570 -------> callable (list)
572
571
573 2. Auto-Quoting
572 2. Auto-Quoting
574 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
575 the first character of a line. For example:
574 the first character of a line. For example:
576 >>> ,my_function /home/me # becomes my_function("/home/me")
575 >>> ,my_function /home/me # becomes my_function("/home/me")
577
576
578 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
579 string (while ',' splits on whitespace):
578 string (while ',' splits on whitespace):
580 >>> ,my_function a b c # becomes my_function("a","b","c")
579 >>> ,my_function a b c # becomes my_function("a","b","c")
581 >>> ;my_function a b c # becomes my_function("a b c")
580 >>> ;my_function a b c # becomes my_function("a b c")
582
581
583 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
584 won't work:
583 won't work:
585 >>> x = ,my_function /home/me # syntax error
584 >>> x = ,my_function /home/me # syntax error
586 """
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 NO CONTENT: modified file
NO CONTENT: modified file
The requested commit or file is too big and content was truncated. Show full diff
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