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