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