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