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