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