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