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