##// END OF EJS Templates
Fix profiler stats problem with python2.5
fperez -
Show More

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

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