##// END OF EJS Templates
All platutils modules to utils, moved tests and updated imports.
Brian Granger -
Show More
@@ -1,3457 +1,3457 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Magic functions for InteractiveShell.
2 """Magic functions for InteractiveShell.
3 """
3 """
4
4
5 #*****************************************************************************
5 #*****************************************************************************
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #*****************************************************************************
11 #*****************************************************************************
12
12
13 #****************************************************************************
13 #****************************************************************************
14 # Modules and globals
14 # Modules and globals
15
15
16 # Python standard modules
16 # Python standard modules
17 import __builtin__
17 import __builtin__
18 import bdb
18 import bdb
19 import inspect
19 import inspect
20 import os
20 import os
21 import pdb
21 import pdb
22 import pydoc
22 import pydoc
23 import sys
23 import sys
24 import re
24 import re
25 import tempfile
25 import tempfile
26 import time
26 import time
27 import cPickle as pickle
27 import cPickle as pickle
28 import textwrap
28 import textwrap
29 from cStringIO import StringIO
29 from cStringIO import StringIO
30 from getopt import getopt,GetoptError
30 from getopt import getopt,GetoptError
31 from pprint import pprint, pformat
31 from pprint import pprint, pformat
32
32
33 # cProfile was added in Python2.5
33 # cProfile was added in Python2.5
34 try:
34 try:
35 import cProfile as profile
35 import cProfile as profile
36 import pstats
36 import pstats
37 except ImportError:
37 except ImportError:
38 # profile isn't bundled by default in Debian for license reasons
38 # profile isn't bundled by default in Debian for license reasons
39 try:
39 try:
40 import profile,pstats
40 import profile,pstats
41 except ImportError:
41 except ImportError:
42 profile = pstats = None
42 profile = pstats = None
43
43
44 # Homebrewed
44 # Homebrewed
45 import IPython
45 import IPython
46 from IPython import wildcard
46 from IPython import wildcard
47 from IPython.core import debugger, oinspect
47 from IPython.core import debugger, oinspect
48 from IPython.core.fakemodule import FakeModule
48 from IPython.core.fakemodule import FakeModule
49 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
49 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
50 from IPython.PyColorize import Parser
50 from IPython.PyColorize import Parser
51 from IPython.utils.ipstruct import Struct
51 from IPython.utils.ipstruct import Struct
52 from IPython.core.macro import Macro
52 from IPython.core.macro import Macro
53 from IPython.utils.genutils import *
53 from IPython.utils.genutils import *
54 from IPython import platutils
54 from IPython.utils import platutils
55 import IPython.utils.generics
55 import IPython.utils.generics
56 from IPython.core import ipapi
56 from IPython.core import ipapi
57 from IPython.core.ipapi import UsageError
57 from IPython.core.ipapi import UsageError
58 from IPython.testing import decorators as testdec
58 from IPython.testing import decorators as testdec
59
59
60 #***************************************************************************
60 #***************************************************************************
61 # Utility functions
61 # Utility functions
62 def on_off(tag):
62 def on_off(tag):
63 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
63 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
64 return ['OFF','ON'][tag]
64 return ['OFF','ON'][tag]
65
65
66 class Bunch: pass
66 class Bunch: pass
67
67
68 def compress_dhist(dh):
68 def compress_dhist(dh):
69 head, tail = dh[:-10], dh[-10:]
69 head, tail = dh[:-10], dh[-10:]
70
70
71 newhead = []
71 newhead = []
72 done = set()
72 done = set()
73 for h in head:
73 for h in head:
74 if h in done:
74 if h in done:
75 continue
75 continue
76 newhead.append(h)
76 newhead.append(h)
77 done.add(h)
77 done.add(h)
78
78
79 return newhead + tail
79 return newhead + tail
80
80
81
81
82 #***************************************************************************
82 #***************************************************************************
83 # Main class implementing Magic functionality
83 # Main class implementing Magic functionality
84 class Magic:
84 class Magic:
85 """Magic functions for InteractiveShell.
85 """Magic functions for InteractiveShell.
86
86
87 Shell functions which can be reached as %function_name. All magic
87 Shell functions which can be reached as %function_name. All magic
88 functions should accept a string, which they can parse for their own
88 functions should accept a string, which they can parse for their own
89 needs. This can make some functions easier to type, eg `%cd ../`
89 needs. This can make some functions easier to type, eg `%cd ../`
90 vs. `%cd("../")`
90 vs. `%cd("../")`
91
91
92 ALL definitions MUST begin with the prefix magic_. The user won't need it
92 ALL definitions MUST begin with the prefix magic_. The user won't need it
93 at the command line, but it is is needed in the definition. """
93 at the command line, but it is is needed in the definition. """
94
94
95 # class globals
95 # class globals
96 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
96 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
97 'Automagic is ON, % prefix NOT needed for magic functions.']
97 'Automagic is ON, % prefix NOT needed for magic functions.']
98
98
99 #......................................................................
99 #......................................................................
100 # some utility functions
100 # some utility functions
101
101
102 def __init__(self,shell):
102 def __init__(self,shell):
103
103
104 self.options_table = {}
104 self.options_table = {}
105 if profile is None:
105 if profile is None:
106 self.magic_prun = self.profile_missing_notice
106 self.magic_prun = self.profile_missing_notice
107 self.shell = shell
107 self.shell = shell
108
108
109 # namespace for holding state we may need
109 # namespace for holding state we may need
110 self._magic_state = Bunch()
110 self._magic_state = Bunch()
111
111
112 def profile_missing_notice(self, *args, **kwargs):
112 def profile_missing_notice(self, *args, **kwargs):
113 error("""\
113 error("""\
114 The profile module could not be found. It has been removed from the standard
114 The profile module could not be found. It has been removed from the standard
115 python packages because of its non-free license. To use profiling, install the
115 python packages because of its non-free license. To use profiling, install the
116 python-profiler package from non-free.""")
116 python-profiler package from non-free.""")
117
117
118 def default_option(self,fn,optstr):
118 def default_option(self,fn,optstr):
119 """Make an entry in the options_table for fn, with value optstr"""
119 """Make an entry in the options_table for fn, with value optstr"""
120
120
121 if fn not in self.lsmagic():
121 if fn not in self.lsmagic():
122 error("%s is not a magic function" % fn)
122 error("%s is not a magic function" % fn)
123 self.options_table[fn] = optstr
123 self.options_table[fn] = optstr
124
124
125 def lsmagic(self):
125 def lsmagic(self):
126 """Return a list of currently available magic functions.
126 """Return a list of currently available magic functions.
127
127
128 Gives a list of the bare names after mangling (['ls','cd', ...], not
128 Gives a list of the bare names after mangling (['ls','cd', ...], not
129 ['magic_ls','magic_cd',...]"""
129 ['magic_ls','magic_cd',...]"""
130
130
131 # FIXME. This needs a cleanup, in the way the magics list is built.
131 # FIXME. This needs a cleanup, in the way the magics list is built.
132
132
133 # magics in class definition
133 # magics in class definition
134 class_magic = lambda fn: fn.startswith('magic_') and \
134 class_magic = lambda fn: fn.startswith('magic_') and \
135 callable(Magic.__dict__[fn])
135 callable(Magic.__dict__[fn])
136 # in instance namespace (run-time user additions)
136 # in instance namespace (run-time user additions)
137 inst_magic = lambda fn: fn.startswith('magic_') and \
137 inst_magic = lambda fn: fn.startswith('magic_') and \
138 callable(self.__dict__[fn])
138 callable(self.__dict__[fn])
139 # and bound magics by user (so they can access self):
139 # and bound magics by user (so they can access self):
140 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
140 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
141 callable(self.__class__.__dict__[fn])
141 callable(self.__class__.__dict__[fn])
142 magics = filter(class_magic,Magic.__dict__.keys()) + \
142 magics = filter(class_magic,Magic.__dict__.keys()) + \
143 filter(inst_magic,self.__dict__.keys()) + \
143 filter(inst_magic,self.__dict__.keys()) + \
144 filter(inst_bound_magic,self.__class__.__dict__.keys())
144 filter(inst_bound_magic,self.__class__.__dict__.keys())
145 out = []
145 out = []
146 for fn in set(magics):
146 for fn in set(magics):
147 out.append(fn.replace('magic_','',1))
147 out.append(fn.replace('magic_','',1))
148 out.sort()
148 out.sort()
149 return out
149 return out
150
150
151 def extract_input_slices(self,slices,raw=False):
151 def extract_input_slices(self,slices,raw=False):
152 """Return as a string a set of input history slices.
152 """Return as a string a set of input history slices.
153
153
154 Inputs:
154 Inputs:
155
155
156 - slices: the set of slices is given as a list of strings (like
156 - slices: the set of slices is given as a list of strings (like
157 ['1','4:8','9'], since this function is for use by magic functions
157 ['1','4:8','9'], since this function is for use by magic functions
158 which get their arguments as strings.
158 which get their arguments as strings.
159
159
160 Optional inputs:
160 Optional inputs:
161
161
162 - raw(False): by default, the processed input is used. If this is
162 - raw(False): by default, the processed input is used. If this is
163 true, the raw input history is used instead.
163 true, the raw input history is used instead.
164
164
165 Note that slices can be called with two notations:
165 Note that slices can be called with two notations:
166
166
167 N:M -> standard python form, means including items N...(M-1).
167 N:M -> standard python form, means including items N...(M-1).
168
168
169 N-M -> include items N..M (closed endpoint)."""
169 N-M -> include items N..M (closed endpoint)."""
170
170
171 if raw:
171 if raw:
172 hist = self.shell.input_hist_raw
172 hist = self.shell.input_hist_raw
173 else:
173 else:
174 hist = self.shell.input_hist
174 hist = self.shell.input_hist
175
175
176 cmds = []
176 cmds = []
177 for chunk in slices:
177 for chunk in slices:
178 if ':' in chunk:
178 if ':' in chunk:
179 ini,fin = map(int,chunk.split(':'))
179 ini,fin = map(int,chunk.split(':'))
180 elif '-' in chunk:
180 elif '-' in chunk:
181 ini,fin = map(int,chunk.split('-'))
181 ini,fin = map(int,chunk.split('-'))
182 fin += 1
182 fin += 1
183 else:
183 else:
184 ini = int(chunk)
184 ini = int(chunk)
185 fin = ini+1
185 fin = ini+1
186 cmds.append(hist[ini:fin])
186 cmds.append(hist[ini:fin])
187 return cmds
187 return cmds
188
188
189 def _ofind(self, oname, namespaces=None):
189 def _ofind(self, oname, namespaces=None):
190 """Find an object in the available namespaces.
190 """Find an object in the available namespaces.
191
191
192 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
192 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
193
193
194 Has special code to detect magic functions.
194 Has special code to detect magic functions.
195 """
195 """
196
196
197 oname = oname.strip()
197 oname = oname.strip()
198
198
199 alias_ns = None
199 alias_ns = None
200 if namespaces is None:
200 if namespaces is None:
201 # Namespaces to search in:
201 # Namespaces to search in:
202 # Put them in a list. The order is important so that we
202 # Put them in a list. The order is important so that we
203 # find things in the same order that Python finds them.
203 # find things in the same order that Python finds them.
204 namespaces = [ ('Interactive', self.shell.user_ns),
204 namespaces = [ ('Interactive', self.shell.user_ns),
205 ('IPython internal', self.shell.internal_ns),
205 ('IPython internal', self.shell.internal_ns),
206 ('Python builtin', __builtin__.__dict__),
206 ('Python builtin', __builtin__.__dict__),
207 ('Alias', self.shell.alias_table),
207 ('Alias', self.shell.alias_table),
208 ]
208 ]
209 alias_ns = self.shell.alias_table
209 alias_ns = self.shell.alias_table
210
210
211 # initialize results to 'null'
211 # initialize results to 'null'
212 found = 0; obj = None; ospace = None; ds = None;
212 found = 0; obj = None; ospace = None; ds = None;
213 ismagic = 0; isalias = 0; parent = None
213 ismagic = 0; isalias = 0; parent = None
214
214
215 # Look for the given name by splitting it in parts. If the head is
215 # Look for the given name by splitting it in parts. If the head is
216 # found, then we look for all the remaining parts as members, and only
216 # found, then we look for all the remaining parts as members, and only
217 # declare success if we can find them all.
217 # declare success if we can find them all.
218 oname_parts = oname.split('.')
218 oname_parts = oname.split('.')
219 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
219 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
220 for nsname,ns in namespaces:
220 for nsname,ns in namespaces:
221 try:
221 try:
222 obj = ns[oname_head]
222 obj = ns[oname_head]
223 except KeyError:
223 except KeyError:
224 continue
224 continue
225 else:
225 else:
226 #print 'oname_rest:', oname_rest # dbg
226 #print 'oname_rest:', oname_rest # dbg
227 for part in oname_rest:
227 for part in oname_rest:
228 try:
228 try:
229 parent = obj
229 parent = obj
230 obj = getattr(obj,part)
230 obj = getattr(obj,part)
231 except:
231 except:
232 # Blanket except b/c some badly implemented objects
232 # Blanket except b/c some badly implemented objects
233 # allow __getattr__ to raise exceptions other than
233 # allow __getattr__ to raise exceptions other than
234 # AttributeError, which then crashes IPython.
234 # AttributeError, which then crashes IPython.
235 break
235 break
236 else:
236 else:
237 # If we finish the for loop (no break), we got all members
237 # If we finish the for loop (no break), we got all members
238 found = 1
238 found = 1
239 ospace = nsname
239 ospace = nsname
240 if ns == alias_ns:
240 if ns == alias_ns:
241 isalias = 1
241 isalias = 1
242 break # namespace loop
242 break # namespace loop
243
243
244 # Try to see if it's magic
244 # Try to see if it's magic
245 if not found:
245 if not found:
246 if oname.startswith(self.shell.ESC_MAGIC):
246 if oname.startswith(self.shell.ESC_MAGIC):
247 oname = oname[1:]
247 oname = oname[1:]
248 obj = getattr(self,'magic_'+oname,None)
248 obj = getattr(self,'magic_'+oname,None)
249 if obj is not None:
249 if obj is not None:
250 found = 1
250 found = 1
251 ospace = 'IPython internal'
251 ospace = 'IPython internal'
252 ismagic = 1
252 ismagic = 1
253
253
254 # Last try: special-case some literals like '', [], {}, etc:
254 # Last try: special-case some literals like '', [], {}, etc:
255 if not found and oname_head in ["''",'""','[]','{}','()']:
255 if not found and oname_head in ["''",'""','[]','{}','()']:
256 obj = eval(oname_head)
256 obj = eval(oname_head)
257 found = 1
257 found = 1
258 ospace = 'Interactive'
258 ospace = 'Interactive'
259
259
260 return {'found':found, 'obj':obj, 'namespace':ospace,
260 return {'found':found, 'obj':obj, 'namespace':ospace,
261 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
261 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
262
262
263 def arg_err(self,func):
263 def arg_err(self,func):
264 """Print docstring if incorrect arguments were passed"""
264 """Print docstring if incorrect arguments were passed"""
265 print 'Error in arguments:'
265 print 'Error in arguments:'
266 print OInspect.getdoc(func)
266 print OInspect.getdoc(func)
267
267
268 def format_latex(self,strng):
268 def format_latex(self,strng):
269 """Format a string for latex inclusion."""
269 """Format a string for latex inclusion."""
270
270
271 # Characters that need to be escaped for latex:
271 # Characters that need to be escaped for latex:
272 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
272 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
273 # Magic command names as headers:
273 # Magic command names as headers:
274 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
274 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
275 re.MULTILINE)
275 re.MULTILINE)
276 # Magic commands
276 # Magic commands
277 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
277 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
278 re.MULTILINE)
278 re.MULTILINE)
279 # Paragraph continue
279 # Paragraph continue
280 par_re = re.compile(r'\\$',re.MULTILINE)
280 par_re = re.compile(r'\\$',re.MULTILINE)
281
281
282 # The "\n" symbol
282 # The "\n" symbol
283 newline_re = re.compile(r'\\n')
283 newline_re = re.compile(r'\\n')
284
284
285 # Now build the string for output:
285 # Now build the string for output:
286 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
286 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
287 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
287 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
288 strng)
288 strng)
289 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
289 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
290 strng = par_re.sub(r'\\\\',strng)
290 strng = par_re.sub(r'\\\\',strng)
291 strng = escape_re.sub(r'\\\1',strng)
291 strng = escape_re.sub(r'\\\1',strng)
292 strng = newline_re.sub(r'\\textbackslash{}n',strng)
292 strng = newline_re.sub(r'\\textbackslash{}n',strng)
293 return strng
293 return strng
294
294
295 def format_screen(self,strng):
295 def format_screen(self,strng):
296 """Format a string for screen printing.
296 """Format a string for screen printing.
297
297
298 This removes some latex-type format codes."""
298 This removes some latex-type format codes."""
299 # Paragraph continue
299 # Paragraph continue
300 par_re = re.compile(r'\\$',re.MULTILINE)
300 par_re = re.compile(r'\\$',re.MULTILINE)
301 strng = par_re.sub('',strng)
301 strng = par_re.sub('',strng)
302 return strng
302 return strng
303
303
304 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
304 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
305 """Parse options passed to an argument string.
305 """Parse options passed to an argument string.
306
306
307 The interface is similar to that of getopt(), but it returns back a
307 The interface is similar to that of getopt(), but it returns back a
308 Struct with the options as keys and the stripped argument string still
308 Struct with the options as keys and the stripped argument string still
309 as a string.
309 as a string.
310
310
311 arg_str is quoted as a true sys.argv vector by using shlex.split.
311 arg_str is quoted as a true sys.argv vector by using shlex.split.
312 This allows us to easily expand variables, glob files, quote
312 This allows us to easily expand variables, glob files, quote
313 arguments, etc.
313 arguments, etc.
314
314
315 Options:
315 Options:
316 -mode: default 'string'. If given as 'list', the argument string is
316 -mode: default 'string'. If given as 'list', the argument string is
317 returned as a list (split on whitespace) instead of a string.
317 returned as a list (split on whitespace) instead of a string.
318
318
319 -list_all: put all option values in lists. Normally only options
319 -list_all: put all option values in lists. Normally only options
320 appearing more than once are put in a list.
320 appearing more than once are put in a list.
321
321
322 -posix (True): whether to split the input line in POSIX mode or not,
322 -posix (True): whether to split the input line in POSIX mode or not,
323 as per the conventions outlined in the shlex module from the
323 as per the conventions outlined in the shlex module from the
324 standard library."""
324 standard library."""
325
325
326 # inject default options at the beginning of the input line
326 # inject default options at the beginning of the input line
327 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
327 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
328 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
328 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
329
329
330 mode = kw.get('mode','string')
330 mode = kw.get('mode','string')
331 if mode not in ['string','list']:
331 if mode not in ['string','list']:
332 raise ValueError,'incorrect mode given: %s' % mode
332 raise ValueError,'incorrect mode given: %s' % mode
333 # Get options
333 # Get options
334 list_all = kw.get('list_all',0)
334 list_all = kw.get('list_all',0)
335 posix = kw.get('posix',True)
335 posix = kw.get('posix',True)
336
336
337 # Check if we have more than one argument to warrant extra processing:
337 # Check if we have more than one argument to warrant extra processing:
338 odict = {} # Dictionary with options
338 odict = {} # Dictionary with options
339 args = arg_str.split()
339 args = arg_str.split()
340 if len(args) >= 1:
340 if len(args) >= 1:
341 # If the list of inputs only has 0 or 1 thing in it, there's no
341 # If the list of inputs only has 0 or 1 thing in it, there's no
342 # need to look for options
342 # need to look for options
343 argv = arg_split(arg_str,posix)
343 argv = arg_split(arg_str,posix)
344 # Do regular option processing
344 # Do regular option processing
345 try:
345 try:
346 opts,args = getopt(argv,opt_str,*long_opts)
346 opts,args = getopt(argv,opt_str,*long_opts)
347 except GetoptError,e:
347 except GetoptError,e:
348 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
348 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
349 " ".join(long_opts)))
349 " ".join(long_opts)))
350 for o,a in opts:
350 for o,a in opts:
351 if o.startswith('--'):
351 if o.startswith('--'):
352 o = o[2:]
352 o = o[2:]
353 else:
353 else:
354 o = o[1:]
354 o = o[1:]
355 try:
355 try:
356 odict[o].append(a)
356 odict[o].append(a)
357 except AttributeError:
357 except AttributeError:
358 odict[o] = [odict[o],a]
358 odict[o] = [odict[o],a]
359 except KeyError:
359 except KeyError:
360 if list_all:
360 if list_all:
361 odict[o] = [a]
361 odict[o] = [a]
362 else:
362 else:
363 odict[o] = a
363 odict[o] = a
364
364
365 # Prepare opts,args for return
365 # Prepare opts,args for return
366 opts = Struct(odict)
366 opts = Struct(odict)
367 if mode == 'string':
367 if mode == 'string':
368 args = ' '.join(args)
368 args = ' '.join(args)
369
369
370 return opts,args
370 return opts,args
371
371
372 #......................................................................
372 #......................................................................
373 # And now the actual magic functions
373 # And now the actual magic functions
374
374
375 # Functions for IPython shell work (vars,funcs, config, etc)
375 # Functions for IPython shell work (vars,funcs, config, etc)
376 def magic_lsmagic(self, parameter_s = ''):
376 def magic_lsmagic(self, parameter_s = ''):
377 """List currently available magic functions."""
377 """List currently available magic functions."""
378 mesc = self.shell.ESC_MAGIC
378 mesc = self.shell.ESC_MAGIC
379 print 'Available magic functions:\n'+mesc+\
379 print 'Available magic functions:\n'+mesc+\
380 (' '+mesc).join(self.lsmagic())
380 (' '+mesc).join(self.lsmagic())
381 print '\n' + Magic.auto_status[self.shell.rc.automagic]
381 print '\n' + Magic.auto_status[self.shell.rc.automagic]
382 return None
382 return None
383
383
384 def magic_magic(self, parameter_s = ''):
384 def magic_magic(self, parameter_s = ''):
385 """Print information about the magic function system.
385 """Print information about the magic function system.
386
386
387 Supported formats: -latex, -brief, -rest
387 Supported formats: -latex, -brief, -rest
388 """
388 """
389
389
390 mode = ''
390 mode = ''
391 try:
391 try:
392 if parameter_s.split()[0] == '-latex':
392 if parameter_s.split()[0] == '-latex':
393 mode = 'latex'
393 mode = 'latex'
394 if parameter_s.split()[0] == '-brief':
394 if parameter_s.split()[0] == '-brief':
395 mode = 'brief'
395 mode = 'brief'
396 if parameter_s.split()[0] == '-rest':
396 if parameter_s.split()[0] == '-rest':
397 mode = 'rest'
397 mode = 'rest'
398 rest_docs = []
398 rest_docs = []
399 except:
399 except:
400 pass
400 pass
401
401
402 magic_docs = []
402 magic_docs = []
403 for fname in self.lsmagic():
403 for fname in self.lsmagic():
404 mname = 'magic_' + fname
404 mname = 'magic_' + fname
405 for space in (Magic,self,self.__class__):
405 for space in (Magic,self,self.__class__):
406 try:
406 try:
407 fn = space.__dict__[mname]
407 fn = space.__dict__[mname]
408 except KeyError:
408 except KeyError:
409 pass
409 pass
410 else:
410 else:
411 break
411 break
412 if mode == 'brief':
412 if mode == 'brief':
413 # only first line
413 # only first line
414 if fn.__doc__:
414 if fn.__doc__:
415 fndoc = fn.__doc__.split('\n',1)[0]
415 fndoc = fn.__doc__.split('\n',1)[0]
416 else:
416 else:
417 fndoc = 'No documentation'
417 fndoc = 'No documentation'
418 else:
418 else:
419 if fn.__doc__:
419 if fn.__doc__:
420 fndoc = fn.__doc__.rstrip()
420 fndoc = fn.__doc__.rstrip()
421 else:
421 else:
422 fndoc = 'No documentation'
422 fndoc = 'No documentation'
423
423
424
424
425 if mode == 'rest':
425 if mode == 'rest':
426 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
426 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
427 fname,fndoc))
427 fname,fndoc))
428
428
429 else:
429 else:
430 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
430 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
431 fname,fndoc))
431 fname,fndoc))
432
432
433 magic_docs = ''.join(magic_docs)
433 magic_docs = ''.join(magic_docs)
434
434
435 if mode == 'rest':
435 if mode == 'rest':
436 return "".join(rest_docs)
436 return "".join(rest_docs)
437
437
438 if mode == 'latex':
438 if mode == 'latex':
439 print self.format_latex(magic_docs)
439 print self.format_latex(magic_docs)
440 return
440 return
441 else:
441 else:
442 magic_docs = self.format_screen(magic_docs)
442 magic_docs = self.format_screen(magic_docs)
443 if mode == 'brief':
443 if mode == 'brief':
444 return magic_docs
444 return magic_docs
445
445
446 outmsg = """
446 outmsg = """
447 IPython's 'magic' functions
447 IPython's 'magic' functions
448 ===========================
448 ===========================
449
449
450 The magic function system provides a series of functions which allow you to
450 The magic function system provides a series of functions which allow you to
451 control the behavior of IPython itself, plus a lot of system-type
451 control the behavior of IPython itself, plus a lot of system-type
452 features. All these functions are prefixed with a % character, but parameters
452 features. All these functions are prefixed with a % character, but parameters
453 are given without parentheses or quotes.
453 are given without parentheses or quotes.
454
454
455 NOTE: If you have 'automagic' enabled (via the command line option or with the
455 NOTE: If you have 'automagic' enabled (via the command line option or with the
456 %automagic function), you don't need to type in the % explicitly. By default,
456 %automagic function), you don't need to type in the % explicitly. By default,
457 IPython ships with automagic on, so you should only rarely need the % escape.
457 IPython ships with automagic on, so you should only rarely need the % escape.
458
458
459 Example: typing '%cd mydir' (without the quotes) changes you working directory
459 Example: typing '%cd mydir' (without the quotes) changes you working directory
460 to 'mydir', if it exists.
460 to 'mydir', if it exists.
461
461
462 You can define your own magic functions to extend the system. See the supplied
462 You can define your own magic functions to extend the system. See the supplied
463 ipythonrc and example-magic.py files for details (in your ipython
463 ipythonrc and example-magic.py files for details (in your ipython
464 configuration directory, typically $HOME/.ipython/).
464 configuration directory, typically $HOME/.ipython/).
465
465
466 You can also define your own aliased names for magic functions. In your
466 You can also define your own aliased names for magic functions. In your
467 ipythonrc file, placing a line like:
467 ipythonrc file, placing a line like:
468
468
469 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
469 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
470
470
471 will define %pf as a new name for %profile.
471 will define %pf as a new name for %profile.
472
472
473 You can also call magics in code using the ipmagic() function, which IPython
473 You can also call magics in code using the ipmagic() function, which IPython
474 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
474 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
475
475
476 For a list of the available magic functions, use %lsmagic. For a description
476 For a list of the available magic functions, use %lsmagic. For a description
477 of any of them, type %magic_name?, e.g. '%cd?'.
477 of any of them, type %magic_name?, e.g. '%cd?'.
478
478
479 Currently the magic system has the following functions:\n"""
479 Currently the magic system has the following functions:\n"""
480
480
481 mesc = self.shell.ESC_MAGIC
481 mesc = self.shell.ESC_MAGIC
482 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
482 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
483 "\n\n%s%s\n\n%s" % (outmsg,
483 "\n\n%s%s\n\n%s" % (outmsg,
484 magic_docs,mesc,mesc,
484 magic_docs,mesc,mesc,
485 (' '+mesc).join(self.lsmagic()),
485 (' '+mesc).join(self.lsmagic()),
486 Magic.auto_status[self.shell.rc.automagic] ) )
486 Magic.auto_status[self.shell.rc.automagic] ) )
487
487
488 page(outmsg,screen_lines=self.shell.rc.screen_length)
488 page(outmsg,screen_lines=self.shell.rc.screen_length)
489
489
490
490
491 def magic_autoindent(self, parameter_s = ''):
491 def magic_autoindent(self, parameter_s = ''):
492 """Toggle autoindent on/off (if available)."""
492 """Toggle autoindent on/off (if available)."""
493
493
494 self.shell.set_autoindent()
494 self.shell.set_autoindent()
495 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
495 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
496
496
497
497
498 def magic_automagic(self, parameter_s = ''):
498 def magic_automagic(self, parameter_s = ''):
499 """Make magic functions callable without having to type the initial %.
499 """Make magic functions callable without having to type the initial %.
500
500
501 Without argumentsl toggles on/off (when off, you must call it as
501 Without argumentsl toggles on/off (when off, you must call it as
502 %automagic, of course). With arguments it sets the value, and you can
502 %automagic, of course). With arguments it sets the value, and you can
503 use any of (case insensitive):
503 use any of (case insensitive):
504
504
505 - on,1,True: to activate
505 - on,1,True: to activate
506
506
507 - off,0,False: to deactivate.
507 - off,0,False: to deactivate.
508
508
509 Note that magic functions have lowest priority, so if there's a
509 Note that magic functions have lowest priority, so if there's a
510 variable whose name collides with that of a magic fn, automagic won't
510 variable whose name collides with that of a magic fn, automagic won't
511 work for that function (you get the variable instead). However, if you
511 work for that function (you get the variable instead). However, if you
512 delete the variable (del var), the previously shadowed magic function
512 delete the variable (del var), the previously shadowed magic function
513 becomes visible to automagic again."""
513 becomes visible to automagic again."""
514
514
515 rc = self.shell.rc
515 rc = self.shell.rc
516 arg = parameter_s.lower()
516 arg = parameter_s.lower()
517 if parameter_s in ('on','1','true'):
517 if parameter_s in ('on','1','true'):
518 rc.automagic = True
518 rc.automagic = True
519 elif parameter_s in ('off','0','false'):
519 elif parameter_s in ('off','0','false'):
520 rc.automagic = False
520 rc.automagic = False
521 else:
521 else:
522 rc.automagic = not rc.automagic
522 rc.automagic = not rc.automagic
523 print '\n' + Magic.auto_status[rc.automagic]
523 print '\n' + Magic.auto_status[rc.automagic]
524
524
525 @testdec.skip_doctest
525 @testdec.skip_doctest
526 def magic_autocall(self, parameter_s = ''):
526 def magic_autocall(self, parameter_s = ''):
527 """Make functions callable without having to type parentheses.
527 """Make functions callable without having to type parentheses.
528
528
529 Usage:
529 Usage:
530
530
531 %autocall [mode]
531 %autocall [mode]
532
532
533 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
533 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
534 value is toggled on and off (remembering the previous state).
534 value is toggled on and off (remembering the previous state).
535
535
536 In more detail, these values mean:
536 In more detail, these values mean:
537
537
538 0 -> fully disabled
538 0 -> fully disabled
539
539
540 1 -> active, but do not apply if there are no arguments on the line.
540 1 -> active, but do not apply if there are no arguments on the line.
541
541
542 In this mode, you get:
542 In this mode, you get:
543
543
544 In [1]: callable
544 In [1]: callable
545 Out[1]: <built-in function callable>
545 Out[1]: <built-in function callable>
546
546
547 In [2]: callable 'hello'
547 In [2]: callable 'hello'
548 ------> callable('hello')
548 ------> callable('hello')
549 Out[2]: False
549 Out[2]: False
550
550
551 2 -> Active always. Even if no arguments are present, the callable
551 2 -> Active always. Even if no arguments are present, the callable
552 object is called:
552 object is called:
553
553
554 In [2]: float
554 In [2]: float
555 ------> float()
555 ------> float()
556 Out[2]: 0.0
556 Out[2]: 0.0
557
557
558 Note that even with autocall off, you can still use '/' at the start of
558 Note that even with autocall off, you can still use '/' at the start of
559 a line to treat the first argument on the command line as a function
559 a line to treat the first argument on the command line as a function
560 and add parentheses to it:
560 and add parentheses to it:
561
561
562 In [8]: /str 43
562 In [8]: /str 43
563 ------> str(43)
563 ------> str(43)
564 Out[8]: '43'
564 Out[8]: '43'
565
565
566 # all-random (note for auto-testing)
566 # all-random (note for auto-testing)
567 """
567 """
568
568
569 rc = self.shell.rc
569 rc = self.shell.rc
570
570
571 if parameter_s:
571 if parameter_s:
572 arg = int(parameter_s)
572 arg = int(parameter_s)
573 else:
573 else:
574 arg = 'toggle'
574 arg = 'toggle'
575
575
576 if not arg in (0,1,2,'toggle'):
576 if not arg in (0,1,2,'toggle'):
577 error('Valid modes: (0->Off, 1->Smart, 2->Full')
577 error('Valid modes: (0->Off, 1->Smart, 2->Full')
578 return
578 return
579
579
580 if arg in (0,1,2):
580 if arg in (0,1,2):
581 rc.autocall = arg
581 rc.autocall = arg
582 else: # toggle
582 else: # toggle
583 if rc.autocall:
583 if rc.autocall:
584 self._magic_state.autocall_save = rc.autocall
584 self._magic_state.autocall_save = rc.autocall
585 rc.autocall = 0
585 rc.autocall = 0
586 else:
586 else:
587 try:
587 try:
588 rc.autocall = self._magic_state.autocall_save
588 rc.autocall = self._magic_state.autocall_save
589 except AttributeError:
589 except AttributeError:
590 rc.autocall = self._magic_state.autocall_save = 1
590 rc.autocall = self._magic_state.autocall_save = 1
591
591
592 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
592 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
593
593
594 def magic_system_verbose(self, parameter_s = ''):
594 def magic_system_verbose(self, parameter_s = ''):
595 """Set verbose printing of system calls.
595 """Set verbose printing of system calls.
596
596
597 If called without an argument, act as a toggle"""
597 If called without an argument, act as a toggle"""
598
598
599 if parameter_s:
599 if parameter_s:
600 val = bool(eval(parameter_s))
600 val = bool(eval(parameter_s))
601 else:
601 else:
602 val = None
602 val = None
603
603
604 self.shell.rc_set_toggle('system_verbose',val)
604 self.shell.rc_set_toggle('system_verbose',val)
605 print "System verbose printing is:",\
605 print "System verbose printing is:",\
606 ['OFF','ON'][self.shell.rc.system_verbose]
606 ['OFF','ON'][self.shell.rc.system_verbose]
607
607
608
608
609 def magic_page(self, parameter_s=''):
609 def magic_page(self, parameter_s=''):
610 """Pretty print the object and display it through a pager.
610 """Pretty print the object and display it through a pager.
611
611
612 %page [options] OBJECT
612 %page [options] OBJECT
613
613
614 If no object is given, use _ (last output).
614 If no object is given, use _ (last output).
615
615
616 Options:
616 Options:
617
617
618 -r: page str(object), don't pretty-print it."""
618 -r: page str(object), don't pretty-print it."""
619
619
620 # After a function contributed by Olivier Aubert, slightly modified.
620 # After a function contributed by Olivier Aubert, slightly modified.
621
621
622 # Process options/args
622 # Process options/args
623 opts,args = self.parse_options(parameter_s,'r')
623 opts,args = self.parse_options(parameter_s,'r')
624 raw = 'r' in opts
624 raw = 'r' in opts
625
625
626 oname = args and args or '_'
626 oname = args and args or '_'
627 info = self._ofind(oname)
627 info = self._ofind(oname)
628 if info['found']:
628 if info['found']:
629 txt = (raw and str or pformat)( info['obj'] )
629 txt = (raw and str or pformat)( info['obj'] )
630 page(txt)
630 page(txt)
631 else:
631 else:
632 print 'Object `%s` not found' % oname
632 print 'Object `%s` not found' % oname
633
633
634 def magic_profile(self, parameter_s=''):
634 def magic_profile(self, parameter_s=''):
635 """Print your currently active IPyhton profile."""
635 """Print your currently active IPyhton profile."""
636 if self.shell.rc.profile:
636 if self.shell.rc.profile:
637 printpl('Current IPython profile: $self.shell.rc.profile.')
637 printpl('Current IPython profile: $self.shell.rc.profile.')
638 else:
638 else:
639 print 'No profile active.'
639 print 'No profile active.'
640
640
641 def magic_pinfo(self, parameter_s='', namespaces=None):
641 def magic_pinfo(self, parameter_s='', namespaces=None):
642 """Provide detailed information about an object.
642 """Provide detailed information about an object.
643
643
644 '%pinfo object' is just a synonym for object? or ?object."""
644 '%pinfo object' is just a synonym for object? or ?object."""
645
645
646 #print 'pinfo par: <%s>' % parameter_s # dbg
646 #print 'pinfo par: <%s>' % parameter_s # dbg
647
647
648
648
649 # detail_level: 0 -> obj? , 1 -> obj??
649 # detail_level: 0 -> obj? , 1 -> obj??
650 detail_level = 0
650 detail_level = 0
651 # We need to detect if we got called as 'pinfo pinfo foo', which can
651 # We need to detect if we got called as 'pinfo pinfo foo', which can
652 # happen if the user types 'pinfo foo?' at the cmd line.
652 # happen if the user types 'pinfo foo?' at the cmd line.
653 pinfo,qmark1,oname,qmark2 = \
653 pinfo,qmark1,oname,qmark2 = \
654 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
654 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
655 if pinfo or qmark1 or qmark2:
655 if pinfo or qmark1 or qmark2:
656 detail_level = 1
656 detail_level = 1
657 if "*" in oname:
657 if "*" in oname:
658 self.magic_psearch(oname)
658 self.magic_psearch(oname)
659 else:
659 else:
660 self._inspect('pinfo', oname, detail_level=detail_level,
660 self._inspect('pinfo', oname, detail_level=detail_level,
661 namespaces=namespaces)
661 namespaces=namespaces)
662
662
663 def magic_pdef(self, parameter_s='', namespaces=None):
663 def magic_pdef(self, parameter_s='', namespaces=None):
664 """Print the definition header for any callable object.
664 """Print the definition header for any callable object.
665
665
666 If the object is a class, print the constructor information."""
666 If the object is a class, print the constructor information."""
667 self._inspect('pdef',parameter_s, namespaces)
667 self._inspect('pdef',parameter_s, namespaces)
668
668
669 def magic_pdoc(self, parameter_s='', namespaces=None):
669 def magic_pdoc(self, parameter_s='', namespaces=None):
670 """Print the docstring for an object.
670 """Print the docstring for an object.
671
671
672 If the given object is a class, it will print both the class and the
672 If the given object is a class, it will print both the class and the
673 constructor docstrings."""
673 constructor docstrings."""
674 self._inspect('pdoc',parameter_s, namespaces)
674 self._inspect('pdoc',parameter_s, namespaces)
675
675
676 def magic_psource(self, parameter_s='', namespaces=None):
676 def magic_psource(self, parameter_s='', namespaces=None):
677 """Print (or run through pager) the source code for an object."""
677 """Print (or run through pager) the source code for an object."""
678 self._inspect('psource',parameter_s, namespaces)
678 self._inspect('psource',parameter_s, namespaces)
679
679
680 def magic_pfile(self, parameter_s=''):
680 def magic_pfile(self, parameter_s=''):
681 """Print (or run through pager) the file where an object is defined.
681 """Print (or run through pager) the file where an object is defined.
682
682
683 The file opens at the line where the object definition begins. IPython
683 The file opens at the line where the object definition begins. IPython
684 will honor the environment variable PAGER if set, and otherwise will
684 will honor the environment variable PAGER if set, and otherwise will
685 do its best to print the file in a convenient form.
685 do its best to print the file in a convenient form.
686
686
687 If the given argument is not an object currently defined, IPython will
687 If the given argument is not an object currently defined, IPython will
688 try to interpret it as a filename (automatically adding a .py extension
688 try to interpret it as a filename (automatically adding a .py extension
689 if needed). You can thus use %pfile as a syntax highlighting code
689 if needed). You can thus use %pfile as a syntax highlighting code
690 viewer."""
690 viewer."""
691
691
692 # first interpret argument as an object name
692 # first interpret argument as an object name
693 out = self._inspect('pfile',parameter_s)
693 out = self._inspect('pfile',parameter_s)
694 # if not, try the input as a filename
694 # if not, try the input as a filename
695 if out == 'not found':
695 if out == 'not found':
696 try:
696 try:
697 filename = get_py_filename(parameter_s)
697 filename = get_py_filename(parameter_s)
698 except IOError,msg:
698 except IOError,msg:
699 print msg
699 print msg
700 return
700 return
701 page(self.shell.inspector.format(file(filename).read()))
701 page(self.shell.inspector.format(file(filename).read()))
702
702
703 def _inspect(self,meth,oname,namespaces=None,**kw):
703 def _inspect(self,meth,oname,namespaces=None,**kw):
704 """Generic interface to the inspector system.
704 """Generic interface to the inspector system.
705
705
706 This function is meant to be called by pdef, pdoc & friends."""
706 This function is meant to be called by pdef, pdoc & friends."""
707
707
708 #oname = oname.strip()
708 #oname = oname.strip()
709 #print '1- oname: <%r>' % oname # dbg
709 #print '1- oname: <%r>' % oname # dbg
710 try:
710 try:
711 oname = oname.strip().encode('ascii')
711 oname = oname.strip().encode('ascii')
712 #print '2- oname: <%r>' % oname # dbg
712 #print '2- oname: <%r>' % oname # dbg
713 except UnicodeEncodeError:
713 except UnicodeEncodeError:
714 print 'Python identifiers can only contain ascii characters.'
714 print 'Python identifiers can only contain ascii characters.'
715 return 'not found'
715 return 'not found'
716
716
717 info = Struct(self._ofind(oname, namespaces))
717 info = Struct(self._ofind(oname, namespaces))
718
718
719 if info.found:
719 if info.found:
720 try:
720 try:
721 IPython.utils.generics.inspect_object(info.obj)
721 IPython.utils.generics.inspect_object(info.obj)
722 return
722 return
723 except ipapi.TryNext:
723 except ipapi.TryNext:
724 pass
724 pass
725 # Get the docstring of the class property if it exists.
725 # Get the docstring of the class property if it exists.
726 path = oname.split('.')
726 path = oname.split('.')
727 root = '.'.join(path[:-1])
727 root = '.'.join(path[:-1])
728 if info.parent is not None:
728 if info.parent is not None:
729 try:
729 try:
730 target = getattr(info.parent, '__class__')
730 target = getattr(info.parent, '__class__')
731 # The object belongs to a class instance.
731 # The object belongs to a class instance.
732 try:
732 try:
733 target = getattr(target, path[-1])
733 target = getattr(target, path[-1])
734 # The class defines the object.
734 # The class defines the object.
735 if isinstance(target, property):
735 if isinstance(target, property):
736 oname = root + '.__class__.' + path[-1]
736 oname = root + '.__class__.' + path[-1]
737 info = Struct(self._ofind(oname))
737 info = Struct(self._ofind(oname))
738 except AttributeError: pass
738 except AttributeError: pass
739 except AttributeError: pass
739 except AttributeError: pass
740
740
741 pmethod = getattr(self.shell.inspector,meth)
741 pmethod = getattr(self.shell.inspector,meth)
742 formatter = info.ismagic and self.format_screen or None
742 formatter = info.ismagic and self.format_screen or None
743 if meth == 'pdoc':
743 if meth == 'pdoc':
744 pmethod(info.obj,oname,formatter)
744 pmethod(info.obj,oname,formatter)
745 elif meth == 'pinfo':
745 elif meth == 'pinfo':
746 pmethod(info.obj,oname,formatter,info,**kw)
746 pmethod(info.obj,oname,formatter,info,**kw)
747 else:
747 else:
748 pmethod(info.obj,oname)
748 pmethod(info.obj,oname)
749 else:
749 else:
750 print 'Object `%s` not found.' % oname
750 print 'Object `%s` not found.' % oname
751 return 'not found' # so callers can take other action
751 return 'not found' # so callers can take other action
752
752
753 def magic_psearch(self, parameter_s=''):
753 def magic_psearch(self, parameter_s=''):
754 """Search for object in namespaces by wildcard.
754 """Search for object in namespaces by wildcard.
755
755
756 %psearch [options] PATTERN [OBJECT TYPE]
756 %psearch [options] PATTERN [OBJECT TYPE]
757
757
758 Note: ? can be used as a synonym for %psearch, at the beginning or at
758 Note: ? can be used as a synonym for %psearch, at the beginning or at
759 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
759 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
760 rest of the command line must be unchanged (options come first), so
760 rest of the command line must be unchanged (options come first), so
761 for example the following forms are equivalent
761 for example the following forms are equivalent
762
762
763 %psearch -i a* function
763 %psearch -i a* function
764 -i a* function?
764 -i a* function?
765 ?-i a* function
765 ?-i a* function
766
766
767 Arguments:
767 Arguments:
768
768
769 PATTERN
769 PATTERN
770
770
771 where PATTERN is a string containing * as a wildcard similar to its
771 where PATTERN is a string containing * as a wildcard similar to its
772 use in a shell. The pattern is matched in all namespaces on the
772 use in a shell. The pattern is matched in all namespaces on the
773 search path. By default objects starting with a single _ are not
773 search path. By default objects starting with a single _ are not
774 matched, many IPython generated objects have a single
774 matched, many IPython generated objects have a single
775 underscore. The default is case insensitive matching. Matching is
775 underscore. The default is case insensitive matching. Matching is
776 also done on the attributes of objects and not only on the objects
776 also done on the attributes of objects and not only on the objects
777 in a module.
777 in a module.
778
778
779 [OBJECT TYPE]
779 [OBJECT TYPE]
780
780
781 Is the name of a python type from the types module. The name is
781 Is the name of a python type from the types module. The name is
782 given in lowercase without the ending type, ex. StringType is
782 given in lowercase without the ending type, ex. StringType is
783 written string. By adding a type here only objects matching the
783 written string. By adding a type here only objects matching the
784 given type are matched. Using all here makes the pattern match all
784 given type are matched. Using all here makes the pattern match all
785 types (this is the default).
785 types (this is the default).
786
786
787 Options:
787 Options:
788
788
789 -a: makes the pattern match even objects whose names start with a
789 -a: makes the pattern match even objects whose names start with a
790 single underscore. These names are normally ommitted from the
790 single underscore. These names are normally ommitted from the
791 search.
791 search.
792
792
793 -i/-c: make the pattern case insensitive/sensitive. If neither of
793 -i/-c: make the pattern case insensitive/sensitive. If neither of
794 these options is given, the default is read from your ipythonrc
794 these options is given, the default is read from your ipythonrc
795 file. The option name which sets this value is
795 file. The option name which sets this value is
796 'wildcards_case_sensitive'. If this option is not specified in your
796 'wildcards_case_sensitive'. If this option is not specified in your
797 ipythonrc file, IPython's internal default is to do a case sensitive
797 ipythonrc file, IPython's internal default is to do a case sensitive
798 search.
798 search.
799
799
800 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
800 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
801 specifiy can be searched in any of the following namespaces:
801 specifiy can be searched in any of the following namespaces:
802 'builtin', 'user', 'user_global','internal', 'alias', where
802 'builtin', 'user', 'user_global','internal', 'alias', where
803 'builtin' and 'user' are the search defaults. Note that you should
803 'builtin' and 'user' are the search defaults. Note that you should
804 not use quotes when specifying namespaces.
804 not use quotes when specifying namespaces.
805
805
806 'Builtin' contains the python module builtin, 'user' contains all
806 'Builtin' contains the python module builtin, 'user' contains all
807 user data, 'alias' only contain the shell aliases and no python
807 user data, 'alias' only contain the shell aliases and no python
808 objects, 'internal' contains objects used by IPython. The
808 objects, 'internal' contains objects used by IPython. The
809 'user_global' namespace is only used by embedded IPython instances,
809 'user_global' namespace is only used by embedded IPython instances,
810 and it contains module-level globals. You can add namespaces to the
810 and it contains module-level globals. You can add namespaces to the
811 search with -s or exclude them with -e (these options can be given
811 search with -s or exclude them with -e (these options can be given
812 more than once).
812 more than once).
813
813
814 Examples:
814 Examples:
815
815
816 %psearch a* -> objects beginning with an a
816 %psearch a* -> objects beginning with an a
817 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
817 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
818 %psearch a* function -> all functions beginning with an a
818 %psearch a* function -> all functions beginning with an a
819 %psearch re.e* -> objects beginning with an e in module re
819 %psearch re.e* -> objects beginning with an e in module re
820 %psearch r*.e* -> objects that start with e in modules starting in r
820 %psearch r*.e* -> objects that start with e in modules starting in r
821 %psearch r*.* string -> all strings in modules beginning with r
821 %psearch r*.* string -> all strings in modules beginning with r
822
822
823 Case sensitve search:
823 Case sensitve search:
824
824
825 %psearch -c a* list all object beginning with lower case a
825 %psearch -c a* list all object beginning with lower case a
826
826
827 Show objects beginning with a single _:
827 Show objects beginning with a single _:
828
828
829 %psearch -a _* list objects beginning with a single underscore"""
829 %psearch -a _* list objects beginning with a single underscore"""
830 try:
830 try:
831 parameter_s = parameter_s.encode('ascii')
831 parameter_s = parameter_s.encode('ascii')
832 except UnicodeEncodeError:
832 except UnicodeEncodeError:
833 print 'Python identifiers can only contain ascii characters.'
833 print 'Python identifiers can only contain ascii characters.'
834 return
834 return
835
835
836 # default namespaces to be searched
836 # default namespaces to be searched
837 def_search = ['user','builtin']
837 def_search = ['user','builtin']
838
838
839 # Process options/args
839 # Process options/args
840 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
840 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
841 opt = opts.get
841 opt = opts.get
842 shell = self.shell
842 shell = self.shell
843 psearch = shell.inspector.psearch
843 psearch = shell.inspector.psearch
844
844
845 # select case options
845 # select case options
846 if opts.has_key('i'):
846 if opts.has_key('i'):
847 ignore_case = True
847 ignore_case = True
848 elif opts.has_key('c'):
848 elif opts.has_key('c'):
849 ignore_case = False
849 ignore_case = False
850 else:
850 else:
851 ignore_case = not shell.rc.wildcards_case_sensitive
851 ignore_case = not shell.rc.wildcards_case_sensitive
852
852
853 # Build list of namespaces to search from user options
853 # Build list of namespaces to search from user options
854 def_search.extend(opt('s',[]))
854 def_search.extend(opt('s',[]))
855 ns_exclude = ns_exclude=opt('e',[])
855 ns_exclude = ns_exclude=opt('e',[])
856 ns_search = [nm for nm in def_search if nm not in ns_exclude]
856 ns_search = [nm for nm in def_search if nm not in ns_exclude]
857
857
858 # Call the actual search
858 # Call the actual search
859 try:
859 try:
860 psearch(args,shell.ns_table,ns_search,
860 psearch(args,shell.ns_table,ns_search,
861 show_all=opt('a'),ignore_case=ignore_case)
861 show_all=opt('a'),ignore_case=ignore_case)
862 except:
862 except:
863 shell.showtraceback()
863 shell.showtraceback()
864
864
865 def magic_who_ls(self, parameter_s=''):
865 def magic_who_ls(self, parameter_s=''):
866 """Return a sorted list of all interactive variables.
866 """Return a sorted list of all interactive variables.
867
867
868 If arguments are given, only variables of types matching these
868 If arguments are given, only variables of types matching these
869 arguments are returned."""
869 arguments are returned."""
870
870
871 user_ns = self.shell.user_ns
871 user_ns = self.shell.user_ns
872 internal_ns = self.shell.internal_ns
872 internal_ns = self.shell.internal_ns
873 user_config_ns = self.shell.user_config_ns
873 user_config_ns = self.shell.user_config_ns
874 out = []
874 out = []
875 typelist = parameter_s.split()
875 typelist = parameter_s.split()
876
876
877 for i in user_ns:
877 for i in user_ns:
878 if not (i.startswith('_') or i.startswith('_i')) \
878 if not (i.startswith('_') or i.startswith('_i')) \
879 and not (i in internal_ns or i in user_config_ns):
879 and not (i in internal_ns or i in user_config_ns):
880 if typelist:
880 if typelist:
881 if type(user_ns[i]).__name__ in typelist:
881 if type(user_ns[i]).__name__ in typelist:
882 out.append(i)
882 out.append(i)
883 else:
883 else:
884 out.append(i)
884 out.append(i)
885 out.sort()
885 out.sort()
886 return out
886 return out
887
887
888 def magic_who(self, parameter_s=''):
888 def magic_who(self, parameter_s=''):
889 """Print all interactive variables, with some minimal formatting.
889 """Print all interactive variables, with some minimal formatting.
890
890
891 If any arguments are given, only variables whose type matches one of
891 If any arguments are given, only variables whose type matches one of
892 these are printed. For example:
892 these are printed. For example:
893
893
894 %who function str
894 %who function str
895
895
896 will only list functions and strings, excluding all other types of
896 will only list functions and strings, excluding all other types of
897 variables. To find the proper type names, simply use type(var) at a
897 variables. To find the proper type names, simply use type(var) at a
898 command line to see how python prints type names. For example:
898 command line to see how python prints type names. For example:
899
899
900 In [1]: type('hello')\\
900 In [1]: type('hello')\\
901 Out[1]: <type 'str'>
901 Out[1]: <type 'str'>
902
902
903 indicates that the type name for strings is 'str'.
903 indicates that the type name for strings is 'str'.
904
904
905 %who always excludes executed names loaded through your configuration
905 %who always excludes executed names loaded through your configuration
906 file and things which are internal to IPython.
906 file and things which are internal to IPython.
907
907
908 This is deliberate, as typically you may load many modules and the
908 This is deliberate, as typically you may load many modules and the
909 purpose of %who is to show you only what you've manually defined."""
909 purpose of %who is to show you only what you've manually defined."""
910
910
911 varlist = self.magic_who_ls(parameter_s)
911 varlist = self.magic_who_ls(parameter_s)
912 if not varlist:
912 if not varlist:
913 if parameter_s:
913 if parameter_s:
914 print 'No variables match your requested type.'
914 print 'No variables match your requested type.'
915 else:
915 else:
916 print 'Interactive namespace is empty.'
916 print 'Interactive namespace is empty.'
917 return
917 return
918
918
919 # if we have variables, move on...
919 # if we have variables, move on...
920 count = 0
920 count = 0
921 for i in varlist:
921 for i in varlist:
922 print i+'\t',
922 print i+'\t',
923 count += 1
923 count += 1
924 if count > 8:
924 if count > 8:
925 count = 0
925 count = 0
926 print
926 print
927 print
927 print
928
928
929 def magic_whos(self, parameter_s=''):
929 def magic_whos(self, parameter_s=''):
930 """Like %who, but gives some extra information about each variable.
930 """Like %who, but gives some extra information about each variable.
931
931
932 The same type filtering of %who can be applied here.
932 The same type filtering of %who can be applied here.
933
933
934 For all variables, the type is printed. Additionally it prints:
934 For all variables, the type is printed. Additionally it prints:
935
935
936 - For {},[],(): their length.
936 - For {},[],(): their length.
937
937
938 - For numpy and Numeric arrays, a summary with shape, number of
938 - For numpy and Numeric arrays, a summary with shape, number of
939 elements, typecode and size in memory.
939 elements, typecode and size in memory.
940
940
941 - Everything else: a string representation, snipping their middle if
941 - Everything else: a string representation, snipping their middle if
942 too long."""
942 too long."""
943
943
944 varnames = self.magic_who_ls(parameter_s)
944 varnames = self.magic_who_ls(parameter_s)
945 if not varnames:
945 if not varnames:
946 if parameter_s:
946 if parameter_s:
947 print 'No variables match your requested type.'
947 print 'No variables match your requested type.'
948 else:
948 else:
949 print 'Interactive namespace is empty.'
949 print 'Interactive namespace is empty.'
950 return
950 return
951
951
952 # if we have variables, move on...
952 # if we have variables, move on...
953
953
954 # for these types, show len() instead of data:
954 # for these types, show len() instead of data:
955 seq_types = [types.DictType,types.ListType,types.TupleType]
955 seq_types = [types.DictType,types.ListType,types.TupleType]
956
956
957 # for numpy/Numeric arrays, display summary info
957 # for numpy/Numeric arrays, display summary info
958 try:
958 try:
959 import numpy
959 import numpy
960 except ImportError:
960 except ImportError:
961 ndarray_type = None
961 ndarray_type = None
962 else:
962 else:
963 ndarray_type = numpy.ndarray.__name__
963 ndarray_type = numpy.ndarray.__name__
964 try:
964 try:
965 import Numeric
965 import Numeric
966 except ImportError:
966 except ImportError:
967 array_type = None
967 array_type = None
968 else:
968 else:
969 array_type = Numeric.ArrayType.__name__
969 array_type = Numeric.ArrayType.__name__
970
970
971 # Find all variable names and types so we can figure out column sizes
971 # Find all variable names and types so we can figure out column sizes
972 def get_vars(i):
972 def get_vars(i):
973 return self.shell.user_ns[i]
973 return self.shell.user_ns[i]
974
974
975 # some types are well known and can be shorter
975 # some types are well known and can be shorter
976 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
976 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
977 def type_name(v):
977 def type_name(v):
978 tn = type(v).__name__
978 tn = type(v).__name__
979 return abbrevs.get(tn,tn)
979 return abbrevs.get(tn,tn)
980
980
981 varlist = map(get_vars,varnames)
981 varlist = map(get_vars,varnames)
982
982
983 typelist = []
983 typelist = []
984 for vv in varlist:
984 for vv in varlist:
985 tt = type_name(vv)
985 tt = type_name(vv)
986
986
987 if tt=='instance':
987 if tt=='instance':
988 typelist.append( abbrevs.get(str(vv.__class__),
988 typelist.append( abbrevs.get(str(vv.__class__),
989 str(vv.__class__)))
989 str(vv.__class__)))
990 else:
990 else:
991 typelist.append(tt)
991 typelist.append(tt)
992
992
993 # column labels and # of spaces as separator
993 # column labels and # of spaces as separator
994 varlabel = 'Variable'
994 varlabel = 'Variable'
995 typelabel = 'Type'
995 typelabel = 'Type'
996 datalabel = 'Data/Info'
996 datalabel = 'Data/Info'
997 colsep = 3
997 colsep = 3
998 # variable format strings
998 # variable format strings
999 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
999 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1000 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1000 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1001 aformat = "%s: %s elems, type `%s`, %s bytes"
1001 aformat = "%s: %s elems, type `%s`, %s bytes"
1002 # find the size of the columns to format the output nicely
1002 # find the size of the columns to format the output nicely
1003 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1003 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1004 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1004 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1005 # table header
1005 # table header
1006 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1006 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1007 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1007 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1008 # and the table itself
1008 # and the table itself
1009 kb = 1024
1009 kb = 1024
1010 Mb = 1048576 # kb**2
1010 Mb = 1048576 # kb**2
1011 for vname,var,vtype in zip(varnames,varlist,typelist):
1011 for vname,var,vtype in zip(varnames,varlist,typelist):
1012 print itpl(vformat),
1012 print itpl(vformat),
1013 if vtype in seq_types:
1013 if vtype in seq_types:
1014 print len(var)
1014 print len(var)
1015 elif vtype in [array_type,ndarray_type]:
1015 elif vtype in [array_type,ndarray_type]:
1016 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1016 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1017 if vtype==ndarray_type:
1017 if vtype==ndarray_type:
1018 # numpy
1018 # numpy
1019 vsize = var.size
1019 vsize = var.size
1020 vbytes = vsize*var.itemsize
1020 vbytes = vsize*var.itemsize
1021 vdtype = var.dtype
1021 vdtype = var.dtype
1022 else:
1022 else:
1023 # Numeric
1023 # Numeric
1024 vsize = Numeric.size(var)
1024 vsize = Numeric.size(var)
1025 vbytes = vsize*var.itemsize()
1025 vbytes = vsize*var.itemsize()
1026 vdtype = var.typecode()
1026 vdtype = var.typecode()
1027
1027
1028 if vbytes < 100000:
1028 if vbytes < 100000:
1029 print aformat % (vshape,vsize,vdtype,vbytes)
1029 print aformat % (vshape,vsize,vdtype,vbytes)
1030 else:
1030 else:
1031 print aformat % (vshape,vsize,vdtype,vbytes),
1031 print aformat % (vshape,vsize,vdtype,vbytes),
1032 if vbytes < Mb:
1032 if vbytes < Mb:
1033 print '(%s kb)' % (vbytes/kb,)
1033 print '(%s kb)' % (vbytes/kb,)
1034 else:
1034 else:
1035 print '(%s Mb)' % (vbytes/Mb,)
1035 print '(%s Mb)' % (vbytes/Mb,)
1036 else:
1036 else:
1037 try:
1037 try:
1038 vstr = str(var)
1038 vstr = str(var)
1039 except UnicodeEncodeError:
1039 except UnicodeEncodeError:
1040 vstr = unicode(var).encode(sys.getdefaultencoding(),
1040 vstr = unicode(var).encode(sys.getdefaultencoding(),
1041 'backslashreplace')
1041 'backslashreplace')
1042 vstr = vstr.replace('\n','\\n')
1042 vstr = vstr.replace('\n','\\n')
1043 if len(vstr) < 50:
1043 if len(vstr) < 50:
1044 print vstr
1044 print vstr
1045 else:
1045 else:
1046 printpl(vfmt_short)
1046 printpl(vfmt_short)
1047
1047
1048 def magic_reset(self, parameter_s=''):
1048 def magic_reset(self, parameter_s=''):
1049 """Resets the namespace by removing all names defined by the user.
1049 """Resets the namespace by removing all names defined by the user.
1050
1050
1051 Input/Output history are left around in case you need them.
1051 Input/Output history are left around in case you need them.
1052
1052
1053 Parameters
1053 Parameters
1054 ----------
1054 ----------
1055 -y : force reset without asking for confirmation.
1055 -y : force reset without asking for confirmation.
1056
1056
1057 Examples
1057 Examples
1058 --------
1058 --------
1059 In [6]: a = 1
1059 In [6]: a = 1
1060
1060
1061 In [7]: a
1061 In [7]: a
1062 Out[7]: 1
1062 Out[7]: 1
1063
1063
1064 In [8]: 'a' in _ip.user_ns
1064 In [8]: 'a' in _ip.user_ns
1065 Out[8]: True
1065 Out[8]: True
1066
1066
1067 In [9]: %reset -f
1067 In [9]: %reset -f
1068
1068
1069 In [10]: 'a' in _ip.user_ns
1069 In [10]: 'a' in _ip.user_ns
1070 Out[10]: False
1070 Out[10]: False
1071 """
1071 """
1072
1072
1073 if parameter_s == '-f':
1073 if parameter_s == '-f':
1074 ans = True
1074 ans = True
1075 else:
1075 else:
1076 ans = self.shell.ask_yes_no(
1076 ans = self.shell.ask_yes_no(
1077 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1077 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1078 if not ans:
1078 if not ans:
1079 print 'Nothing done.'
1079 print 'Nothing done.'
1080 return
1080 return
1081 user_ns = self.shell.user_ns
1081 user_ns = self.shell.user_ns
1082 for i in self.magic_who_ls():
1082 for i in self.magic_who_ls():
1083 del(user_ns[i])
1083 del(user_ns[i])
1084
1084
1085 # Also flush the private list of module references kept for script
1085 # Also flush the private list of module references kept for script
1086 # execution protection
1086 # execution protection
1087 self.shell.clear_main_mod_cache()
1087 self.shell.clear_main_mod_cache()
1088
1088
1089 def magic_logstart(self,parameter_s=''):
1089 def magic_logstart(self,parameter_s=''):
1090 """Start logging anywhere in a session.
1090 """Start logging anywhere in a session.
1091
1091
1092 %logstart [-o|-r|-t] [log_name [log_mode]]
1092 %logstart [-o|-r|-t] [log_name [log_mode]]
1093
1093
1094 If no name is given, it defaults to a file named 'ipython_log.py' in your
1094 If no name is given, it defaults to a file named 'ipython_log.py' in your
1095 current directory, in 'rotate' mode (see below).
1095 current directory, in 'rotate' mode (see below).
1096
1096
1097 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1097 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1098 history up to that point and then continues logging.
1098 history up to that point and then continues logging.
1099
1099
1100 %logstart takes a second optional parameter: logging mode. This can be one
1100 %logstart takes a second optional parameter: logging mode. This can be one
1101 of (note that the modes are given unquoted):\\
1101 of (note that the modes are given unquoted):\\
1102 append: well, that says it.\\
1102 append: well, that says it.\\
1103 backup: rename (if exists) to name~ and start name.\\
1103 backup: rename (if exists) to name~ and start name.\\
1104 global: single logfile in your home dir, appended to.\\
1104 global: single logfile in your home dir, appended to.\\
1105 over : overwrite existing log.\\
1105 over : overwrite existing log.\\
1106 rotate: create rotating logs name.1~, name.2~, etc.
1106 rotate: create rotating logs name.1~, name.2~, etc.
1107
1107
1108 Options:
1108 Options:
1109
1109
1110 -o: log also IPython's output. In this mode, all commands which
1110 -o: log also IPython's output. In this mode, all commands which
1111 generate an Out[NN] prompt are recorded to the logfile, right after
1111 generate an Out[NN] prompt are recorded to the logfile, right after
1112 their corresponding input line. The output lines are always
1112 their corresponding input line. The output lines are always
1113 prepended with a '#[Out]# ' marker, so that the log remains valid
1113 prepended with a '#[Out]# ' marker, so that the log remains valid
1114 Python code.
1114 Python code.
1115
1115
1116 Since this marker is always the same, filtering only the output from
1116 Since this marker is always the same, filtering only the output from
1117 a log is very easy, using for example a simple awk call:
1117 a log is very easy, using for example a simple awk call:
1118
1118
1119 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1119 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1120
1120
1121 -r: log 'raw' input. Normally, IPython's logs contain the processed
1121 -r: log 'raw' input. Normally, IPython's logs contain the processed
1122 input, so that user lines are logged in their final form, converted
1122 input, so that user lines are logged in their final form, converted
1123 into valid Python. For example, %Exit is logged as
1123 into valid Python. For example, %Exit is logged as
1124 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1124 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1125 exactly as typed, with no transformations applied.
1125 exactly as typed, with no transformations applied.
1126
1126
1127 -t: put timestamps before each input line logged (these are put in
1127 -t: put timestamps before each input line logged (these are put in
1128 comments)."""
1128 comments)."""
1129
1129
1130 opts,par = self.parse_options(parameter_s,'ort')
1130 opts,par = self.parse_options(parameter_s,'ort')
1131 log_output = 'o' in opts
1131 log_output = 'o' in opts
1132 log_raw_input = 'r' in opts
1132 log_raw_input = 'r' in opts
1133 timestamp = 't' in opts
1133 timestamp = 't' in opts
1134
1134
1135 rc = self.shell.rc
1135 rc = self.shell.rc
1136 logger = self.shell.logger
1136 logger = self.shell.logger
1137
1137
1138 # if no args are given, the defaults set in the logger constructor by
1138 # if no args are given, the defaults set in the logger constructor by
1139 # ipytohn remain valid
1139 # ipytohn remain valid
1140 if par:
1140 if par:
1141 try:
1141 try:
1142 logfname,logmode = par.split()
1142 logfname,logmode = par.split()
1143 except:
1143 except:
1144 logfname = par
1144 logfname = par
1145 logmode = 'backup'
1145 logmode = 'backup'
1146 else:
1146 else:
1147 logfname = logger.logfname
1147 logfname = logger.logfname
1148 logmode = logger.logmode
1148 logmode = logger.logmode
1149 # put logfname into rc struct as if it had been called on the command
1149 # put logfname into rc struct as if it had been called on the command
1150 # line, so it ends up saved in the log header Save it in case we need
1150 # line, so it ends up saved in the log header Save it in case we need
1151 # to restore it...
1151 # to restore it...
1152 old_logfile = rc.opts.get('logfile','')
1152 old_logfile = rc.opts.get('logfile','')
1153 if logfname:
1153 if logfname:
1154 logfname = os.path.expanduser(logfname)
1154 logfname = os.path.expanduser(logfname)
1155 rc.opts.logfile = logfname
1155 rc.opts.logfile = logfname
1156 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1156 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1157 try:
1157 try:
1158 started = logger.logstart(logfname,loghead,logmode,
1158 started = logger.logstart(logfname,loghead,logmode,
1159 log_output,timestamp,log_raw_input)
1159 log_output,timestamp,log_raw_input)
1160 except:
1160 except:
1161 rc.opts.logfile = old_logfile
1161 rc.opts.logfile = old_logfile
1162 warn("Couldn't start log: %s" % sys.exc_info()[1])
1162 warn("Couldn't start log: %s" % sys.exc_info()[1])
1163 else:
1163 else:
1164 # log input history up to this point, optionally interleaving
1164 # log input history up to this point, optionally interleaving
1165 # output if requested
1165 # output if requested
1166
1166
1167 if timestamp:
1167 if timestamp:
1168 # disable timestamping for the previous history, since we've
1168 # disable timestamping for the previous history, since we've
1169 # lost those already (no time machine here).
1169 # lost those already (no time machine here).
1170 logger.timestamp = False
1170 logger.timestamp = False
1171
1171
1172 if log_raw_input:
1172 if log_raw_input:
1173 input_hist = self.shell.input_hist_raw
1173 input_hist = self.shell.input_hist_raw
1174 else:
1174 else:
1175 input_hist = self.shell.input_hist
1175 input_hist = self.shell.input_hist
1176
1176
1177 if log_output:
1177 if log_output:
1178 log_write = logger.log_write
1178 log_write = logger.log_write
1179 output_hist = self.shell.output_hist
1179 output_hist = self.shell.output_hist
1180 for n in range(1,len(input_hist)-1):
1180 for n in range(1,len(input_hist)-1):
1181 log_write(input_hist[n].rstrip())
1181 log_write(input_hist[n].rstrip())
1182 if n in output_hist:
1182 if n in output_hist:
1183 log_write(repr(output_hist[n]),'output')
1183 log_write(repr(output_hist[n]),'output')
1184 else:
1184 else:
1185 logger.log_write(input_hist[1:])
1185 logger.log_write(input_hist[1:])
1186 if timestamp:
1186 if timestamp:
1187 # re-enable timestamping
1187 # re-enable timestamping
1188 logger.timestamp = True
1188 logger.timestamp = True
1189
1189
1190 print ('Activating auto-logging. '
1190 print ('Activating auto-logging. '
1191 'Current session state plus future input saved.')
1191 'Current session state plus future input saved.')
1192 logger.logstate()
1192 logger.logstate()
1193
1193
1194 def magic_logstop(self,parameter_s=''):
1194 def magic_logstop(self,parameter_s=''):
1195 """Fully stop logging and close log file.
1195 """Fully stop logging and close log file.
1196
1196
1197 In order to start logging again, a new %logstart call needs to be made,
1197 In order to start logging again, a new %logstart call needs to be made,
1198 possibly (though not necessarily) with a new filename, mode and other
1198 possibly (though not necessarily) with a new filename, mode and other
1199 options."""
1199 options."""
1200 self.logger.logstop()
1200 self.logger.logstop()
1201
1201
1202 def magic_logoff(self,parameter_s=''):
1202 def magic_logoff(self,parameter_s=''):
1203 """Temporarily stop logging.
1203 """Temporarily stop logging.
1204
1204
1205 You must have previously started logging."""
1205 You must have previously started logging."""
1206 self.shell.logger.switch_log(0)
1206 self.shell.logger.switch_log(0)
1207
1207
1208 def magic_logon(self,parameter_s=''):
1208 def magic_logon(self,parameter_s=''):
1209 """Restart logging.
1209 """Restart logging.
1210
1210
1211 This function is for restarting logging which you've temporarily
1211 This function is for restarting logging which you've temporarily
1212 stopped with %logoff. For starting logging for the first time, you
1212 stopped with %logoff. For starting logging for the first time, you
1213 must use the %logstart function, which allows you to specify an
1213 must use the %logstart function, which allows you to specify an
1214 optional log filename."""
1214 optional log filename."""
1215
1215
1216 self.shell.logger.switch_log(1)
1216 self.shell.logger.switch_log(1)
1217
1217
1218 def magic_logstate(self,parameter_s=''):
1218 def magic_logstate(self,parameter_s=''):
1219 """Print the status of the logging system."""
1219 """Print the status of the logging system."""
1220
1220
1221 self.shell.logger.logstate()
1221 self.shell.logger.logstate()
1222
1222
1223 def magic_pdb(self, parameter_s=''):
1223 def magic_pdb(self, parameter_s=''):
1224 """Control the automatic calling of the pdb interactive debugger.
1224 """Control the automatic calling of the pdb interactive debugger.
1225
1225
1226 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1226 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1227 argument it works as a toggle.
1227 argument it works as a toggle.
1228
1228
1229 When an exception is triggered, IPython can optionally call the
1229 When an exception is triggered, IPython can optionally call the
1230 interactive pdb debugger after the traceback printout. %pdb toggles
1230 interactive pdb debugger after the traceback printout. %pdb toggles
1231 this feature on and off.
1231 this feature on and off.
1232
1232
1233 The initial state of this feature is set in your ipythonrc
1233 The initial state of this feature is set in your ipythonrc
1234 configuration file (the variable is called 'pdb').
1234 configuration file (the variable is called 'pdb').
1235
1235
1236 If you want to just activate the debugger AFTER an exception has fired,
1236 If you want to just activate the debugger AFTER an exception has fired,
1237 without having to type '%pdb on' and rerunning your code, you can use
1237 without having to type '%pdb on' and rerunning your code, you can use
1238 the %debug magic."""
1238 the %debug magic."""
1239
1239
1240 par = parameter_s.strip().lower()
1240 par = parameter_s.strip().lower()
1241
1241
1242 if par:
1242 if par:
1243 try:
1243 try:
1244 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1244 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1245 except KeyError:
1245 except KeyError:
1246 print ('Incorrect argument. Use on/1, off/0, '
1246 print ('Incorrect argument. Use on/1, off/0, '
1247 'or nothing for a toggle.')
1247 'or nothing for a toggle.')
1248 return
1248 return
1249 else:
1249 else:
1250 # toggle
1250 # toggle
1251 new_pdb = not self.shell.call_pdb
1251 new_pdb = not self.shell.call_pdb
1252
1252
1253 # set on the shell
1253 # set on the shell
1254 self.shell.call_pdb = new_pdb
1254 self.shell.call_pdb = new_pdb
1255 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1255 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1256
1256
1257 def magic_debug(self, parameter_s=''):
1257 def magic_debug(self, parameter_s=''):
1258 """Activate the interactive debugger in post-mortem mode.
1258 """Activate the interactive debugger in post-mortem mode.
1259
1259
1260 If an exception has just occurred, this lets you inspect its stack
1260 If an exception has just occurred, this lets you inspect its stack
1261 frames interactively. Note that this will always work only on the last
1261 frames interactively. Note that this will always work only on the last
1262 traceback that occurred, so you must call this quickly after an
1262 traceback that occurred, so you must call this quickly after an
1263 exception that you wish to inspect has fired, because if another one
1263 exception that you wish to inspect has fired, because if another one
1264 occurs, it clobbers the previous one.
1264 occurs, it clobbers the previous one.
1265
1265
1266 If you want IPython to automatically do this on every exception, see
1266 If you want IPython to automatically do this on every exception, see
1267 the %pdb magic for more details.
1267 the %pdb magic for more details.
1268 """
1268 """
1269
1269
1270 self.shell.debugger(force=True)
1270 self.shell.debugger(force=True)
1271
1271
1272 @testdec.skip_doctest
1272 @testdec.skip_doctest
1273 def magic_prun(self, parameter_s ='',user_mode=1,
1273 def magic_prun(self, parameter_s ='',user_mode=1,
1274 opts=None,arg_lst=None,prog_ns=None):
1274 opts=None,arg_lst=None,prog_ns=None):
1275
1275
1276 """Run a statement through the python code profiler.
1276 """Run a statement through the python code profiler.
1277
1277
1278 Usage:
1278 Usage:
1279 %prun [options] statement
1279 %prun [options] statement
1280
1280
1281 The given statement (which doesn't require quote marks) is run via the
1281 The given statement (which doesn't require quote marks) is run via the
1282 python profiler in a manner similar to the profile.run() function.
1282 python profiler in a manner similar to the profile.run() function.
1283 Namespaces are internally managed to work correctly; profile.run
1283 Namespaces are internally managed to work correctly; profile.run
1284 cannot be used in IPython because it makes certain assumptions about
1284 cannot be used in IPython because it makes certain assumptions about
1285 namespaces which do not hold under IPython.
1285 namespaces which do not hold under IPython.
1286
1286
1287 Options:
1287 Options:
1288
1288
1289 -l <limit>: you can place restrictions on what or how much of the
1289 -l <limit>: you can place restrictions on what or how much of the
1290 profile gets printed. The limit value can be:
1290 profile gets printed. The limit value can be:
1291
1291
1292 * A string: only information for function names containing this string
1292 * A string: only information for function names containing this string
1293 is printed.
1293 is printed.
1294
1294
1295 * An integer: only these many lines are printed.
1295 * An integer: only these many lines are printed.
1296
1296
1297 * A float (between 0 and 1): this fraction of the report is printed
1297 * A float (between 0 and 1): this fraction of the report is printed
1298 (for example, use a limit of 0.4 to see the topmost 40% only).
1298 (for example, use a limit of 0.4 to see the topmost 40% only).
1299
1299
1300 You can combine several limits with repeated use of the option. For
1300 You can combine several limits with repeated use of the option. For
1301 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1301 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1302 information about class constructors.
1302 information about class constructors.
1303
1303
1304 -r: return the pstats.Stats object generated by the profiling. This
1304 -r: return the pstats.Stats object generated by the profiling. This
1305 object has all the information about the profile in it, and you can
1305 object has all the information about the profile in it, and you can
1306 later use it for further analysis or in other functions.
1306 later use it for further analysis or in other functions.
1307
1307
1308 -s <key>: sort profile by given key. You can provide more than one key
1308 -s <key>: sort profile by given key. You can provide more than one key
1309 by using the option several times: '-s key1 -s key2 -s key3...'. The
1309 by using the option several times: '-s key1 -s key2 -s key3...'. The
1310 default sorting key is 'time'.
1310 default sorting key is 'time'.
1311
1311
1312 The following is copied verbatim from the profile documentation
1312 The following is copied verbatim from the profile documentation
1313 referenced below:
1313 referenced below:
1314
1314
1315 When more than one key is provided, additional keys are used as
1315 When more than one key is provided, additional keys are used as
1316 secondary criteria when the there is equality in all keys selected
1316 secondary criteria when the there is equality in all keys selected
1317 before them.
1317 before them.
1318
1318
1319 Abbreviations can be used for any key names, as long as the
1319 Abbreviations can be used for any key names, as long as the
1320 abbreviation is unambiguous. The following are the keys currently
1320 abbreviation is unambiguous. The following are the keys currently
1321 defined:
1321 defined:
1322
1322
1323 Valid Arg Meaning
1323 Valid Arg Meaning
1324 "calls" call count
1324 "calls" call count
1325 "cumulative" cumulative time
1325 "cumulative" cumulative time
1326 "file" file name
1326 "file" file name
1327 "module" file name
1327 "module" file name
1328 "pcalls" primitive call count
1328 "pcalls" primitive call count
1329 "line" line number
1329 "line" line number
1330 "name" function name
1330 "name" function name
1331 "nfl" name/file/line
1331 "nfl" name/file/line
1332 "stdname" standard name
1332 "stdname" standard name
1333 "time" internal time
1333 "time" internal time
1334
1334
1335 Note that all sorts on statistics are in descending order (placing
1335 Note that all sorts on statistics are in descending order (placing
1336 most time consuming items first), where as name, file, and line number
1336 most time consuming items first), where as name, file, and line number
1337 searches are in ascending order (i.e., alphabetical). The subtle
1337 searches are in ascending order (i.e., alphabetical). The subtle
1338 distinction between "nfl" and "stdname" is that the standard name is a
1338 distinction between "nfl" and "stdname" is that the standard name is a
1339 sort of the name as printed, which means that the embedded line
1339 sort of the name as printed, which means that the embedded line
1340 numbers get compared in an odd way. For example, lines 3, 20, and 40
1340 numbers get compared in an odd way. For example, lines 3, 20, and 40
1341 would (if the file names were the same) appear in the string order
1341 would (if the file names were the same) appear in the string order
1342 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1342 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1343 line numbers. In fact, sort_stats("nfl") is the same as
1343 line numbers. In fact, sort_stats("nfl") is the same as
1344 sort_stats("name", "file", "line").
1344 sort_stats("name", "file", "line").
1345
1345
1346 -T <filename>: save profile results as shown on screen to a text
1346 -T <filename>: save profile results as shown on screen to a text
1347 file. The profile is still shown on screen.
1347 file. The profile is still shown on screen.
1348
1348
1349 -D <filename>: save (via dump_stats) profile statistics to given
1349 -D <filename>: save (via dump_stats) profile statistics to given
1350 filename. This data is in a format understod by the pstats module, and
1350 filename. This data is in a format understod by the pstats module, and
1351 is generated by a call to the dump_stats() method of profile
1351 is generated by a call to the dump_stats() method of profile
1352 objects. The profile is still shown on screen.
1352 objects. The profile is still shown on screen.
1353
1353
1354 If you want to run complete programs under the profiler's control, use
1354 If you want to run complete programs under the profiler's control, use
1355 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1355 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1356 contains profiler specific options as described here.
1356 contains profiler specific options as described here.
1357
1357
1358 You can read the complete documentation for the profile module with::
1358 You can read the complete documentation for the profile module with::
1359
1359
1360 In [1]: import profile; profile.help()
1360 In [1]: import profile; profile.help()
1361 """
1361 """
1362
1362
1363 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1363 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1364 # protect user quote marks
1364 # protect user quote marks
1365 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1365 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1366
1366
1367 if user_mode: # regular user call
1367 if user_mode: # regular user call
1368 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1368 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1369 list_all=1)
1369 list_all=1)
1370 namespace = self.shell.user_ns
1370 namespace = self.shell.user_ns
1371 else: # called to run a program by %run -p
1371 else: # called to run a program by %run -p
1372 try:
1372 try:
1373 filename = get_py_filename(arg_lst[0])
1373 filename = get_py_filename(arg_lst[0])
1374 except IOError,msg:
1374 except IOError,msg:
1375 error(msg)
1375 error(msg)
1376 return
1376 return
1377
1377
1378 arg_str = 'execfile(filename,prog_ns)'
1378 arg_str = 'execfile(filename,prog_ns)'
1379 namespace = locals()
1379 namespace = locals()
1380
1380
1381 opts.merge(opts_def)
1381 opts.merge(opts_def)
1382
1382
1383 prof = profile.Profile()
1383 prof = profile.Profile()
1384 try:
1384 try:
1385 prof = prof.runctx(arg_str,namespace,namespace)
1385 prof = prof.runctx(arg_str,namespace,namespace)
1386 sys_exit = ''
1386 sys_exit = ''
1387 except SystemExit:
1387 except SystemExit:
1388 sys_exit = """*** SystemExit exception caught in code being profiled."""
1388 sys_exit = """*** SystemExit exception caught in code being profiled."""
1389
1389
1390 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1390 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1391
1391
1392 lims = opts.l
1392 lims = opts.l
1393 if lims:
1393 if lims:
1394 lims = [] # rebuild lims with ints/floats/strings
1394 lims = [] # rebuild lims with ints/floats/strings
1395 for lim in opts.l:
1395 for lim in opts.l:
1396 try:
1396 try:
1397 lims.append(int(lim))
1397 lims.append(int(lim))
1398 except ValueError:
1398 except ValueError:
1399 try:
1399 try:
1400 lims.append(float(lim))
1400 lims.append(float(lim))
1401 except ValueError:
1401 except ValueError:
1402 lims.append(lim)
1402 lims.append(lim)
1403
1403
1404 # Trap output.
1404 # Trap output.
1405 stdout_trap = StringIO()
1405 stdout_trap = StringIO()
1406
1406
1407 if hasattr(stats,'stream'):
1407 if hasattr(stats,'stream'):
1408 # In newer versions of python, the stats object has a 'stream'
1408 # In newer versions of python, the stats object has a 'stream'
1409 # attribute to write into.
1409 # attribute to write into.
1410 stats.stream = stdout_trap
1410 stats.stream = stdout_trap
1411 stats.print_stats(*lims)
1411 stats.print_stats(*lims)
1412 else:
1412 else:
1413 # For older versions, we manually redirect stdout during printing
1413 # For older versions, we manually redirect stdout during printing
1414 sys_stdout = sys.stdout
1414 sys_stdout = sys.stdout
1415 try:
1415 try:
1416 sys.stdout = stdout_trap
1416 sys.stdout = stdout_trap
1417 stats.print_stats(*lims)
1417 stats.print_stats(*lims)
1418 finally:
1418 finally:
1419 sys.stdout = sys_stdout
1419 sys.stdout = sys_stdout
1420
1420
1421 output = stdout_trap.getvalue()
1421 output = stdout_trap.getvalue()
1422 output = output.rstrip()
1422 output = output.rstrip()
1423
1423
1424 page(output,screen_lines=self.shell.rc.screen_length)
1424 page(output,screen_lines=self.shell.rc.screen_length)
1425 print sys_exit,
1425 print sys_exit,
1426
1426
1427 dump_file = opts.D[0]
1427 dump_file = opts.D[0]
1428 text_file = opts.T[0]
1428 text_file = opts.T[0]
1429 if dump_file:
1429 if dump_file:
1430 prof.dump_stats(dump_file)
1430 prof.dump_stats(dump_file)
1431 print '\n*** Profile stats marshalled to file',\
1431 print '\n*** Profile stats marshalled to file',\
1432 `dump_file`+'.',sys_exit
1432 `dump_file`+'.',sys_exit
1433 if text_file:
1433 if text_file:
1434 pfile = file(text_file,'w')
1434 pfile = file(text_file,'w')
1435 pfile.write(output)
1435 pfile.write(output)
1436 pfile.close()
1436 pfile.close()
1437 print '\n*** Profile printout saved to text file',\
1437 print '\n*** Profile printout saved to text file',\
1438 `text_file`+'.',sys_exit
1438 `text_file`+'.',sys_exit
1439
1439
1440 if opts.has_key('r'):
1440 if opts.has_key('r'):
1441 return stats
1441 return stats
1442 else:
1442 else:
1443 return None
1443 return None
1444
1444
1445 @testdec.skip_doctest
1445 @testdec.skip_doctest
1446 def magic_run(self, parameter_s ='',runner=None,
1446 def magic_run(self, parameter_s ='',runner=None,
1447 file_finder=get_py_filename):
1447 file_finder=get_py_filename):
1448 """Run the named file inside IPython as a program.
1448 """Run the named file inside IPython as a program.
1449
1449
1450 Usage:\\
1450 Usage:\\
1451 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1451 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1452
1452
1453 Parameters after the filename are passed as command-line arguments to
1453 Parameters after the filename are passed as command-line arguments to
1454 the program (put in sys.argv). Then, control returns to IPython's
1454 the program (put in sys.argv). Then, control returns to IPython's
1455 prompt.
1455 prompt.
1456
1456
1457 This is similar to running at a system prompt:\\
1457 This is similar to running at a system prompt:\\
1458 $ python file args\\
1458 $ python file args\\
1459 but with the advantage of giving you IPython's tracebacks, and of
1459 but with the advantage of giving you IPython's tracebacks, and of
1460 loading all variables into your interactive namespace for further use
1460 loading all variables into your interactive namespace for further use
1461 (unless -p is used, see below).
1461 (unless -p is used, see below).
1462
1462
1463 The file is executed in a namespace initially consisting only of
1463 The file is executed in a namespace initially consisting only of
1464 __name__=='__main__' and sys.argv constructed as indicated. It thus
1464 __name__=='__main__' and sys.argv constructed as indicated. It thus
1465 sees its environment as if it were being run as a stand-alone program
1465 sees its environment as if it were being run as a stand-alone program
1466 (except for sharing global objects such as previously imported
1466 (except for sharing global objects such as previously imported
1467 modules). But after execution, the IPython interactive namespace gets
1467 modules). But after execution, the IPython interactive namespace gets
1468 updated with all variables defined in the program (except for __name__
1468 updated with all variables defined in the program (except for __name__
1469 and sys.argv). This allows for very convenient loading of code for
1469 and sys.argv). This allows for very convenient loading of code for
1470 interactive work, while giving each program a 'clean sheet' to run in.
1470 interactive work, while giving each program a 'clean sheet' to run in.
1471
1471
1472 Options:
1472 Options:
1473
1473
1474 -n: __name__ is NOT set to '__main__', but to the running file's name
1474 -n: __name__ is NOT set to '__main__', but to the running file's name
1475 without extension (as python does under import). This allows running
1475 without extension (as python does under import). This allows running
1476 scripts and reloading the definitions in them without calling code
1476 scripts and reloading the definitions in them without calling code
1477 protected by an ' if __name__ == "__main__" ' clause.
1477 protected by an ' if __name__ == "__main__" ' clause.
1478
1478
1479 -i: run the file in IPython's namespace instead of an empty one. This
1479 -i: run the file in IPython's namespace instead of an empty one. This
1480 is useful if you are experimenting with code written in a text editor
1480 is useful if you are experimenting with code written in a text editor
1481 which depends on variables defined interactively.
1481 which depends on variables defined interactively.
1482
1482
1483 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1483 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1484 being run. This is particularly useful if IPython is being used to
1484 being run. This is particularly useful if IPython is being used to
1485 run unittests, which always exit with a sys.exit() call. In such
1485 run unittests, which always exit with a sys.exit() call. In such
1486 cases you are interested in the output of the test results, not in
1486 cases you are interested in the output of the test results, not in
1487 seeing a traceback of the unittest module.
1487 seeing a traceback of the unittest module.
1488
1488
1489 -t: print timing information at the end of the run. IPython will give
1489 -t: print timing information at the end of the run. IPython will give
1490 you an estimated CPU time consumption for your script, which under
1490 you an estimated CPU time consumption for your script, which under
1491 Unix uses the resource module to avoid the wraparound problems of
1491 Unix uses the resource module to avoid the wraparound problems of
1492 time.clock(). Under Unix, an estimate of time spent on system tasks
1492 time.clock(). Under Unix, an estimate of time spent on system tasks
1493 is also given (for Windows platforms this is reported as 0.0).
1493 is also given (for Windows platforms this is reported as 0.0).
1494
1494
1495 If -t is given, an additional -N<N> option can be given, where <N>
1495 If -t is given, an additional -N<N> option can be given, where <N>
1496 must be an integer indicating how many times you want the script to
1496 must be an integer indicating how many times you want the script to
1497 run. The final timing report will include total and per run results.
1497 run. The final timing report will include total and per run results.
1498
1498
1499 For example (testing the script uniq_stable.py):
1499 For example (testing the script uniq_stable.py):
1500
1500
1501 In [1]: run -t uniq_stable
1501 In [1]: run -t uniq_stable
1502
1502
1503 IPython CPU timings (estimated):\\
1503 IPython CPU timings (estimated):\\
1504 User : 0.19597 s.\\
1504 User : 0.19597 s.\\
1505 System: 0.0 s.\\
1505 System: 0.0 s.\\
1506
1506
1507 In [2]: run -t -N5 uniq_stable
1507 In [2]: run -t -N5 uniq_stable
1508
1508
1509 IPython CPU timings (estimated):\\
1509 IPython CPU timings (estimated):\\
1510 Total runs performed: 5\\
1510 Total runs performed: 5\\
1511 Times : Total Per run\\
1511 Times : Total Per run\\
1512 User : 0.910862 s, 0.1821724 s.\\
1512 User : 0.910862 s, 0.1821724 s.\\
1513 System: 0.0 s, 0.0 s.
1513 System: 0.0 s, 0.0 s.
1514
1514
1515 -d: run your program under the control of pdb, the Python debugger.
1515 -d: run your program under the control of pdb, the Python debugger.
1516 This allows you to execute your program step by step, watch variables,
1516 This allows you to execute your program step by step, watch variables,
1517 etc. Internally, what IPython does is similar to calling:
1517 etc. Internally, what IPython does is similar to calling:
1518
1518
1519 pdb.run('execfile("YOURFILENAME")')
1519 pdb.run('execfile("YOURFILENAME")')
1520
1520
1521 with a breakpoint set on line 1 of your file. You can change the line
1521 with a breakpoint set on line 1 of your file. You can change the line
1522 number for this automatic breakpoint to be <N> by using the -bN option
1522 number for this automatic breakpoint to be <N> by using the -bN option
1523 (where N must be an integer). For example:
1523 (where N must be an integer). For example:
1524
1524
1525 %run -d -b40 myscript
1525 %run -d -b40 myscript
1526
1526
1527 will set the first breakpoint at line 40 in myscript.py. Note that
1527 will set the first breakpoint at line 40 in myscript.py. Note that
1528 the first breakpoint must be set on a line which actually does
1528 the first breakpoint must be set on a line which actually does
1529 something (not a comment or docstring) for it to stop execution.
1529 something (not a comment or docstring) for it to stop execution.
1530
1530
1531 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1531 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1532 first enter 'c' (without qoutes) to start execution up to the first
1532 first enter 'c' (without qoutes) to start execution up to the first
1533 breakpoint.
1533 breakpoint.
1534
1534
1535 Entering 'help' gives information about the use of the debugger. You
1535 Entering 'help' gives information about the use of the debugger. You
1536 can easily see pdb's full documentation with "import pdb;pdb.help()"
1536 can easily see pdb's full documentation with "import pdb;pdb.help()"
1537 at a prompt.
1537 at a prompt.
1538
1538
1539 -p: run program under the control of the Python profiler module (which
1539 -p: run program under the control of the Python profiler module (which
1540 prints a detailed report of execution times, function calls, etc).
1540 prints a detailed report of execution times, function calls, etc).
1541
1541
1542 You can pass other options after -p which affect the behavior of the
1542 You can pass other options after -p which affect the behavior of the
1543 profiler itself. See the docs for %prun for details.
1543 profiler itself. See the docs for %prun for details.
1544
1544
1545 In this mode, the program's variables do NOT propagate back to the
1545 In this mode, the program's variables do NOT propagate back to the
1546 IPython interactive namespace (because they remain in the namespace
1546 IPython interactive namespace (because they remain in the namespace
1547 where the profiler executes them).
1547 where the profiler executes them).
1548
1548
1549 Internally this triggers a call to %prun, see its documentation for
1549 Internally this triggers a call to %prun, see its documentation for
1550 details on the options available specifically for profiling.
1550 details on the options available specifically for profiling.
1551
1551
1552 There is one special usage for which the text above doesn't apply:
1552 There is one special usage for which the text above doesn't apply:
1553 if the filename ends with .ipy, the file is run as ipython script,
1553 if the filename ends with .ipy, the file is run as ipython script,
1554 just as if the commands were written on IPython prompt.
1554 just as if the commands were written on IPython prompt.
1555 """
1555 """
1556
1556
1557 # get arguments and set sys.argv for program to be run.
1557 # get arguments and set sys.argv for program to be run.
1558 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1558 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1559 mode='list',list_all=1)
1559 mode='list',list_all=1)
1560
1560
1561 try:
1561 try:
1562 filename = file_finder(arg_lst[0])
1562 filename = file_finder(arg_lst[0])
1563 except IndexError:
1563 except IndexError:
1564 warn('you must provide at least a filename.')
1564 warn('you must provide at least a filename.')
1565 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1565 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1566 return
1566 return
1567 except IOError,msg:
1567 except IOError,msg:
1568 error(msg)
1568 error(msg)
1569 return
1569 return
1570
1570
1571 if filename.lower().endswith('.ipy'):
1571 if filename.lower().endswith('.ipy'):
1572 self.api.runlines(open(filename).read())
1572 self.api.runlines(open(filename).read())
1573 return
1573 return
1574
1574
1575 # Control the response to exit() calls made by the script being run
1575 # Control the response to exit() calls made by the script being run
1576 exit_ignore = opts.has_key('e')
1576 exit_ignore = opts.has_key('e')
1577
1577
1578 # Make sure that the running script gets a proper sys.argv as if it
1578 # Make sure that the running script gets a proper sys.argv as if it
1579 # were run from a system shell.
1579 # were run from a system shell.
1580 save_argv = sys.argv # save it for later restoring
1580 save_argv = sys.argv # save it for later restoring
1581 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1581 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1582
1582
1583 if opts.has_key('i'):
1583 if opts.has_key('i'):
1584 # Run in user's interactive namespace
1584 # Run in user's interactive namespace
1585 prog_ns = self.shell.user_ns
1585 prog_ns = self.shell.user_ns
1586 __name__save = self.shell.user_ns['__name__']
1586 __name__save = self.shell.user_ns['__name__']
1587 prog_ns['__name__'] = '__main__'
1587 prog_ns['__name__'] = '__main__'
1588 main_mod = self.shell.new_main_mod(prog_ns)
1588 main_mod = self.shell.new_main_mod(prog_ns)
1589 else:
1589 else:
1590 # Run in a fresh, empty namespace
1590 # Run in a fresh, empty namespace
1591 if opts.has_key('n'):
1591 if opts.has_key('n'):
1592 name = os.path.splitext(os.path.basename(filename))[0]
1592 name = os.path.splitext(os.path.basename(filename))[0]
1593 else:
1593 else:
1594 name = '__main__'
1594 name = '__main__'
1595
1595
1596 main_mod = self.shell.new_main_mod()
1596 main_mod = self.shell.new_main_mod()
1597 prog_ns = main_mod.__dict__
1597 prog_ns = main_mod.__dict__
1598 prog_ns['__name__'] = name
1598 prog_ns['__name__'] = name
1599
1599
1600 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1600 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1601 # set the __file__ global in the script's namespace
1601 # set the __file__ global in the script's namespace
1602 prog_ns['__file__'] = filename
1602 prog_ns['__file__'] = filename
1603
1603
1604 # pickle fix. See iplib for an explanation. But we need to make sure
1604 # pickle fix. See iplib for an explanation. But we need to make sure
1605 # that, if we overwrite __main__, we replace it at the end
1605 # that, if we overwrite __main__, we replace it at the end
1606 main_mod_name = prog_ns['__name__']
1606 main_mod_name = prog_ns['__name__']
1607
1607
1608 if main_mod_name == '__main__':
1608 if main_mod_name == '__main__':
1609 restore_main = sys.modules['__main__']
1609 restore_main = sys.modules['__main__']
1610 else:
1610 else:
1611 restore_main = False
1611 restore_main = False
1612
1612
1613 # This needs to be undone at the end to prevent holding references to
1613 # This needs to be undone at the end to prevent holding references to
1614 # every single object ever created.
1614 # every single object ever created.
1615 sys.modules[main_mod_name] = main_mod
1615 sys.modules[main_mod_name] = main_mod
1616
1616
1617 stats = None
1617 stats = None
1618 try:
1618 try:
1619 self.shell.savehist()
1619 self.shell.savehist()
1620
1620
1621 if opts.has_key('p'):
1621 if opts.has_key('p'):
1622 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1622 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1623 else:
1623 else:
1624 if opts.has_key('d'):
1624 if opts.has_key('d'):
1625 deb = debugger.Pdb(self.shell.rc.colors)
1625 deb = debugger.Pdb(self.shell.rc.colors)
1626 # reset Breakpoint state, which is moronically kept
1626 # reset Breakpoint state, which is moronically kept
1627 # in a class
1627 # in a class
1628 bdb.Breakpoint.next = 1
1628 bdb.Breakpoint.next = 1
1629 bdb.Breakpoint.bplist = {}
1629 bdb.Breakpoint.bplist = {}
1630 bdb.Breakpoint.bpbynumber = [None]
1630 bdb.Breakpoint.bpbynumber = [None]
1631 # Set an initial breakpoint to stop execution
1631 # Set an initial breakpoint to stop execution
1632 maxtries = 10
1632 maxtries = 10
1633 bp = int(opts.get('b',[1])[0])
1633 bp = int(opts.get('b',[1])[0])
1634 checkline = deb.checkline(filename,bp)
1634 checkline = deb.checkline(filename,bp)
1635 if not checkline:
1635 if not checkline:
1636 for bp in range(bp+1,bp+maxtries+1):
1636 for bp in range(bp+1,bp+maxtries+1):
1637 if deb.checkline(filename,bp):
1637 if deb.checkline(filename,bp):
1638 break
1638 break
1639 else:
1639 else:
1640 msg = ("\nI failed to find a valid line to set "
1640 msg = ("\nI failed to find a valid line to set "
1641 "a breakpoint\n"
1641 "a breakpoint\n"
1642 "after trying up to line: %s.\n"
1642 "after trying up to line: %s.\n"
1643 "Please set a valid breakpoint manually "
1643 "Please set a valid breakpoint manually "
1644 "with the -b option." % bp)
1644 "with the -b option." % bp)
1645 error(msg)
1645 error(msg)
1646 return
1646 return
1647 # if we find a good linenumber, set the breakpoint
1647 # if we find a good linenumber, set the breakpoint
1648 deb.do_break('%s:%s' % (filename,bp))
1648 deb.do_break('%s:%s' % (filename,bp))
1649 # Start file run
1649 # Start file run
1650 print "NOTE: Enter 'c' at the",
1650 print "NOTE: Enter 'c' at the",
1651 print "%s prompt to start your script." % deb.prompt
1651 print "%s prompt to start your script." % deb.prompt
1652 try:
1652 try:
1653 deb.run('execfile("%s")' % filename,prog_ns)
1653 deb.run('execfile("%s")' % filename,prog_ns)
1654
1654
1655 except:
1655 except:
1656 etype, value, tb = sys.exc_info()
1656 etype, value, tb = sys.exc_info()
1657 # Skip three frames in the traceback: the %run one,
1657 # Skip three frames in the traceback: the %run one,
1658 # one inside bdb.py, and the command-line typed by the
1658 # one inside bdb.py, and the command-line typed by the
1659 # user (run by exec in pdb itself).
1659 # user (run by exec in pdb itself).
1660 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1660 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1661 else:
1661 else:
1662 if runner is None:
1662 if runner is None:
1663 runner = self.shell.safe_execfile
1663 runner = self.shell.safe_execfile
1664 if opts.has_key('t'):
1664 if opts.has_key('t'):
1665 # timed execution
1665 # timed execution
1666 try:
1666 try:
1667 nruns = int(opts['N'][0])
1667 nruns = int(opts['N'][0])
1668 if nruns < 1:
1668 if nruns < 1:
1669 error('Number of runs must be >=1')
1669 error('Number of runs must be >=1')
1670 return
1670 return
1671 except (KeyError):
1671 except (KeyError):
1672 nruns = 1
1672 nruns = 1
1673 if nruns == 1:
1673 if nruns == 1:
1674 t0 = clock2()
1674 t0 = clock2()
1675 runner(filename,prog_ns,prog_ns,
1675 runner(filename,prog_ns,prog_ns,
1676 exit_ignore=exit_ignore)
1676 exit_ignore=exit_ignore)
1677 t1 = clock2()
1677 t1 = clock2()
1678 t_usr = t1[0]-t0[0]
1678 t_usr = t1[0]-t0[0]
1679 t_sys = t1[1]-t0[1]
1679 t_sys = t1[1]-t0[1]
1680 print "\nIPython CPU timings (estimated):"
1680 print "\nIPython CPU timings (estimated):"
1681 print " User : %10s s." % t_usr
1681 print " User : %10s s." % t_usr
1682 print " System: %10s s." % t_sys
1682 print " System: %10s s." % t_sys
1683 else:
1683 else:
1684 runs = range(nruns)
1684 runs = range(nruns)
1685 t0 = clock2()
1685 t0 = clock2()
1686 for nr in runs:
1686 for nr in runs:
1687 runner(filename,prog_ns,prog_ns,
1687 runner(filename,prog_ns,prog_ns,
1688 exit_ignore=exit_ignore)
1688 exit_ignore=exit_ignore)
1689 t1 = clock2()
1689 t1 = clock2()
1690 t_usr = t1[0]-t0[0]
1690 t_usr = t1[0]-t0[0]
1691 t_sys = t1[1]-t0[1]
1691 t_sys = t1[1]-t0[1]
1692 print "\nIPython CPU timings (estimated):"
1692 print "\nIPython CPU timings (estimated):"
1693 print "Total runs performed:",nruns
1693 print "Total runs performed:",nruns
1694 print " Times : %10s %10s" % ('Total','Per run')
1694 print " Times : %10s %10s" % ('Total','Per run')
1695 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1695 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1696 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1696 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1697
1697
1698 else:
1698 else:
1699 # regular execution
1699 # regular execution
1700 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1700 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1701
1701
1702 if opts.has_key('i'):
1702 if opts.has_key('i'):
1703 self.shell.user_ns['__name__'] = __name__save
1703 self.shell.user_ns['__name__'] = __name__save
1704 else:
1704 else:
1705 # The shell MUST hold a reference to prog_ns so after %run
1705 # The shell MUST hold a reference to prog_ns so after %run
1706 # exits, the python deletion mechanism doesn't zero it out
1706 # exits, the python deletion mechanism doesn't zero it out
1707 # (leaving dangling references).
1707 # (leaving dangling references).
1708 self.shell.cache_main_mod(prog_ns,filename)
1708 self.shell.cache_main_mod(prog_ns,filename)
1709 # update IPython interactive namespace
1709 # update IPython interactive namespace
1710 del prog_ns['__name__']
1710 del prog_ns['__name__']
1711 self.shell.user_ns.update(prog_ns)
1711 self.shell.user_ns.update(prog_ns)
1712 finally:
1712 finally:
1713 # It's a bit of a mystery why, but __builtins__ can change from
1713 # It's a bit of a mystery why, but __builtins__ can change from
1714 # being a module to becoming a dict missing some key data after
1714 # being a module to becoming a dict missing some key data after
1715 # %run. As best I can see, this is NOT something IPython is doing
1715 # %run. As best I can see, this is NOT something IPython is doing
1716 # at all, and similar problems have been reported before:
1716 # at all, and similar problems have been reported before:
1717 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1717 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1718 # Since this seems to be done by the interpreter itself, the best
1718 # Since this seems to be done by the interpreter itself, the best
1719 # we can do is to at least restore __builtins__ for the user on
1719 # we can do is to at least restore __builtins__ for the user on
1720 # exit.
1720 # exit.
1721 self.shell.user_ns['__builtins__'] = __builtin__
1721 self.shell.user_ns['__builtins__'] = __builtin__
1722
1722
1723 # Ensure key global structures are restored
1723 # Ensure key global structures are restored
1724 sys.argv = save_argv
1724 sys.argv = save_argv
1725 if restore_main:
1725 if restore_main:
1726 sys.modules['__main__'] = restore_main
1726 sys.modules['__main__'] = restore_main
1727 else:
1727 else:
1728 # Remove from sys.modules the reference to main_mod we'd
1728 # Remove from sys.modules the reference to main_mod we'd
1729 # added. Otherwise it will trap references to objects
1729 # added. Otherwise it will trap references to objects
1730 # contained therein.
1730 # contained therein.
1731 del sys.modules[main_mod_name]
1731 del sys.modules[main_mod_name]
1732
1732
1733 self.shell.reloadhist()
1733 self.shell.reloadhist()
1734
1734
1735 return stats
1735 return stats
1736
1736
1737 def magic_runlog(self, parameter_s =''):
1737 def magic_runlog(self, parameter_s =''):
1738 """Run files as logs.
1738 """Run files as logs.
1739
1739
1740 Usage:\\
1740 Usage:\\
1741 %runlog file1 file2 ...
1741 %runlog file1 file2 ...
1742
1742
1743 Run the named files (treating them as log files) in sequence inside
1743 Run the named files (treating them as log files) in sequence inside
1744 the interpreter, and return to the prompt. This is much slower than
1744 the interpreter, and return to the prompt. This is much slower than
1745 %run because each line is executed in a try/except block, but it
1745 %run because each line is executed in a try/except block, but it
1746 allows running files with syntax errors in them.
1746 allows running files with syntax errors in them.
1747
1747
1748 Normally IPython will guess when a file is one of its own logfiles, so
1748 Normally IPython will guess when a file is one of its own logfiles, so
1749 you can typically use %run even for logs. This shorthand allows you to
1749 you can typically use %run even for logs. This shorthand allows you to
1750 force any file to be treated as a log file."""
1750 force any file to be treated as a log file."""
1751
1751
1752 for f in parameter_s.split():
1752 for f in parameter_s.split():
1753 self.shell.safe_execfile(f,self.shell.user_ns,
1753 self.shell.safe_execfile(f,self.shell.user_ns,
1754 self.shell.user_ns,islog=1)
1754 self.shell.user_ns,islog=1)
1755
1755
1756 @testdec.skip_doctest
1756 @testdec.skip_doctest
1757 def magic_timeit(self, parameter_s =''):
1757 def magic_timeit(self, parameter_s =''):
1758 """Time execution of a Python statement or expression
1758 """Time execution of a Python statement or expression
1759
1759
1760 Usage:\\
1760 Usage:\\
1761 %timeit [-n<N> -r<R> [-t|-c]] statement
1761 %timeit [-n<N> -r<R> [-t|-c]] statement
1762
1762
1763 Time execution of a Python statement or expression using the timeit
1763 Time execution of a Python statement or expression using the timeit
1764 module.
1764 module.
1765
1765
1766 Options:
1766 Options:
1767 -n<N>: execute the given statement <N> times in a loop. If this value
1767 -n<N>: execute the given statement <N> times in a loop. If this value
1768 is not given, a fitting value is chosen.
1768 is not given, a fitting value is chosen.
1769
1769
1770 -r<R>: repeat the loop iteration <R> times and take the best result.
1770 -r<R>: repeat the loop iteration <R> times and take the best result.
1771 Default: 3
1771 Default: 3
1772
1772
1773 -t: use time.time to measure the time, which is the default on Unix.
1773 -t: use time.time to measure the time, which is the default on Unix.
1774 This function measures wall time.
1774 This function measures wall time.
1775
1775
1776 -c: use time.clock to measure the time, which is the default on
1776 -c: use time.clock to measure the time, which is the default on
1777 Windows and measures wall time. On Unix, resource.getrusage is used
1777 Windows and measures wall time. On Unix, resource.getrusage is used
1778 instead and returns the CPU user time.
1778 instead and returns the CPU user time.
1779
1779
1780 -p<P>: use a precision of <P> digits to display the timing result.
1780 -p<P>: use a precision of <P> digits to display the timing result.
1781 Default: 3
1781 Default: 3
1782
1782
1783
1783
1784 Examples:
1784 Examples:
1785
1785
1786 In [1]: %timeit pass
1786 In [1]: %timeit pass
1787 10000000 loops, best of 3: 53.3 ns per loop
1787 10000000 loops, best of 3: 53.3 ns per loop
1788
1788
1789 In [2]: u = None
1789 In [2]: u = None
1790
1790
1791 In [3]: %timeit u is None
1791 In [3]: %timeit u is None
1792 10000000 loops, best of 3: 184 ns per loop
1792 10000000 loops, best of 3: 184 ns per loop
1793
1793
1794 In [4]: %timeit -r 4 u == None
1794 In [4]: %timeit -r 4 u == None
1795 1000000 loops, best of 4: 242 ns per loop
1795 1000000 loops, best of 4: 242 ns per loop
1796
1796
1797 In [5]: import time
1797 In [5]: import time
1798
1798
1799 In [6]: %timeit -n1 time.sleep(2)
1799 In [6]: %timeit -n1 time.sleep(2)
1800 1 loops, best of 3: 2 s per loop
1800 1 loops, best of 3: 2 s per loop
1801
1801
1802
1802
1803 The times reported by %timeit will be slightly higher than those
1803 The times reported by %timeit will be slightly higher than those
1804 reported by the timeit.py script when variables are accessed. This is
1804 reported by the timeit.py script when variables are accessed. This is
1805 due to the fact that %timeit executes the statement in the namespace
1805 due to the fact that %timeit executes the statement in the namespace
1806 of the shell, compared with timeit.py, which uses a single setup
1806 of the shell, compared with timeit.py, which uses a single setup
1807 statement to import function or create variables. Generally, the bias
1807 statement to import function or create variables. Generally, the bias
1808 does not matter as long as results from timeit.py are not mixed with
1808 does not matter as long as results from timeit.py are not mixed with
1809 those from %timeit."""
1809 those from %timeit."""
1810
1810
1811 import timeit
1811 import timeit
1812 import math
1812 import math
1813
1813
1814 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1814 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1815 # certain terminals. Until we figure out a robust way of
1815 # certain terminals. Until we figure out a robust way of
1816 # auto-detecting if the terminal can deal with it, use plain 'us' for
1816 # auto-detecting if the terminal can deal with it, use plain 'us' for
1817 # microseconds. I am really NOT happy about disabling the proper
1817 # microseconds. I am really NOT happy about disabling the proper
1818 # 'micro' prefix, but crashing is worse... If anyone knows what the
1818 # 'micro' prefix, but crashing is worse... If anyone knows what the
1819 # right solution for this is, I'm all ears...
1819 # right solution for this is, I'm all ears...
1820 #
1820 #
1821 # Note: using
1821 # Note: using
1822 #
1822 #
1823 # s = u'\xb5'
1823 # s = u'\xb5'
1824 # s.encode(sys.getdefaultencoding())
1824 # s.encode(sys.getdefaultencoding())
1825 #
1825 #
1826 # is not sufficient, as I've seen terminals where that fails but
1826 # is not sufficient, as I've seen terminals where that fails but
1827 # print s
1827 # print s
1828 #
1828 #
1829 # succeeds
1829 # succeeds
1830 #
1830 #
1831 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1831 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1832
1832
1833 #units = [u"s", u"ms",u'\xb5',"ns"]
1833 #units = [u"s", u"ms",u'\xb5',"ns"]
1834 units = [u"s", u"ms",u'us',"ns"]
1834 units = [u"s", u"ms",u'us',"ns"]
1835
1835
1836 scaling = [1, 1e3, 1e6, 1e9]
1836 scaling = [1, 1e3, 1e6, 1e9]
1837
1837
1838 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1838 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1839 posix=False)
1839 posix=False)
1840 if stmt == "":
1840 if stmt == "":
1841 return
1841 return
1842 timefunc = timeit.default_timer
1842 timefunc = timeit.default_timer
1843 number = int(getattr(opts, "n", 0))
1843 number = int(getattr(opts, "n", 0))
1844 repeat = int(getattr(opts, "r", timeit.default_repeat))
1844 repeat = int(getattr(opts, "r", timeit.default_repeat))
1845 precision = int(getattr(opts, "p", 3))
1845 precision = int(getattr(opts, "p", 3))
1846 if hasattr(opts, "t"):
1846 if hasattr(opts, "t"):
1847 timefunc = time.time
1847 timefunc = time.time
1848 if hasattr(opts, "c"):
1848 if hasattr(opts, "c"):
1849 timefunc = clock
1849 timefunc = clock
1850
1850
1851 timer = timeit.Timer(timer=timefunc)
1851 timer = timeit.Timer(timer=timefunc)
1852 # this code has tight coupling to the inner workings of timeit.Timer,
1852 # this code has tight coupling to the inner workings of timeit.Timer,
1853 # but is there a better way to achieve that the code stmt has access
1853 # but is there a better way to achieve that the code stmt has access
1854 # to the shell namespace?
1854 # to the shell namespace?
1855
1855
1856 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1856 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1857 'setup': "pass"}
1857 'setup': "pass"}
1858 # Track compilation time so it can be reported if too long
1858 # Track compilation time so it can be reported if too long
1859 # Minimum time above which compilation time will be reported
1859 # Minimum time above which compilation time will be reported
1860 tc_min = 0.1
1860 tc_min = 0.1
1861
1861
1862 t0 = clock()
1862 t0 = clock()
1863 code = compile(src, "<magic-timeit>", "exec")
1863 code = compile(src, "<magic-timeit>", "exec")
1864 tc = clock()-t0
1864 tc = clock()-t0
1865
1865
1866 ns = {}
1866 ns = {}
1867 exec code in self.shell.user_ns, ns
1867 exec code in self.shell.user_ns, ns
1868 timer.inner = ns["inner"]
1868 timer.inner = ns["inner"]
1869
1869
1870 if number == 0:
1870 if number == 0:
1871 # determine number so that 0.2 <= total time < 2.0
1871 # determine number so that 0.2 <= total time < 2.0
1872 number = 1
1872 number = 1
1873 for i in range(1, 10):
1873 for i in range(1, 10):
1874 if timer.timeit(number) >= 0.2:
1874 if timer.timeit(number) >= 0.2:
1875 break
1875 break
1876 number *= 10
1876 number *= 10
1877
1877
1878 best = min(timer.repeat(repeat, number)) / number
1878 best = min(timer.repeat(repeat, number)) / number
1879
1879
1880 if best > 0.0:
1880 if best > 0.0:
1881 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1881 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1882 else:
1882 else:
1883 order = 3
1883 order = 3
1884 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1884 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1885 precision,
1885 precision,
1886 best * scaling[order],
1886 best * scaling[order],
1887 units[order])
1887 units[order])
1888 if tc > tc_min:
1888 if tc > tc_min:
1889 print "Compiler time: %.2f s" % tc
1889 print "Compiler time: %.2f s" % tc
1890
1890
1891 @testdec.skip_doctest
1891 @testdec.skip_doctest
1892 def magic_time(self,parameter_s = ''):
1892 def magic_time(self,parameter_s = ''):
1893 """Time execution of a Python statement or expression.
1893 """Time execution of a Python statement or expression.
1894
1894
1895 The CPU and wall clock times are printed, and the value of the
1895 The CPU and wall clock times are printed, and the value of the
1896 expression (if any) is returned. Note that under Win32, system time
1896 expression (if any) is returned. Note that under Win32, system time
1897 is always reported as 0, since it can not be measured.
1897 is always reported as 0, since it can not be measured.
1898
1898
1899 This function provides very basic timing functionality. In Python
1899 This function provides very basic timing functionality. In Python
1900 2.3, the timeit module offers more control and sophistication, so this
1900 2.3, the timeit module offers more control and sophistication, so this
1901 could be rewritten to use it (patches welcome).
1901 could be rewritten to use it (patches welcome).
1902
1902
1903 Some examples:
1903 Some examples:
1904
1904
1905 In [1]: time 2**128
1905 In [1]: time 2**128
1906 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1906 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1907 Wall time: 0.00
1907 Wall time: 0.00
1908 Out[1]: 340282366920938463463374607431768211456L
1908 Out[1]: 340282366920938463463374607431768211456L
1909
1909
1910 In [2]: n = 1000000
1910 In [2]: n = 1000000
1911
1911
1912 In [3]: time sum(range(n))
1912 In [3]: time sum(range(n))
1913 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1913 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1914 Wall time: 1.37
1914 Wall time: 1.37
1915 Out[3]: 499999500000L
1915 Out[3]: 499999500000L
1916
1916
1917 In [4]: time print 'hello world'
1917 In [4]: time print 'hello world'
1918 hello world
1918 hello world
1919 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1919 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1920 Wall time: 0.00
1920 Wall time: 0.00
1921
1921
1922 Note that the time needed by Python to compile the given expression
1922 Note that the time needed by Python to compile the given expression
1923 will be reported if it is more than 0.1s. In this example, the
1923 will be reported if it is more than 0.1s. In this example, the
1924 actual exponentiation is done by Python at compilation time, so while
1924 actual exponentiation is done by Python at compilation time, so while
1925 the expression can take a noticeable amount of time to compute, that
1925 the expression can take a noticeable amount of time to compute, that
1926 time is purely due to the compilation:
1926 time is purely due to the compilation:
1927
1927
1928 In [5]: time 3**9999;
1928 In [5]: time 3**9999;
1929 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1929 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1930 Wall time: 0.00 s
1930 Wall time: 0.00 s
1931
1931
1932 In [6]: time 3**999999;
1932 In [6]: time 3**999999;
1933 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1933 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1934 Wall time: 0.00 s
1934 Wall time: 0.00 s
1935 Compiler : 0.78 s
1935 Compiler : 0.78 s
1936 """
1936 """
1937
1937
1938 # fail immediately if the given expression can't be compiled
1938 # fail immediately if the given expression can't be compiled
1939
1939
1940 expr = self.shell.prefilter(parameter_s,False)
1940 expr = self.shell.prefilter(parameter_s,False)
1941
1941
1942 # Minimum time above which compilation time will be reported
1942 # Minimum time above which compilation time will be reported
1943 tc_min = 0.1
1943 tc_min = 0.1
1944
1944
1945 try:
1945 try:
1946 mode = 'eval'
1946 mode = 'eval'
1947 t0 = clock()
1947 t0 = clock()
1948 code = compile(expr,'<timed eval>',mode)
1948 code = compile(expr,'<timed eval>',mode)
1949 tc = clock()-t0
1949 tc = clock()-t0
1950 except SyntaxError:
1950 except SyntaxError:
1951 mode = 'exec'
1951 mode = 'exec'
1952 t0 = clock()
1952 t0 = clock()
1953 code = compile(expr,'<timed exec>',mode)
1953 code = compile(expr,'<timed exec>',mode)
1954 tc = clock()-t0
1954 tc = clock()-t0
1955 # skew measurement as little as possible
1955 # skew measurement as little as possible
1956 glob = self.shell.user_ns
1956 glob = self.shell.user_ns
1957 clk = clock2
1957 clk = clock2
1958 wtime = time.time
1958 wtime = time.time
1959 # time execution
1959 # time execution
1960 wall_st = wtime()
1960 wall_st = wtime()
1961 if mode=='eval':
1961 if mode=='eval':
1962 st = clk()
1962 st = clk()
1963 out = eval(code,glob)
1963 out = eval(code,glob)
1964 end = clk()
1964 end = clk()
1965 else:
1965 else:
1966 st = clk()
1966 st = clk()
1967 exec code in glob
1967 exec code in glob
1968 end = clk()
1968 end = clk()
1969 out = None
1969 out = None
1970 wall_end = wtime()
1970 wall_end = wtime()
1971 # Compute actual times and report
1971 # Compute actual times and report
1972 wall_time = wall_end-wall_st
1972 wall_time = wall_end-wall_st
1973 cpu_user = end[0]-st[0]
1973 cpu_user = end[0]-st[0]
1974 cpu_sys = end[1]-st[1]
1974 cpu_sys = end[1]-st[1]
1975 cpu_tot = cpu_user+cpu_sys
1975 cpu_tot = cpu_user+cpu_sys
1976 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1976 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1977 (cpu_user,cpu_sys,cpu_tot)
1977 (cpu_user,cpu_sys,cpu_tot)
1978 print "Wall time: %.2f s" % wall_time
1978 print "Wall time: %.2f s" % wall_time
1979 if tc > tc_min:
1979 if tc > tc_min:
1980 print "Compiler : %.2f s" % tc
1980 print "Compiler : %.2f s" % tc
1981 return out
1981 return out
1982
1982
1983 @testdec.skip_doctest
1983 @testdec.skip_doctest
1984 def magic_macro(self,parameter_s = ''):
1984 def magic_macro(self,parameter_s = ''):
1985 """Define a set of input lines as a macro for future re-execution.
1985 """Define a set of input lines as a macro for future re-execution.
1986
1986
1987 Usage:\\
1987 Usage:\\
1988 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1988 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1989
1989
1990 Options:
1990 Options:
1991
1991
1992 -r: use 'raw' input. By default, the 'processed' history is used,
1992 -r: use 'raw' input. By default, the 'processed' history is used,
1993 so that magics are loaded in their transformed version to valid
1993 so that magics are loaded in their transformed version to valid
1994 Python. If this option is given, the raw input as typed as the
1994 Python. If this option is given, the raw input as typed as the
1995 command line is used instead.
1995 command line is used instead.
1996
1996
1997 This will define a global variable called `name` which is a string
1997 This will define a global variable called `name` which is a string
1998 made of joining the slices and lines you specify (n1,n2,... numbers
1998 made of joining the slices and lines you specify (n1,n2,... numbers
1999 above) from your input history into a single string. This variable
1999 above) from your input history into a single string. This variable
2000 acts like an automatic function which re-executes those lines as if
2000 acts like an automatic function which re-executes those lines as if
2001 you had typed them. You just type 'name' at the prompt and the code
2001 you had typed them. You just type 'name' at the prompt and the code
2002 executes.
2002 executes.
2003
2003
2004 The notation for indicating number ranges is: n1-n2 means 'use line
2004 The notation for indicating number ranges is: n1-n2 means 'use line
2005 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2005 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2006 using the lines numbered 5,6 and 7.
2006 using the lines numbered 5,6 and 7.
2007
2007
2008 Note: as a 'hidden' feature, you can also use traditional python slice
2008 Note: as a 'hidden' feature, you can also use traditional python slice
2009 notation, where N:M means numbers N through M-1.
2009 notation, where N:M means numbers N through M-1.
2010
2010
2011 For example, if your history contains (%hist prints it):
2011 For example, if your history contains (%hist prints it):
2012
2012
2013 44: x=1
2013 44: x=1
2014 45: y=3
2014 45: y=3
2015 46: z=x+y
2015 46: z=x+y
2016 47: print x
2016 47: print x
2017 48: a=5
2017 48: a=5
2018 49: print 'x',x,'y',y
2018 49: print 'x',x,'y',y
2019
2019
2020 you can create a macro with lines 44 through 47 (included) and line 49
2020 you can create a macro with lines 44 through 47 (included) and line 49
2021 called my_macro with:
2021 called my_macro with:
2022
2022
2023 In [55]: %macro my_macro 44-47 49
2023 In [55]: %macro my_macro 44-47 49
2024
2024
2025 Now, typing `my_macro` (without quotes) will re-execute all this code
2025 Now, typing `my_macro` (without quotes) will re-execute all this code
2026 in one pass.
2026 in one pass.
2027
2027
2028 You don't need to give the line-numbers in order, and any given line
2028 You don't need to give the line-numbers in order, and any given line
2029 number can appear multiple times. You can assemble macros with any
2029 number can appear multiple times. You can assemble macros with any
2030 lines from your input history in any order.
2030 lines from your input history in any order.
2031
2031
2032 The macro is a simple object which holds its value in an attribute,
2032 The macro is a simple object which holds its value in an attribute,
2033 but IPython's display system checks for macros and executes them as
2033 but IPython's display system checks for macros and executes them as
2034 code instead of printing them when you type their name.
2034 code instead of printing them when you type their name.
2035
2035
2036 You can view a macro's contents by explicitly printing it with:
2036 You can view a macro's contents by explicitly printing it with:
2037
2037
2038 'print macro_name'.
2038 'print macro_name'.
2039
2039
2040 For one-off cases which DON'T contain magic function calls in them you
2040 For one-off cases which DON'T contain magic function calls in them you
2041 can obtain similar results by explicitly executing slices from your
2041 can obtain similar results by explicitly executing slices from your
2042 input history with:
2042 input history with:
2043
2043
2044 In [60]: exec In[44:48]+In[49]"""
2044 In [60]: exec In[44:48]+In[49]"""
2045
2045
2046 opts,args = self.parse_options(parameter_s,'r',mode='list')
2046 opts,args = self.parse_options(parameter_s,'r',mode='list')
2047 if not args:
2047 if not args:
2048 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2048 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2049 macs.sort()
2049 macs.sort()
2050 return macs
2050 return macs
2051 if len(args) == 1:
2051 if len(args) == 1:
2052 raise UsageError(
2052 raise UsageError(
2053 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2053 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2054 name,ranges = args[0], args[1:]
2054 name,ranges = args[0], args[1:]
2055
2055
2056 #print 'rng',ranges # dbg
2056 #print 'rng',ranges # dbg
2057 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2057 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2058 macro = Macro(lines)
2058 macro = Macro(lines)
2059 self.shell.user_ns.update({name:macro})
2059 self.shell.user_ns.update({name:macro})
2060 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2060 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2061 print 'Macro contents:'
2061 print 'Macro contents:'
2062 print macro,
2062 print macro,
2063
2063
2064 def magic_save(self,parameter_s = ''):
2064 def magic_save(self,parameter_s = ''):
2065 """Save a set of lines to a given filename.
2065 """Save a set of lines to a given filename.
2066
2066
2067 Usage:\\
2067 Usage:\\
2068 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2068 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2069
2069
2070 Options:
2070 Options:
2071
2071
2072 -r: use 'raw' input. By default, the 'processed' history is used,
2072 -r: use 'raw' input. By default, the 'processed' history is used,
2073 so that magics are loaded in their transformed version to valid
2073 so that magics are loaded in their transformed version to valid
2074 Python. If this option is given, the raw input as typed as the
2074 Python. If this option is given, the raw input as typed as the
2075 command line is used instead.
2075 command line is used instead.
2076
2076
2077 This function uses the same syntax as %macro for line extraction, but
2077 This function uses the same syntax as %macro for line extraction, but
2078 instead of creating a macro it saves the resulting string to the
2078 instead of creating a macro it saves the resulting string to the
2079 filename you specify.
2079 filename you specify.
2080
2080
2081 It adds a '.py' extension to the file if you don't do so yourself, and
2081 It adds a '.py' extension to the file if you don't do so yourself, and
2082 it asks for confirmation before overwriting existing files."""
2082 it asks for confirmation before overwriting existing files."""
2083
2083
2084 opts,args = self.parse_options(parameter_s,'r',mode='list')
2084 opts,args = self.parse_options(parameter_s,'r',mode='list')
2085 fname,ranges = args[0], args[1:]
2085 fname,ranges = args[0], args[1:]
2086 if not fname.endswith('.py'):
2086 if not fname.endswith('.py'):
2087 fname += '.py'
2087 fname += '.py'
2088 if os.path.isfile(fname):
2088 if os.path.isfile(fname):
2089 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2089 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2090 if ans.lower() not in ['y','yes']:
2090 if ans.lower() not in ['y','yes']:
2091 print 'Operation cancelled.'
2091 print 'Operation cancelled.'
2092 return
2092 return
2093 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2093 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2094 f = file(fname,'w')
2094 f = file(fname,'w')
2095 f.write(cmds)
2095 f.write(cmds)
2096 f.close()
2096 f.close()
2097 print 'The following commands were written to file `%s`:' % fname
2097 print 'The following commands were written to file `%s`:' % fname
2098 print cmds
2098 print cmds
2099
2099
2100 def _edit_macro(self,mname,macro):
2100 def _edit_macro(self,mname,macro):
2101 """open an editor with the macro data in a file"""
2101 """open an editor with the macro data in a file"""
2102 filename = self.shell.mktempfile(macro.value)
2102 filename = self.shell.mktempfile(macro.value)
2103 self.shell.hooks.editor(filename)
2103 self.shell.hooks.editor(filename)
2104
2104
2105 # and make a new macro object, to replace the old one
2105 # and make a new macro object, to replace the old one
2106 mfile = open(filename)
2106 mfile = open(filename)
2107 mvalue = mfile.read()
2107 mvalue = mfile.read()
2108 mfile.close()
2108 mfile.close()
2109 self.shell.user_ns[mname] = Macro(mvalue)
2109 self.shell.user_ns[mname] = Macro(mvalue)
2110
2110
2111 def magic_ed(self,parameter_s=''):
2111 def magic_ed(self,parameter_s=''):
2112 """Alias to %edit."""
2112 """Alias to %edit."""
2113 return self.magic_edit(parameter_s)
2113 return self.magic_edit(parameter_s)
2114
2114
2115 @testdec.skip_doctest
2115 @testdec.skip_doctest
2116 def magic_edit(self,parameter_s='',last_call=['','']):
2116 def magic_edit(self,parameter_s='',last_call=['','']):
2117 """Bring up an editor and execute the resulting code.
2117 """Bring up an editor and execute the resulting code.
2118
2118
2119 Usage:
2119 Usage:
2120 %edit [options] [args]
2120 %edit [options] [args]
2121
2121
2122 %edit runs IPython's editor hook. The default version of this hook is
2122 %edit runs IPython's editor hook. The default version of this hook is
2123 set to call the __IPYTHON__.rc.editor command. This is read from your
2123 set to call the __IPYTHON__.rc.editor command. This is read from your
2124 environment variable $EDITOR. If this isn't found, it will default to
2124 environment variable $EDITOR. If this isn't found, it will default to
2125 vi under Linux/Unix and to notepad under Windows. See the end of this
2125 vi under Linux/Unix and to notepad under Windows. See the end of this
2126 docstring for how to change the editor hook.
2126 docstring for how to change the editor hook.
2127
2127
2128 You can also set the value of this editor via the command line option
2128 You can also set the value of this editor via the command line option
2129 '-editor' or in your ipythonrc file. This is useful if you wish to use
2129 '-editor' or in your ipythonrc file. This is useful if you wish to use
2130 specifically for IPython an editor different from your typical default
2130 specifically for IPython an editor different from your typical default
2131 (and for Windows users who typically don't set environment variables).
2131 (and for Windows users who typically don't set environment variables).
2132
2132
2133 This command allows you to conveniently edit multi-line code right in
2133 This command allows you to conveniently edit multi-line code right in
2134 your IPython session.
2134 your IPython session.
2135
2135
2136 If called without arguments, %edit opens up an empty editor with a
2136 If called without arguments, %edit opens up an empty editor with a
2137 temporary file and will execute the contents of this file when you
2137 temporary file and will execute the contents of this file when you
2138 close it (don't forget to save it!).
2138 close it (don't forget to save it!).
2139
2139
2140
2140
2141 Options:
2141 Options:
2142
2142
2143 -n <number>: open the editor at a specified line number. By default,
2143 -n <number>: open the editor at a specified line number. By default,
2144 the IPython editor hook uses the unix syntax 'editor +N filename', but
2144 the IPython editor hook uses the unix syntax 'editor +N filename', but
2145 you can configure this by providing your own modified hook if your
2145 you can configure this by providing your own modified hook if your
2146 favorite editor supports line-number specifications with a different
2146 favorite editor supports line-number specifications with a different
2147 syntax.
2147 syntax.
2148
2148
2149 -p: this will call the editor with the same data as the previous time
2149 -p: this will call the editor with the same data as the previous time
2150 it was used, regardless of how long ago (in your current session) it
2150 it was used, regardless of how long ago (in your current session) it
2151 was.
2151 was.
2152
2152
2153 -r: use 'raw' input. This option only applies to input taken from the
2153 -r: use 'raw' input. This option only applies to input taken from the
2154 user's history. By default, the 'processed' history is used, so that
2154 user's history. By default, the 'processed' history is used, so that
2155 magics are loaded in their transformed version to valid Python. If
2155 magics are loaded in their transformed version to valid Python. If
2156 this option is given, the raw input as typed as the command line is
2156 this option is given, the raw input as typed as the command line is
2157 used instead. When you exit the editor, it will be executed by
2157 used instead. When you exit the editor, it will be executed by
2158 IPython's own processor.
2158 IPython's own processor.
2159
2159
2160 -x: do not execute the edited code immediately upon exit. This is
2160 -x: do not execute the edited code immediately upon exit. This is
2161 mainly useful if you are editing programs which need to be called with
2161 mainly useful if you are editing programs which need to be called with
2162 command line arguments, which you can then do using %run.
2162 command line arguments, which you can then do using %run.
2163
2163
2164
2164
2165 Arguments:
2165 Arguments:
2166
2166
2167 If arguments are given, the following possibilites exist:
2167 If arguments are given, the following possibilites exist:
2168
2168
2169 - The arguments are numbers or pairs of colon-separated numbers (like
2169 - The arguments are numbers or pairs of colon-separated numbers (like
2170 1 4:8 9). These are interpreted as lines of previous input to be
2170 1 4:8 9). These are interpreted as lines of previous input to be
2171 loaded into the editor. The syntax is the same of the %macro command.
2171 loaded into the editor. The syntax is the same of the %macro command.
2172
2172
2173 - If the argument doesn't start with a number, it is evaluated as a
2173 - If the argument doesn't start with a number, it is evaluated as a
2174 variable and its contents loaded into the editor. You can thus edit
2174 variable and its contents loaded into the editor. You can thus edit
2175 any string which contains python code (including the result of
2175 any string which contains python code (including the result of
2176 previous edits).
2176 previous edits).
2177
2177
2178 - If the argument is the name of an object (other than a string),
2178 - If the argument is the name of an object (other than a string),
2179 IPython will try to locate the file where it was defined and open the
2179 IPython will try to locate the file where it was defined and open the
2180 editor at the point where it is defined. You can use `%edit function`
2180 editor at the point where it is defined. You can use `%edit function`
2181 to load an editor exactly at the point where 'function' is defined,
2181 to load an editor exactly at the point where 'function' is defined,
2182 edit it and have the file be executed automatically.
2182 edit it and have the file be executed automatically.
2183
2183
2184 If the object is a macro (see %macro for details), this opens up your
2184 If the object is a macro (see %macro for details), this opens up your
2185 specified editor with a temporary file containing the macro's data.
2185 specified editor with a temporary file containing the macro's data.
2186 Upon exit, the macro is reloaded with the contents of the file.
2186 Upon exit, the macro is reloaded with the contents of the file.
2187
2187
2188 Note: opening at an exact line is only supported under Unix, and some
2188 Note: opening at an exact line is only supported under Unix, and some
2189 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2189 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2190 '+NUMBER' parameter necessary for this feature. Good editors like
2190 '+NUMBER' parameter necessary for this feature. Good editors like
2191 (X)Emacs, vi, jed, pico and joe all do.
2191 (X)Emacs, vi, jed, pico and joe all do.
2192
2192
2193 - If the argument is not found as a variable, IPython will look for a
2193 - If the argument is not found as a variable, IPython will look for a
2194 file with that name (adding .py if necessary) and load it into the
2194 file with that name (adding .py if necessary) and load it into the
2195 editor. It will execute its contents with execfile() when you exit,
2195 editor. It will execute its contents with execfile() when you exit,
2196 loading any code in the file into your interactive namespace.
2196 loading any code in the file into your interactive namespace.
2197
2197
2198 After executing your code, %edit will return as output the code you
2198 After executing your code, %edit will return as output the code you
2199 typed in the editor (except when it was an existing file). This way
2199 typed in the editor (except when it was an existing file). This way
2200 you can reload the code in further invocations of %edit as a variable,
2200 you can reload the code in further invocations of %edit as a variable,
2201 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2201 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2202 the output.
2202 the output.
2203
2203
2204 Note that %edit is also available through the alias %ed.
2204 Note that %edit is also available through the alias %ed.
2205
2205
2206 This is an example of creating a simple function inside the editor and
2206 This is an example of creating a simple function inside the editor and
2207 then modifying it. First, start up the editor:
2207 then modifying it. First, start up the editor:
2208
2208
2209 In [1]: ed
2209 In [1]: ed
2210 Editing... done. Executing edited code...
2210 Editing... done. Executing edited code...
2211 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2211 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2212
2212
2213 We can then call the function foo():
2213 We can then call the function foo():
2214
2214
2215 In [2]: foo()
2215 In [2]: foo()
2216 foo() was defined in an editing session
2216 foo() was defined in an editing session
2217
2217
2218 Now we edit foo. IPython automatically loads the editor with the
2218 Now we edit foo. IPython automatically loads the editor with the
2219 (temporary) file where foo() was previously defined:
2219 (temporary) file where foo() was previously defined:
2220
2220
2221 In [3]: ed foo
2221 In [3]: ed foo
2222 Editing... done. Executing edited code...
2222 Editing... done. Executing edited code...
2223
2223
2224 And if we call foo() again we get the modified version:
2224 And if we call foo() again we get the modified version:
2225
2225
2226 In [4]: foo()
2226 In [4]: foo()
2227 foo() has now been changed!
2227 foo() has now been changed!
2228
2228
2229 Here is an example of how to edit a code snippet successive
2229 Here is an example of how to edit a code snippet successive
2230 times. First we call the editor:
2230 times. First we call the editor:
2231
2231
2232 In [5]: ed
2232 In [5]: ed
2233 Editing... done. Executing edited code...
2233 Editing... done. Executing edited code...
2234 hello
2234 hello
2235 Out[5]: "print 'hello'n"
2235 Out[5]: "print 'hello'n"
2236
2236
2237 Now we call it again with the previous output (stored in _):
2237 Now we call it again with the previous output (stored in _):
2238
2238
2239 In [6]: ed _
2239 In [6]: ed _
2240 Editing... done. Executing edited code...
2240 Editing... done. Executing edited code...
2241 hello world
2241 hello world
2242 Out[6]: "print 'hello world'n"
2242 Out[6]: "print 'hello world'n"
2243
2243
2244 Now we call it with the output #8 (stored in _8, also as Out[8]):
2244 Now we call it with the output #8 (stored in _8, also as Out[8]):
2245
2245
2246 In [7]: ed _8
2246 In [7]: ed _8
2247 Editing... done. Executing edited code...
2247 Editing... done. Executing edited code...
2248 hello again
2248 hello again
2249 Out[7]: "print 'hello again'n"
2249 Out[7]: "print 'hello again'n"
2250
2250
2251
2251
2252 Changing the default editor hook:
2252 Changing the default editor hook:
2253
2253
2254 If you wish to write your own editor hook, you can put it in a
2254 If you wish to write your own editor hook, you can put it in a
2255 configuration file which you load at startup time. The default hook
2255 configuration file which you load at startup time. The default hook
2256 is defined in the IPython.core.hooks module, and you can use that as a
2256 is defined in the IPython.core.hooks module, and you can use that as a
2257 starting example for further modifications. That file also has
2257 starting example for further modifications. That file also has
2258 general instructions on how to set a new hook for use once you've
2258 general instructions on how to set a new hook for use once you've
2259 defined it."""
2259 defined it."""
2260
2260
2261 # FIXME: This function has become a convoluted mess. It needs a
2261 # FIXME: This function has become a convoluted mess. It needs a
2262 # ground-up rewrite with clean, simple logic.
2262 # ground-up rewrite with clean, simple logic.
2263
2263
2264 def make_filename(arg):
2264 def make_filename(arg):
2265 "Make a filename from the given args"
2265 "Make a filename from the given args"
2266 try:
2266 try:
2267 filename = get_py_filename(arg)
2267 filename = get_py_filename(arg)
2268 except IOError:
2268 except IOError:
2269 if args.endswith('.py'):
2269 if args.endswith('.py'):
2270 filename = arg
2270 filename = arg
2271 else:
2271 else:
2272 filename = None
2272 filename = None
2273 return filename
2273 return filename
2274
2274
2275 # custom exceptions
2275 # custom exceptions
2276 class DataIsObject(Exception): pass
2276 class DataIsObject(Exception): pass
2277
2277
2278 opts,args = self.parse_options(parameter_s,'prxn:')
2278 opts,args = self.parse_options(parameter_s,'prxn:')
2279 # Set a few locals from the options for convenience:
2279 # Set a few locals from the options for convenience:
2280 opts_p = opts.has_key('p')
2280 opts_p = opts.has_key('p')
2281 opts_r = opts.has_key('r')
2281 opts_r = opts.has_key('r')
2282
2282
2283 # Default line number value
2283 # Default line number value
2284 lineno = opts.get('n',None)
2284 lineno = opts.get('n',None)
2285
2285
2286 if opts_p:
2286 if opts_p:
2287 args = '_%s' % last_call[0]
2287 args = '_%s' % last_call[0]
2288 if not self.shell.user_ns.has_key(args):
2288 if not self.shell.user_ns.has_key(args):
2289 args = last_call[1]
2289 args = last_call[1]
2290
2290
2291 # use last_call to remember the state of the previous call, but don't
2291 # use last_call to remember the state of the previous call, but don't
2292 # let it be clobbered by successive '-p' calls.
2292 # let it be clobbered by successive '-p' calls.
2293 try:
2293 try:
2294 last_call[0] = self.shell.outputcache.prompt_count
2294 last_call[0] = self.shell.outputcache.prompt_count
2295 if not opts_p:
2295 if not opts_p:
2296 last_call[1] = parameter_s
2296 last_call[1] = parameter_s
2297 except:
2297 except:
2298 pass
2298 pass
2299
2299
2300 # by default this is done with temp files, except when the given
2300 # by default this is done with temp files, except when the given
2301 # arg is a filename
2301 # arg is a filename
2302 use_temp = 1
2302 use_temp = 1
2303
2303
2304 if re.match(r'\d',args):
2304 if re.match(r'\d',args):
2305 # Mode where user specifies ranges of lines, like in %macro.
2305 # Mode where user specifies ranges of lines, like in %macro.
2306 # This means that you can't edit files whose names begin with
2306 # This means that you can't edit files whose names begin with
2307 # numbers this way. Tough.
2307 # numbers this way. Tough.
2308 ranges = args.split()
2308 ranges = args.split()
2309 data = ''.join(self.extract_input_slices(ranges,opts_r))
2309 data = ''.join(self.extract_input_slices(ranges,opts_r))
2310 elif args.endswith('.py'):
2310 elif args.endswith('.py'):
2311 filename = make_filename(args)
2311 filename = make_filename(args)
2312 data = ''
2312 data = ''
2313 use_temp = 0
2313 use_temp = 0
2314 elif args:
2314 elif args:
2315 try:
2315 try:
2316 # Load the parameter given as a variable. If not a string,
2316 # Load the parameter given as a variable. If not a string,
2317 # process it as an object instead (below)
2317 # process it as an object instead (below)
2318
2318
2319 #print '*** args',args,'type',type(args) # dbg
2319 #print '*** args',args,'type',type(args) # dbg
2320 data = eval(args,self.shell.user_ns)
2320 data = eval(args,self.shell.user_ns)
2321 if not type(data) in StringTypes:
2321 if not type(data) in StringTypes:
2322 raise DataIsObject
2322 raise DataIsObject
2323
2323
2324 except (NameError,SyntaxError):
2324 except (NameError,SyntaxError):
2325 # given argument is not a variable, try as a filename
2325 # given argument is not a variable, try as a filename
2326 filename = make_filename(args)
2326 filename = make_filename(args)
2327 if filename is None:
2327 if filename is None:
2328 warn("Argument given (%s) can't be found as a variable "
2328 warn("Argument given (%s) can't be found as a variable "
2329 "or as a filename." % args)
2329 "or as a filename." % args)
2330 return
2330 return
2331
2331
2332 data = ''
2332 data = ''
2333 use_temp = 0
2333 use_temp = 0
2334 except DataIsObject:
2334 except DataIsObject:
2335
2335
2336 # macros have a special edit function
2336 # macros have a special edit function
2337 if isinstance(data,Macro):
2337 if isinstance(data,Macro):
2338 self._edit_macro(args,data)
2338 self._edit_macro(args,data)
2339 return
2339 return
2340
2340
2341 # For objects, try to edit the file where they are defined
2341 # For objects, try to edit the file where they are defined
2342 try:
2342 try:
2343 filename = inspect.getabsfile(data)
2343 filename = inspect.getabsfile(data)
2344 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2344 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2345 # class created by %edit? Try to find source
2345 # class created by %edit? Try to find source
2346 # by looking for method definitions instead, the
2346 # by looking for method definitions instead, the
2347 # __module__ in those classes is FakeModule.
2347 # __module__ in those classes is FakeModule.
2348 attrs = [getattr(data, aname) for aname in dir(data)]
2348 attrs = [getattr(data, aname) for aname in dir(data)]
2349 for attr in attrs:
2349 for attr in attrs:
2350 if not inspect.ismethod(attr):
2350 if not inspect.ismethod(attr):
2351 continue
2351 continue
2352 filename = inspect.getabsfile(attr)
2352 filename = inspect.getabsfile(attr)
2353 if filename and 'fakemodule' not in filename.lower():
2353 if filename and 'fakemodule' not in filename.lower():
2354 # change the attribute to be the edit target instead
2354 # change the attribute to be the edit target instead
2355 data = attr
2355 data = attr
2356 break
2356 break
2357
2357
2358 datafile = 1
2358 datafile = 1
2359 except TypeError:
2359 except TypeError:
2360 filename = make_filename(args)
2360 filename = make_filename(args)
2361 datafile = 1
2361 datafile = 1
2362 warn('Could not find file where `%s` is defined.\n'
2362 warn('Could not find file where `%s` is defined.\n'
2363 'Opening a file named `%s`' % (args,filename))
2363 'Opening a file named `%s`' % (args,filename))
2364 # Now, make sure we can actually read the source (if it was in
2364 # Now, make sure we can actually read the source (if it was in
2365 # a temp file it's gone by now).
2365 # a temp file it's gone by now).
2366 if datafile:
2366 if datafile:
2367 try:
2367 try:
2368 if lineno is None:
2368 if lineno is None:
2369 lineno = inspect.getsourcelines(data)[1]
2369 lineno = inspect.getsourcelines(data)[1]
2370 except IOError:
2370 except IOError:
2371 filename = make_filename(args)
2371 filename = make_filename(args)
2372 if filename is None:
2372 if filename is None:
2373 warn('The file `%s` where `%s` was defined cannot '
2373 warn('The file `%s` where `%s` was defined cannot '
2374 'be read.' % (filename,data))
2374 'be read.' % (filename,data))
2375 return
2375 return
2376 use_temp = 0
2376 use_temp = 0
2377 else:
2377 else:
2378 data = ''
2378 data = ''
2379
2379
2380 if use_temp:
2380 if use_temp:
2381 filename = self.shell.mktempfile(data)
2381 filename = self.shell.mktempfile(data)
2382 print 'IPython will make a temporary file named:',filename
2382 print 'IPython will make a temporary file named:',filename
2383
2383
2384 # do actual editing here
2384 # do actual editing here
2385 print 'Editing...',
2385 print 'Editing...',
2386 sys.stdout.flush()
2386 sys.stdout.flush()
2387 try:
2387 try:
2388 self.shell.hooks.editor(filename,lineno)
2388 self.shell.hooks.editor(filename,lineno)
2389 except ipapi.TryNext:
2389 except ipapi.TryNext:
2390 warn('Could not open editor')
2390 warn('Could not open editor')
2391 return
2391 return
2392
2392
2393 # XXX TODO: should this be generalized for all string vars?
2393 # XXX TODO: should this be generalized for all string vars?
2394 # For now, this is special-cased to blocks created by cpaste
2394 # For now, this is special-cased to blocks created by cpaste
2395 if args.strip() == 'pasted_block':
2395 if args.strip() == 'pasted_block':
2396 self.shell.user_ns['pasted_block'] = file_read(filename)
2396 self.shell.user_ns['pasted_block'] = file_read(filename)
2397
2397
2398 if opts.has_key('x'): # -x prevents actual execution
2398 if opts.has_key('x'): # -x prevents actual execution
2399 print
2399 print
2400 else:
2400 else:
2401 print 'done. Executing edited code...'
2401 print 'done. Executing edited code...'
2402 if opts_r:
2402 if opts_r:
2403 self.shell.runlines(file_read(filename))
2403 self.shell.runlines(file_read(filename))
2404 else:
2404 else:
2405 self.shell.safe_execfile(filename,self.shell.user_ns,
2405 self.shell.safe_execfile(filename,self.shell.user_ns,
2406 self.shell.user_ns)
2406 self.shell.user_ns)
2407
2407
2408
2408
2409 if use_temp:
2409 if use_temp:
2410 try:
2410 try:
2411 return open(filename).read()
2411 return open(filename).read()
2412 except IOError,msg:
2412 except IOError,msg:
2413 if msg.filename == filename:
2413 if msg.filename == filename:
2414 warn('File not found. Did you forget to save?')
2414 warn('File not found. Did you forget to save?')
2415 return
2415 return
2416 else:
2416 else:
2417 self.shell.showtraceback()
2417 self.shell.showtraceback()
2418
2418
2419 def magic_xmode(self,parameter_s = ''):
2419 def magic_xmode(self,parameter_s = ''):
2420 """Switch modes for the exception handlers.
2420 """Switch modes for the exception handlers.
2421
2421
2422 Valid modes: Plain, Context and Verbose.
2422 Valid modes: Plain, Context and Verbose.
2423
2423
2424 If called without arguments, acts as a toggle."""
2424 If called without arguments, acts as a toggle."""
2425
2425
2426 def xmode_switch_err(name):
2426 def xmode_switch_err(name):
2427 warn('Error changing %s exception modes.\n%s' %
2427 warn('Error changing %s exception modes.\n%s' %
2428 (name,sys.exc_info()[1]))
2428 (name,sys.exc_info()[1]))
2429
2429
2430 shell = self.shell
2430 shell = self.shell
2431 new_mode = parameter_s.strip().capitalize()
2431 new_mode = parameter_s.strip().capitalize()
2432 try:
2432 try:
2433 shell.InteractiveTB.set_mode(mode=new_mode)
2433 shell.InteractiveTB.set_mode(mode=new_mode)
2434 print 'Exception reporting mode:',shell.InteractiveTB.mode
2434 print 'Exception reporting mode:',shell.InteractiveTB.mode
2435 except:
2435 except:
2436 xmode_switch_err('user')
2436 xmode_switch_err('user')
2437
2437
2438 # threaded shells use a special handler in sys.excepthook
2438 # threaded shells use a special handler in sys.excepthook
2439 if shell.isthreaded:
2439 if shell.isthreaded:
2440 try:
2440 try:
2441 shell.sys_excepthook.set_mode(mode=new_mode)
2441 shell.sys_excepthook.set_mode(mode=new_mode)
2442 except:
2442 except:
2443 xmode_switch_err('threaded')
2443 xmode_switch_err('threaded')
2444
2444
2445 def magic_colors(self,parameter_s = ''):
2445 def magic_colors(self,parameter_s = ''):
2446 """Switch color scheme for prompts, info system and exception handlers.
2446 """Switch color scheme for prompts, info system and exception handlers.
2447
2447
2448 Currently implemented schemes: NoColor, Linux, LightBG.
2448 Currently implemented schemes: NoColor, Linux, LightBG.
2449
2449
2450 Color scheme names are not case-sensitive."""
2450 Color scheme names are not case-sensitive."""
2451
2451
2452 def color_switch_err(name):
2452 def color_switch_err(name):
2453 warn('Error changing %s color schemes.\n%s' %
2453 warn('Error changing %s color schemes.\n%s' %
2454 (name,sys.exc_info()[1]))
2454 (name,sys.exc_info()[1]))
2455
2455
2456
2456
2457 new_scheme = parameter_s.strip()
2457 new_scheme = parameter_s.strip()
2458 if not new_scheme:
2458 if not new_scheme:
2459 raise UsageError(
2459 raise UsageError(
2460 "%colors: you must specify a color scheme. See '%colors?'")
2460 "%colors: you must specify a color scheme. See '%colors?'")
2461 return
2461 return
2462 # local shortcut
2462 # local shortcut
2463 shell = self.shell
2463 shell = self.shell
2464
2464
2465 import IPython.rlineimpl as readline
2465 import IPython.rlineimpl as readline
2466
2466
2467 if not readline.have_readline and sys.platform == "win32":
2467 if not readline.have_readline and sys.platform == "win32":
2468 msg = """\
2468 msg = """\
2469 Proper color support under MS Windows requires the pyreadline library.
2469 Proper color support under MS Windows requires the pyreadline library.
2470 You can find it at:
2470 You can find it at:
2471 http://ipython.scipy.org/moin/PyReadline/Intro
2471 http://ipython.scipy.org/moin/PyReadline/Intro
2472 Gary's readline needs the ctypes module, from:
2472 Gary's readline needs the ctypes module, from:
2473 http://starship.python.net/crew/theller/ctypes
2473 http://starship.python.net/crew/theller/ctypes
2474 (Note that ctypes is already part of Python versions 2.5 and newer).
2474 (Note that ctypes is already part of Python versions 2.5 and newer).
2475
2475
2476 Defaulting color scheme to 'NoColor'"""
2476 Defaulting color scheme to 'NoColor'"""
2477 new_scheme = 'NoColor'
2477 new_scheme = 'NoColor'
2478 warn(msg)
2478 warn(msg)
2479
2479
2480 # readline option is 0
2480 # readline option is 0
2481 if not shell.has_readline:
2481 if not shell.has_readline:
2482 new_scheme = 'NoColor'
2482 new_scheme = 'NoColor'
2483
2483
2484 # Set prompt colors
2484 # Set prompt colors
2485 try:
2485 try:
2486 shell.outputcache.set_colors(new_scheme)
2486 shell.outputcache.set_colors(new_scheme)
2487 except:
2487 except:
2488 color_switch_err('prompt')
2488 color_switch_err('prompt')
2489 else:
2489 else:
2490 shell.rc.colors = \
2490 shell.rc.colors = \
2491 shell.outputcache.color_table.active_scheme_name
2491 shell.outputcache.color_table.active_scheme_name
2492 # Set exception colors
2492 # Set exception colors
2493 try:
2493 try:
2494 shell.InteractiveTB.set_colors(scheme = new_scheme)
2494 shell.InteractiveTB.set_colors(scheme = new_scheme)
2495 shell.SyntaxTB.set_colors(scheme = new_scheme)
2495 shell.SyntaxTB.set_colors(scheme = new_scheme)
2496 except:
2496 except:
2497 color_switch_err('exception')
2497 color_switch_err('exception')
2498
2498
2499 # threaded shells use a verbose traceback in sys.excepthook
2499 # threaded shells use a verbose traceback in sys.excepthook
2500 if shell.isthreaded:
2500 if shell.isthreaded:
2501 try:
2501 try:
2502 shell.sys_excepthook.set_colors(scheme=new_scheme)
2502 shell.sys_excepthook.set_colors(scheme=new_scheme)
2503 except:
2503 except:
2504 color_switch_err('system exception handler')
2504 color_switch_err('system exception handler')
2505
2505
2506 # Set info (for 'object?') colors
2506 # Set info (for 'object?') colors
2507 if shell.rc.color_info:
2507 if shell.rc.color_info:
2508 try:
2508 try:
2509 shell.inspector.set_active_scheme(new_scheme)
2509 shell.inspector.set_active_scheme(new_scheme)
2510 except:
2510 except:
2511 color_switch_err('object inspector')
2511 color_switch_err('object inspector')
2512 else:
2512 else:
2513 shell.inspector.set_active_scheme('NoColor')
2513 shell.inspector.set_active_scheme('NoColor')
2514
2514
2515 def magic_color_info(self,parameter_s = ''):
2515 def magic_color_info(self,parameter_s = ''):
2516 """Toggle color_info.
2516 """Toggle color_info.
2517
2517
2518 The color_info configuration parameter controls whether colors are
2518 The color_info configuration parameter controls whether colors are
2519 used for displaying object details (by things like %psource, %pfile or
2519 used for displaying object details (by things like %psource, %pfile or
2520 the '?' system). This function toggles this value with each call.
2520 the '?' system). This function toggles this value with each call.
2521
2521
2522 Note that unless you have a fairly recent pager (less works better
2522 Note that unless you have a fairly recent pager (less works better
2523 than more) in your system, using colored object information displays
2523 than more) in your system, using colored object information displays
2524 will not work properly. Test it and see."""
2524 will not work properly. Test it and see."""
2525
2525
2526 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2526 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2527 self.magic_colors(self.shell.rc.colors)
2527 self.magic_colors(self.shell.rc.colors)
2528 print 'Object introspection functions have now coloring:',
2528 print 'Object introspection functions have now coloring:',
2529 print ['OFF','ON'][self.shell.rc.color_info]
2529 print ['OFF','ON'][self.shell.rc.color_info]
2530
2530
2531 def magic_Pprint(self, parameter_s=''):
2531 def magic_Pprint(self, parameter_s=''):
2532 """Toggle pretty printing on/off."""
2532 """Toggle pretty printing on/off."""
2533
2533
2534 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2534 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2535 print 'Pretty printing has been turned', \
2535 print 'Pretty printing has been turned', \
2536 ['OFF','ON'][self.shell.rc.pprint]
2536 ['OFF','ON'][self.shell.rc.pprint]
2537
2537
2538 def magic_exit(self, parameter_s=''):
2538 def magic_exit(self, parameter_s=''):
2539 """Exit IPython, confirming if configured to do so.
2539 """Exit IPython, confirming if configured to do so.
2540
2540
2541 You can configure whether IPython asks for confirmation upon exit by
2541 You can configure whether IPython asks for confirmation upon exit by
2542 setting the confirm_exit flag in the ipythonrc file."""
2542 setting the confirm_exit flag in the ipythonrc file."""
2543
2543
2544 self.shell.exit()
2544 self.shell.exit()
2545
2545
2546 def magic_quit(self, parameter_s=''):
2546 def magic_quit(self, parameter_s=''):
2547 """Exit IPython, confirming if configured to do so (like %exit)"""
2547 """Exit IPython, confirming if configured to do so (like %exit)"""
2548
2548
2549 self.shell.exit()
2549 self.shell.exit()
2550
2550
2551 def magic_Exit(self, parameter_s=''):
2551 def magic_Exit(self, parameter_s=''):
2552 """Exit IPython without confirmation."""
2552 """Exit IPython without confirmation."""
2553
2553
2554 self.shell.ask_exit()
2554 self.shell.ask_exit()
2555
2555
2556 #......................................................................
2556 #......................................................................
2557 # Functions to implement unix shell-type things
2557 # Functions to implement unix shell-type things
2558
2558
2559 @testdec.skip_doctest
2559 @testdec.skip_doctest
2560 def magic_alias(self, parameter_s = ''):
2560 def magic_alias(self, parameter_s = ''):
2561 """Define an alias for a system command.
2561 """Define an alias for a system command.
2562
2562
2563 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2563 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2564
2564
2565 Then, typing 'alias_name params' will execute the system command 'cmd
2565 Then, typing 'alias_name params' will execute the system command 'cmd
2566 params' (from your underlying operating system).
2566 params' (from your underlying operating system).
2567
2567
2568 Aliases have lower precedence than magic functions and Python normal
2568 Aliases have lower precedence than magic functions and Python normal
2569 variables, so if 'foo' is both a Python variable and an alias, the
2569 variables, so if 'foo' is both a Python variable and an alias, the
2570 alias can not be executed until 'del foo' removes the Python variable.
2570 alias can not be executed until 'del foo' removes the Python variable.
2571
2571
2572 You can use the %l specifier in an alias definition to represent the
2572 You can use the %l specifier in an alias definition to represent the
2573 whole line when the alias is called. For example:
2573 whole line when the alias is called. For example:
2574
2574
2575 In [2]: alias all echo "Input in brackets: <%l>"
2575 In [2]: alias all echo "Input in brackets: <%l>"
2576 In [3]: all hello world
2576 In [3]: all hello world
2577 Input in brackets: <hello world>
2577 Input in brackets: <hello world>
2578
2578
2579 You can also define aliases with parameters using %s specifiers (one
2579 You can also define aliases with parameters using %s specifiers (one
2580 per parameter):
2580 per parameter):
2581
2581
2582 In [1]: alias parts echo first %s second %s
2582 In [1]: alias parts echo first %s second %s
2583 In [2]: %parts A B
2583 In [2]: %parts A B
2584 first A second B
2584 first A second B
2585 In [3]: %parts A
2585 In [3]: %parts A
2586 Incorrect number of arguments: 2 expected.
2586 Incorrect number of arguments: 2 expected.
2587 parts is an alias to: 'echo first %s second %s'
2587 parts is an alias to: 'echo first %s second %s'
2588
2588
2589 Note that %l and %s are mutually exclusive. You can only use one or
2589 Note that %l and %s are mutually exclusive. You can only use one or
2590 the other in your aliases.
2590 the other in your aliases.
2591
2591
2592 Aliases expand Python variables just like system calls using ! or !!
2592 Aliases expand Python variables just like system calls using ! or !!
2593 do: all expressions prefixed with '$' get expanded. For details of
2593 do: all expressions prefixed with '$' get expanded. For details of
2594 the semantic rules, see PEP-215:
2594 the semantic rules, see PEP-215:
2595 http://www.python.org/peps/pep-0215.html. This is the library used by
2595 http://www.python.org/peps/pep-0215.html. This is the library used by
2596 IPython for variable expansion. If you want to access a true shell
2596 IPython for variable expansion. If you want to access a true shell
2597 variable, an extra $ is necessary to prevent its expansion by IPython:
2597 variable, an extra $ is necessary to prevent its expansion by IPython:
2598
2598
2599 In [6]: alias show echo
2599 In [6]: alias show echo
2600 In [7]: PATH='A Python string'
2600 In [7]: PATH='A Python string'
2601 In [8]: show $PATH
2601 In [8]: show $PATH
2602 A Python string
2602 A Python string
2603 In [9]: show $$PATH
2603 In [9]: show $$PATH
2604 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2604 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2605
2605
2606 You can use the alias facility to acess all of $PATH. See the %rehash
2606 You can use the alias facility to acess all of $PATH. See the %rehash
2607 and %rehashx functions, which automatically create aliases for the
2607 and %rehashx functions, which automatically create aliases for the
2608 contents of your $PATH.
2608 contents of your $PATH.
2609
2609
2610 If called with no parameters, %alias prints the current alias table."""
2610 If called with no parameters, %alias prints the current alias table."""
2611
2611
2612 par = parameter_s.strip()
2612 par = parameter_s.strip()
2613 if not par:
2613 if not par:
2614 stored = self.db.get('stored_aliases', {} )
2614 stored = self.db.get('stored_aliases', {} )
2615 atab = self.shell.alias_table
2615 atab = self.shell.alias_table
2616 aliases = atab.keys()
2616 aliases = atab.keys()
2617 aliases.sort()
2617 aliases.sort()
2618 res = []
2618 res = []
2619 showlast = []
2619 showlast = []
2620 for alias in aliases:
2620 for alias in aliases:
2621 special = False
2621 special = False
2622 try:
2622 try:
2623 tgt = atab[alias][1]
2623 tgt = atab[alias][1]
2624 except (TypeError, AttributeError):
2624 except (TypeError, AttributeError):
2625 # unsubscriptable? probably a callable
2625 # unsubscriptable? probably a callable
2626 tgt = atab[alias]
2626 tgt = atab[alias]
2627 special = True
2627 special = True
2628 # 'interesting' aliases
2628 # 'interesting' aliases
2629 if (alias in stored or
2629 if (alias in stored or
2630 special or
2630 special or
2631 alias.lower() != os.path.splitext(tgt)[0].lower() or
2631 alias.lower() != os.path.splitext(tgt)[0].lower() or
2632 ' ' in tgt):
2632 ' ' in tgt):
2633 showlast.append((alias, tgt))
2633 showlast.append((alias, tgt))
2634 else:
2634 else:
2635 res.append((alias, tgt ))
2635 res.append((alias, tgt ))
2636
2636
2637 # show most interesting aliases last
2637 # show most interesting aliases last
2638 res.extend(showlast)
2638 res.extend(showlast)
2639 print "Total number of aliases:",len(aliases)
2639 print "Total number of aliases:",len(aliases)
2640 return res
2640 return res
2641 try:
2641 try:
2642 alias,cmd = par.split(None,1)
2642 alias,cmd = par.split(None,1)
2643 except:
2643 except:
2644 print oinspect.getdoc(self.magic_alias)
2644 print oinspect.getdoc(self.magic_alias)
2645 else:
2645 else:
2646 nargs = cmd.count('%s')
2646 nargs = cmd.count('%s')
2647 if nargs>0 and cmd.find('%l')>=0:
2647 if nargs>0 and cmd.find('%l')>=0:
2648 error('The %s and %l specifiers are mutually exclusive '
2648 error('The %s and %l specifiers are mutually exclusive '
2649 'in alias definitions.')
2649 'in alias definitions.')
2650 else: # all looks OK
2650 else: # all looks OK
2651 self.shell.alias_table[alias] = (nargs,cmd)
2651 self.shell.alias_table[alias] = (nargs,cmd)
2652 self.shell.alias_table_validate(verbose=0)
2652 self.shell.alias_table_validate(verbose=0)
2653 # end magic_alias
2653 # end magic_alias
2654
2654
2655 def magic_unalias(self, parameter_s = ''):
2655 def magic_unalias(self, parameter_s = ''):
2656 """Remove an alias"""
2656 """Remove an alias"""
2657
2657
2658 aname = parameter_s.strip()
2658 aname = parameter_s.strip()
2659 if aname in self.shell.alias_table:
2659 if aname in self.shell.alias_table:
2660 del self.shell.alias_table[aname]
2660 del self.shell.alias_table[aname]
2661 stored = self.db.get('stored_aliases', {} )
2661 stored = self.db.get('stored_aliases', {} )
2662 if aname in stored:
2662 if aname in stored:
2663 print "Removing %stored alias",aname
2663 print "Removing %stored alias",aname
2664 del stored[aname]
2664 del stored[aname]
2665 self.db['stored_aliases'] = stored
2665 self.db['stored_aliases'] = stored
2666
2666
2667
2667
2668 def magic_rehashx(self, parameter_s = ''):
2668 def magic_rehashx(self, parameter_s = ''):
2669 """Update the alias table with all executable files in $PATH.
2669 """Update the alias table with all executable files in $PATH.
2670
2670
2671 This version explicitly checks that every entry in $PATH is a file
2671 This version explicitly checks that every entry in $PATH is a file
2672 with execute access (os.X_OK), so it is much slower than %rehash.
2672 with execute access (os.X_OK), so it is much slower than %rehash.
2673
2673
2674 Under Windows, it checks executability as a match agains a
2674 Under Windows, it checks executability as a match agains a
2675 '|'-separated string of extensions, stored in the IPython config
2675 '|'-separated string of extensions, stored in the IPython config
2676 variable win_exec_ext. This defaults to 'exe|com|bat'.
2676 variable win_exec_ext. This defaults to 'exe|com|bat'.
2677
2677
2678 This function also resets the root module cache of module completer,
2678 This function also resets the root module cache of module completer,
2679 used on slow filesystems.
2679 used on slow filesystems.
2680 """
2680 """
2681
2681
2682
2682
2683 ip = self.api
2683 ip = self.api
2684
2684
2685 # for the benefit of module completer in ipy_completers.py
2685 # for the benefit of module completer in ipy_completers.py
2686 del ip.db['rootmodules']
2686 del ip.db['rootmodules']
2687
2687
2688 path = [os.path.abspath(os.path.expanduser(p)) for p in
2688 path = [os.path.abspath(os.path.expanduser(p)) for p in
2689 os.environ.get('PATH','').split(os.pathsep)]
2689 os.environ.get('PATH','').split(os.pathsep)]
2690 path = filter(os.path.isdir,path)
2690 path = filter(os.path.isdir,path)
2691
2691
2692 alias_table = self.shell.alias_table
2692 alias_table = self.shell.alias_table
2693 syscmdlist = []
2693 syscmdlist = []
2694 if os.name == 'posix':
2694 if os.name == 'posix':
2695 isexec = lambda fname:os.path.isfile(fname) and \
2695 isexec = lambda fname:os.path.isfile(fname) and \
2696 os.access(fname,os.X_OK)
2696 os.access(fname,os.X_OK)
2697 else:
2697 else:
2698
2698
2699 try:
2699 try:
2700 winext = os.environ['pathext'].replace(';','|').replace('.','')
2700 winext = os.environ['pathext'].replace(';','|').replace('.','')
2701 except KeyError:
2701 except KeyError:
2702 winext = 'exe|com|bat|py'
2702 winext = 'exe|com|bat|py'
2703 if 'py' not in winext:
2703 if 'py' not in winext:
2704 winext += '|py'
2704 winext += '|py'
2705 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2705 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2706 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2706 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2707 savedir = os.getcwd()
2707 savedir = os.getcwd()
2708 try:
2708 try:
2709 # write the whole loop for posix/Windows so we don't have an if in
2709 # write the whole loop for posix/Windows so we don't have an if in
2710 # the innermost part
2710 # the innermost part
2711 if os.name == 'posix':
2711 if os.name == 'posix':
2712 for pdir in path:
2712 for pdir in path:
2713 os.chdir(pdir)
2713 os.chdir(pdir)
2714 for ff in os.listdir(pdir):
2714 for ff in os.listdir(pdir):
2715 if isexec(ff) and ff not in self.shell.no_alias:
2715 if isexec(ff) and ff not in self.shell.no_alias:
2716 # each entry in the alias table must be (N,name),
2716 # each entry in the alias table must be (N,name),
2717 # where N is the number of positional arguments of the
2717 # where N is the number of positional arguments of the
2718 # alias.
2718 # alias.
2719 # Dots will be removed from alias names, since ipython
2719 # Dots will be removed from alias names, since ipython
2720 # assumes names with dots to be python code
2720 # assumes names with dots to be python code
2721 alias_table[ff.replace('.','')] = (0,ff)
2721 alias_table[ff.replace('.','')] = (0,ff)
2722 syscmdlist.append(ff)
2722 syscmdlist.append(ff)
2723 else:
2723 else:
2724 for pdir in path:
2724 for pdir in path:
2725 os.chdir(pdir)
2725 os.chdir(pdir)
2726 for ff in os.listdir(pdir):
2726 for ff in os.listdir(pdir):
2727 base, ext = os.path.splitext(ff)
2727 base, ext = os.path.splitext(ff)
2728 if isexec(ff) and base.lower() not in self.shell.no_alias:
2728 if isexec(ff) and base.lower() not in self.shell.no_alias:
2729 if ext.lower() == '.exe':
2729 if ext.lower() == '.exe':
2730 ff = base
2730 ff = base
2731 alias_table[base.lower().replace('.','')] = (0,ff)
2731 alias_table[base.lower().replace('.','')] = (0,ff)
2732 syscmdlist.append(ff)
2732 syscmdlist.append(ff)
2733 # Make sure the alias table doesn't contain keywords or builtins
2733 # Make sure the alias table doesn't contain keywords or builtins
2734 self.shell.alias_table_validate()
2734 self.shell.alias_table_validate()
2735 # Call again init_auto_alias() so we get 'rm -i' and other
2735 # Call again init_auto_alias() so we get 'rm -i' and other
2736 # modified aliases since %rehashx will probably clobber them
2736 # modified aliases since %rehashx will probably clobber them
2737
2737
2738 # no, we don't want them. if %rehashx clobbers them, good,
2738 # no, we don't want them. if %rehashx clobbers them, good,
2739 # we'll probably get better versions
2739 # we'll probably get better versions
2740 # self.shell.init_auto_alias()
2740 # self.shell.init_auto_alias()
2741 db = ip.db
2741 db = ip.db
2742 db['syscmdlist'] = syscmdlist
2742 db['syscmdlist'] = syscmdlist
2743 finally:
2743 finally:
2744 os.chdir(savedir)
2744 os.chdir(savedir)
2745
2745
2746 def magic_pwd(self, parameter_s = ''):
2746 def magic_pwd(self, parameter_s = ''):
2747 """Return the current working directory path."""
2747 """Return the current working directory path."""
2748 return os.getcwd()
2748 return os.getcwd()
2749
2749
2750 def magic_cd(self, parameter_s=''):
2750 def magic_cd(self, parameter_s=''):
2751 """Change the current working directory.
2751 """Change the current working directory.
2752
2752
2753 This command automatically maintains an internal list of directories
2753 This command automatically maintains an internal list of directories
2754 you visit during your IPython session, in the variable _dh. The
2754 you visit during your IPython session, in the variable _dh. The
2755 command %dhist shows this history nicely formatted. You can also
2755 command %dhist shows this history nicely formatted. You can also
2756 do 'cd -<tab>' to see directory history conveniently.
2756 do 'cd -<tab>' to see directory history conveniently.
2757
2757
2758 Usage:
2758 Usage:
2759
2759
2760 cd 'dir': changes to directory 'dir'.
2760 cd 'dir': changes to directory 'dir'.
2761
2761
2762 cd -: changes to the last visited directory.
2762 cd -: changes to the last visited directory.
2763
2763
2764 cd -<n>: changes to the n-th directory in the directory history.
2764 cd -<n>: changes to the n-th directory in the directory history.
2765
2765
2766 cd --foo: change to directory that matches 'foo' in history
2766 cd --foo: change to directory that matches 'foo' in history
2767
2767
2768 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2768 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2769 (note: cd <bookmark_name> is enough if there is no
2769 (note: cd <bookmark_name> is enough if there is no
2770 directory <bookmark_name>, but a bookmark with the name exists.)
2770 directory <bookmark_name>, but a bookmark with the name exists.)
2771 'cd -b <tab>' allows you to tab-complete bookmark names.
2771 'cd -b <tab>' allows you to tab-complete bookmark names.
2772
2772
2773 Options:
2773 Options:
2774
2774
2775 -q: quiet. Do not print the working directory after the cd command is
2775 -q: quiet. Do not print the working directory after the cd command is
2776 executed. By default IPython's cd command does print this directory,
2776 executed. By default IPython's cd command does print this directory,
2777 since the default prompts do not display path information.
2777 since the default prompts do not display path information.
2778
2778
2779 Note that !cd doesn't work for this purpose because the shell where
2779 Note that !cd doesn't work for this purpose because the shell where
2780 !command runs is immediately discarded after executing 'command'."""
2780 !command runs is immediately discarded after executing 'command'."""
2781
2781
2782 parameter_s = parameter_s.strip()
2782 parameter_s = parameter_s.strip()
2783 #bkms = self.shell.persist.get("bookmarks",{})
2783 #bkms = self.shell.persist.get("bookmarks",{})
2784
2784
2785 oldcwd = os.getcwd()
2785 oldcwd = os.getcwd()
2786 numcd = re.match(r'(-)(\d+)$',parameter_s)
2786 numcd = re.match(r'(-)(\d+)$',parameter_s)
2787 # jump in directory history by number
2787 # jump in directory history by number
2788 if numcd:
2788 if numcd:
2789 nn = int(numcd.group(2))
2789 nn = int(numcd.group(2))
2790 try:
2790 try:
2791 ps = self.shell.user_ns['_dh'][nn]
2791 ps = self.shell.user_ns['_dh'][nn]
2792 except IndexError:
2792 except IndexError:
2793 print 'The requested directory does not exist in history.'
2793 print 'The requested directory does not exist in history.'
2794 return
2794 return
2795 else:
2795 else:
2796 opts = {}
2796 opts = {}
2797 elif parameter_s.startswith('--'):
2797 elif parameter_s.startswith('--'):
2798 ps = None
2798 ps = None
2799 fallback = None
2799 fallback = None
2800 pat = parameter_s[2:]
2800 pat = parameter_s[2:]
2801 dh = self.shell.user_ns['_dh']
2801 dh = self.shell.user_ns['_dh']
2802 # first search only by basename (last component)
2802 # first search only by basename (last component)
2803 for ent in reversed(dh):
2803 for ent in reversed(dh):
2804 if pat in os.path.basename(ent) and os.path.isdir(ent):
2804 if pat in os.path.basename(ent) and os.path.isdir(ent):
2805 ps = ent
2805 ps = ent
2806 break
2806 break
2807
2807
2808 if fallback is None and pat in ent and os.path.isdir(ent):
2808 if fallback is None and pat in ent and os.path.isdir(ent):
2809 fallback = ent
2809 fallback = ent
2810
2810
2811 # if we have no last part match, pick the first full path match
2811 # if we have no last part match, pick the first full path match
2812 if ps is None:
2812 if ps is None:
2813 ps = fallback
2813 ps = fallback
2814
2814
2815 if ps is None:
2815 if ps is None:
2816 print "No matching entry in directory history"
2816 print "No matching entry in directory history"
2817 return
2817 return
2818 else:
2818 else:
2819 opts = {}
2819 opts = {}
2820
2820
2821
2821
2822 else:
2822 else:
2823 #turn all non-space-escaping backslashes to slashes,
2823 #turn all non-space-escaping backslashes to slashes,
2824 # for c:\windows\directory\names\
2824 # for c:\windows\directory\names\
2825 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2825 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2826 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2826 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2827 # jump to previous
2827 # jump to previous
2828 if ps == '-':
2828 if ps == '-':
2829 try:
2829 try:
2830 ps = self.shell.user_ns['_dh'][-2]
2830 ps = self.shell.user_ns['_dh'][-2]
2831 except IndexError:
2831 except IndexError:
2832 raise UsageError('%cd -: No previous directory to change to.')
2832 raise UsageError('%cd -: No previous directory to change to.')
2833 # jump to bookmark if needed
2833 # jump to bookmark if needed
2834 else:
2834 else:
2835 if not os.path.isdir(ps) or opts.has_key('b'):
2835 if not os.path.isdir(ps) or opts.has_key('b'):
2836 bkms = self.db.get('bookmarks', {})
2836 bkms = self.db.get('bookmarks', {})
2837
2837
2838 if bkms.has_key(ps):
2838 if bkms.has_key(ps):
2839 target = bkms[ps]
2839 target = bkms[ps]
2840 print '(bookmark:%s) -> %s' % (ps,target)
2840 print '(bookmark:%s) -> %s' % (ps,target)
2841 ps = target
2841 ps = target
2842 else:
2842 else:
2843 if opts.has_key('b'):
2843 if opts.has_key('b'):
2844 raise UsageError("Bookmark '%s' not found. "
2844 raise UsageError("Bookmark '%s' not found. "
2845 "Use '%%bookmark -l' to see your bookmarks." % ps)
2845 "Use '%%bookmark -l' to see your bookmarks." % ps)
2846
2846
2847 # at this point ps should point to the target dir
2847 # at this point ps should point to the target dir
2848 if ps:
2848 if ps:
2849 try:
2849 try:
2850 os.chdir(os.path.expanduser(ps))
2850 os.chdir(os.path.expanduser(ps))
2851 if self.shell.rc.term_title:
2851 if self.shell.rc.term_title:
2852 #print 'set term title:',self.shell.rc.term_title # dbg
2852 #print 'set term title:',self.shell.rc.term_title # dbg
2853 platutils.set_term_title('IPy ' + abbrev_cwd())
2853 platutils.set_term_title('IPy ' + abbrev_cwd())
2854 except OSError:
2854 except OSError:
2855 print sys.exc_info()[1]
2855 print sys.exc_info()[1]
2856 else:
2856 else:
2857 cwd = os.getcwd()
2857 cwd = os.getcwd()
2858 dhist = self.shell.user_ns['_dh']
2858 dhist = self.shell.user_ns['_dh']
2859 if oldcwd != cwd:
2859 if oldcwd != cwd:
2860 dhist.append(cwd)
2860 dhist.append(cwd)
2861 self.db['dhist'] = compress_dhist(dhist)[-100:]
2861 self.db['dhist'] = compress_dhist(dhist)[-100:]
2862
2862
2863 else:
2863 else:
2864 os.chdir(self.shell.home_dir)
2864 os.chdir(self.shell.home_dir)
2865 if self.shell.rc.term_title:
2865 if self.shell.rc.term_title:
2866 platutils.set_term_title("IPy ~")
2866 platutils.set_term_title("IPy ~")
2867 cwd = os.getcwd()
2867 cwd = os.getcwd()
2868 dhist = self.shell.user_ns['_dh']
2868 dhist = self.shell.user_ns['_dh']
2869
2869
2870 if oldcwd != cwd:
2870 if oldcwd != cwd:
2871 dhist.append(cwd)
2871 dhist.append(cwd)
2872 self.db['dhist'] = compress_dhist(dhist)[-100:]
2872 self.db['dhist'] = compress_dhist(dhist)[-100:]
2873 if not 'q' in opts and self.shell.user_ns['_dh']:
2873 if not 'q' in opts and self.shell.user_ns['_dh']:
2874 print self.shell.user_ns['_dh'][-1]
2874 print self.shell.user_ns['_dh'][-1]
2875
2875
2876
2876
2877 def magic_env(self, parameter_s=''):
2877 def magic_env(self, parameter_s=''):
2878 """List environment variables."""
2878 """List environment variables."""
2879
2879
2880 return os.environ.data
2880 return os.environ.data
2881
2881
2882 def magic_pushd(self, parameter_s=''):
2882 def magic_pushd(self, parameter_s=''):
2883 """Place the current dir on stack and change directory.
2883 """Place the current dir on stack and change directory.
2884
2884
2885 Usage:\\
2885 Usage:\\
2886 %pushd ['dirname']
2886 %pushd ['dirname']
2887 """
2887 """
2888
2888
2889 dir_s = self.shell.dir_stack
2889 dir_s = self.shell.dir_stack
2890 tgt = os.path.expanduser(parameter_s)
2890 tgt = os.path.expanduser(parameter_s)
2891 cwd = os.getcwd().replace(self.home_dir,'~')
2891 cwd = os.getcwd().replace(self.home_dir,'~')
2892 if tgt:
2892 if tgt:
2893 self.magic_cd(parameter_s)
2893 self.magic_cd(parameter_s)
2894 dir_s.insert(0,cwd)
2894 dir_s.insert(0,cwd)
2895 return self.magic_dirs()
2895 return self.magic_dirs()
2896
2896
2897 def magic_popd(self, parameter_s=''):
2897 def magic_popd(self, parameter_s=''):
2898 """Change to directory popped off the top of the stack.
2898 """Change to directory popped off the top of the stack.
2899 """
2899 """
2900 if not self.shell.dir_stack:
2900 if not self.shell.dir_stack:
2901 raise UsageError("%popd on empty stack")
2901 raise UsageError("%popd on empty stack")
2902 top = self.shell.dir_stack.pop(0)
2902 top = self.shell.dir_stack.pop(0)
2903 self.magic_cd(top)
2903 self.magic_cd(top)
2904 print "popd ->",top
2904 print "popd ->",top
2905
2905
2906 def magic_dirs(self, parameter_s=''):
2906 def magic_dirs(self, parameter_s=''):
2907 """Return the current directory stack."""
2907 """Return the current directory stack."""
2908
2908
2909 return self.shell.dir_stack
2909 return self.shell.dir_stack
2910
2910
2911 def magic_dhist(self, parameter_s=''):
2911 def magic_dhist(self, parameter_s=''):
2912 """Print your history of visited directories.
2912 """Print your history of visited directories.
2913
2913
2914 %dhist -> print full history\\
2914 %dhist -> print full history\\
2915 %dhist n -> print last n entries only\\
2915 %dhist n -> print last n entries only\\
2916 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2916 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2917
2917
2918 This history is automatically maintained by the %cd command, and
2918 This history is automatically maintained by the %cd command, and
2919 always available as the global list variable _dh. You can use %cd -<n>
2919 always available as the global list variable _dh. You can use %cd -<n>
2920 to go to directory number <n>.
2920 to go to directory number <n>.
2921
2921
2922 Note that most of time, you should view directory history by entering
2922 Note that most of time, you should view directory history by entering
2923 cd -<TAB>.
2923 cd -<TAB>.
2924
2924
2925 """
2925 """
2926
2926
2927 dh = self.shell.user_ns['_dh']
2927 dh = self.shell.user_ns['_dh']
2928 if parameter_s:
2928 if parameter_s:
2929 try:
2929 try:
2930 args = map(int,parameter_s.split())
2930 args = map(int,parameter_s.split())
2931 except:
2931 except:
2932 self.arg_err(Magic.magic_dhist)
2932 self.arg_err(Magic.magic_dhist)
2933 return
2933 return
2934 if len(args) == 1:
2934 if len(args) == 1:
2935 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2935 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2936 elif len(args) == 2:
2936 elif len(args) == 2:
2937 ini,fin = args
2937 ini,fin = args
2938 else:
2938 else:
2939 self.arg_err(Magic.magic_dhist)
2939 self.arg_err(Magic.magic_dhist)
2940 return
2940 return
2941 else:
2941 else:
2942 ini,fin = 0,len(dh)
2942 ini,fin = 0,len(dh)
2943 nlprint(dh,
2943 nlprint(dh,
2944 header = 'Directory history (kept in _dh)',
2944 header = 'Directory history (kept in _dh)',
2945 start=ini,stop=fin)
2945 start=ini,stop=fin)
2946
2946
2947 @testdec.skip_doctest
2947 @testdec.skip_doctest
2948 def magic_sc(self, parameter_s=''):
2948 def magic_sc(self, parameter_s=''):
2949 """Shell capture - execute a shell command and capture its output.
2949 """Shell capture - execute a shell command and capture its output.
2950
2950
2951 DEPRECATED. Suboptimal, retained for backwards compatibility.
2951 DEPRECATED. Suboptimal, retained for backwards compatibility.
2952
2952
2953 You should use the form 'var = !command' instead. Example:
2953 You should use the form 'var = !command' instead. Example:
2954
2954
2955 "%sc -l myfiles = ls ~" should now be written as
2955 "%sc -l myfiles = ls ~" should now be written as
2956
2956
2957 "myfiles = !ls ~"
2957 "myfiles = !ls ~"
2958
2958
2959 myfiles.s, myfiles.l and myfiles.n still apply as documented
2959 myfiles.s, myfiles.l and myfiles.n still apply as documented
2960 below.
2960 below.
2961
2961
2962 --
2962 --
2963 %sc [options] varname=command
2963 %sc [options] varname=command
2964
2964
2965 IPython will run the given command using commands.getoutput(), and
2965 IPython will run the given command using commands.getoutput(), and
2966 will then update the user's interactive namespace with a variable
2966 will then update the user's interactive namespace with a variable
2967 called varname, containing the value of the call. Your command can
2967 called varname, containing the value of the call. Your command can
2968 contain shell wildcards, pipes, etc.
2968 contain shell wildcards, pipes, etc.
2969
2969
2970 The '=' sign in the syntax is mandatory, and the variable name you
2970 The '=' sign in the syntax is mandatory, and the variable name you
2971 supply must follow Python's standard conventions for valid names.
2971 supply must follow Python's standard conventions for valid names.
2972
2972
2973 (A special format without variable name exists for internal use)
2973 (A special format without variable name exists for internal use)
2974
2974
2975 Options:
2975 Options:
2976
2976
2977 -l: list output. Split the output on newlines into a list before
2977 -l: list output. Split the output on newlines into a list before
2978 assigning it to the given variable. By default the output is stored
2978 assigning it to the given variable. By default the output is stored
2979 as a single string.
2979 as a single string.
2980
2980
2981 -v: verbose. Print the contents of the variable.
2981 -v: verbose. Print the contents of the variable.
2982
2982
2983 In most cases you should not need to split as a list, because the
2983 In most cases you should not need to split as a list, because the
2984 returned value is a special type of string which can automatically
2984 returned value is a special type of string which can automatically
2985 provide its contents either as a list (split on newlines) or as a
2985 provide its contents either as a list (split on newlines) or as a
2986 space-separated string. These are convenient, respectively, either
2986 space-separated string. These are convenient, respectively, either
2987 for sequential processing or to be passed to a shell command.
2987 for sequential processing or to be passed to a shell command.
2988
2988
2989 For example:
2989 For example:
2990
2990
2991 # all-random
2991 # all-random
2992
2992
2993 # Capture into variable a
2993 # Capture into variable a
2994 In [1]: sc a=ls *py
2994 In [1]: sc a=ls *py
2995
2995
2996 # a is a string with embedded newlines
2996 # a is a string with embedded newlines
2997 In [2]: a
2997 In [2]: a
2998 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2998 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2999
2999
3000 # which can be seen as a list:
3000 # which can be seen as a list:
3001 In [3]: a.l
3001 In [3]: a.l
3002 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3002 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3003
3003
3004 # or as a whitespace-separated string:
3004 # or as a whitespace-separated string:
3005 In [4]: a.s
3005 In [4]: a.s
3006 Out[4]: 'setup.py win32_manual_post_install.py'
3006 Out[4]: 'setup.py win32_manual_post_install.py'
3007
3007
3008 # a.s is useful to pass as a single command line:
3008 # a.s is useful to pass as a single command line:
3009 In [5]: !wc -l $a.s
3009 In [5]: !wc -l $a.s
3010 146 setup.py
3010 146 setup.py
3011 130 win32_manual_post_install.py
3011 130 win32_manual_post_install.py
3012 276 total
3012 276 total
3013
3013
3014 # while the list form is useful to loop over:
3014 # while the list form is useful to loop over:
3015 In [6]: for f in a.l:
3015 In [6]: for f in a.l:
3016 ...: !wc -l $f
3016 ...: !wc -l $f
3017 ...:
3017 ...:
3018 146 setup.py
3018 146 setup.py
3019 130 win32_manual_post_install.py
3019 130 win32_manual_post_install.py
3020
3020
3021 Similiarly, the lists returned by the -l option are also special, in
3021 Similiarly, the lists returned by the -l option are also special, in
3022 the sense that you can equally invoke the .s attribute on them to
3022 the sense that you can equally invoke the .s attribute on them to
3023 automatically get a whitespace-separated string from their contents:
3023 automatically get a whitespace-separated string from their contents:
3024
3024
3025 In [7]: sc -l b=ls *py
3025 In [7]: sc -l b=ls *py
3026
3026
3027 In [8]: b
3027 In [8]: b
3028 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3028 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3029
3029
3030 In [9]: b.s
3030 In [9]: b.s
3031 Out[9]: 'setup.py win32_manual_post_install.py'
3031 Out[9]: 'setup.py win32_manual_post_install.py'
3032
3032
3033 In summary, both the lists and strings used for ouptut capture have
3033 In summary, both the lists and strings used for ouptut capture have
3034 the following special attributes:
3034 the following special attributes:
3035
3035
3036 .l (or .list) : value as list.
3036 .l (or .list) : value as list.
3037 .n (or .nlstr): value as newline-separated string.
3037 .n (or .nlstr): value as newline-separated string.
3038 .s (or .spstr): value as space-separated string.
3038 .s (or .spstr): value as space-separated string.
3039 """
3039 """
3040
3040
3041 opts,args = self.parse_options(parameter_s,'lv')
3041 opts,args = self.parse_options(parameter_s,'lv')
3042 # Try to get a variable name and command to run
3042 # Try to get a variable name and command to run
3043 try:
3043 try:
3044 # the variable name must be obtained from the parse_options
3044 # the variable name must be obtained from the parse_options
3045 # output, which uses shlex.split to strip options out.
3045 # output, which uses shlex.split to strip options out.
3046 var,_ = args.split('=',1)
3046 var,_ = args.split('=',1)
3047 var = var.strip()
3047 var = var.strip()
3048 # But the the command has to be extracted from the original input
3048 # But the the command has to be extracted from the original input
3049 # parameter_s, not on what parse_options returns, to avoid the
3049 # parameter_s, not on what parse_options returns, to avoid the
3050 # quote stripping which shlex.split performs on it.
3050 # quote stripping which shlex.split performs on it.
3051 _,cmd = parameter_s.split('=',1)
3051 _,cmd = parameter_s.split('=',1)
3052 except ValueError:
3052 except ValueError:
3053 var,cmd = '',''
3053 var,cmd = '',''
3054 # If all looks ok, proceed
3054 # If all looks ok, proceed
3055 out,err = self.shell.getoutputerror(cmd)
3055 out,err = self.shell.getoutputerror(cmd)
3056 if err:
3056 if err:
3057 print >> Term.cerr,err
3057 print >> Term.cerr,err
3058 if opts.has_key('l'):
3058 if opts.has_key('l'):
3059 out = SList(out.split('\n'))
3059 out = SList(out.split('\n'))
3060 else:
3060 else:
3061 out = LSString(out)
3061 out = LSString(out)
3062 if opts.has_key('v'):
3062 if opts.has_key('v'):
3063 print '%s ==\n%s' % (var,pformat(out))
3063 print '%s ==\n%s' % (var,pformat(out))
3064 if var:
3064 if var:
3065 self.shell.user_ns.update({var:out})
3065 self.shell.user_ns.update({var:out})
3066 else:
3066 else:
3067 return out
3067 return out
3068
3068
3069 def magic_sx(self, parameter_s=''):
3069 def magic_sx(self, parameter_s=''):
3070 """Shell execute - run a shell command and capture its output.
3070 """Shell execute - run a shell command and capture its output.
3071
3071
3072 %sx command
3072 %sx command
3073
3073
3074 IPython will run the given command using commands.getoutput(), and
3074 IPython will run the given command using commands.getoutput(), and
3075 return the result formatted as a list (split on '\\n'). Since the
3075 return the result formatted as a list (split on '\\n'). Since the
3076 output is _returned_, it will be stored in ipython's regular output
3076 output is _returned_, it will be stored in ipython's regular output
3077 cache Out[N] and in the '_N' automatic variables.
3077 cache Out[N] and in the '_N' automatic variables.
3078
3078
3079 Notes:
3079 Notes:
3080
3080
3081 1) If an input line begins with '!!', then %sx is automatically
3081 1) If an input line begins with '!!', then %sx is automatically
3082 invoked. That is, while:
3082 invoked. That is, while:
3083 !ls
3083 !ls
3084 causes ipython to simply issue system('ls'), typing
3084 causes ipython to simply issue system('ls'), typing
3085 !!ls
3085 !!ls
3086 is a shorthand equivalent to:
3086 is a shorthand equivalent to:
3087 %sx ls
3087 %sx ls
3088
3088
3089 2) %sx differs from %sc in that %sx automatically splits into a list,
3089 2) %sx differs from %sc in that %sx automatically splits into a list,
3090 like '%sc -l'. The reason for this is to make it as easy as possible
3090 like '%sc -l'. The reason for this is to make it as easy as possible
3091 to process line-oriented shell output via further python commands.
3091 to process line-oriented shell output via further python commands.
3092 %sc is meant to provide much finer control, but requires more
3092 %sc is meant to provide much finer control, but requires more
3093 typing.
3093 typing.
3094
3094
3095 3) Just like %sc -l, this is a list with special attributes:
3095 3) Just like %sc -l, this is a list with special attributes:
3096
3096
3097 .l (or .list) : value as list.
3097 .l (or .list) : value as list.
3098 .n (or .nlstr): value as newline-separated string.
3098 .n (or .nlstr): value as newline-separated string.
3099 .s (or .spstr): value as whitespace-separated string.
3099 .s (or .spstr): value as whitespace-separated string.
3100
3100
3101 This is very useful when trying to use such lists as arguments to
3101 This is very useful when trying to use such lists as arguments to
3102 system commands."""
3102 system commands."""
3103
3103
3104 if parameter_s:
3104 if parameter_s:
3105 out,err = self.shell.getoutputerror(parameter_s)
3105 out,err = self.shell.getoutputerror(parameter_s)
3106 if err:
3106 if err:
3107 print >> Term.cerr,err
3107 print >> Term.cerr,err
3108 return SList(out.split('\n'))
3108 return SList(out.split('\n'))
3109
3109
3110 def magic_bg(self, parameter_s=''):
3110 def magic_bg(self, parameter_s=''):
3111 """Run a job in the background, in a separate thread.
3111 """Run a job in the background, in a separate thread.
3112
3112
3113 For example,
3113 For example,
3114
3114
3115 %bg myfunc(x,y,z=1)
3115 %bg myfunc(x,y,z=1)
3116
3116
3117 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3117 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3118 execution starts, a message will be printed indicating the job
3118 execution starts, a message will be printed indicating the job
3119 number. If your job number is 5, you can use
3119 number. If your job number is 5, you can use
3120
3120
3121 myvar = jobs.result(5) or myvar = jobs[5].result
3121 myvar = jobs.result(5) or myvar = jobs[5].result
3122
3122
3123 to assign this result to variable 'myvar'.
3123 to assign this result to variable 'myvar'.
3124
3124
3125 IPython has a job manager, accessible via the 'jobs' object. You can
3125 IPython has a job manager, accessible via the 'jobs' object. You can
3126 type jobs? to get more information about it, and use jobs.<TAB> to see
3126 type jobs? to get more information about it, and use jobs.<TAB> to see
3127 its attributes. All attributes not starting with an underscore are
3127 its attributes. All attributes not starting with an underscore are
3128 meant for public use.
3128 meant for public use.
3129
3129
3130 In particular, look at the jobs.new() method, which is used to create
3130 In particular, look at the jobs.new() method, which is used to create
3131 new jobs. This magic %bg function is just a convenience wrapper
3131 new jobs. This magic %bg function is just a convenience wrapper
3132 around jobs.new(), for expression-based jobs. If you want to create a
3132 around jobs.new(), for expression-based jobs. If you want to create a
3133 new job with an explicit function object and arguments, you must call
3133 new job with an explicit function object and arguments, you must call
3134 jobs.new() directly.
3134 jobs.new() directly.
3135
3135
3136 The jobs.new docstring also describes in detail several important
3136 The jobs.new docstring also describes in detail several important
3137 caveats associated with a thread-based model for background job
3137 caveats associated with a thread-based model for background job
3138 execution. Type jobs.new? for details.
3138 execution. Type jobs.new? for details.
3139
3139
3140 You can check the status of all jobs with jobs.status().
3140 You can check the status of all jobs with jobs.status().
3141
3141
3142 The jobs variable is set by IPython into the Python builtin namespace.
3142 The jobs variable is set by IPython into the Python builtin namespace.
3143 If you ever declare a variable named 'jobs', you will shadow this
3143 If you ever declare a variable named 'jobs', you will shadow this
3144 name. You can either delete your global jobs variable to regain
3144 name. You can either delete your global jobs variable to regain
3145 access to the job manager, or make a new name and assign it manually
3145 access to the job manager, or make a new name and assign it manually
3146 to the manager (stored in IPython's namespace). For example, to
3146 to the manager (stored in IPython's namespace). For example, to
3147 assign the job manager to the Jobs name, use:
3147 assign the job manager to the Jobs name, use:
3148
3148
3149 Jobs = __builtins__.jobs"""
3149 Jobs = __builtins__.jobs"""
3150
3150
3151 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3151 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3152
3152
3153 def magic_r(self, parameter_s=''):
3153 def magic_r(self, parameter_s=''):
3154 """Repeat previous input.
3154 """Repeat previous input.
3155
3155
3156 Note: Consider using the more powerfull %rep instead!
3156 Note: Consider using the more powerfull %rep instead!
3157
3157
3158 If given an argument, repeats the previous command which starts with
3158 If given an argument, repeats the previous command which starts with
3159 the same string, otherwise it just repeats the previous input.
3159 the same string, otherwise it just repeats the previous input.
3160
3160
3161 Shell escaped commands (with ! as first character) are not recognized
3161 Shell escaped commands (with ! as first character) are not recognized
3162 by this system, only pure python code and magic commands.
3162 by this system, only pure python code and magic commands.
3163 """
3163 """
3164
3164
3165 start = parameter_s.strip()
3165 start = parameter_s.strip()
3166 esc_magic = self.shell.ESC_MAGIC
3166 esc_magic = self.shell.ESC_MAGIC
3167 # Identify magic commands even if automagic is on (which means
3167 # Identify magic commands even if automagic is on (which means
3168 # the in-memory version is different from that typed by the user).
3168 # the in-memory version is different from that typed by the user).
3169 if self.shell.rc.automagic:
3169 if self.shell.rc.automagic:
3170 start_magic = esc_magic+start
3170 start_magic = esc_magic+start
3171 else:
3171 else:
3172 start_magic = start
3172 start_magic = start
3173 # Look through the input history in reverse
3173 # Look through the input history in reverse
3174 for n in range(len(self.shell.input_hist)-2,0,-1):
3174 for n in range(len(self.shell.input_hist)-2,0,-1):
3175 input = self.shell.input_hist[n]
3175 input = self.shell.input_hist[n]
3176 # skip plain 'r' lines so we don't recurse to infinity
3176 # skip plain 'r' lines so we don't recurse to infinity
3177 if input != '_ip.magic("r")\n' and \
3177 if input != '_ip.magic("r")\n' and \
3178 (input.startswith(start) or input.startswith(start_magic)):
3178 (input.startswith(start) or input.startswith(start_magic)):
3179 #print 'match',`input` # dbg
3179 #print 'match',`input` # dbg
3180 print 'Executing:',input,
3180 print 'Executing:',input,
3181 self.shell.runlines(input)
3181 self.shell.runlines(input)
3182 return
3182 return
3183 print 'No previous input matching `%s` found.' % start
3183 print 'No previous input matching `%s` found.' % start
3184
3184
3185
3185
3186 def magic_bookmark(self, parameter_s=''):
3186 def magic_bookmark(self, parameter_s=''):
3187 """Manage IPython's bookmark system.
3187 """Manage IPython's bookmark system.
3188
3188
3189 %bookmark <name> - set bookmark to current dir
3189 %bookmark <name> - set bookmark to current dir
3190 %bookmark <name> <dir> - set bookmark to <dir>
3190 %bookmark <name> <dir> - set bookmark to <dir>
3191 %bookmark -l - list all bookmarks
3191 %bookmark -l - list all bookmarks
3192 %bookmark -d <name> - remove bookmark
3192 %bookmark -d <name> - remove bookmark
3193 %bookmark -r - remove all bookmarks
3193 %bookmark -r - remove all bookmarks
3194
3194
3195 You can later on access a bookmarked folder with:
3195 You can later on access a bookmarked folder with:
3196 %cd -b <name>
3196 %cd -b <name>
3197 or simply '%cd <name>' if there is no directory called <name> AND
3197 or simply '%cd <name>' if there is no directory called <name> AND
3198 there is such a bookmark defined.
3198 there is such a bookmark defined.
3199
3199
3200 Your bookmarks persist through IPython sessions, but they are
3200 Your bookmarks persist through IPython sessions, but they are
3201 associated with each profile."""
3201 associated with each profile."""
3202
3202
3203 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3203 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3204 if len(args) > 2:
3204 if len(args) > 2:
3205 raise UsageError("%bookmark: too many arguments")
3205 raise UsageError("%bookmark: too many arguments")
3206
3206
3207 bkms = self.db.get('bookmarks',{})
3207 bkms = self.db.get('bookmarks',{})
3208
3208
3209 if opts.has_key('d'):
3209 if opts.has_key('d'):
3210 try:
3210 try:
3211 todel = args[0]
3211 todel = args[0]
3212 except IndexError:
3212 except IndexError:
3213 raise UsageError(
3213 raise UsageError(
3214 "%bookmark -d: must provide a bookmark to delete")
3214 "%bookmark -d: must provide a bookmark to delete")
3215 else:
3215 else:
3216 try:
3216 try:
3217 del bkms[todel]
3217 del bkms[todel]
3218 except KeyError:
3218 except KeyError:
3219 raise UsageError(
3219 raise UsageError(
3220 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3220 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3221
3221
3222 elif opts.has_key('r'):
3222 elif opts.has_key('r'):
3223 bkms = {}
3223 bkms = {}
3224 elif opts.has_key('l'):
3224 elif opts.has_key('l'):
3225 bks = bkms.keys()
3225 bks = bkms.keys()
3226 bks.sort()
3226 bks.sort()
3227 if bks:
3227 if bks:
3228 size = max(map(len,bks))
3228 size = max(map(len,bks))
3229 else:
3229 else:
3230 size = 0
3230 size = 0
3231 fmt = '%-'+str(size)+'s -> %s'
3231 fmt = '%-'+str(size)+'s -> %s'
3232 print 'Current bookmarks:'
3232 print 'Current bookmarks:'
3233 for bk in bks:
3233 for bk in bks:
3234 print fmt % (bk,bkms[bk])
3234 print fmt % (bk,bkms[bk])
3235 else:
3235 else:
3236 if not args:
3236 if not args:
3237 raise UsageError("%bookmark: You must specify the bookmark name")
3237 raise UsageError("%bookmark: You must specify the bookmark name")
3238 elif len(args)==1:
3238 elif len(args)==1:
3239 bkms[args[0]] = os.getcwd()
3239 bkms[args[0]] = os.getcwd()
3240 elif len(args)==2:
3240 elif len(args)==2:
3241 bkms[args[0]] = args[1]
3241 bkms[args[0]] = args[1]
3242 self.db['bookmarks'] = bkms
3242 self.db['bookmarks'] = bkms
3243
3243
3244 def magic_pycat(self, parameter_s=''):
3244 def magic_pycat(self, parameter_s=''):
3245 """Show a syntax-highlighted file through a pager.
3245 """Show a syntax-highlighted file through a pager.
3246
3246
3247 This magic is similar to the cat utility, but it will assume the file
3247 This magic is similar to the cat utility, but it will assume the file
3248 to be Python source and will show it with syntax highlighting. """
3248 to be Python source and will show it with syntax highlighting. """
3249
3249
3250 try:
3250 try:
3251 filename = get_py_filename(parameter_s)
3251 filename = get_py_filename(parameter_s)
3252 cont = file_read(filename)
3252 cont = file_read(filename)
3253 except IOError:
3253 except IOError:
3254 try:
3254 try:
3255 cont = eval(parameter_s,self.user_ns)
3255 cont = eval(parameter_s,self.user_ns)
3256 except NameError:
3256 except NameError:
3257 cont = None
3257 cont = None
3258 if cont is None:
3258 if cont is None:
3259 print "Error: no such file or variable"
3259 print "Error: no such file or variable"
3260 return
3260 return
3261
3261
3262 page(self.shell.pycolorize(cont),
3262 page(self.shell.pycolorize(cont),
3263 screen_lines=self.shell.rc.screen_length)
3263 screen_lines=self.shell.rc.screen_length)
3264
3264
3265 def magic_cpaste(self, parameter_s=''):
3265 def magic_cpaste(self, parameter_s=''):
3266 """Allows you to paste & execute a pre-formatted code block from clipboard.
3266 """Allows you to paste & execute a pre-formatted code block from clipboard.
3267
3267
3268 You must terminate the block with '--' (two minus-signs) alone on the
3268 You must terminate the block with '--' (two minus-signs) alone on the
3269 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3269 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3270 is the new sentinel for this operation)
3270 is the new sentinel for this operation)
3271
3271
3272 The block is dedented prior to execution to enable execution of method
3272 The block is dedented prior to execution to enable execution of method
3273 definitions. '>' and '+' characters at the beginning of a line are
3273 definitions. '>' and '+' characters at the beginning of a line are
3274 ignored, to allow pasting directly from e-mails, diff files and
3274 ignored, to allow pasting directly from e-mails, diff files and
3275 doctests (the '...' continuation prompt is also stripped). The
3275 doctests (the '...' continuation prompt is also stripped). The
3276 executed block is also assigned to variable named 'pasted_block' for
3276 executed block is also assigned to variable named 'pasted_block' for
3277 later editing with '%edit pasted_block'.
3277 later editing with '%edit pasted_block'.
3278
3278
3279 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3279 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3280 This assigns the pasted block to variable 'foo' as string, without
3280 This assigns the pasted block to variable 'foo' as string, without
3281 dedenting or executing it (preceding >>> and + is still stripped)
3281 dedenting or executing it (preceding >>> and + is still stripped)
3282
3282
3283 '%cpaste -r' re-executes the block previously entered by cpaste.
3283 '%cpaste -r' re-executes the block previously entered by cpaste.
3284
3284
3285 Do not be alarmed by garbled output on Windows (it's a readline bug).
3285 Do not be alarmed by garbled output on Windows (it's a readline bug).
3286 Just press enter and type -- (and press enter again) and the block
3286 Just press enter and type -- (and press enter again) and the block
3287 will be what was just pasted.
3287 will be what was just pasted.
3288
3288
3289 IPython statements (magics, shell escapes) are not supported (yet).
3289 IPython statements (magics, shell escapes) are not supported (yet).
3290 """
3290 """
3291 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3291 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3292 par = args.strip()
3292 par = args.strip()
3293 if opts.has_key('r'):
3293 if opts.has_key('r'):
3294 b = self.user_ns.get('pasted_block', None)
3294 b = self.user_ns.get('pasted_block', None)
3295 if b is None:
3295 if b is None:
3296 raise UsageError('No previous pasted block available')
3296 raise UsageError('No previous pasted block available')
3297 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3297 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3298 exec b in self.user_ns
3298 exec b in self.user_ns
3299 return
3299 return
3300
3300
3301 sentinel = opts.get('s','--')
3301 sentinel = opts.get('s','--')
3302
3302
3303 # Regular expressions that declare text we strip from the input:
3303 # Regular expressions that declare text we strip from the input:
3304 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3304 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3305 r'^\s*(\s?>)+', # Python input prompt
3305 r'^\s*(\s?>)+', # Python input prompt
3306 r'^\s*\.{3,}', # Continuation prompts
3306 r'^\s*\.{3,}', # Continuation prompts
3307 r'^\++',
3307 r'^\++',
3308 ]
3308 ]
3309
3309
3310 strip_from_start = map(re.compile,strip_re)
3310 strip_from_start = map(re.compile,strip_re)
3311
3311
3312 from IPython.core import iplib
3312 from IPython.core import iplib
3313 lines = []
3313 lines = []
3314 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3314 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3315 while 1:
3315 while 1:
3316 l = iplib.raw_input_original(':')
3316 l = iplib.raw_input_original(':')
3317 if l ==sentinel:
3317 if l ==sentinel:
3318 break
3318 break
3319
3319
3320 for pat in strip_from_start:
3320 for pat in strip_from_start:
3321 l = pat.sub('',l)
3321 l = pat.sub('',l)
3322 lines.append(l)
3322 lines.append(l)
3323
3323
3324 block = "\n".join(lines) + '\n'
3324 block = "\n".join(lines) + '\n'
3325 #print "block:\n",block
3325 #print "block:\n",block
3326 if not par:
3326 if not par:
3327 b = textwrap.dedent(block)
3327 b = textwrap.dedent(block)
3328 self.user_ns['pasted_block'] = b
3328 self.user_ns['pasted_block'] = b
3329 exec b in self.user_ns
3329 exec b in self.user_ns
3330 else:
3330 else:
3331 self.user_ns[par] = SList(block.splitlines())
3331 self.user_ns[par] = SList(block.splitlines())
3332 print "Block assigned to '%s'" % par
3332 print "Block assigned to '%s'" % par
3333
3333
3334 def magic_quickref(self,arg):
3334 def magic_quickref(self,arg):
3335 """ Show a quick reference sheet """
3335 """ Show a quick reference sheet """
3336 import IPython.usage
3336 import IPython.usage
3337 qr = IPython.usage.quick_reference + self.magic_magic('-brief')
3337 qr = IPython.usage.quick_reference + self.magic_magic('-brief')
3338
3338
3339 page(qr)
3339 page(qr)
3340
3340
3341 def magic_upgrade(self,arg):
3341 def magic_upgrade(self,arg):
3342 """ Upgrade your IPython installation
3342 """ Upgrade your IPython installation
3343
3343
3344 This will copy the config files that don't yet exist in your
3344 This will copy the config files that don't yet exist in your
3345 ipython dir from the system config dir. Use this after upgrading
3345 ipython dir from the system config dir. Use this after upgrading
3346 IPython if you don't wish to delete your .ipython dir.
3346 IPython if you don't wish to delete your .ipython dir.
3347
3347
3348 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3348 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3349 new users)
3349 new users)
3350
3350
3351 """
3351 """
3352 ip = self.getapi()
3352 ip = self.getapi()
3353 ipinstallation = path(IPython.__file__).dirname()
3353 ipinstallation = path(IPython.__file__).dirname()
3354 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'upgrade_dir.py')
3354 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'upgrade_dir.py')
3355 src_config = ipinstallation / 'UserConfig'
3355 src_config = ipinstallation / 'UserConfig'
3356 userdir = path(ip.options.ipythondir)
3356 userdir = path(ip.options.ipythondir)
3357 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3357 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3358 print ">",cmd
3358 print ">",cmd
3359 shell(cmd)
3359 shell(cmd)
3360 if arg == '-nolegacy':
3360 if arg == '-nolegacy':
3361 legacy = userdir.files('ipythonrc*')
3361 legacy = userdir.files('ipythonrc*')
3362 print "Nuking legacy files:",legacy
3362 print "Nuking legacy files:",legacy
3363
3363
3364 [p.remove() for p in legacy]
3364 [p.remove() for p in legacy]
3365 suffix = (sys.platform == 'win32' and '.ini' or '')
3365 suffix = (sys.platform == 'win32' and '.ini' or '')
3366 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3366 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3367
3367
3368
3368
3369 def magic_doctest_mode(self,parameter_s=''):
3369 def magic_doctest_mode(self,parameter_s=''):
3370 """Toggle doctest mode on and off.
3370 """Toggle doctest mode on and off.
3371
3371
3372 This mode allows you to toggle the prompt behavior between normal
3372 This mode allows you to toggle the prompt behavior between normal
3373 IPython prompts and ones that are as similar to the default IPython
3373 IPython prompts and ones that are as similar to the default IPython
3374 interpreter as possible.
3374 interpreter as possible.
3375
3375
3376 It also supports the pasting of code snippets that have leading '>>>'
3376 It also supports the pasting of code snippets that have leading '>>>'
3377 and '...' prompts in them. This means that you can paste doctests from
3377 and '...' prompts in them. This means that you can paste doctests from
3378 files or docstrings (even if they have leading whitespace), and the
3378 files or docstrings (even if they have leading whitespace), and the
3379 code will execute correctly. You can then use '%history -tn' to see
3379 code will execute correctly. You can then use '%history -tn' to see
3380 the translated history without line numbers; this will give you the
3380 the translated history without line numbers; this will give you the
3381 input after removal of all the leading prompts and whitespace, which
3381 input after removal of all the leading prompts and whitespace, which
3382 can be pasted back into an editor.
3382 can be pasted back into an editor.
3383
3383
3384 With these features, you can switch into this mode easily whenever you
3384 With these features, you can switch into this mode easily whenever you
3385 need to do testing and changes to doctests, without having to leave
3385 need to do testing and changes to doctests, without having to leave
3386 your existing IPython session.
3386 your existing IPython session.
3387 """
3387 """
3388
3388
3389 # XXX - Fix this to have cleaner activate/deactivate calls.
3389 # XXX - Fix this to have cleaner activate/deactivate calls.
3390 from IPython.Extensions import InterpreterPasteInput as ipaste
3390 from IPython.Extensions import InterpreterPasteInput as ipaste
3391 from IPython.utils.ipstruct import Struct
3391 from IPython.utils.ipstruct import Struct
3392
3392
3393 # Shorthands
3393 # Shorthands
3394 shell = self.shell
3394 shell = self.shell
3395 oc = shell.outputcache
3395 oc = shell.outputcache
3396 rc = shell.rc
3396 rc = shell.rc
3397 meta = shell.meta
3397 meta = shell.meta
3398 # dstore is a data store kept in the instance metadata bag to track any
3398 # dstore is a data store kept in the instance metadata bag to track any
3399 # changes we make, so we can undo them later.
3399 # changes we make, so we can undo them later.
3400 dstore = meta.setdefault('doctest_mode',Struct())
3400 dstore = meta.setdefault('doctest_mode',Struct())
3401 save_dstore = dstore.setdefault
3401 save_dstore = dstore.setdefault
3402
3402
3403 # save a few values we'll need to recover later
3403 # save a few values we'll need to recover later
3404 mode = save_dstore('mode',False)
3404 mode = save_dstore('mode',False)
3405 save_dstore('rc_pprint',rc.pprint)
3405 save_dstore('rc_pprint',rc.pprint)
3406 save_dstore('xmode',shell.InteractiveTB.mode)
3406 save_dstore('xmode',shell.InteractiveTB.mode)
3407 save_dstore('rc_separate_out',rc.separate_out)
3407 save_dstore('rc_separate_out',rc.separate_out)
3408 save_dstore('rc_separate_out2',rc.separate_out2)
3408 save_dstore('rc_separate_out2',rc.separate_out2)
3409 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3409 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3410 save_dstore('rc_separate_in',rc.separate_in)
3410 save_dstore('rc_separate_in',rc.separate_in)
3411
3411
3412 if mode == False:
3412 if mode == False:
3413 # turn on
3413 # turn on
3414 ipaste.activate_prefilter()
3414 ipaste.activate_prefilter()
3415
3415
3416 oc.prompt1.p_template = '>>> '
3416 oc.prompt1.p_template = '>>> '
3417 oc.prompt2.p_template = '... '
3417 oc.prompt2.p_template = '... '
3418 oc.prompt_out.p_template = ''
3418 oc.prompt_out.p_template = ''
3419
3419
3420 # Prompt separators like plain python
3420 # Prompt separators like plain python
3421 oc.input_sep = oc.prompt1.sep = ''
3421 oc.input_sep = oc.prompt1.sep = ''
3422 oc.output_sep = ''
3422 oc.output_sep = ''
3423 oc.output_sep2 = ''
3423 oc.output_sep2 = ''
3424
3424
3425 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3425 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3426 oc.prompt_out.pad_left = False
3426 oc.prompt_out.pad_left = False
3427
3427
3428 rc.pprint = False
3428 rc.pprint = False
3429
3429
3430 shell.magic_xmode('Plain')
3430 shell.magic_xmode('Plain')
3431
3431
3432 else:
3432 else:
3433 # turn off
3433 # turn off
3434 ipaste.deactivate_prefilter()
3434 ipaste.deactivate_prefilter()
3435
3435
3436 oc.prompt1.p_template = rc.prompt_in1
3436 oc.prompt1.p_template = rc.prompt_in1
3437 oc.prompt2.p_template = rc.prompt_in2
3437 oc.prompt2.p_template = rc.prompt_in2
3438 oc.prompt_out.p_template = rc.prompt_out
3438 oc.prompt_out.p_template = rc.prompt_out
3439
3439
3440 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3440 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3441
3441
3442 oc.output_sep = dstore.rc_separate_out
3442 oc.output_sep = dstore.rc_separate_out
3443 oc.output_sep2 = dstore.rc_separate_out2
3443 oc.output_sep2 = dstore.rc_separate_out2
3444
3444
3445 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3445 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3446 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3446 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3447
3447
3448 rc.pprint = dstore.rc_pprint
3448 rc.pprint = dstore.rc_pprint
3449
3449
3450 shell.magic_xmode(dstore.xmode)
3450 shell.magic_xmode(dstore.xmode)
3451
3451
3452 # Store new mode and inform
3452 # Store new mode and inform
3453 dstore.mode = bool(1-int(mode))
3453 dstore.mode = bool(1-int(mode))
3454 print 'Doctest mode is:',
3454 print 'Doctest mode is:',
3455 print ['OFF','ON'][dstore.mode]
3455 print ['OFF','ON'][dstore.mode]
3456
3456
3457 # end Magic
3457 # end Magic
@@ -1,300 +1,300 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """IPython Test Suite Runner.
2 """IPython Test Suite Runner.
3
3
4 This module provides a main entry point to a user script to test IPython
4 This module provides a main entry point to a user script to test IPython
5 itself from the command line. There are two ways of running this script:
5 itself from the command line. There are two ways of running this script:
6
6
7 1. With the syntax `iptest all`. This runs our entire test suite by
7 1. With the syntax `iptest all`. This runs our entire test suite by
8 calling this script (with different arguments) or trial recursively. This
8 calling this script (with different arguments) or trial recursively. This
9 causes modules and package to be tested in different processes, using nose
9 causes modules and package to be tested in different processes, using nose
10 or trial where appropriate.
10 or trial where appropriate.
11 2. With the regular nose syntax, like `iptest -vvs IPython`. In this form
11 2. With the regular nose syntax, like `iptest -vvs IPython`. In this form
12 the script simply calls nose, but with special command line flags and
12 the script simply calls nose, but with special command line flags and
13 plugins loaded.
13 plugins loaded.
14
14
15 For now, this script requires that both nose and twisted are installed. This
15 For now, this script requires that both nose and twisted are installed. This
16 will change in the future.
16 will change in the future.
17 """
17 """
18
18
19 #-----------------------------------------------------------------------------
19 #-----------------------------------------------------------------------------
20 # Module imports
20 # Module imports
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22
22
23 import os
23 import os
24 import os.path as path
24 import os.path as path
25 import sys
25 import sys
26 import subprocess
26 import subprocess
27 import time
27 import time
28 import warnings
28 import warnings
29
29
30 import nose.plugins.builtin
30 import nose.plugins.builtin
31 from nose.core import TestProgram
31 from nose.core import TestProgram
32
32
33 from IPython.platutils import find_cmd
33 from IPython.utils.platutils import find_cmd
34 from IPython.testing.plugin.ipdoctest import IPythonDoctest
34 from IPython.testing.plugin.ipdoctest import IPythonDoctest
35
35
36 pjoin = path.join
36 pjoin = path.join
37
37
38 #-----------------------------------------------------------------------------
38 #-----------------------------------------------------------------------------
39 # Logic for skipping doctests
39 # Logic for skipping doctests
40 #-----------------------------------------------------------------------------
40 #-----------------------------------------------------------------------------
41
41
42 def test_for(mod):
42 def test_for(mod):
43 """Test to see if mod is importable."""
43 """Test to see if mod is importable."""
44 try:
44 try:
45 __import__(mod)
45 __import__(mod)
46 except ImportError:
46 except ImportError:
47 return False
47 return False
48 else:
48 else:
49 return True
49 return True
50
50
51 have_curses = test_for('_curses')
51 have_curses = test_for('_curses')
52 have_wx = test_for('wx')
52 have_wx = test_for('wx')
53 have_zi = test_for('zope.interface')
53 have_zi = test_for('zope.interface')
54 have_twisted = test_for('twisted')
54 have_twisted = test_for('twisted')
55 have_foolscap = test_for('foolscap')
55 have_foolscap = test_for('foolscap')
56 have_objc = test_for('objc')
56 have_objc = test_for('objc')
57 have_pexpect = test_for('pexpect')
57 have_pexpect = test_for('pexpect')
58
58
59 # For the IPythonDoctest plugin, we need to exclude certain patterns that cause
59 # For the IPythonDoctest plugin, we need to exclude certain patterns that cause
60 # testing problems. We should strive to minimize the number of skipped
60 # testing problems. We should strive to minimize the number of skipped
61 # modules, since this means untested code. As the testing machinery
61 # modules, since this means untested code. As the testing machinery
62 # solidifies, this list should eventually become empty.
62 # solidifies, this list should eventually become empty.
63 EXCLUDE = [pjoin('IPython', 'external'),
63 EXCLUDE = [pjoin('IPython', 'external'),
64 pjoin('IPython', 'frontend', 'process', 'winprocess.py'),
64 pjoin('IPython', 'frontend', 'process', 'winprocess.py'),
65 pjoin('IPython_doctest_plugin'),
65 pjoin('IPython_doctest_plugin'),
66 pjoin('IPython', 'Gnuplot'),
66 pjoin('IPython', 'Gnuplot'),
67 pjoin('IPython', 'Extensions', 'ipy_'),
67 pjoin('IPython', 'Extensions', 'ipy_'),
68 pjoin('IPython', 'Extensions', 'clearcmd'),
68 pjoin('IPython', 'Extensions', 'clearcmd'),
69 pjoin('IPython', 'Extensions', 'PhysicalQInteractive'),
69 pjoin('IPython', 'Extensions', 'PhysicalQInteractive'),
70 pjoin('IPython', 'Extensions', 'scitedirector'),
70 pjoin('IPython', 'Extensions', 'scitedirector'),
71 pjoin('IPython', 'Extensions', 'numeric_formats'),
71 pjoin('IPython', 'Extensions', 'numeric_formats'),
72 pjoin('IPython', 'testing', 'attic'),
72 pjoin('IPython', 'testing', 'attic'),
73 pjoin('IPython', 'testing', 'tutils'),
73 pjoin('IPython', 'testing', 'tutils'),
74 pjoin('IPython', 'testing', 'tools'),
74 pjoin('IPython', 'testing', 'tools'),
75 pjoin('IPython', 'testing', 'mkdoctests')
75 pjoin('IPython', 'testing', 'mkdoctests')
76 ]
76 ]
77
77
78 if not have_wx:
78 if not have_wx:
79 EXCLUDE.append(pjoin('IPython', 'Extensions', 'igrid'))
79 EXCLUDE.append(pjoin('IPython', 'Extensions', 'igrid'))
80 EXCLUDE.append(pjoin('IPython', 'gui'))
80 EXCLUDE.append(pjoin('IPython', 'gui'))
81 EXCLUDE.append(pjoin('IPython', 'frontend', 'wx'))
81 EXCLUDE.append(pjoin('IPython', 'frontend', 'wx'))
82
82
83 if not have_objc:
83 if not have_objc:
84 EXCLUDE.append(pjoin('IPython', 'frontend', 'cocoa'))
84 EXCLUDE.append(pjoin('IPython', 'frontend', 'cocoa'))
85
85
86 if not have_curses:
86 if not have_curses:
87 EXCLUDE.append(pjoin('IPython', 'Extensions', 'ibrowse'))
87 EXCLUDE.append(pjoin('IPython', 'Extensions', 'ibrowse'))
88
88
89 if not sys.platform == 'win32':
89 if not sys.platform == 'win32':
90 EXCLUDE.append(pjoin('IPython', 'platutils_win32'))
90 EXCLUDE.append(pjoin('IPython', 'platutils_win32'))
91
91
92 # These have to be skipped on win32 because the use echo, rm, cd, etc.
92 # These have to be skipped on win32 because the use echo, rm, cd, etc.
93 # See ticket https://bugs.launchpad.net/bugs/366982
93 # See ticket https://bugs.launchpad.net/bugs/366982
94 if sys.platform == 'win32':
94 if sys.platform == 'win32':
95 EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'test_exampleip'))
95 EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'test_exampleip'))
96 EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'dtexample'))
96 EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'dtexample'))
97
97
98 if not os.name == 'posix':
98 if not os.name == 'posix':
99 EXCLUDE.append(pjoin('IPython', 'platutils_posix'))
99 EXCLUDE.append(pjoin('IPython', 'platutils_posix'))
100
100
101 if not have_pexpect:
101 if not have_pexpect:
102 EXCLUDE.append(pjoin('IPython', 'lib', 'irunner'))
102 EXCLUDE.append(pjoin('IPython', 'lib', 'irunner'))
103
103
104 # This is needed for the reg-exp to match on win32 in the ipdoctest plugin.
104 # This is needed for the reg-exp to match on win32 in the ipdoctest plugin.
105 if sys.platform == 'win32':
105 if sys.platform == 'win32':
106 EXCLUDE = [s.replace('\\','\\\\') for s in EXCLUDE]
106 EXCLUDE = [s.replace('\\','\\\\') for s in EXCLUDE]
107
107
108
108
109 #-----------------------------------------------------------------------------
109 #-----------------------------------------------------------------------------
110 # Functions and classes
110 # Functions and classes
111 #-----------------------------------------------------------------------------
111 #-----------------------------------------------------------------------------
112
112
113 def run_iptest():
113 def run_iptest():
114 """Run the IPython test suite using nose.
114 """Run the IPython test suite using nose.
115
115
116 This function is called when this script is **not** called with the form
116 This function is called when this script is **not** called with the form
117 `iptest all`. It simply calls nose with appropriate command line flags
117 `iptest all`. It simply calls nose with appropriate command line flags
118 and accepts all of the standard nose arguments.
118 and accepts all of the standard nose arguments.
119 """
119 """
120
120
121 warnings.filterwarnings('ignore',
121 warnings.filterwarnings('ignore',
122 'This will be removed soon. Use IPython.testing.util instead')
122 'This will be removed soon. Use IPython.testing.util instead')
123
123
124 argv = sys.argv + [
124 argv = sys.argv + [
125 # Loading ipdoctest causes problems with Twisted.
125 # Loading ipdoctest causes problems with Twisted.
126 # I am removing this as a temporary fix to get the
126 # I am removing this as a temporary fix to get the
127 # test suite back into working shape. Our nose
127 # test suite back into working shape. Our nose
128 # plugin needs to be gone through with a fine
128 # plugin needs to be gone through with a fine
129 # toothed comb to find what is causing the problem.
129 # toothed comb to find what is causing the problem.
130 '--with-ipdoctest',
130 '--with-ipdoctest',
131 '--ipdoctest-tests','--ipdoctest-extension=txt',
131 '--ipdoctest-tests','--ipdoctest-extension=txt',
132 '--detailed-errors',
132 '--detailed-errors',
133
133
134 # We add --exe because of setuptools' imbecility (it
134 # We add --exe because of setuptools' imbecility (it
135 # blindly does chmod +x on ALL files). Nose does the
135 # blindly does chmod +x on ALL files). Nose does the
136 # right thing and it tries to avoid executables,
136 # right thing and it tries to avoid executables,
137 # setuptools unfortunately forces our hand here. This
137 # setuptools unfortunately forces our hand here. This
138 # has been discussed on the distutils list and the
138 # has been discussed on the distutils list and the
139 # setuptools devs refuse to fix this problem!
139 # setuptools devs refuse to fix this problem!
140 '--exe',
140 '--exe',
141 ]
141 ]
142
142
143 # Detect if any tests were required by explicitly calling an IPython
143 # Detect if any tests were required by explicitly calling an IPython
144 # submodule or giving a specific path
144 # submodule or giving a specific path
145 has_tests = False
145 has_tests = False
146 for arg in sys.argv:
146 for arg in sys.argv:
147 if 'IPython' in arg or arg.endswith('.py') or \
147 if 'IPython' in arg or arg.endswith('.py') or \
148 (':' in arg and '.py' in arg):
148 (':' in arg and '.py' in arg):
149 has_tests = True
149 has_tests = True
150 break
150 break
151
151
152 # If nothing was specifically requested, test full IPython
152 # If nothing was specifically requested, test full IPython
153 if not has_tests:
153 if not has_tests:
154 argv.append('IPython')
154 argv.append('IPython')
155
155
156 # Construct list of plugins, omitting the existing doctest plugin, which
156 # Construct list of plugins, omitting the existing doctest plugin, which
157 # ours replaces (and extends).
157 # ours replaces (and extends).
158 plugins = [IPythonDoctest(EXCLUDE)]
158 plugins = [IPythonDoctest(EXCLUDE)]
159 for p in nose.plugins.builtin.plugins:
159 for p in nose.plugins.builtin.plugins:
160 plug = p()
160 plug = p()
161 if plug.name == 'doctest':
161 if plug.name == 'doctest':
162 continue
162 continue
163
163
164 #print '*** adding plugin:',plug.name # dbg
164 #print '*** adding plugin:',plug.name # dbg
165 plugins.append(plug)
165 plugins.append(plug)
166
166
167 TestProgram(argv=argv,plugins=plugins)
167 TestProgram(argv=argv,plugins=plugins)
168
168
169
169
170 class IPTester(object):
170 class IPTester(object):
171 """Call that calls iptest or trial in a subprocess.
171 """Call that calls iptest or trial in a subprocess.
172 """
172 """
173 def __init__(self,runner='iptest',params=None):
173 def __init__(self,runner='iptest',params=None):
174 """ """
174 """ """
175 if runner == 'iptest':
175 if runner == 'iptest':
176 self.runner = ['iptest','-v']
176 self.runner = ['iptest','-v']
177 else:
177 else:
178 self.runner = [find_cmd('trial')]
178 self.runner = [find_cmd('trial')]
179 if params is None:
179 if params is None:
180 params = []
180 params = []
181 if isinstance(params,str):
181 if isinstance(params,str):
182 params = [params]
182 params = [params]
183 self.params = params
183 self.params = params
184
184
185 # Assemble call
185 # Assemble call
186 self.call_args = self.runner+self.params
186 self.call_args = self.runner+self.params
187
187
188 def run(self):
188 def run(self):
189 """Run the stored commands"""
189 """Run the stored commands"""
190 return subprocess.call(self.call_args)
190 return subprocess.call(self.call_args)
191
191
192
192
193 def make_runners():
193 def make_runners():
194 """Define the modules and packages that need to be tested.
194 """Define the modules and packages that need to be tested.
195 """
195 """
196
196
197 # This omits additional top-level modules that should not be doctested.
197 # This omits additional top-level modules that should not be doctested.
198 # XXX: Shell.py is also ommited because of a bug in the skip_doctest
198 # XXX: Shell.py is also ommited because of a bug in the skip_doctest
199 # decorator. See ticket https://bugs.launchpad.net/bugs/366209
199 # decorator. See ticket https://bugs.launchpad.net/bugs/366209
200 top_mod = \
200 top_mod = \
201 ['backgroundjobs.py', 'coloransi.py', 'completer.py', 'configloader.py',
201 ['backgroundjobs.py', 'coloransi.py', 'completer.py', 'configloader.py',
202 'crashhandler.py', 'debugger.py', 'deepreload.py', 'demo.py',
202 'crashhandler.py', 'debugger.py', 'deepreload.py', 'demo.py',
203 'DPyGetOpt.py', 'dtutils.py', 'excolors.py', 'fakemodule.py',
203 'DPyGetOpt.py', 'dtutils.py', 'excolors.py', 'fakemodule.py',
204 'generics.py', 'genutils.py', 'history.py', 'hooks.py', 'ipapi.py',
204 'generics.py', 'genutils.py', 'history.py', 'hooks.py', 'ipapi.py',
205 'iplib.py', 'ipmaker.py', 'ipstruct.py', 'Itpl.py',
205 'iplib.py', 'ipmaker.py', 'ipstruct.py', 'Itpl.py',
206 'logger.py', 'macro.py', 'magic.py', 'oinspect.py',
206 'logger.py', 'macro.py', 'magic.py', 'oinspect.py',
207 'outputtrap.py', 'platutils.py', 'prefilter.py', 'Prompts.py',
207 'outputtrap.py', 'platutils.py', 'prefilter.py', 'Prompts.py',
208 'PyColorize.py', 'Release.py', 'rlineimpl.py', 'shadowns.py',
208 'PyColorize.py', 'Release.py', 'rlineimpl.py', 'shadowns.py',
209 'shellglobals.py', 'strdispatch.py', 'twshell.py',
209 'shellglobals.py', 'strdispatch.py', 'twshell.py',
210 'ultraTB.py', 'upgrade_dir.py', 'usage.py', 'wildcard.py',
210 'ultraTB.py', 'upgrade_dir.py', 'usage.py', 'wildcard.py',
211 # See note above for why this is skipped
211 # See note above for why this is skipped
212 # 'Shell.py',
212 # 'Shell.py',
213 'winconsole.py']
213 'winconsole.py']
214
214
215 if have_pexpect:
215 if have_pexpect:
216 top_mod.append('irunner.py')
216 top_mod.append('irunner.py')
217
217
218 if sys.platform == 'win32':
218 if sys.platform == 'win32':
219 top_mod.append('platutils_win32.py')
219 top_mod.append('platutils_win32.py')
220 elif os.name == 'posix':
220 elif os.name == 'posix':
221 top_mod.append('platutils_posix.py')
221 top_mod.append('platutils_posix.py')
222 else:
222 else:
223 top_mod.append('platutils_dummy.py')
223 top_mod.append('platutils_dummy.py')
224
224
225 # These are tested by nose, so skip IPython.kernel
225 # These are tested by nose, so skip IPython.kernel
226 top_pack = ['config','Extensions','frontend',
226 top_pack = ['config','Extensions','frontend',
227 'testing','tests','tools','UserConfig']
227 'testing','tests','tools','UserConfig']
228
228
229 if have_wx:
229 if have_wx:
230 top_pack.append('gui')
230 top_pack.append('gui')
231
231
232 modules = ['IPython.%s' % m[:-3] for m in top_mod ]
232 modules = ['IPython.%s' % m[:-3] for m in top_mod ]
233 packages = ['IPython.%s' % m for m in top_pack ]
233 packages = ['IPython.%s' % m for m in top_pack ]
234
234
235 # Make runners
235 # Make runners
236 runners = dict(zip(top_pack, [IPTester(params=v) for v in packages]))
236 runners = dict(zip(top_pack, [IPTester(params=v) for v in packages]))
237
237
238 # Test IPython.kernel using trial if twisted is installed
238 # Test IPython.kernel using trial if twisted is installed
239 if have_zi and have_twisted and have_foolscap:
239 if have_zi and have_twisted and have_foolscap:
240 runners['trial'] = IPTester('trial',['IPython'])
240 runners['trial'] = IPTester('trial',['IPython'])
241
241
242 runners['modules'] = IPTester(params=modules)
242 runners['modules'] = IPTester(params=modules)
243
243
244 return runners
244 return runners
245
245
246
246
247 def run_iptestall():
247 def run_iptestall():
248 """Run the entire IPython test suite by calling nose and trial.
248 """Run the entire IPython test suite by calling nose and trial.
249
249
250 This function constructs :class:`IPTester` instances for all IPython
250 This function constructs :class:`IPTester` instances for all IPython
251 modules and package and then runs each of them. This causes the modules
251 modules and package and then runs each of them. This causes the modules
252 and packages of IPython to be tested each in their own subprocess using
252 and packages of IPython to be tested each in their own subprocess using
253 nose or twisted.trial appropriately.
253 nose or twisted.trial appropriately.
254 """
254 """
255 runners = make_runners()
255 runners = make_runners()
256 # Run all test runners, tracking execution time
256 # Run all test runners, tracking execution time
257 failed = {}
257 failed = {}
258 t_start = time.time()
258 t_start = time.time()
259 for name,runner in runners.iteritems():
259 for name,runner in runners.iteritems():
260 print '*'*77
260 print '*'*77
261 print 'IPython test set:',name
261 print 'IPython test set:',name
262 res = runner.run()
262 res = runner.run()
263 if res:
263 if res:
264 failed[name] = res
264 failed[name] = res
265 t_end = time.time()
265 t_end = time.time()
266 t_tests = t_end - t_start
266 t_tests = t_end - t_start
267 nrunners = len(runners)
267 nrunners = len(runners)
268 nfail = len(failed)
268 nfail = len(failed)
269 # summarize results
269 # summarize results
270 print
270 print
271 print '*'*77
271 print '*'*77
272 print 'Ran %s test sets in %.3fs' % (nrunners, t_tests)
272 print 'Ran %s test sets in %.3fs' % (nrunners, t_tests)
273 print
273 print
274 if not failed:
274 if not failed:
275 print 'OK'
275 print 'OK'
276 else:
276 else:
277 # If anything went wrong, point out what command to rerun manually to
277 # If anything went wrong, point out what command to rerun manually to
278 # see the actual errors and individual summary
278 # see the actual errors and individual summary
279 print 'ERROR - %s out of %s test sets failed.' % (nfail, nrunners)
279 print 'ERROR - %s out of %s test sets failed.' % (nfail, nrunners)
280 for name in failed:
280 for name in failed:
281 failed_runner = runners[name]
281 failed_runner = runners[name]
282 print '-'*40
282 print '-'*40
283 print 'Runner failed:',name
283 print 'Runner failed:',name
284 print 'You may wish to rerun this one individually, with:'
284 print 'You may wish to rerun this one individually, with:'
285 print ' '.join(failed_runner.call_args)
285 print ' '.join(failed_runner.call_args)
286 print
286 print
287
287
288
288
289 def main():
289 def main():
290 if len(sys.argv) == 1:
290 if len(sys.argv) == 1:
291 run_iptestall()
291 run_iptestall()
292 else:
292 else:
293 if sys.argv[1] == 'all':
293 if sys.argv[1] == 'all':
294 run_iptestall()
294 run_iptestall()
295 else:
295 else:
296 run_iptest()
296 run_iptest()
297
297
298
298
299 if __name__ == '__main__':
299 if __name__ == '__main__':
300 main() No newline at end of file
300 main()
@@ -1,249 +1,249 b''
1 """Tests for various magic functions.
1 """Tests for various magic functions.
2
2
3 Needs to be run by nose (to make ipython session available).
3 Needs to be run by nose (to make ipython session available).
4 """
4 """
5
5
6 import os
6 import os
7 import sys
7 import sys
8 import tempfile
8 import tempfile
9 import types
9 import types
10
10
11 import nose.tools as nt
11 import nose.tools as nt
12
12
13 from IPython.platutils import find_cmd, get_long_path_name
13 from IPython.utils.platutils import find_cmd, get_long_path_name
14 from IPython.testing import decorators as dec
14 from IPython.testing import decorators as dec
15 from IPython.testing import tools as tt
15 from IPython.testing import tools as tt
16
16
17 #-----------------------------------------------------------------------------
17 #-----------------------------------------------------------------------------
18 # Test functions begin
18 # Test functions begin
19
19
20 def test_rehashx():
20 def test_rehashx():
21 # clear up everything
21 # clear up everything
22 _ip.IP.alias_table.clear()
22 _ip.IP.alias_table.clear()
23 del _ip.db['syscmdlist']
23 del _ip.db['syscmdlist']
24
24
25 _ip.magic('rehashx')
25 _ip.magic('rehashx')
26 # Practically ALL ipython development systems will have more than 10 aliases
26 # Practically ALL ipython development systems will have more than 10 aliases
27
27
28 assert len(_ip.IP.alias_table) > 10
28 assert len(_ip.IP.alias_table) > 10
29 for key, val in _ip.IP.alias_table.items():
29 for key, val in _ip.IP.alias_table.items():
30 # we must strip dots from alias names
30 # we must strip dots from alias names
31 assert '.' not in key
31 assert '.' not in key
32
32
33 # rehashx must fill up syscmdlist
33 # rehashx must fill up syscmdlist
34 scoms = _ip.db['syscmdlist']
34 scoms = _ip.db['syscmdlist']
35 assert len(scoms) > 10
35 assert len(scoms) > 10
36
36
37
37
38 def doctest_hist_f():
38 def doctest_hist_f():
39 """Test %hist -f with temporary filename.
39 """Test %hist -f with temporary filename.
40
40
41 In [9]: import tempfile
41 In [9]: import tempfile
42
42
43 In [10]: tfile = tempfile.mktemp('.py','tmp-ipython-')
43 In [10]: tfile = tempfile.mktemp('.py','tmp-ipython-')
44
44
45 In [11]: %history -n -f $tfile 3
45 In [11]: %history -n -f $tfile 3
46 """
46 """
47
47
48
48
49 def doctest_hist_r():
49 def doctest_hist_r():
50 """Test %hist -r
50 """Test %hist -r
51
51
52 XXX - This test is not recording the output correctly. Not sure why...
52 XXX - This test is not recording the output correctly. Not sure why...
53
53
54 In [6]: x=1
54 In [6]: x=1
55
55
56 In [7]: hist -n -r 2
56 In [7]: hist -n -r 2
57 x=1 # random
57 x=1 # random
58 hist -n -r 2 # random
58 hist -n -r 2 # random
59 """
59 """
60
60
61 # This test is known to fail on win32.
61 # This test is known to fail on win32.
62 # See ticket https://bugs.launchpad.net/bugs/366334
62 # See ticket https://bugs.launchpad.net/bugs/366334
63 def test_obj_del():
63 def test_obj_del():
64 """Test that object's __del__ methods are called on exit."""
64 """Test that object's __del__ methods are called on exit."""
65 test_dir = os.path.dirname(__file__)
65 test_dir = os.path.dirname(__file__)
66 del_file = os.path.join(test_dir,'obj_del.py')
66 del_file = os.path.join(test_dir,'obj_del.py')
67 ipython_cmd = find_cmd('ipython')
67 ipython_cmd = find_cmd('ipython')
68 out = _ip.IP.getoutput('%s %s' % (ipython_cmd, del_file))
68 out = _ip.IP.getoutput('%s %s' % (ipython_cmd, del_file))
69 nt.assert_equals(out,'obj_del.py: object A deleted')
69 nt.assert_equals(out,'obj_del.py: object A deleted')
70
70
71
71
72 def test_shist():
72 def test_shist():
73 # Simple tests of ShadowHist class - test generator.
73 # Simple tests of ShadowHist class - test generator.
74 import os, shutil, tempfile
74 import os, shutil, tempfile
75
75
76 from IPython.Extensions import pickleshare
76 from IPython.Extensions import pickleshare
77 from IPython.history import ShadowHist
77 from IPython.history import ShadowHist
78
78
79 tfile = tempfile.mktemp('','tmp-ipython-')
79 tfile = tempfile.mktemp('','tmp-ipython-')
80
80
81 db = pickleshare.PickleShareDB(tfile)
81 db = pickleshare.PickleShareDB(tfile)
82 s = ShadowHist(db)
82 s = ShadowHist(db)
83 s.add('hello')
83 s.add('hello')
84 s.add('world')
84 s.add('world')
85 s.add('hello')
85 s.add('hello')
86 s.add('hello')
86 s.add('hello')
87 s.add('karhu')
87 s.add('karhu')
88
88
89 yield nt.assert_equals,s.all(),[(1, 'hello'), (2, 'world'), (3, 'karhu')]
89 yield nt.assert_equals,s.all(),[(1, 'hello'), (2, 'world'), (3, 'karhu')]
90
90
91 yield nt.assert_equal,s.get(2),'world'
91 yield nt.assert_equal,s.get(2),'world'
92
92
93 shutil.rmtree(tfile)
93 shutil.rmtree(tfile)
94
94
95 @dec.skipif_not_numpy
95 @dec.skipif_not_numpy
96 def test_numpy_clear_array_undec():
96 def test_numpy_clear_array_undec():
97 _ip.ex('import numpy as np')
97 _ip.ex('import numpy as np')
98 _ip.ex('a = np.empty(2)')
98 _ip.ex('a = np.empty(2)')
99
99
100 yield nt.assert_true,'a' in _ip.user_ns
100 yield nt.assert_true,'a' in _ip.user_ns
101 _ip.magic('clear array')
101 _ip.magic('clear array')
102 yield nt.assert_false,'a' in _ip.user_ns
102 yield nt.assert_false,'a' in _ip.user_ns
103
103
104
104
105 @dec.skip()
105 @dec.skip()
106 def test_fail_dec(*a,**k):
106 def test_fail_dec(*a,**k):
107 yield nt.assert_true, False
107 yield nt.assert_true, False
108
108
109 @dec.skip('This one shouldn not run')
109 @dec.skip('This one shouldn not run')
110 def test_fail_dec2(*a,**k):
110 def test_fail_dec2(*a,**k):
111 yield nt.assert_true, False
111 yield nt.assert_true, False
112
112
113 @dec.skipknownfailure
113 @dec.skipknownfailure
114 def test_fail_dec3(*a,**k):
114 def test_fail_dec3(*a,**k):
115 yield nt.assert_true, False
115 yield nt.assert_true, False
116
116
117
117
118 def doctest_refbug():
118 def doctest_refbug():
119 """Very nasty problem with references held by multiple runs of a script.
119 """Very nasty problem with references held by multiple runs of a script.
120 See: https://bugs.launchpad.net/ipython/+bug/269966
120 See: https://bugs.launchpad.net/ipython/+bug/269966
121
121
122 In [1]: _ip.IP.clear_main_mod_cache()
122 In [1]: _ip.IP.clear_main_mod_cache()
123
123
124 In [2]: run refbug
124 In [2]: run refbug
125
125
126 In [3]: call_f()
126 In [3]: call_f()
127 lowercased: hello
127 lowercased: hello
128
128
129 In [4]: run refbug
129 In [4]: run refbug
130
130
131 In [5]: call_f()
131 In [5]: call_f()
132 lowercased: hello
132 lowercased: hello
133 lowercased: hello
133 lowercased: hello
134 """
134 """
135
135
136 #-----------------------------------------------------------------------------
136 #-----------------------------------------------------------------------------
137 # Tests for %run
137 # Tests for %run
138 #-----------------------------------------------------------------------------
138 #-----------------------------------------------------------------------------
139
139
140 # %run is critical enough that it's a good idea to have a solid collection of
140 # %run is critical enough that it's a good idea to have a solid collection of
141 # tests for it, some as doctests and some as normal tests.
141 # tests for it, some as doctests and some as normal tests.
142
142
143 def doctest_run_ns():
143 def doctest_run_ns():
144 """Classes declared %run scripts must be instantiable afterwards.
144 """Classes declared %run scripts must be instantiable afterwards.
145
145
146 In [11]: run tclass foo
146 In [11]: run tclass foo
147
147
148 In [12]: isinstance(f(),foo)
148 In [12]: isinstance(f(),foo)
149 Out[12]: True
149 Out[12]: True
150 """
150 """
151
151
152
152
153 def doctest_run_ns2():
153 def doctest_run_ns2():
154 """Classes declared %run scripts must be instantiable afterwards.
154 """Classes declared %run scripts must be instantiable afterwards.
155
155
156 In [4]: run tclass C-first_pass
156 In [4]: run tclass C-first_pass
157
157
158 In [5]: run tclass C-second_pass
158 In [5]: run tclass C-second_pass
159 tclass.py: deleting object: C-first_pass
159 tclass.py: deleting object: C-first_pass
160 """
160 """
161
161
162 @dec.skip_win32
162 @dec.skip_win32
163 def doctest_run_builtins():
163 def doctest_run_builtins():
164 """Check that %run doesn't damage __builtins__ via a doctest.
164 """Check that %run doesn't damage __builtins__ via a doctest.
165
165
166 This is similar to the test_run_builtins, but I want *both* forms of the
166 This is similar to the test_run_builtins, but I want *both* forms of the
167 test to catch any possible glitches in our testing machinery, since that
167 test to catch any possible glitches in our testing machinery, since that
168 modifies %run somewhat. So for this, we have both a normal test (below)
168 modifies %run somewhat. So for this, we have both a normal test (below)
169 and a doctest (this one).
169 and a doctest (this one).
170
170
171 In [1]: import tempfile
171 In [1]: import tempfile
172
172
173 In [2]: bid1 = id(__builtins__)
173 In [2]: bid1 = id(__builtins__)
174
174
175 In [3]: f = tempfile.NamedTemporaryFile()
175 In [3]: f = tempfile.NamedTemporaryFile()
176
176
177 In [4]: f.write('pass\\n')
177 In [4]: f.write('pass\\n')
178
178
179 In [5]: f.flush()
179 In [5]: f.flush()
180
180
181 In [6]: print 'B1:',type(__builtins__)
181 In [6]: print 'B1:',type(__builtins__)
182 B1: <type 'module'>
182 B1: <type 'module'>
183
183
184 In [7]: %run $f.name
184 In [7]: %run $f.name
185
185
186 In [8]: bid2 = id(__builtins__)
186 In [8]: bid2 = id(__builtins__)
187
187
188 In [9]: print 'B2:',type(__builtins__)
188 In [9]: print 'B2:',type(__builtins__)
189 B2: <type 'module'>
189 B2: <type 'module'>
190
190
191 In [10]: bid1 == bid2
191 In [10]: bid1 == bid2
192 Out[10]: True
192 Out[10]: True
193 """
193 """
194
194
195 # For some tests, it will be handy to organize them in a class with a common
195 # For some tests, it will be handy to organize them in a class with a common
196 # setup that makes a temp file
196 # setup that makes a temp file
197
197
198 class TestMagicRun(object):
198 class TestMagicRun(object):
199
199
200 def setup(self):
200 def setup(self):
201 """Make a valid python temp file."""
201 """Make a valid python temp file."""
202 f = tempfile.NamedTemporaryFile()
202 f = tempfile.NamedTemporaryFile()
203 f.write('pass\n')
203 f.write('pass\n')
204 f.flush()
204 f.flush()
205 self.tmpfile = f
205 self.tmpfile = f
206
206
207 def run_tmpfile(self):
207 def run_tmpfile(self):
208 # This fails on Windows if self.tmpfile.name has spaces or "~" in it.
208 # This fails on Windows if self.tmpfile.name has spaces or "~" in it.
209 # See below and ticket https://bugs.launchpad.net/bugs/366353
209 # See below and ticket https://bugs.launchpad.net/bugs/366353
210 _ip.magic('run %s' % self.tmpfile.name)
210 _ip.magic('run %s' % self.tmpfile.name)
211
211
212 # See https://bugs.launchpad.net/bugs/366353
212 # See https://bugs.launchpad.net/bugs/366353
213 @dec.skip_if_not_win32
213 @dec.skip_if_not_win32
214 def test_run_tempfile_path(self):
214 def test_run_tempfile_path(self):
215 tt.assert_equals(True,False,"%run doesn't work with tempfile paths on win32.")
215 tt.assert_equals(True,False,"%run doesn't work with tempfile paths on win32.")
216
216
217 # See https://bugs.launchpad.net/bugs/366353
217 # See https://bugs.launchpad.net/bugs/366353
218 @dec.skip_win32
218 @dec.skip_win32
219 def test_builtins_id(self):
219 def test_builtins_id(self):
220 """Check that %run doesn't damage __builtins__ """
220 """Check that %run doesn't damage __builtins__ """
221
221
222 # Test that the id of __builtins__ is not modified by %run
222 # Test that the id of __builtins__ is not modified by %run
223 bid1 = id(_ip.user_ns['__builtins__'])
223 bid1 = id(_ip.user_ns['__builtins__'])
224 self.run_tmpfile()
224 self.run_tmpfile()
225 bid2 = id(_ip.user_ns['__builtins__'])
225 bid2 = id(_ip.user_ns['__builtins__'])
226 tt.assert_equals(bid1, bid2)
226 tt.assert_equals(bid1, bid2)
227
227
228 # See https://bugs.launchpad.net/bugs/366353
228 # See https://bugs.launchpad.net/bugs/366353
229 @dec.skip_win32
229 @dec.skip_win32
230 def test_builtins_type(self):
230 def test_builtins_type(self):
231 """Check that the type of __builtins__ doesn't change with %run.
231 """Check that the type of __builtins__ doesn't change with %run.
232
232
233 However, the above could pass if __builtins__ was already modified to
233 However, the above could pass if __builtins__ was already modified to
234 be a dict (it should be a module) by a previous use of %run. So we
234 be a dict (it should be a module) by a previous use of %run. So we
235 also check explicitly that it really is a module:
235 also check explicitly that it really is a module:
236 """
236 """
237 self.run_tmpfile()
237 self.run_tmpfile()
238 tt.assert_equals(type(_ip.user_ns['__builtins__']),type(sys))
238 tt.assert_equals(type(_ip.user_ns['__builtins__']),type(sys))
239
239
240 # See https://bugs.launchpad.net/bugs/366353
240 # See https://bugs.launchpad.net/bugs/366353
241 @dec.skip_win32
241 @dec.skip_win32
242 def test_prompts(self):
242 def test_prompts(self):
243 """Test that prompts correctly generate after %run"""
243 """Test that prompts correctly generate after %run"""
244 self.run_tmpfile()
244 self.run_tmpfile()
245 p2 = str(_ip.IP.outputcache.prompt2).strip()
245 p2 = str(_ip.IP.outputcache.prompt2).strip()
246 nt.assert_equals(p2[:3], '...')
246 nt.assert_equals(p2[:3], '...')
247
247
248 def teardown(self):
248 def teardown(self):
249 self.tmpfile.close()
249 self.tmpfile.close()
@@ -1,2172 +1,2172 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """General purpose utilities.
2 """General purpose utilities.
3
3
4 This is a grab-bag of stuff I find useful in most programs I write. Some of
4 This is a grab-bag of stuff I find useful in most programs I write. Some of
5 these things are also convenient when working at the command line.
5 these things are also convenient when working at the command line.
6 """
6 """
7
7
8 #*****************************************************************************
8 #*****************************************************************************
9 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
9 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
10 #
10 #
11 # Distributed under the terms of the BSD License. The full license is in
11 # Distributed under the terms of the BSD License. The full license is in
12 # the file COPYING, distributed as part of this software.
12 # the file COPYING, distributed as part of this software.
13 #*****************************************************************************
13 #*****************************************************************************
14
14
15 #****************************************************************************
15 #****************************************************************************
16 # required modules from the Python standard library
16 # required modules from the Python standard library
17 import __main__
17 import __main__
18 import commands
18 import commands
19 try:
19 try:
20 import doctest
20 import doctest
21 except ImportError:
21 except ImportError:
22 pass
22 pass
23 import os
23 import os
24 import platform
24 import platform
25 import re
25 import re
26 import shlex
26 import shlex
27 import shutil
27 import shutil
28 import subprocess
28 import subprocess
29 import sys
29 import sys
30 import tempfile
30 import tempfile
31 import time
31 import time
32 import types
32 import types
33 import warnings
33 import warnings
34
34
35 # Curses and termios are Unix-only modules
35 # Curses and termios are Unix-only modules
36 try:
36 try:
37 import curses
37 import curses
38 # We need termios as well, so if its import happens to raise, we bail on
38 # We need termios as well, so if its import happens to raise, we bail on
39 # using curses altogether.
39 # using curses altogether.
40 import termios
40 import termios
41 except ImportError:
41 except ImportError:
42 USE_CURSES = False
42 USE_CURSES = False
43 else:
43 else:
44 # Curses on Solaris may not be complete, so we can't use it there
44 # Curses on Solaris may not be complete, so we can't use it there
45 USE_CURSES = hasattr(curses,'initscr')
45 USE_CURSES = hasattr(curses,'initscr')
46
46
47 # Other IPython utilities
47 # Other IPython utilities
48 import IPython
48 import IPython
49 from IPython.external.Itpl import Itpl,itpl,printpl
49 from IPython.external.Itpl import Itpl,itpl,printpl
50 from IPython import platutils
50 from IPython.utils import platutils
51 from IPython.utils import DPyGetOpt
51 from IPython.utils import DPyGetOpt
52 from IPython.utils.generics import result_display
52 from IPython.utils.generics import result_display
53 from IPython.core import ipapi
53 from IPython.core import ipapi
54 from IPython.external.path import path
54 from IPython.external.path import path
55 if os.name == "nt":
55 if os.name == "nt":
56 from IPython.winconsole import get_console_size
56 from IPython.winconsole import get_console_size
57
57
58 try:
58 try:
59 set
59 set
60 except:
60 except:
61 from sets import Set as set
61 from sets import Set as set
62
62
63
63
64 #****************************************************************************
64 #****************************************************************************
65 # Exceptions
65 # Exceptions
66 class Error(Exception):
66 class Error(Exception):
67 """Base class for exceptions in this module."""
67 """Base class for exceptions in this module."""
68 pass
68 pass
69
69
70 #----------------------------------------------------------------------------
70 #----------------------------------------------------------------------------
71 class IOStream:
71 class IOStream:
72 def __init__(self,stream,fallback):
72 def __init__(self,stream,fallback):
73 if not hasattr(stream,'write') or not hasattr(stream,'flush'):
73 if not hasattr(stream,'write') or not hasattr(stream,'flush'):
74 stream = fallback
74 stream = fallback
75 self.stream = stream
75 self.stream = stream
76 self._swrite = stream.write
76 self._swrite = stream.write
77 self.flush = stream.flush
77 self.flush = stream.flush
78
78
79 def write(self,data):
79 def write(self,data):
80 try:
80 try:
81 self._swrite(data)
81 self._swrite(data)
82 except:
82 except:
83 try:
83 try:
84 # print handles some unicode issues which may trip a plain
84 # print handles some unicode issues which may trip a plain
85 # write() call. Attempt to emulate write() by using a
85 # write() call. Attempt to emulate write() by using a
86 # trailing comma
86 # trailing comma
87 print >> self.stream, data,
87 print >> self.stream, data,
88 except:
88 except:
89 # if we get here, something is seriously broken.
89 # if we get here, something is seriously broken.
90 print >> sys.stderr, \
90 print >> sys.stderr, \
91 'ERROR - failed to write data to stream:', self.stream
91 'ERROR - failed to write data to stream:', self.stream
92
92
93 def close(self):
93 def close(self):
94 pass
94 pass
95
95
96
96
97 class IOTerm:
97 class IOTerm:
98 """ Term holds the file or file-like objects for handling I/O operations.
98 """ Term holds the file or file-like objects for handling I/O operations.
99
99
100 These are normally just sys.stdin, sys.stdout and sys.stderr but for
100 These are normally just sys.stdin, sys.stdout and sys.stderr but for
101 Windows they can can replaced to allow editing the strings before they are
101 Windows they can can replaced to allow editing the strings before they are
102 displayed."""
102 displayed."""
103
103
104 # In the future, having IPython channel all its I/O operations through
104 # In the future, having IPython channel all its I/O operations through
105 # this class will make it easier to embed it into other environments which
105 # this class will make it easier to embed it into other environments which
106 # are not a normal terminal (such as a GUI-based shell)
106 # are not a normal terminal (such as a GUI-based shell)
107 def __init__(self,cin=None,cout=None,cerr=None):
107 def __init__(self,cin=None,cout=None,cerr=None):
108 self.cin = IOStream(cin,sys.stdin)
108 self.cin = IOStream(cin,sys.stdin)
109 self.cout = IOStream(cout,sys.stdout)
109 self.cout = IOStream(cout,sys.stdout)
110 self.cerr = IOStream(cerr,sys.stderr)
110 self.cerr = IOStream(cerr,sys.stderr)
111
111
112 # Global variable to be used for all I/O
112 # Global variable to be used for all I/O
113 Term = IOTerm()
113 Term = IOTerm()
114
114
115 import IPython.rlineimpl as readline
115 import IPython.rlineimpl as readline
116 # Remake Term to use the readline i/o facilities
116 # Remake Term to use the readline i/o facilities
117 if sys.platform == 'win32' and readline.have_readline:
117 if sys.platform == 'win32' and readline.have_readline:
118
118
119 Term = IOTerm(cout=readline._outputfile,cerr=readline._outputfile)
119 Term = IOTerm(cout=readline._outputfile,cerr=readline._outputfile)
120
120
121
121
122 #****************************************************************************
122 #****************************************************************************
123 # Generic warning/error printer, used by everything else
123 # Generic warning/error printer, used by everything else
124 def warn(msg,level=2,exit_val=1):
124 def warn(msg,level=2,exit_val=1):
125 """Standard warning printer. Gives formatting consistency.
125 """Standard warning printer. Gives formatting consistency.
126
126
127 Output is sent to Term.cerr (sys.stderr by default).
127 Output is sent to Term.cerr (sys.stderr by default).
128
128
129 Options:
129 Options:
130
130
131 -level(2): allows finer control:
131 -level(2): allows finer control:
132 0 -> Do nothing, dummy function.
132 0 -> Do nothing, dummy function.
133 1 -> Print message.
133 1 -> Print message.
134 2 -> Print 'WARNING:' + message. (Default level).
134 2 -> Print 'WARNING:' + message. (Default level).
135 3 -> Print 'ERROR:' + message.
135 3 -> Print 'ERROR:' + message.
136 4 -> Print 'FATAL ERROR:' + message and trigger a sys.exit(exit_val).
136 4 -> Print 'FATAL ERROR:' + message and trigger a sys.exit(exit_val).
137
137
138 -exit_val (1): exit value returned by sys.exit() for a level 4
138 -exit_val (1): exit value returned by sys.exit() for a level 4
139 warning. Ignored for all other levels."""
139 warning. Ignored for all other levels."""
140
140
141 if level>0:
141 if level>0:
142 header = ['','','WARNING: ','ERROR: ','FATAL ERROR: ']
142 header = ['','','WARNING: ','ERROR: ','FATAL ERROR: ']
143 print >> Term.cerr, '%s%s' % (header[level],msg)
143 print >> Term.cerr, '%s%s' % (header[level],msg)
144 if level == 4:
144 if level == 4:
145 print >> Term.cerr,'Exiting.\n'
145 print >> Term.cerr,'Exiting.\n'
146 sys.exit(exit_val)
146 sys.exit(exit_val)
147
147
148 def info(msg):
148 def info(msg):
149 """Equivalent to warn(msg,level=1)."""
149 """Equivalent to warn(msg,level=1)."""
150
150
151 warn(msg,level=1)
151 warn(msg,level=1)
152
152
153 def error(msg):
153 def error(msg):
154 """Equivalent to warn(msg,level=3)."""
154 """Equivalent to warn(msg,level=3)."""
155
155
156 warn(msg,level=3)
156 warn(msg,level=3)
157
157
158 def fatal(msg,exit_val=1):
158 def fatal(msg,exit_val=1):
159 """Equivalent to warn(msg,exit_val=exit_val,level=4)."""
159 """Equivalent to warn(msg,exit_val=exit_val,level=4)."""
160
160
161 warn(msg,exit_val=exit_val,level=4)
161 warn(msg,exit_val=exit_val,level=4)
162
162
163 #---------------------------------------------------------------------------
163 #---------------------------------------------------------------------------
164 # Debugging routines
164 # Debugging routines
165 #
165 #
166 def debugx(expr,pre_msg=''):
166 def debugx(expr,pre_msg=''):
167 """Print the value of an expression from the caller's frame.
167 """Print the value of an expression from the caller's frame.
168
168
169 Takes an expression, evaluates it in the caller's frame and prints both
169 Takes an expression, evaluates it in the caller's frame and prints both
170 the given expression and the resulting value (as well as a debug mark
170 the given expression and the resulting value (as well as a debug mark
171 indicating the name of the calling function. The input must be of a form
171 indicating the name of the calling function. The input must be of a form
172 suitable for eval().
172 suitable for eval().
173
173
174 An optional message can be passed, which will be prepended to the printed
174 An optional message can be passed, which will be prepended to the printed
175 expr->value pair."""
175 expr->value pair."""
176
176
177 cf = sys._getframe(1)
177 cf = sys._getframe(1)
178 print '[DBG:%s] %s%s -> %r' % (cf.f_code.co_name,pre_msg,expr,
178 print '[DBG:%s] %s%s -> %r' % (cf.f_code.co_name,pre_msg,expr,
179 eval(expr,cf.f_globals,cf.f_locals))
179 eval(expr,cf.f_globals,cf.f_locals))
180
180
181 # deactivate it by uncommenting the following line, which makes it a no-op
181 # deactivate it by uncommenting the following line, which makes it a no-op
182 #def debugx(expr,pre_msg=''): pass
182 #def debugx(expr,pre_msg=''): pass
183
183
184 #----------------------------------------------------------------------------
184 #----------------------------------------------------------------------------
185 StringTypes = types.StringTypes
185 StringTypes = types.StringTypes
186
186
187 # Basic timing functionality
187 # Basic timing functionality
188
188
189 # If possible (Unix), use the resource module instead of time.clock()
189 # If possible (Unix), use the resource module instead of time.clock()
190 try:
190 try:
191 import resource
191 import resource
192 def clocku():
192 def clocku():
193 """clocku() -> floating point number
193 """clocku() -> floating point number
194
194
195 Return the *USER* CPU time in seconds since the start of the process.
195 Return the *USER* CPU time in seconds since the start of the process.
196 This is done via a call to resource.getrusage, so it avoids the
196 This is done via a call to resource.getrusage, so it avoids the
197 wraparound problems in time.clock()."""
197 wraparound problems in time.clock()."""
198
198
199 return resource.getrusage(resource.RUSAGE_SELF)[0]
199 return resource.getrusage(resource.RUSAGE_SELF)[0]
200
200
201 def clocks():
201 def clocks():
202 """clocks() -> floating point number
202 """clocks() -> floating point number
203
203
204 Return the *SYSTEM* CPU time in seconds since the start of the process.
204 Return the *SYSTEM* CPU time in seconds since the start of the process.
205 This is done via a call to resource.getrusage, so it avoids the
205 This is done via a call to resource.getrusage, so it avoids the
206 wraparound problems in time.clock()."""
206 wraparound problems in time.clock()."""
207
207
208 return resource.getrusage(resource.RUSAGE_SELF)[1]
208 return resource.getrusage(resource.RUSAGE_SELF)[1]
209
209
210 def clock():
210 def clock():
211 """clock() -> floating point number
211 """clock() -> floating point number
212
212
213 Return the *TOTAL USER+SYSTEM* CPU time in seconds since the start of
213 Return the *TOTAL USER+SYSTEM* CPU time in seconds since the start of
214 the process. This is done via a call to resource.getrusage, so it
214 the process. This is done via a call to resource.getrusage, so it
215 avoids the wraparound problems in time.clock()."""
215 avoids the wraparound problems in time.clock()."""
216
216
217 u,s = resource.getrusage(resource.RUSAGE_SELF)[:2]
217 u,s = resource.getrusage(resource.RUSAGE_SELF)[:2]
218 return u+s
218 return u+s
219
219
220 def clock2():
220 def clock2():
221 """clock2() -> (t_user,t_system)
221 """clock2() -> (t_user,t_system)
222
222
223 Similar to clock(), but return a tuple of user/system times."""
223 Similar to clock(), but return a tuple of user/system times."""
224 return resource.getrusage(resource.RUSAGE_SELF)[:2]
224 return resource.getrusage(resource.RUSAGE_SELF)[:2]
225
225
226 except ImportError:
226 except ImportError:
227 # There is no distinction of user/system time under windows, so we just use
227 # There is no distinction of user/system time under windows, so we just use
228 # time.clock() for everything...
228 # time.clock() for everything...
229 clocku = clocks = clock = time.clock
229 clocku = clocks = clock = time.clock
230 def clock2():
230 def clock2():
231 """Under windows, system CPU time can't be measured.
231 """Under windows, system CPU time can't be measured.
232
232
233 This just returns clock() and zero."""
233 This just returns clock() and zero."""
234 return time.clock(),0.0
234 return time.clock(),0.0
235
235
236 def timings_out(reps,func,*args,**kw):
236 def timings_out(reps,func,*args,**kw):
237 """timings_out(reps,func,*args,**kw) -> (t_total,t_per_call,output)
237 """timings_out(reps,func,*args,**kw) -> (t_total,t_per_call,output)
238
238
239 Execute a function reps times, return a tuple with the elapsed total
239 Execute a function reps times, return a tuple with the elapsed total
240 CPU time in seconds, the time per call and the function's output.
240 CPU time in seconds, the time per call and the function's output.
241
241
242 Under Unix, the return value is the sum of user+system time consumed by
242 Under Unix, the return value is the sum of user+system time consumed by
243 the process, computed via the resource module. This prevents problems
243 the process, computed via the resource module. This prevents problems
244 related to the wraparound effect which the time.clock() function has.
244 related to the wraparound effect which the time.clock() function has.
245
245
246 Under Windows the return value is in wall clock seconds. See the
246 Under Windows the return value is in wall clock seconds. See the
247 documentation for the time module for more details."""
247 documentation for the time module for more details."""
248
248
249 reps = int(reps)
249 reps = int(reps)
250 assert reps >=1, 'reps must be >= 1'
250 assert reps >=1, 'reps must be >= 1'
251 if reps==1:
251 if reps==1:
252 start = clock()
252 start = clock()
253 out = func(*args,**kw)
253 out = func(*args,**kw)
254 tot_time = clock()-start
254 tot_time = clock()-start
255 else:
255 else:
256 rng = xrange(reps-1) # the last time is executed separately to store output
256 rng = xrange(reps-1) # the last time is executed separately to store output
257 start = clock()
257 start = clock()
258 for dummy in rng: func(*args,**kw)
258 for dummy in rng: func(*args,**kw)
259 out = func(*args,**kw) # one last time
259 out = func(*args,**kw) # one last time
260 tot_time = clock()-start
260 tot_time = clock()-start
261 av_time = tot_time / reps
261 av_time = tot_time / reps
262 return tot_time,av_time,out
262 return tot_time,av_time,out
263
263
264 def timings(reps,func,*args,**kw):
264 def timings(reps,func,*args,**kw):
265 """timings(reps,func,*args,**kw) -> (t_total,t_per_call)
265 """timings(reps,func,*args,**kw) -> (t_total,t_per_call)
266
266
267 Execute a function reps times, return a tuple with the elapsed total CPU
267 Execute a function reps times, return a tuple with the elapsed total CPU
268 time in seconds and the time per call. These are just the first two values
268 time in seconds and the time per call. These are just the first two values
269 in timings_out()."""
269 in timings_out()."""
270
270
271 return timings_out(reps,func,*args,**kw)[0:2]
271 return timings_out(reps,func,*args,**kw)[0:2]
272
272
273 def timing(func,*args,**kw):
273 def timing(func,*args,**kw):
274 """timing(func,*args,**kw) -> t_total
274 """timing(func,*args,**kw) -> t_total
275
275
276 Execute a function once, return the elapsed total CPU time in
276 Execute a function once, return the elapsed total CPU time in
277 seconds. This is just the first value in timings_out()."""
277 seconds. This is just the first value in timings_out()."""
278
278
279 return timings_out(1,func,*args,**kw)[0]
279 return timings_out(1,func,*args,**kw)[0]
280
280
281 #****************************************************************************
281 #****************************************************************************
282 # file and system
282 # file and system
283
283
284 def arg_split(s,posix=False):
284 def arg_split(s,posix=False):
285 """Split a command line's arguments in a shell-like manner.
285 """Split a command line's arguments in a shell-like manner.
286
286
287 This is a modified version of the standard library's shlex.split()
287 This is a modified version of the standard library's shlex.split()
288 function, but with a default of posix=False for splitting, so that quotes
288 function, but with a default of posix=False for splitting, so that quotes
289 in inputs are respected."""
289 in inputs are respected."""
290
290
291 # XXX - there may be unicode-related problems here!!! I'm not sure that
291 # XXX - there may be unicode-related problems here!!! I'm not sure that
292 # shlex is truly unicode-safe, so it might be necessary to do
292 # shlex is truly unicode-safe, so it might be necessary to do
293 #
293 #
294 # s = s.encode(sys.stdin.encoding)
294 # s = s.encode(sys.stdin.encoding)
295 #
295 #
296 # first, to ensure that shlex gets a normal string. Input from anyone who
296 # first, to ensure that shlex gets a normal string. Input from anyone who
297 # knows more about unicode and shlex than I would be good to have here...
297 # knows more about unicode and shlex than I would be good to have here...
298 lex = shlex.shlex(s, posix=posix)
298 lex = shlex.shlex(s, posix=posix)
299 lex.whitespace_split = True
299 lex.whitespace_split = True
300 return list(lex)
300 return list(lex)
301
301
302 def system(cmd,verbose=0,debug=0,header=''):
302 def system(cmd,verbose=0,debug=0,header=''):
303 """Execute a system command, return its exit status.
303 """Execute a system command, return its exit status.
304
304
305 Options:
305 Options:
306
306
307 - verbose (0): print the command to be executed.
307 - verbose (0): print the command to be executed.
308
308
309 - debug (0): only print, do not actually execute.
309 - debug (0): only print, do not actually execute.
310
310
311 - header (''): Header to print on screen prior to the executed command (it
311 - header (''): Header to print on screen prior to the executed command (it
312 is only prepended to the command, no newlines are added).
312 is only prepended to the command, no newlines are added).
313
313
314 Note: a stateful version of this function is available through the
314 Note: a stateful version of this function is available through the
315 SystemExec class."""
315 SystemExec class."""
316
316
317 stat = 0
317 stat = 0
318 if verbose or debug: print header+cmd
318 if verbose or debug: print header+cmd
319 sys.stdout.flush()
319 sys.stdout.flush()
320 if not debug: stat = os.system(cmd)
320 if not debug: stat = os.system(cmd)
321 return stat
321 return stat
322
322
323 def abbrev_cwd():
323 def abbrev_cwd():
324 """ Return abbreviated version of cwd, e.g. d:mydir """
324 """ Return abbreviated version of cwd, e.g. d:mydir """
325 cwd = os.getcwd().replace('\\','/')
325 cwd = os.getcwd().replace('\\','/')
326 drivepart = ''
326 drivepart = ''
327 tail = cwd
327 tail = cwd
328 if sys.platform == 'win32':
328 if sys.platform == 'win32':
329 if len(cwd) < 4:
329 if len(cwd) < 4:
330 return cwd
330 return cwd
331 drivepart,tail = os.path.splitdrive(cwd)
331 drivepart,tail = os.path.splitdrive(cwd)
332
332
333
333
334 parts = tail.split('/')
334 parts = tail.split('/')
335 if len(parts) > 2:
335 if len(parts) > 2:
336 tail = '/'.join(parts[-2:])
336 tail = '/'.join(parts[-2:])
337
337
338 return (drivepart + (
338 return (drivepart + (
339 cwd == '/' and '/' or tail))
339 cwd == '/' and '/' or tail))
340
340
341
341
342 # This function is used by ipython in a lot of places to make system calls.
342 # This function is used by ipython in a lot of places to make system calls.
343 # We need it to be slightly different under win32, due to the vagaries of
343 # We need it to be slightly different under win32, due to the vagaries of
344 # 'network shares'. A win32 override is below.
344 # 'network shares'. A win32 override is below.
345
345
346 def shell(cmd,verbose=0,debug=0,header=''):
346 def shell(cmd,verbose=0,debug=0,header=''):
347 """Execute a command in the system shell, always return None.
347 """Execute a command in the system shell, always return None.
348
348
349 Options:
349 Options:
350
350
351 - verbose (0): print the command to be executed.
351 - verbose (0): print the command to be executed.
352
352
353 - debug (0): only print, do not actually execute.
353 - debug (0): only print, do not actually execute.
354
354
355 - header (''): Header to print on screen prior to the executed command (it
355 - header (''): Header to print on screen prior to the executed command (it
356 is only prepended to the command, no newlines are added).
356 is only prepended to the command, no newlines are added).
357
357
358 Note: this is similar to genutils.system(), but it returns None so it can
358 Note: this is similar to genutils.system(), but it returns None so it can
359 be conveniently used in interactive loops without getting the return value
359 be conveniently used in interactive loops without getting the return value
360 (typically 0) printed many times."""
360 (typically 0) printed many times."""
361
361
362 stat = 0
362 stat = 0
363 if verbose or debug: print header+cmd
363 if verbose or debug: print header+cmd
364 # flush stdout so we don't mangle python's buffering
364 # flush stdout so we don't mangle python's buffering
365 sys.stdout.flush()
365 sys.stdout.flush()
366
366
367 if not debug:
367 if not debug:
368 platutils.set_term_title("IPy " + cmd)
368 platutils.set_term_title("IPy " + cmd)
369 os.system(cmd)
369 os.system(cmd)
370 platutils.set_term_title("IPy " + abbrev_cwd())
370 platutils.set_term_title("IPy " + abbrev_cwd())
371
371
372 # override shell() for win32 to deal with network shares
372 # override shell() for win32 to deal with network shares
373 if os.name in ('nt','dos'):
373 if os.name in ('nt','dos'):
374
374
375 shell_ori = shell
375 shell_ori = shell
376
376
377 def shell(cmd,verbose=0,debug=0,header=''):
377 def shell(cmd,verbose=0,debug=0,header=''):
378 if os.getcwd().startswith(r"\\"):
378 if os.getcwd().startswith(r"\\"):
379 path = os.getcwd()
379 path = os.getcwd()
380 # change to c drive (cannot be on UNC-share when issuing os.system,
380 # change to c drive (cannot be on UNC-share when issuing os.system,
381 # as cmd.exe cannot handle UNC addresses)
381 # as cmd.exe cannot handle UNC addresses)
382 os.chdir("c:")
382 os.chdir("c:")
383 # issue pushd to the UNC-share and then run the command
383 # issue pushd to the UNC-share and then run the command
384 try:
384 try:
385 shell_ori('"pushd %s&&"'%path+cmd,verbose,debug,header)
385 shell_ori('"pushd %s&&"'%path+cmd,verbose,debug,header)
386 finally:
386 finally:
387 os.chdir(path)
387 os.chdir(path)
388 else:
388 else:
389 shell_ori(cmd,verbose,debug,header)
389 shell_ori(cmd,verbose,debug,header)
390
390
391 shell.__doc__ = shell_ori.__doc__
391 shell.__doc__ = shell_ori.__doc__
392
392
393 def getoutput(cmd,verbose=0,debug=0,header='',split=0):
393 def getoutput(cmd,verbose=0,debug=0,header='',split=0):
394 """Dummy substitute for perl's backquotes.
394 """Dummy substitute for perl's backquotes.
395
395
396 Executes a command and returns the output.
396 Executes a command and returns the output.
397
397
398 Accepts the same arguments as system(), plus:
398 Accepts the same arguments as system(), plus:
399
399
400 - split(0): if true, the output is returned as a list split on newlines.
400 - split(0): if true, the output is returned as a list split on newlines.
401
401
402 Note: a stateful version of this function is available through the
402 Note: a stateful version of this function is available through the
403 SystemExec class.
403 SystemExec class.
404
404
405 This is pretty much deprecated and rarely used,
405 This is pretty much deprecated and rarely used,
406 genutils.getoutputerror may be what you need.
406 genutils.getoutputerror may be what you need.
407
407
408 """
408 """
409
409
410 if verbose or debug: print header+cmd
410 if verbose or debug: print header+cmd
411 if not debug:
411 if not debug:
412 output = os.popen(cmd).read()
412 output = os.popen(cmd).read()
413 # stipping last \n is here for backwards compat.
413 # stipping last \n is here for backwards compat.
414 if output.endswith('\n'):
414 if output.endswith('\n'):
415 output = output[:-1]
415 output = output[:-1]
416 if split:
416 if split:
417 return output.split('\n')
417 return output.split('\n')
418 else:
418 else:
419 return output
419 return output
420
420
421 def getoutputerror(cmd,verbose=0,debug=0,header='',split=0):
421 def getoutputerror(cmd,verbose=0,debug=0,header='',split=0):
422 """Return (standard output,standard error) of executing cmd in a shell.
422 """Return (standard output,standard error) of executing cmd in a shell.
423
423
424 Accepts the same arguments as system(), plus:
424 Accepts the same arguments as system(), plus:
425
425
426 - split(0): if true, each of stdout/err is returned as a list split on
426 - split(0): if true, each of stdout/err is returned as a list split on
427 newlines.
427 newlines.
428
428
429 Note: a stateful version of this function is available through the
429 Note: a stateful version of this function is available through the
430 SystemExec class."""
430 SystemExec class."""
431
431
432 if verbose or debug: print header+cmd
432 if verbose or debug: print header+cmd
433 if not cmd:
433 if not cmd:
434 if split:
434 if split:
435 return [],[]
435 return [],[]
436 else:
436 else:
437 return '',''
437 return '',''
438 if not debug:
438 if not debug:
439 pin,pout,perr = os.popen3(cmd)
439 pin,pout,perr = os.popen3(cmd)
440 tout = pout.read().rstrip()
440 tout = pout.read().rstrip()
441 terr = perr.read().rstrip()
441 terr = perr.read().rstrip()
442 pin.close()
442 pin.close()
443 pout.close()
443 pout.close()
444 perr.close()
444 perr.close()
445 if split:
445 if split:
446 return tout.split('\n'),terr.split('\n')
446 return tout.split('\n'),terr.split('\n')
447 else:
447 else:
448 return tout,terr
448 return tout,terr
449
449
450 # for compatibility with older naming conventions
450 # for compatibility with older naming conventions
451 xsys = system
451 xsys = system
452 bq = getoutput
452 bq = getoutput
453
453
454 class SystemExec:
454 class SystemExec:
455 """Access the system and getoutput functions through a stateful interface.
455 """Access the system and getoutput functions through a stateful interface.
456
456
457 Note: here we refer to the system and getoutput functions from this
457 Note: here we refer to the system and getoutput functions from this
458 library, not the ones from the standard python library.
458 library, not the ones from the standard python library.
459
459
460 This class offers the system and getoutput functions as methods, but the
460 This class offers the system and getoutput functions as methods, but the
461 verbose, debug and header parameters can be set for the instance (at
461 verbose, debug and header parameters can be set for the instance (at
462 creation time or later) so that they don't need to be specified on each
462 creation time or later) so that they don't need to be specified on each
463 call.
463 call.
464
464
465 For efficiency reasons, there's no way to override the parameters on a
465 For efficiency reasons, there's no way to override the parameters on a
466 per-call basis other than by setting instance attributes. If you need
466 per-call basis other than by setting instance attributes. If you need
467 local overrides, it's best to directly call system() or getoutput().
467 local overrides, it's best to directly call system() or getoutput().
468
468
469 The following names are provided as alternate options:
469 The following names are provided as alternate options:
470 - xsys: alias to system
470 - xsys: alias to system
471 - bq: alias to getoutput
471 - bq: alias to getoutput
472
472
473 An instance can then be created as:
473 An instance can then be created as:
474 >>> sysexec = SystemExec(verbose=1,debug=0,header='Calling: ')
474 >>> sysexec = SystemExec(verbose=1,debug=0,header='Calling: ')
475 """
475 """
476
476
477 def __init__(self,verbose=0,debug=0,header='',split=0):
477 def __init__(self,verbose=0,debug=0,header='',split=0):
478 """Specify the instance's values for verbose, debug and header."""
478 """Specify the instance's values for verbose, debug and header."""
479 setattr_list(self,'verbose debug header split')
479 setattr_list(self,'verbose debug header split')
480
480
481 def system(self,cmd):
481 def system(self,cmd):
482 """Stateful interface to system(), with the same keyword parameters."""
482 """Stateful interface to system(), with the same keyword parameters."""
483
483
484 system(cmd,self.verbose,self.debug,self.header)
484 system(cmd,self.verbose,self.debug,self.header)
485
485
486 def shell(self,cmd):
486 def shell(self,cmd):
487 """Stateful interface to shell(), with the same keyword parameters."""
487 """Stateful interface to shell(), with the same keyword parameters."""
488
488
489 shell(cmd,self.verbose,self.debug,self.header)
489 shell(cmd,self.verbose,self.debug,self.header)
490
490
491 xsys = system # alias
491 xsys = system # alias
492
492
493 def getoutput(self,cmd):
493 def getoutput(self,cmd):
494 """Stateful interface to getoutput()."""
494 """Stateful interface to getoutput()."""
495
495
496 return getoutput(cmd,self.verbose,self.debug,self.header,self.split)
496 return getoutput(cmd,self.verbose,self.debug,self.header,self.split)
497
497
498 def getoutputerror(self,cmd):
498 def getoutputerror(self,cmd):
499 """Stateful interface to getoutputerror()."""
499 """Stateful interface to getoutputerror()."""
500
500
501 return getoutputerror(cmd,self.verbose,self.debug,self.header,self.split)
501 return getoutputerror(cmd,self.verbose,self.debug,self.header,self.split)
502
502
503 bq = getoutput # alias
503 bq = getoutput # alias
504
504
505 #-----------------------------------------------------------------------------
505 #-----------------------------------------------------------------------------
506 def mutex_opts(dict,ex_op):
506 def mutex_opts(dict,ex_op):
507 """Check for presence of mutually exclusive keys in a dict.
507 """Check for presence of mutually exclusive keys in a dict.
508
508
509 Call: mutex_opts(dict,[[op1a,op1b],[op2a,op2b]...]"""
509 Call: mutex_opts(dict,[[op1a,op1b],[op2a,op2b]...]"""
510 for op1,op2 in ex_op:
510 for op1,op2 in ex_op:
511 if op1 in dict and op2 in dict:
511 if op1 in dict and op2 in dict:
512 raise ValueError,'\n*** ERROR in Arguments *** '\
512 raise ValueError,'\n*** ERROR in Arguments *** '\
513 'Options '+op1+' and '+op2+' are mutually exclusive.'
513 'Options '+op1+' and '+op2+' are mutually exclusive.'
514
514
515 #-----------------------------------------------------------------------------
515 #-----------------------------------------------------------------------------
516 def get_py_filename(name):
516 def get_py_filename(name):
517 """Return a valid python filename in the current directory.
517 """Return a valid python filename in the current directory.
518
518
519 If the given name is not a file, it adds '.py' and searches again.
519 If the given name is not a file, it adds '.py' and searches again.
520 Raises IOError with an informative message if the file isn't found."""
520 Raises IOError with an informative message if the file isn't found."""
521
521
522 name = os.path.expanduser(name)
522 name = os.path.expanduser(name)
523 if not os.path.isfile(name) and not name.endswith('.py'):
523 if not os.path.isfile(name) and not name.endswith('.py'):
524 name += '.py'
524 name += '.py'
525 if os.path.isfile(name):
525 if os.path.isfile(name):
526 return name
526 return name
527 else:
527 else:
528 raise IOError,'File `%s` not found.' % name
528 raise IOError,'File `%s` not found.' % name
529
529
530 #-----------------------------------------------------------------------------
530 #-----------------------------------------------------------------------------
531 def filefind(fname,alt_dirs = None):
531 def filefind(fname,alt_dirs = None):
532 """Return the given filename either in the current directory, if it
532 """Return the given filename either in the current directory, if it
533 exists, or in a specified list of directories.
533 exists, or in a specified list of directories.
534
534
535 ~ expansion is done on all file and directory names.
535 ~ expansion is done on all file and directory names.
536
536
537 Upon an unsuccessful search, raise an IOError exception."""
537 Upon an unsuccessful search, raise an IOError exception."""
538
538
539 if alt_dirs is None:
539 if alt_dirs is None:
540 try:
540 try:
541 alt_dirs = get_home_dir()
541 alt_dirs = get_home_dir()
542 except HomeDirError:
542 except HomeDirError:
543 alt_dirs = os.getcwd()
543 alt_dirs = os.getcwd()
544 search = [fname] + list_strings(alt_dirs)
544 search = [fname] + list_strings(alt_dirs)
545 search = map(os.path.expanduser,search)
545 search = map(os.path.expanduser,search)
546 #print 'search list for',fname,'list:',search # dbg
546 #print 'search list for',fname,'list:',search # dbg
547 fname = search[0]
547 fname = search[0]
548 if os.path.isfile(fname):
548 if os.path.isfile(fname):
549 return fname
549 return fname
550 for direc in search[1:]:
550 for direc in search[1:]:
551 testname = os.path.join(direc,fname)
551 testname = os.path.join(direc,fname)
552 #print 'testname',testname # dbg
552 #print 'testname',testname # dbg
553 if os.path.isfile(testname):
553 if os.path.isfile(testname):
554 return testname
554 return testname
555 raise IOError,'File' + `fname` + \
555 raise IOError,'File' + `fname` + \
556 ' not found in current or supplied directories:' + `alt_dirs`
556 ' not found in current or supplied directories:' + `alt_dirs`
557
557
558 #----------------------------------------------------------------------------
558 #----------------------------------------------------------------------------
559 def file_read(filename):
559 def file_read(filename):
560 """Read a file and close it. Returns the file source."""
560 """Read a file and close it. Returns the file source."""
561 fobj = open(filename,'r');
561 fobj = open(filename,'r');
562 source = fobj.read();
562 source = fobj.read();
563 fobj.close()
563 fobj.close()
564 return source
564 return source
565
565
566 def file_readlines(filename):
566 def file_readlines(filename):
567 """Read a file and close it. Returns the file source using readlines()."""
567 """Read a file and close it. Returns the file source using readlines()."""
568 fobj = open(filename,'r');
568 fobj = open(filename,'r');
569 lines = fobj.readlines();
569 lines = fobj.readlines();
570 fobj.close()
570 fobj.close()
571 return lines
571 return lines
572
572
573 #----------------------------------------------------------------------------
573 #----------------------------------------------------------------------------
574 def target_outdated(target,deps):
574 def target_outdated(target,deps):
575 """Determine whether a target is out of date.
575 """Determine whether a target is out of date.
576
576
577 target_outdated(target,deps) -> 1/0
577 target_outdated(target,deps) -> 1/0
578
578
579 deps: list of filenames which MUST exist.
579 deps: list of filenames which MUST exist.
580 target: single filename which may or may not exist.
580 target: single filename which may or may not exist.
581
581
582 If target doesn't exist or is older than any file listed in deps, return
582 If target doesn't exist or is older than any file listed in deps, return
583 true, otherwise return false.
583 true, otherwise return false.
584 """
584 """
585 try:
585 try:
586 target_time = os.path.getmtime(target)
586 target_time = os.path.getmtime(target)
587 except os.error:
587 except os.error:
588 return 1
588 return 1
589 for dep in deps:
589 for dep in deps:
590 dep_time = os.path.getmtime(dep)
590 dep_time = os.path.getmtime(dep)
591 if dep_time > target_time:
591 if dep_time > target_time:
592 #print "For target",target,"Dep failed:",dep # dbg
592 #print "For target",target,"Dep failed:",dep # dbg
593 #print "times (dep,tar):",dep_time,target_time # dbg
593 #print "times (dep,tar):",dep_time,target_time # dbg
594 return 1
594 return 1
595 return 0
595 return 0
596
596
597 #-----------------------------------------------------------------------------
597 #-----------------------------------------------------------------------------
598 def target_update(target,deps,cmd):
598 def target_update(target,deps,cmd):
599 """Update a target with a given command given a list of dependencies.
599 """Update a target with a given command given a list of dependencies.
600
600
601 target_update(target,deps,cmd) -> runs cmd if target is outdated.
601 target_update(target,deps,cmd) -> runs cmd if target is outdated.
602
602
603 This is just a wrapper around target_outdated() which calls the given
603 This is just a wrapper around target_outdated() which calls the given
604 command if target is outdated."""
604 command if target is outdated."""
605
605
606 if target_outdated(target,deps):
606 if target_outdated(target,deps):
607 xsys(cmd)
607 xsys(cmd)
608
608
609 #----------------------------------------------------------------------------
609 #----------------------------------------------------------------------------
610 def unquote_ends(istr):
610 def unquote_ends(istr):
611 """Remove a single pair of quotes from the endpoints of a string."""
611 """Remove a single pair of quotes from the endpoints of a string."""
612
612
613 if not istr:
613 if not istr:
614 return istr
614 return istr
615 if (istr[0]=="'" and istr[-1]=="'") or \
615 if (istr[0]=="'" and istr[-1]=="'") or \
616 (istr[0]=='"' and istr[-1]=='"'):
616 (istr[0]=='"' and istr[-1]=='"'):
617 return istr[1:-1]
617 return istr[1:-1]
618 else:
618 else:
619 return istr
619 return istr
620
620
621 #----------------------------------------------------------------------------
621 #----------------------------------------------------------------------------
622 def process_cmdline(argv,names=[],defaults={},usage=''):
622 def process_cmdline(argv,names=[],defaults={},usage=''):
623 """ Process command-line options and arguments.
623 """ Process command-line options and arguments.
624
624
625 Arguments:
625 Arguments:
626
626
627 - argv: list of arguments, typically sys.argv.
627 - argv: list of arguments, typically sys.argv.
628
628
629 - names: list of option names. See DPyGetOpt docs for details on options
629 - names: list of option names. See DPyGetOpt docs for details on options
630 syntax.
630 syntax.
631
631
632 - defaults: dict of default values.
632 - defaults: dict of default values.
633
633
634 - usage: optional usage notice to print if a wrong argument is passed.
634 - usage: optional usage notice to print if a wrong argument is passed.
635
635
636 Return a dict of options and a list of free arguments."""
636 Return a dict of options and a list of free arguments."""
637
637
638 getopt = DPyGetOpt.DPyGetOpt()
638 getopt = DPyGetOpt.DPyGetOpt()
639 getopt.setIgnoreCase(0)
639 getopt.setIgnoreCase(0)
640 getopt.parseConfiguration(names)
640 getopt.parseConfiguration(names)
641
641
642 try:
642 try:
643 getopt.processArguments(argv)
643 getopt.processArguments(argv)
644 except DPyGetOpt.ArgumentError, exc:
644 except DPyGetOpt.ArgumentError, exc:
645 print usage
645 print usage
646 warn('"%s"' % exc,level=4)
646 warn('"%s"' % exc,level=4)
647
647
648 defaults.update(getopt.optionValues)
648 defaults.update(getopt.optionValues)
649 args = getopt.freeValues
649 args = getopt.freeValues
650
650
651 return defaults,args
651 return defaults,args
652
652
653 #----------------------------------------------------------------------------
653 #----------------------------------------------------------------------------
654 def optstr2types(ostr):
654 def optstr2types(ostr):
655 """Convert a string of option names to a dict of type mappings.
655 """Convert a string of option names to a dict of type mappings.
656
656
657 optstr2types(str) -> {None:'string_opts',int:'int_opts',float:'float_opts'}
657 optstr2types(str) -> {None:'string_opts',int:'int_opts',float:'float_opts'}
658
658
659 This is used to get the types of all the options in a string formatted
659 This is used to get the types of all the options in a string formatted
660 with the conventions of DPyGetOpt. The 'type' None is used for options
660 with the conventions of DPyGetOpt. The 'type' None is used for options
661 which are strings (they need no further conversion). This function's main
661 which are strings (they need no further conversion). This function's main
662 use is to get a typemap for use with read_dict().
662 use is to get a typemap for use with read_dict().
663 """
663 """
664
664
665 typeconv = {None:'',int:'',float:''}
665 typeconv = {None:'',int:'',float:''}
666 typemap = {'s':None,'i':int,'f':float}
666 typemap = {'s':None,'i':int,'f':float}
667 opt_re = re.compile(r'([\w]*)([^:=]*:?=?)([sif]?)')
667 opt_re = re.compile(r'([\w]*)([^:=]*:?=?)([sif]?)')
668
668
669 for w in ostr.split():
669 for w in ostr.split():
670 oname,alias,otype = opt_re.match(w).groups()
670 oname,alias,otype = opt_re.match(w).groups()
671 if otype == '' or alias == '!': # simple switches are integers too
671 if otype == '' or alias == '!': # simple switches are integers too
672 otype = 'i'
672 otype = 'i'
673 typeconv[typemap[otype]] += oname + ' '
673 typeconv[typemap[otype]] += oname + ' '
674 return typeconv
674 return typeconv
675
675
676 #----------------------------------------------------------------------------
676 #----------------------------------------------------------------------------
677 def read_dict(filename,type_conv=None,**opt):
677 def read_dict(filename,type_conv=None,**opt):
678 r"""Read a dictionary of key=value pairs from an input file, optionally
678 r"""Read a dictionary of key=value pairs from an input file, optionally
679 performing conversions on the resulting values.
679 performing conversions on the resulting values.
680
680
681 read_dict(filename,type_conv,**opt) -> dict
681 read_dict(filename,type_conv,**opt) -> dict
682
682
683 Only one value per line is accepted, the format should be
683 Only one value per line is accepted, the format should be
684 # optional comments are ignored
684 # optional comments are ignored
685 key value\n
685 key value\n
686
686
687 Args:
687 Args:
688
688
689 - type_conv: A dictionary specifying which keys need to be converted to
689 - type_conv: A dictionary specifying which keys need to be converted to
690 which types. By default all keys are read as strings. This dictionary
690 which types. By default all keys are read as strings. This dictionary
691 should have as its keys valid conversion functions for strings
691 should have as its keys valid conversion functions for strings
692 (int,long,float,complex, or your own). The value for each key
692 (int,long,float,complex, or your own). The value for each key
693 (converter) should be a whitespace separated string containing the names
693 (converter) should be a whitespace separated string containing the names
694 of all the entries in the file to be converted using that function. For
694 of all the entries in the file to be converted using that function. For
695 keys to be left alone, use None as the conversion function (only needed
695 keys to be left alone, use None as the conversion function (only needed
696 with purge=1, see below).
696 with purge=1, see below).
697
697
698 - opt: dictionary with extra options as below (default in parens)
698 - opt: dictionary with extra options as below (default in parens)
699
699
700 purge(0): if set to 1, all keys *not* listed in type_conv are purged out
700 purge(0): if set to 1, all keys *not* listed in type_conv are purged out
701 of the dictionary to be returned. If purge is going to be used, the
701 of the dictionary to be returned. If purge is going to be used, the
702 set of keys to be left as strings also has to be explicitly specified
702 set of keys to be left as strings also has to be explicitly specified
703 using the (non-existent) conversion function None.
703 using the (non-existent) conversion function None.
704
704
705 fs(None): field separator. This is the key/value separator to be used
705 fs(None): field separator. This is the key/value separator to be used
706 when parsing the file. The None default means any whitespace [behavior
706 when parsing the file. The None default means any whitespace [behavior
707 of string.split()].
707 of string.split()].
708
708
709 strip(0): if 1, strip string values of leading/trailinig whitespace.
709 strip(0): if 1, strip string values of leading/trailinig whitespace.
710
710
711 warn(1): warning level if requested keys are not found in file.
711 warn(1): warning level if requested keys are not found in file.
712 - 0: silently ignore.
712 - 0: silently ignore.
713 - 1: inform but proceed.
713 - 1: inform but proceed.
714 - 2: raise KeyError exception.
714 - 2: raise KeyError exception.
715
715
716 no_empty(0): if 1, remove keys with whitespace strings as a value.
716 no_empty(0): if 1, remove keys with whitespace strings as a value.
717
717
718 unique([]): list of keys (or space separated string) which can't be
718 unique([]): list of keys (or space separated string) which can't be
719 repeated. If one such key is found in the file, each new instance
719 repeated. If one such key is found in the file, each new instance
720 overwrites the previous one. For keys not listed here, the behavior is
720 overwrites the previous one. For keys not listed here, the behavior is
721 to make a list of all appearances.
721 to make a list of all appearances.
722
722
723 Example:
723 Example:
724
724
725 If the input file test.ini contains (we put it in a string to keep the test
725 If the input file test.ini contains (we put it in a string to keep the test
726 self-contained):
726 self-contained):
727
727
728 >>> test_ini = '''\
728 >>> test_ini = '''\
729 ... i 3
729 ... i 3
730 ... x 4.5
730 ... x 4.5
731 ... y 5.5
731 ... y 5.5
732 ... s hi ho'''
732 ... s hi ho'''
733
733
734 Then we can use it as follows:
734 Then we can use it as follows:
735 >>> type_conv={int:'i',float:'x',None:'s'}
735 >>> type_conv={int:'i',float:'x',None:'s'}
736
736
737 >>> d = read_dict(test_ini)
737 >>> d = read_dict(test_ini)
738
738
739 >>> sorted(d.items())
739 >>> sorted(d.items())
740 [('i', '3'), ('s', 'hi ho'), ('x', '4.5'), ('y', '5.5')]
740 [('i', '3'), ('s', 'hi ho'), ('x', '4.5'), ('y', '5.5')]
741
741
742 >>> d = read_dict(test_ini,type_conv)
742 >>> d = read_dict(test_ini,type_conv)
743
743
744 >>> sorted(d.items())
744 >>> sorted(d.items())
745 [('i', 3), ('s', 'hi ho'), ('x', 4.5), ('y', '5.5')]
745 [('i', 3), ('s', 'hi ho'), ('x', 4.5), ('y', '5.5')]
746
746
747 >>> d = read_dict(test_ini,type_conv,purge=True)
747 >>> d = read_dict(test_ini,type_conv,purge=True)
748
748
749 >>> sorted(d.items())
749 >>> sorted(d.items())
750 [('i', 3), ('s', 'hi ho'), ('x', 4.5)]
750 [('i', 3), ('s', 'hi ho'), ('x', 4.5)]
751 """
751 """
752
752
753 # starting config
753 # starting config
754 opt.setdefault('purge',0)
754 opt.setdefault('purge',0)
755 opt.setdefault('fs',None) # field sep defaults to any whitespace
755 opt.setdefault('fs',None) # field sep defaults to any whitespace
756 opt.setdefault('strip',0)
756 opt.setdefault('strip',0)
757 opt.setdefault('warn',1)
757 opt.setdefault('warn',1)
758 opt.setdefault('no_empty',0)
758 opt.setdefault('no_empty',0)
759 opt.setdefault('unique','')
759 opt.setdefault('unique','')
760 if type(opt['unique']) in StringTypes:
760 if type(opt['unique']) in StringTypes:
761 unique_keys = qw(opt['unique'])
761 unique_keys = qw(opt['unique'])
762 elif type(opt['unique']) in (types.TupleType,types.ListType):
762 elif type(opt['unique']) in (types.TupleType,types.ListType):
763 unique_keys = opt['unique']
763 unique_keys = opt['unique']
764 else:
764 else:
765 raise ValueError, 'Unique keys must be given as a string, List or Tuple'
765 raise ValueError, 'Unique keys must be given as a string, List or Tuple'
766
766
767 dict = {}
767 dict = {}
768
768
769 # first read in table of values as strings
769 # first read in table of values as strings
770 if '\n' in filename:
770 if '\n' in filename:
771 lines = filename.splitlines()
771 lines = filename.splitlines()
772 file = None
772 file = None
773 else:
773 else:
774 file = open(filename,'r')
774 file = open(filename,'r')
775 lines = file.readlines()
775 lines = file.readlines()
776 for line in lines:
776 for line in lines:
777 line = line.strip()
777 line = line.strip()
778 if len(line) and line[0]=='#': continue
778 if len(line) and line[0]=='#': continue
779 if len(line)>0:
779 if len(line)>0:
780 lsplit = line.split(opt['fs'],1)
780 lsplit = line.split(opt['fs'],1)
781 try:
781 try:
782 key,val = lsplit
782 key,val = lsplit
783 except ValueError:
783 except ValueError:
784 key,val = lsplit[0],''
784 key,val = lsplit[0],''
785 key = key.strip()
785 key = key.strip()
786 if opt['strip']: val = val.strip()
786 if opt['strip']: val = val.strip()
787 if val == "''" or val == '""': val = ''
787 if val == "''" or val == '""': val = ''
788 if opt['no_empty'] and (val=='' or val.isspace()):
788 if opt['no_empty'] and (val=='' or val.isspace()):
789 continue
789 continue
790 # if a key is found more than once in the file, build a list
790 # if a key is found more than once in the file, build a list
791 # unless it's in the 'unique' list. In that case, last found in file
791 # unless it's in the 'unique' list. In that case, last found in file
792 # takes precedence. User beware.
792 # takes precedence. User beware.
793 try:
793 try:
794 if dict[key] and key in unique_keys:
794 if dict[key] and key in unique_keys:
795 dict[key] = val
795 dict[key] = val
796 elif type(dict[key]) is types.ListType:
796 elif type(dict[key]) is types.ListType:
797 dict[key].append(val)
797 dict[key].append(val)
798 else:
798 else:
799 dict[key] = [dict[key],val]
799 dict[key] = [dict[key],val]
800 except KeyError:
800 except KeyError:
801 dict[key] = val
801 dict[key] = val
802 # purge if requested
802 # purge if requested
803 if opt['purge']:
803 if opt['purge']:
804 accepted_keys = qwflat(type_conv.values())
804 accepted_keys = qwflat(type_conv.values())
805 for key in dict.keys():
805 for key in dict.keys():
806 if key in accepted_keys: continue
806 if key in accepted_keys: continue
807 del(dict[key])
807 del(dict[key])
808 # now convert if requested
808 # now convert if requested
809 if type_conv==None: return dict
809 if type_conv==None: return dict
810 conversions = type_conv.keys()
810 conversions = type_conv.keys()
811 try: conversions.remove(None)
811 try: conversions.remove(None)
812 except: pass
812 except: pass
813 for convert in conversions:
813 for convert in conversions:
814 for val in qw(type_conv[convert]):
814 for val in qw(type_conv[convert]):
815 try:
815 try:
816 dict[val] = convert(dict[val])
816 dict[val] = convert(dict[val])
817 except KeyError,e:
817 except KeyError,e:
818 if opt['warn'] == 0:
818 if opt['warn'] == 0:
819 pass
819 pass
820 elif opt['warn'] == 1:
820 elif opt['warn'] == 1:
821 print >>sys.stderr, 'Warning: key',val,\
821 print >>sys.stderr, 'Warning: key',val,\
822 'not found in file',filename
822 'not found in file',filename
823 elif opt['warn'] == 2:
823 elif opt['warn'] == 2:
824 raise KeyError,e
824 raise KeyError,e
825 else:
825 else:
826 raise ValueError,'Warning level must be 0,1 or 2'
826 raise ValueError,'Warning level must be 0,1 or 2'
827
827
828 return dict
828 return dict
829
829
830 #----------------------------------------------------------------------------
830 #----------------------------------------------------------------------------
831 def flag_calls(func):
831 def flag_calls(func):
832 """Wrap a function to detect and flag when it gets called.
832 """Wrap a function to detect and flag when it gets called.
833
833
834 This is a decorator which takes a function and wraps it in a function with
834 This is a decorator which takes a function and wraps it in a function with
835 a 'called' attribute. wrapper.called is initialized to False.
835 a 'called' attribute. wrapper.called is initialized to False.
836
836
837 The wrapper.called attribute is set to False right before each call to the
837 The wrapper.called attribute is set to False right before each call to the
838 wrapped function, so if the call fails it remains False. After the call
838 wrapped function, so if the call fails it remains False. After the call
839 completes, wrapper.called is set to True and the output is returned.
839 completes, wrapper.called is set to True and the output is returned.
840
840
841 Testing for truth in wrapper.called allows you to determine if a call to
841 Testing for truth in wrapper.called allows you to determine if a call to
842 func() was attempted and succeeded."""
842 func() was attempted and succeeded."""
843
843
844 def wrapper(*args,**kw):
844 def wrapper(*args,**kw):
845 wrapper.called = False
845 wrapper.called = False
846 out = func(*args,**kw)
846 out = func(*args,**kw)
847 wrapper.called = True
847 wrapper.called = True
848 return out
848 return out
849
849
850 wrapper.called = False
850 wrapper.called = False
851 wrapper.__doc__ = func.__doc__
851 wrapper.__doc__ = func.__doc__
852 return wrapper
852 return wrapper
853
853
854 #----------------------------------------------------------------------------
854 #----------------------------------------------------------------------------
855 def dhook_wrap(func,*a,**k):
855 def dhook_wrap(func,*a,**k):
856 """Wrap a function call in a sys.displayhook controller.
856 """Wrap a function call in a sys.displayhook controller.
857
857
858 Returns a wrapper around func which calls func, with all its arguments and
858 Returns a wrapper around func which calls func, with all its arguments and
859 keywords unmodified, using the default sys.displayhook. Since IPython
859 keywords unmodified, using the default sys.displayhook. Since IPython
860 modifies sys.displayhook, it breaks the behavior of certain systems that
860 modifies sys.displayhook, it breaks the behavior of certain systems that
861 rely on the default behavior, notably doctest.
861 rely on the default behavior, notably doctest.
862 """
862 """
863
863
864 def f(*a,**k):
864 def f(*a,**k):
865
865
866 dhook_s = sys.displayhook
866 dhook_s = sys.displayhook
867 sys.displayhook = sys.__displayhook__
867 sys.displayhook = sys.__displayhook__
868 try:
868 try:
869 out = func(*a,**k)
869 out = func(*a,**k)
870 finally:
870 finally:
871 sys.displayhook = dhook_s
871 sys.displayhook = dhook_s
872
872
873 return out
873 return out
874
874
875 f.__doc__ = func.__doc__
875 f.__doc__ = func.__doc__
876 return f
876 return f
877
877
878 #----------------------------------------------------------------------------
878 #----------------------------------------------------------------------------
879 def doctest_reload():
879 def doctest_reload():
880 """Properly reload doctest to reuse it interactively.
880 """Properly reload doctest to reuse it interactively.
881
881
882 This routine:
882 This routine:
883
883
884 - reloads doctest
884 - reloads doctest
885
885
886 - resets its global 'master' attribute to None, so that multiple uses of
886 - resets its global 'master' attribute to None, so that multiple uses of
887 the module interactively don't produce cumulative reports.
887 the module interactively don't produce cumulative reports.
888
888
889 - Monkeypatches its core test runner method to protect it from IPython's
889 - Monkeypatches its core test runner method to protect it from IPython's
890 modified displayhook. Doctest expects the default displayhook behavior
890 modified displayhook. Doctest expects the default displayhook behavior
891 deep down, so our modification breaks it completely. For this reason, a
891 deep down, so our modification breaks it completely. For this reason, a
892 hard monkeypatch seems like a reasonable solution rather than asking
892 hard monkeypatch seems like a reasonable solution rather than asking
893 users to manually use a different doctest runner when under IPython."""
893 users to manually use a different doctest runner when under IPython."""
894
894
895 import doctest
895 import doctest
896 reload(doctest)
896 reload(doctest)
897 doctest.master=None
897 doctest.master=None
898
898
899 try:
899 try:
900 doctest.DocTestRunner
900 doctest.DocTestRunner
901 except AttributeError:
901 except AttributeError:
902 # This is only for python 2.3 compatibility, remove once we move to
902 # This is only for python 2.3 compatibility, remove once we move to
903 # 2.4 only.
903 # 2.4 only.
904 pass
904 pass
905 else:
905 else:
906 doctest.DocTestRunner.run = dhook_wrap(doctest.DocTestRunner.run)
906 doctest.DocTestRunner.run = dhook_wrap(doctest.DocTestRunner.run)
907
907
908 #----------------------------------------------------------------------------
908 #----------------------------------------------------------------------------
909 class HomeDirError(Error):
909 class HomeDirError(Error):
910 pass
910 pass
911
911
912 def get_home_dir():
912 def get_home_dir():
913 """Return the closest possible equivalent to a 'home' directory.
913 """Return the closest possible equivalent to a 'home' directory.
914
914
915 We first try $HOME. Absent that, on NT it's $HOMEDRIVE\$HOMEPATH.
915 We first try $HOME. Absent that, on NT it's $HOMEDRIVE\$HOMEPATH.
916
916
917 Currently only Posix and NT are implemented, a HomeDirError exception is
917 Currently only Posix and NT are implemented, a HomeDirError exception is
918 raised for all other OSes. """
918 raised for all other OSes. """
919
919
920 isdir = os.path.isdir
920 isdir = os.path.isdir
921 env = os.environ
921 env = os.environ
922
922
923 # first, check py2exe distribution root directory for _ipython.
923 # first, check py2exe distribution root directory for _ipython.
924 # This overrides all. Normally does not exist.
924 # This overrides all. Normally does not exist.
925
925
926 if hasattr(sys, "frozen"): #Is frozen by py2exe
926 if hasattr(sys, "frozen"): #Is frozen by py2exe
927 if '\\library.zip\\' in IPython.__file__.lower():#libraries compressed to zip-file
927 if '\\library.zip\\' in IPython.__file__.lower():#libraries compressed to zip-file
928 root, rest = IPython.__file__.lower().split('library.zip')
928 root, rest = IPython.__file__.lower().split('library.zip')
929 else:
929 else:
930 root=os.path.join(os.path.split(IPython.__file__)[0],"../../")
930 root=os.path.join(os.path.split(IPython.__file__)[0],"../../")
931 root=os.path.abspath(root).rstrip('\\')
931 root=os.path.abspath(root).rstrip('\\')
932 if isdir(os.path.join(root, '_ipython')):
932 if isdir(os.path.join(root, '_ipython')):
933 os.environ["IPYKITROOT"] = root
933 os.environ["IPYKITROOT"] = root
934 return root
934 return root
935 try:
935 try:
936 homedir = env['HOME']
936 homedir = env['HOME']
937 if not isdir(homedir):
937 if not isdir(homedir):
938 # in case a user stuck some string which does NOT resolve to a
938 # in case a user stuck some string which does NOT resolve to a
939 # valid path, it's as good as if we hadn't foud it
939 # valid path, it's as good as if we hadn't foud it
940 raise KeyError
940 raise KeyError
941 return homedir
941 return homedir
942 except KeyError:
942 except KeyError:
943 if os.name == 'posix':
943 if os.name == 'posix':
944 raise HomeDirError,'undefined $HOME, IPython can not proceed.'
944 raise HomeDirError,'undefined $HOME, IPython can not proceed.'
945 elif os.name == 'nt':
945 elif os.name == 'nt':
946 # For some strange reason, win9x returns 'nt' for os.name.
946 # For some strange reason, win9x returns 'nt' for os.name.
947 try:
947 try:
948 homedir = os.path.join(env['HOMEDRIVE'],env['HOMEPATH'])
948 homedir = os.path.join(env['HOMEDRIVE'],env['HOMEPATH'])
949 if not isdir(homedir):
949 if not isdir(homedir):
950 homedir = os.path.join(env['USERPROFILE'])
950 homedir = os.path.join(env['USERPROFILE'])
951 if not isdir(homedir):
951 if not isdir(homedir):
952 raise HomeDirError
952 raise HomeDirError
953 return homedir
953 return homedir
954 except KeyError:
954 except KeyError:
955 try:
955 try:
956 # Use the registry to get the 'My Documents' folder.
956 # Use the registry to get the 'My Documents' folder.
957 import _winreg as wreg
957 import _winreg as wreg
958 key = wreg.OpenKey(wreg.HKEY_CURRENT_USER,
958 key = wreg.OpenKey(wreg.HKEY_CURRENT_USER,
959 "Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
959 "Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
960 homedir = wreg.QueryValueEx(key,'Personal')[0]
960 homedir = wreg.QueryValueEx(key,'Personal')[0]
961 key.Close()
961 key.Close()
962 if not isdir(homedir):
962 if not isdir(homedir):
963 e = ('Invalid "Personal" folder registry key '
963 e = ('Invalid "Personal" folder registry key '
964 'typically "My Documents".\n'
964 'typically "My Documents".\n'
965 'Value: %s\n'
965 'Value: %s\n'
966 'This is not a valid directory on your system.' %
966 'This is not a valid directory on your system.' %
967 homedir)
967 homedir)
968 raise HomeDirError(e)
968 raise HomeDirError(e)
969 return homedir
969 return homedir
970 except HomeDirError:
970 except HomeDirError:
971 raise
971 raise
972 except:
972 except:
973 return 'C:\\'
973 return 'C:\\'
974 elif os.name == 'dos':
974 elif os.name == 'dos':
975 # Desperate, may do absurd things in classic MacOS. May work under DOS.
975 # Desperate, may do absurd things in classic MacOS. May work under DOS.
976 return 'C:\\'
976 return 'C:\\'
977 else:
977 else:
978 raise HomeDirError,'support for your operating system not implemented.'
978 raise HomeDirError,'support for your operating system not implemented.'
979
979
980
980
981 def get_ipython_dir():
981 def get_ipython_dir():
982 """Get the IPython directory for this platform and user.
982 """Get the IPython directory for this platform and user.
983
983
984 This uses the logic in `get_home_dir` to find the home directory
984 This uses the logic in `get_home_dir` to find the home directory
985 and the adds either .ipython or _ipython to the end of the path.
985 and the adds either .ipython or _ipython to the end of the path.
986 """
986 """
987 if os.name == 'posix':
987 if os.name == 'posix':
988 ipdir_def = '.ipython'
988 ipdir_def = '.ipython'
989 else:
989 else:
990 ipdir_def = '_ipython'
990 ipdir_def = '_ipython'
991 home_dir = get_home_dir()
991 home_dir = get_home_dir()
992 ipdir = os.path.abspath(os.environ.get('IPYTHONDIR',
992 ipdir = os.path.abspath(os.environ.get('IPYTHONDIR',
993 os.path.join(home_dir, ipdir_def)))
993 os.path.join(home_dir, ipdir_def)))
994 return ipdir.decode(sys.getfilesystemencoding())
994 return ipdir.decode(sys.getfilesystemencoding())
995
995
996 def get_security_dir():
996 def get_security_dir():
997 """Get the IPython security directory.
997 """Get the IPython security directory.
998
998
999 This directory is the default location for all security related files,
999 This directory is the default location for all security related files,
1000 including SSL/TLS certificates and FURL files.
1000 including SSL/TLS certificates and FURL files.
1001
1001
1002 If the directory does not exist, it is created with 0700 permissions.
1002 If the directory does not exist, it is created with 0700 permissions.
1003 If it exists, permissions are set to 0700.
1003 If it exists, permissions are set to 0700.
1004 """
1004 """
1005 security_dir = os.path.join(get_ipython_dir(), 'security')
1005 security_dir = os.path.join(get_ipython_dir(), 'security')
1006 if not os.path.isdir(security_dir):
1006 if not os.path.isdir(security_dir):
1007 os.mkdir(security_dir, 0700)
1007 os.mkdir(security_dir, 0700)
1008 else:
1008 else:
1009 os.chmod(security_dir, 0700)
1009 os.chmod(security_dir, 0700)
1010 return security_dir
1010 return security_dir
1011
1011
1012 def get_log_dir():
1012 def get_log_dir():
1013 """Get the IPython log directory.
1013 """Get the IPython log directory.
1014
1014
1015 If the log directory does not exist, it is created.
1015 If the log directory does not exist, it is created.
1016 """
1016 """
1017 log_dir = os.path.join(get_ipython_dir(), 'log')
1017 log_dir = os.path.join(get_ipython_dir(), 'log')
1018 if not os.path.isdir(log_dir):
1018 if not os.path.isdir(log_dir):
1019 os.mkdir(log_dir, 0777)
1019 os.mkdir(log_dir, 0777)
1020 return log_dir
1020 return log_dir
1021
1021
1022 #****************************************************************************
1022 #****************************************************************************
1023 # strings and text
1023 # strings and text
1024
1024
1025 class LSString(str):
1025 class LSString(str):
1026 """String derivative with a special access attributes.
1026 """String derivative with a special access attributes.
1027
1027
1028 These are normal strings, but with the special attributes:
1028 These are normal strings, but with the special attributes:
1029
1029
1030 .l (or .list) : value as list (split on newlines).
1030 .l (or .list) : value as list (split on newlines).
1031 .n (or .nlstr): original value (the string itself).
1031 .n (or .nlstr): original value (the string itself).
1032 .s (or .spstr): value as whitespace-separated string.
1032 .s (or .spstr): value as whitespace-separated string.
1033 .p (or .paths): list of path objects
1033 .p (or .paths): list of path objects
1034
1034
1035 Any values which require transformations are computed only once and
1035 Any values which require transformations are computed only once and
1036 cached.
1036 cached.
1037
1037
1038 Such strings are very useful to efficiently interact with the shell, which
1038 Such strings are very useful to efficiently interact with the shell, which
1039 typically only understands whitespace-separated options for commands."""
1039 typically only understands whitespace-separated options for commands."""
1040
1040
1041 def get_list(self):
1041 def get_list(self):
1042 try:
1042 try:
1043 return self.__list
1043 return self.__list
1044 except AttributeError:
1044 except AttributeError:
1045 self.__list = self.split('\n')
1045 self.__list = self.split('\n')
1046 return self.__list
1046 return self.__list
1047
1047
1048 l = list = property(get_list)
1048 l = list = property(get_list)
1049
1049
1050 def get_spstr(self):
1050 def get_spstr(self):
1051 try:
1051 try:
1052 return self.__spstr
1052 return self.__spstr
1053 except AttributeError:
1053 except AttributeError:
1054 self.__spstr = self.replace('\n',' ')
1054 self.__spstr = self.replace('\n',' ')
1055 return self.__spstr
1055 return self.__spstr
1056
1056
1057 s = spstr = property(get_spstr)
1057 s = spstr = property(get_spstr)
1058
1058
1059 def get_nlstr(self):
1059 def get_nlstr(self):
1060 return self
1060 return self
1061
1061
1062 n = nlstr = property(get_nlstr)
1062 n = nlstr = property(get_nlstr)
1063
1063
1064 def get_paths(self):
1064 def get_paths(self):
1065 try:
1065 try:
1066 return self.__paths
1066 return self.__paths
1067 except AttributeError:
1067 except AttributeError:
1068 self.__paths = [path(p) for p in self.split('\n') if os.path.exists(p)]
1068 self.__paths = [path(p) for p in self.split('\n') if os.path.exists(p)]
1069 return self.__paths
1069 return self.__paths
1070
1070
1071 p = paths = property(get_paths)
1071 p = paths = property(get_paths)
1072
1072
1073 def print_lsstring(arg):
1073 def print_lsstring(arg):
1074 """ Prettier (non-repr-like) and more informative printer for LSString """
1074 """ Prettier (non-repr-like) and more informative printer for LSString """
1075 print "LSString (.p, .n, .l, .s available). Value:"
1075 print "LSString (.p, .n, .l, .s available). Value:"
1076 print arg
1076 print arg
1077
1077
1078 print_lsstring = result_display.when_type(LSString)(print_lsstring)
1078 print_lsstring = result_display.when_type(LSString)(print_lsstring)
1079
1079
1080 #----------------------------------------------------------------------------
1080 #----------------------------------------------------------------------------
1081 class SList(list):
1081 class SList(list):
1082 """List derivative with a special access attributes.
1082 """List derivative with a special access attributes.
1083
1083
1084 These are normal lists, but with the special attributes:
1084 These are normal lists, but with the special attributes:
1085
1085
1086 .l (or .list) : value as list (the list itself).
1086 .l (or .list) : value as list (the list itself).
1087 .n (or .nlstr): value as a string, joined on newlines.
1087 .n (or .nlstr): value as a string, joined on newlines.
1088 .s (or .spstr): value as a string, joined on spaces.
1088 .s (or .spstr): value as a string, joined on spaces.
1089 .p (or .paths): list of path objects
1089 .p (or .paths): list of path objects
1090
1090
1091 Any values which require transformations are computed only once and
1091 Any values which require transformations are computed only once and
1092 cached."""
1092 cached."""
1093
1093
1094 def get_list(self):
1094 def get_list(self):
1095 return self
1095 return self
1096
1096
1097 l = list = property(get_list)
1097 l = list = property(get_list)
1098
1098
1099 def get_spstr(self):
1099 def get_spstr(self):
1100 try:
1100 try:
1101 return self.__spstr
1101 return self.__spstr
1102 except AttributeError:
1102 except AttributeError:
1103 self.__spstr = ' '.join(self)
1103 self.__spstr = ' '.join(self)
1104 return self.__spstr
1104 return self.__spstr
1105
1105
1106 s = spstr = property(get_spstr)
1106 s = spstr = property(get_spstr)
1107
1107
1108 def get_nlstr(self):
1108 def get_nlstr(self):
1109 try:
1109 try:
1110 return self.__nlstr
1110 return self.__nlstr
1111 except AttributeError:
1111 except AttributeError:
1112 self.__nlstr = '\n'.join(self)
1112 self.__nlstr = '\n'.join(self)
1113 return self.__nlstr
1113 return self.__nlstr
1114
1114
1115 n = nlstr = property(get_nlstr)
1115 n = nlstr = property(get_nlstr)
1116
1116
1117 def get_paths(self):
1117 def get_paths(self):
1118 try:
1118 try:
1119 return self.__paths
1119 return self.__paths
1120 except AttributeError:
1120 except AttributeError:
1121 self.__paths = [path(p) for p in self if os.path.exists(p)]
1121 self.__paths = [path(p) for p in self if os.path.exists(p)]
1122 return self.__paths
1122 return self.__paths
1123
1123
1124 p = paths = property(get_paths)
1124 p = paths = property(get_paths)
1125
1125
1126 def grep(self, pattern, prune = False, field = None):
1126 def grep(self, pattern, prune = False, field = None):
1127 """ Return all strings matching 'pattern' (a regex or callable)
1127 """ Return all strings matching 'pattern' (a regex or callable)
1128
1128
1129 This is case-insensitive. If prune is true, return all items
1129 This is case-insensitive. If prune is true, return all items
1130 NOT matching the pattern.
1130 NOT matching the pattern.
1131
1131
1132 If field is specified, the match must occur in the specified
1132 If field is specified, the match must occur in the specified
1133 whitespace-separated field.
1133 whitespace-separated field.
1134
1134
1135 Examples::
1135 Examples::
1136
1136
1137 a.grep( lambda x: x.startswith('C') )
1137 a.grep( lambda x: x.startswith('C') )
1138 a.grep('Cha.*log', prune=1)
1138 a.grep('Cha.*log', prune=1)
1139 a.grep('chm', field=-1)
1139 a.grep('chm', field=-1)
1140 """
1140 """
1141
1141
1142 def match_target(s):
1142 def match_target(s):
1143 if field is None:
1143 if field is None:
1144 return s
1144 return s
1145 parts = s.split()
1145 parts = s.split()
1146 try:
1146 try:
1147 tgt = parts[field]
1147 tgt = parts[field]
1148 return tgt
1148 return tgt
1149 except IndexError:
1149 except IndexError:
1150 return ""
1150 return ""
1151
1151
1152 if isinstance(pattern, basestring):
1152 if isinstance(pattern, basestring):
1153 pred = lambda x : re.search(pattern, x, re.IGNORECASE)
1153 pred = lambda x : re.search(pattern, x, re.IGNORECASE)
1154 else:
1154 else:
1155 pred = pattern
1155 pred = pattern
1156 if not prune:
1156 if not prune:
1157 return SList([el for el in self if pred(match_target(el))])
1157 return SList([el for el in self if pred(match_target(el))])
1158 else:
1158 else:
1159 return SList([el for el in self if not pred(match_target(el))])
1159 return SList([el for el in self if not pred(match_target(el))])
1160 def fields(self, *fields):
1160 def fields(self, *fields):
1161 """ Collect whitespace-separated fields from string list
1161 """ Collect whitespace-separated fields from string list
1162
1162
1163 Allows quick awk-like usage of string lists.
1163 Allows quick awk-like usage of string lists.
1164
1164
1165 Example data (in var a, created by 'a = !ls -l')::
1165 Example data (in var a, created by 'a = !ls -l')::
1166 -rwxrwxrwx 1 ville None 18 Dec 14 2006 ChangeLog
1166 -rwxrwxrwx 1 ville None 18 Dec 14 2006 ChangeLog
1167 drwxrwxrwx+ 6 ville None 0 Oct 24 18:05 IPython
1167 drwxrwxrwx+ 6 ville None 0 Oct 24 18:05 IPython
1168
1168
1169 a.fields(0) is ['-rwxrwxrwx', 'drwxrwxrwx+']
1169 a.fields(0) is ['-rwxrwxrwx', 'drwxrwxrwx+']
1170 a.fields(1,0) is ['1 -rwxrwxrwx', '6 drwxrwxrwx+']
1170 a.fields(1,0) is ['1 -rwxrwxrwx', '6 drwxrwxrwx+']
1171 (note the joining by space).
1171 (note the joining by space).
1172 a.fields(-1) is ['ChangeLog', 'IPython']
1172 a.fields(-1) is ['ChangeLog', 'IPython']
1173
1173
1174 IndexErrors are ignored.
1174 IndexErrors are ignored.
1175
1175
1176 Without args, fields() just split()'s the strings.
1176 Without args, fields() just split()'s the strings.
1177 """
1177 """
1178 if len(fields) == 0:
1178 if len(fields) == 0:
1179 return [el.split() for el in self]
1179 return [el.split() for el in self]
1180
1180
1181 res = SList()
1181 res = SList()
1182 for el in [f.split() for f in self]:
1182 for el in [f.split() for f in self]:
1183 lineparts = []
1183 lineparts = []
1184
1184
1185 for fd in fields:
1185 for fd in fields:
1186 try:
1186 try:
1187 lineparts.append(el[fd])
1187 lineparts.append(el[fd])
1188 except IndexError:
1188 except IndexError:
1189 pass
1189 pass
1190 if lineparts:
1190 if lineparts:
1191 res.append(" ".join(lineparts))
1191 res.append(" ".join(lineparts))
1192
1192
1193 return res
1193 return res
1194 def sort(self,field= None, nums = False):
1194 def sort(self,field= None, nums = False):
1195 """ sort by specified fields (see fields())
1195 """ sort by specified fields (see fields())
1196
1196
1197 Example::
1197 Example::
1198 a.sort(1, nums = True)
1198 a.sort(1, nums = True)
1199
1199
1200 Sorts a by second field, in numerical order (so that 21 > 3)
1200 Sorts a by second field, in numerical order (so that 21 > 3)
1201
1201
1202 """
1202 """
1203
1203
1204 #decorate, sort, undecorate
1204 #decorate, sort, undecorate
1205 if field is not None:
1205 if field is not None:
1206 dsu = [[SList([line]).fields(field), line] for line in self]
1206 dsu = [[SList([line]).fields(field), line] for line in self]
1207 else:
1207 else:
1208 dsu = [[line, line] for line in self]
1208 dsu = [[line, line] for line in self]
1209 if nums:
1209 if nums:
1210 for i in range(len(dsu)):
1210 for i in range(len(dsu)):
1211 numstr = "".join([ch for ch in dsu[i][0] if ch.isdigit()])
1211 numstr = "".join([ch for ch in dsu[i][0] if ch.isdigit()])
1212 try:
1212 try:
1213 n = int(numstr)
1213 n = int(numstr)
1214 except ValueError:
1214 except ValueError:
1215 n = 0;
1215 n = 0;
1216 dsu[i][0] = n
1216 dsu[i][0] = n
1217
1217
1218
1218
1219 dsu.sort()
1219 dsu.sort()
1220 return SList([t[1] for t in dsu])
1220 return SList([t[1] for t in dsu])
1221
1221
1222 def print_slist(arg):
1222 def print_slist(arg):
1223 """ Prettier (non-repr-like) and more informative printer for SList """
1223 """ Prettier (non-repr-like) and more informative printer for SList """
1224 print "SList (.p, .n, .l, .s, .grep(), .fields(), sort() available):"
1224 print "SList (.p, .n, .l, .s, .grep(), .fields(), sort() available):"
1225 if hasattr(arg, 'hideonce') and arg.hideonce:
1225 if hasattr(arg, 'hideonce') and arg.hideonce:
1226 arg.hideonce = False
1226 arg.hideonce = False
1227 return
1227 return
1228
1228
1229 nlprint(arg)
1229 nlprint(arg)
1230
1230
1231 print_slist = result_display.when_type(SList)(print_slist)
1231 print_slist = result_display.when_type(SList)(print_slist)
1232
1232
1233
1233
1234
1234
1235 #----------------------------------------------------------------------------
1235 #----------------------------------------------------------------------------
1236 def esc_quotes(strng):
1236 def esc_quotes(strng):
1237 """Return the input string with single and double quotes escaped out"""
1237 """Return the input string with single and double quotes escaped out"""
1238
1238
1239 return strng.replace('"','\\"').replace("'","\\'")
1239 return strng.replace('"','\\"').replace("'","\\'")
1240
1240
1241 #----------------------------------------------------------------------------
1241 #----------------------------------------------------------------------------
1242 def make_quoted_expr(s):
1242 def make_quoted_expr(s):
1243 """Return string s in appropriate quotes, using raw string if possible.
1243 """Return string s in appropriate quotes, using raw string if possible.
1244
1244
1245 XXX - example removed because it caused encoding errors in documentation
1245 XXX - example removed because it caused encoding errors in documentation
1246 generation. We need a new example that doesn't contain invalid chars.
1246 generation. We need a new example that doesn't contain invalid chars.
1247
1247
1248 Note the use of raw string and padding at the end to allow trailing
1248 Note the use of raw string and padding at the end to allow trailing
1249 backslash.
1249 backslash.
1250 """
1250 """
1251
1251
1252 tail = ''
1252 tail = ''
1253 tailpadding = ''
1253 tailpadding = ''
1254 raw = ''
1254 raw = ''
1255 if "\\" in s:
1255 if "\\" in s:
1256 raw = 'r'
1256 raw = 'r'
1257 if s.endswith('\\'):
1257 if s.endswith('\\'):
1258 tail = '[:-1]'
1258 tail = '[:-1]'
1259 tailpadding = '_'
1259 tailpadding = '_'
1260 if '"' not in s:
1260 if '"' not in s:
1261 quote = '"'
1261 quote = '"'
1262 elif "'" not in s:
1262 elif "'" not in s:
1263 quote = "'"
1263 quote = "'"
1264 elif '"""' not in s and not s.endswith('"'):
1264 elif '"""' not in s and not s.endswith('"'):
1265 quote = '"""'
1265 quote = '"""'
1266 elif "'''" not in s and not s.endswith("'"):
1266 elif "'''" not in s and not s.endswith("'"):
1267 quote = "'''"
1267 quote = "'''"
1268 else:
1268 else:
1269 # give up, backslash-escaped string will do
1269 # give up, backslash-escaped string will do
1270 return '"%s"' % esc_quotes(s)
1270 return '"%s"' % esc_quotes(s)
1271 res = raw + quote + s + tailpadding + quote + tail
1271 res = raw + quote + s + tailpadding + quote + tail
1272 return res
1272 return res
1273
1273
1274
1274
1275 #----------------------------------------------------------------------------
1275 #----------------------------------------------------------------------------
1276 def raw_input_multi(header='', ps1='==> ', ps2='..> ',terminate_str = '.'):
1276 def raw_input_multi(header='', ps1='==> ', ps2='..> ',terminate_str = '.'):
1277 """Take multiple lines of input.
1277 """Take multiple lines of input.
1278
1278
1279 A list with each line of input as a separate element is returned when a
1279 A list with each line of input as a separate element is returned when a
1280 termination string is entered (defaults to a single '.'). Input can also
1280 termination string is entered (defaults to a single '.'). Input can also
1281 terminate via EOF (^D in Unix, ^Z-RET in Windows).
1281 terminate via EOF (^D in Unix, ^Z-RET in Windows).
1282
1282
1283 Lines of input which end in \\ are joined into single entries (and a
1283 Lines of input which end in \\ are joined into single entries (and a
1284 secondary continuation prompt is issued as long as the user terminates
1284 secondary continuation prompt is issued as long as the user terminates
1285 lines with \\). This allows entering very long strings which are still
1285 lines with \\). This allows entering very long strings which are still
1286 meant to be treated as single entities.
1286 meant to be treated as single entities.
1287 """
1287 """
1288
1288
1289 try:
1289 try:
1290 if header:
1290 if header:
1291 header += '\n'
1291 header += '\n'
1292 lines = [raw_input(header + ps1)]
1292 lines = [raw_input(header + ps1)]
1293 except EOFError:
1293 except EOFError:
1294 return []
1294 return []
1295 terminate = [terminate_str]
1295 terminate = [terminate_str]
1296 try:
1296 try:
1297 while lines[-1:] != terminate:
1297 while lines[-1:] != terminate:
1298 new_line = raw_input(ps1)
1298 new_line = raw_input(ps1)
1299 while new_line.endswith('\\'):
1299 while new_line.endswith('\\'):
1300 new_line = new_line[:-1] + raw_input(ps2)
1300 new_line = new_line[:-1] + raw_input(ps2)
1301 lines.append(new_line)
1301 lines.append(new_line)
1302
1302
1303 return lines[:-1] # don't return the termination command
1303 return lines[:-1] # don't return the termination command
1304 except EOFError:
1304 except EOFError:
1305 print
1305 print
1306 return lines
1306 return lines
1307
1307
1308 #----------------------------------------------------------------------------
1308 #----------------------------------------------------------------------------
1309 def raw_input_ext(prompt='', ps2='... '):
1309 def raw_input_ext(prompt='', ps2='... '):
1310 """Similar to raw_input(), but accepts extended lines if input ends with \\."""
1310 """Similar to raw_input(), but accepts extended lines if input ends with \\."""
1311
1311
1312 line = raw_input(prompt)
1312 line = raw_input(prompt)
1313 while line.endswith('\\'):
1313 while line.endswith('\\'):
1314 line = line[:-1] + raw_input(ps2)
1314 line = line[:-1] + raw_input(ps2)
1315 return line
1315 return line
1316
1316
1317 #----------------------------------------------------------------------------
1317 #----------------------------------------------------------------------------
1318 def ask_yes_no(prompt,default=None):
1318 def ask_yes_no(prompt,default=None):
1319 """Asks a question and returns a boolean (y/n) answer.
1319 """Asks a question and returns a boolean (y/n) answer.
1320
1320
1321 If default is given (one of 'y','n'), it is used if the user input is
1321 If default is given (one of 'y','n'), it is used if the user input is
1322 empty. Otherwise the question is repeated until an answer is given.
1322 empty. Otherwise the question is repeated until an answer is given.
1323
1323
1324 An EOF is treated as the default answer. If there is no default, an
1324 An EOF is treated as the default answer. If there is no default, an
1325 exception is raised to prevent infinite loops.
1325 exception is raised to prevent infinite loops.
1326
1326
1327 Valid answers are: y/yes/n/no (match is not case sensitive)."""
1327 Valid answers are: y/yes/n/no (match is not case sensitive)."""
1328
1328
1329 answers = {'y':True,'n':False,'yes':True,'no':False}
1329 answers = {'y':True,'n':False,'yes':True,'no':False}
1330 ans = None
1330 ans = None
1331 while ans not in answers.keys():
1331 while ans not in answers.keys():
1332 try:
1332 try:
1333 ans = raw_input(prompt+' ').lower()
1333 ans = raw_input(prompt+' ').lower()
1334 if not ans: # response was an empty string
1334 if not ans: # response was an empty string
1335 ans = default
1335 ans = default
1336 except KeyboardInterrupt:
1336 except KeyboardInterrupt:
1337 pass
1337 pass
1338 except EOFError:
1338 except EOFError:
1339 if default in answers.keys():
1339 if default in answers.keys():
1340 ans = default
1340 ans = default
1341 print
1341 print
1342 else:
1342 else:
1343 raise
1343 raise
1344
1344
1345 return answers[ans]
1345 return answers[ans]
1346
1346
1347 #----------------------------------------------------------------------------
1347 #----------------------------------------------------------------------------
1348 def marquee(txt='',width=78,mark='*'):
1348 def marquee(txt='',width=78,mark='*'):
1349 """Return the input string centered in a 'marquee'."""
1349 """Return the input string centered in a 'marquee'."""
1350 if not txt:
1350 if not txt:
1351 return (mark*width)[:width]
1351 return (mark*width)[:width]
1352 nmark = (width-len(txt)-2)/len(mark)/2
1352 nmark = (width-len(txt)-2)/len(mark)/2
1353 if nmark < 0: nmark =0
1353 if nmark < 0: nmark =0
1354 marks = mark*nmark
1354 marks = mark*nmark
1355 return '%s %s %s' % (marks,txt,marks)
1355 return '%s %s %s' % (marks,txt,marks)
1356
1356
1357 #----------------------------------------------------------------------------
1357 #----------------------------------------------------------------------------
1358 class EvalDict:
1358 class EvalDict:
1359 """
1359 """
1360 Emulate a dict which evaluates its contents in the caller's frame.
1360 Emulate a dict which evaluates its contents in the caller's frame.
1361
1361
1362 Usage:
1362 Usage:
1363 >>> number = 19
1363 >>> number = 19
1364
1364
1365 >>> text = "python"
1365 >>> text = "python"
1366
1366
1367 >>> print "%(text.capitalize())s %(number/9.0).1f rules!" % EvalDict()
1367 >>> print "%(text.capitalize())s %(number/9.0).1f rules!" % EvalDict()
1368 Python 2.1 rules!
1368 Python 2.1 rules!
1369 """
1369 """
1370
1370
1371 # This version is due to sismex01@hebmex.com on c.l.py, and is basically a
1371 # This version is due to sismex01@hebmex.com on c.l.py, and is basically a
1372 # modified (shorter) version of:
1372 # modified (shorter) version of:
1373 # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/66018 by
1373 # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/66018 by
1374 # Skip Montanaro (skip@pobox.com).
1374 # Skip Montanaro (skip@pobox.com).
1375
1375
1376 def __getitem__(self, name):
1376 def __getitem__(self, name):
1377 frame = sys._getframe(1)
1377 frame = sys._getframe(1)
1378 return eval(name, frame.f_globals, frame.f_locals)
1378 return eval(name, frame.f_globals, frame.f_locals)
1379
1379
1380 EvalString = EvalDict # for backwards compatibility
1380 EvalString = EvalDict # for backwards compatibility
1381 #----------------------------------------------------------------------------
1381 #----------------------------------------------------------------------------
1382 def qw(words,flat=0,sep=None,maxsplit=-1):
1382 def qw(words,flat=0,sep=None,maxsplit=-1):
1383 """Similar to Perl's qw() operator, but with some more options.
1383 """Similar to Perl's qw() operator, but with some more options.
1384
1384
1385 qw(words,flat=0,sep=' ',maxsplit=-1) -> words.split(sep,maxsplit)
1385 qw(words,flat=0,sep=' ',maxsplit=-1) -> words.split(sep,maxsplit)
1386
1386
1387 words can also be a list itself, and with flat=1, the output will be
1387 words can also be a list itself, and with flat=1, the output will be
1388 recursively flattened.
1388 recursively flattened.
1389
1389
1390 Examples:
1390 Examples:
1391
1391
1392 >>> qw('1 2')
1392 >>> qw('1 2')
1393 ['1', '2']
1393 ['1', '2']
1394
1394
1395 >>> qw(['a b','1 2',['m n','p q']])
1395 >>> qw(['a b','1 2',['m n','p q']])
1396 [['a', 'b'], ['1', '2'], [['m', 'n'], ['p', 'q']]]
1396 [['a', 'b'], ['1', '2'], [['m', 'n'], ['p', 'q']]]
1397
1397
1398 >>> qw(['a b','1 2',['m n','p q']],flat=1)
1398 >>> qw(['a b','1 2',['m n','p q']],flat=1)
1399 ['a', 'b', '1', '2', 'm', 'n', 'p', 'q']
1399 ['a', 'b', '1', '2', 'm', 'n', 'p', 'q']
1400 """
1400 """
1401
1401
1402 if type(words) in StringTypes:
1402 if type(words) in StringTypes:
1403 return [word.strip() for word in words.split(sep,maxsplit)
1403 return [word.strip() for word in words.split(sep,maxsplit)
1404 if word and not word.isspace() ]
1404 if word and not word.isspace() ]
1405 if flat:
1405 if flat:
1406 return flatten(map(qw,words,[1]*len(words)))
1406 return flatten(map(qw,words,[1]*len(words)))
1407 return map(qw,words)
1407 return map(qw,words)
1408
1408
1409 #----------------------------------------------------------------------------
1409 #----------------------------------------------------------------------------
1410 def qwflat(words,sep=None,maxsplit=-1):
1410 def qwflat(words,sep=None,maxsplit=-1):
1411 """Calls qw(words) in flat mode. It's just a convenient shorthand."""
1411 """Calls qw(words) in flat mode. It's just a convenient shorthand."""
1412 return qw(words,1,sep,maxsplit)
1412 return qw(words,1,sep,maxsplit)
1413
1413
1414 #----------------------------------------------------------------------------
1414 #----------------------------------------------------------------------------
1415 def qw_lol(indata):
1415 def qw_lol(indata):
1416 """qw_lol('a b') -> [['a','b']],
1416 """qw_lol('a b') -> [['a','b']],
1417 otherwise it's just a call to qw().
1417 otherwise it's just a call to qw().
1418
1418
1419 We need this to make sure the modules_some keys *always* end up as a
1419 We need this to make sure the modules_some keys *always* end up as a
1420 list of lists."""
1420 list of lists."""
1421
1421
1422 if type(indata) in StringTypes:
1422 if type(indata) in StringTypes:
1423 return [qw(indata)]
1423 return [qw(indata)]
1424 else:
1424 else:
1425 return qw(indata)
1425 return qw(indata)
1426
1426
1427 #-----------------------------------------------------------------------------
1427 #-----------------------------------------------------------------------------
1428 def list_strings(arg):
1428 def list_strings(arg):
1429 """Always return a list of strings, given a string or list of strings
1429 """Always return a list of strings, given a string or list of strings
1430 as input."""
1430 as input."""
1431
1431
1432 if type(arg) in StringTypes: return [arg]
1432 if type(arg) in StringTypes: return [arg]
1433 else: return arg
1433 else: return arg
1434
1434
1435 #----------------------------------------------------------------------------
1435 #----------------------------------------------------------------------------
1436 def grep(pat,list,case=1):
1436 def grep(pat,list,case=1):
1437 """Simple minded grep-like function.
1437 """Simple minded grep-like function.
1438 grep(pat,list) returns occurrences of pat in list, None on failure.
1438 grep(pat,list) returns occurrences of pat in list, None on failure.
1439
1439
1440 It only does simple string matching, with no support for regexps. Use the
1440 It only does simple string matching, with no support for regexps. Use the
1441 option case=0 for case-insensitive matching."""
1441 option case=0 for case-insensitive matching."""
1442
1442
1443 # This is pretty crude. At least it should implement copying only references
1443 # This is pretty crude. At least it should implement copying only references
1444 # to the original data in case it's big. Now it copies the data for output.
1444 # to the original data in case it's big. Now it copies the data for output.
1445 out=[]
1445 out=[]
1446 if case:
1446 if case:
1447 for term in list:
1447 for term in list:
1448 if term.find(pat)>-1: out.append(term)
1448 if term.find(pat)>-1: out.append(term)
1449 else:
1449 else:
1450 lpat=pat.lower()
1450 lpat=pat.lower()
1451 for term in list:
1451 for term in list:
1452 if term.lower().find(lpat)>-1: out.append(term)
1452 if term.lower().find(lpat)>-1: out.append(term)
1453
1453
1454 if len(out): return out
1454 if len(out): return out
1455 else: return None
1455 else: return None
1456
1456
1457 #----------------------------------------------------------------------------
1457 #----------------------------------------------------------------------------
1458 def dgrep(pat,*opts):
1458 def dgrep(pat,*opts):
1459 """Return grep() on dir()+dir(__builtins__).
1459 """Return grep() on dir()+dir(__builtins__).
1460
1460
1461 A very common use of grep() when working interactively."""
1461 A very common use of grep() when working interactively."""
1462
1462
1463 return grep(pat,dir(__main__)+dir(__main__.__builtins__),*opts)
1463 return grep(pat,dir(__main__)+dir(__main__.__builtins__),*opts)
1464
1464
1465 #----------------------------------------------------------------------------
1465 #----------------------------------------------------------------------------
1466 def idgrep(pat):
1466 def idgrep(pat):
1467 """Case-insensitive dgrep()"""
1467 """Case-insensitive dgrep()"""
1468
1468
1469 return dgrep(pat,0)
1469 return dgrep(pat,0)
1470
1470
1471 #----------------------------------------------------------------------------
1471 #----------------------------------------------------------------------------
1472 def igrep(pat,list):
1472 def igrep(pat,list):
1473 """Synonym for case-insensitive grep."""
1473 """Synonym for case-insensitive grep."""
1474
1474
1475 return grep(pat,list,case=0)
1475 return grep(pat,list,case=0)
1476
1476
1477 #----------------------------------------------------------------------------
1477 #----------------------------------------------------------------------------
1478 def indent(str,nspaces=4,ntabs=0):
1478 def indent(str,nspaces=4,ntabs=0):
1479 """Indent a string a given number of spaces or tabstops.
1479 """Indent a string a given number of spaces or tabstops.
1480
1480
1481 indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.
1481 indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.
1482 """
1482 """
1483 if str is None:
1483 if str is None:
1484 return
1484 return
1485 ind = '\t'*ntabs+' '*nspaces
1485 ind = '\t'*ntabs+' '*nspaces
1486 outstr = '%s%s' % (ind,str.replace(os.linesep,os.linesep+ind))
1486 outstr = '%s%s' % (ind,str.replace(os.linesep,os.linesep+ind))
1487 if outstr.endswith(os.linesep+ind):
1487 if outstr.endswith(os.linesep+ind):
1488 return outstr[:-len(ind)]
1488 return outstr[:-len(ind)]
1489 else:
1489 else:
1490 return outstr
1490 return outstr
1491
1491
1492 #-----------------------------------------------------------------------------
1492 #-----------------------------------------------------------------------------
1493 def native_line_ends(filename,backup=1):
1493 def native_line_ends(filename,backup=1):
1494 """Convert (in-place) a file to line-ends native to the current OS.
1494 """Convert (in-place) a file to line-ends native to the current OS.
1495
1495
1496 If the optional backup argument is given as false, no backup of the
1496 If the optional backup argument is given as false, no backup of the
1497 original file is left. """
1497 original file is left. """
1498
1498
1499 backup_suffixes = {'posix':'~','dos':'.bak','nt':'.bak','mac':'.bak'}
1499 backup_suffixes = {'posix':'~','dos':'.bak','nt':'.bak','mac':'.bak'}
1500
1500
1501 bak_filename = filename + backup_suffixes[os.name]
1501 bak_filename = filename + backup_suffixes[os.name]
1502
1502
1503 original = open(filename).read()
1503 original = open(filename).read()
1504 shutil.copy2(filename,bak_filename)
1504 shutil.copy2(filename,bak_filename)
1505 try:
1505 try:
1506 new = open(filename,'wb')
1506 new = open(filename,'wb')
1507 new.write(os.linesep.join(original.splitlines()))
1507 new.write(os.linesep.join(original.splitlines()))
1508 new.write(os.linesep) # ALWAYS put an eol at the end of the file
1508 new.write(os.linesep) # ALWAYS put an eol at the end of the file
1509 new.close()
1509 new.close()
1510 except:
1510 except:
1511 os.rename(bak_filename,filename)
1511 os.rename(bak_filename,filename)
1512 if not backup:
1512 if not backup:
1513 try:
1513 try:
1514 os.remove(bak_filename)
1514 os.remove(bak_filename)
1515 except:
1515 except:
1516 pass
1516 pass
1517
1517
1518 #----------------------------------------------------------------------------
1518 #----------------------------------------------------------------------------
1519 def get_pager_cmd(pager_cmd = None):
1519 def get_pager_cmd(pager_cmd = None):
1520 """Return a pager command.
1520 """Return a pager command.
1521
1521
1522 Makes some attempts at finding an OS-correct one."""
1522 Makes some attempts at finding an OS-correct one."""
1523
1523
1524 if os.name == 'posix':
1524 if os.name == 'posix':
1525 default_pager_cmd = 'less -r' # -r for color control sequences
1525 default_pager_cmd = 'less -r' # -r for color control sequences
1526 elif os.name in ['nt','dos']:
1526 elif os.name in ['nt','dos']:
1527 default_pager_cmd = 'type'
1527 default_pager_cmd = 'type'
1528
1528
1529 if pager_cmd is None:
1529 if pager_cmd is None:
1530 try:
1530 try:
1531 pager_cmd = os.environ['PAGER']
1531 pager_cmd = os.environ['PAGER']
1532 except:
1532 except:
1533 pager_cmd = default_pager_cmd
1533 pager_cmd = default_pager_cmd
1534 return pager_cmd
1534 return pager_cmd
1535
1535
1536 #-----------------------------------------------------------------------------
1536 #-----------------------------------------------------------------------------
1537 def get_pager_start(pager,start):
1537 def get_pager_start(pager,start):
1538 """Return the string for paging files with an offset.
1538 """Return the string for paging files with an offset.
1539
1539
1540 This is the '+N' argument which less and more (under Unix) accept.
1540 This is the '+N' argument which less and more (under Unix) accept.
1541 """
1541 """
1542
1542
1543 if pager in ['less','more']:
1543 if pager in ['less','more']:
1544 if start:
1544 if start:
1545 start_string = '+' + str(start)
1545 start_string = '+' + str(start)
1546 else:
1546 else:
1547 start_string = ''
1547 start_string = ''
1548 else:
1548 else:
1549 start_string = ''
1549 start_string = ''
1550 return start_string
1550 return start_string
1551
1551
1552 #----------------------------------------------------------------------------
1552 #----------------------------------------------------------------------------
1553 # (X)emacs on W32 doesn't like to be bypassed with msvcrt.getch()
1553 # (X)emacs on W32 doesn't like to be bypassed with msvcrt.getch()
1554 if os.name == 'nt' and os.environ.get('TERM','dumb') != 'emacs':
1554 if os.name == 'nt' and os.environ.get('TERM','dumb') != 'emacs':
1555 import msvcrt
1555 import msvcrt
1556 def page_more():
1556 def page_more():
1557 """ Smart pausing between pages
1557 """ Smart pausing between pages
1558
1558
1559 @return: True if need print more lines, False if quit
1559 @return: True if need print more lines, False if quit
1560 """
1560 """
1561 Term.cout.write('---Return to continue, q to quit--- ')
1561 Term.cout.write('---Return to continue, q to quit--- ')
1562 ans = msvcrt.getch()
1562 ans = msvcrt.getch()
1563 if ans in ("q", "Q"):
1563 if ans in ("q", "Q"):
1564 result = False
1564 result = False
1565 else:
1565 else:
1566 result = True
1566 result = True
1567 Term.cout.write("\b"*37 + " "*37 + "\b"*37)
1567 Term.cout.write("\b"*37 + " "*37 + "\b"*37)
1568 return result
1568 return result
1569 else:
1569 else:
1570 def page_more():
1570 def page_more():
1571 ans = raw_input('---Return to continue, q to quit--- ')
1571 ans = raw_input('---Return to continue, q to quit--- ')
1572 if ans.lower().startswith('q'):
1572 if ans.lower().startswith('q'):
1573 return False
1573 return False
1574 else:
1574 else:
1575 return True
1575 return True
1576
1576
1577 esc_re = re.compile(r"(\x1b[^m]+m)")
1577 esc_re = re.compile(r"(\x1b[^m]+m)")
1578
1578
1579 def page_dumb(strng,start=0,screen_lines=25):
1579 def page_dumb(strng,start=0,screen_lines=25):
1580 """Very dumb 'pager' in Python, for when nothing else works.
1580 """Very dumb 'pager' in Python, for when nothing else works.
1581
1581
1582 Only moves forward, same interface as page(), except for pager_cmd and
1582 Only moves forward, same interface as page(), except for pager_cmd and
1583 mode."""
1583 mode."""
1584
1584
1585 out_ln = strng.splitlines()[start:]
1585 out_ln = strng.splitlines()[start:]
1586 screens = chop(out_ln,screen_lines-1)
1586 screens = chop(out_ln,screen_lines-1)
1587 if len(screens) == 1:
1587 if len(screens) == 1:
1588 print >>Term.cout, os.linesep.join(screens[0])
1588 print >>Term.cout, os.linesep.join(screens[0])
1589 else:
1589 else:
1590 last_escape = ""
1590 last_escape = ""
1591 for scr in screens[0:-1]:
1591 for scr in screens[0:-1]:
1592 hunk = os.linesep.join(scr)
1592 hunk = os.linesep.join(scr)
1593 print >>Term.cout, last_escape + hunk
1593 print >>Term.cout, last_escape + hunk
1594 if not page_more():
1594 if not page_more():
1595 return
1595 return
1596 esc_list = esc_re.findall(hunk)
1596 esc_list = esc_re.findall(hunk)
1597 if len(esc_list) > 0:
1597 if len(esc_list) > 0:
1598 last_escape = esc_list[-1]
1598 last_escape = esc_list[-1]
1599 print >>Term.cout, last_escape + os.linesep.join(screens[-1])
1599 print >>Term.cout, last_escape + os.linesep.join(screens[-1])
1600
1600
1601 #----------------------------------------------------------------------------
1601 #----------------------------------------------------------------------------
1602 def page(strng,start=0,screen_lines=0,pager_cmd = None):
1602 def page(strng,start=0,screen_lines=0,pager_cmd = None):
1603 """Print a string, piping through a pager after a certain length.
1603 """Print a string, piping through a pager after a certain length.
1604
1604
1605 The screen_lines parameter specifies the number of *usable* lines of your
1605 The screen_lines parameter specifies the number of *usable* lines of your
1606 terminal screen (total lines minus lines you need to reserve to show other
1606 terminal screen (total lines minus lines you need to reserve to show other
1607 information).
1607 information).
1608
1608
1609 If you set screen_lines to a number <=0, page() will try to auto-determine
1609 If you set screen_lines to a number <=0, page() will try to auto-determine
1610 your screen size and will only use up to (screen_size+screen_lines) for
1610 your screen size and will only use up to (screen_size+screen_lines) for
1611 printing, paging after that. That is, if you want auto-detection but need
1611 printing, paging after that. That is, if you want auto-detection but need
1612 to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
1612 to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
1613 auto-detection without any lines reserved simply use screen_lines = 0.
1613 auto-detection without any lines reserved simply use screen_lines = 0.
1614
1614
1615 If a string won't fit in the allowed lines, it is sent through the
1615 If a string won't fit in the allowed lines, it is sent through the
1616 specified pager command. If none given, look for PAGER in the environment,
1616 specified pager command. If none given, look for PAGER in the environment,
1617 and ultimately default to less.
1617 and ultimately default to less.
1618
1618
1619 If no system pager works, the string is sent through a 'dumb pager'
1619 If no system pager works, the string is sent through a 'dumb pager'
1620 written in python, very simplistic.
1620 written in python, very simplistic.
1621 """
1621 """
1622
1622
1623 # Some routines may auto-compute start offsets incorrectly and pass a
1623 # Some routines may auto-compute start offsets incorrectly and pass a
1624 # negative value. Offset to 0 for robustness.
1624 # negative value. Offset to 0 for robustness.
1625 start = max(0,start)
1625 start = max(0,start)
1626
1626
1627 # first, try the hook
1627 # first, try the hook
1628 ip = ipapi.get()
1628 ip = ipapi.get()
1629 if ip:
1629 if ip:
1630 try:
1630 try:
1631 ip.IP.hooks.show_in_pager(strng)
1631 ip.IP.hooks.show_in_pager(strng)
1632 return
1632 return
1633 except ipapi.TryNext:
1633 except ipapi.TryNext:
1634 pass
1634 pass
1635
1635
1636 # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
1636 # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
1637 TERM = os.environ.get('TERM','dumb')
1637 TERM = os.environ.get('TERM','dumb')
1638 if TERM in ['dumb','emacs'] and os.name != 'nt':
1638 if TERM in ['dumb','emacs'] and os.name != 'nt':
1639 print strng
1639 print strng
1640 return
1640 return
1641 # chop off the topmost part of the string we don't want to see
1641 # chop off the topmost part of the string we don't want to see
1642 str_lines = strng.split(os.linesep)[start:]
1642 str_lines = strng.split(os.linesep)[start:]
1643 str_toprint = os.linesep.join(str_lines)
1643 str_toprint = os.linesep.join(str_lines)
1644 num_newlines = len(str_lines)
1644 num_newlines = len(str_lines)
1645 len_str = len(str_toprint)
1645 len_str = len(str_toprint)
1646
1646
1647 # Dumb heuristics to guesstimate number of on-screen lines the string
1647 # Dumb heuristics to guesstimate number of on-screen lines the string
1648 # takes. Very basic, but good enough for docstrings in reasonable
1648 # takes. Very basic, but good enough for docstrings in reasonable
1649 # terminals. If someone later feels like refining it, it's not hard.
1649 # terminals. If someone later feels like refining it, it's not hard.
1650 numlines = max(num_newlines,int(len_str/80)+1)
1650 numlines = max(num_newlines,int(len_str/80)+1)
1651
1651
1652 if os.name == "nt":
1652 if os.name == "nt":
1653 screen_lines_def = get_console_size(defaulty=25)[1]
1653 screen_lines_def = get_console_size(defaulty=25)[1]
1654 else:
1654 else:
1655 screen_lines_def = 25 # default value if we can't auto-determine
1655 screen_lines_def = 25 # default value if we can't auto-determine
1656
1656
1657 # auto-determine screen size
1657 # auto-determine screen size
1658 if screen_lines <= 0:
1658 if screen_lines <= 0:
1659 if TERM=='xterm':
1659 if TERM=='xterm':
1660 use_curses = USE_CURSES
1660 use_curses = USE_CURSES
1661 else:
1661 else:
1662 # curses causes problems on many terminals other than xterm.
1662 # curses causes problems on many terminals other than xterm.
1663 use_curses = False
1663 use_curses = False
1664 if use_curses:
1664 if use_curses:
1665 # There is a bug in curses, where *sometimes* it fails to properly
1665 # There is a bug in curses, where *sometimes* it fails to properly
1666 # initialize, and then after the endwin() call is made, the
1666 # initialize, and then after the endwin() call is made, the
1667 # terminal is left in an unusable state. Rather than trying to
1667 # terminal is left in an unusable state. Rather than trying to
1668 # check everytime for this (by requesting and comparing termios
1668 # check everytime for this (by requesting and comparing termios
1669 # flags each time), we just save the initial terminal state and
1669 # flags each time), we just save the initial terminal state and
1670 # unconditionally reset it every time. It's cheaper than making
1670 # unconditionally reset it every time. It's cheaper than making
1671 # the checks.
1671 # the checks.
1672 term_flags = termios.tcgetattr(sys.stdout)
1672 term_flags = termios.tcgetattr(sys.stdout)
1673 scr = curses.initscr()
1673 scr = curses.initscr()
1674 screen_lines_real,screen_cols = scr.getmaxyx()
1674 screen_lines_real,screen_cols = scr.getmaxyx()
1675 curses.endwin()
1675 curses.endwin()
1676 # Restore terminal state in case endwin() didn't.
1676 # Restore terminal state in case endwin() didn't.
1677 termios.tcsetattr(sys.stdout,termios.TCSANOW,term_flags)
1677 termios.tcsetattr(sys.stdout,termios.TCSANOW,term_flags)
1678 # Now we have what we needed: the screen size in rows/columns
1678 # Now we have what we needed: the screen size in rows/columns
1679 screen_lines += screen_lines_real
1679 screen_lines += screen_lines_real
1680 #print '***Screen size:',screen_lines_real,'lines x',\
1680 #print '***Screen size:',screen_lines_real,'lines x',\
1681 #screen_cols,'columns.' # dbg
1681 #screen_cols,'columns.' # dbg
1682 else:
1682 else:
1683 screen_lines += screen_lines_def
1683 screen_lines += screen_lines_def
1684
1684
1685 #print 'numlines',numlines,'screenlines',screen_lines # dbg
1685 #print 'numlines',numlines,'screenlines',screen_lines # dbg
1686 if numlines <= screen_lines :
1686 if numlines <= screen_lines :
1687 #print '*** normal print' # dbg
1687 #print '*** normal print' # dbg
1688 print >>Term.cout, str_toprint
1688 print >>Term.cout, str_toprint
1689 else:
1689 else:
1690 # Try to open pager and default to internal one if that fails.
1690 # Try to open pager and default to internal one if that fails.
1691 # All failure modes are tagged as 'retval=1', to match the return
1691 # All failure modes are tagged as 'retval=1', to match the return
1692 # value of a failed system command. If any intermediate attempt
1692 # value of a failed system command. If any intermediate attempt
1693 # sets retval to 1, at the end we resort to our own page_dumb() pager.
1693 # sets retval to 1, at the end we resort to our own page_dumb() pager.
1694 pager_cmd = get_pager_cmd(pager_cmd)
1694 pager_cmd = get_pager_cmd(pager_cmd)
1695 pager_cmd += ' ' + get_pager_start(pager_cmd,start)
1695 pager_cmd += ' ' + get_pager_start(pager_cmd,start)
1696 if os.name == 'nt':
1696 if os.name == 'nt':
1697 if pager_cmd.startswith('type'):
1697 if pager_cmd.startswith('type'):
1698 # The default WinXP 'type' command is failing on complex strings.
1698 # The default WinXP 'type' command is failing on complex strings.
1699 retval = 1
1699 retval = 1
1700 else:
1700 else:
1701 tmpname = tempfile.mktemp('.txt')
1701 tmpname = tempfile.mktemp('.txt')
1702 tmpfile = file(tmpname,'wt')
1702 tmpfile = file(tmpname,'wt')
1703 tmpfile.write(strng)
1703 tmpfile.write(strng)
1704 tmpfile.close()
1704 tmpfile.close()
1705 cmd = "%s < %s" % (pager_cmd,tmpname)
1705 cmd = "%s < %s" % (pager_cmd,tmpname)
1706 if os.system(cmd):
1706 if os.system(cmd):
1707 retval = 1
1707 retval = 1
1708 else:
1708 else:
1709 retval = None
1709 retval = None
1710 os.remove(tmpname)
1710 os.remove(tmpname)
1711 else:
1711 else:
1712 try:
1712 try:
1713 retval = None
1713 retval = None
1714 # if I use popen4, things hang. No idea why.
1714 # if I use popen4, things hang. No idea why.
1715 #pager,shell_out = os.popen4(pager_cmd)
1715 #pager,shell_out = os.popen4(pager_cmd)
1716 pager = os.popen(pager_cmd,'w')
1716 pager = os.popen(pager_cmd,'w')
1717 pager.write(strng)
1717 pager.write(strng)
1718 pager.close()
1718 pager.close()
1719 retval = pager.close() # success returns None
1719 retval = pager.close() # success returns None
1720 except IOError,msg: # broken pipe when user quits
1720 except IOError,msg: # broken pipe when user quits
1721 if msg.args == (32,'Broken pipe'):
1721 if msg.args == (32,'Broken pipe'):
1722 retval = None
1722 retval = None
1723 else:
1723 else:
1724 retval = 1
1724 retval = 1
1725 except OSError:
1725 except OSError:
1726 # Other strange problems, sometimes seen in Win2k/cygwin
1726 # Other strange problems, sometimes seen in Win2k/cygwin
1727 retval = 1
1727 retval = 1
1728 if retval is not None:
1728 if retval is not None:
1729 page_dumb(strng,screen_lines=screen_lines)
1729 page_dumb(strng,screen_lines=screen_lines)
1730
1730
1731 #----------------------------------------------------------------------------
1731 #----------------------------------------------------------------------------
1732 def page_file(fname,start = 0, pager_cmd = None):
1732 def page_file(fname,start = 0, pager_cmd = None):
1733 """Page a file, using an optional pager command and starting line.
1733 """Page a file, using an optional pager command and starting line.
1734 """
1734 """
1735
1735
1736 pager_cmd = get_pager_cmd(pager_cmd)
1736 pager_cmd = get_pager_cmd(pager_cmd)
1737 pager_cmd += ' ' + get_pager_start(pager_cmd,start)
1737 pager_cmd += ' ' + get_pager_start(pager_cmd,start)
1738
1738
1739 try:
1739 try:
1740 if os.environ['TERM'] in ['emacs','dumb']:
1740 if os.environ['TERM'] in ['emacs','dumb']:
1741 raise EnvironmentError
1741 raise EnvironmentError
1742 xsys(pager_cmd + ' ' + fname)
1742 xsys(pager_cmd + ' ' + fname)
1743 except:
1743 except:
1744 try:
1744 try:
1745 if start > 0:
1745 if start > 0:
1746 start -= 1
1746 start -= 1
1747 page(open(fname).read(),start)
1747 page(open(fname).read(),start)
1748 except:
1748 except:
1749 print 'Unable to show file',`fname`
1749 print 'Unable to show file',`fname`
1750
1750
1751
1751
1752 #----------------------------------------------------------------------------
1752 #----------------------------------------------------------------------------
1753 def snip_print(str,width = 75,print_full = 0,header = ''):
1753 def snip_print(str,width = 75,print_full = 0,header = ''):
1754 """Print a string snipping the midsection to fit in width.
1754 """Print a string snipping the midsection to fit in width.
1755
1755
1756 print_full: mode control:
1756 print_full: mode control:
1757 - 0: only snip long strings
1757 - 0: only snip long strings
1758 - 1: send to page() directly.
1758 - 1: send to page() directly.
1759 - 2: snip long strings and ask for full length viewing with page()
1759 - 2: snip long strings and ask for full length viewing with page()
1760 Return 1 if snipping was necessary, 0 otherwise."""
1760 Return 1 if snipping was necessary, 0 otherwise."""
1761
1761
1762 if print_full == 1:
1762 if print_full == 1:
1763 page(header+str)
1763 page(header+str)
1764 return 0
1764 return 0
1765
1765
1766 print header,
1766 print header,
1767 if len(str) < width:
1767 if len(str) < width:
1768 print str
1768 print str
1769 snip = 0
1769 snip = 0
1770 else:
1770 else:
1771 whalf = int((width -5)/2)
1771 whalf = int((width -5)/2)
1772 print str[:whalf] + ' <...> ' + str[-whalf:]
1772 print str[:whalf] + ' <...> ' + str[-whalf:]
1773 snip = 1
1773 snip = 1
1774 if snip and print_full == 2:
1774 if snip and print_full == 2:
1775 if raw_input(header+' Snipped. View (y/n)? [N]').lower() == 'y':
1775 if raw_input(header+' Snipped. View (y/n)? [N]').lower() == 'y':
1776 page(str)
1776 page(str)
1777 return snip
1777 return snip
1778
1778
1779 #****************************************************************************
1779 #****************************************************************************
1780 # lists, dicts and structures
1780 # lists, dicts and structures
1781
1781
1782 def belong(candidates,checklist):
1782 def belong(candidates,checklist):
1783 """Check whether a list of items appear in a given list of options.
1783 """Check whether a list of items appear in a given list of options.
1784
1784
1785 Returns a list of 1 and 0, one for each candidate given."""
1785 Returns a list of 1 and 0, one for each candidate given."""
1786
1786
1787 return [x in checklist for x in candidates]
1787 return [x in checklist for x in candidates]
1788
1788
1789 #----------------------------------------------------------------------------
1789 #----------------------------------------------------------------------------
1790 def uniq_stable(elems):
1790 def uniq_stable(elems):
1791 """uniq_stable(elems) -> list
1791 """uniq_stable(elems) -> list
1792
1792
1793 Return from an iterable, a list of all the unique elements in the input,
1793 Return from an iterable, a list of all the unique elements in the input,
1794 but maintaining the order in which they first appear.
1794 but maintaining the order in which they first appear.
1795
1795
1796 A naive solution to this problem which just makes a dictionary with the
1796 A naive solution to this problem which just makes a dictionary with the
1797 elements as keys fails to respect the stability condition, since
1797 elements as keys fails to respect the stability condition, since
1798 dictionaries are unsorted by nature.
1798 dictionaries are unsorted by nature.
1799
1799
1800 Note: All elements in the input must be valid dictionary keys for this
1800 Note: All elements in the input must be valid dictionary keys for this
1801 routine to work, as it internally uses a dictionary for efficiency
1801 routine to work, as it internally uses a dictionary for efficiency
1802 reasons."""
1802 reasons."""
1803
1803
1804 unique = []
1804 unique = []
1805 unique_dict = {}
1805 unique_dict = {}
1806 for nn in elems:
1806 for nn in elems:
1807 if nn not in unique_dict:
1807 if nn not in unique_dict:
1808 unique.append(nn)
1808 unique.append(nn)
1809 unique_dict[nn] = None
1809 unique_dict[nn] = None
1810 return unique
1810 return unique
1811
1811
1812 #----------------------------------------------------------------------------
1812 #----------------------------------------------------------------------------
1813 class NLprinter:
1813 class NLprinter:
1814 """Print an arbitrarily nested list, indicating index numbers.
1814 """Print an arbitrarily nested list, indicating index numbers.
1815
1815
1816 An instance of this class called nlprint is available and callable as a
1816 An instance of this class called nlprint is available and callable as a
1817 function.
1817 function.
1818
1818
1819 nlprint(list,indent=' ',sep=': ') -> prints indenting each level by 'indent'
1819 nlprint(list,indent=' ',sep=': ') -> prints indenting each level by 'indent'
1820 and using 'sep' to separate the index from the value. """
1820 and using 'sep' to separate the index from the value. """
1821
1821
1822 def __init__(self):
1822 def __init__(self):
1823 self.depth = 0
1823 self.depth = 0
1824
1824
1825 def __call__(self,lst,pos='',**kw):
1825 def __call__(self,lst,pos='',**kw):
1826 """Prints the nested list numbering levels."""
1826 """Prints the nested list numbering levels."""
1827 kw.setdefault('indent',' ')
1827 kw.setdefault('indent',' ')
1828 kw.setdefault('sep',': ')
1828 kw.setdefault('sep',': ')
1829 kw.setdefault('start',0)
1829 kw.setdefault('start',0)
1830 kw.setdefault('stop',len(lst))
1830 kw.setdefault('stop',len(lst))
1831 # we need to remove start and stop from kw so they don't propagate
1831 # we need to remove start and stop from kw so they don't propagate
1832 # into a recursive call for a nested list.
1832 # into a recursive call for a nested list.
1833 start = kw['start']; del kw['start']
1833 start = kw['start']; del kw['start']
1834 stop = kw['stop']; del kw['stop']
1834 stop = kw['stop']; del kw['stop']
1835 if self.depth == 0 and 'header' in kw.keys():
1835 if self.depth == 0 and 'header' in kw.keys():
1836 print kw['header']
1836 print kw['header']
1837
1837
1838 for idx in range(start,stop):
1838 for idx in range(start,stop):
1839 elem = lst[idx]
1839 elem = lst[idx]
1840 if type(elem)==type([]):
1840 if type(elem)==type([]):
1841 self.depth += 1
1841 self.depth += 1
1842 self.__call__(elem,itpl('$pos$idx,'),**kw)
1842 self.__call__(elem,itpl('$pos$idx,'),**kw)
1843 self.depth -= 1
1843 self.depth -= 1
1844 else:
1844 else:
1845 printpl(kw['indent']*self.depth+'$pos$idx$kw["sep"]$elem')
1845 printpl(kw['indent']*self.depth+'$pos$idx$kw["sep"]$elem')
1846
1846
1847 nlprint = NLprinter()
1847 nlprint = NLprinter()
1848 #----------------------------------------------------------------------------
1848 #----------------------------------------------------------------------------
1849 def all_belong(candidates,checklist):
1849 def all_belong(candidates,checklist):
1850 """Check whether a list of items ALL appear in a given list of options.
1850 """Check whether a list of items ALL appear in a given list of options.
1851
1851
1852 Returns a single 1 or 0 value."""
1852 Returns a single 1 or 0 value."""
1853
1853
1854 return 1-(0 in [x in checklist for x in candidates])
1854 return 1-(0 in [x in checklist for x in candidates])
1855
1855
1856 #----------------------------------------------------------------------------
1856 #----------------------------------------------------------------------------
1857 def sort_compare(lst1,lst2,inplace = 1):
1857 def sort_compare(lst1,lst2,inplace = 1):
1858 """Sort and compare two lists.
1858 """Sort and compare two lists.
1859
1859
1860 By default it does it in place, thus modifying the lists. Use inplace = 0
1860 By default it does it in place, thus modifying the lists. Use inplace = 0
1861 to avoid that (at the cost of temporary copy creation)."""
1861 to avoid that (at the cost of temporary copy creation)."""
1862 if not inplace:
1862 if not inplace:
1863 lst1 = lst1[:]
1863 lst1 = lst1[:]
1864 lst2 = lst2[:]
1864 lst2 = lst2[:]
1865 lst1.sort(); lst2.sort()
1865 lst1.sort(); lst2.sort()
1866 return lst1 == lst2
1866 return lst1 == lst2
1867
1867
1868 #----------------------------------------------------------------------------
1868 #----------------------------------------------------------------------------
1869 def list2dict(lst):
1869 def list2dict(lst):
1870 """Takes a list of (key,value) pairs and turns it into a dict."""
1870 """Takes a list of (key,value) pairs and turns it into a dict."""
1871
1871
1872 dic = {}
1872 dic = {}
1873 for k,v in lst: dic[k] = v
1873 for k,v in lst: dic[k] = v
1874 return dic
1874 return dic
1875
1875
1876 #----------------------------------------------------------------------------
1876 #----------------------------------------------------------------------------
1877 def list2dict2(lst,default=''):
1877 def list2dict2(lst,default=''):
1878 """Takes a list and turns it into a dict.
1878 """Takes a list and turns it into a dict.
1879 Much slower than list2dict, but more versatile. This version can take
1879 Much slower than list2dict, but more versatile. This version can take
1880 lists with sublists of arbitrary length (including sclars)."""
1880 lists with sublists of arbitrary length (including sclars)."""
1881
1881
1882 dic = {}
1882 dic = {}
1883 for elem in lst:
1883 for elem in lst:
1884 if type(elem) in (types.ListType,types.TupleType):
1884 if type(elem) in (types.ListType,types.TupleType):
1885 size = len(elem)
1885 size = len(elem)
1886 if size == 0:
1886 if size == 0:
1887 pass
1887 pass
1888 elif size == 1:
1888 elif size == 1:
1889 dic[elem] = default
1889 dic[elem] = default
1890 else:
1890 else:
1891 k,v = elem[0], elem[1:]
1891 k,v = elem[0], elem[1:]
1892 if len(v) == 1: v = v[0]
1892 if len(v) == 1: v = v[0]
1893 dic[k] = v
1893 dic[k] = v
1894 else:
1894 else:
1895 dic[elem] = default
1895 dic[elem] = default
1896 return dic
1896 return dic
1897
1897
1898 #----------------------------------------------------------------------------
1898 #----------------------------------------------------------------------------
1899 def flatten(seq):
1899 def flatten(seq):
1900 """Flatten a list of lists (NOT recursive, only works for 2d lists)."""
1900 """Flatten a list of lists (NOT recursive, only works for 2d lists)."""
1901
1901
1902 return [x for subseq in seq for x in subseq]
1902 return [x for subseq in seq for x in subseq]
1903
1903
1904 #----------------------------------------------------------------------------
1904 #----------------------------------------------------------------------------
1905 def get_slice(seq,start=0,stop=None,step=1):
1905 def get_slice(seq,start=0,stop=None,step=1):
1906 """Get a slice of a sequence with variable step. Specify start,stop,step."""
1906 """Get a slice of a sequence with variable step. Specify start,stop,step."""
1907 if stop == None:
1907 if stop == None:
1908 stop = len(seq)
1908 stop = len(seq)
1909 item = lambda i: seq[i]
1909 item = lambda i: seq[i]
1910 return map(item,xrange(start,stop,step))
1910 return map(item,xrange(start,stop,step))
1911
1911
1912 #----------------------------------------------------------------------------
1912 #----------------------------------------------------------------------------
1913 def chop(seq,size):
1913 def chop(seq,size):
1914 """Chop a sequence into chunks of the given size."""
1914 """Chop a sequence into chunks of the given size."""
1915 chunk = lambda i: seq[i:i+size]
1915 chunk = lambda i: seq[i:i+size]
1916 return map(chunk,xrange(0,len(seq),size))
1916 return map(chunk,xrange(0,len(seq),size))
1917
1917
1918 #----------------------------------------------------------------------------
1918 #----------------------------------------------------------------------------
1919 # with is a keyword as of python 2.5, so this function is renamed to withobj
1919 # with is a keyword as of python 2.5, so this function is renamed to withobj
1920 # from its old 'with' name.
1920 # from its old 'with' name.
1921 def with_obj(object, **args):
1921 def with_obj(object, **args):
1922 """Set multiple attributes for an object, similar to Pascal's with.
1922 """Set multiple attributes for an object, similar to Pascal's with.
1923
1923
1924 Example:
1924 Example:
1925 with_obj(jim,
1925 with_obj(jim,
1926 born = 1960,
1926 born = 1960,
1927 haircolour = 'Brown',
1927 haircolour = 'Brown',
1928 eyecolour = 'Green')
1928 eyecolour = 'Green')
1929
1929
1930 Credit: Greg Ewing, in
1930 Credit: Greg Ewing, in
1931 http://mail.python.org/pipermail/python-list/2001-May/040703.html.
1931 http://mail.python.org/pipermail/python-list/2001-May/040703.html.
1932
1932
1933 NOTE: up until IPython 0.7.2, this was called simply 'with', but 'with'
1933 NOTE: up until IPython 0.7.2, this was called simply 'with', but 'with'
1934 has become a keyword for Python 2.5, so we had to rename it."""
1934 has become a keyword for Python 2.5, so we had to rename it."""
1935
1935
1936 object.__dict__.update(args)
1936 object.__dict__.update(args)
1937
1937
1938 #----------------------------------------------------------------------------
1938 #----------------------------------------------------------------------------
1939 def setattr_list(obj,alist,nspace = None):
1939 def setattr_list(obj,alist,nspace = None):
1940 """Set a list of attributes for an object taken from a namespace.
1940 """Set a list of attributes for an object taken from a namespace.
1941
1941
1942 setattr_list(obj,alist,nspace) -> sets in obj all the attributes listed in
1942 setattr_list(obj,alist,nspace) -> sets in obj all the attributes listed in
1943 alist with their values taken from nspace, which must be a dict (something
1943 alist with their values taken from nspace, which must be a dict (something
1944 like locals() will often do) If nspace isn't given, locals() of the
1944 like locals() will often do) If nspace isn't given, locals() of the
1945 *caller* is used, so in most cases you can omit it.
1945 *caller* is used, so in most cases you can omit it.
1946
1946
1947 Note that alist can be given as a string, which will be automatically
1947 Note that alist can be given as a string, which will be automatically
1948 split into a list on whitespace. If given as a list, it must be a list of
1948 split into a list on whitespace. If given as a list, it must be a list of
1949 *strings* (the variable names themselves), not of variables."""
1949 *strings* (the variable names themselves), not of variables."""
1950
1950
1951 # this grabs the local variables from the *previous* call frame -- that is
1951 # this grabs the local variables from the *previous* call frame -- that is
1952 # the locals from the function that called setattr_list().
1952 # the locals from the function that called setattr_list().
1953 # - snipped from weave.inline()
1953 # - snipped from weave.inline()
1954 if nspace is None:
1954 if nspace is None:
1955 call_frame = sys._getframe().f_back
1955 call_frame = sys._getframe().f_back
1956 nspace = call_frame.f_locals
1956 nspace = call_frame.f_locals
1957
1957
1958 if type(alist) in StringTypes:
1958 if type(alist) in StringTypes:
1959 alist = alist.split()
1959 alist = alist.split()
1960 for attr in alist:
1960 for attr in alist:
1961 val = eval(attr,nspace)
1961 val = eval(attr,nspace)
1962 setattr(obj,attr,val)
1962 setattr(obj,attr,val)
1963
1963
1964 #----------------------------------------------------------------------------
1964 #----------------------------------------------------------------------------
1965 def getattr_list(obj,alist,*args):
1965 def getattr_list(obj,alist,*args):
1966 """getattr_list(obj,alist[, default]) -> attribute list.
1966 """getattr_list(obj,alist[, default]) -> attribute list.
1967
1967
1968 Get a list of named attributes for an object. When a default argument is
1968 Get a list of named attributes for an object. When a default argument is
1969 given, it is returned when the attribute doesn't exist; without it, an
1969 given, it is returned when the attribute doesn't exist; without it, an
1970 exception is raised in that case.
1970 exception is raised in that case.
1971
1971
1972 Note that alist can be given as a string, which will be automatically
1972 Note that alist can be given as a string, which will be automatically
1973 split into a list on whitespace. If given as a list, it must be a list of
1973 split into a list on whitespace. If given as a list, it must be a list of
1974 *strings* (the variable names themselves), not of variables."""
1974 *strings* (the variable names themselves), not of variables."""
1975
1975
1976 if type(alist) in StringTypes:
1976 if type(alist) in StringTypes:
1977 alist = alist.split()
1977 alist = alist.split()
1978 if args:
1978 if args:
1979 if len(args)==1:
1979 if len(args)==1:
1980 default = args[0]
1980 default = args[0]
1981 return map(lambda attr: getattr(obj,attr,default),alist)
1981 return map(lambda attr: getattr(obj,attr,default),alist)
1982 else:
1982 else:
1983 raise ValueError,'getattr_list() takes only one optional argument'
1983 raise ValueError,'getattr_list() takes only one optional argument'
1984 else:
1984 else:
1985 return map(lambda attr: getattr(obj,attr),alist)
1985 return map(lambda attr: getattr(obj,attr),alist)
1986
1986
1987 #----------------------------------------------------------------------------
1987 #----------------------------------------------------------------------------
1988 def map_method(method,object_list,*argseq,**kw):
1988 def map_method(method,object_list,*argseq,**kw):
1989 """map_method(method,object_list,*args,**kw) -> list
1989 """map_method(method,object_list,*args,**kw) -> list
1990
1990
1991 Return a list of the results of applying the methods to the items of the
1991 Return a list of the results of applying the methods to the items of the
1992 argument sequence(s). If more than one sequence is given, the method is
1992 argument sequence(s). If more than one sequence is given, the method is
1993 called with an argument list consisting of the corresponding item of each
1993 called with an argument list consisting of the corresponding item of each
1994 sequence. All sequences must be of the same length.
1994 sequence. All sequences must be of the same length.
1995
1995
1996 Keyword arguments are passed verbatim to all objects called.
1996 Keyword arguments are passed verbatim to all objects called.
1997
1997
1998 This is Python code, so it's not nearly as fast as the builtin map()."""
1998 This is Python code, so it's not nearly as fast as the builtin map()."""
1999
1999
2000 out_list = []
2000 out_list = []
2001 idx = 0
2001 idx = 0
2002 for object in object_list:
2002 for object in object_list:
2003 try:
2003 try:
2004 handler = getattr(object, method)
2004 handler = getattr(object, method)
2005 except AttributeError:
2005 except AttributeError:
2006 out_list.append(None)
2006 out_list.append(None)
2007 else:
2007 else:
2008 if argseq:
2008 if argseq:
2009 args = map(lambda lst:lst[idx],argseq)
2009 args = map(lambda lst:lst[idx],argseq)
2010 #print 'ob',object,'hand',handler,'ar',args # dbg
2010 #print 'ob',object,'hand',handler,'ar',args # dbg
2011 out_list.append(handler(args,**kw))
2011 out_list.append(handler(args,**kw))
2012 else:
2012 else:
2013 out_list.append(handler(**kw))
2013 out_list.append(handler(**kw))
2014 idx += 1
2014 idx += 1
2015 return out_list
2015 return out_list
2016
2016
2017 #----------------------------------------------------------------------------
2017 #----------------------------------------------------------------------------
2018 def get_class_members(cls):
2018 def get_class_members(cls):
2019 ret = dir(cls)
2019 ret = dir(cls)
2020 if hasattr(cls,'__bases__'):
2020 if hasattr(cls,'__bases__'):
2021 for base in cls.__bases__:
2021 for base in cls.__bases__:
2022 ret.extend(get_class_members(base))
2022 ret.extend(get_class_members(base))
2023 return ret
2023 return ret
2024
2024
2025 #----------------------------------------------------------------------------
2025 #----------------------------------------------------------------------------
2026 def dir2(obj):
2026 def dir2(obj):
2027 """dir2(obj) -> list of strings
2027 """dir2(obj) -> list of strings
2028
2028
2029 Extended version of the Python builtin dir(), which does a few extra
2029 Extended version of the Python builtin dir(), which does a few extra
2030 checks, and supports common objects with unusual internals that confuse
2030 checks, and supports common objects with unusual internals that confuse
2031 dir(), such as Traits and PyCrust.
2031 dir(), such as Traits and PyCrust.
2032
2032
2033 This version is guaranteed to return only a list of true strings, whereas
2033 This version is guaranteed to return only a list of true strings, whereas
2034 dir() returns anything that objects inject into themselves, even if they
2034 dir() returns anything that objects inject into themselves, even if they
2035 are later not really valid for attribute access (many extension libraries
2035 are later not really valid for attribute access (many extension libraries
2036 have such bugs).
2036 have such bugs).
2037 """
2037 """
2038
2038
2039 # Start building the attribute list via dir(), and then complete it
2039 # Start building the attribute list via dir(), and then complete it
2040 # with a few extra special-purpose calls.
2040 # with a few extra special-purpose calls.
2041 words = dir(obj)
2041 words = dir(obj)
2042
2042
2043 if hasattr(obj,'__class__'):
2043 if hasattr(obj,'__class__'):
2044 words.append('__class__')
2044 words.append('__class__')
2045 words.extend(get_class_members(obj.__class__))
2045 words.extend(get_class_members(obj.__class__))
2046 #if '__base__' in words: 1/0
2046 #if '__base__' in words: 1/0
2047
2047
2048 # Some libraries (such as traits) may introduce duplicates, we want to
2048 # Some libraries (such as traits) may introduce duplicates, we want to
2049 # track and clean this up if it happens
2049 # track and clean this up if it happens
2050 may_have_dupes = False
2050 may_have_dupes = False
2051
2051
2052 # this is the 'dir' function for objects with Enthought's traits
2052 # this is the 'dir' function for objects with Enthought's traits
2053 if hasattr(obj, 'trait_names'):
2053 if hasattr(obj, 'trait_names'):
2054 try:
2054 try:
2055 words.extend(obj.trait_names())
2055 words.extend(obj.trait_names())
2056 may_have_dupes = True
2056 may_have_dupes = True
2057 except TypeError:
2057 except TypeError:
2058 # This will happen if `obj` is a class and not an instance.
2058 # This will happen if `obj` is a class and not an instance.
2059 pass
2059 pass
2060
2060
2061 # Support for PyCrust-style _getAttributeNames magic method.
2061 # Support for PyCrust-style _getAttributeNames magic method.
2062 if hasattr(obj, '_getAttributeNames'):
2062 if hasattr(obj, '_getAttributeNames'):
2063 try:
2063 try:
2064 words.extend(obj._getAttributeNames())
2064 words.extend(obj._getAttributeNames())
2065 may_have_dupes = True
2065 may_have_dupes = True
2066 except TypeError:
2066 except TypeError:
2067 # `obj` is a class and not an instance. Ignore
2067 # `obj` is a class and not an instance. Ignore
2068 # this error.
2068 # this error.
2069 pass
2069 pass
2070
2070
2071 if may_have_dupes:
2071 if may_have_dupes:
2072 # eliminate possible duplicates, as some traits may also
2072 # eliminate possible duplicates, as some traits may also
2073 # appear as normal attributes in the dir() call.
2073 # appear as normal attributes in the dir() call.
2074 words = list(set(words))
2074 words = list(set(words))
2075 words.sort()
2075 words.sort()
2076
2076
2077 # filter out non-string attributes which may be stuffed by dir() calls
2077 # filter out non-string attributes which may be stuffed by dir() calls
2078 # and poor coding in third-party modules
2078 # and poor coding in third-party modules
2079 return [w for w in words if isinstance(w, basestring)]
2079 return [w for w in words if isinstance(w, basestring)]
2080
2080
2081 #----------------------------------------------------------------------------
2081 #----------------------------------------------------------------------------
2082 def import_fail_info(mod_name,fns=None):
2082 def import_fail_info(mod_name,fns=None):
2083 """Inform load failure for a module."""
2083 """Inform load failure for a module."""
2084
2084
2085 if fns == None:
2085 if fns == None:
2086 warn("Loading of %s failed.\n" % (mod_name,))
2086 warn("Loading of %s failed.\n" % (mod_name,))
2087 else:
2087 else:
2088 warn("Loading of %s from %s failed.\n" % (fns,mod_name))
2088 warn("Loading of %s from %s failed.\n" % (fns,mod_name))
2089
2089
2090 #----------------------------------------------------------------------------
2090 #----------------------------------------------------------------------------
2091 # Proposed popitem() extension, written as a method
2091 # Proposed popitem() extension, written as a method
2092
2092
2093
2093
2094 class NotGiven: pass
2094 class NotGiven: pass
2095
2095
2096 def popkey(dct,key,default=NotGiven):
2096 def popkey(dct,key,default=NotGiven):
2097 """Return dct[key] and delete dct[key].
2097 """Return dct[key] and delete dct[key].
2098
2098
2099 If default is given, return it if dct[key] doesn't exist, otherwise raise
2099 If default is given, return it if dct[key] doesn't exist, otherwise raise
2100 KeyError. """
2100 KeyError. """
2101
2101
2102 try:
2102 try:
2103 val = dct[key]
2103 val = dct[key]
2104 except KeyError:
2104 except KeyError:
2105 if default is NotGiven:
2105 if default is NotGiven:
2106 raise
2106 raise
2107 else:
2107 else:
2108 return default
2108 return default
2109 else:
2109 else:
2110 del dct[key]
2110 del dct[key]
2111 return val
2111 return val
2112
2112
2113 def wrap_deprecated(func, suggest = '<nothing>'):
2113 def wrap_deprecated(func, suggest = '<nothing>'):
2114 def newFunc(*args, **kwargs):
2114 def newFunc(*args, **kwargs):
2115 warnings.warn("Call to deprecated function %s, use %s instead" %
2115 warnings.warn("Call to deprecated function %s, use %s instead" %
2116 ( func.__name__, suggest),
2116 ( func.__name__, suggest),
2117 category=DeprecationWarning,
2117 category=DeprecationWarning,
2118 stacklevel = 2)
2118 stacklevel = 2)
2119 return func(*args, **kwargs)
2119 return func(*args, **kwargs)
2120 return newFunc
2120 return newFunc
2121
2121
2122
2122
2123 def _num_cpus_unix():
2123 def _num_cpus_unix():
2124 """Return the number of active CPUs on a Unix system."""
2124 """Return the number of active CPUs on a Unix system."""
2125 return os.sysconf("SC_NPROCESSORS_ONLN")
2125 return os.sysconf("SC_NPROCESSORS_ONLN")
2126
2126
2127
2127
2128 def _num_cpus_darwin():
2128 def _num_cpus_darwin():
2129 """Return the number of active CPUs on a Darwin system."""
2129 """Return the number of active CPUs on a Darwin system."""
2130 p = subprocess.Popen(['sysctl','-n','hw.ncpu'],stdout=subprocess.PIPE)
2130 p = subprocess.Popen(['sysctl','-n','hw.ncpu'],stdout=subprocess.PIPE)
2131 return p.stdout.read()
2131 return p.stdout.read()
2132
2132
2133
2133
2134 def _num_cpus_windows():
2134 def _num_cpus_windows():
2135 """Return the number of active CPUs on a Windows system."""
2135 """Return the number of active CPUs on a Windows system."""
2136 return os.environ.get("NUMBER_OF_PROCESSORS")
2136 return os.environ.get("NUMBER_OF_PROCESSORS")
2137
2137
2138
2138
2139 def num_cpus():
2139 def num_cpus():
2140 """Return the effective number of CPUs in the system as an integer.
2140 """Return the effective number of CPUs in the system as an integer.
2141
2141
2142 This cross-platform function makes an attempt at finding the total number of
2142 This cross-platform function makes an attempt at finding the total number of
2143 available CPUs in the system, as returned by various underlying system and
2143 available CPUs in the system, as returned by various underlying system and
2144 python calls.
2144 python calls.
2145
2145
2146 If it can't find a sensible answer, it returns 1 (though an error *may* make
2146 If it can't find a sensible answer, it returns 1 (though an error *may* make
2147 it return a large positive number that's actually incorrect).
2147 it return a large positive number that's actually incorrect).
2148 """
2148 """
2149
2149
2150 # Many thanks to the Parallel Python project (http://www.parallelpython.com)
2150 # Many thanks to the Parallel Python project (http://www.parallelpython.com)
2151 # for the names of the keys we needed to look up for this function. This
2151 # for the names of the keys we needed to look up for this function. This
2152 # code was inspired by their equivalent function.
2152 # code was inspired by their equivalent function.
2153
2153
2154 ncpufuncs = {'Linux':_num_cpus_unix,
2154 ncpufuncs = {'Linux':_num_cpus_unix,
2155 'Darwin':_num_cpus_darwin,
2155 'Darwin':_num_cpus_darwin,
2156 'Windows':_num_cpus_windows,
2156 'Windows':_num_cpus_windows,
2157 # On Vista, python < 2.5.2 has a bug and returns 'Microsoft'
2157 # On Vista, python < 2.5.2 has a bug and returns 'Microsoft'
2158 # See http://bugs.python.org/issue1082 for details.
2158 # See http://bugs.python.org/issue1082 for details.
2159 'Microsoft':_num_cpus_windows,
2159 'Microsoft':_num_cpus_windows,
2160 }
2160 }
2161
2161
2162 ncpufunc = ncpufuncs.get(platform.system(),
2162 ncpufunc = ncpufuncs.get(platform.system(),
2163 # default to unix version (Solaris, AIX, etc)
2163 # default to unix version (Solaris, AIX, etc)
2164 _num_cpus_unix)
2164 _num_cpus_unix)
2165
2165
2166 try:
2166 try:
2167 ncpus = max(1,int(ncpufunc()))
2167 ncpus = max(1,int(ncpufunc()))
2168 except:
2168 except:
2169 ncpus = 1
2169 ncpus = 1
2170 return ncpus
2170 return ncpus
2171
2171
2172 #*************************** end of file <genutils.py> **********************
2172 #*************************** end of file <genutils.py> **********************
1 NO CONTENT: file renamed from IPython/platutils.py to IPython/utils/platutils.py
NO CONTENT: file renamed from IPython/platutils.py to IPython/utils/platutils.py
1 NO CONTENT: file renamed from IPython/platutils_dummy.py to IPython/utils/platutils_dummy.py
NO CONTENT: file renamed from IPython/platutils_dummy.py to IPython/utils/platutils_dummy.py
1 NO CONTENT: file renamed from IPython/platutils_posix.py to IPython/utils/platutils_posix.py
NO CONTENT: file renamed from IPython/platutils_posix.py to IPython/utils/platutils_posix.py
1 NO CONTENT: file renamed from IPython/platutils_win32.py to IPython/utils/platutils_win32.py
NO CONTENT: file renamed from IPython/platutils_win32.py to IPython/utils/platutils_win32.py
@@ -1,19 +1,21 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 # encoding: utf-8
2 # encoding: utf-8
3
3
4 def test_import_coloransi():
4 def test_import_coloransi():
5 from IPython.utils import coloransi
5 from IPython.utils import coloransi
6
6
7 def test_import_DPyGetOpt():
7 def test_import_DPyGetOpt():
8 from IPython.utils import DPyGetOpt
8 from IPython.utils import DPyGetOpt
9
9
10 def test_import_generics():
10 def test_import_generics():
11 from IPython.utils import generics
11 from IPython.utils import generics
12
12
13 def test_import_genutils():
13 def test_import_genutils():
14 from IPython.utils import genutils
14 from IPython.utils import genutils
15
15
16 def test_import_ipstruct():
16 def test_import_ipstruct():
17 from IPython.utils import ipstruct
17 from IPython.utils import ipstruct
18
18
19 def test_import_platutils():
20 from IPython.utils import platutils
19
21
@@ -1,59 +1,59 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 # encoding: utf-8
2 # encoding: utf-8
3 """
3 """
4 Tests for platutils.py
4 Tests for platutils.py
5 """
5 """
6
6
7 #-----------------------------------------------------------------------------
7 #-----------------------------------------------------------------------------
8 # Copyright (C) 2008-2009 The IPython Development Team
8 # Copyright (C) 2008-2009 The IPython Development Team
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 # Imports
15 # Imports
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17
17
18 import os
18 import os
19 import sys
19 import sys
20
20
21 import nose.tools as nt
21 import nose.tools as nt
22
22
23 from IPython.platutils import find_cmd, FindCmdError, get_long_path_name
23 from IPython.utils.platutils import find_cmd, FindCmdError, get_long_path_name
24 from IPython.testing import decorators as dec
24 from IPython.testing import decorators as dec
25
25
26 #-----------------------------------------------------------------------------
26 #-----------------------------------------------------------------------------
27 # Tests
27 # Tests
28 #-----------------------------------------------------------------------------
28 #-----------------------------------------------------------------------------
29
29
30 def test_find_cmd_python():
30 def test_find_cmd_python():
31 """Make sure we find sys.exectable for python."""
31 """Make sure we find sys.exectable for python."""
32 nt.assert_equals(find_cmd('python'), sys.executable)
32 nt.assert_equals(find_cmd('python'), sys.executable)
33
33
34 @dec.skip_win32
34 @dec.skip_win32
35 def test_find_cmd():
35 def test_find_cmd():
36 """Make sure we can find the full path to ls."""
36 """Make sure we can find the full path to ls."""
37 path = find_cmd('ls')
37 path = find_cmd('ls')
38 nt.assert_true(path.endswith('ls'))
38 nt.assert_true(path.endswith('ls'))
39
39
40 @dec.skip_if_not_win32
40 @dec.skip_if_not_win32
41 def test_find_cmd():
41 def test_find_cmd():
42 """Try to find pythonw on Windows."""
42 """Try to find pythonw on Windows."""
43 path = find_cmd('pythonw')
43 path = find_cmd('pythonw')
44 nt.assert_true(path.endswith('pythonw.exe'))
44 nt.assert_true(path.endswith('pythonw.exe'))
45
45
46 def test_find_cmd_fail():
46 def test_find_cmd_fail():
47 """Make sure that FindCmdError is raised if we can't find the cmd."""
47 """Make sure that FindCmdError is raised if we can't find the cmd."""
48 nt.assert_raises(FindCmdError,find_cmd,'asdfasdf')
48 nt.assert_raises(FindCmdError,find_cmd,'asdfasdf')
49
49
50 @dec.skip_if_not_win32
50 @dec.skip_if_not_win32
51 def test_get_long_path_name_win32():
51 def test_get_long_path_name_win32():
52 p = get_long_path_name('c:\\docume~1')
52 p = get_long_path_name('c:\\docume~1')
53 nt.assert_equals(p,u'c:\\Documents and Settings')
53 nt.assert_equals(p,u'c:\\Documents and Settings')
54
54
55 @dec.skip_win32
55 @dec.skip_win32
56 def test_get_long_path_name():
56 def test_get_long_path_name():
57 p = get_long_path_name('/usr/local')
57 p = get_long_path_name('/usr/local')
58 nt.assert_equals(p,'/usr/local')
58 nt.assert_equals(p,'/usr/local')
59
59
General Comments 0
You need to be logged in to leave comments. Login now