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