##// END OF EJS Templates
%rehashx now works correctly with no_alias, even if the command has upper case characters
Ville M. Vainio -
Show More
@@ -1,3296 +1,3296 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Magic functions for InteractiveShell.
2 """Magic functions for InteractiveShell.
3
3
4 $Id: Magic.py 2996 2008-01-30 06:31:39Z fperez $"""
4 $Id: Magic.py 2996 2008-01-30 06:31:39Z fperez $"""
5
5
6 #*****************************************************************************
6 #*****************************************************************************
7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
8 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
8 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
9 #
9 #
10 # Distributed under the terms of the BSD License. The full license is in
10 # Distributed under the terms of the BSD License. The full license is in
11 # the file COPYING, distributed as part of this software.
11 # the file COPYING, distributed as part of this software.
12 #*****************************************************************************
12 #*****************************************************************************
13
13
14 #****************************************************************************
14 #****************************************************************************
15 # Modules and globals
15 # Modules and globals
16
16
17 from IPython import Release
17 from IPython import Release
18 __author__ = '%s <%s>\n%s <%s>' % \
18 __author__ = '%s <%s>\n%s <%s>' % \
19 ( Release.authors['Janko'] + Release.authors['Fernando'] )
19 ( Release.authors['Janko'] + Release.authors['Fernando'] )
20 __license__ = Release.license
20 __license__ = Release.license
21
21
22 # Python standard modules
22 # Python standard modules
23 import __builtin__
23 import __builtin__
24 import bdb
24 import bdb
25 import inspect
25 import inspect
26 import os
26 import os
27 import pdb
27 import pdb
28 import pydoc
28 import pydoc
29 import sys
29 import sys
30 import re
30 import re
31 import tempfile
31 import tempfile
32 import time
32 import time
33 import cPickle as pickle
33 import cPickle as pickle
34 import textwrap
34 import textwrap
35 from cStringIO import StringIO
35 from cStringIO import StringIO
36 from getopt import getopt,GetoptError
36 from getopt import getopt,GetoptError
37 from pprint import pprint, pformat
37 from pprint import pprint, pformat
38 from sets import Set
38 from sets import Set
39
39
40 # cProfile was added in Python2.5
40 # cProfile was added in Python2.5
41 try:
41 try:
42 import cProfile as profile
42 import cProfile as profile
43 import pstats
43 import pstats
44 except ImportError:
44 except ImportError:
45 # profile isn't bundled by default in Debian for license reasons
45 # profile isn't bundled by default in Debian for license reasons
46 try:
46 try:
47 import profile,pstats
47 import profile,pstats
48 except ImportError:
48 except ImportError:
49 profile = pstats = None
49 profile = pstats = None
50
50
51 # Homebrewed
51 # Homebrewed
52 import IPython
52 import IPython
53 from IPython import Debugger, OInspect, wildcard
53 from IPython import Debugger, OInspect, wildcard
54 from IPython.FakeModule import FakeModule
54 from IPython.FakeModule import FakeModule
55 from IPython.Itpl import Itpl, itpl, printpl,itplns
55 from IPython.Itpl import Itpl, itpl, printpl,itplns
56 from IPython.PyColorize import Parser
56 from IPython.PyColorize import Parser
57 from IPython.ipstruct import Struct
57 from IPython.ipstruct import Struct
58 from IPython.macro import Macro
58 from IPython.macro import Macro
59 from IPython.genutils import *
59 from IPython.genutils import *
60 from IPython import platutils
60 from IPython import platutils
61 import IPython.generics
61 import IPython.generics
62 import IPython.ipapi
62 import IPython.ipapi
63 from IPython.ipapi import UsageError
63 from IPython.ipapi import UsageError
64 #***************************************************************************
64 #***************************************************************************
65 # Utility functions
65 # Utility functions
66 def on_off(tag):
66 def on_off(tag):
67 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
67 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
68 return ['OFF','ON'][tag]
68 return ['OFF','ON'][tag]
69
69
70 class Bunch: pass
70 class Bunch: pass
71
71
72 def compress_dhist(dh):
72 def compress_dhist(dh):
73 head, tail = dh[:-10], dh[-10:]
73 head, tail = dh[:-10], dh[-10:]
74
74
75 newhead = []
75 newhead = []
76 done = Set()
76 done = Set()
77 for h in head:
77 for h in head:
78 if h in done:
78 if h in done:
79 continue
79 continue
80 newhead.append(h)
80 newhead.append(h)
81 done.add(h)
81 done.add(h)
82
82
83 return newhead + tail
83 return newhead + tail
84
84
85
85
86 #***************************************************************************
86 #***************************************************************************
87 # Main class implementing Magic functionality
87 # Main class implementing Magic functionality
88 class Magic:
88 class Magic:
89 """Magic functions for InteractiveShell.
89 """Magic functions for InteractiveShell.
90
90
91 Shell functions which can be reached as %function_name. All magic
91 Shell functions which can be reached as %function_name. All magic
92 functions should accept a string, which they can parse for their own
92 functions should accept a string, which they can parse for their own
93 needs. This can make some functions easier to type, eg `%cd ../`
93 needs. This can make some functions easier to type, eg `%cd ../`
94 vs. `%cd("../")`
94 vs. `%cd("../")`
95
95
96 ALL definitions MUST begin with the prefix magic_. The user won't need it
96 ALL definitions MUST begin with the prefix magic_. The user won't need it
97 at the command line, but it is is needed in the definition. """
97 at the command line, but it is is needed in the definition. """
98
98
99 # class globals
99 # class globals
100 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
100 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
101 'Automagic is ON, % prefix NOT needed for magic functions.']
101 'Automagic is ON, % prefix NOT needed for magic functions.']
102
102
103 #......................................................................
103 #......................................................................
104 # some utility functions
104 # some utility functions
105
105
106 def __init__(self,shell):
106 def __init__(self,shell):
107
107
108 self.options_table = {}
108 self.options_table = {}
109 if profile is None:
109 if profile is None:
110 self.magic_prun = self.profile_missing_notice
110 self.magic_prun = self.profile_missing_notice
111 self.shell = shell
111 self.shell = shell
112
112
113 # namespace for holding state we may need
113 # namespace for holding state we may need
114 self._magic_state = Bunch()
114 self._magic_state = Bunch()
115
115
116 def profile_missing_notice(self, *args, **kwargs):
116 def profile_missing_notice(self, *args, **kwargs):
117 error("""\
117 error("""\
118 The profile module could not be found. If you are a Debian user,
118 The profile module could not be found. If you are a Debian user,
119 it has been removed from the standard Debian package because of its non-free
119 it has been removed from the standard Debian package because of its non-free
120 license. To use profiling, please install"python2.3-profiler" from non-free.""")
120 license. To use profiling, please install"python2.3-profiler" from non-free.""")
121
121
122 def default_option(self,fn,optstr):
122 def default_option(self,fn,optstr):
123 """Make an entry in the options_table for fn, with value optstr"""
123 """Make an entry in the options_table for fn, with value optstr"""
124
124
125 if fn not in self.lsmagic():
125 if fn not in self.lsmagic():
126 error("%s is not a magic function" % fn)
126 error("%s is not a magic function" % fn)
127 self.options_table[fn] = optstr
127 self.options_table[fn] = optstr
128
128
129 def lsmagic(self):
129 def lsmagic(self):
130 """Return a list of currently available magic functions.
130 """Return a list of currently available magic functions.
131
131
132 Gives a list of the bare names after mangling (['ls','cd', ...], not
132 Gives a list of the bare names after mangling (['ls','cd', ...], not
133 ['magic_ls','magic_cd',...]"""
133 ['magic_ls','magic_cd',...]"""
134
134
135 # FIXME. This needs a cleanup, in the way the magics list is built.
135 # FIXME. This needs a cleanup, in the way the magics list is built.
136
136
137 # magics in class definition
137 # magics in class definition
138 class_magic = lambda fn: fn.startswith('magic_') and \
138 class_magic = lambda fn: fn.startswith('magic_') and \
139 callable(Magic.__dict__[fn])
139 callable(Magic.__dict__[fn])
140 # in instance namespace (run-time user additions)
140 # in instance namespace (run-time user additions)
141 inst_magic = lambda fn: fn.startswith('magic_') and \
141 inst_magic = lambda fn: fn.startswith('magic_') and \
142 callable(self.__dict__[fn])
142 callable(self.__dict__[fn])
143 # and bound magics by user (so they can access self):
143 # and bound magics by user (so they can access self):
144 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
144 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
145 callable(self.__class__.__dict__[fn])
145 callable(self.__class__.__dict__[fn])
146 magics = filter(class_magic,Magic.__dict__.keys()) + \
146 magics = filter(class_magic,Magic.__dict__.keys()) + \
147 filter(inst_magic,self.__dict__.keys()) + \
147 filter(inst_magic,self.__dict__.keys()) + \
148 filter(inst_bound_magic,self.__class__.__dict__.keys())
148 filter(inst_bound_magic,self.__class__.__dict__.keys())
149 out = []
149 out = []
150 for fn in magics:
150 for fn in magics:
151 out.append(fn.replace('magic_','',1))
151 out.append(fn.replace('magic_','',1))
152 out.sort()
152 out.sort()
153 return out
153 return out
154
154
155 def extract_input_slices(self,slices,raw=False):
155 def extract_input_slices(self,slices,raw=False):
156 """Return as a string a set of input history slices.
156 """Return as a string a set of input history slices.
157
157
158 Inputs:
158 Inputs:
159
159
160 - slices: the set of slices is given as a list of strings (like
160 - slices: the set of slices is given as a list of strings (like
161 ['1','4:8','9'], since this function is for use by magic functions
161 ['1','4:8','9'], since this function is for use by magic functions
162 which get their arguments as strings.
162 which get their arguments as strings.
163
163
164 Optional inputs:
164 Optional inputs:
165
165
166 - raw(False): by default, the processed input is used. If this is
166 - raw(False): by default, the processed input is used. If this is
167 true, the raw input history is used instead.
167 true, the raw input history is used instead.
168
168
169 Note that slices can be called with two notations:
169 Note that slices can be called with two notations:
170
170
171 N:M -> standard python form, means including items N...(M-1).
171 N:M -> standard python form, means including items N...(M-1).
172
172
173 N-M -> include items N..M (closed endpoint)."""
173 N-M -> include items N..M (closed endpoint)."""
174
174
175 if raw:
175 if raw:
176 hist = self.shell.input_hist_raw
176 hist = self.shell.input_hist_raw
177 else:
177 else:
178 hist = self.shell.input_hist
178 hist = self.shell.input_hist
179
179
180 cmds = []
180 cmds = []
181 for chunk in slices:
181 for chunk in slices:
182 if ':' in chunk:
182 if ':' in chunk:
183 ini,fin = map(int,chunk.split(':'))
183 ini,fin = map(int,chunk.split(':'))
184 elif '-' in chunk:
184 elif '-' in chunk:
185 ini,fin = map(int,chunk.split('-'))
185 ini,fin = map(int,chunk.split('-'))
186 fin += 1
186 fin += 1
187 else:
187 else:
188 ini = int(chunk)
188 ini = int(chunk)
189 fin = ini+1
189 fin = ini+1
190 cmds.append(hist[ini:fin])
190 cmds.append(hist[ini:fin])
191 return cmds
191 return cmds
192
192
193 def _ofind(self, oname, namespaces=None):
193 def _ofind(self, oname, namespaces=None):
194 """Find an object in the available namespaces.
194 """Find an object in the available namespaces.
195
195
196 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
196 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
197
197
198 Has special code to detect magic functions.
198 Has special code to detect magic functions.
199 """
199 """
200
200
201 oname = oname.strip()
201 oname = oname.strip()
202
202
203 alias_ns = None
203 alias_ns = None
204 if namespaces is None:
204 if namespaces is None:
205 # Namespaces to search in:
205 # Namespaces to search in:
206 # Put them in a list. The order is important so that we
206 # Put them in a list. The order is important so that we
207 # find things in the same order that Python finds them.
207 # find things in the same order that Python finds them.
208 namespaces = [ ('Interactive', self.shell.user_ns),
208 namespaces = [ ('Interactive', self.shell.user_ns),
209 ('IPython internal', self.shell.internal_ns),
209 ('IPython internal', self.shell.internal_ns),
210 ('Python builtin', __builtin__.__dict__),
210 ('Python builtin', __builtin__.__dict__),
211 ('Alias', self.shell.alias_table),
211 ('Alias', self.shell.alias_table),
212 ]
212 ]
213 alias_ns = self.shell.alias_table
213 alias_ns = self.shell.alias_table
214
214
215 # initialize results to 'null'
215 # initialize results to 'null'
216 found = 0; obj = None; ospace = None; ds = None;
216 found = 0; obj = None; ospace = None; ds = None;
217 ismagic = 0; isalias = 0; parent = None
217 ismagic = 0; isalias = 0; parent = None
218
218
219 # Look for the given name by splitting it in parts. If the head is
219 # Look for the given name by splitting it in parts. If the head is
220 # found, then we look for all the remaining parts as members, and only
220 # found, then we look for all the remaining parts as members, and only
221 # declare success if we can find them all.
221 # declare success if we can find them all.
222 oname_parts = oname.split('.')
222 oname_parts = oname.split('.')
223 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
223 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
224 for nsname,ns in namespaces:
224 for nsname,ns in namespaces:
225 try:
225 try:
226 obj = ns[oname_head]
226 obj = ns[oname_head]
227 except KeyError:
227 except KeyError:
228 continue
228 continue
229 else:
229 else:
230 #print 'oname_rest:', oname_rest # dbg
230 #print 'oname_rest:', oname_rest # dbg
231 for part in oname_rest:
231 for part in oname_rest:
232 try:
232 try:
233 parent = obj
233 parent = obj
234 obj = getattr(obj,part)
234 obj = getattr(obj,part)
235 except:
235 except:
236 # Blanket except b/c some badly implemented objects
236 # Blanket except b/c some badly implemented objects
237 # allow __getattr__ to raise exceptions other than
237 # allow __getattr__ to raise exceptions other than
238 # AttributeError, which then crashes IPython.
238 # AttributeError, which then crashes IPython.
239 break
239 break
240 else:
240 else:
241 # If we finish the for loop (no break), we got all members
241 # If we finish the for loop (no break), we got all members
242 found = 1
242 found = 1
243 ospace = nsname
243 ospace = nsname
244 if ns == alias_ns:
244 if ns == alias_ns:
245 isalias = 1
245 isalias = 1
246 break # namespace loop
246 break # namespace loop
247
247
248 # Try to see if it's magic
248 # Try to see if it's magic
249 if not found:
249 if not found:
250 if oname.startswith(self.shell.ESC_MAGIC):
250 if oname.startswith(self.shell.ESC_MAGIC):
251 oname = oname[1:]
251 oname = oname[1:]
252 obj = getattr(self,'magic_'+oname,None)
252 obj = getattr(self,'magic_'+oname,None)
253 if obj is not None:
253 if obj is not None:
254 found = 1
254 found = 1
255 ospace = 'IPython internal'
255 ospace = 'IPython internal'
256 ismagic = 1
256 ismagic = 1
257
257
258 # Last try: special-case some literals like '', [], {}, etc:
258 # Last try: special-case some literals like '', [], {}, etc:
259 if not found and oname_head in ["''",'""','[]','{}','()']:
259 if not found and oname_head in ["''",'""','[]','{}','()']:
260 obj = eval(oname_head)
260 obj = eval(oname_head)
261 found = 1
261 found = 1
262 ospace = 'Interactive'
262 ospace = 'Interactive'
263
263
264 return {'found':found, 'obj':obj, 'namespace':ospace,
264 return {'found':found, 'obj':obj, 'namespace':ospace,
265 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
265 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
266
266
267 def arg_err(self,func):
267 def arg_err(self,func):
268 """Print docstring if incorrect arguments were passed"""
268 """Print docstring if incorrect arguments were passed"""
269 print 'Error in arguments:'
269 print 'Error in arguments:'
270 print OInspect.getdoc(func)
270 print OInspect.getdoc(func)
271
271
272 def format_latex(self,strng):
272 def format_latex(self,strng):
273 """Format a string for latex inclusion."""
273 """Format a string for latex inclusion."""
274
274
275 # Characters that need to be escaped for latex:
275 # Characters that need to be escaped for latex:
276 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
276 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
277 # Magic command names as headers:
277 # Magic command names as headers:
278 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
278 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
279 re.MULTILINE)
279 re.MULTILINE)
280 # Magic commands
280 # Magic commands
281 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
281 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
282 re.MULTILINE)
282 re.MULTILINE)
283 # Paragraph continue
283 # Paragraph continue
284 par_re = re.compile(r'\\$',re.MULTILINE)
284 par_re = re.compile(r'\\$',re.MULTILINE)
285
285
286 # The "\n" symbol
286 # The "\n" symbol
287 newline_re = re.compile(r'\\n')
287 newline_re = re.compile(r'\\n')
288
288
289 # Now build the string for output:
289 # Now build the string for output:
290 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
290 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
291 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
291 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
292 strng)
292 strng)
293 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
293 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
294 strng = par_re.sub(r'\\\\',strng)
294 strng = par_re.sub(r'\\\\',strng)
295 strng = escape_re.sub(r'\\\1',strng)
295 strng = escape_re.sub(r'\\\1',strng)
296 strng = newline_re.sub(r'\\textbackslash{}n',strng)
296 strng = newline_re.sub(r'\\textbackslash{}n',strng)
297 return strng
297 return strng
298
298
299 def format_screen(self,strng):
299 def format_screen(self,strng):
300 """Format a string for screen printing.
300 """Format a string for screen printing.
301
301
302 This removes some latex-type format codes."""
302 This removes some latex-type format codes."""
303 # Paragraph continue
303 # Paragraph continue
304 par_re = re.compile(r'\\$',re.MULTILINE)
304 par_re = re.compile(r'\\$',re.MULTILINE)
305 strng = par_re.sub('',strng)
305 strng = par_re.sub('',strng)
306 return strng
306 return strng
307
307
308 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
308 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
309 """Parse options passed to an argument string.
309 """Parse options passed to an argument string.
310
310
311 The interface is similar to that of getopt(), but it returns back a
311 The interface is similar to that of getopt(), but it returns back a
312 Struct with the options as keys and the stripped argument string still
312 Struct with the options as keys and the stripped argument string still
313 as a string.
313 as a string.
314
314
315 arg_str is quoted as a true sys.argv vector by using shlex.split.
315 arg_str is quoted as a true sys.argv vector by using shlex.split.
316 This allows us to easily expand variables, glob files, quote
316 This allows us to easily expand variables, glob files, quote
317 arguments, etc.
317 arguments, etc.
318
318
319 Options:
319 Options:
320 -mode: default 'string'. If given as 'list', the argument string is
320 -mode: default 'string'. If given as 'list', the argument string is
321 returned as a list (split on whitespace) instead of a string.
321 returned as a list (split on whitespace) instead of a string.
322
322
323 -list_all: put all option values in lists. Normally only options
323 -list_all: put all option values in lists. Normally only options
324 appearing more than once are put in a list.
324 appearing more than once are put in a list.
325
325
326 -posix (True): whether to split the input line in POSIX mode or not,
326 -posix (True): whether to split the input line in POSIX mode or not,
327 as per the conventions outlined in the shlex module from the
327 as per the conventions outlined in the shlex module from the
328 standard library."""
328 standard library."""
329
329
330 # inject default options at the beginning of the input line
330 # inject default options at the beginning of the input line
331 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
331 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
332 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
332 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
333
333
334 mode = kw.get('mode','string')
334 mode = kw.get('mode','string')
335 if mode not in ['string','list']:
335 if mode not in ['string','list']:
336 raise ValueError,'incorrect mode given: %s' % mode
336 raise ValueError,'incorrect mode given: %s' % mode
337 # Get options
337 # Get options
338 list_all = kw.get('list_all',0)
338 list_all = kw.get('list_all',0)
339 posix = kw.get('posix',True)
339 posix = kw.get('posix',True)
340
340
341 # Check if we have more than one argument to warrant extra processing:
341 # Check if we have more than one argument to warrant extra processing:
342 odict = {} # Dictionary with options
342 odict = {} # Dictionary with options
343 args = arg_str.split()
343 args = arg_str.split()
344 if len(args) >= 1:
344 if len(args) >= 1:
345 # If the list of inputs only has 0 or 1 thing in it, there's no
345 # If the list of inputs only has 0 or 1 thing in it, there's no
346 # need to look for options
346 # need to look for options
347 argv = arg_split(arg_str,posix)
347 argv = arg_split(arg_str,posix)
348 # Do regular option processing
348 # Do regular option processing
349 try:
349 try:
350 opts,args = getopt(argv,opt_str,*long_opts)
350 opts,args = getopt(argv,opt_str,*long_opts)
351 except GetoptError,e:
351 except GetoptError,e:
352 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
352 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
353 " ".join(long_opts)))
353 " ".join(long_opts)))
354 for o,a in opts:
354 for o,a in opts:
355 if o.startswith('--'):
355 if o.startswith('--'):
356 o = o[2:]
356 o = o[2:]
357 else:
357 else:
358 o = o[1:]
358 o = o[1:]
359 try:
359 try:
360 odict[o].append(a)
360 odict[o].append(a)
361 except AttributeError:
361 except AttributeError:
362 odict[o] = [odict[o],a]
362 odict[o] = [odict[o],a]
363 except KeyError:
363 except KeyError:
364 if list_all:
364 if list_all:
365 odict[o] = [a]
365 odict[o] = [a]
366 else:
366 else:
367 odict[o] = a
367 odict[o] = a
368
368
369 # Prepare opts,args for return
369 # Prepare opts,args for return
370 opts = Struct(odict)
370 opts = Struct(odict)
371 if mode == 'string':
371 if mode == 'string':
372 args = ' '.join(args)
372 args = ' '.join(args)
373
373
374 return opts,args
374 return opts,args
375
375
376 #......................................................................
376 #......................................................................
377 # And now the actual magic functions
377 # And now the actual magic functions
378
378
379 # Functions for IPython shell work (vars,funcs, config, etc)
379 # Functions for IPython shell work (vars,funcs, config, etc)
380 def magic_lsmagic(self, parameter_s = ''):
380 def magic_lsmagic(self, parameter_s = ''):
381 """List currently available magic functions."""
381 """List currently available magic functions."""
382 mesc = self.shell.ESC_MAGIC
382 mesc = self.shell.ESC_MAGIC
383 print 'Available magic functions:\n'+mesc+\
383 print 'Available magic functions:\n'+mesc+\
384 (' '+mesc).join(self.lsmagic())
384 (' '+mesc).join(self.lsmagic())
385 print '\n' + Magic.auto_status[self.shell.rc.automagic]
385 print '\n' + Magic.auto_status[self.shell.rc.automagic]
386 return None
386 return None
387
387
388 def magic_magic(self, parameter_s = ''):
388 def magic_magic(self, parameter_s = ''):
389 """Print information about the magic function system."""
389 """Print information about the magic function system."""
390
390
391 mode = ''
391 mode = ''
392 try:
392 try:
393 if parameter_s.split()[0] == '-latex':
393 if parameter_s.split()[0] == '-latex':
394 mode = 'latex'
394 mode = 'latex'
395 if parameter_s.split()[0] == '-brief':
395 if parameter_s.split()[0] == '-brief':
396 mode = 'brief'
396 mode = 'brief'
397 except:
397 except:
398 pass
398 pass
399
399
400 magic_docs = []
400 magic_docs = []
401 for fname in self.lsmagic():
401 for fname in self.lsmagic():
402 mname = 'magic_' + fname
402 mname = 'magic_' + fname
403 for space in (Magic,self,self.__class__):
403 for space in (Magic,self,self.__class__):
404 try:
404 try:
405 fn = space.__dict__[mname]
405 fn = space.__dict__[mname]
406 except KeyError:
406 except KeyError:
407 pass
407 pass
408 else:
408 else:
409 break
409 break
410 if mode == 'brief':
410 if mode == 'brief':
411 # only first line
411 # only first line
412 if fn.__doc__:
412 if fn.__doc__:
413 fndoc = fn.__doc__.split('\n',1)[0]
413 fndoc = fn.__doc__.split('\n',1)[0]
414 else:
414 else:
415 fndoc = 'No documentation'
415 fndoc = 'No documentation'
416 else:
416 else:
417 fndoc = fn.__doc__
417 fndoc = fn.__doc__
418
418
419 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
419 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
420 fname,fndoc))
420 fname,fndoc))
421 magic_docs = ''.join(magic_docs)
421 magic_docs = ''.join(magic_docs)
422
422
423 if mode == 'latex':
423 if mode == 'latex':
424 print self.format_latex(magic_docs)
424 print self.format_latex(magic_docs)
425 return
425 return
426 else:
426 else:
427 magic_docs = self.format_screen(magic_docs)
427 magic_docs = self.format_screen(magic_docs)
428 if mode == 'brief':
428 if mode == 'brief':
429 return magic_docs
429 return magic_docs
430
430
431 outmsg = """
431 outmsg = """
432 IPython's 'magic' functions
432 IPython's 'magic' functions
433 ===========================
433 ===========================
434
434
435 The magic function system provides a series of functions which allow you to
435 The magic function system provides a series of functions which allow you to
436 control the behavior of IPython itself, plus a lot of system-type
436 control the behavior of IPython itself, plus a lot of system-type
437 features. All these functions are prefixed with a % character, but parameters
437 features. All these functions are prefixed with a % character, but parameters
438 are given without parentheses or quotes.
438 are given without parentheses or quotes.
439
439
440 NOTE: If you have 'automagic' enabled (via the command line option or with the
440 NOTE: If you have 'automagic' enabled (via the command line option or with the
441 %automagic function), you don't need to type in the % explicitly. By default,
441 %automagic function), you don't need to type in the % explicitly. By default,
442 IPython ships with automagic on, so you should only rarely need the % escape.
442 IPython ships with automagic on, so you should only rarely need the % escape.
443
443
444 Example: typing '%cd mydir' (without the quotes) changes you working directory
444 Example: typing '%cd mydir' (without the quotes) changes you working directory
445 to 'mydir', if it exists.
445 to 'mydir', if it exists.
446
446
447 You can define your own magic functions to extend the system. See the supplied
447 You can define your own magic functions to extend the system. See the supplied
448 ipythonrc and example-magic.py files for details (in your ipython
448 ipythonrc and example-magic.py files for details (in your ipython
449 configuration directory, typically $HOME/.ipython/).
449 configuration directory, typically $HOME/.ipython/).
450
450
451 You can also define your own aliased names for magic functions. In your
451 You can also define your own aliased names for magic functions. In your
452 ipythonrc file, placing a line like:
452 ipythonrc file, placing a line like:
453
453
454 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
454 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
455
455
456 will define %pf as a new name for %profile.
456 will define %pf as a new name for %profile.
457
457
458 You can also call magics in code using the ipmagic() function, which IPython
458 You can also call magics in code using the ipmagic() function, which IPython
459 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
459 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
460
460
461 For a list of the available magic functions, use %lsmagic. For a description
461 For a list of the available magic functions, use %lsmagic. For a description
462 of any of them, type %magic_name?, e.g. '%cd?'.
462 of any of them, type %magic_name?, e.g. '%cd?'.
463
463
464 Currently the magic system has the following functions:\n"""
464 Currently the magic system has the following functions:\n"""
465
465
466 mesc = self.shell.ESC_MAGIC
466 mesc = self.shell.ESC_MAGIC
467 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
467 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
468 "\n\n%s%s\n\n%s" % (outmsg,
468 "\n\n%s%s\n\n%s" % (outmsg,
469 magic_docs,mesc,mesc,
469 magic_docs,mesc,mesc,
470 (' '+mesc).join(self.lsmagic()),
470 (' '+mesc).join(self.lsmagic()),
471 Magic.auto_status[self.shell.rc.automagic] ) )
471 Magic.auto_status[self.shell.rc.automagic] ) )
472
472
473 page(outmsg,screen_lines=self.shell.rc.screen_length)
473 page(outmsg,screen_lines=self.shell.rc.screen_length)
474
474
475
475
476 def magic_autoindent(self, parameter_s = ''):
476 def magic_autoindent(self, parameter_s = ''):
477 """Toggle autoindent on/off (if available)."""
477 """Toggle autoindent on/off (if available)."""
478
478
479 self.shell.set_autoindent()
479 self.shell.set_autoindent()
480 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
480 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
481
481
482
482
483 def magic_automagic(self, parameter_s = ''):
483 def magic_automagic(self, parameter_s = ''):
484 """Make magic functions callable without having to type the initial %.
484 """Make magic functions callable without having to type the initial %.
485
485
486 Without argumentsl toggles on/off (when off, you must call it as
486 Without argumentsl toggles on/off (when off, you must call it as
487 %automagic, of course). With arguments it sets the value, and you can
487 %automagic, of course). With arguments it sets the value, and you can
488 use any of (case insensitive):
488 use any of (case insensitive):
489
489
490 - on,1,True: to activate
490 - on,1,True: to activate
491
491
492 - off,0,False: to deactivate.
492 - off,0,False: to deactivate.
493
493
494 Note that magic functions have lowest priority, so if there's a
494 Note that magic functions have lowest priority, so if there's a
495 variable whose name collides with that of a magic fn, automagic won't
495 variable whose name collides with that of a magic fn, automagic won't
496 work for that function (you get the variable instead). However, if you
496 work for that function (you get the variable instead). However, if you
497 delete the variable (del var), the previously shadowed magic function
497 delete the variable (del var), the previously shadowed magic function
498 becomes visible to automagic again."""
498 becomes visible to automagic again."""
499
499
500 rc = self.shell.rc
500 rc = self.shell.rc
501 arg = parameter_s.lower()
501 arg = parameter_s.lower()
502 if parameter_s in ('on','1','true'):
502 if parameter_s in ('on','1','true'):
503 rc.automagic = True
503 rc.automagic = True
504 elif parameter_s in ('off','0','false'):
504 elif parameter_s in ('off','0','false'):
505 rc.automagic = False
505 rc.automagic = False
506 else:
506 else:
507 rc.automagic = not rc.automagic
507 rc.automagic = not rc.automagic
508 print '\n' + Magic.auto_status[rc.automagic]
508 print '\n' + Magic.auto_status[rc.automagic]
509
509
510
510
511 def magic_autocall(self, parameter_s = ''):
511 def magic_autocall(self, parameter_s = ''):
512 """Make functions callable without having to type parentheses.
512 """Make functions callable without having to type parentheses.
513
513
514 Usage:
514 Usage:
515
515
516 %autocall [mode]
516 %autocall [mode]
517
517
518 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
518 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
519 value is toggled on and off (remembering the previous state).
519 value is toggled on and off (remembering the previous state).
520
520
521 In more detail, these values mean:
521 In more detail, these values mean:
522
522
523 0 -> fully disabled
523 0 -> fully disabled
524
524
525 1 -> active, but do not apply if there are no arguments on the line.
525 1 -> active, but do not apply if there are no arguments on the line.
526
526
527 In this mode, you get:
527 In this mode, you get:
528
528
529 In [1]: callable
529 In [1]: callable
530 Out[1]: <built-in function callable>
530 Out[1]: <built-in function callable>
531
531
532 In [2]: callable 'hello'
532 In [2]: callable 'hello'
533 ------> callable('hello')
533 ------> callable('hello')
534 Out[2]: False
534 Out[2]: False
535
535
536 2 -> Active always. Even if no arguments are present, the callable
536 2 -> Active always. Even if no arguments are present, the callable
537 object is called:
537 object is called:
538
538
539 In [4]: callable
539 In [4]: callable
540 ------> callable()
540 ------> callable()
541
541
542 Note that even with autocall off, you can still use '/' at the start of
542 Note that even with autocall off, you can still use '/' at the start of
543 a line to treat the first argument on the command line as a function
543 a line to treat the first argument on the command line as a function
544 and add parentheses to it:
544 and add parentheses to it:
545
545
546 In [8]: /str 43
546 In [8]: /str 43
547 ------> str(43)
547 ------> str(43)
548 Out[8]: '43'
548 Out[8]: '43'
549 """
549 """
550
550
551 rc = self.shell.rc
551 rc = self.shell.rc
552
552
553 if parameter_s:
553 if parameter_s:
554 arg = int(parameter_s)
554 arg = int(parameter_s)
555 else:
555 else:
556 arg = 'toggle'
556 arg = 'toggle'
557
557
558 if not arg in (0,1,2,'toggle'):
558 if not arg in (0,1,2,'toggle'):
559 error('Valid modes: (0->Off, 1->Smart, 2->Full')
559 error('Valid modes: (0->Off, 1->Smart, 2->Full')
560 return
560 return
561
561
562 if arg in (0,1,2):
562 if arg in (0,1,2):
563 rc.autocall = arg
563 rc.autocall = arg
564 else: # toggle
564 else: # toggle
565 if rc.autocall:
565 if rc.autocall:
566 self._magic_state.autocall_save = rc.autocall
566 self._magic_state.autocall_save = rc.autocall
567 rc.autocall = 0
567 rc.autocall = 0
568 else:
568 else:
569 try:
569 try:
570 rc.autocall = self._magic_state.autocall_save
570 rc.autocall = self._magic_state.autocall_save
571 except AttributeError:
571 except AttributeError:
572 rc.autocall = self._magic_state.autocall_save = 1
572 rc.autocall = self._magic_state.autocall_save = 1
573
573
574 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
574 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
575
575
576 def magic_system_verbose(self, parameter_s = ''):
576 def magic_system_verbose(self, parameter_s = ''):
577 """Set verbose printing of system calls.
577 """Set verbose printing of system calls.
578
578
579 If called without an argument, act as a toggle"""
579 If called without an argument, act as a toggle"""
580
580
581 if parameter_s:
581 if parameter_s:
582 val = bool(eval(parameter_s))
582 val = bool(eval(parameter_s))
583 else:
583 else:
584 val = None
584 val = None
585
585
586 self.shell.rc_set_toggle('system_verbose',val)
586 self.shell.rc_set_toggle('system_verbose',val)
587 print "System verbose printing is:",\
587 print "System verbose printing is:",\
588 ['OFF','ON'][self.shell.rc.system_verbose]
588 ['OFF','ON'][self.shell.rc.system_verbose]
589
589
590
590
591 def magic_page(self, parameter_s=''):
591 def magic_page(self, parameter_s=''):
592 """Pretty print the object and display it through a pager.
592 """Pretty print the object and display it through a pager.
593
593
594 %page [options] OBJECT
594 %page [options] OBJECT
595
595
596 If no object is given, use _ (last output).
596 If no object is given, use _ (last output).
597
597
598 Options:
598 Options:
599
599
600 -r: page str(object), don't pretty-print it."""
600 -r: page str(object), don't pretty-print it."""
601
601
602 # After a function contributed by Olivier Aubert, slightly modified.
602 # After a function contributed by Olivier Aubert, slightly modified.
603
603
604 # Process options/args
604 # Process options/args
605 opts,args = self.parse_options(parameter_s,'r')
605 opts,args = self.parse_options(parameter_s,'r')
606 raw = 'r' in opts
606 raw = 'r' in opts
607
607
608 oname = args and args or '_'
608 oname = args and args or '_'
609 info = self._ofind(oname)
609 info = self._ofind(oname)
610 if info['found']:
610 if info['found']:
611 txt = (raw and str or pformat)( info['obj'] )
611 txt = (raw and str or pformat)( info['obj'] )
612 page(txt)
612 page(txt)
613 else:
613 else:
614 print 'Object `%s` not found' % oname
614 print 'Object `%s` not found' % oname
615
615
616 def magic_profile(self, parameter_s=''):
616 def magic_profile(self, parameter_s=''):
617 """Print your currently active IPyhton profile."""
617 """Print your currently active IPyhton profile."""
618 if self.shell.rc.profile:
618 if self.shell.rc.profile:
619 printpl('Current IPython profile: $self.shell.rc.profile.')
619 printpl('Current IPython profile: $self.shell.rc.profile.')
620 else:
620 else:
621 print 'No profile active.'
621 print 'No profile active.'
622
622
623 def magic_pinfo(self, parameter_s='', namespaces=None):
623 def magic_pinfo(self, parameter_s='', namespaces=None):
624 """Provide detailed information about an object.
624 """Provide detailed information about an object.
625
625
626 '%pinfo object' is just a synonym for object? or ?object."""
626 '%pinfo object' is just a synonym for object? or ?object."""
627
627
628 #print 'pinfo par: <%s>' % parameter_s # dbg
628 #print 'pinfo par: <%s>' % parameter_s # dbg
629
629
630
630
631 # detail_level: 0 -> obj? , 1 -> obj??
631 # detail_level: 0 -> obj? , 1 -> obj??
632 detail_level = 0
632 detail_level = 0
633 # We need to detect if we got called as 'pinfo pinfo foo', which can
633 # We need to detect if we got called as 'pinfo pinfo foo', which can
634 # happen if the user types 'pinfo foo?' at the cmd line.
634 # happen if the user types 'pinfo foo?' at the cmd line.
635 pinfo,qmark1,oname,qmark2 = \
635 pinfo,qmark1,oname,qmark2 = \
636 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
636 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
637 if pinfo or qmark1 or qmark2:
637 if pinfo or qmark1 or qmark2:
638 detail_level = 1
638 detail_level = 1
639 if "*" in oname:
639 if "*" in oname:
640 self.magic_psearch(oname)
640 self.magic_psearch(oname)
641 else:
641 else:
642 self._inspect('pinfo', oname, detail_level=detail_level,
642 self._inspect('pinfo', oname, detail_level=detail_level,
643 namespaces=namespaces)
643 namespaces=namespaces)
644
644
645 def magic_pdef(self, parameter_s='', namespaces=None):
645 def magic_pdef(self, parameter_s='', namespaces=None):
646 """Print the definition header for any callable object.
646 """Print the definition header for any callable object.
647
647
648 If the object is a class, print the constructor information."""
648 If the object is a class, print the constructor information."""
649 self._inspect('pdef',parameter_s, namespaces)
649 self._inspect('pdef',parameter_s, namespaces)
650
650
651 def magic_pdoc(self, parameter_s='', namespaces=None):
651 def magic_pdoc(self, parameter_s='', namespaces=None):
652 """Print the docstring for an object.
652 """Print the docstring for an object.
653
653
654 If the given object is a class, it will print both the class and the
654 If the given object is a class, it will print both the class and the
655 constructor docstrings."""
655 constructor docstrings."""
656 self._inspect('pdoc',parameter_s, namespaces)
656 self._inspect('pdoc',parameter_s, namespaces)
657
657
658 def magic_psource(self, parameter_s='', namespaces=None):
658 def magic_psource(self, parameter_s='', namespaces=None):
659 """Print (or run through pager) the source code for an object."""
659 """Print (or run through pager) the source code for an object."""
660 self._inspect('psource',parameter_s, namespaces)
660 self._inspect('psource',parameter_s, namespaces)
661
661
662 def magic_pfile(self, parameter_s=''):
662 def magic_pfile(self, parameter_s=''):
663 """Print (or run through pager) the file where an object is defined.
663 """Print (or run through pager) the file where an object is defined.
664
664
665 The file opens at the line where the object definition begins. IPython
665 The file opens at the line where the object definition begins. IPython
666 will honor the environment variable PAGER if set, and otherwise will
666 will honor the environment variable PAGER if set, and otherwise will
667 do its best to print the file in a convenient form.
667 do its best to print the file in a convenient form.
668
668
669 If the given argument is not an object currently defined, IPython will
669 If the given argument is not an object currently defined, IPython will
670 try to interpret it as a filename (automatically adding a .py extension
670 try to interpret it as a filename (automatically adding a .py extension
671 if needed). You can thus use %pfile as a syntax highlighting code
671 if needed). You can thus use %pfile as a syntax highlighting code
672 viewer."""
672 viewer."""
673
673
674 # first interpret argument as an object name
674 # first interpret argument as an object name
675 out = self._inspect('pfile',parameter_s)
675 out = self._inspect('pfile',parameter_s)
676 # if not, try the input as a filename
676 # if not, try the input as a filename
677 if out == 'not found':
677 if out == 'not found':
678 try:
678 try:
679 filename = get_py_filename(parameter_s)
679 filename = get_py_filename(parameter_s)
680 except IOError,msg:
680 except IOError,msg:
681 print msg
681 print msg
682 return
682 return
683 page(self.shell.inspector.format(file(filename).read()))
683 page(self.shell.inspector.format(file(filename).read()))
684
684
685 def _inspect(self,meth,oname,namespaces=None,**kw):
685 def _inspect(self,meth,oname,namespaces=None,**kw):
686 """Generic interface to the inspector system.
686 """Generic interface to the inspector system.
687
687
688 This function is meant to be called by pdef, pdoc & friends."""
688 This function is meant to be called by pdef, pdoc & friends."""
689
689
690 #oname = oname.strip()
690 #oname = oname.strip()
691 #print '1- oname: <%r>' % oname # dbg
691 #print '1- oname: <%r>' % oname # dbg
692 try:
692 try:
693 oname = oname.strip().encode('ascii')
693 oname = oname.strip().encode('ascii')
694 #print '2- oname: <%r>' % oname # dbg
694 #print '2- oname: <%r>' % oname # dbg
695 except UnicodeEncodeError:
695 except UnicodeEncodeError:
696 print 'Python identifiers can only contain ascii characters.'
696 print 'Python identifiers can only contain ascii characters.'
697 return 'not found'
697 return 'not found'
698
698
699 info = Struct(self._ofind(oname, namespaces))
699 info = Struct(self._ofind(oname, namespaces))
700
700
701 if info.found:
701 if info.found:
702 try:
702 try:
703 IPython.generics.inspect_object(info.obj)
703 IPython.generics.inspect_object(info.obj)
704 return
704 return
705 except IPython.ipapi.TryNext:
705 except IPython.ipapi.TryNext:
706 pass
706 pass
707 # Get the docstring of the class property if it exists.
707 # Get the docstring of the class property if it exists.
708 path = oname.split('.')
708 path = oname.split('.')
709 root = '.'.join(path[:-1])
709 root = '.'.join(path[:-1])
710 if info.parent is not None:
710 if info.parent is not None:
711 try:
711 try:
712 target = getattr(info.parent, '__class__')
712 target = getattr(info.parent, '__class__')
713 # The object belongs to a class instance.
713 # The object belongs to a class instance.
714 try:
714 try:
715 target = getattr(target, path[-1])
715 target = getattr(target, path[-1])
716 # The class defines the object.
716 # The class defines the object.
717 if isinstance(target, property):
717 if isinstance(target, property):
718 oname = root + '.__class__.' + path[-1]
718 oname = root + '.__class__.' + path[-1]
719 info = Struct(self._ofind(oname))
719 info = Struct(self._ofind(oname))
720 except AttributeError: pass
720 except AttributeError: pass
721 except AttributeError: pass
721 except AttributeError: pass
722
722
723 pmethod = getattr(self.shell.inspector,meth)
723 pmethod = getattr(self.shell.inspector,meth)
724 formatter = info.ismagic and self.format_screen or None
724 formatter = info.ismagic and self.format_screen or None
725 if meth == 'pdoc':
725 if meth == 'pdoc':
726 pmethod(info.obj,oname,formatter)
726 pmethod(info.obj,oname,formatter)
727 elif meth == 'pinfo':
727 elif meth == 'pinfo':
728 pmethod(info.obj,oname,formatter,info,**kw)
728 pmethod(info.obj,oname,formatter,info,**kw)
729 else:
729 else:
730 pmethod(info.obj,oname)
730 pmethod(info.obj,oname)
731 else:
731 else:
732 print 'Object `%s` not found.' % oname
732 print 'Object `%s` not found.' % oname
733 return 'not found' # so callers can take other action
733 return 'not found' # so callers can take other action
734
734
735 def magic_psearch(self, parameter_s=''):
735 def magic_psearch(self, parameter_s=''):
736 """Search for object in namespaces by wildcard.
736 """Search for object in namespaces by wildcard.
737
737
738 %psearch [options] PATTERN [OBJECT TYPE]
738 %psearch [options] PATTERN [OBJECT TYPE]
739
739
740 Note: ? can be used as a synonym for %psearch, at the beginning or at
740 Note: ? can be used as a synonym for %psearch, at the beginning or at
741 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
741 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
742 rest of the command line must be unchanged (options come first), so
742 rest of the command line must be unchanged (options come first), so
743 for example the following forms are equivalent
743 for example the following forms are equivalent
744
744
745 %psearch -i a* function
745 %psearch -i a* function
746 -i a* function?
746 -i a* function?
747 ?-i a* function
747 ?-i a* function
748
748
749 Arguments:
749 Arguments:
750
750
751 PATTERN
751 PATTERN
752
752
753 where PATTERN is a string containing * as a wildcard similar to its
753 where PATTERN is a string containing * as a wildcard similar to its
754 use in a shell. The pattern is matched in all namespaces on the
754 use in a shell. The pattern is matched in all namespaces on the
755 search path. By default objects starting with a single _ are not
755 search path. By default objects starting with a single _ are not
756 matched, many IPython generated objects have a single
756 matched, many IPython generated objects have a single
757 underscore. The default is case insensitive matching. Matching is
757 underscore. The default is case insensitive matching. Matching is
758 also done on the attributes of objects and not only on the objects
758 also done on the attributes of objects and not only on the objects
759 in a module.
759 in a module.
760
760
761 [OBJECT TYPE]
761 [OBJECT TYPE]
762
762
763 Is the name of a python type from the types module. The name is
763 Is the name of a python type from the types module. The name is
764 given in lowercase without the ending type, ex. StringType is
764 given in lowercase without the ending type, ex. StringType is
765 written string. By adding a type here only objects matching the
765 written string. By adding a type here only objects matching the
766 given type are matched. Using all here makes the pattern match all
766 given type are matched. Using all here makes the pattern match all
767 types (this is the default).
767 types (this is the default).
768
768
769 Options:
769 Options:
770
770
771 -a: makes the pattern match even objects whose names start with a
771 -a: makes the pattern match even objects whose names start with a
772 single underscore. These names are normally ommitted from the
772 single underscore. These names are normally ommitted from the
773 search.
773 search.
774
774
775 -i/-c: make the pattern case insensitive/sensitive. If neither of
775 -i/-c: make the pattern case insensitive/sensitive. If neither of
776 these options is given, the default is read from your ipythonrc
776 these options is given, the default is read from your ipythonrc
777 file. The option name which sets this value is
777 file. The option name which sets this value is
778 'wildcards_case_sensitive'. If this option is not specified in your
778 'wildcards_case_sensitive'. If this option is not specified in your
779 ipythonrc file, IPython's internal default is to do a case sensitive
779 ipythonrc file, IPython's internal default is to do a case sensitive
780 search.
780 search.
781
781
782 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
782 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
783 specifiy can be searched in any of the following namespaces:
783 specifiy can be searched in any of the following namespaces:
784 'builtin', 'user', 'user_global','internal', 'alias', where
784 'builtin', 'user', 'user_global','internal', 'alias', where
785 'builtin' and 'user' are the search defaults. Note that you should
785 'builtin' and 'user' are the search defaults. Note that you should
786 not use quotes when specifying namespaces.
786 not use quotes when specifying namespaces.
787
787
788 'Builtin' contains the python module builtin, 'user' contains all
788 'Builtin' contains the python module builtin, 'user' contains all
789 user data, 'alias' only contain the shell aliases and no python
789 user data, 'alias' only contain the shell aliases and no python
790 objects, 'internal' contains objects used by IPython. The
790 objects, 'internal' contains objects used by IPython. The
791 'user_global' namespace is only used by embedded IPython instances,
791 'user_global' namespace is only used by embedded IPython instances,
792 and it contains module-level globals. You can add namespaces to the
792 and it contains module-level globals. You can add namespaces to the
793 search with -s or exclude them with -e (these options can be given
793 search with -s or exclude them with -e (these options can be given
794 more than once).
794 more than once).
795
795
796 Examples:
796 Examples:
797
797
798 %psearch a* -> objects beginning with an a
798 %psearch a* -> objects beginning with an a
799 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
799 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
800 %psearch a* function -> all functions beginning with an a
800 %psearch a* function -> all functions beginning with an a
801 %psearch re.e* -> objects beginning with an e in module re
801 %psearch re.e* -> objects beginning with an e in module re
802 %psearch r*.e* -> objects that start with e in modules starting in r
802 %psearch r*.e* -> objects that start with e in modules starting in r
803 %psearch r*.* string -> all strings in modules beginning with r
803 %psearch r*.* string -> all strings in modules beginning with r
804
804
805 Case sensitve search:
805 Case sensitve search:
806
806
807 %psearch -c a* list all object beginning with lower case a
807 %psearch -c a* list all object beginning with lower case a
808
808
809 Show objects beginning with a single _:
809 Show objects beginning with a single _:
810
810
811 %psearch -a _* list objects beginning with a single underscore"""
811 %psearch -a _* list objects beginning with a single underscore"""
812 try:
812 try:
813 parameter_s = parameter_s.encode('ascii')
813 parameter_s = parameter_s.encode('ascii')
814 except UnicodeEncodeError:
814 except UnicodeEncodeError:
815 print 'Python identifiers can only contain ascii characters.'
815 print 'Python identifiers can only contain ascii characters.'
816 return
816 return
817
817
818 # default namespaces to be searched
818 # default namespaces to be searched
819 def_search = ['user','builtin']
819 def_search = ['user','builtin']
820
820
821 # Process options/args
821 # Process options/args
822 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
822 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
823 opt = opts.get
823 opt = opts.get
824 shell = self.shell
824 shell = self.shell
825 psearch = shell.inspector.psearch
825 psearch = shell.inspector.psearch
826
826
827 # select case options
827 # select case options
828 if opts.has_key('i'):
828 if opts.has_key('i'):
829 ignore_case = True
829 ignore_case = True
830 elif opts.has_key('c'):
830 elif opts.has_key('c'):
831 ignore_case = False
831 ignore_case = False
832 else:
832 else:
833 ignore_case = not shell.rc.wildcards_case_sensitive
833 ignore_case = not shell.rc.wildcards_case_sensitive
834
834
835 # Build list of namespaces to search from user options
835 # Build list of namespaces to search from user options
836 def_search.extend(opt('s',[]))
836 def_search.extend(opt('s',[]))
837 ns_exclude = ns_exclude=opt('e',[])
837 ns_exclude = ns_exclude=opt('e',[])
838 ns_search = [nm for nm in def_search if nm not in ns_exclude]
838 ns_search = [nm for nm in def_search if nm not in ns_exclude]
839
839
840 # Call the actual search
840 # Call the actual search
841 try:
841 try:
842 psearch(args,shell.ns_table,ns_search,
842 psearch(args,shell.ns_table,ns_search,
843 show_all=opt('a'),ignore_case=ignore_case)
843 show_all=opt('a'),ignore_case=ignore_case)
844 except:
844 except:
845 shell.showtraceback()
845 shell.showtraceback()
846
846
847 def magic_who_ls(self, parameter_s=''):
847 def magic_who_ls(self, parameter_s=''):
848 """Return a sorted list of all interactive variables.
848 """Return a sorted list of all interactive variables.
849
849
850 If arguments are given, only variables of types matching these
850 If arguments are given, only variables of types matching these
851 arguments are returned."""
851 arguments are returned."""
852
852
853 user_ns = self.shell.user_ns
853 user_ns = self.shell.user_ns
854 internal_ns = self.shell.internal_ns
854 internal_ns = self.shell.internal_ns
855 user_config_ns = self.shell.user_config_ns
855 user_config_ns = self.shell.user_config_ns
856 out = []
856 out = []
857 typelist = parameter_s.split()
857 typelist = parameter_s.split()
858
858
859 for i in user_ns:
859 for i in user_ns:
860 if not (i.startswith('_') or i.startswith('_i')) \
860 if not (i.startswith('_') or i.startswith('_i')) \
861 and not (i in internal_ns or i in user_config_ns):
861 and not (i in internal_ns or i in user_config_ns):
862 if typelist:
862 if typelist:
863 if type(user_ns[i]).__name__ in typelist:
863 if type(user_ns[i]).__name__ in typelist:
864 out.append(i)
864 out.append(i)
865 else:
865 else:
866 out.append(i)
866 out.append(i)
867 out.sort()
867 out.sort()
868 return out
868 return out
869
869
870 def magic_who(self, parameter_s=''):
870 def magic_who(self, parameter_s=''):
871 """Print all interactive variables, with some minimal formatting.
871 """Print all interactive variables, with some minimal formatting.
872
872
873 If any arguments are given, only variables whose type matches one of
873 If any arguments are given, only variables whose type matches one of
874 these are printed. For example:
874 these are printed. For example:
875
875
876 %who function str
876 %who function str
877
877
878 will only list functions and strings, excluding all other types of
878 will only list functions and strings, excluding all other types of
879 variables. To find the proper type names, simply use type(var) at a
879 variables. To find the proper type names, simply use type(var) at a
880 command line to see how python prints type names. For example:
880 command line to see how python prints type names. For example:
881
881
882 In [1]: type('hello')\\
882 In [1]: type('hello')\\
883 Out[1]: <type 'str'>
883 Out[1]: <type 'str'>
884
884
885 indicates that the type name for strings is 'str'.
885 indicates that the type name for strings is 'str'.
886
886
887 %who always excludes executed names loaded through your configuration
887 %who always excludes executed names loaded through your configuration
888 file and things which are internal to IPython.
888 file and things which are internal to IPython.
889
889
890 This is deliberate, as typically you may load many modules and the
890 This is deliberate, as typically you may load many modules and the
891 purpose of %who is to show you only what you've manually defined."""
891 purpose of %who is to show you only what you've manually defined."""
892
892
893 varlist = self.magic_who_ls(parameter_s)
893 varlist = self.magic_who_ls(parameter_s)
894 if not varlist:
894 if not varlist:
895 if parameter_s:
895 if parameter_s:
896 print 'No variables match your requested type.'
896 print 'No variables match your requested type.'
897 else:
897 else:
898 print 'Interactive namespace is empty.'
898 print 'Interactive namespace is empty.'
899 return
899 return
900
900
901 # if we have variables, move on...
901 # if we have variables, move on...
902 count = 0
902 count = 0
903 for i in varlist:
903 for i in varlist:
904 print i+'\t',
904 print i+'\t',
905 count += 1
905 count += 1
906 if count > 8:
906 if count > 8:
907 count = 0
907 count = 0
908 print
908 print
909 print
909 print
910
910
911 def magic_whos(self, parameter_s=''):
911 def magic_whos(self, parameter_s=''):
912 """Like %who, but gives some extra information about each variable.
912 """Like %who, but gives some extra information about each variable.
913
913
914 The same type filtering of %who can be applied here.
914 The same type filtering of %who can be applied here.
915
915
916 For all variables, the type is printed. Additionally it prints:
916 For all variables, the type is printed. Additionally it prints:
917
917
918 - For {},[],(): their length.
918 - For {},[],(): their length.
919
919
920 - For numpy and Numeric arrays, a summary with shape, number of
920 - For numpy and Numeric arrays, a summary with shape, number of
921 elements, typecode and size in memory.
921 elements, typecode and size in memory.
922
922
923 - Everything else: a string representation, snipping their middle if
923 - Everything else: a string representation, snipping their middle if
924 too long."""
924 too long."""
925
925
926 varnames = self.magic_who_ls(parameter_s)
926 varnames = self.magic_who_ls(parameter_s)
927 if not varnames:
927 if not varnames:
928 if parameter_s:
928 if parameter_s:
929 print 'No variables match your requested type.'
929 print 'No variables match your requested type.'
930 else:
930 else:
931 print 'Interactive namespace is empty.'
931 print 'Interactive namespace is empty.'
932 return
932 return
933
933
934 # if we have variables, move on...
934 # if we have variables, move on...
935
935
936 # for these types, show len() instead of data:
936 # for these types, show len() instead of data:
937 seq_types = [types.DictType,types.ListType,types.TupleType]
937 seq_types = [types.DictType,types.ListType,types.TupleType]
938
938
939 # for numpy/Numeric arrays, display summary info
939 # for numpy/Numeric arrays, display summary info
940 try:
940 try:
941 import numpy
941 import numpy
942 except ImportError:
942 except ImportError:
943 ndarray_type = None
943 ndarray_type = None
944 else:
944 else:
945 ndarray_type = numpy.ndarray.__name__
945 ndarray_type = numpy.ndarray.__name__
946 try:
946 try:
947 import Numeric
947 import Numeric
948 except ImportError:
948 except ImportError:
949 array_type = None
949 array_type = None
950 else:
950 else:
951 array_type = Numeric.ArrayType.__name__
951 array_type = Numeric.ArrayType.__name__
952
952
953 # Find all variable names and types so we can figure out column sizes
953 # Find all variable names and types so we can figure out column sizes
954 def get_vars(i):
954 def get_vars(i):
955 return self.shell.user_ns[i]
955 return self.shell.user_ns[i]
956
956
957 # some types are well known and can be shorter
957 # some types are well known and can be shorter
958 abbrevs = {'IPython.macro.Macro' : 'Macro'}
958 abbrevs = {'IPython.macro.Macro' : 'Macro'}
959 def type_name(v):
959 def type_name(v):
960 tn = type(v).__name__
960 tn = type(v).__name__
961 return abbrevs.get(tn,tn)
961 return abbrevs.get(tn,tn)
962
962
963 varlist = map(get_vars,varnames)
963 varlist = map(get_vars,varnames)
964
964
965 typelist = []
965 typelist = []
966 for vv in varlist:
966 for vv in varlist:
967 tt = type_name(vv)
967 tt = type_name(vv)
968
968
969 if tt=='instance':
969 if tt=='instance':
970 typelist.append( abbrevs.get(str(vv.__class__),
970 typelist.append( abbrevs.get(str(vv.__class__),
971 str(vv.__class__)))
971 str(vv.__class__)))
972 else:
972 else:
973 typelist.append(tt)
973 typelist.append(tt)
974
974
975 # column labels and # of spaces as separator
975 # column labels and # of spaces as separator
976 varlabel = 'Variable'
976 varlabel = 'Variable'
977 typelabel = 'Type'
977 typelabel = 'Type'
978 datalabel = 'Data/Info'
978 datalabel = 'Data/Info'
979 colsep = 3
979 colsep = 3
980 # variable format strings
980 # variable format strings
981 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
981 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
982 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
982 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
983 aformat = "%s: %s elems, type `%s`, %s bytes"
983 aformat = "%s: %s elems, type `%s`, %s bytes"
984 # find the size of the columns to format the output nicely
984 # find the size of the columns to format the output nicely
985 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
985 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
986 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
986 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
987 # table header
987 # table header
988 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
988 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
989 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
989 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
990 # and the table itself
990 # and the table itself
991 kb = 1024
991 kb = 1024
992 Mb = 1048576 # kb**2
992 Mb = 1048576 # kb**2
993 for vname,var,vtype in zip(varnames,varlist,typelist):
993 for vname,var,vtype in zip(varnames,varlist,typelist):
994 print itpl(vformat),
994 print itpl(vformat),
995 if vtype in seq_types:
995 if vtype in seq_types:
996 print len(var)
996 print len(var)
997 elif vtype in [array_type,ndarray_type]:
997 elif vtype in [array_type,ndarray_type]:
998 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
998 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
999 if vtype==ndarray_type:
999 if vtype==ndarray_type:
1000 # numpy
1000 # numpy
1001 vsize = var.size
1001 vsize = var.size
1002 vbytes = vsize*var.itemsize
1002 vbytes = vsize*var.itemsize
1003 vdtype = var.dtype
1003 vdtype = var.dtype
1004 else:
1004 else:
1005 # Numeric
1005 # Numeric
1006 vsize = Numeric.size(var)
1006 vsize = Numeric.size(var)
1007 vbytes = vsize*var.itemsize()
1007 vbytes = vsize*var.itemsize()
1008 vdtype = var.typecode()
1008 vdtype = var.typecode()
1009
1009
1010 if vbytes < 100000:
1010 if vbytes < 100000:
1011 print aformat % (vshape,vsize,vdtype,vbytes)
1011 print aformat % (vshape,vsize,vdtype,vbytes)
1012 else:
1012 else:
1013 print aformat % (vshape,vsize,vdtype,vbytes),
1013 print aformat % (vshape,vsize,vdtype,vbytes),
1014 if vbytes < Mb:
1014 if vbytes < Mb:
1015 print '(%s kb)' % (vbytes/kb,)
1015 print '(%s kb)' % (vbytes/kb,)
1016 else:
1016 else:
1017 print '(%s Mb)' % (vbytes/Mb,)
1017 print '(%s Mb)' % (vbytes/Mb,)
1018 else:
1018 else:
1019 try:
1019 try:
1020 vstr = str(var)
1020 vstr = str(var)
1021 except UnicodeEncodeError:
1021 except UnicodeEncodeError:
1022 vstr = unicode(var).encode(sys.getdefaultencoding(),
1022 vstr = unicode(var).encode(sys.getdefaultencoding(),
1023 'backslashreplace')
1023 'backslashreplace')
1024 vstr = vstr.replace('\n','\\n')
1024 vstr = vstr.replace('\n','\\n')
1025 if len(vstr) < 50:
1025 if len(vstr) < 50:
1026 print vstr
1026 print vstr
1027 else:
1027 else:
1028 printpl(vfmt_short)
1028 printpl(vfmt_short)
1029
1029
1030 def magic_reset(self, parameter_s=''):
1030 def magic_reset(self, parameter_s=''):
1031 """Resets the namespace by removing all names defined by the user.
1031 """Resets the namespace by removing all names defined by the user.
1032
1032
1033 Input/Output history are left around in case you need them."""
1033 Input/Output history are left around in case you need them."""
1034
1034
1035 ans = self.shell.ask_yes_no(
1035 ans = self.shell.ask_yes_no(
1036 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1036 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1037 if not ans:
1037 if not ans:
1038 print 'Nothing done.'
1038 print 'Nothing done.'
1039 return
1039 return
1040 user_ns = self.shell.user_ns
1040 user_ns = self.shell.user_ns
1041 for i in self.magic_who_ls():
1041 for i in self.magic_who_ls():
1042 del(user_ns[i])
1042 del(user_ns[i])
1043
1043
1044 # Also flush the private list of module references kept for script
1044 # Also flush the private list of module references kept for script
1045 # execution protection
1045 # execution protection
1046 self.shell._user_main_modules[:] = []
1046 self.shell._user_main_modules[:] = []
1047
1047
1048 def magic_logstart(self,parameter_s=''):
1048 def magic_logstart(self,parameter_s=''):
1049 """Start logging anywhere in a session.
1049 """Start logging anywhere in a session.
1050
1050
1051 %logstart [-o|-r|-t] [log_name [log_mode]]
1051 %logstart [-o|-r|-t] [log_name [log_mode]]
1052
1052
1053 If no name is given, it defaults to a file named 'ipython_log.py' in your
1053 If no name is given, it defaults to a file named 'ipython_log.py' in your
1054 current directory, in 'rotate' mode (see below).
1054 current directory, in 'rotate' mode (see below).
1055
1055
1056 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1056 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1057 history up to that point and then continues logging.
1057 history up to that point and then continues logging.
1058
1058
1059 %logstart takes a second optional parameter: logging mode. This can be one
1059 %logstart takes a second optional parameter: logging mode. This can be one
1060 of (note that the modes are given unquoted):\\
1060 of (note that the modes are given unquoted):\\
1061 append: well, that says it.\\
1061 append: well, that says it.\\
1062 backup: rename (if exists) to name~ and start name.\\
1062 backup: rename (if exists) to name~ and start name.\\
1063 global: single logfile in your home dir, appended to.\\
1063 global: single logfile in your home dir, appended to.\\
1064 over : overwrite existing log.\\
1064 over : overwrite existing log.\\
1065 rotate: create rotating logs name.1~, name.2~, etc.
1065 rotate: create rotating logs name.1~, name.2~, etc.
1066
1066
1067 Options:
1067 Options:
1068
1068
1069 -o: log also IPython's output. In this mode, all commands which
1069 -o: log also IPython's output. In this mode, all commands which
1070 generate an Out[NN] prompt are recorded to the logfile, right after
1070 generate an Out[NN] prompt are recorded to the logfile, right after
1071 their corresponding input line. The output lines are always
1071 their corresponding input line. The output lines are always
1072 prepended with a '#[Out]# ' marker, so that the log remains valid
1072 prepended with a '#[Out]# ' marker, so that the log remains valid
1073 Python code.
1073 Python code.
1074
1074
1075 Since this marker is always the same, filtering only the output from
1075 Since this marker is always the same, filtering only the output from
1076 a log is very easy, using for example a simple awk call:
1076 a log is very easy, using for example a simple awk call:
1077
1077
1078 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1078 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1079
1079
1080 -r: log 'raw' input. Normally, IPython's logs contain the processed
1080 -r: log 'raw' input. Normally, IPython's logs contain the processed
1081 input, so that user lines are logged in their final form, converted
1081 input, so that user lines are logged in their final form, converted
1082 into valid Python. For example, %Exit is logged as
1082 into valid Python. For example, %Exit is logged as
1083 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1083 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1084 exactly as typed, with no transformations applied.
1084 exactly as typed, with no transformations applied.
1085
1085
1086 -t: put timestamps before each input line logged (these are put in
1086 -t: put timestamps before each input line logged (these are put in
1087 comments)."""
1087 comments)."""
1088
1088
1089 opts,par = self.parse_options(parameter_s,'ort')
1089 opts,par = self.parse_options(parameter_s,'ort')
1090 log_output = 'o' in opts
1090 log_output = 'o' in opts
1091 log_raw_input = 'r' in opts
1091 log_raw_input = 'r' in opts
1092 timestamp = 't' in opts
1092 timestamp = 't' in opts
1093
1093
1094 rc = self.shell.rc
1094 rc = self.shell.rc
1095 logger = self.shell.logger
1095 logger = self.shell.logger
1096
1096
1097 # if no args are given, the defaults set in the logger constructor by
1097 # if no args are given, the defaults set in the logger constructor by
1098 # ipytohn remain valid
1098 # ipytohn remain valid
1099 if par:
1099 if par:
1100 try:
1100 try:
1101 logfname,logmode = par.split()
1101 logfname,logmode = par.split()
1102 except:
1102 except:
1103 logfname = par
1103 logfname = par
1104 logmode = 'backup'
1104 logmode = 'backup'
1105 else:
1105 else:
1106 logfname = logger.logfname
1106 logfname = logger.logfname
1107 logmode = logger.logmode
1107 logmode = logger.logmode
1108 # put logfname into rc struct as if it had been called on the command
1108 # put logfname into rc struct as if it had been called on the command
1109 # line, so it ends up saved in the log header Save it in case we need
1109 # line, so it ends up saved in the log header Save it in case we need
1110 # to restore it...
1110 # to restore it...
1111 old_logfile = rc.opts.get('logfile','')
1111 old_logfile = rc.opts.get('logfile','')
1112 if logfname:
1112 if logfname:
1113 logfname = os.path.expanduser(logfname)
1113 logfname = os.path.expanduser(logfname)
1114 rc.opts.logfile = logfname
1114 rc.opts.logfile = logfname
1115 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1115 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1116 try:
1116 try:
1117 started = logger.logstart(logfname,loghead,logmode,
1117 started = logger.logstart(logfname,loghead,logmode,
1118 log_output,timestamp,log_raw_input)
1118 log_output,timestamp,log_raw_input)
1119 except:
1119 except:
1120 rc.opts.logfile = old_logfile
1120 rc.opts.logfile = old_logfile
1121 warn("Couldn't start log: %s" % sys.exc_info()[1])
1121 warn("Couldn't start log: %s" % sys.exc_info()[1])
1122 else:
1122 else:
1123 # log input history up to this point, optionally interleaving
1123 # log input history up to this point, optionally interleaving
1124 # output if requested
1124 # output if requested
1125
1125
1126 if timestamp:
1126 if timestamp:
1127 # disable timestamping for the previous history, since we've
1127 # disable timestamping for the previous history, since we've
1128 # lost those already (no time machine here).
1128 # lost those already (no time machine here).
1129 logger.timestamp = False
1129 logger.timestamp = False
1130
1130
1131 if log_raw_input:
1131 if log_raw_input:
1132 input_hist = self.shell.input_hist_raw
1132 input_hist = self.shell.input_hist_raw
1133 else:
1133 else:
1134 input_hist = self.shell.input_hist
1134 input_hist = self.shell.input_hist
1135
1135
1136 if log_output:
1136 if log_output:
1137 log_write = logger.log_write
1137 log_write = logger.log_write
1138 output_hist = self.shell.output_hist
1138 output_hist = self.shell.output_hist
1139 for n in range(1,len(input_hist)-1):
1139 for n in range(1,len(input_hist)-1):
1140 log_write(input_hist[n].rstrip())
1140 log_write(input_hist[n].rstrip())
1141 if n in output_hist:
1141 if n in output_hist:
1142 log_write(repr(output_hist[n]),'output')
1142 log_write(repr(output_hist[n]),'output')
1143 else:
1143 else:
1144 logger.log_write(input_hist[1:])
1144 logger.log_write(input_hist[1:])
1145 if timestamp:
1145 if timestamp:
1146 # re-enable timestamping
1146 # re-enable timestamping
1147 logger.timestamp = True
1147 logger.timestamp = True
1148
1148
1149 print ('Activating auto-logging. '
1149 print ('Activating auto-logging. '
1150 'Current session state plus future input saved.')
1150 'Current session state plus future input saved.')
1151 logger.logstate()
1151 logger.logstate()
1152
1152
1153 def magic_logstop(self,parameter_s=''):
1153 def magic_logstop(self,parameter_s=''):
1154 """Fully stop logging and close log file.
1154 """Fully stop logging and close log file.
1155
1155
1156 In order to start logging again, a new %logstart call needs to be made,
1156 In order to start logging again, a new %logstart call needs to be made,
1157 possibly (though not necessarily) with a new filename, mode and other
1157 possibly (though not necessarily) with a new filename, mode and other
1158 options."""
1158 options."""
1159 self.logger.logstop()
1159 self.logger.logstop()
1160
1160
1161 def magic_logoff(self,parameter_s=''):
1161 def magic_logoff(self,parameter_s=''):
1162 """Temporarily stop logging.
1162 """Temporarily stop logging.
1163
1163
1164 You must have previously started logging."""
1164 You must have previously started logging."""
1165 self.shell.logger.switch_log(0)
1165 self.shell.logger.switch_log(0)
1166
1166
1167 def magic_logon(self,parameter_s=''):
1167 def magic_logon(self,parameter_s=''):
1168 """Restart logging.
1168 """Restart logging.
1169
1169
1170 This function is for restarting logging which you've temporarily
1170 This function is for restarting logging which you've temporarily
1171 stopped with %logoff. For starting logging for the first time, you
1171 stopped with %logoff. For starting logging for the first time, you
1172 must use the %logstart function, which allows you to specify an
1172 must use the %logstart function, which allows you to specify an
1173 optional log filename."""
1173 optional log filename."""
1174
1174
1175 self.shell.logger.switch_log(1)
1175 self.shell.logger.switch_log(1)
1176
1176
1177 def magic_logstate(self,parameter_s=''):
1177 def magic_logstate(self,parameter_s=''):
1178 """Print the status of the logging system."""
1178 """Print the status of the logging system."""
1179
1179
1180 self.shell.logger.logstate()
1180 self.shell.logger.logstate()
1181
1181
1182 def magic_pdb(self, parameter_s=''):
1182 def magic_pdb(self, parameter_s=''):
1183 """Control the automatic calling of the pdb interactive debugger.
1183 """Control the automatic calling of the pdb interactive debugger.
1184
1184
1185 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1185 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1186 argument it works as a toggle.
1186 argument it works as a toggle.
1187
1187
1188 When an exception is triggered, IPython can optionally call the
1188 When an exception is triggered, IPython can optionally call the
1189 interactive pdb debugger after the traceback printout. %pdb toggles
1189 interactive pdb debugger after the traceback printout. %pdb toggles
1190 this feature on and off.
1190 this feature on and off.
1191
1191
1192 The initial state of this feature is set in your ipythonrc
1192 The initial state of this feature is set in your ipythonrc
1193 configuration file (the variable is called 'pdb').
1193 configuration file (the variable is called 'pdb').
1194
1194
1195 If you want to just activate the debugger AFTER an exception has fired,
1195 If you want to just activate the debugger AFTER an exception has fired,
1196 without having to type '%pdb on' and rerunning your code, you can use
1196 without having to type '%pdb on' and rerunning your code, you can use
1197 the %debug magic."""
1197 the %debug magic."""
1198
1198
1199 par = parameter_s.strip().lower()
1199 par = parameter_s.strip().lower()
1200
1200
1201 if par:
1201 if par:
1202 try:
1202 try:
1203 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1203 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1204 except KeyError:
1204 except KeyError:
1205 print ('Incorrect argument. Use on/1, off/0, '
1205 print ('Incorrect argument. Use on/1, off/0, '
1206 'or nothing for a toggle.')
1206 'or nothing for a toggle.')
1207 return
1207 return
1208 else:
1208 else:
1209 # toggle
1209 # toggle
1210 new_pdb = not self.shell.call_pdb
1210 new_pdb = not self.shell.call_pdb
1211
1211
1212 # set on the shell
1212 # set on the shell
1213 self.shell.call_pdb = new_pdb
1213 self.shell.call_pdb = new_pdb
1214 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1214 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1215
1215
1216 def magic_debug(self, parameter_s=''):
1216 def magic_debug(self, parameter_s=''):
1217 """Activate the interactive debugger in post-mortem mode.
1217 """Activate the interactive debugger in post-mortem mode.
1218
1218
1219 If an exception has just occurred, this lets you inspect its stack
1219 If an exception has just occurred, this lets you inspect its stack
1220 frames interactively. Note that this will always work only on the last
1220 frames interactively. Note that this will always work only on the last
1221 traceback that occurred, so you must call this quickly after an
1221 traceback that occurred, so you must call this quickly after an
1222 exception that you wish to inspect has fired, because if another one
1222 exception that you wish to inspect has fired, because if another one
1223 occurs, it clobbers the previous one.
1223 occurs, it clobbers the previous one.
1224
1224
1225 If you want IPython to automatically do this on every exception, see
1225 If you want IPython to automatically do this on every exception, see
1226 the %pdb magic for more details.
1226 the %pdb magic for more details.
1227 """
1227 """
1228
1228
1229 self.shell.debugger(force=True)
1229 self.shell.debugger(force=True)
1230
1230
1231 def magic_prun(self, parameter_s ='',user_mode=1,
1231 def magic_prun(self, parameter_s ='',user_mode=1,
1232 opts=None,arg_lst=None,prog_ns=None):
1232 opts=None,arg_lst=None,prog_ns=None):
1233
1233
1234 """Run a statement through the python code profiler.
1234 """Run a statement through the python code profiler.
1235
1235
1236 Usage:\\
1236 Usage:\\
1237 %prun [options] statement
1237 %prun [options] statement
1238
1238
1239 The given statement (which doesn't require quote marks) is run via the
1239 The given statement (which doesn't require quote marks) is run via the
1240 python profiler in a manner similar to the profile.run() function.
1240 python profiler in a manner similar to the profile.run() function.
1241 Namespaces are internally managed to work correctly; profile.run
1241 Namespaces are internally managed to work correctly; profile.run
1242 cannot be used in IPython because it makes certain assumptions about
1242 cannot be used in IPython because it makes certain assumptions about
1243 namespaces which do not hold under IPython.
1243 namespaces which do not hold under IPython.
1244
1244
1245 Options:
1245 Options:
1246
1246
1247 -l <limit>: you can place restrictions on what or how much of the
1247 -l <limit>: you can place restrictions on what or how much of the
1248 profile gets printed. The limit value can be:
1248 profile gets printed. The limit value can be:
1249
1249
1250 * A string: only information for function names containing this string
1250 * A string: only information for function names containing this string
1251 is printed.
1251 is printed.
1252
1252
1253 * An integer: only these many lines are printed.
1253 * An integer: only these many lines are printed.
1254
1254
1255 * A float (between 0 and 1): this fraction of the report is printed
1255 * A float (between 0 and 1): this fraction of the report is printed
1256 (for example, use a limit of 0.4 to see the topmost 40% only).
1256 (for example, use a limit of 0.4 to see the topmost 40% only).
1257
1257
1258 You can combine several limits with repeated use of the option. For
1258 You can combine several limits with repeated use of the option. For
1259 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1259 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1260 information about class constructors.
1260 information about class constructors.
1261
1261
1262 -r: return the pstats.Stats object generated by the profiling. This
1262 -r: return the pstats.Stats object generated by the profiling. This
1263 object has all the information about the profile in it, and you can
1263 object has all the information about the profile in it, and you can
1264 later use it for further analysis or in other functions.
1264 later use it for further analysis or in other functions.
1265
1265
1266 -s <key>: sort profile by given key. You can provide more than one key
1266 -s <key>: sort profile by given key. You can provide more than one key
1267 by using the option several times: '-s key1 -s key2 -s key3...'. The
1267 by using the option several times: '-s key1 -s key2 -s key3...'. The
1268 default sorting key is 'time'.
1268 default sorting key is 'time'.
1269
1269
1270 The following is copied verbatim from the profile documentation
1270 The following is copied verbatim from the profile documentation
1271 referenced below:
1271 referenced below:
1272
1272
1273 When more than one key is provided, additional keys are used as
1273 When more than one key is provided, additional keys are used as
1274 secondary criteria when the there is equality in all keys selected
1274 secondary criteria when the there is equality in all keys selected
1275 before them.
1275 before them.
1276
1276
1277 Abbreviations can be used for any key names, as long as the
1277 Abbreviations can be used for any key names, as long as the
1278 abbreviation is unambiguous. The following are the keys currently
1278 abbreviation is unambiguous. The following are the keys currently
1279 defined:
1279 defined:
1280
1280
1281 Valid Arg Meaning\\
1281 Valid Arg Meaning\\
1282 "calls" call count\\
1282 "calls" call count\\
1283 "cumulative" cumulative time\\
1283 "cumulative" cumulative time\\
1284 "file" file name\\
1284 "file" file name\\
1285 "module" file name\\
1285 "module" file name\\
1286 "pcalls" primitive call count\\
1286 "pcalls" primitive call count\\
1287 "line" line number\\
1287 "line" line number\\
1288 "name" function name\\
1288 "name" function name\\
1289 "nfl" name/file/line\\
1289 "nfl" name/file/line\\
1290 "stdname" standard name\\
1290 "stdname" standard name\\
1291 "time" internal time
1291 "time" internal time
1292
1292
1293 Note that all sorts on statistics are in descending order (placing
1293 Note that all sorts on statistics are in descending order (placing
1294 most time consuming items first), where as name, file, and line number
1294 most time consuming items first), where as name, file, and line number
1295 searches are in ascending order (i.e., alphabetical). The subtle
1295 searches are in ascending order (i.e., alphabetical). The subtle
1296 distinction between "nfl" and "stdname" is that the standard name is a
1296 distinction between "nfl" and "stdname" is that the standard name is a
1297 sort of the name as printed, which means that the embedded line
1297 sort of the name as printed, which means that the embedded line
1298 numbers get compared in an odd way. For example, lines 3, 20, and 40
1298 numbers get compared in an odd way. For example, lines 3, 20, and 40
1299 would (if the file names were the same) appear in the string order
1299 would (if the file names were the same) appear in the string order
1300 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1300 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1301 line numbers. In fact, sort_stats("nfl") is the same as
1301 line numbers. In fact, sort_stats("nfl") is the same as
1302 sort_stats("name", "file", "line").
1302 sort_stats("name", "file", "line").
1303
1303
1304 -T <filename>: save profile results as shown on screen to a text
1304 -T <filename>: save profile results as shown on screen to a text
1305 file. The profile is still shown on screen.
1305 file. The profile is still shown on screen.
1306
1306
1307 -D <filename>: save (via dump_stats) profile statistics to given
1307 -D <filename>: save (via dump_stats) profile statistics to given
1308 filename. This data is in a format understod by the pstats module, and
1308 filename. This data is in a format understod by the pstats module, and
1309 is generated by a call to the dump_stats() method of profile
1309 is generated by a call to the dump_stats() method of profile
1310 objects. The profile is still shown on screen.
1310 objects. The profile is still shown on screen.
1311
1311
1312 If you want to run complete programs under the profiler's control, use
1312 If you want to run complete programs under the profiler's control, use
1313 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1313 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1314 contains profiler specific options as described here.
1314 contains profiler specific options as described here.
1315
1315
1316 You can read the complete documentation for the profile module with:\\
1316 You can read the complete documentation for the profile module with:\\
1317 In [1]: import profile; profile.help() """
1317 In [1]: import profile; profile.help() """
1318
1318
1319 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1319 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1320 # protect user quote marks
1320 # protect user quote marks
1321 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1321 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1322
1322
1323 if user_mode: # regular user call
1323 if user_mode: # regular user call
1324 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1324 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1325 list_all=1)
1325 list_all=1)
1326 namespace = self.shell.user_ns
1326 namespace = self.shell.user_ns
1327 else: # called to run a program by %run -p
1327 else: # called to run a program by %run -p
1328 try:
1328 try:
1329 filename = get_py_filename(arg_lst[0])
1329 filename = get_py_filename(arg_lst[0])
1330 except IOError,msg:
1330 except IOError,msg:
1331 error(msg)
1331 error(msg)
1332 return
1332 return
1333
1333
1334 arg_str = 'execfile(filename,prog_ns)'
1334 arg_str = 'execfile(filename,prog_ns)'
1335 namespace = locals()
1335 namespace = locals()
1336
1336
1337 opts.merge(opts_def)
1337 opts.merge(opts_def)
1338
1338
1339 prof = profile.Profile()
1339 prof = profile.Profile()
1340 try:
1340 try:
1341 prof = prof.runctx(arg_str,namespace,namespace)
1341 prof = prof.runctx(arg_str,namespace,namespace)
1342 sys_exit = ''
1342 sys_exit = ''
1343 except SystemExit:
1343 except SystemExit:
1344 sys_exit = """*** SystemExit exception caught in code being profiled."""
1344 sys_exit = """*** SystemExit exception caught in code being profiled."""
1345
1345
1346 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1346 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1347
1347
1348 lims = opts.l
1348 lims = opts.l
1349 if lims:
1349 if lims:
1350 lims = [] # rebuild lims with ints/floats/strings
1350 lims = [] # rebuild lims with ints/floats/strings
1351 for lim in opts.l:
1351 for lim in opts.l:
1352 try:
1352 try:
1353 lims.append(int(lim))
1353 lims.append(int(lim))
1354 except ValueError:
1354 except ValueError:
1355 try:
1355 try:
1356 lims.append(float(lim))
1356 lims.append(float(lim))
1357 except ValueError:
1357 except ValueError:
1358 lims.append(lim)
1358 lims.append(lim)
1359
1359
1360 # Trap output.
1360 # Trap output.
1361 stdout_trap = StringIO()
1361 stdout_trap = StringIO()
1362
1362
1363 if hasattr(stats,'stream'):
1363 if hasattr(stats,'stream'):
1364 # In newer versions of python, the stats object has a 'stream'
1364 # In newer versions of python, the stats object has a 'stream'
1365 # attribute to write into.
1365 # attribute to write into.
1366 stats.stream = stdout_trap
1366 stats.stream = stdout_trap
1367 stats.print_stats(*lims)
1367 stats.print_stats(*lims)
1368 else:
1368 else:
1369 # For older versions, we manually redirect stdout during printing
1369 # For older versions, we manually redirect stdout during printing
1370 sys_stdout = sys.stdout
1370 sys_stdout = sys.stdout
1371 try:
1371 try:
1372 sys.stdout = stdout_trap
1372 sys.stdout = stdout_trap
1373 stats.print_stats(*lims)
1373 stats.print_stats(*lims)
1374 finally:
1374 finally:
1375 sys.stdout = sys_stdout
1375 sys.stdout = sys_stdout
1376
1376
1377 output = stdout_trap.getvalue()
1377 output = stdout_trap.getvalue()
1378 output = output.rstrip()
1378 output = output.rstrip()
1379
1379
1380 page(output,screen_lines=self.shell.rc.screen_length)
1380 page(output,screen_lines=self.shell.rc.screen_length)
1381 print sys_exit,
1381 print sys_exit,
1382
1382
1383 dump_file = opts.D[0]
1383 dump_file = opts.D[0]
1384 text_file = opts.T[0]
1384 text_file = opts.T[0]
1385 if dump_file:
1385 if dump_file:
1386 prof.dump_stats(dump_file)
1386 prof.dump_stats(dump_file)
1387 print '\n*** Profile stats marshalled to file',\
1387 print '\n*** Profile stats marshalled to file',\
1388 `dump_file`+'.',sys_exit
1388 `dump_file`+'.',sys_exit
1389 if text_file:
1389 if text_file:
1390 pfile = file(text_file,'w')
1390 pfile = file(text_file,'w')
1391 pfile.write(output)
1391 pfile.write(output)
1392 pfile.close()
1392 pfile.close()
1393 print '\n*** Profile printout saved to text file',\
1393 print '\n*** Profile printout saved to text file',\
1394 `text_file`+'.',sys_exit
1394 `text_file`+'.',sys_exit
1395
1395
1396 if opts.has_key('r'):
1396 if opts.has_key('r'):
1397 return stats
1397 return stats
1398 else:
1398 else:
1399 return None
1399 return None
1400
1400
1401 def magic_run(self, parameter_s ='',runner=None):
1401 def magic_run(self, parameter_s ='',runner=None):
1402 """Run the named file inside IPython as a program.
1402 """Run the named file inside IPython as a program.
1403
1403
1404 Usage:\\
1404 Usage:\\
1405 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1405 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1406
1406
1407 Parameters after the filename are passed as command-line arguments to
1407 Parameters after the filename are passed as command-line arguments to
1408 the program (put in sys.argv). Then, control returns to IPython's
1408 the program (put in sys.argv). Then, control returns to IPython's
1409 prompt.
1409 prompt.
1410
1410
1411 This is similar to running at a system prompt:\\
1411 This is similar to running at a system prompt:\\
1412 $ python file args\\
1412 $ python file args\\
1413 but with the advantage of giving you IPython's tracebacks, and of
1413 but with the advantage of giving you IPython's tracebacks, and of
1414 loading all variables into your interactive namespace for further use
1414 loading all variables into your interactive namespace for further use
1415 (unless -p is used, see below).
1415 (unless -p is used, see below).
1416
1416
1417 The file is executed in a namespace initially consisting only of
1417 The file is executed in a namespace initially consisting only of
1418 __name__=='__main__' and sys.argv constructed as indicated. It thus
1418 __name__=='__main__' and sys.argv constructed as indicated. It thus
1419 sees its environment as if it were being run as a stand-alone program
1419 sees its environment as if it were being run as a stand-alone program
1420 (except for sharing global objects such as previously imported
1420 (except for sharing global objects such as previously imported
1421 modules). But after execution, the IPython interactive namespace gets
1421 modules). But after execution, the IPython interactive namespace gets
1422 updated with all variables defined in the program (except for __name__
1422 updated with all variables defined in the program (except for __name__
1423 and sys.argv). This allows for very convenient loading of code for
1423 and sys.argv). This allows for very convenient loading of code for
1424 interactive work, while giving each program a 'clean sheet' to run in.
1424 interactive work, while giving each program a 'clean sheet' to run in.
1425
1425
1426 Options:
1426 Options:
1427
1427
1428 -n: __name__ is NOT set to '__main__', but to the running file's name
1428 -n: __name__ is NOT set to '__main__', but to the running file's name
1429 without extension (as python does under import). This allows running
1429 without extension (as python does under import). This allows running
1430 scripts and reloading the definitions in them without calling code
1430 scripts and reloading the definitions in them without calling code
1431 protected by an ' if __name__ == "__main__" ' clause.
1431 protected by an ' if __name__ == "__main__" ' clause.
1432
1432
1433 -i: run the file in IPython's namespace instead of an empty one. This
1433 -i: run the file in IPython's namespace instead of an empty one. This
1434 is useful if you are experimenting with code written in a text editor
1434 is useful if you are experimenting with code written in a text editor
1435 which depends on variables defined interactively.
1435 which depends on variables defined interactively.
1436
1436
1437 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1437 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1438 being run. This is particularly useful if IPython is being used to
1438 being run. This is particularly useful if IPython is being used to
1439 run unittests, which always exit with a sys.exit() call. In such
1439 run unittests, which always exit with a sys.exit() call. In such
1440 cases you are interested in the output of the test results, not in
1440 cases you are interested in the output of the test results, not in
1441 seeing a traceback of the unittest module.
1441 seeing a traceback of the unittest module.
1442
1442
1443 -t: print timing information at the end of the run. IPython will give
1443 -t: print timing information at the end of the run. IPython will give
1444 you an estimated CPU time consumption for your script, which under
1444 you an estimated CPU time consumption for your script, which under
1445 Unix uses the resource module to avoid the wraparound problems of
1445 Unix uses the resource module to avoid the wraparound problems of
1446 time.clock(). Under Unix, an estimate of time spent on system tasks
1446 time.clock(). Under Unix, an estimate of time spent on system tasks
1447 is also given (for Windows platforms this is reported as 0.0).
1447 is also given (for Windows platforms this is reported as 0.0).
1448
1448
1449 If -t is given, an additional -N<N> option can be given, where <N>
1449 If -t is given, an additional -N<N> option can be given, where <N>
1450 must be an integer indicating how many times you want the script to
1450 must be an integer indicating how many times you want the script to
1451 run. The final timing report will include total and per run results.
1451 run. The final timing report will include total and per run results.
1452
1452
1453 For example (testing the script uniq_stable.py):
1453 For example (testing the script uniq_stable.py):
1454
1454
1455 In [1]: run -t uniq_stable
1455 In [1]: run -t uniq_stable
1456
1456
1457 IPython CPU timings (estimated):\\
1457 IPython CPU timings (estimated):\\
1458 User : 0.19597 s.\\
1458 User : 0.19597 s.\\
1459 System: 0.0 s.\\
1459 System: 0.0 s.\\
1460
1460
1461 In [2]: run -t -N5 uniq_stable
1461 In [2]: run -t -N5 uniq_stable
1462
1462
1463 IPython CPU timings (estimated):\\
1463 IPython CPU timings (estimated):\\
1464 Total runs performed: 5\\
1464 Total runs performed: 5\\
1465 Times : Total Per run\\
1465 Times : Total Per run\\
1466 User : 0.910862 s, 0.1821724 s.\\
1466 User : 0.910862 s, 0.1821724 s.\\
1467 System: 0.0 s, 0.0 s.
1467 System: 0.0 s, 0.0 s.
1468
1468
1469 -d: run your program under the control of pdb, the Python debugger.
1469 -d: run your program under the control of pdb, the Python debugger.
1470 This allows you to execute your program step by step, watch variables,
1470 This allows you to execute your program step by step, watch variables,
1471 etc. Internally, what IPython does is similar to calling:
1471 etc. Internally, what IPython does is similar to calling:
1472
1472
1473 pdb.run('execfile("YOURFILENAME")')
1473 pdb.run('execfile("YOURFILENAME")')
1474
1474
1475 with a breakpoint set on line 1 of your file. You can change the line
1475 with a breakpoint set on line 1 of your file. You can change the line
1476 number for this automatic breakpoint to be <N> by using the -bN option
1476 number for this automatic breakpoint to be <N> by using the -bN option
1477 (where N must be an integer). For example:
1477 (where N must be an integer). For example:
1478
1478
1479 %run -d -b40 myscript
1479 %run -d -b40 myscript
1480
1480
1481 will set the first breakpoint at line 40 in myscript.py. Note that
1481 will set the first breakpoint at line 40 in myscript.py. Note that
1482 the first breakpoint must be set on a line which actually does
1482 the first breakpoint must be set on a line which actually does
1483 something (not a comment or docstring) for it to stop execution.
1483 something (not a comment or docstring) for it to stop execution.
1484
1484
1485 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1485 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1486 first enter 'c' (without qoutes) to start execution up to the first
1486 first enter 'c' (without qoutes) to start execution up to the first
1487 breakpoint.
1487 breakpoint.
1488
1488
1489 Entering 'help' gives information about the use of the debugger. You
1489 Entering 'help' gives information about the use of the debugger. You
1490 can easily see pdb's full documentation with "import pdb;pdb.help()"
1490 can easily see pdb's full documentation with "import pdb;pdb.help()"
1491 at a prompt.
1491 at a prompt.
1492
1492
1493 -p: run program under the control of the Python profiler module (which
1493 -p: run program under the control of the Python profiler module (which
1494 prints a detailed report of execution times, function calls, etc).
1494 prints a detailed report of execution times, function calls, etc).
1495
1495
1496 You can pass other options after -p which affect the behavior of the
1496 You can pass other options after -p which affect the behavior of the
1497 profiler itself. See the docs for %prun for details.
1497 profiler itself. See the docs for %prun for details.
1498
1498
1499 In this mode, the program's variables do NOT propagate back to the
1499 In this mode, the program's variables do NOT propagate back to the
1500 IPython interactive namespace (because they remain in the namespace
1500 IPython interactive namespace (because they remain in the namespace
1501 where the profiler executes them).
1501 where the profiler executes them).
1502
1502
1503 Internally this triggers a call to %prun, see its documentation for
1503 Internally this triggers a call to %prun, see its documentation for
1504 details on the options available specifically for profiling.
1504 details on the options available specifically for profiling.
1505
1505
1506 There is one special usage for which the text above doesn't apply:
1506 There is one special usage for which the text above doesn't apply:
1507 if the filename ends with .ipy, the file is run as ipython script,
1507 if the filename ends with .ipy, the file is run as ipython script,
1508 just as if the commands were written on IPython prompt.
1508 just as if the commands were written on IPython prompt.
1509 """
1509 """
1510
1510
1511 # get arguments and set sys.argv for program to be run.
1511 # get arguments and set sys.argv for program to be run.
1512 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1512 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1513 mode='list',list_all=1)
1513 mode='list',list_all=1)
1514
1514
1515 try:
1515 try:
1516 filename = get_py_filename(arg_lst[0])
1516 filename = get_py_filename(arg_lst[0])
1517 except IndexError:
1517 except IndexError:
1518 warn('you must provide at least a filename.')
1518 warn('you must provide at least a filename.')
1519 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1519 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1520 return
1520 return
1521 except IOError,msg:
1521 except IOError,msg:
1522 error(msg)
1522 error(msg)
1523 return
1523 return
1524
1524
1525 if filename.lower().endswith('.ipy'):
1525 if filename.lower().endswith('.ipy'):
1526 self.api.runlines(open(filename).read())
1526 self.api.runlines(open(filename).read())
1527 return
1527 return
1528
1528
1529 # Control the response to exit() calls made by the script being run
1529 # Control the response to exit() calls made by the script being run
1530 exit_ignore = opts.has_key('e')
1530 exit_ignore = opts.has_key('e')
1531
1531
1532 # Make sure that the running script gets a proper sys.argv as if it
1532 # Make sure that the running script gets a proper sys.argv as if it
1533 # were run from a system shell.
1533 # were run from a system shell.
1534 save_argv = sys.argv # save it for later restoring
1534 save_argv = sys.argv # save it for later restoring
1535 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1535 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1536
1536
1537 if opts.has_key('i'):
1537 if opts.has_key('i'):
1538 # Run in user's interactive namespace
1538 # Run in user's interactive namespace
1539 prog_ns = self.shell.user_ns
1539 prog_ns = self.shell.user_ns
1540 __name__save = self.shell.user_ns['__name__']
1540 __name__save = self.shell.user_ns['__name__']
1541 prog_ns['__name__'] = '__main__'
1541 prog_ns['__name__'] = '__main__'
1542 main_mod = FakeModule(prog_ns)
1542 main_mod = FakeModule(prog_ns)
1543 else:
1543 else:
1544 # Run in a fresh, empty namespace
1544 # Run in a fresh, empty namespace
1545 if opts.has_key('n'):
1545 if opts.has_key('n'):
1546 name = os.path.splitext(os.path.basename(filename))[0]
1546 name = os.path.splitext(os.path.basename(filename))[0]
1547 else:
1547 else:
1548 name = '__main__'
1548 name = '__main__'
1549 main_mod = FakeModule()
1549 main_mod = FakeModule()
1550 prog_ns = main_mod.__dict__
1550 prog_ns = main_mod.__dict__
1551 prog_ns['__name__'] = name
1551 prog_ns['__name__'] = name
1552 # The shell MUST hold a reference to main_mod so after %run exits,
1552 # The shell MUST hold a reference to main_mod so after %run exits,
1553 # the python deletion mechanism doesn't zero it out (leaving
1553 # the python deletion mechanism doesn't zero it out (leaving
1554 # dangling references)
1554 # dangling references)
1555 self.shell._user_main_modules.append(main_mod)
1555 self.shell._user_main_modules.append(main_mod)
1556
1556
1557 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1557 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1558 # set the __file__ global in the script's namespace
1558 # set the __file__ global in the script's namespace
1559 prog_ns['__file__'] = filename
1559 prog_ns['__file__'] = filename
1560
1560
1561 # pickle fix. See iplib for an explanation. But we need to make sure
1561 # pickle fix. See iplib for an explanation. But we need to make sure
1562 # that, if we overwrite __main__, we replace it at the end
1562 # that, if we overwrite __main__, we replace it at the end
1563 if prog_ns['__name__'] == '__main__':
1563 if prog_ns['__name__'] == '__main__':
1564 restore_main = sys.modules['__main__']
1564 restore_main = sys.modules['__main__']
1565 else:
1565 else:
1566 restore_main = False
1566 restore_main = False
1567
1567
1568 sys.modules[prog_ns['__name__']] = main_mod
1568 sys.modules[prog_ns['__name__']] = main_mod
1569
1569
1570 stats = None
1570 stats = None
1571 try:
1571 try:
1572 self.shell.savehist()
1572 self.shell.savehist()
1573
1573
1574 if opts.has_key('p'):
1574 if opts.has_key('p'):
1575 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1575 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1576 else:
1576 else:
1577 if opts.has_key('d'):
1577 if opts.has_key('d'):
1578 deb = Debugger.Pdb(self.shell.rc.colors)
1578 deb = Debugger.Pdb(self.shell.rc.colors)
1579 # reset Breakpoint state, which is moronically kept
1579 # reset Breakpoint state, which is moronically kept
1580 # in a class
1580 # in a class
1581 bdb.Breakpoint.next = 1
1581 bdb.Breakpoint.next = 1
1582 bdb.Breakpoint.bplist = {}
1582 bdb.Breakpoint.bplist = {}
1583 bdb.Breakpoint.bpbynumber = [None]
1583 bdb.Breakpoint.bpbynumber = [None]
1584 # Set an initial breakpoint to stop execution
1584 # Set an initial breakpoint to stop execution
1585 maxtries = 10
1585 maxtries = 10
1586 bp = int(opts.get('b',[1])[0])
1586 bp = int(opts.get('b',[1])[0])
1587 checkline = deb.checkline(filename,bp)
1587 checkline = deb.checkline(filename,bp)
1588 if not checkline:
1588 if not checkline:
1589 for bp in range(bp+1,bp+maxtries+1):
1589 for bp in range(bp+1,bp+maxtries+1):
1590 if deb.checkline(filename,bp):
1590 if deb.checkline(filename,bp):
1591 break
1591 break
1592 else:
1592 else:
1593 msg = ("\nI failed to find a valid line to set "
1593 msg = ("\nI failed to find a valid line to set "
1594 "a breakpoint\n"
1594 "a breakpoint\n"
1595 "after trying up to line: %s.\n"
1595 "after trying up to line: %s.\n"
1596 "Please set a valid breakpoint manually "
1596 "Please set a valid breakpoint manually "
1597 "with the -b option." % bp)
1597 "with the -b option." % bp)
1598 error(msg)
1598 error(msg)
1599 return
1599 return
1600 # if we find a good linenumber, set the breakpoint
1600 # if we find a good linenumber, set the breakpoint
1601 deb.do_break('%s:%s' % (filename,bp))
1601 deb.do_break('%s:%s' % (filename,bp))
1602 # Start file run
1602 # Start file run
1603 print "NOTE: Enter 'c' at the",
1603 print "NOTE: Enter 'c' at the",
1604 print "%s prompt to start your script." % deb.prompt
1604 print "%s prompt to start your script." % deb.prompt
1605 try:
1605 try:
1606 deb.run('execfile("%s")' % filename,prog_ns)
1606 deb.run('execfile("%s")' % filename,prog_ns)
1607
1607
1608 except:
1608 except:
1609 etype, value, tb = sys.exc_info()
1609 etype, value, tb = sys.exc_info()
1610 # Skip three frames in the traceback: the %run one,
1610 # Skip three frames in the traceback: the %run one,
1611 # one inside bdb.py, and the command-line typed by the
1611 # one inside bdb.py, and the command-line typed by the
1612 # user (run by exec in pdb itself).
1612 # user (run by exec in pdb itself).
1613 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1613 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1614 else:
1614 else:
1615 if runner is None:
1615 if runner is None:
1616 runner = self.shell.safe_execfile
1616 runner = self.shell.safe_execfile
1617 if opts.has_key('t'):
1617 if opts.has_key('t'):
1618 # timed execution
1618 # timed execution
1619 try:
1619 try:
1620 nruns = int(opts['N'][0])
1620 nruns = int(opts['N'][0])
1621 if nruns < 1:
1621 if nruns < 1:
1622 error('Number of runs must be >=1')
1622 error('Number of runs must be >=1')
1623 return
1623 return
1624 except (KeyError):
1624 except (KeyError):
1625 nruns = 1
1625 nruns = 1
1626 if nruns == 1:
1626 if nruns == 1:
1627 t0 = clock2()
1627 t0 = clock2()
1628 runner(filename,prog_ns,prog_ns,
1628 runner(filename,prog_ns,prog_ns,
1629 exit_ignore=exit_ignore)
1629 exit_ignore=exit_ignore)
1630 t1 = clock2()
1630 t1 = clock2()
1631 t_usr = t1[0]-t0[0]
1631 t_usr = t1[0]-t0[0]
1632 t_sys = t1[1]-t1[1]
1632 t_sys = t1[1]-t1[1]
1633 print "\nIPython CPU timings (estimated):"
1633 print "\nIPython CPU timings (estimated):"
1634 print " User : %10s s." % t_usr
1634 print " User : %10s s." % t_usr
1635 print " System: %10s s." % t_sys
1635 print " System: %10s s." % t_sys
1636 else:
1636 else:
1637 runs = range(nruns)
1637 runs = range(nruns)
1638 t0 = clock2()
1638 t0 = clock2()
1639 for nr in runs:
1639 for nr in runs:
1640 runner(filename,prog_ns,prog_ns,
1640 runner(filename,prog_ns,prog_ns,
1641 exit_ignore=exit_ignore)
1641 exit_ignore=exit_ignore)
1642 t1 = clock2()
1642 t1 = clock2()
1643 t_usr = t1[0]-t0[0]
1643 t_usr = t1[0]-t0[0]
1644 t_sys = t1[1]-t1[1]
1644 t_sys = t1[1]-t1[1]
1645 print "\nIPython CPU timings (estimated):"
1645 print "\nIPython CPU timings (estimated):"
1646 print "Total runs performed:",nruns
1646 print "Total runs performed:",nruns
1647 print " Times : %10s %10s" % ('Total','Per run')
1647 print " Times : %10s %10s" % ('Total','Per run')
1648 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1648 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1649 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1649 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1650
1650
1651 else:
1651 else:
1652 # regular execution
1652 # regular execution
1653 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1653 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1654 if opts.has_key('i'):
1654 if opts.has_key('i'):
1655 self.shell.user_ns['__name__'] = __name__save
1655 self.shell.user_ns['__name__'] = __name__save
1656 else:
1656 else:
1657 # update IPython interactive namespace
1657 # update IPython interactive namespace
1658 del prog_ns['__name__']
1658 del prog_ns['__name__']
1659 self.shell.user_ns.update(prog_ns)
1659 self.shell.user_ns.update(prog_ns)
1660 finally:
1660 finally:
1661 sys.argv = save_argv
1661 sys.argv = save_argv
1662 if restore_main:
1662 if restore_main:
1663 sys.modules['__main__'] = restore_main
1663 sys.modules['__main__'] = restore_main
1664 self.shell.reloadhist()
1664 self.shell.reloadhist()
1665
1665
1666 return stats
1666 return stats
1667
1667
1668 def magic_runlog(self, parameter_s =''):
1668 def magic_runlog(self, parameter_s =''):
1669 """Run files as logs.
1669 """Run files as logs.
1670
1670
1671 Usage:\\
1671 Usage:\\
1672 %runlog file1 file2 ...
1672 %runlog file1 file2 ...
1673
1673
1674 Run the named files (treating them as log files) in sequence inside
1674 Run the named files (treating them as log files) in sequence inside
1675 the interpreter, and return to the prompt. This is much slower than
1675 the interpreter, and return to the prompt. This is much slower than
1676 %run because each line is executed in a try/except block, but it
1676 %run because each line is executed in a try/except block, but it
1677 allows running files with syntax errors in them.
1677 allows running files with syntax errors in them.
1678
1678
1679 Normally IPython will guess when a file is one of its own logfiles, so
1679 Normally IPython will guess when a file is one of its own logfiles, so
1680 you can typically use %run even for logs. This shorthand allows you to
1680 you can typically use %run even for logs. This shorthand allows you to
1681 force any file to be treated as a log file."""
1681 force any file to be treated as a log file."""
1682
1682
1683 for f in parameter_s.split():
1683 for f in parameter_s.split():
1684 self.shell.safe_execfile(f,self.shell.user_ns,
1684 self.shell.safe_execfile(f,self.shell.user_ns,
1685 self.shell.user_ns,islog=1)
1685 self.shell.user_ns,islog=1)
1686
1686
1687 def magic_timeit(self, parameter_s =''):
1687 def magic_timeit(self, parameter_s =''):
1688 """Time execution of a Python statement or expression
1688 """Time execution of a Python statement or expression
1689
1689
1690 Usage:\\
1690 Usage:\\
1691 %timeit [-n<N> -r<R> [-t|-c]] statement
1691 %timeit [-n<N> -r<R> [-t|-c]] statement
1692
1692
1693 Time execution of a Python statement or expression using the timeit
1693 Time execution of a Python statement or expression using the timeit
1694 module.
1694 module.
1695
1695
1696 Options:
1696 Options:
1697 -n<N>: execute the given statement <N> times in a loop. If this value
1697 -n<N>: execute the given statement <N> times in a loop. If this value
1698 is not given, a fitting value is chosen.
1698 is not given, a fitting value is chosen.
1699
1699
1700 -r<R>: repeat the loop iteration <R> times and take the best result.
1700 -r<R>: repeat the loop iteration <R> times and take the best result.
1701 Default: 3
1701 Default: 3
1702
1702
1703 -t: use time.time to measure the time, which is the default on Unix.
1703 -t: use time.time to measure the time, which is the default on Unix.
1704 This function measures wall time.
1704 This function measures wall time.
1705
1705
1706 -c: use time.clock to measure the time, which is the default on
1706 -c: use time.clock to measure the time, which is the default on
1707 Windows and measures wall time. On Unix, resource.getrusage is used
1707 Windows and measures wall time. On Unix, resource.getrusage is used
1708 instead and returns the CPU user time.
1708 instead and returns the CPU user time.
1709
1709
1710 -p<P>: use a precision of <P> digits to display the timing result.
1710 -p<P>: use a precision of <P> digits to display the timing result.
1711 Default: 3
1711 Default: 3
1712
1712
1713
1713
1714 Examples:\\
1714 Examples:\\
1715 In [1]: %timeit pass
1715 In [1]: %timeit pass
1716 10000000 loops, best of 3: 53.3 ns per loop
1716 10000000 loops, best of 3: 53.3 ns per loop
1717
1717
1718 In [2]: u = None
1718 In [2]: u = None
1719
1719
1720 In [3]: %timeit u is None
1720 In [3]: %timeit u is None
1721 10000000 loops, best of 3: 184 ns per loop
1721 10000000 loops, best of 3: 184 ns per loop
1722
1722
1723 In [4]: %timeit -r 4 u == None
1723 In [4]: %timeit -r 4 u == None
1724 1000000 loops, best of 4: 242 ns per loop
1724 1000000 loops, best of 4: 242 ns per loop
1725
1725
1726 In [5]: import time
1726 In [5]: import time
1727
1727
1728 In [6]: %timeit -n1 time.sleep(2)
1728 In [6]: %timeit -n1 time.sleep(2)
1729 1 loops, best of 3: 2 s per loop
1729 1 loops, best of 3: 2 s per loop
1730
1730
1731
1731
1732 The times reported by %timeit will be slightly higher than those
1732 The times reported by %timeit will be slightly higher than those
1733 reported by the timeit.py script when variables are accessed. This is
1733 reported by the timeit.py script when variables are accessed. This is
1734 due to the fact that %timeit executes the statement in the namespace
1734 due to the fact that %timeit executes the statement in the namespace
1735 of the shell, compared with timeit.py, which uses a single setup
1735 of the shell, compared with timeit.py, which uses a single setup
1736 statement to import function or create variables. Generally, the bias
1736 statement to import function or create variables. Generally, the bias
1737 does not matter as long as results from timeit.py are not mixed with
1737 does not matter as long as results from timeit.py are not mixed with
1738 those from %timeit."""
1738 those from %timeit."""
1739
1739
1740 import timeit
1740 import timeit
1741 import math
1741 import math
1742
1742
1743 units = ["s", "ms", "\xc2\xb5s", "ns"]
1743 units = ["s", "ms", "\xc2\xb5s", "ns"]
1744 scaling = [1, 1e3, 1e6, 1e9]
1744 scaling = [1, 1e3, 1e6, 1e9]
1745
1745
1746 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1746 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1747 posix=False)
1747 posix=False)
1748 if stmt == "":
1748 if stmt == "":
1749 return
1749 return
1750 timefunc = timeit.default_timer
1750 timefunc = timeit.default_timer
1751 number = int(getattr(opts, "n", 0))
1751 number = int(getattr(opts, "n", 0))
1752 repeat = int(getattr(opts, "r", timeit.default_repeat))
1752 repeat = int(getattr(opts, "r", timeit.default_repeat))
1753 precision = int(getattr(opts, "p", 3))
1753 precision = int(getattr(opts, "p", 3))
1754 if hasattr(opts, "t"):
1754 if hasattr(opts, "t"):
1755 timefunc = time.time
1755 timefunc = time.time
1756 if hasattr(opts, "c"):
1756 if hasattr(opts, "c"):
1757 timefunc = clock
1757 timefunc = clock
1758
1758
1759 timer = timeit.Timer(timer=timefunc)
1759 timer = timeit.Timer(timer=timefunc)
1760 # this code has tight coupling to the inner workings of timeit.Timer,
1760 # this code has tight coupling to the inner workings of timeit.Timer,
1761 # but is there a better way to achieve that the code stmt has access
1761 # but is there a better way to achieve that the code stmt has access
1762 # to the shell namespace?
1762 # to the shell namespace?
1763
1763
1764 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1764 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1765 'setup': "pass"}
1765 'setup': "pass"}
1766 # Track compilation time so it can be reported if too long
1766 # Track compilation time so it can be reported if too long
1767 # Minimum time above which compilation time will be reported
1767 # Minimum time above which compilation time will be reported
1768 tc_min = 0.1
1768 tc_min = 0.1
1769
1769
1770 t0 = clock()
1770 t0 = clock()
1771 code = compile(src, "<magic-timeit>", "exec")
1771 code = compile(src, "<magic-timeit>", "exec")
1772 tc = clock()-t0
1772 tc = clock()-t0
1773
1773
1774 ns = {}
1774 ns = {}
1775 exec code in self.shell.user_ns, ns
1775 exec code in self.shell.user_ns, ns
1776 timer.inner = ns["inner"]
1776 timer.inner = ns["inner"]
1777
1777
1778 if number == 0:
1778 if number == 0:
1779 # determine number so that 0.2 <= total time < 2.0
1779 # determine number so that 0.2 <= total time < 2.0
1780 number = 1
1780 number = 1
1781 for i in range(1, 10):
1781 for i in range(1, 10):
1782 number *= 10
1782 number *= 10
1783 if timer.timeit(number) >= 0.2:
1783 if timer.timeit(number) >= 0.2:
1784 break
1784 break
1785
1785
1786 best = min(timer.repeat(repeat, number)) / number
1786 best = min(timer.repeat(repeat, number)) / number
1787
1787
1788 if best > 0.0:
1788 if best > 0.0:
1789 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1789 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1790 else:
1790 else:
1791 order = 3
1791 order = 3
1792 print "%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1792 print "%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1793 precision,
1793 precision,
1794 best * scaling[order],
1794 best * scaling[order],
1795 units[order])
1795 units[order])
1796 if tc > tc_min:
1796 if tc > tc_min:
1797 print "Compiler time: %.2f s" % tc
1797 print "Compiler time: %.2f s" % tc
1798
1798
1799 def magic_time(self,parameter_s = ''):
1799 def magic_time(self,parameter_s = ''):
1800 """Time execution of a Python statement or expression.
1800 """Time execution of a Python statement or expression.
1801
1801
1802 The CPU and wall clock times are printed, and the value of the
1802 The CPU and wall clock times are printed, and the value of the
1803 expression (if any) is returned. Note that under Win32, system time
1803 expression (if any) is returned. Note that under Win32, system time
1804 is always reported as 0, since it can not be measured.
1804 is always reported as 0, since it can not be measured.
1805
1805
1806 This function provides very basic timing functionality. In Python
1806 This function provides very basic timing functionality. In Python
1807 2.3, the timeit module offers more control and sophistication, so this
1807 2.3, the timeit module offers more control and sophistication, so this
1808 could be rewritten to use it (patches welcome).
1808 could be rewritten to use it (patches welcome).
1809
1809
1810 Some examples:
1810 Some examples:
1811
1811
1812 In [1]: time 2**128
1812 In [1]: time 2**128
1813 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1813 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1814 Wall time: 0.00
1814 Wall time: 0.00
1815 Out[1]: 340282366920938463463374607431768211456L
1815 Out[1]: 340282366920938463463374607431768211456L
1816
1816
1817 In [2]: n = 1000000
1817 In [2]: n = 1000000
1818
1818
1819 In [3]: time sum(range(n))
1819 In [3]: time sum(range(n))
1820 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1820 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1821 Wall time: 1.37
1821 Wall time: 1.37
1822 Out[3]: 499999500000L
1822 Out[3]: 499999500000L
1823
1823
1824 In [4]: time print 'hello world'
1824 In [4]: time print 'hello world'
1825 hello world
1825 hello world
1826 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1826 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1827 Wall time: 0.00
1827 Wall time: 0.00
1828
1828
1829 Note that the time needed by Python to compile the given expression
1829 Note that the time needed by Python to compile the given expression
1830 will be reported if it is more than 0.1s. In this example, the
1830 will be reported if it is more than 0.1s. In this example, the
1831 actual exponentiation is done by Python at compilation time, so while
1831 actual exponentiation is done by Python at compilation time, so while
1832 the expression can take a noticeable amount of time to compute, that
1832 the expression can take a noticeable amount of time to compute, that
1833 time is purely due to the compilation:
1833 time is purely due to the compilation:
1834
1834
1835 In [5]: time 3**9999;
1835 In [5]: time 3**9999;
1836 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1836 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1837 Wall time: 0.00 s
1837 Wall time: 0.00 s
1838
1838
1839 In [6]: time 3**999999;
1839 In [6]: time 3**999999;
1840 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1840 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1841 Wall time: 0.00 s
1841 Wall time: 0.00 s
1842 Compiler : 0.78 s
1842 Compiler : 0.78 s
1843 """
1843 """
1844
1844
1845 # fail immediately if the given expression can't be compiled
1845 # fail immediately if the given expression can't be compiled
1846
1846
1847 expr = self.shell.prefilter(parameter_s,False)
1847 expr = self.shell.prefilter(parameter_s,False)
1848
1848
1849 # Minimum time above which compilation time will be reported
1849 # Minimum time above which compilation time will be reported
1850 tc_min = 0.1
1850 tc_min = 0.1
1851
1851
1852 try:
1852 try:
1853 mode = 'eval'
1853 mode = 'eval'
1854 t0 = clock()
1854 t0 = clock()
1855 code = compile(expr,'<timed eval>',mode)
1855 code = compile(expr,'<timed eval>',mode)
1856 tc = clock()-t0
1856 tc = clock()-t0
1857 except SyntaxError:
1857 except SyntaxError:
1858 mode = 'exec'
1858 mode = 'exec'
1859 t0 = clock()
1859 t0 = clock()
1860 code = compile(expr,'<timed exec>',mode)
1860 code = compile(expr,'<timed exec>',mode)
1861 tc = clock()-t0
1861 tc = clock()-t0
1862 # skew measurement as little as possible
1862 # skew measurement as little as possible
1863 glob = self.shell.user_ns
1863 glob = self.shell.user_ns
1864 clk = clock2
1864 clk = clock2
1865 wtime = time.time
1865 wtime = time.time
1866 # time execution
1866 # time execution
1867 wall_st = wtime()
1867 wall_st = wtime()
1868 if mode=='eval':
1868 if mode=='eval':
1869 st = clk()
1869 st = clk()
1870 out = eval(code,glob)
1870 out = eval(code,glob)
1871 end = clk()
1871 end = clk()
1872 else:
1872 else:
1873 st = clk()
1873 st = clk()
1874 exec code in glob
1874 exec code in glob
1875 end = clk()
1875 end = clk()
1876 out = None
1876 out = None
1877 wall_end = wtime()
1877 wall_end = wtime()
1878 # Compute actual times and report
1878 # Compute actual times and report
1879 wall_time = wall_end-wall_st
1879 wall_time = wall_end-wall_st
1880 cpu_user = end[0]-st[0]
1880 cpu_user = end[0]-st[0]
1881 cpu_sys = end[1]-st[1]
1881 cpu_sys = end[1]-st[1]
1882 cpu_tot = cpu_user+cpu_sys
1882 cpu_tot = cpu_user+cpu_sys
1883 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1883 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1884 (cpu_user,cpu_sys,cpu_tot)
1884 (cpu_user,cpu_sys,cpu_tot)
1885 print "Wall time: %.2f s" % wall_time
1885 print "Wall time: %.2f s" % wall_time
1886 if tc > tc_min:
1886 if tc > tc_min:
1887 print "Compiler : %.2f s" % tc
1887 print "Compiler : %.2f s" % tc
1888 return out
1888 return out
1889
1889
1890 def magic_macro(self,parameter_s = ''):
1890 def magic_macro(self,parameter_s = ''):
1891 """Define a set of input lines as a macro for future re-execution.
1891 """Define a set of input lines as a macro for future re-execution.
1892
1892
1893 Usage:\\
1893 Usage:\\
1894 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1894 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1895
1895
1896 Options:
1896 Options:
1897
1897
1898 -r: use 'raw' input. By default, the 'processed' history is used,
1898 -r: use 'raw' input. By default, the 'processed' history is used,
1899 so that magics are loaded in their transformed version to valid
1899 so that magics are loaded in their transformed version to valid
1900 Python. If this option is given, the raw input as typed as the
1900 Python. If this option is given, the raw input as typed as the
1901 command line is used instead.
1901 command line is used instead.
1902
1902
1903 This will define a global variable called `name` which is a string
1903 This will define a global variable called `name` which is a string
1904 made of joining the slices and lines you specify (n1,n2,... numbers
1904 made of joining the slices and lines you specify (n1,n2,... numbers
1905 above) from your input history into a single string. This variable
1905 above) from your input history into a single string. This variable
1906 acts like an automatic function which re-executes those lines as if
1906 acts like an automatic function which re-executes those lines as if
1907 you had typed them. You just type 'name' at the prompt and the code
1907 you had typed them. You just type 'name' at the prompt and the code
1908 executes.
1908 executes.
1909
1909
1910 The notation for indicating number ranges is: n1-n2 means 'use line
1910 The notation for indicating number ranges is: n1-n2 means 'use line
1911 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1911 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1912 using the lines numbered 5,6 and 7.
1912 using the lines numbered 5,6 and 7.
1913
1913
1914 Note: as a 'hidden' feature, you can also use traditional python slice
1914 Note: as a 'hidden' feature, you can also use traditional python slice
1915 notation, where N:M means numbers N through M-1.
1915 notation, where N:M means numbers N through M-1.
1916
1916
1917 For example, if your history contains (%hist prints it):
1917 For example, if your history contains (%hist prints it):
1918
1918
1919 44: x=1\\
1919 44: x=1\\
1920 45: y=3\\
1920 45: y=3\\
1921 46: z=x+y\\
1921 46: z=x+y\\
1922 47: print x\\
1922 47: print x\\
1923 48: a=5\\
1923 48: a=5\\
1924 49: print 'x',x,'y',y\\
1924 49: print 'x',x,'y',y\\
1925
1925
1926 you can create a macro with lines 44 through 47 (included) and line 49
1926 you can create a macro with lines 44 through 47 (included) and line 49
1927 called my_macro with:
1927 called my_macro with:
1928
1928
1929 In [51]: %macro my_macro 44-47 49
1929 In [51]: %macro my_macro 44-47 49
1930
1930
1931 Now, typing `my_macro` (without quotes) will re-execute all this code
1931 Now, typing `my_macro` (without quotes) will re-execute all this code
1932 in one pass.
1932 in one pass.
1933
1933
1934 You don't need to give the line-numbers in order, and any given line
1934 You don't need to give the line-numbers in order, and any given line
1935 number can appear multiple times. You can assemble macros with any
1935 number can appear multiple times. You can assemble macros with any
1936 lines from your input history in any order.
1936 lines from your input history in any order.
1937
1937
1938 The macro is a simple object which holds its value in an attribute,
1938 The macro is a simple object which holds its value in an attribute,
1939 but IPython's display system checks for macros and executes them as
1939 but IPython's display system checks for macros and executes them as
1940 code instead of printing them when you type their name.
1940 code instead of printing them when you type their name.
1941
1941
1942 You can view a macro's contents by explicitly printing it with:
1942 You can view a macro's contents by explicitly printing it with:
1943
1943
1944 'print macro_name'.
1944 'print macro_name'.
1945
1945
1946 For one-off cases which DON'T contain magic function calls in them you
1946 For one-off cases which DON'T contain magic function calls in them you
1947 can obtain similar results by explicitly executing slices from your
1947 can obtain similar results by explicitly executing slices from your
1948 input history with:
1948 input history with:
1949
1949
1950 In [60]: exec In[44:48]+In[49]"""
1950 In [60]: exec In[44:48]+In[49]"""
1951
1951
1952 opts,args = self.parse_options(parameter_s,'r',mode='list')
1952 opts,args = self.parse_options(parameter_s,'r',mode='list')
1953 if not args:
1953 if not args:
1954 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
1954 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
1955 macs.sort()
1955 macs.sort()
1956 return macs
1956 return macs
1957 if len(args) == 1:
1957 if len(args) == 1:
1958 raise UsageError(
1958 raise UsageError(
1959 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1959 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1960 name,ranges = args[0], args[1:]
1960 name,ranges = args[0], args[1:]
1961
1961
1962 #print 'rng',ranges # dbg
1962 #print 'rng',ranges # dbg
1963 lines = self.extract_input_slices(ranges,opts.has_key('r'))
1963 lines = self.extract_input_slices(ranges,opts.has_key('r'))
1964 macro = Macro(lines)
1964 macro = Macro(lines)
1965 self.shell.user_ns.update({name:macro})
1965 self.shell.user_ns.update({name:macro})
1966 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1966 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1967 print 'Macro contents:'
1967 print 'Macro contents:'
1968 print macro,
1968 print macro,
1969
1969
1970 def magic_save(self,parameter_s = ''):
1970 def magic_save(self,parameter_s = ''):
1971 """Save a set of lines to a given filename.
1971 """Save a set of lines to a given filename.
1972
1972
1973 Usage:\\
1973 Usage:\\
1974 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
1974 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
1975
1975
1976 Options:
1976 Options:
1977
1977
1978 -r: use 'raw' input. By default, the 'processed' history is used,
1978 -r: use 'raw' input. By default, the 'processed' history is used,
1979 so that magics are loaded in their transformed version to valid
1979 so that magics are loaded in their transformed version to valid
1980 Python. If this option is given, the raw input as typed as the
1980 Python. If this option is given, the raw input as typed as the
1981 command line is used instead.
1981 command line is used instead.
1982
1982
1983 This function uses the same syntax as %macro for line extraction, but
1983 This function uses the same syntax as %macro for line extraction, but
1984 instead of creating a macro it saves the resulting string to the
1984 instead of creating a macro it saves the resulting string to the
1985 filename you specify.
1985 filename you specify.
1986
1986
1987 It adds a '.py' extension to the file if you don't do so yourself, and
1987 It adds a '.py' extension to the file if you don't do so yourself, and
1988 it asks for confirmation before overwriting existing files."""
1988 it asks for confirmation before overwriting existing files."""
1989
1989
1990 opts,args = self.parse_options(parameter_s,'r',mode='list')
1990 opts,args = self.parse_options(parameter_s,'r',mode='list')
1991 fname,ranges = args[0], args[1:]
1991 fname,ranges = args[0], args[1:]
1992 if not fname.endswith('.py'):
1992 if not fname.endswith('.py'):
1993 fname += '.py'
1993 fname += '.py'
1994 if os.path.isfile(fname):
1994 if os.path.isfile(fname):
1995 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1995 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1996 if ans.lower() not in ['y','yes']:
1996 if ans.lower() not in ['y','yes']:
1997 print 'Operation cancelled.'
1997 print 'Operation cancelled.'
1998 return
1998 return
1999 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
1999 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2000 f = file(fname,'w')
2000 f = file(fname,'w')
2001 f.write(cmds)
2001 f.write(cmds)
2002 f.close()
2002 f.close()
2003 print 'The following commands were written to file `%s`:' % fname
2003 print 'The following commands were written to file `%s`:' % fname
2004 print cmds
2004 print cmds
2005
2005
2006 def _edit_macro(self,mname,macro):
2006 def _edit_macro(self,mname,macro):
2007 """open an editor with the macro data in a file"""
2007 """open an editor with the macro data in a file"""
2008 filename = self.shell.mktempfile(macro.value)
2008 filename = self.shell.mktempfile(macro.value)
2009 self.shell.hooks.editor(filename)
2009 self.shell.hooks.editor(filename)
2010
2010
2011 # and make a new macro object, to replace the old one
2011 # and make a new macro object, to replace the old one
2012 mfile = open(filename)
2012 mfile = open(filename)
2013 mvalue = mfile.read()
2013 mvalue = mfile.read()
2014 mfile.close()
2014 mfile.close()
2015 self.shell.user_ns[mname] = Macro(mvalue)
2015 self.shell.user_ns[mname] = Macro(mvalue)
2016
2016
2017 def magic_ed(self,parameter_s=''):
2017 def magic_ed(self,parameter_s=''):
2018 """Alias to %edit."""
2018 """Alias to %edit."""
2019 return self.magic_edit(parameter_s)
2019 return self.magic_edit(parameter_s)
2020
2020
2021 def magic_edit(self,parameter_s='',last_call=['','']):
2021 def magic_edit(self,parameter_s='',last_call=['','']):
2022 """Bring up an editor and execute the resulting code.
2022 """Bring up an editor and execute the resulting code.
2023
2023
2024 Usage:
2024 Usage:
2025 %edit [options] [args]
2025 %edit [options] [args]
2026
2026
2027 %edit runs IPython's editor hook. The default version of this hook is
2027 %edit runs IPython's editor hook. The default version of this hook is
2028 set to call the __IPYTHON__.rc.editor command. This is read from your
2028 set to call the __IPYTHON__.rc.editor command. This is read from your
2029 environment variable $EDITOR. If this isn't found, it will default to
2029 environment variable $EDITOR. If this isn't found, it will default to
2030 vi under Linux/Unix and to notepad under Windows. See the end of this
2030 vi under Linux/Unix and to notepad under Windows. See the end of this
2031 docstring for how to change the editor hook.
2031 docstring for how to change the editor hook.
2032
2032
2033 You can also set the value of this editor via the command line option
2033 You can also set the value of this editor via the command line option
2034 '-editor' or in your ipythonrc file. This is useful if you wish to use
2034 '-editor' or in your ipythonrc file. This is useful if you wish to use
2035 specifically for IPython an editor different from your typical default
2035 specifically for IPython an editor different from your typical default
2036 (and for Windows users who typically don't set environment variables).
2036 (and for Windows users who typically don't set environment variables).
2037
2037
2038 This command allows you to conveniently edit multi-line code right in
2038 This command allows you to conveniently edit multi-line code right in
2039 your IPython session.
2039 your IPython session.
2040
2040
2041 If called without arguments, %edit opens up an empty editor with a
2041 If called without arguments, %edit opens up an empty editor with a
2042 temporary file and will execute the contents of this file when you
2042 temporary file and will execute the contents of this file when you
2043 close it (don't forget to save it!).
2043 close it (don't forget to save it!).
2044
2044
2045
2045
2046 Options:
2046 Options:
2047
2047
2048 -n <number>: open the editor at a specified line number. By default,
2048 -n <number>: open the editor at a specified line number. By default,
2049 the IPython editor hook uses the unix syntax 'editor +N filename', but
2049 the IPython editor hook uses the unix syntax 'editor +N filename', but
2050 you can configure this by providing your own modified hook if your
2050 you can configure this by providing your own modified hook if your
2051 favorite editor supports line-number specifications with a different
2051 favorite editor supports line-number specifications with a different
2052 syntax.
2052 syntax.
2053
2053
2054 -p: this will call the editor with the same data as the previous time
2054 -p: this will call the editor with the same data as the previous time
2055 it was used, regardless of how long ago (in your current session) it
2055 it was used, regardless of how long ago (in your current session) it
2056 was.
2056 was.
2057
2057
2058 -r: use 'raw' input. This option only applies to input taken from the
2058 -r: use 'raw' input. This option only applies to input taken from the
2059 user's history. By default, the 'processed' history is used, so that
2059 user's history. By default, the 'processed' history is used, so that
2060 magics are loaded in their transformed version to valid Python. If
2060 magics are loaded in their transformed version to valid Python. If
2061 this option is given, the raw input as typed as the command line is
2061 this option is given, the raw input as typed as the command line is
2062 used instead. When you exit the editor, it will be executed by
2062 used instead. When you exit the editor, it will be executed by
2063 IPython's own processor.
2063 IPython's own processor.
2064
2064
2065 -x: do not execute the edited code immediately upon exit. This is
2065 -x: do not execute the edited code immediately upon exit. This is
2066 mainly useful if you are editing programs which need to be called with
2066 mainly useful if you are editing programs which need to be called with
2067 command line arguments, which you can then do using %run.
2067 command line arguments, which you can then do using %run.
2068
2068
2069
2069
2070 Arguments:
2070 Arguments:
2071
2071
2072 If arguments are given, the following possibilites exist:
2072 If arguments are given, the following possibilites exist:
2073
2073
2074 - The arguments are numbers or pairs of colon-separated numbers (like
2074 - The arguments are numbers or pairs of colon-separated numbers (like
2075 1 4:8 9). These are interpreted as lines of previous input to be
2075 1 4:8 9). These are interpreted as lines of previous input to be
2076 loaded into the editor. The syntax is the same of the %macro command.
2076 loaded into the editor. The syntax is the same of the %macro command.
2077
2077
2078 - If the argument doesn't start with a number, it is evaluated as a
2078 - If the argument doesn't start with a number, it is evaluated as a
2079 variable and its contents loaded into the editor. You can thus edit
2079 variable and its contents loaded into the editor. You can thus edit
2080 any string which contains python code (including the result of
2080 any string which contains python code (including the result of
2081 previous edits).
2081 previous edits).
2082
2082
2083 - If the argument is the name of an object (other than a string),
2083 - If the argument is the name of an object (other than a string),
2084 IPython will try to locate the file where it was defined and open the
2084 IPython will try to locate the file where it was defined and open the
2085 editor at the point where it is defined. You can use `%edit function`
2085 editor at the point where it is defined. You can use `%edit function`
2086 to load an editor exactly at the point where 'function' is defined,
2086 to load an editor exactly at the point where 'function' is defined,
2087 edit it and have the file be executed automatically.
2087 edit it and have the file be executed automatically.
2088
2088
2089 If the object is a macro (see %macro for details), this opens up your
2089 If the object is a macro (see %macro for details), this opens up your
2090 specified editor with a temporary file containing the macro's data.
2090 specified editor with a temporary file containing the macro's data.
2091 Upon exit, the macro is reloaded with the contents of the file.
2091 Upon exit, the macro is reloaded with the contents of the file.
2092
2092
2093 Note: opening at an exact line is only supported under Unix, and some
2093 Note: opening at an exact line is only supported under Unix, and some
2094 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2094 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2095 '+NUMBER' parameter necessary for this feature. Good editors like
2095 '+NUMBER' parameter necessary for this feature. Good editors like
2096 (X)Emacs, vi, jed, pico and joe all do.
2096 (X)Emacs, vi, jed, pico and joe all do.
2097
2097
2098 - If the argument is not found as a variable, IPython will look for a
2098 - If the argument is not found as a variable, IPython will look for a
2099 file with that name (adding .py if necessary) and load it into the
2099 file with that name (adding .py if necessary) and load it into the
2100 editor. It will execute its contents with execfile() when you exit,
2100 editor. It will execute its contents with execfile() when you exit,
2101 loading any code in the file into your interactive namespace.
2101 loading any code in the file into your interactive namespace.
2102
2102
2103 After executing your code, %edit will return as output the code you
2103 After executing your code, %edit will return as output the code you
2104 typed in the editor (except when it was an existing file). This way
2104 typed in the editor (except when it was an existing file). This way
2105 you can reload the code in further invocations of %edit as a variable,
2105 you can reload the code in further invocations of %edit as a variable,
2106 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2106 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2107 the output.
2107 the output.
2108
2108
2109 Note that %edit is also available through the alias %ed.
2109 Note that %edit is also available through the alias %ed.
2110
2110
2111 This is an example of creating a simple function inside the editor and
2111 This is an example of creating a simple function inside the editor and
2112 then modifying it. First, start up the editor:
2112 then modifying it. First, start up the editor:
2113
2113
2114 In [1]: ed\\
2114 In [1]: ed\\
2115 Editing... done. Executing edited code...\\
2115 Editing... done. Executing edited code...\\
2116 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
2116 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
2117
2117
2118 We can then call the function foo():
2118 We can then call the function foo():
2119
2119
2120 In [2]: foo()\\
2120 In [2]: foo()\\
2121 foo() was defined in an editing session
2121 foo() was defined in an editing session
2122
2122
2123 Now we edit foo. IPython automatically loads the editor with the
2123 Now we edit foo. IPython automatically loads the editor with the
2124 (temporary) file where foo() was previously defined:
2124 (temporary) file where foo() was previously defined:
2125
2125
2126 In [3]: ed foo\\
2126 In [3]: ed foo\\
2127 Editing... done. Executing edited code...
2127 Editing... done. Executing edited code...
2128
2128
2129 And if we call foo() again we get the modified version:
2129 And if we call foo() again we get the modified version:
2130
2130
2131 In [4]: foo()\\
2131 In [4]: foo()\\
2132 foo() has now been changed!
2132 foo() has now been changed!
2133
2133
2134 Here is an example of how to edit a code snippet successive
2134 Here is an example of how to edit a code snippet successive
2135 times. First we call the editor:
2135 times. First we call the editor:
2136
2136
2137 In [8]: ed\\
2137 In [8]: ed\\
2138 Editing... done. Executing edited code...\\
2138 Editing... done. Executing edited code...\\
2139 hello\\
2139 hello\\
2140 Out[8]: "print 'hello'\\n"
2140 Out[8]: "print 'hello'\\n"
2141
2141
2142 Now we call it again with the previous output (stored in _):
2142 Now we call it again with the previous output (stored in _):
2143
2143
2144 In [9]: ed _\\
2144 In [9]: ed _\\
2145 Editing... done. Executing edited code...\\
2145 Editing... done. Executing edited code...\\
2146 hello world\\
2146 hello world\\
2147 Out[9]: "print 'hello world'\\n"
2147 Out[9]: "print 'hello world'\\n"
2148
2148
2149 Now we call it with the output #8 (stored in _8, also as Out[8]):
2149 Now we call it with the output #8 (stored in _8, also as Out[8]):
2150
2150
2151 In [10]: ed _8\\
2151 In [10]: ed _8\\
2152 Editing... done. Executing edited code...\\
2152 Editing... done. Executing edited code...\\
2153 hello again\\
2153 hello again\\
2154 Out[10]: "print 'hello again'\\n"
2154 Out[10]: "print 'hello again'\\n"
2155
2155
2156
2156
2157 Changing the default editor hook:
2157 Changing the default editor hook:
2158
2158
2159 If you wish to write your own editor hook, you can put it in a
2159 If you wish to write your own editor hook, you can put it in a
2160 configuration file which you load at startup time. The default hook
2160 configuration file which you load at startup time. The default hook
2161 is defined in the IPython.hooks module, and you can use that as a
2161 is defined in the IPython.hooks module, and you can use that as a
2162 starting example for further modifications. That file also has
2162 starting example for further modifications. That file also has
2163 general instructions on how to set a new hook for use once you've
2163 general instructions on how to set a new hook for use once you've
2164 defined it."""
2164 defined it."""
2165
2165
2166 # FIXME: This function has become a convoluted mess. It needs a
2166 # FIXME: This function has become a convoluted mess. It needs a
2167 # ground-up rewrite with clean, simple logic.
2167 # ground-up rewrite with clean, simple logic.
2168
2168
2169 def make_filename(arg):
2169 def make_filename(arg):
2170 "Make a filename from the given args"
2170 "Make a filename from the given args"
2171 try:
2171 try:
2172 filename = get_py_filename(arg)
2172 filename = get_py_filename(arg)
2173 except IOError:
2173 except IOError:
2174 if args.endswith('.py'):
2174 if args.endswith('.py'):
2175 filename = arg
2175 filename = arg
2176 else:
2176 else:
2177 filename = None
2177 filename = None
2178 return filename
2178 return filename
2179
2179
2180 # custom exceptions
2180 # custom exceptions
2181 class DataIsObject(Exception): pass
2181 class DataIsObject(Exception): pass
2182
2182
2183 opts,args = self.parse_options(parameter_s,'prxn:')
2183 opts,args = self.parse_options(parameter_s,'prxn:')
2184 # Set a few locals from the options for convenience:
2184 # Set a few locals from the options for convenience:
2185 opts_p = opts.has_key('p')
2185 opts_p = opts.has_key('p')
2186 opts_r = opts.has_key('r')
2186 opts_r = opts.has_key('r')
2187
2187
2188 # Default line number value
2188 # Default line number value
2189 lineno = opts.get('n',None)
2189 lineno = opts.get('n',None)
2190
2190
2191 if opts_p:
2191 if opts_p:
2192 args = '_%s' % last_call[0]
2192 args = '_%s' % last_call[0]
2193 if not self.shell.user_ns.has_key(args):
2193 if not self.shell.user_ns.has_key(args):
2194 args = last_call[1]
2194 args = last_call[1]
2195
2195
2196 # use last_call to remember the state of the previous call, but don't
2196 # use last_call to remember the state of the previous call, but don't
2197 # let it be clobbered by successive '-p' calls.
2197 # let it be clobbered by successive '-p' calls.
2198 try:
2198 try:
2199 last_call[0] = self.shell.outputcache.prompt_count
2199 last_call[0] = self.shell.outputcache.prompt_count
2200 if not opts_p:
2200 if not opts_p:
2201 last_call[1] = parameter_s
2201 last_call[1] = parameter_s
2202 except:
2202 except:
2203 pass
2203 pass
2204
2204
2205 # by default this is done with temp files, except when the given
2205 # by default this is done with temp files, except when the given
2206 # arg is a filename
2206 # arg is a filename
2207 use_temp = 1
2207 use_temp = 1
2208
2208
2209 if re.match(r'\d',args):
2209 if re.match(r'\d',args):
2210 # Mode where user specifies ranges of lines, like in %macro.
2210 # Mode where user specifies ranges of lines, like in %macro.
2211 # This means that you can't edit files whose names begin with
2211 # This means that you can't edit files whose names begin with
2212 # numbers this way. Tough.
2212 # numbers this way. Tough.
2213 ranges = args.split()
2213 ranges = args.split()
2214 data = ''.join(self.extract_input_slices(ranges,opts_r))
2214 data = ''.join(self.extract_input_slices(ranges,opts_r))
2215 elif args.endswith('.py'):
2215 elif args.endswith('.py'):
2216 filename = make_filename(args)
2216 filename = make_filename(args)
2217 data = ''
2217 data = ''
2218 use_temp = 0
2218 use_temp = 0
2219 elif args:
2219 elif args:
2220 try:
2220 try:
2221 # Load the parameter given as a variable. If not a string,
2221 # Load the parameter given as a variable. If not a string,
2222 # process it as an object instead (below)
2222 # process it as an object instead (below)
2223
2223
2224 #print '*** args',args,'type',type(args) # dbg
2224 #print '*** args',args,'type',type(args) # dbg
2225 data = eval(args,self.shell.user_ns)
2225 data = eval(args,self.shell.user_ns)
2226 if not type(data) in StringTypes:
2226 if not type(data) in StringTypes:
2227 raise DataIsObject
2227 raise DataIsObject
2228
2228
2229 except (NameError,SyntaxError):
2229 except (NameError,SyntaxError):
2230 # given argument is not a variable, try as a filename
2230 # given argument is not a variable, try as a filename
2231 filename = make_filename(args)
2231 filename = make_filename(args)
2232 if filename is None:
2232 if filename is None:
2233 warn("Argument given (%s) can't be found as a variable "
2233 warn("Argument given (%s) can't be found as a variable "
2234 "or as a filename." % args)
2234 "or as a filename." % args)
2235 return
2235 return
2236
2236
2237 data = ''
2237 data = ''
2238 use_temp = 0
2238 use_temp = 0
2239 except DataIsObject:
2239 except DataIsObject:
2240
2240
2241 # macros have a special edit function
2241 # macros have a special edit function
2242 if isinstance(data,Macro):
2242 if isinstance(data,Macro):
2243 self._edit_macro(args,data)
2243 self._edit_macro(args,data)
2244 return
2244 return
2245
2245
2246 # For objects, try to edit the file where they are defined
2246 # For objects, try to edit the file where they are defined
2247 try:
2247 try:
2248 filename = inspect.getabsfile(data)
2248 filename = inspect.getabsfile(data)
2249 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2249 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2250 # class created by %edit? Try to find source
2250 # class created by %edit? Try to find source
2251 # by looking for method definitions instead, the
2251 # by looking for method definitions instead, the
2252 # __module__ in those classes is FakeModule.
2252 # __module__ in those classes is FakeModule.
2253 attrs = [getattr(data, aname) for aname in dir(data)]
2253 attrs = [getattr(data, aname) for aname in dir(data)]
2254 for attr in attrs:
2254 for attr in attrs:
2255 if not inspect.ismethod(attr):
2255 if not inspect.ismethod(attr):
2256 continue
2256 continue
2257 filename = inspect.getabsfile(attr)
2257 filename = inspect.getabsfile(attr)
2258 if filename and 'fakemodule' not in filename.lower():
2258 if filename and 'fakemodule' not in filename.lower():
2259 # change the attribute to be the edit target instead
2259 # change the attribute to be the edit target instead
2260 data = attr
2260 data = attr
2261 break
2261 break
2262
2262
2263 datafile = 1
2263 datafile = 1
2264 except TypeError:
2264 except TypeError:
2265 filename = make_filename(args)
2265 filename = make_filename(args)
2266 datafile = 1
2266 datafile = 1
2267 warn('Could not find file where `%s` is defined.\n'
2267 warn('Could not find file where `%s` is defined.\n'
2268 'Opening a file named `%s`' % (args,filename))
2268 'Opening a file named `%s`' % (args,filename))
2269 # Now, make sure we can actually read the source (if it was in
2269 # Now, make sure we can actually read the source (if it was in
2270 # a temp file it's gone by now).
2270 # a temp file it's gone by now).
2271 if datafile:
2271 if datafile:
2272 try:
2272 try:
2273 if lineno is None:
2273 if lineno is None:
2274 lineno = inspect.getsourcelines(data)[1]
2274 lineno = inspect.getsourcelines(data)[1]
2275 except IOError:
2275 except IOError:
2276 filename = make_filename(args)
2276 filename = make_filename(args)
2277 if filename is None:
2277 if filename is None:
2278 warn('The file `%s` where `%s` was defined cannot '
2278 warn('The file `%s` where `%s` was defined cannot '
2279 'be read.' % (filename,data))
2279 'be read.' % (filename,data))
2280 return
2280 return
2281 use_temp = 0
2281 use_temp = 0
2282 else:
2282 else:
2283 data = ''
2283 data = ''
2284
2284
2285 if use_temp:
2285 if use_temp:
2286 filename = self.shell.mktempfile(data)
2286 filename = self.shell.mktempfile(data)
2287 print 'IPython will make a temporary file named:',filename
2287 print 'IPython will make a temporary file named:',filename
2288
2288
2289 # do actual editing here
2289 # do actual editing here
2290 print 'Editing...',
2290 print 'Editing...',
2291 sys.stdout.flush()
2291 sys.stdout.flush()
2292 self.shell.hooks.editor(filename,lineno)
2292 self.shell.hooks.editor(filename,lineno)
2293 if opts.has_key('x'): # -x prevents actual execution
2293 if opts.has_key('x'): # -x prevents actual execution
2294 print
2294 print
2295 else:
2295 else:
2296 print 'done. Executing edited code...'
2296 print 'done. Executing edited code...'
2297 if opts_r:
2297 if opts_r:
2298 self.shell.runlines(file_read(filename))
2298 self.shell.runlines(file_read(filename))
2299 else:
2299 else:
2300 self.shell.safe_execfile(filename,self.shell.user_ns,
2300 self.shell.safe_execfile(filename,self.shell.user_ns,
2301 self.shell.user_ns)
2301 self.shell.user_ns)
2302 if use_temp:
2302 if use_temp:
2303 try:
2303 try:
2304 return open(filename).read()
2304 return open(filename).read()
2305 except IOError,msg:
2305 except IOError,msg:
2306 if msg.filename == filename:
2306 if msg.filename == filename:
2307 warn('File not found. Did you forget to save?')
2307 warn('File not found. Did you forget to save?')
2308 return
2308 return
2309 else:
2309 else:
2310 self.shell.showtraceback()
2310 self.shell.showtraceback()
2311
2311
2312 def magic_xmode(self,parameter_s = ''):
2312 def magic_xmode(self,parameter_s = ''):
2313 """Switch modes for the exception handlers.
2313 """Switch modes for the exception handlers.
2314
2314
2315 Valid modes: Plain, Context and Verbose.
2315 Valid modes: Plain, Context and Verbose.
2316
2316
2317 If called without arguments, acts as a toggle."""
2317 If called without arguments, acts as a toggle."""
2318
2318
2319 def xmode_switch_err(name):
2319 def xmode_switch_err(name):
2320 warn('Error changing %s exception modes.\n%s' %
2320 warn('Error changing %s exception modes.\n%s' %
2321 (name,sys.exc_info()[1]))
2321 (name,sys.exc_info()[1]))
2322
2322
2323 shell = self.shell
2323 shell = self.shell
2324 new_mode = parameter_s.strip().capitalize()
2324 new_mode = parameter_s.strip().capitalize()
2325 try:
2325 try:
2326 shell.InteractiveTB.set_mode(mode=new_mode)
2326 shell.InteractiveTB.set_mode(mode=new_mode)
2327 print 'Exception reporting mode:',shell.InteractiveTB.mode
2327 print 'Exception reporting mode:',shell.InteractiveTB.mode
2328 except:
2328 except:
2329 xmode_switch_err('user')
2329 xmode_switch_err('user')
2330
2330
2331 # threaded shells use a special handler in sys.excepthook
2331 # threaded shells use a special handler in sys.excepthook
2332 if shell.isthreaded:
2332 if shell.isthreaded:
2333 try:
2333 try:
2334 shell.sys_excepthook.set_mode(mode=new_mode)
2334 shell.sys_excepthook.set_mode(mode=new_mode)
2335 except:
2335 except:
2336 xmode_switch_err('threaded')
2336 xmode_switch_err('threaded')
2337
2337
2338 def magic_colors(self,parameter_s = ''):
2338 def magic_colors(self,parameter_s = ''):
2339 """Switch color scheme for prompts, info system and exception handlers.
2339 """Switch color scheme for prompts, info system and exception handlers.
2340
2340
2341 Currently implemented schemes: NoColor, Linux, LightBG.
2341 Currently implemented schemes: NoColor, Linux, LightBG.
2342
2342
2343 Color scheme names are not case-sensitive."""
2343 Color scheme names are not case-sensitive."""
2344
2344
2345 def color_switch_err(name):
2345 def color_switch_err(name):
2346 warn('Error changing %s color schemes.\n%s' %
2346 warn('Error changing %s color schemes.\n%s' %
2347 (name,sys.exc_info()[1]))
2347 (name,sys.exc_info()[1]))
2348
2348
2349
2349
2350 new_scheme = parameter_s.strip()
2350 new_scheme = parameter_s.strip()
2351 if not new_scheme:
2351 if not new_scheme:
2352 raise UsageError(
2352 raise UsageError(
2353 "%colors: you must specify a color scheme. See '%colors?'")
2353 "%colors: you must specify a color scheme. See '%colors?'")
2354 return
2354 return
2355 # local shortcut
2355 # local shortcut
2356 shell = self.shell
2356 shell = self.shell
2357
2357
2358 import IPython.rlineimpl as readline
2358 import IPython.rlineimpl as readline
2359
2359
2360 if not readline.have_readline and sys.platform == "win32":
2360 if not readline.have_readline and sys.platform == "win32":
2361 msg = """\
2361 msg = """\
2362 Proper color support under MS Windows requires the pyreadline library.
2362 Proper color support under MS Windows requires the pyreadline library.
2363 You can find it at:
2363 You can find it at:
2364 http://ipython.scipy.org/moin/PyReadline/Intro
2364 http://ipython.scipy.org/moin/PyReadline/Intro
2365 Gary's readline needs the ctypes module, from:
2365 Gary's readline needs the ctypes module, from:
2366 http://starship.python.net/crew/theller/ctypes
2366 http://starship.python.net/crew/theller/ctypes
2367 (Note that ctypes is already part of Python versions 2.5 and newer).
2367 (Note that ctypes is already part of Python versions 2.5 and newer).
2368
2368
2369 Defaulting color scheme to 'NoColor'"""
2369 Defaulting color scheme to 'NoColor'"""
2370 new_scheme = 'NoColor'
2370 new_scheme = 'NoColor'
2371 warn(msg)
2371 warn(msg)
2372
2372
2373 # readline option is 0
2373 # readline option is 0
2374 if not shell.has_readline:
2374 if not shell.has_readline:
2375 new_scheme = 'NoColor'
2375 new_scheme = 'NoColor'
2376
2376
2377 # Set prompt colors
2377 # Set prompt colors
2378 try:
2378 try:
2379 shell.outputcache.set_colors(new_scheme)
2379 shell.outputcache.set_colors(new_scheme)
2380 except:
2380 except:
2381 color_switch_err('prompt')
2381 color_switch_err('prompt')
2382 else:
2382 else:
2383 shell.rc.colors = \
2383 shell.rc.colors = \
2384 shell.outputcache.color_table.active_scheme_name
2384 shell.outputcache.color_table.active_scheme_name
2385 # Set exception colors
2385 # Set exception colors
2386 try:
2386 try:
2387 shell.InteractiveTB.set_colors(scheme = new_scheme)
2387 shell.InteractiveTB.set_colors(scheme = new_scheme)
2388 shell.SyntaxTB.set_colors(scheme = new_scheme)
2388 shell.SyntaxTB.set_colors(scheme = new_scheme)
2389 except:
2389 except:
2390 color_switch_err('exception')
2390 color_switch_err('exception')
2391
2391
2392 # threaded shells use a verbose traceback in sys.excepthook
2392 # threaded shells use a verbose traceback in sys.excepthook
2393 if shell.isthreaded:
2393 if shell.isthreaded:
2394 try:
2394 try:
2395 shell.sys_excepthook.set_colors(scheme=new_scheme)
2395 shell.sys_excepthook.set_colors(scheme=new_scheme)
2396 except:
2396 except:
2397 color_switch_err('system exception handler')
2397 color_switch_err('system exception handler')
2398
2398
2399 # Set info (for 'object?') colors
2399 # Set info (for 'object?') colors
2400 if shell.rc.color_info:
2400 if shell.rc.color_info:
2401 try:
2401 try:
2402 shell.inspector.set_active_scheme(new_scheme)
2402 shell.inspector.set_active_scheme(new_scheme)
2403 except:
2403 except:
2404 color_switch_err('object inspector')
2404 color_switch_err('object inspector')
2405 else:
2405 else:
2406 shell.inspector.set_active_scheme('NoColor')
2406 shell.inspector.set_active_scheme('NoColor')
2407
2407
2408 def magic_color_info(self,parameter_s = ''):
2408 def magic_color_info(self,parameter_s = ''):
2409 """Toggle color_info.
2409 """Toggle color_info.
2410
2410
2411 The color_info configuration parameter controls whether colors are
2411 The color_info configuration parameter controls whether colors are
2412 used for displaying object details (by things like %psource, %pfile or
2412 used for displaying object details (by things like %psource, %pfile or
2413 the '?' system). This function toggles this value with each call.
2413 the '?' system). This function toggles this value with each call.
2414
2414
2415 Note that unless you have a fairly recent pager (less works better
2415 Note that unless you have a fairly recent pager (less works better
2416 than more) in your system, using colored object information displays
2416 than more) in your system, using colored object information displays
2417 will not work properly. Test it and see."""
2417 will not work properly. Test it and see."""
2418
2418
2419 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2419 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2420 self.magic_colors(self.shell.rc.colors)
2420 self.magic_colors(self.shell.rc.colors)
2421 print 'Object introspection functions have now coloring:',
2421 print 'Object introspection functions have now coloring:',
2422 print ['OFF','ON'][self.shell.rc.color_info]
2422 print ['OFF','ON'][self.shell.rc.color_info]
2423
2423
2424 def magic_Pprint(self, parameter_s=''):
2424 def magic_Pprint(self, parameter_s=''):
2425 """Toggle pretty printing on/off."""
2425 """Toggle pretty printing on/off."""
2426
2426
2427 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2427 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2428 print 'Pretty printing has been turned', \
2428 print 'Pretty printing has been turned', \
2429 ['OFF','ON'][self.shell.rc.pprint]
2429 ['OFF','ON'][self.shell.rc.pprint]
2430
2430
2431 def magic_exit(self, parameter_s=''):
2431 def magic_exit(self, parameter_s=''):
2432 """Exit IPython, confirming if configured to do so.
2432 """Exit IPython, confirming if configured to do so.
2433
2433
2434 You can configure whether IPython asks for confirmation upon exit by
2434 You can configure whether IPython asks for confirmation upon exit by
2435 setting the confirm_exit flag in the ipythonrc file."""
2435 setting the confirm_exit flag in the ipythonrc file."""
2436
2436
2437 self.shell.exit()
2437 self.shell.exit()
2438
2438
2439 def magic_quit(self, parameter_s=''):
2439 def magic_quit(self, parameter_s=''):
2440 """Exit IPython, confirming if configured to do so (like %exit)"""
2440 """Exit IPython, confirming if configured to do so (like %exit)"""
2441
2441
2442 self.shell.exit()
2442 self.shell.exit()
2443
2443
2444 def magic_Exit(self, parameter_s=''):
2444 def magic_Exit(self, parameter_s=''):
2445 """Exit IPython without confirmation."""
2445 """Exit IPython without confirmation."""
2446
2446
2447 self.shell.exit_now = True
2447 self.shell.exit_now = True
2448
2448
2449 #......................................................................
2449 #......................................................................
2450 # Functions to implement unix shell-type things
2450 # Functions to implement unix shell-type things
2451
2451
2452 def magic_alias(self, parameter_s = ''):
2452 def magic_alias(self, parameter_s = ''):
2453 """Define an alias for a system command.
2453 """Define an alias for a system command.
2454
2454
2455 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2455 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2456
2456
2457 Then, typing 'alias_name params' will execute the system command 'cmd
2457 Then, typing 'alias_name params' will execute the system command 'cmd
2458 params' (from your underlying operating system).
2458 params' (from your underlying operating system).
2459
2459
2460 Aliases have lower precedence than magic functions and Python normal
2460 Aliases have lower precedence than magic functions and Python normal
2461 variables, so if 'foo' is both a Python variable and an alias, the
2461 variables, so if 'foo' is both a Python variable and an alias, the
2462 alias can not be executed until 'del foo' removes the Python variable.
2462 alias can not be executed until 'del foo' removes the Python variable.
2463
2463
2464 You can use the %l specifier in an alias definition to represent the
2464 You can use the %l specifier in an alias definition to represent the
2465 whole line when the alias is called. For example:
2465 whole line when the alias is called. For example:
2466
2466
2467 In [2]: alias all echo "Input in brackets: <%l>"\\
2467 In [2]: alias all echo "Input in brackets: <%l>"\\
2468 In [3]: all hello world\\
2468 In [3]: all hello world\\
2469 Input in brackets: <hello world>
2469 Input in brackets: <hello world>
2470
2470
2471 You can also define aliases with parameters using %s specifiers (one
2471 You can also define aliases with parameters using %s specifiers (one
2472 per parameter):
2472 per parameter):
2473
2473
2474 In [1]: alias parts echo first %s second %s\\
2474 In [1]: alias parts echo first %s second %s\\
2475 In [2]: %parts A B\\
2475 In [2]: %parts A B\\
2476 first A second B\\
2476 first A second B\\
2477 In [3]: %parts A\\
2477 In [3]: %parts A\\
2478 Incorrect number of arguments: 2 expected.\\
2478 Incorrect number of arguments: 2 expected.\\
2479 parts is an alias to: 'echo first %s second %s'
2479 parts is an alias to: 'echo first %s second %s'
2480
2480
2481 Note that %l and %s are mutually exclusive. You can only use one or
2481 Note that %l and %s are mutually exclusive. You can only use one or
2482 the other in your aliases.
2482 the other in your aliases.
2483
2483
2484 Aliases expand Python variables just like system calls using ! or !!
2484 Aliases expand Python variables just like system calls using ! or !!
2485 do: all expressions prefixed with '$' get expanded. For details of
2485 do: all expressions prefixed with '$' get expanded. For details of
2486 the semantic rules, see PEP-215:
2486 the semantic rules, see PEP-215:
2487 http://www.python.org/peps/pep-0215.html. This is the library used by
2487 http://www.python.org/peps/pep-0215.html. This is the library used by
2488 IPython for variable expansion. If you want to access a true shell
2488 IPython for variable expansion. If you want to access a true shell
2489 variable, an extra $ is necessary to prevent its expansion by IPython:
2489 variable, an extra $ is necessary to prevent its expansion by IPython:
2490
2490
2491 In [6]: alias show echo\\
2491 In [6]: alias show echo\\
2492 In [7]: PATH='A Python string'\\
2492 In [7]: PATH='A Python string'\\
2493 In [8]: show $PATH\\
2493 In [8]: show $PATH\\
2494 A Python string\\
2494 A Python string\\
2495 In [9]: show $$PATH\\
2495 In [9]: show $$PATH\\
2496 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2496 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2497
2497
2498 You can use the alias facility to acess all of $PATH. See the %rehash
2498 You can use the alias facility to acess all of $PATH. See the %rehash
2499 and %rehashx functions, which automatically create aliases for the
2499 and %rehashx functions, which automatically create aliases for the
2500 contents of your $PATH.
2500 contents of your $PATH.
2501
2501
2502 If called with no parameters, %alias prints the current alias table."""
2502 If called with no parameters, %alias prints the current alias table."""
2503
2503
2504 par = parameter_s.strip()
2504 par = parameter_s.strip()
2505 if not par:
2505 if not par:
2506 stored = self.db.get('stored_aliases', {} )
2506 stored = self.db.get('stored_aliases', {} )
2507 atab = self.shell.alias_table
2507 atab = self.shell.alias_table
2508 aliases = atab.keys()
2508 aliases = atab.keys()
2509 aliases.sort()
2509 aliases.sort()
2510 res = []
2510 res = []
2511 showlast = []
2511 showlast = []
2512 for alias in aliases:
2512 for alias in aliases:
2513 special = False
2513 special = False
2514 try:
2514 try:
2515 tgt = atab[alias][1]
2515 tgt = atab[alias][1]
2516 except (TypeError, AttributeError):
2516 except (TypeError, AttributeError):
2517 # unsubscriptable? probably a callable
2517 # unsubscriptable? probably a callable
2518 tgt = atab[alias]
2518 tgt = atab[alias]
2519 special = True
2519 special = True
2520 # 'interesting' aliases
2520 # 'interesting' aliases
2521 if (alias in stored or
2521 if (alias in stored or
2522 special or
2522 special or
2523 alias.lower() != os.path.splitext(tgt)[0].lower() or
2523 alias.lower() != os.path.splitext(tgt)[0].lower() or
2524 ' ' in tgt):
2524 ' ' in tgt):
2525 showlast.append((alias, tgt))
2525 showlast.append((alias, tgt))
2526 else:
2526 else:
2527 res.append((alias, tgt ))
2527 res.append((alias, tgt ))
2528
2528
2529 # show most interesting aliases last
2529 # show most interesting aliases last
2530 res.extend(showlast)
2530 res.extend(showlast)
2531 print "Total number of aliases:",len(aliases)
2531 print "Total number of aliases:",len(aliases)
2532 return res
2532 return res
2533 try:
2533 try:
2534 alias,cmd = par.split(None,1)
2534 alias,cmd = par.split(None,1)
2535 except:
2535 except:
2536 print OInspect.getdoc(self.magic_alias)
2536 print OInspect.getdoc(self.magic_alias)
2537 else:
2537 else:
2538 nargs = cmd.count('%s')
2538 nargs = cmd.count('%s')
2539 if nargs>0 and cmd.find('%l')>=0:
2539 if nargs>0 and cmd.find('%l')>=0:
2540 error('The %s and %l specifiers are mutually exclusive '
2540 error('The %s and %l specifiers are mutually exclusive '
2541 'in alias definitions.')
2541 'in alias definitions.')
2542 else: # all looks OK
2542 else: # all looks OK
2543 self.shell.alias_table[alias] = (nargs,cmd)
2543 self.shell.alias_table[alias] = (nargs,cmd)
2544 self.shell.alias_table_validate(verbose=0)
2544 self.shell.alias_table_validate(verbose=0)
2545 # end magic_alias
2545 # end magic_alias
2546
2546
2547 def magic_unalias(self, parameter_s = ''):
2547 def magic_unalias(self, parameter_s = ''):
2548 """Remove an alias"""
2548 """Remove an alias"""
2549
2549
2550 aname = parameter_s.strip()
2550 aname = parameter_s.strip()
2551 if aname in self.shell.alias_table:
2551 if aname in self.shell.alias_table:
2552 del self.shell.alias_table[aname]
2552 del self.shell.alias_table[aname]
2553 stored = self.db.get('stored_aliases', {} )
2553 stored = self.db.get('stored_aliases', {} )
2554 if aname in stored:
2554 if aname in stored:
2555 print "Removing %stored alias",aname
2555 print "Removing %stored alias",aname
2556 del stored[aname]
2556 del stored[aname]
2557 self.db['stored_aliases'] = stored
2557 self.db['stored_aliases'] = stored
2558
2558
2559
2559
2560 def magic_rehashx(self, parameter_s = ''):
2560 def magic_rehashx(self, parameter_s = ''):
2561 """Update the alias table with all executable files in $PATH.
2561 """Update the alias table with all executable files in $PATH.
2562
2562
2563 This version explicitly checks that every entry in $PATH is a file
2563 This version explicitly checks that every entry in $PATH is a file
2564 with execute access (os.X_OK), so it is much slower than %rehash.
2564 with execute access (os.X_OK), so it is much slower than %rehash.
2565
2565
2566 Under Windows, it checks executability as a match agains a
2566 Under Windows, it checks executability as a match agains a
2567 '|'-separated string of extensions, stored in the IPython config
2567 '|'-separated string of extensions, stored in the IPython config
2568 variable win_exec_ext. This defaults to 'exe|com|bat'.
2568 variable win_exec_ext. This defaults to 'exe|com|bat'.
2569
2569
2570 This function also resets the root module cache of module completer,
2570 This function also resets the root module cache of module completer,
2571 used on slow filesystems.
2571 used on slow filesystems.
2572 """
2572 """
2573
2573
2574
2574
2575 ip = self.api
2575 ip = self.api
2576
2576
2577 # for the benefit of module completer in ipy_completers.py
2577 # for the benefit of module completer in ipy_completers.py
2578 del ip.db['rootmodules']
2578 del ip.db['rootmodules']
2579
2579
2580 path = [os.path.abspath(os.path.expanduser(p)) for p in
2580 path = [os.path.abspath(os.path.expanduser(p)) for p in
2581 os.environ.get('PATH','').split(os.pathsep)]
2581 os.environ.get('PATH','').split(os.pathsep)]
2582 path = filter(os.path.isdir,path)
2582 path = filter(os.path.isdir,path)
2583
2583
2584 alias_table = self.shell.alias_table
2584 alias_table = self.shell.alias_table
2585 syscmdlist = []
2585 syscmdlist = []
2586 if os.name == 'posix':
2586 if os.name == 'posix':
2587 isexec = lambda fname:os.path.isfile(fname) and \
2587 isexec = lambda fname:os.path.isfile(fname) and \
2588 os.access(fname,os.X_OK)
2588 os.access(fname,os.X_OK)
2589 else:
2589 else:
2590
2590
2591 try:
2591 try:
2592 winext = os.environ['pathext'].replace(';','|').replace('.','')
2592 winext = os.environ['pathext'].replace(';','|').replace('.','')
2593 except KeyError:
2593 except KeyError:
2594 winext = 'exe|com|bat|py'
2594 winext = 'exe|com|bat|py'
2595 if 'py' not in winext:
2595 if 'py' not in winext:
2596 winext += '|py'
2596 winext += '|py'
2597 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2597 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2598 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2598 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2599 savedir = os.getcwd()
2599 savedir = os.getcwd()
2600 try:
2600 try:
2601 # write the whole loop for posix/Windows so we don't have an if in
2601 # write the whole loop for posix/Windows so we don't have an if in
2602 # the innermost part
2602 # the innermost part
2603 if os.name == 'posix':
2603 if os.name == 'posix':
2604 for pdir in path:
2604 for pdir in path:
2605 os.chdir(pdir)
2605 os.chdir(pdir)
2606 for ff in os.listdir(pdir):
2606 for ff in os.listdir(pdir):
2607 if isexec(ff) and ff not in self.shell.no_alias:
2607 if isexec(ff) and ff not in self.shell.no_alias:
2608 # each entry in the alias table must be (N,name),
2608 # each entry in the alias table must be (N,name),
2609 # where N is the number of positional arguments of the
2609 # where N is the number of positional arguments of the
2610 # alias.
2610 # alias.
2611 alias_table[ff] = (0,ff)
2611 alias_table[ff] = (0,ff)
2612 syscmdlist.append(ff)
2612 syscmdlist.append(ff)
2613 else:
2613 else:
2614 for pdir in path:
2614 for pdir in path:
2615 os.chdir(pdir)
2615 os.chdir(pdir)
2616 for ff in os.listdir(pdir):
2616 for ff in os.listdir(pdir):
2617 base, ext = os.path.splitext(ff)
2617 base, ext = os.path.splitext(ff)
2618 if isexec(ff) and base not in self.shell.no_alias:
2618 if isexec(ff) and base.lower() not in self.shell.no_alias:
2619 if ext.lower() == '.exe':
2619 if ext.lower() == '.exe':
2620 ff = base
2620 ff = base
2621 alias_table[base.lower()] = (0,ff)
2621 alias_table[base.lower()] = (0,ff)
2622 syscmdlist.append(ff)
2622 syscmdlist.append(ff)
2623 # Make sure the alias table doesn't contain keywords or builtins
2623 # Make sure the alias table doesn't contain keywords or builtins
2624 self.shell.alias_table_validate()
2624 self.shell.alias_table_validate()
2625 # Call again init_auto_alias() so we get 'rm -i' and other
2625 # Call again init_auto_alias() so we get 'rm -i' and other
2626 # modified aliases since %rehashx will probably clobber them
2626 # modified aliases since %rehashx will probably clobber them
2627
2627
2628 # no, we don't want them. if %rehashx clobbers them, good,
2628 # no, we don't want them. if %rehashx clobbers them, good,
2629 # we'll probably get better versions
2629 # we'll probably get better versions
2630 # self.shell.init_auto_alias()
2630 # self.shell.init_auto_alias()
2631 db = ip.db
2631 db = ip.db
2632 db['syscmdlist'] = syscmdlist
2632 db['syscmdlist'] = syscmdlist
2633 finally:
2633 finally:
2634 os.chdir(savedir)
2634 os.chdir(savedir)
2635
2635
2636 def magic_pwd(self, parameter_s = ''):
2636 def magic_pwd(self, parameter_s = ''):
2637 """Return the current working directory path."""
2637 """Return the current working directory path."""
2638 return os.getcwd()
2638 return os.getcwd()
2639
2639
2640 def magic_cd(self, parameter_s=''):
2640 def magic_cd(self, parameter_s=''):
2641 """Change the current working directory.
2641 """Change the current working directory.
2642
2642
2643 This command automatically maintains an internal list of directories
2643 This command automatically maintains an internal list of directories
2644 you visit during your IPython session, in the variable _dh. The
2644 you visit during your IPython session, in the variable _dh. The
2645 command %dhist shows this history nicely formatted. You can also
2645 command %dhist shows this history nicely formatted. You can also
2646 do 'cd -<tab>' to see directory history conveniently.
2646 do 'cd -<tab>' to see directory history conveniently.
2647
2647
2648 Usage:
2648 Usage:
2649
2649
2650 cd 'dir': changes to directory 'dir'.
2650 cd 'dir': changes to directory 'dir'.
2651
2651
2652 cd -: changes to the last visited directory.
2652 cd -: changes to the last visited directory.
2653
2653
2654 cd -<n>: changes to the n-th directory in the directory history.
2654 cd -<n>: changes to the n-th directory in the directory history.
2655
2655
2656 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2656 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2657 (note: cd <bookmark_name> is enough if there is no
2657 (note: cd <bookmark_name> is enough if there is no
2658 directory <bookmark_name>, but a bookmark with the name exists.)
2658 directory <bookmark_name>, but a bookmark with the name exists.)
2659 'cd -b <tab>' allows you to tab-complete bookmark names.
2659 'cd -b <tab>' allows you to tab-complete bookmark names.
2660
2660
2661 Options:
2661 Options:
2662
2662
2663 -q: quiet. Do not print the working directory after the cd command is
2663 -q: quiet. Do not print the working directory after the cd command is
2664 executed. By default IPython's cd command does print this directory,
2664 executed. By default IPython's cd command does print this directory,
2665 since the default prompts do not display path information.
2665 since the default prompts do not display path information.
2666
2666
2667 Note that !cd doesn't work for this purpose because the shell where
2667 Note that !cd doesn't work for this purpose because the shell where
2668 !command runs is immediately discarded after executing 'command'."""
2668 !command runs is immediately discarded after executing 'command'."""
2669
2669
2670 parameter_s = parameter_s.strip()
2670 parameter_s = parameter_s.strip()
2671 #bkms = self.shell.persist.get("bookmarks",{})
2671 #bkms = self.shell.persist.get("bookmarks",{})
2672
2672
2673 oldcwd = os.getcwd()
2673 oldcwd = os.getcwd()
2674 numcd = re.match(r'(-)(\d+)$',parameter_s)
2674 numcd = re.match(r'(-)(\d+)$',parameter_s)
2675 # jump in directory history by number
2675 # jump in directory history by number
2676 if numcd:
2676 if numcd:
2677 nn = int(numcd.group(2))
2677 nn = int(numcd.group(2))
2678 try:
2678 try:
2679 ps = self.shell.user_ns['_dh'][nn]
2679 ps = self.shell.user_ns['_dh'][nn]
2680 except IndexError:
2680 except IndexError:
2681 print 'The requested directory does not exist in history.'
2681 print 'The requested directory does not exist in history.'
2682 return
2682 return
2683 else:
2683 else:
2684 opts = {}
2684 opts = {}
2685 else:
2685 else:
2686 #turn all non-space-escaping backslashes to slashes,
2686 #turn all non-space-escaping backslashes to slashes,
2687 # for c:\windows\directory\names\
2687 # for c:\windows\directory\names\
2688 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2688 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2689 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2689 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2690 # jump to previous
2690 # jump to previous
2691 if ps == '-':
2691 if ps == '-':
2692 try:
2692 try:
2693 ps = self.shell.user_ns['_dh'][-2]
2693 ps = self.shell.user_ns['_dh'][-2]
2694 except IndexError:
2694 except IndexError:
2695 raise UsageError('%cd -: No previous directory to change to.')
2695 raise UsageError('%cd -: No previous directory to change to.')
2696 # jump to bookmark if needed
2696 # jump to bookmark if needed
2697 else:
2697 else:
2698 if not os.path.isdir(ps) or opts.has_key('b'):
2698 if not os.path.isdir(ps) or opts.has_key('b'):
2699 bkms = self.db.get('bookmarks', {})
2699 bkms = self.db.get('bookmarks', {})
2700
2700
2701 if bkms.has_key(ps):
2701 if bkms.has_key(ps):
2702 target = bkms[ps]
2702 target = bkms[ps]
2703 print '(bookmark:%s) -> %s' % (ps,target)
2703 print '(bookmark:%s) -> %s' % (ps,target)
2704 ps = target
2704 ps = target
2705 else:
2705 else:
2706 if opts.has_key('b'):
2706 if opts.has_key('b'):
2707 raise UsageError("Bookmark '%s' not found. "
2707 raise UsageError("Bookmark '%s' not found. "
2708 "Use '%%bookmark -l' to see your bookmarks." % ps)
2708 "Use '%%bookmark -l' to see your bookmarks." % ps)
2709
2709
2710 # at this point ps should point to the target dir
2710 # at this point ps should point to the target dir
2711 if ps:
2711 if ps:
2712 try:
2712 try:
2713 os.chdir(os.path.expanduser(ps))
2713 os.chdir(os.path.expanduser(ps))
2714 if self.shell.rc.term_title:
2714 if self.shell.rc.term_title:
2715 #print 'set term title:',self.shell.rc.term_title # dbg
2715 #print 'set term title:',self.shell.rc.term_title # dbg
2716 ttitle = 'IPy ' + abbrev_cwd()
2716 ttitle = 'IPy ' + abbrev_cwd()
2717 platutils.set_term_title(ttitle)
2717 platutils.set_term_title(ttitle)
2718 except OSError:
2718 except OSError:
2719 print sys.exc_info()[1]
2719 print sys.exc_info()[1]
2720 else:
2720 else:
2721 cwd = os.getcwd()
2721 cwd = os.getcwd()
2722 dhist = self.shell.user_ns['_dh']
2722 dhist = self.shell.user_ns['_dh']
2723 if oldcwd != cwd:
2723 if oldcwd != cwd:
2724 dhist.append(cwd)
2724 dhist.append(cwd)
2725 self.db['dhist'] = compress_dhist(dhist)[-100:]
2725 self.db['dhist'] = compress_dhist(dhist)[-100:]
2726
2726
2727 else:
2727 else:
2728 os.chdir(self.shell.home_dir)
2728 os.chdir(self.shell.home_dir)
2729 if self.shell.rc.term_title:
2729 if self.shell.rc.term_title:
2730 platutils.set_term_title("IPy ~")
2730 platutils.set_term_title("IPy ~")
2731 cwd = os.getcwd()
2731 cwd = os.getcwd()
2732 dhist = self.shell.user_ns['_dh']
2732 dhist = self.shell.user_ns['_dh']
2733
2733
2734 if oldcwd != cwd:
2734 if oldcwd != cwd:
2735 dhist.append(cwd)
2735 dhist.append(cwd)
2736 self.db['dhist'] = compress_dhist(dhist)[-100:]
2736 self.db['dhist'] = compress_dhist(dhist)[-100:]
2737 if not 'q' in opts and self.shell.user_ns['_dh']:
2737 if not 'q' in opts and self.shell.user_ns['_dh']:
2738 print self.shell.user_ns['_dh'][-1]
2738 print self.shell.user_ns['_dh'][-1]
2739
2739
2740
2740
2741 def magic_env(self, parameter_s=''):
2741 def magic_env(self, parameter_s=''):
2742 """List environment variables."""
2742 """List environment variables."""
2743
2743
2744 return os.environ.data
2744 return os.environ.data
2745
2745
2746 def magic_pushd(self, parameter_s=''):
2746 def magic_pushd(self, parameter_s=''):
2747 """Place the current dir on stack and change directory.
2747 """Place the current dir on stack and change directory.
2748
2748
2749 Usage:\\
2749 Usage:\\
2750 %pushd ['dirname']
2750 %pushd ['dirname']
2751 """
2751 """
2752
2752
2753 dir_s = self.shell.dir_stack
2753 dir_s = self.shell.dir_stack
2754 tgt = os.path.expanduser(parameter_s)
2754 tgt = os.path.expanduser(parameter_s)
2755 cwd = os.getcwd().replace(self.home_dir,'~')
2755 cwd = os.getcwd().replace(self.home_dir,'~')
2756 if tgt:
2756 if tgt:
2757 self.magic_cd(parameter_s)
2757 self.magic_cd(parameter_s)
2758 dir_s.insert(0,cwd)
2758 dir_s.insert(0,cwd)
2759 return self.magic_dirs()
2759 return self.magic_dirs()
2760
2760
2761 def magic_popd(self, parameter_s=''):
2761 def magic_popd(self, parameter_s=''):
2762 """Change to directory popped off the top of the stack.
2762 """Change to directory popped off the top of the stack.
2763 """
2763 """
2764 if not self.shell.dir_stack:
2764 if not self.shell.dir_stack:
2765 raise UsageError("%popd on empty stack")
2765 raise UsageError("%popd on empty stack")
2766 top = self.shell.dir_stack.pop(0)
2766 top = self.shell.dir_stack.pop(0)
2767 self.magic_cd(top)
2767 self.magic_cd(top)
2768 print "popd ->",top
2768 print "popd ->",top
2769
2769
2770 def magic_dirs(self, parameter_s=''):
2770 def magic_dirs(self, parameter_s=''):
2771 """Return the current directory stack."""
2771 """Return the current directory stack."""
2772
2772
2773 return self.shell.dir_stack
2773 return self.shell.dir_stack
2774
2774
2775 def magic_dhist(self, parameter_s=''):
2775 def magic_dhist(self, parameter_s=''):
2776 """Print your history of visited directories.
2776 """Print your history of visited directories.
2777
2777
2778 %dhist -> print full history\\
2778 %dhist -> print full history\\
2779 %dhist n -> print last n entries only\\
2779 %dhist n -> print last n entries only\\
2780 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2780 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2781
2781
2782 This history is automatically maintained by the %cd command, and
2782 This history is automatically maintained by the %cd command, and
2783 always available as the global list variable _dh. You can use %cd -<n>
2783 always available as the global list variable _dh. You can use %cd -<n>
2784 to go to directory number <n>.
2784 to go to directory number <n>.
2785
2785
2786 Note that most of time, you should view directory history by entering
2786 Note that most of time, you should view directory history by entering
2787 cd -<TAB>.
2787 cd -<TAB>.
2788
2788
2789 """
2789 """
2790
2790
2791 dh = self.shell.user_ns['_dh']
2791 dh = self.shell.user_ns['_dh']
2792 if parameter_s:
2792 if parameter_s:
2793 try:
2793 try:
2794 args = map(int,parameter_s.split())
2794 args = map(int,parameter_s.split())
2795 except:
2795 except:
2796 self.arg_err(Magic.magic_dhist)
2796 self.arg_err(Magic.magic_dhist)
2797 return
2797 return
2798 if len(args) == 1:
2798 if len(args) == 1:
2799 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2799 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2800 elif len(args) == 2:
2800 elif len(args) == 2:
2801 ini,fin = args
2801 ini,fin = args
2802 else:
2802 else:
2803 self.arg_err(Magic.magic_dhist)
2803 self.arg_err(Magic.magic_dhist)
2804 return
2804 return
2805 else:
2805 else:
2806 ini,fin = 0,len(dh)
2806 ini,fin = 0,len(dh)
2807 nlprint(dh,
2807 nlprint(dh,
2808 header = 'Directory history (kept in _dh)',
2808 header = 'Directory history (kept in _dh)',
2809 start=ini,stop=fin)
2809 start=ini,stop=fin)
2810
2810
2811
2811
2812 def magic_sc(self, parameter_s=''):
2812 def magic_sc(self, parameter_s=''):
2813 """Shell capture - execute a shell command and capture its output.
2813 """Shell capture - execute a shell command and capture its output.
2814
2814
2815 DEPRECATED. Suboptimal, retained for backwards compatibility.
2815 DEPRECATED. Suboptimal, retained for backwards compatibility.
2816
2816
2817 You should use the form 'var = !command' instead. Example:
2817 You should use the form 'var = !command' instead. Example:
2818
2818
2819 "%sc -l myfiles = ls ~" should now be written as
2819 "%sc -l myfiles = ls ~" should now be written as
2820
2820
2821 "myfiles = !ls ~"
2821 "myfiles = !ls ~"
2822
2822
2823 myfiles.s, myfiles.l and myfiles.n still apply as documented
2823 myfiles.s, myfiles.l and myfiles.n still apply as documented
2824 below.
2824 below.
2825
2825
2826 --
2826 --
2827 %sc [options] varname=command
2827 %sc [options] varname=command
2828
2828
2829 IPython will run the given command using commands.getoutput(), and
2829 IPython will run the given command using commands.getoutput(), and
2830 will then update the user's interactive namespace with a variable
2830 will then update the user's interactive namespace with a variable
2831 called varname, containing the value of the call. Your command can
2831 called varname, containing the value of the call. Your command can
2832 contain shell wildcards, pipes, etc.
2832 contain shell wildcards, pipes, etc.
2833
2833
2834 The '=' sign in the syntax is mandatory, and the variable name you
2834 The '=' sign in the syntax is mandatory, and the variable name you
2835 supply must follow Python's standard conventions for valid names.
2835 supply must follow Python's standard conventions for valid names.
2836
2836
2837 (A special format without variable name exists for internal use)
2837 (A special format without variable name exists for internal use)
2838
2838
2839 Options:
2839 Options:
2840
2840
2841 -l: list output. Split the output on newlines into a list before
2841 -l: list output. Split the output on newlines into a list before
2842 assigning it to the given variable. By default the output is stored
2842 assigning it to the given variable. By default the output is stored
2843 as a single string.
2843 as a single string.
2844
2844
2845 -v: verbose. Print the contents of the variable.
2845 -v: verbose. Print the contents of the variable.
2846
2846
2847 In most cases you should not need to split as a list, because the
2847 In most cases you should not need to split as a list, because the
2848 returned value is a special type of string which can automatically
2848 returned value is a special type of string which can automatically
2849 provide its contents either as a list (split on newlines) or as a
2849 provide its contents either as a list (split on newlines) or as a
2850 space-separated string. These are convenient, respectively, either
2850 space-separated string. These are convenient, respectively, either
2851 for sequential processing or to be passed to a shell command.
2851 for sequential processing or to be passed to a shell command.
2852
2852
2853 For example:
2853 For example:
2854
2854
2855 # Capture into variable a
2855 # Capture into variable a
2856 In [9]: sc a=ls *py
2856 In [9]: sc a=ls *py
2857
2857
2858 # a is a string with embedded newlines
2858 # a is a string with embedded newlines
2859 In [10]: a
2859 In [10]: a
2860 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2860 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2861
2861
2862 # which can be seen as a list:
2862 # which can be seen as a list:
2863 In [11]: a.l
2863 In [11]: a.l
2864 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2864 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2865
2865
2866 # or as a whitespace-separated string:
2866 # or as a whitespace-separated string:
2867 In [12]: a.s
2867 In [12]: a.s
2868 Out[12]: 'setup.py win32_manual_post_install.py'
2868 Out[12]: 'setup.py win32_manual_post_install.py'
2869
2869
2870 # a.s is useful to pass as a single command line:
2870 # a.s is useful to pass as a single command line:
2871 In [13]: !wc -l $a.s
2871 In [13]: !wc -l $a.s
2872 146 setup.py
2872 146 setup.py
2873 130 win32_manual_post_install.py
2873 130 win32_manual_post_install.py
2874 276 total
2874 276 total
2875
2875
2876 # while the list form is useful to loop over:
2876 # while the list form is useful to loop over:
2877 In [14]: for f in a.l:
2877 In [14]: for f in a.l:
2878 ....: !wc -l $f
2878 ....: !wc -l $f
2879 ....:
2879 ....:
2880 146 setup.py
2880 146 setup.py
2881 130 win32_manual_post_install.py
2881 130 win32_manual_post_install.py
2882
2882
2883 Similiarly, the lists returned by the -l option are also special, in
2883 Similiarly, the lists returned by the -l option are also special, in
2884 the sense that you can equally invoke the .s attribute on them to
2884 the sense that you can equally invoke the .s attribute on them to
2885 automatically get a whitespace-separated string from their contents:
2885 automatically get a whitespace-separated string from their contents:
2886
2886
2887 In [1]: sc -l b=ls *py
2887 In [1]: sc -l b=ls *py
2888
2888
2889 In [2]: b
2889 In [2]: b
2890 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2890 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2891
2891
2892 In [3]: b.s
2892 In [3]: b.s
2893 Out[3]: 'setup.py win32_manual_post_install.py'
2893 Out[3]: 'setup.py win32_manual_post_install.py'
2894
2894
2895 In summary, both the lists and strings used for ouptut capture have
2895 In summary, both the lists and strings used for ouptut capture have
2896 the following special attributes:
2896 the following special attributes:
2897
2897
2898 .l (or .list) : value as list.
2898 .l (or .list) : value as list.
2899 .n (or .nlstr): value as newline-separated string.
2899 .n (or .nlstr): value as newline-separated string.
2900 .s (or .spstr): value as space-separated string.
2900 .s (or .spstr): value as space-separated string.
2901 """
2901 """
2902
2902
2903 opts,args = self.parse_options(parameter_s,'lv')
2903 opts,args = self.parse_options(parameter_s,'lv')
2904 # Try to get a variable name and command to run
2904 # Try to get a variable name and command to run
2905 try:
2905 try:
2906 # the variable name must be obtained from the parse_options
2906 # the variable name must be obtained from the parse_options
2907 # output, which uses shlex.split to strip options out.
2907 # output, which uses shlex.split to strip options out.
2908 var,_ = args.split('=',1)
2908 var,_ = args.split('=',1)
2909 var = var.strip()
2909 var = var.strip()
2910 # But the the command has to be extracted from the original input
2910 # But the the command has to be extracted from the original input
2911 # parameter_s, not on what parse_options returns, to avoid the
2911 # parameter_s, not on what parse_options returns, to avoid the
2912 # quote stripping which shlex.split performs on it.
2912 # quote stripping which shlex.split performs on it.
2913 _,cmd = parameter_s.split('=',1)
2913 _,cmd = parameter_s.split('=',1)
2914 except ValueError:
2914 except ValueError:
2915 var,cmd = '',''
2915 var,cmd = '',''
2916 # If all looks ok, proceed
2916 # If all looks ok, proceed
2917 out,err = self.shell.getoutputerror(cmd)
2917 out,err = self.shell.getoutputerror(cmd)
2918 if err:
2918 if err:
2919 print >> Term.cerr,err
2919 print >> Term.cerr,err
2920 if opts.has_key('l'):
2920 if opts.has_key('l'):
2921 out = SList(out.split('\n'))
2921 out = SList(out.split('\n'))
2922 else:
2922 else:
2923 out = LSString(out)
2923 out = LSString(out)
2924 if opts.has_key('v'):
2924 if opts.has_key('v'):
2925 print '%s ==\n%s' % (var,pformat(out))
2925 print '%s ==\n%s' % (var,pformat(out))
2926 if var:
2926 if var:
2927 self.shell.user_ns.update({var:out})
2927 self.shell.user_ns.update({var:out})
2928 else:
2928 else:
2929 return out
2929 return out
2930
2930
2931 def magic_sx(self, parameter_s=''):
2931 def magic_sx(self, parameter_s=''):
2932 """Shell execute - run a shell command and capture its output.
2932 """Shell execute - run a shell command and capture its output.
2933
2933
2934 %sx command
2934 %sx command
2935
2935
2936 IPython will run the given command using commands.getoutput(), and
2936 IPython will run the given command using commands.getoutput(), and
2937 return the result formatted as a list (split on '\\n'). Since the
2937 return the result formatted as a list (split on '\\n'). Since the
2938 output is _returned_, it will be stored in ipython's regular output
2938 output is _returned_, it will be stored in ipython's regular output
2939 cache Out[N] and in the '_N' automatic variables.
2939 cache Out[N] and in the '_N' automatic variables.
2940
2940
2941 Notes:
2941 Notes:
2942
2942
2943 1) If an input line begins with '!!', then %sx is automatically
2943 1) If an input line begins with '!!', then %sx is automatically
2944 invoked. That is, while:
2944 invoked. That is, while:
2945 !ls
2945 !ls
2946 causes ipython to simply issue system('ls'), typing
2946 causes ipython to simply issue system('ls'), typing
2947 !!ls
2947 !!ls
2948 is a shorthand equivalent to:
2948 is a shorthand equivalent to:
2949 %sx ls
2949 %sx ls
2950
2950
2951 2) %sx differs from %sc in that %sx automatically splits into a list,
2951 2) %sx differs from %sc in that %sx automatically splits into a list,
2952 like '%sc -l'. The reason for this is to make it as easy as possible
2952 like '%sc -l'. The reason for this is to make it as easy as possible
2953 to process line-oriented shell output via further python commands.
2953 to process line-oriented shell output via further python commands.
2954 %sc is meant to provide much finer control, but requires more
2954 %sc is meant to provide much finer control, but requires more
2955 typing.
2955 typing.
2956
2956
2957 3) Just like %sc -l, this is a list with special attributes:
2957 3) Just like %sc -l, this is a list with special attributes:
2958
2958
2959 .l (or .list) : value as list.
2959 .l (or .list) : value as list.
2960 .n (or .nlstr): value as newline-separated string.
2960 .n (or .nlstr): value as newline-separated string.
2961 .s (or .spstr): value as whitespace-separated string.
2961 .s (or .spstr): value as whitespace-separated string.
2962
2962
2963 This is very useful when trying to use such lists as arguments to
2963 This is very useful when trying to use such lists as arguments to
2964 system commands."""
2964 system commands."""
2965
2965
2966 if parameter_s:
2966 if parameter_s:
2967 out,err = self.shell.getoutputerror(parameter_s)
2967 out,err = self.shell.getoutputerror(parameter_s)
2968 if err:
2968 if err:
2969 print >> Term.cerr,err
2969 print >> Term.cerr,err
2970 return SList(out.split('\n'))
2970 return SList(out.split('\n'))
2971
2971
2972 def magic_bg(self, parameter_s=''):
2972 def magic_bg(self, parameter_s=''):
2973 """Run a job in the background, in a separate thread.
2973 """Run a job in the background, in a separate thread.
2974
2974
2975 For example,
2975 For example,
2976
2976
2977 %bg myfunc(x,y,z=1)
2977 %bg myfunc(x,y,z=1)
2978
2978
2979 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2979 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2980 execution starts, a message will be printed indicating the job
2980 execution starts, a message will be printed indicating the job
2981 number. If your job number is 5, you can use
2981 number. If your job number is 5, you can use
2982
2982
2983 myvar = jobs.result(5) or myvar = jobs[5].result
2983 myvar = jobs.result(5) or myvar = jobs[5].result
2984
2984
2985 to assign this result to variable 'myvar'.
2985 to assign this result to variable 'myvar'.
2986
2986
2987 IPython has a job manager, accessible via the 'jobs' object. You can
2987 IPython has a job manager, accessible via the 'jobs' object. You can
2988 type jobs? to get more information about it, and use jobs.<TAB> to see
2988 type jobs? to get more information about it, and use jobs.<TAB> to see
2989 its attributes. All attributes not starting with an underscore are
2989 its attributes. All attributes not starting with an underscore are
2990 meant for public use.
2990 meant for public use.
2991
2991
2992 In particular, look at the jobs.new() method, which is used to create
2992 In particular, look at the jobs.new() method, which is used to create
2993 new jobs. This magic %bg function is just a convenience wrapper
2993 new jobs. This magic %bg function is just a convenience wrapper
2994 around jobs.new(), for expression-based jobs. If you want to create a
2994 around jobs.new(), for expression-based jobs. If you want to create a
2995 new job with an explicit function object and arguments, you must call
2995 new job with an explicit function object and arguments, you must call
2996 jobs.new() directly.
2996 jobs.new() directly.
2997
2997
2998 The jobs.new docstring also describes in detail several important
2998 The jobs.new docstring also describes in detail several important
2999 caveats associated with a thread-based model for background job
2999 caveats associated with a thread-based model for background job
3000 execution. Type jobs.new? for details.
3000 execution. Type jobs.new? for details.
3001
3001
3002 You can check the status of all jobs with jobs.status().
3002 You can check the status of all jobs with jobs.status().
3003
3003
3004 The jobs variable is set by IPython into the Python builtin namespace.
3004 The jobs variable is set by IPython into the Python builtin namespace.
3005 If you ever declare a variable named 'jobs', you will shadow this
3005 If you ever declare a variable named 'jobs', you will shadow this
3006 name. You can either delete your global jobs variable to regain
3006 name. You can either delete your global jobs variable to regain
3007 access to the job manager, or make a new name and assign it manually
3007 access to the job manager, or make a new name and assign it manually
3008 to the manager (stored in IPython's namespace). For example, to
3008 to the manager (stored in IPython's namespace). For example, to
3009 assign the job manager to the Jobs name, use:
3009 assign the job manager to the Jobs name, use:
3010
3010
3011 Jobs = __builtins__.jobs"""
3011 Jobs = __builtins__.jobs"""
3012
3012
3013 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3013 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3014
3014
3015 def magic_r(self, parameter_s=''):
3015 def magic_r(self, parameter_s=''):
3016 """Repeat previous input.
3016 """Repeat previous input.
3017
3017
3018 Note: Consider using the more powerfull %rep instead!
3018 Note: Consider using the more powerfull %rep instead!
3019
3019
3020 If given an argument, repeats the previous command which starts with
3020 If given an argument, repeats the previous command which starts with
3021 the same string, otherwise it just repeats the previous input.
3021 the same string, otherwise it just repeats the previous input.
3022
3022
3023 Shell escaped commands (with ! as first character) are not recognized
3023 Shell escaped commands (with ! as first character) are not recognized
3024 by this system, only pure python code and magic commands.
3024 by this system, only pure python code and magic commands.
3025 """
3025 """
3026
3026
3027 start = parameter_s.strip()
3027 start = parameter_s.strip()
3028 esc_magic = self.shell.ESC_MAGIC
3028 esc_magic = self.shell.ESC_MAGIC
3029 # Identify magic commands even if automagic is on (which means
3029 # Identify magic commands even if automagic is on (which means
3030 # the in-memory version is different from that typed by the user).
3030 # the in-memory version is different from that typed by the user).
3031 if self.shell.rc.automagic:
3031 if self.shell.rc.automagic:
3032 start_magic = esc_magic+start
3032 start_magic = esc_magic+start
3033 else:
3033 else:
3034 start_magic = start
3034 start_magic = start
3035 # Look through the input history in reverse
3035 # Look through the input history in reverse
3036 for n in range(len(self.shell.input_hist)-2,0,-1):
3036 for n in range(len(self.shell.input_hist)-2,0,-1):
3037 input = self.shell.input_hist[n]
3037 input = self.shell.input_hist[n]
3038 # skip plain 'r' lines so we don't recurse to infinity
3038 # skip plain 'r' lines so we don't recurse to infinity
3039 if input != '_ip.magic("r")\n' and \
3039 if input != '_ip.magic("r")\n' and \
3040 (input.startswith(start) or input.startswith(start_magic)):
3040 (input.startswith(start) or input.startswith(start_magic)):
3041 #print 'match',`input` # dbg
3041 #print 'match',`input` # dbg
3042 print 'Executing:',input,
3042 print 'Executing:',input,
3043 self.shell.runlines(input)
3043 self.shell.runlines(input)
3044 return
3044 return
3045 print 'No previous input matching `%s` found.' % start
3045 print 'No previous input matching `%s` found.' % start
3046
3046
3047
3047
3048 def magic_bookmark(self, parameter_s=''):
3048 def magic_bookmark(self, parameter_s=''):
3049 """Manage IPython's bookmark system.
3049 """Manage IPython's bookmark system.
3050
3050
3051 %bookmark <name> - set bookmark to current dir
3051 %bookmark <name> - set bookmark to current dir
3052 %bookmark <name> <dir> - set bookmark to <dir>
3052 %bookmark <name> <dir> - set bookmark to <dir>
3053 %bookmark -l - list all bookmarks
3053 %bookmark -l - list all bookmarks
3054 %bookmark -d <name> - remove bookmark
3054 %bookmark -d <name> - remove bookmark
3055 %bookmark -r - remove all bookmarks
3055 %bookmark -r - remove all bookmarks
3056
3056
3057 You can later on access a bookmarked folder with:
3057 You can later on access a bookmarked folder with:
3058 %cd -b <name>
3058 %cd -b <name>
3059 or simply '%cd <name>' if there is no directory called <name> AND
3059 or simply '%cd <name>' if there is no directory called <name> AND
3060 there is such a bookmark defined.
3060 there is such a bookmark defined.
3061
3061
3062 Your bookmarks persist through IPython sessions, but they are
3062 Your bookmarks persist through IPython sessions, but they are
3063 associated with each profile."""
3063 associated with each profile."""
3064
3064
3065 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3065 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3066 if len(args) > 2:
3066 if len(args) > 2:
3067 raise UsageError("%bookmark: too many arguments")
3067 raise UsageError("%bookmark: too many arguments")
3068
3068
3069 bkms = self.db.get('bookmarks',{})
3069 bkms = self.db.get('bookmarks',{})
3070
3070
3071 if opts.has_key('d'):
3071 if opts.has_key('d'):
3072 try:
3072 try:
3073 todel = args[0]
3073 todel = args[0]
3074 except IndexError:
3074 except IndexError:
3075 raise UsageError(
3075 raise UsageError(
3076 "%bookmark -d: must provide a bookmark to delete")
3076 "%bookmark -d: must provide a bookmark to delete")
3077 else:
3077 else:
3078 try:
3078 try:
3079 del bkms[todel]
3079 del bkms[todel]
3080 except KeyError:
3080 except KeyError:
3081 raise UsageError(
3081 raise UsageError(
3082 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3082 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3083
3083
3084 elif opts.has_key('r'):
3084 elif opts.has_key('r'):
3085 bkms = {}
3085 bkms = {}
3086 elif opts.has_key('l'):
3086 elif opts.has_key('l'):
3087 bks = bkms.keys()
3087 bks = bkms.keys()
3088 bks.sort()
3088 bks.sort()
3089 if bks:
3089 if bks:
3090 size = max(map(len,bks))
3090 size = max(map(len,bks))
3091 else:
3091 else:
3092 size = 0
3092 size = 0
3093 fmt = '%-'+str(size)+'s -> %s'
3093 fmt = '%-'+str(size)+'s -> %s'
3094 print 'Current bookmarks:'
3094 print 'Current bookmarks:'
3095 for bk in bks:
3095 for bk in bks:
3096 print fmt % (bk,bkms[bk])
3096 print fmt % (bk,bkms[bk])
3097 else:
3097 else:
3098 if not args:
3098 if not args:
3099 raise UsageError("%bookmark: You must specify the bookmark name")
3099 raise UsageError("%bookmark: You must specify the bookmark name")
3100 elif len(args)==1:
3100 elif len(args)==1:
3101 bkms[args[0]] = os.getcwd()
3101 bkms[args[0]] = os.getcwd()
3102 elif len(args)==2:
3102 elif len(args)==2:
3103 bkms[args[0]] = args[1]
3103 bkms[args[0]] = args[1]
3104 self.db['bookmarks'] = bkms
3104 self.db['bookmarks'] = bkms
3105
3105
3106 def magic_pycat(self, parameter_s=''):
3106 def magic_pycat(self, parameter_s=''):
3107 """Show a syntax-highlighted file through a pager.
3107 """Show a syntax-highlighted file through a pager.
3108
3108
3109 This magic is similar to the cat utility, but it will assume the file
3109 This magic is similar to the cat utility, but it will assume the file
3110 to be Python source and will show it with syntax highlighting. """
3110 to be Python source and will show it with syntax highlighting. """
3111
3111
3112 try:
3112 try:
3113 filename = get_py_filename(parameter_s)
3113 filename = get_py_filename(parameter_s)
3114 cont = file_read(filename)
3114 cont = file_read(filename)
3115 except IOError:
3115 except IOError:
3116 try:
3116 try:
3117 cont = eval(parameter_s,self.user_ns)
3117 cont = eval(parameter_s,self.user_ns)
3118 except NameError:
3118 except NameError:
3119 cont = None
3119 cont = None
3120 if cont is None:
3120 if cont is None:
3121 print "Error: no such file or variable"
3121 print "Error: no such file or variable"
3122 return
3122 return
3123
3123
3124 page(self.shell.pycolorize(cont),
3124 page(self.shell.pycolorize(cont),
3125 screen_lines=self.shell.rc.screen_length)
3125 screen_lines=self.shell.rc.screen_length)
3126
3126
3127 def magic_cpaste(self, parameter_s=''):
3127 def magic_cpaste(self, parameter_s=''):
3128 """Allows you to paste & execute a pre-formatted code block from clipboard
3128 """Allows you to paste & execute a pre-formatted code block from clipboard
3129
3129
3130 You must terminate the block with '--' (two minus-signs) alone on the
3130 You must terminate the block with '--' (two minus-signs) alone on the
3131 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3131 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3132 is the new sentinel for this operation)
3132 is the new sentinel for this operation)
3133
3133
3134 The block is dedented prior to execution to enable execution of method
3134 The block is dedented prior to execution to enable execution of method
3135 definitions. '>' and '+' characters at the beginning of a line are
3135 definitions. '>' and '+' characters at the beginning of a line are
3136 ignored, to allow pasting directly from e-mails or diff files. The
3136 ignored, to allow pasting directly from e-mails or diff files. The
3137 executed block is also assigned to variable named 'pasted_block' for
3137 executed block is also assigned to variable named 'pasted_block' for
3138 later editing with '%edit pasted_block'.
3138 later editing with '%edit pasted_block'.
3139
3139
3140 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3140 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3141 This assigns the pasted block to variable 'foo' as string, without
3141 This assigns the pasted block to variable 'foo' as string, without
3142 dedenting or executing it.
3142 dedenting or executing it.
3143
3143
3144 Do not be alarmed by garbled output on Windows (it's a readline bug).
3144 Do not be alarmed by garbled output on Windows (it's a readline bug).
3145 Just press enter and type -- (and press enter again) and the block
3145 Just press enter and type -- (and press enter again) and the block
3146 will be what was just pasted.
3146 will be what was just pasted.
3147
3147
3148 IPython statements (magics, shell escapes) are not supported (yet).
3148 IPython statements (magics, shell escapes) are not supported (yet).
3149 """
3149 """
3150 opts,args = self.parse_options(parameter_s,'s:',mode='string')
3150 opts,args = self.parse_options(parameter_s,'s:',mode='string')
3151 par = args.strip()
3151 par = args.strip()
3152 sentinel = opts.get('s','--')
3152 sentinel = opts.get('s','--')
3153
3153
3154 strip_from_start = [re.compile(e) for e in
3154 strip_from_start = [re.compile(e) for e in
3155 ['^(.?>)+','^In \[\d+\]:','^\++']]
3155 ['^(.?>)+','^In \[\d+\]:','^\++']]
3156 from IPython import iplib
3156 from IPython import iplib
3157 lines = []
3157 lines = []
3158 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3158 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3159 while 1:
3159 while 1:
3160 l = iplib.raw_input_original(':')
3160 l = iplib.raw_input_original(':')
3161 if l ==sentinel:
3161 if l ==sentinel:
3162 break
3162 break
3163
3163
3164 for pat in strip_from_start:
3164 for pat in strip_from_start:
3165 l = pat.sub('',l)
3165 l = pat.sub('',l)
3166 lines.append(l)
3166 lines.append(l)
3167
3167
3168 block = "\n".join(lines) + '\n'
3168 block = "\n".join(lines) + '\n'
3169 #print "block:\n",block
3169 #print "block:\n",block
3170 if not par:
3170 if not par:
3171 b = textwrap.dedent(block)
3171 b = textwrap.dedent(block)
3172 exec b in self.user_ns
3172 exec b in self.user_ns
3173 self.user_ns['pasted_block'] = b
3173 self.user_ns['pasted_block'] = b
3174 else:
3174 else:
3175 self.user_ns[par] = block
3175 self.user_ns[par] = block
3176 print "Block assigned to '%s'" % par
3176 print "Block assigned to '%s'" % par
3177
3177
3178 def magic_quickref(self,arg):
3178 def magic_quickref(self,arg):
3179 """ Show a quick reference sheet """
3179 """ Show a quick reference sheet """
3180 import IPython.usage
3180 import IPython.usage
3181 qr = IPython.usage.quick_reference + self.magic_magic('-brief')
3181 qr = IPython.usage.quick_reference + self.magic_magic('-brief')
3182
3182
3183 page(qr)
3183 page(qr)
3184
3184
3185 def magic_upgrade(self,arg):
3185 def magic_upgrade(self,arg):
3186 """ Upgrade your IPython installation
3186 """ Upgrade your IPython installation
3187
3187
3188 This will copy the config files that don't yet exist in your
3188 This will copy the config files that don't yet exist in your
3189 ipython dir from the system config dir. Use this after upgrading
3189 ipython dir from the system config dir. Use this after upgrading
3190 IPython if you don't wish to delete your .ipython dir.
3190 IPython if you don't wish to delete your .ipython dir.
3191
3191
3192 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3192 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3193 new users)
3193 new users)
3194
3194
3195 """
3195 """
3196 ip = self.getapi()
3196 ip = self.getapi()
3197 ipinstallation = path(IPython.__file__).dirname()
3197 ipinstallation = path(IPython.__file__).dirname()
3198 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'upgrade_dir.py')
3198 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'upgrade_dir.py')
3199 src_config = ipinstallation / 'UserConfig'
3199 src_config = ipinstallation / 'UserConfig'
3200 userdir = path(ip.options.ipythondir)
3200 userdir = path(ip.options.ipythondir)
3201 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3201 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3202 print ">",cmd
3202 print ">",cmd
3203 shell(cmd)
3203 shell(cmd)
3204 if arg == '-nolegacy':
3204 if arg == '-nolegacy':
3205 legacy = userdir.files('ipythonrc*')
3205 legacy = userdir.files('ipythonrc*')
3206 print "Nuking legacy files:",legacy
3206 print "Nuking legacy files:",legacy
3207
3207
3208 [p.remove() for p in legacy]
3208 [p.remove() for p in legacy]
3209 suffix = (sys.platform == 'win32' and '.ini' or '')
3209 suffix = (sys.platform == 'win32' and '.ini' or '')
3210 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3210 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3211
3211
3212
3212
3213 def magic_doctest_mode(self,parameter_s=''):
3213 def magic_doctest_mode(self,parameter_s=''):
3214 """Toggle doctest mode on and off.
3214 """Toggle doctest mode on and off.
3215
3215
3216 This mode allows you to toggle the prompt behavior between normal
3216 This mode allows you to toggle the prompt behavior between normal
3217 IPython prompts and ones that are as similar to the default IPython
3217 IPython prompts and ones that are as similar to the default IPython
3218 interpreter as possible.
3218 interpreter as possible.
3219
3219
3220 It also supports the pasting of code snippets that have leading '>>>'
3220 It also supports the pasting of code snippets that have leading '>>>'
3221 and '...' prompts in them. This means that you can paste doctests from
3221 and '...' prompts in them. This means that you can paste doctests from
3222 files or docstrings (even if they have leading whitespace), and the
3222 files or docstrings (even if they have leading whitespace), and the
3223 code will execute correctly. You can then use '%history -tn' to see
3223 code will execute correctly. You can then use '%history -tn' to see
3224 the translated history without line numbers; this will give you the
3224 the translated history without line numbers; this will give you the
3225 input after removal of all the leading prompts and whitespace, which
3225 input after removal of all the leading prompts and whitespace, which
3226 can be pasted back into an editor.
3226 can be pasted back into an editor.
3227
3227
3228 With these features, you can switch into this mode easily whenever you
3228 With these features, you can switch into this mode easily whenever you
3229 need to do testing and changes to doctests, without having to leave
3229 need to do testing and changes to doctests, without having to leave
3230 your existing IPython session.
3230 your existing IPython session.
3231 """
3231 """
3232
3232
3233 # XXX - Fix this to have cleaner activate/deactivate calls.
3233 # XXX - Fix this to have cleaner activate/deactivate calls.
3234 from IPython.Extensions import InterpreterPasteInput as ipaste
3234 from IPython.Extensions import InterpreterPasteInput as ipaste
3235 from IPython.ipstruct import Struct
3235 from IPython.ipstruct import Struct
3236
3236
3237 # Shorthands
3237 # Shorthands
3238 shell = self.shell
3238 shell = self.shell
3239 oc = shell.outputcache
3239 oc = shell.outputcache
3240 rc = shell.rc
3240 rc = shell.rc
3241 meta = shell.meta
3241 meta = shell.meta
3242 # dstore is a data store kept in the instance metadata bag to track any
3242 # dstore is a data store kept in the instance metadata bag to track any
3243 # changes we make, so we can undo them later.
3243 # changes we make, so we can undo them later.
3244 dstore = meta.setdefault('doctest_mode',Struct())
3244 dstore = meta.setdefault('doctest_mode',Struct())
3245 save_dstore = dstore.setdefault
3245 save_dstore = dstore.setdefault
3246
3246
3247 # save a few values we'll need to recover later
3247 # save a few values we'll need to recover later
3248 mode = save_dstore('mode',False)
3248 mode = save_dstore('mode',False)
3249 save_dstore('rc_pprint',rc.pprint)
3249 save_dstore('rc_pprint',rc.pprint)
3250 save_dstore('xmode',shell.InteractiveTB.mode)
3250 save_dstore('xmode',shell.InteractiveTB.mode)
3251 save_dstore('rc_separate_out',rc.separate_out)
3251 save_dstore('rc_separate_out',rc.separate_out)
3252 save_dstore('rc_separate_out2',rc.separate_out2)
3252 save_dstore('rc_separate_out2',rc.separate_out2)
3253 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3253 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3254
3254
3255 if mode == False:
3255 if mode == False:
3256 # turn on
3256 # turn on
3257 ipaste.activate_prefilter()
3257 ipaste.activate_prefilter()
3258
3258
3259 oc.prompt1.p_template = '>>> '
3259 oc.prompt1.p_template = '>>> '
3260 oc.prompt2.p_template = '... '
3260 oc.prompt2.p_template = '... '
3261 oc.prompt_out.p_template = ''
3261 oc.prompt_out.p_template = ''
3262
3262
3263 oc.output_sep = ''
3263 oc.output_sep = ''
3264 oc.output_sep2 = ''
3264 oc.output_sep2 = ''
3265
3265
3266 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3266 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3267 oc.prompt_out.pad_left = False
3267 oc.prompt_out.pad_left = False
3268
3268
3269 rc.pprint = False
3269 rc.pprint = False
3270
3270
3271 shell.magic_xmode('Plain')
3271 shell.magic_xmode('Plain')
3272
3272
3273 else:
3273 else:
3274 # turn off
3274 # turn off
3275 ipaste.deactivate_prefilter()
3275 ipaste.deactivate_prefilter()
3276
3276
3277 oc.prompt1.p_template = rc.prompt_in1
3277 oc.prompt1.p_template = rc.prompt_in1
3278 oc.prompt2.p_template = rc.prompt_in2
3278 oc.prompt2.p_template = rc.prompt_in2
3279 oc.prompt_out.p_template = rc.prompt_out
3279 oc.prompt_out.p_template = rc.prompt_out
3280
3280
3281 oc.output_sep = dstore.rc_separate_out
3281 oc.output_sep = dstore.rc_separate_out
3282 oc.output_sep2 = dstore.rc_separate_out2
3282 oc.output_sep2 = dstore.rc_separate_out2
3283
3283
3284 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3284 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3285 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3285 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3286
3286
3287 rc.pprint = dstore.rc_pprint
3287 rc.pprint = dstore.rc_pprint
3288
3288
3289 shell.magic_xmode(dstore.xmode)
3289 shell.magic_xmode(dstore.xmode)
3290
3290
3291 # Store new mode and inform
3291 # Store new mode and inform
3292 dstore.mode = bool(1-int(mode))
3292 dstore.mode = bool(1-int(mode))
3293 print 'Doctest mode is:',
3293 print 'Doctest mode is:',
3294 print ['OFF','ON'][dstore.mode]
3294 print ['OFF','ON'][dstore.mode]
3295
3295
3296 # end Magic
3296 # end Magic
General Comments 0
You need to be logged in to leave comments. Login now