##// END OF EJS Templates
update capture per review...
MinRK -
Show More
@@ -1,1016 +1,1022 b''
1 """Implementation of execution-related magic functions.
1 """Implementation of execution-related magic functions.
2 """
2 """
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Copyright (c) 2012 The IPython Development Team.
4 # Copyright (c) 2012 The IPython Development Team.
5 #
5 #
6 # Distributed under the terms of the Modified BSD License.
6 # Distributed under the terms of the Modified BSD License.
7 #
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10
10
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12 # Imports
12 # Imports
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14
14
15 # Stdlib
15 # Stdlib
16 import __builtin__ as builtin_mod
16 import __builtin__ as builtin_mod
17 import bdb
17 import bdb
18 import os
18 import os
19 import sys
19 import sys
20 import time
20 import time
21 from StringIO import StringIO
21 from StringIO import StringIO
22
22
23 # cProfile was added in Python2.5
23 # cProfile was added in Python2.5
24 try:
24 try:
25 import cProfile as profile
25 import cProfile as profile
26 import pstats
26 import pstats
27 except ImportError:
27 except ImportError:
28 # profile isn't bundled by default in Debian for license reasons
28 # profile isn't bundled by default in Debian for license reasons
29 try:
29 try:
30 import profile, pstats
30 import profile, pstats
31 except ImportError:
31 except ImportError:
32 profile = pstats = None
32 profile = pstats = None
33
33
34 # Our own packages
34 # Our own packages
35 from IPython.core import debugger, oinspect
35 from IPython.core import debugger, oinspect
36 from IPython.core import magic_arguments
36 from IPython.core import magic_arguments
37 from IPython.core import page
37 from IPython.core import page
38 from IPython.core.error import UsageError
38 from IPython.core.error import UsageError
39 from IPython.core.macro import Macro
39 from IPython.core.macro import Macro
40 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
40 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
41 line_cell_magic, on_off, needs_local_scope)
41 line_cell_magic, on_off, needs_local_scope)
42 from IPython.testing.skipdoctest import skip_doctest
42 from IPython.testing.skipdoctest import skip_doctest
43 from IPython.utils import py3compat
43 from IPython.utils import py3compat
44 from IPython.utils.io import capture_output
44 from IPython.utils.io import capture_output
45 from IPython.utils.ipstruct import Struct
45 from IPython.utils.ipstruct import Struct
46 from IPython.utils.module_paths import find_mod
46 from IPython.utils.module_paths import find_mod
47 from IPython.utils.path import get_py_filename, unquote_filename
47 from IPython.utils.path import get_py_filename, unquote_filename
48 from IPython.utils.timing import clock, clock2
48 from IPython.utils.timing import clock, clock2
49 from IPython.utils.warn import warn, error
49 from IPython.utils.warn import warn, error
50
50
51 #-----------------------------------------------------------------------------
51 #-----------------------------------------------------------------------------
52 # Magic implementation classes
52 # Magic implementation classes
53 #-----------------------------------------------------------------------------
53 #-----------------------------------------------------------------------------
54
54
55 @magics_class
55 @magics_class
56 class ExecutionMagics(Magics):
56 class ExecutionMagics(Magics):
57 """Magics related to code execution, debugging, profiling, etc.
57 """Magics related to code execution, debugging, profiling, etc.
58
58
59 """
59 """
60
60
61 def __init__(self, shell):
61 def __init__(self, shell):
62 super(ExecutionMagics, self).__init__(shell)
62 super(ExecutionMagics, self).__init__(shell)
63 if profile is None:
63 if profile is None:
64 self.prun = self.profile_missing_notice
64 self.prun = self.profile_missing_notice
65 # Default execution function used to actually run user code.
65 # Default execution function used to actually run user code.
66 self.default_runner = None
66 self.default_runner = None
67
67
68 def profile_missing_notice(self, *args, **kwargs):
68 def profile_missing_notice(self, *args, **kwargs):
69 error("""\
69 error("""\
70 The profile module could not be found. It has been removed from the standard
70 The profile module could not be found. It has been removed from the standard
71 python packages because of its non-free license. To use profiling, install the
71 python packages because of its non-free license. To use profiling, install the
72 python-profiler package from non-free.""")
72 python-profiler package from non-free.""")
73
73
74 @skip_doctest
74 @skip_doctest
75 @line_cell_magic
75 @line_cell_magic
76 def prun(self, parameter_s='', cell=None, user_mode=True,
76 def prun(self, parameter_s='', cell=None, user_mode=True,
77 opts=None,arg_lst=None,prog_ns=None):
77 opts=None,arg_lst=None,prog_ns=None):
78
78
79 """Run a statement through the python code profiler.
79 """Run a statement through the python code profiler.
80
80
81 Usage, in line mode:
81 Usage, in line mode:
82 %prun [options] statement
82 %prun [options] statement
83
83
84 Usage, in cell mode:
84 Usage, in cell mode:
85 %%prun [options] [statement]
85 %%prun [options] [statement]
86 code...
86 code...
87 code...
87 code...
88
88
89 In cell mode, the additional code lines are appended to the (possibly
89 In cell mode, the additional code lines are appended to the (possibly
90 empty) statement in the first line. Cell mode allows you to easily
90 empty) statement in the first line. Cell mode allows you to easily
91 profile multiline blocks without having to put them in a separate
91 profile multiline blocks without having to put them in a separate
92 function.
92 function.
93
93
94 The given statement (which doesn't require quote marks) is run via the
94 The given statement (which doesn't require quote marks) is run via the
95 python profiler in a manner similar to the profile.run() function.
95 python profiler in a manner similar to the profile.run() function.
96 Namespaces are internally managed to work correctly; profile.run
96 Namespaces are internally managed to work correctly; profile.run
97 cannot be used in IPython because it makes certain assumptions about
97 cannot be used in IPython because it makes certain assumptions about
98 namespaces which do not hold under IPython.
98 namespaces which do not hold under IPython.
99
99
100 Options:
100 Options:
101
101
102 -l <limit>: you can place restrictions on what or how much of the
102 -l <limit>: you can place restrictions on what or how much of the
103 profile gets printed. The limit value can be:
103 profile gets printed. The limit value can be:
104
104
105 * A string: only information for function names containing this string
105 * A string: only information for function names containing this string
106 is printed.
106 is printed.
107
107
108 * An integer: only these many lines are printed.
108 * An integer: only these many lines are printed.
109
109
110 * A float (between 0 and 1): this fraction of the report is printed
110 * A float (between 0 and 1): this fraction of the report is printed
111 (for example, use a limit of 0.4 to see the topmost 40% only).
111 (for example, use a limit of 0.4 to see the topmost 40% only).
112
112
113 You can combine several limits with repeated use of the option. For
113 You can combine several limits with repeated use of the option. For
114 example, '-l __init__ -l 5' will print only the topmost 5 lines of
114 example, '-l __init__ -l 5' will print only the topmost 5 lines of
115 information about class constructors.
115 information about class constructors.
116
116
117 -r: return the pstats.Stats object generated by the profiling. This
117 -r: return the pstats.Stats object generated by the profiling. This
118 object has all the information about the profile in it, and you can
118 object has all the information about the profile in it, and you can
119 later use it for further analysis or in other functions.
119 later use it for further analysis or in other functions.
120
120
121 -s <key>: sort profile by given key. You can provide more than one key
121 -s <key>: sort profile by given key. You can provide more than one key
122 by using the option several times: '-s key1 -s key2 -s key3...'. The
122 by using the option several times: '-s key1 -s key2 -s key3...'. The
123 default sorting key is 'time'.
123 default sorting key is 'time'.
124
124
125 The following is copied verbatim from the profile documentation
125 The following is copied verbatim from the profile documentation
126 referenced below:
126 referenced below:
127
127
128 When more than one key is provided, additional keys are used as
128 When more than one key is provided, additional keys are used as
129 secondary criteria when the there is equality in all keys selected
129 secondary criteria when the there is equality in all keys selected
130 before them.
130 before them.
131
131
132 Abbreviations can be used for any key names, as long as the
132 Abbreviations can be used for any key names, as long as the
133 abbreviation is unambiguous. The following are the keys currently
133 abbreviation is unambiguous. The following are the keys currently
134 defined:
134 defined:
135
135
136 Valid Arg Meaning
136 Valid Arg Meaning
137 "calls" call count
137 "calls" call count
138 "cumulative" cumulative time
138 "cumulative" cumulative time
139 "file" file name
139 "file" file name
140 "module" file name
140 "module" file name
141 "pcalls" primitive call count
141 "pcalls" primitive call count
142 "line" line number
142 "line" line number
143 "name" function name
143 "name" function name
144 "nfl" name/file/line
144 "nfl" name/file/line
145 "stdname" standard name
145 "stdname" standard name
146 "time" internal time
146 "time" internal time
147
147
148 Note that all sorts on statistics are in descending order (placing
148 Note that all sorts on statistics are in descending order (placing
149 most time consuming items first), where as name, file, and line number
149 most time consuming items first), where as name, file, and line number
150 searches are in ascending order (i.e., alphabetical). The subtle
150 searches are in ascending order (i.e., alphabetical). The subtle
151 distinction between "nfl" and "stdname" is that the standard name is a
151 distinction between "nfl" and "stdname" is that the standard name is a
152 sort of the name as printed, which means that the embedded line
152 sort of the name as printed, which means that the embedded line
153 numbers get compared in an odd way. For example, lines 3, 20, and 40
153 numbers get compared in an odd way. For example, lines 3, 20, and 40
154 would (if the file names were the same) appear in the string order
154 would (if the file names were the same) appear in the string order
155 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
155 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
156 line numbers. In fact, sort_stats("nfl") is the same as
156 line numbers. In fact, sort_stats("nfl") is the same as
157 sort_stats("name", "file", "line").
157 sort_stats("name", "file", "line").
158
158
159 -T <filename>: save profile results as shown on screen to a text
159 -T <filename>: save profile results as shown on screen to a text
160 file. The profile is still shown on screen.
160 file. The profile is still shown on screen.
161
161
162 -D <filename>: save (via dump_stats) profile statistics to given
162 -D <filename>: save (via dump_stats) profile statistics to given
163 filename. This data is in a format understood by the pstats module, and
163 filename. This data is in a format understood by the pstats module, and
164 is generated by a call to the dump_stats() method of profile
164 is generated by a call to the dump_stats() method of profile
165 objects. The profile is still shown on screen.
165 objects. The profile is still shown on screen.
166
166
167 -q: suppress output to the pager. Best used with -T and/or -D above.
167 -q: suppress output to the pager. Best used with -T and/or -D above.
168
168
169 If you want to run complete programs under the profiler's control, use
169 If you want to run complete programs under the profiler's control, use
170 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
170 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
171 contains profiler specific options as described here.
171 contains profiler specific options as described here.
172
172
173 You can read the complete documentation for the profile module with::
173 You can read the complete documentation for the profile module with::
174
174
175 In [1]: import profile; profile.help()
175 In [1]: import profile; profile.help()
176 """
176 """
177
177
178 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
178 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
179
179
180 if user_mode: # regular user call
180 if user_mode: # regular user call
181 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
181 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
182 list_all=True, posix=False)
182 list_all=True, posix=False)
183 namespace = self.shell.user_ns
183 namespace = self.shell.user_ns
184 if cell is not None:
184 if cell is not None:
185 arg_str += '\n' + cell
185 arg_str += '\n' + cell
186 else: # called to run a program by %run -p
186 else: # called to run a program by %run -p
187 try:
187 try:
188 filename = get_py_filename(arg_lst[0])
188 filename = get_py_filename(arg_lst[0])
189 except IOError as e:
189 except IOError as e:
190 try:
190 try:
191 msg = str(e)
191 msg = str(e)
192 except UnicodeError:
192 except UnicodeError:
193 msg = e.message
193 msg = e.message
194 error(msg)
194 error(msg)
195 return
195 return
196
196
197 arg_str = 'execfile(filename,prog_ns)'
197 arg_str = 'execfile(filename,prog_ns)'
198 namespace = {
198 namespace = {
199 'execfile': self.shell.safe_execfile,
199 'execfile': self.shell.safe_execfile,
200 'prog_ns': prog_ns,
200 'prog_ns': prog_ns,
201 'filename': filename
201 'filename': filename
202 }
202 }
203
203
204 opts.merge(opts_def)
204 opts.merge(opts_def)
205
205
206 prof = profile.Profile()
206 prof = profile.Profile()
207 try:
207 try:
208 prof = prof.runctx(arg_str,namespace,namespace)
208 prof = prof.runctx(arg_str,namespace,namespace)
209 sys_exit = ''
209 sys_exit = ''
210 except SystemExit:
210 except SystemExit:
211 sys_exit = """*** SystemExit exception caught in code being profiled."""
211 sys_exit = """*** SystemExit exception caught in code being profiled."""
212
212
213 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
213 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
214
214
215 lims = opts.l
215 lims = opts.l
216 if lims:
216 if lims:
217 lims = [] # rebuild lims with ints/floats/strings
217 lims = [] # rebuild lims with ints/floats/strings
218 for lim in opts.l:
218 for lim in opts.l:
219 try:
219 try:
220 lims.append(int(lim))
220 lims.append(int(lim))
221 except ValueError:
221 except ValueError:
222 try:
222 try:
223 lims.append(float(lim))
223 lims.append(float(lim))
224 except ValueError:
224 except ValueError:
225 lims.append(lim)
225 lims.append(lim)
226
226
227 # Trap output.
227 # Trap output.
228 stdout_trap = StringIO()
228 stdout_trap = StringIO()
229
229
230 if hasattr(stats,'stream'):
230 if hasattr(stats,'stream'):
231 # In newer versions of python, the stats object has a 'stream'
231 # In newer versions of python, the stats object has a 'stream'
232 # attribute to write into.
232 # attribute to write into.
233 stats.stream = stdout_trap
233 stats.stream = stdout_trap
234 stats.print_stats(*lims)
234 stats.print_stats(*lims)
235 else:
235 else:
236 # For older versions, we manually redirect stdout during printing
236 # For older versions, we manually redirect stdout during printing
237 sys_stdout = sys.stdout
237 sys_stdout = sys.stdout
238 try:
238 try:
239 sys.stdout = stdout_trap
239 sys.stdout = stdout_trap
240 stats.print_stats(*lims)
240 stats.print_stats(*lims)
241 finally:
241 finally:
242 sys.stdout = sys_stdout
242 sys.stdout = sys_stdout
243
243
244 output = stdout_trap.getvalue()
244 output = stdout_trap.getvalue()
245 output = output.rstrip()
245 output = output.rstrip()
246
246
247 if 'q' not in opts:
247 if 'q' not in opts:
248 page.page(output)
248 page.page(output)
249 print sys_exit,
249 print sys_exit,
250
250
251 dump_file = opts.D[0]
251 dump_file = opts.D[0]
252 text_file = opts.T[0]
252 text_file = opts.T[0]
253 if dump_file:
253 if dump_file:
254 dump_file = unquote_filename(dump_file)
254 dump_file = unquote_filename(dump_file)
255 prof.dump_stats(dump_file)
255 prof.dump_stats(dump_file)
256 print '\n*** Profile stats marshalled to file',\
256 print '\n*** Profile stats marshalled to file',\
257 `dump_file`+'.',sys_exit
257 `dump_file`+'.',sys_exit
258 if text_file:
258 if text_file:
259 text_file = unquote_filename(text_file)
259 text_file = unquote_filename(text_file)
260 pfile = open(text_file,'w')
260 pfile = open(text_file,'w')
261 pfile.write(output)
261 pfile.write(output)
262 pfile.close()
262 pfile.close()
263 print '\n*** Profile printout saved to text file',\
263 print '\n*** Profile printout saved to text file',\
264 `text_file`+'.',sys_exit
264 `text_file`+'.',sys_exit
265
265
266 if opts.has_key('r'):
266 if opts.has_key('r'):
267 return stats
267 return stats
268 else:
268 else:
269 return None
269 return None
270
270
271 @line_magic
271 @line_magic
272 def pdb(self, parameter_s=''):
272 def pdb(self, parameter_s=''):
273 """Control the automatic calling of the pdb interactive debugger.
273 """Control the automatic calling of the pdb interactive debugger.
274
274
275 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
275 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
276 argument it works as a toggle.
276 argument it works as a toggle.
277
277
278 When an exception is triggered, IPython can optionally call the
278 When an exception is triggered, IPython can optionally call the
279 interactive pdb debugger after the traceback printout. %pdb toggles
279 interactive pdb debugger after the traceback printout. %pdb toggles
280 this feature on and off.
280 this feature on and off.
281
281
282 The initial state of this feature is set in your configuration
282 The initial state of this feature is set in your configuration
283 file (the option is ``InteractiveShell.pdb``).
283 file (the option is ``InteractiveShell.pdb``).
284
284
285 If you want to just activate the debugger AFTER an exception has fired,
285 If you want to just activate the debugger AFTER an exception has fired,
286 without having to type '%pdb on' and rerunning your code, you can use
286 without having to type '%pdb on' and rerunning your code, you can use
287 the %debug magic."""
287 the %debug magic."""
288
288
289 par = parameter_s.strip().lower()
289 par = parameter_s.strip().lower()
290
290
291 if par:
291 if par:
292 try:
292 try:
293 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
293 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
294 except KeyError:
294 except KeyError:
295 print ('Incorrect argument. Use on/1, off/0, '
295 print ('Incorrect argument. Use on/1, off/0, '
296 'or nothing for a toggle.')
296 'or nothing for a toggle.')
297 return
297 return
298 else:
298 else:
299 # toggle
299 # toggle
300 new_pdb = not self.shell.call_pdb
300 new_pdb = not self.shell.call_pdb
301
301
302 # set on the shell
302 # set on the shell
303 self.shell.call_pdb = new_pdb
303 self.shell.call_pdb = new_pdb
304 print 'Automatic pdb calling has been turned',on_off(new_pdb)
304 print 'Automatic pdb calling has been turned',on_off(new_pdb)
305
305
306 @line_magic
306 @line_magic
307 def debug(self, parameter_s=''):
307 def debug(self, parameter_s=''):
308 """Activate the interactive debugger in post-mortem mode.
308 """Activate the interactive debugger in post-mortem mode.
309
309
310 If an exception has just occurred, this lets you inspect its stack
310 If an exception has just occurred, this lets you inspect its stack
311 frames interactively. Note that this will always work only on the last
311 frames interactively. Note that this will always work only on the last
312 traceback that occurred, so you must call this quickly after an
312 traceback that occurred, so you must call this quickly after an
313 exception that you wish to inspect has fired, because if another one
313 exception that you wish to inspect has fired, because if another one
314 occurs, it clobbers the previous one.
314 occurs, it clobbers the previous one.
315
315
316 If you want IPython to automatically do this on every exception, see
316 If you want IPython to automatically do this on every exception, see
317 the %pdb magic for more details.
317 the %pdb magic for more details.
318 """
318 """
319 self.shell.debugger(force=True)
319 self.shell.debugger(force=True)
320
320
321 @line_magic
321 @line_magic
322 def tb(self, s):
322 def tb(self, s):
323 """Print the last traceback with the currently active exception mode.
323 """Print the last traceback with the currently active exception mode.
324
324
325 See %xmode for changing exception reporting modes."""
325 See %xmode for changing exception reporting modes."""
326 self.shell.showtraceback()
326 self.shell.showtraceback()
327
327
328 @skip_doctest
328 @skip_doctest
329 @line_magic
329 @line_magic
330 def run(self, parameter_s='', runner=None,
330 def run(self, parameter_s='', runner=None,
331 file_finder=get_py_filename):
331 file_finder=get_py_filename):
332 """Run the named file inside IPython as a program.
332 """Run the named file inside IPython as a program.
333
333
334 Usage:\\
334 Usage:\\
335 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
335 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
336
336
337 Parameters after the filename are passed as command-line arguments to
337 Parameters after the filename are passed as command-line arguments to
338 the program (put in sys.argv). Then, control returns to IPython's
338 the program (put in sys.argv). Then, control returns to IPython's
339 prompt.
339 prompt.
340
340
341 This is similar to running at a system prompt:\\
341 This is similar to running at a system prompt:\\
342 $ python file args\\
342 $ python file args\\
343 but with the advantage of giving you IPython's tracebacks, and of
343 but with the advantage of giving you IPython's tracebacks, and of
344 loading all variables into your interactive namespace for further use
344 loading all variables into your interactive namespace for further use
345 (unless -p is used, see below).
345 (unless -p is used, see below).
346
346
347 The file is executed in a namespace initially consisting only of
347 The file is executed in a namespace initially consisting only of
348 __name__=='__main__' and sys.argv constructed as indicated. It thus
348 __name__=='__main__' and sys.argv constructed as indicated. It thus
349 sees its environment as if it were being run as a stand-alone program
349 sees its environment as if it were being run as a stand-alone program
350 (except for sharing global objects such as previously imported
350 (except for sharing global objects such as previously imported
351 modules). But after execution, the IPython interactive namespace gets
351 modules). But after execution, the IPython interactive namespace gets
352 updated with all variables defined in the program (except for __name__
352 updated with all variables defined in the program (except for __name__
353 and sys.argv). This allows for very convenient loading of code for
353 and sys.argv). This allows for very convenient loading of code for
354 interactive work, while giving each program a 'clean sheet' to run in.
354 interactive work, while giving each program a 'clean sheet' to run in.
355
355
356 Options:
356 Options:
357
357
358 -n: __name__ is NOT set to '__main__', but to the running file's name
358 -n: __name__ is NOT set to '__main__', but to the running file's name
359 without extension (as python does under import). This allows running
359 without extension (as python does under import). This allows running
360 scripts and reloading the definitions in them without calling code
360 scripts and reloading the definitions in them without calling code
361 protected by an ' if __name__ == "__main__" ' clause.
361 protected by an ' if __name__ == "__main__" ' clause.
362
362
363 -i: run the file in IPython's namespace instead of an empty one. This
363 -i: run the file in IPython's namespace instead of an empty one. This
364 is useful if you are experimenting with code written in a text editor
364 is useful if you are experimenting with code written in a text editor
365 which depends on variables defined interactively.
365 which depends on variables defined interactively.
366
366
367 -e: ignore sys.exit() calls or SystemExit exceptions in the script
367 -e: ignore sys.exit() calls or SystemExit exceptions in the script
368 being run. This is particularly useful if IPython is being used to
368 being run. This is particularly useful if IPython is being used to
369 run unittests, which always exit with a sys.exit() call. In such
369 run unittests, which always exit with a sys.exit() call. In such
370 cases you are interested in the output of the test results, not in
370 cases you are interested in the output of the test results, not in
371 seeing a traceback of the unittest module.
371 seeing a traceback of the unittest module.
372
372
373 -t: print timing information at the end of the run. IPython will give
373 -t: print timing information at the end of the run. IPython will give
374 you an estimated CPU time consumption for your script, which under
374 you an estimated CPU time consumption for your script, which under
375 Unix uses the resource module to avoid the wraparound problems of
375 Unix uses the resource module to avoid the wraparound problems of
376 time.clock(). Under Unix, an estimate of time spent on system tasks
376 time.clock(). Under Unix, an estimate of time spent on system tasks
377 is also given (for Windows platforms this is reported as 0.0).
377 is also given (for Windows platforms this is reported as 0.0).
378
378
379 If -t is given, an additional -N<N> option can be given, where <N>
379 If -t is given, an additional -N<N> option can be given, where <N>
380 must be an integer indicating how many times you want the script to
380 must be an integer indicating how many times you want the script to
381 run. The final timing report will include total and per run results.
381 run. The final timing report will include total and per run results.
382
382
383 For example (testing the script uniq_stable.py)::
383 For example (testing the script uniq_stable.py)::
384
384
385 In [1]: run -t uniq_stable
385 In [1]: run -t uniq_stable
386
386
387 IPython CPU timings (estimated):\\
387 IPython CPU timings (estimated):\\
388 User : 0.19597 s.\\
388 User : 0.19597 s.\\
389 System: 0.0 s.\\
389 System: 0.0 s.\\
390
390
391 In [2]: run -t -N5 uniq_stable
391 In [2]: run -t -N5 uniq_stable
392
392
393 IPython CPU timings (estimated):\\
393 IPython CPU timings (estimated):\\
394 Total runs performed: 5\\
394 Total runs performed: 5\\
395 Times : Total Per run\\
395 Times : Total Per run\\
396 User : 0.910862 s, 0.1821724 s.\\
396 User : 0.910862 s, 0.1821724 s.\\
397 System: 0.0 s, 0.0 s.
397 System: 0.0 s, 0.0 s.
398
398
399 -d: run your program under the control of pdb, the Python debugger.
399 -d: run your program under the control of pdb, the Python debugger.
400 This allows you to execute your program step by step, watch variables,
400 This allows you to execute your program step by step, watch variables,
401 etc. Internally, what IPython does is similar to calling:
401 etc. Internally, what IPython does is similar to calling:
402
402
403 pdb.run('execfile("YOURFILENAME")')
403 pdb.run('execfile("YOURFILENAME")')
404
404
405 with a breakpoint set on line 1 of your file. You can change the line
405 with a breakpoint set on line 1 of your file. You can change the line
406 number for this automatic breakpoint to be <N> by using the -bN option
406 number for this automatic breakpoint to be <N> by using the -bN option
407 (where N must be an integer). For example::
407 (where N must be an integer). For example::
408
408
409 %run -d -b40 myscript
409 %run -d -b40 myscript
410
410
411 will set the first breakpoint at line 40 in myscript.py. Note that
411 will set the first breakpoint at line 40 in myscript.py. Note that
412 the first breakpoint must be set on a line which actually does
412 the first breakpoint must be set on a line which actually does
413 something (not a comment or docstring) for it to stop execution.
413 something (not a comment or docstring) for it to stop execution.
414
414
415 When the pdb debugger starts, you will see a (Pdb) prompt. You must
415 When the pdb debugger starts, you will see a (Pdb) prompt. You must
416 first enter 'c' (without quotes) to start execution up to the first
416 first enter 'c' (without quotes) to start execution up to the first
417 breakpoint.
417 breakpoint.
418
418
419 Entering 'help' gives information about the use of the debugger. You
419 Entering 'help' gives information about the use of the debugger. You
420 can easily see pdb's full documentation with "import pdb;pdb.help()"
420 can easily see pdb's full documentation with "import pdb;pdb.help()"
421 at a prompt.
421 at a prompt.
422
422
423 -p: run program under the control of the Python profiler module (which
423 -p: run program under the control of the Python profiler module (which
424 prints a detailed report of execution times, function calls, etc).
424 prints a detailed report of execution times, function calls, etc).
425
425
426 You can pass other options after -p which affect the behavior of the
426 You can pass other options after -p which affect the behavior of the
427 profiler itself. See the docs for %prun for details.
427 profiler itself. See the docs for %prun for details.
428
428
429 In this mode, the program's variables do NOT propagate back to the
429 In this mode, the program's variables do NOT propagate back to the
430 IPython interactive namespace (because they remain in the namespace
430 IPython interactive namespace (because they remain in the namespace
431 where the profiler executes them).
431 where the profiler executes them).
432
432
433 Internally this triggers a call to %prun, see its documentation for
433 Internally this triggers a call to %prun, see its documentation for
434 details on the options available specifically for profiling.
434 details on the options available specifically for profiling.
435
435
436 There is one special usage for which the text above doesn't apply:
436 There is one special usage for which the text above doesn't apply:
437 if the filename ends with .ipy, the file is run as ipython script,
437 if the filename ends with .ipy, the file is run as ipython script,
438 just as if the commands were written on IPython prompt.
438 just as if the commands were written on IPython prompt.
439
439
440 -m: specify module name to load instead of script path. Similar to
440 -m: specify module name to load instead of script path. Similar to
441 the -m option for the python interpreter. Use this option last if you
441 the -m option for the python interpreter. Use this option last if you
442 want to combine with other %run options. Unlike the python interpreter
442 want to combine with other %run options. Unlike the python interpreter
443 only source modules are allowed no .pyc or .pyo files.
443 only source modules are allowed no .pyc or .pyo files.
444 For example::
444 For example::
445
445
446 %run -m example
446 %run -m example
447
447
448 will run the example module.
448 will run the example module.
449
449
450 """
450 """
451
451
452 # get arguments and set sys.argv for program to be run.
452 # get arguments and set sys.argv for program to be run.
453 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
453 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
454 mode='list', list_all=1)
454 mode='list', list_all=1)
455 if "m" in opts:
455 if "m" in opts:
456 modulename = opts["m"][0]
456 modulename = opts["m"][0]
457 modpath = find_mod(modulename)
457 modpath = find_mod(modulename)
458 if modpath is None:
458 if modpath is None:
459 warn('%r is not a valid modulename on sys.path'%modulename)
459 warn('%r is not a valid modulename on sys.path'%modulename)
460 return
460 return
461 arg_lst = [modpath] + arg_lst
461 arg_lst = [modpath] + arg_lst
462 try:
462 try:
463 filename = file_finder(arg_lst[0])
463 filename = file_finder(arg_lst[0])
464 except IndexError:
464 except IndexError:
465 warn('you must provide at least a filename.')
465 warn('you must provide at least a filename.')
466 print '\n%run:\n', oinspect.getdoc(self.run)
466 print '\n%run:\n', oinspect.getdoc(self.run)
467 return
467 return
468 except IOError as e:
468 except IOError as e:
469 try:
469 try:
470 msg = str(e)
470 msg = str(e)
471 except UnicodeError:
471 except UnicodeError:
472 msg = e.message
472 msg = e.message
473 error(msg)
473 error(msg)
474 return
474 return
475
475
476 if filename.lower().endswith('.ipy'):
476 if filename.lower().endswith('.ipy'):
477 self.shell.safe_execfile_ipy(filename)
477 self.shell.safe_execfile_ipy(filename)
478 return
478 return
479
479
480 # Control the response to exit() calls made by the script being run
480 # Control the response to exit() calls made by the script being run
481 exit_ignore = 'e' in opts
481 exit_ignore = 'e' in opts
482
482
483 # Make sure that the running script gets a proper sys.argv as if it
483 # Make sure that the running script gets a proper sys.argv as if it
484 # were run from a system shell.
484 # were run from a system shell.
485 save_argv = sys.argv # save it for later restoring
485 save_argv = sys.argv # save it for later restoring
486
486
487 # simulate shell expansion on arguments, at least tilde expansion
487 # simulate shell expansion on arguments, at least tilde expansion
488 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
488 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
489
489
490 sys.argv = [filename] + args # put in the proper filename
490 sys.argv = [filename] + args # put in the proper filename
491 # protect sys.argv from potential unicode strings on Python 2:
491 # protect sys.argv from potential unicode strings on Python 2:
492 if not py3compat.PY3:
492 if not py3compat.PY3:
493 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
493 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
494
494
495 if 'i' in opts:
495 if 'i' in opts:
496 # Run in user's interactive namespace
496 # Run in user's interactive namespace
497 prog_ns = self.shell.user_ns
497 prog_ns = self.shell.user_ns
498 __name__save = self.shell.user_ns['__name__']
498 __name__save = self.shell.user_ns['__name__']
499 prog_ns['__name__'] = '__main__'
499 prog_ns['__name__'] = '__main__'
500 main_mod = self.shell.new_main_mod(prog_ns)
500 main_mod = self.shell.new_main_mod(prog_ns)
501 else:
501 else:
502 # Run in a fresh, empty namespace
502 # Run in a fresh, empty namespace
503 if 'n' in opts:
503 if 'n' in opts:
504 name = os.path.splitext(os.path.basename(filename))[0]
504 name = os.path.splitext(os.path.basename(filename))[0]
505 else:
505 else:
506 name = '__main__'
506 name = '__main__'
507
507
508 main_mod = self.shell.new_main_mod()
508 main_mod = self.shell.new_main_mod()
509 prog_ns = main_mod.__dict__
509 prog_ns = main_mod.__dict__
510 prog_ns['__name__'] = name
510 prog_ns['__name__'] = name
511
511
512 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
512 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
513 # set the __file__ global in the script's namespace
513 # set the __file__ global in the script's namespace
514 prog_ns['__file__'] = filename
514 prog_ns['__file__'] = filename
515
515
516 # pickle fix. See interactiveshell for an explanation. But we need to
516 # pickle fix. See interactiveshell for an explanation. But we need to
517 # make sure that, if we overwrite __main__, we replace it at the end
517 # make sure that, if we overwrite __main__, we replace it at the end
518 main_mod_name = prog_ns['__name__']
518 main_mod_name = prog_ns['__name__']
519
519
520 if main_mod_name == '__main__':
520 if main_mod_name == '__main__':
521 restore_main = sys.modules['__main__']
521 restore_main = sys.modules['__main__']
522 else:
522 else:
523 restore_main = False
523 restore_main = False
524
524
525 # This needs to be undone at the end to prevent holding references to
525 # This needs to be undone at the end to prevent holding references to
526 # every single object ever created.
526 # every single object ever created.
527 sys.modules[main_mod_name] = main_mod
527 sys.modules[main_mod_name] = main_mod
528
528
529 try:
529 try:
530 stats = None
530 stats = None
531 with self.shell.readline_no_record:
531 with self.shell.readline_no_record:
532 if 'p' in opts:
532 if 'p' in opts:
533 stats = self.prun('', None, False, opts, arg_lst, prog_ns)
533 stats = self.prun('', None, False, opts, arg_lst, prog_ns)
534 else:
534 else:
535 if 'd' in opts:
535 if 'd' in opts:
536 deb = debugger.Pdb(self.shell.colors)
536 deb = debugger.Pdb(self.shell.colors)
537 # reset Breakpoint state, which is moronically kept
537 # reset Breakpoint state, which is moronically kept
538 # in a class
538 # in a class
539 bdb.Breakpoint.next = 1
539 bdb.Breakpoint.next = 1
540 bdb.Breakpoint.bplist = {}
540 bdb.Breakpoint.bplist = {}
541 bdb.Breakpoint.bpbynumber = [None]
541 bdb.Breakpoint.bpbynumber = [None]
542 # Set an initial breakpoint to stop execution
542 # Set an initial breakpoint to stop execution
543 maxtries = 10
543 maxtries = 10
544 bp = int(opts.get('b', [1])[0])
544 bp = int(opts.get('b', [1])[0])
545 checkline = deb.checkline(filename, bp)
545 checkline = deb.checkline(filename, bp)
546 if not checkline:
546 if not checkline:
547 for bp in range(bp + 1, bp + maxtries + 1):
547 for bp in range(bp + 1, bp + maxtries + 1):
548 if deb.checkline(filename, bp):
548 if deb.checkline(filename, bp):
549 break
549 break
550 else:
550 else:
551 msg = ("\nI failed to find a valid line to set "
551 msg = ("\nI failed to find a valid line to set "
552 "a breakpoint\n"
552 "a breakpoint\n"
553 "after trying up to line: %s.\n"
553 "after trying up to line: %s.\n"
554 "Please set a valid breakpoint manually "
554 "Please set a valid breakpoint manually "
555 "with the -b option." % bp)
555 "with the -b option." % bp)
556 error(msg)
556 error(msg)
557 return
557 return
558 # if we find a good linenumber, set the breakpoint
558 # if we find a good linenumber, set the breakpoint
559 deb.do_break('%s:%s' % (filename, bp))
559 deb.do_break('%s:%s' % (filename, bp))
560 # Start file run
560 # Start file run
561 print "NOTE: Enter 'c' at the",
561 print "NOTE: Enter 'c' at the",
562 print "%s prompt to start your script." % deb.prompt
562 print "%s prompt to start your script." % deb.prompt
563 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
563 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
564 try:
564 try:
565 deb.run('execfile("%s", prog_ns)' % filename, ns)
565 deb.run('execfile("%s", prog_ns)' % filename, ns)
566
566
567 except:
567 except:
568 etype, value, tb = sys.exc_info()
568 etype, value, tb = sys.exc_info()
569 # Skip three frames in the traceback: the %run one,
569 # Skip three frames in the traceback: the %run one,
570 # one inside bdb.py, and the command-line typed by the
570 # one inside bdb.py, and the command-line typed by the
571 # user (run by exec in pdb itself).
571 # user (run by exec in pdb itself).
572 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
572 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
573 else:
573 else:
574 if runner is None:
574 if runner is None:
575 runner = self.default_runner
575 runner = self.default_runner
576 if runner is None:
576 if runner is None:
577 runner = self.shell.safe_execfile
577 runner = self.shell.safe_execfile
578 if 't' in opts:
578 if 't' in opts:
579 # timed execution
579 # timed execution
580 try:
580 try:
581 nruns = int(opts['N'][0])
581 nruns = int(opts['N'][0])
582 if nruns < 1:
582 if nruns < 1:
583 error('Number of runs must be >=1')
583 error('Number of runs must be >=1')
584 return
584 return
585 except (KeyError):
585 except (KeyError):
586 nruns = 1
586 nruns = 1
587 twall0 = time.time()
587 twall0 = time.time()
588 if nruns == 1:
588 if nruns == 1:
589 t0 = clock2()
589 t0 = clock2()
590 runner(filename, prog_ns, prog_ns,
590 runner(filename, prog_ns, prog_ns,
591 exit_ignore=exit_ignore)
591 exit_ignore=exit_ignore)
592 t1 = clock2()
592 t1 = clock2()
593 t_usr = t1[0] - t0[0]
593 t_usr = t1[0] - t0[0]
594 t_sys = t1[1] - t0[1]
594 t_sys = t1[1] - t0[1]
595 print "\nIPython CPU timings (estimated):"
595 print "\nIPython CPU timings (estimated):"
596 print " User : %10.2f s." % t_usr
596 print " User : %10.2f s." % t_usr
597 print " System : %10.2f s." % t_sys
597 print " System : %10.2f s." % t_sys
598 else:
598 else:
599 runs = range(nruns)
599 runs = range(nruns)
600 t0 = clock2()
600 t0 = clock2()
601 for nr in runs:
601 for nr in runs:
602 runner(filename, prog_ns, prog_ns,
602 runner(filename, prog_ns, prog_ns,
603 exit_ignore=exit_ignore)
603 exit_ignore=exit_ignore)
604 t1 = clock2()
604 t1 = clock2()
605 t_usr = t1[0] - t0[0]
605 t_usr = t1[0] - t0[0]
606 t_sys = t1[1] - t0[1]
606 t_sys = t1[1] - t0[1]
607 print "\nIPython CPU timings (estimated):"
607 print "\nIPython CPU timings (estimated):"
608 print "Total runs performed:", nruns
608 print "Total runs performed:", nruns
609 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
609 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
610 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
610 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
611 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
611 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
612 twall1 = time.time()
612 twall1 = time.time()
613 print "Wall time: %10.2f s." % (twall1 - twall0)
613 print "Wall time: %10.2f s." % (twall1 - twall0)
614
614
615 else:
615 else:
616 # regular execution
616 # regular execution
617 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
617 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
618
618
619 if 'i' in opts:
619 if 'i' in opts:
620 self.shell.user_ns['__name__'] = __name__save
620 self.shell.user_ns['__name__'] = __name__save
621 else:
621 else:
622 # The shell MUST hold a reference to prog_ns so after %run
622 # The shell MUST hold a reference to prog_ns so after %run
623 # exits, the python deletion mechanism doesn't zero it out
623 # exits, the python deletion mechanism doesn't zero it out
624 # (leaving dangling references).
624 # (leaving dangling references).
625 self.shell.cache_main_mod(prog_ns, filename)
625 self.shell.cache_main_mod(prog_ns, filename)
626 # update IPython interactive namespace
626 # update IPython interactive namespace
627
627
628 # Some forms of read errors on the file may mean the
628 # Some forms of read errors on the file may mean the
629 # __name__ key was never set; using pop we don't have to
629 # __name__ key was never set; using pop we don't have to
630 # worry about a possible KeyError.
630 # worry about a possible KeyError.
631 prog_ns.pop('__name__', None)
631 prog_ns.pop('__name__', None)
632
632
633 self.shell.user_ns.update(prog_ns)
633 self.shell.user_ns.update(prog_ns)
634 finally:
634 finally:
635 # It's a bit of a mystery why, but __builtins__ can change from
635 # It's a bit of a mystery why, but __builtins__ can change from
636 # being a module to becoming a dict missing some key data after
636 # being a module to becoming a dict missing some key data after
637 # %run. As best I can see, this is NOT something IPython is doing
637 # %run. As best I can see, this is NOT something IPython is doing
638 # at all, and similar problems have been reported before:
638 # at all, and similar problems have been reported before:
639 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
639 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
640 # Since this seems to be done by the interpreter itself, the best
640 # Since this seems to be done by the interpreter itself, the best
641 # we can do is to at least restore __builtins__ for the user on
641 # we can do is to at least restore __builtins__ for the user on
642 # exit.
642 # exit.
643 self.shell.user_ns['__builtins__'] = builtin_mod
643 self.shell.user_ns['__builtins__'] = builtin_mod
644
644
645 # Ensure key global structures are restored
645 # Ensure key global structures are restored
646 sys.argv = save_argv
646 sys.argv = save_argv
647 if restore_main:
647 if restore_main:
648 sys.modules['__main__'] = restore_main
648 sys.modules['__main__'] = restore_main
649 else:
649 else:
650 # Remove from sys.modules the reference to main_mod we'd
650 # Remove from sys.modules the reference to main_mod we'd
651 # added. Otherwise it will trap references to objects
651 # added. Otherwise it will trap references to objects
652 # contained therein.
652 # contained therein.
653 del sys.modules[main_mod_name]
653 del sys.modules[main_mod_name]
654
654
655 return stats
655 return stats
656
656
657 @skip_doctest
657 @skip_doctest
658 @line_cell_magic
658 @line_cell_magic
659 def timeit(self, line='', cell=None):
659 def timeit(self, line='', cell=None):
660 """Time execution of a Python statement or expression
660 """Time execution of a Python statement or expression
661
661
662 Usage, in line mode:
662 Usage, in line mode:
663 %timeit [-n<N> -r<R> [-t|-c]] statement
663 %timeit [-n<N> -r<R> [-t|-c]] statement
664 or in cell mode:
664 or in cell mode:
665 %%timeit [-n<N> -r<R> [-t|-c]] setup_code
665 %%timeit [-n<N> -r<R> [-t|-c]] setup_code
666 code
666 code
667 code...
667 code...
668
668
669 Time execution of a Python statement or expression using the timeit
669 Time execution of a Python statement or expression using the timeit
670 module. This function can be used both as a line and cell magic:
670 module. This function can be used both as a line and cell magic:
671
671
672 - In line mode you can time a single-line statement (though multiple
672 - In line mode you can time a single-line statement (though multiple
673 ones can be chained with using semicolons).
673 ones can be chained with using semicolons).
674
674
675 - In cell mode, the statement in the first line is used as setup code
675 - In cell mode, the statement in the first line is used as setup code
676 (executed but not timed) and the body of the cell is timed. The cell
676 (executed but not timed) and the body of the cell is timed. The cell
677 body has access to any variables created in the setup code.
677 body has access to any variables created in the setup code.
678
678
679 Options:
679 Options:
680 -n<N>: execute the given statement <N> times in a loop. If this value
680 -n<N>: execute the given statement <N> times in a loop. If this value
681 is not given, a fitting value is chosen.
681 is not given, a fitting value is chosen.
682
682
683 -r<R>: repeat the loop iteration <R> times and take the best result.
683 -r<R>: repeat the loop iteration <R> times and take the best result.
684 Default: 3
684 Default: 3
685
685
686 -t: use time.time to measure the time, which is the default on Unix.
686 -t: use time.time to measure the time, which is the default on Unix.
687 This function measures wall time.
687 This function measures wall time.
688
688
689 -c: use time.clock to measure the time, which is the default on
689 -c: use time.clock to measure the time, which is the default on
690 Windows and measures wall time. On Unix, resource.getrusage is used
690 Windows and measures wall time. On Unix, resource.getrusage is used
691 instead and returns the CPU user time.
691 instead and returns the CPU user time.
692
692
693 -p<P>: use a precision of <P> digits to display the timing result.
693 -p<P>: use a precision of <P> digits to display the timing result.
694 Default: 3
694 Default: 3
695
695
696
696
697 Examples
697 Examples
698 --------
698 --------
699 ::
699 ::
700
700
701 In [1]: %timeit pass
701 In [1]: %timeit pass
702 10000000 loops, best of 3: 53.3 ns per loop
702 10000000 loops, best of 3: 53.3 ns per loop
703
703
704 In [2]: u = None
704 In [2]: u = None
705
705
706 In [3]: %timeit u is None
706 In [3]: %timeit u is None
707 10000000 loops, best of 3: 184 ns per loop
707 10000000 loops, best of 3: 184 ns per loop
708
708
709 In [4]: %timeit -r 4 u == None
709 In [4]: %timeit -r 4 u == None
710 1000000 loops, best of 4: 242 ns per loop
710 1000000 loops, best of 4: 242 ns per loop
711
711
712 In [5]: import time
712 In [5]: import time
713
713
714 In [6]: %timeit -n1 time.sleep(2)
714 In [6]: %timeit -n1 time.sleep(2)
715 1 loops, best of 3: 2 s per loop
715 1 loops, best of 3: 2 s per loop
716
716
717
717
718 The times reported by %timeit will be slightly higher than those
718 The times reported by %timeit will be slightly higher than those
719 reported by the timeit.py script when variables are accessed. This is
719 reported by the timeit.py script when variables are accessed. This is
720 due to the fact that %timeit executes the statement in the namespace
720 due to the fact that %timeit executes the statement in the namespace
721 of the shell, compared with timeit.py, which uses a single setup
721 of the shell, compared with timeit.py, which uses a single setup
722 statement to import function or create variables. Generally, the bias
722 statement to import function or create variables. Generally, the bias
723 does not matter as long as results from timeit.py are not mixed with
723 does not matter as long as results from timeit.py are not mixed with
724 those from %timeit."""
724 those from %timeit."""
725
725
726 import timeit
726 import timeit
727 import math
727 import math
728
728
729 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
729 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
730 # certain terminals. Until we figure out a robust way of
730 # certain terminals. Until we figure out a robust way of
731 # auto-detecting if the terminal can deal with it, use plain 'us' for
731 # auto-detecting if the terminal can deal with it, use plain 'us' for
732 # microseconds. I am really NOT happy about disabling the proper
732 # microseconds. I am really NOT happy about disabling the proper
733 # 'micro' prefix, but crashing is worse... If anyone knows what the
733 # 'micro' prefix, but crashing is worse... If anyone knows what the
734 # right solution for this is, I'm all ears...
734 # right solution for this is, I'm all ears...
735 #
735 #
736 # Note: using
736 # Note: using
737 #
737 #
738 # s = u'\xb5'
738 # s = u'\xb5'
739 # s.encode(sys.getdefaultencoding())
739 # s.encode(sys.getdefaultencoding())
740 #
740 #
741 # is not sufficient, as I've seen terminals where that fails but
741 # is not sufficient, as I've seen terminals where that fails but
742 # print s
742 # print s
743 #
743 #
744 # succeeds
744 # succeeds
745 #
745 #
746 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
746 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
747
747
748 #units = [u"s", u"ms",u'\xb5',"ns"]
748 #units = [u"s", u"ms",u'\xb5',"ns"]
749 units = [u"s", u"ms",u'us',"ns"]
749 units = [u"s", u"ms",u'us',"ns"]
750
750
751 scaling = [1, 1e3, 1e6, 1e9]
751 scaling = [1, 1e3, 1e6, 1e9]
752
752
753 opts, stmt = self.parse_options(line,'n:r:tcp:',
753 opts, stmt = self.parse_options(line,'n:r:tcp:',
754 posix=False, strict=False)
754 posix=False, strict=False)
755 if stmt == "" and cell is None:
755 if stmt == "" and cell is None:
756 return
756 return
757 timefunc = timeit.default_timer
757 timefunc = timeit.default_timer
758 number = int(getattr(opts, "n", 0))
758 number = int(getattr(opts, "n", 0))
759 repeat = int(getattr(opts, "r", timeit.default_repeat))
759 repeat = int(getattr(opts, "r", timeit.default_repeat))
760 precision = int(getattr(opts, "p", 3))
760 precision = int(getattr(opts, "p", 3))
761 if hasattr(opts, "t"):
761 if hasattr(opts, "t"):
762 timefunc = time.time
762 timefunc = time.time
763 if hasattr(opts, "c"):
763 if hasattr(opts, "c"):
764 timefunc = clock
764 timefunc = clock
765
765
766 timer = timeit.Timer(timer=timefunc)
766 timer = timeit.Timer(timer=timefunc)
767 # this code has tight coupling to the inner workings of timeit.Timer,
767 # this code has tight coupling to the inner workings of timeit.Timer,
768 # but is there a better way to achieve that the code stmt has access
768 # but is there a better way to achieve that the code stmt has access
769 # to the shell namespace?
769 # to the shell namespace?
770
770
771 if cell is None:
771 if cell is None:
772 # called as line magic
772 # called as line magic
773 setup = 'pass'
773 setup = 'pass'
774 stmt = timeit.reindent(stmt, 8)
774 stmt = timeit.reindent(stmt, 8)
775 else:
775 else:
776 setup = timeit.reindent(stmt, 4)
776 setup = timeit.reindent(stmt, 4)
777 stmt = timeit.reindent(cell, 8)
777 stmt = timeit.reindent(cell, 8)
778
778
779 # From Python 3.3, this template uses new-style string formatting.
779 # From Python 3.3, this template uses new-style string formatting.
780 if sys.version_info >= (3, 3):
780 if sys.version_info >= (3, 3):
781 src = timeit.template.format(stmt=stmt, setup=setup)
781 src = timeit.template.format(stmt=stmt, setup=setup)
782 else:
782 else:
783 src = timeit.template % dict(stmt=stmt, setup=setup)
783 src = timeit.template % dict(stmt=stmt, setup=setup)
784
784
785 # Track compilation time so it can be reported if too long
785 # Track compilation time so it can be reported if too long
786 # Minimum time above which compilation time will be reported
786 # Minimum time above which compilation time will be reported
787 tc_min = 0.1
787 tc_min = 0.1
788
788
789 t0 = clock()
789 t0 = clock()
790 code = compile(src, "<magic-timeit>", "exec")
790 code = compile(src, "<magic-timeit>", "exec")
791 tc = clock()-t0
791 tc = clock()-t0
792
792
793 ns = {}
793 ns = {}
794 exec code in self.shell.user_ns, ns
794 exec code in self.shell.user_ns, ns
795 timer.inner = ns["inner"]
795 timer.inner = ns["inner"]
796
796
797 if number == 0:
797 if number == 0:
798 # determine number so that 0.2 <= total time < 2.0
798 # determine number so that 0.2 <= total time < 2.0
799 number = 1
799 number = 1
800 for i in range(1, 10):
800 for i in range(1, 10):
801 if timer.timeit(number) >= 0.2:
801 if timer.timeit(number) >= 0.2:
802 break
802 break
803 number *= 10
803 number *= 10
804
804
805 best = min(timer.repeat(repeat, number)) / number
805 best = min(timer.repeat(repeat, number)) / number
806
806
807 if best > 0.0 and best < 1000.0:
807 if best > 0.0 and best < 1000.0:
808 order = min(-int(math.floor(math.log10(best)) // 3), 3)
808 order = min(-int(math.floor(math.log10(best)) // 3), 3)
809 elif best >= 1000.0:
809 elif best >= 1000.0:
810 order = 0
810 order = 0
811 else:
811 else:
812 order = 3
812 order = 3
813 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
813 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
814 precision,
814 precision,
815 best * scaling[order],
815 best * scaling[order],
816 units[order])
816 units[order])
817 if tc > tc_min:
817 if tc > tc_min:
818 print "Compiler time: %.2f s" % tc
818 print "Compiler time: %.2f s" % tc
819
819
820 @skip_doctest
820 @skip_doctest
821 @needs_local_scope
821 @needs_local_scope
822 @line_magic
822 @line_magic
823 def time(self,parameter_s, user_locals):
823 def time(self,parameter_s, user_locals):
824 """Time execution of a Python statement or expression.
824 """Time execution of a Python statement or expression.
825
825
826 The CPU and wall clock times are printed, and the value of the
826 The CPU and wall clock times are printed, and the value of the
827 expression (if any) is returned. Note that under Win32, system time
827 expression (if any) is returned. Note that under Win32, system time
828 is always reported as 0, since it can not be measured.
828 is always reported as 0, since it can not be measured.
829
829
830 This function provides very basic timing functionality. In Python
830 This function provides very basic timing functionality. In Python
831 2.3, the timeit module offers more control and sophistication, so this
831 2.3, the timeit module offers more control and sophistication, so this
832 could be rewritten to use it (patches welcome).
832 could be rewritten to use it (patches welcome).
833
833
834 Examples
834 Examples
835 --------
835 --------
836 ::
836 ::
837
837
838 In [1]: time 2**128
838 In [1]: time 2**128
839 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
839 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
840 Wall time: 0.00
840 Wall time: 0.00
841 Out[1]: 340282366920938463463374607431768211456L
841 Out[1]: 340282366920938463463374607431768211456L
842
842
843 In [2]: n = 1000000
843 In [2]: n = 1000000
844
844
845 In [3]: time sum(range(n))
845 In [3]: time sum(range(n))
846 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
846 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
847 Wall time: 1.37
847 Wall time: 1.37
848 Out[3]: 499999500000L
848 Out[3]: 499999500000L
849
849
850 In [4]: time print 'hello world'
850 In [4]: time print 'hello world'
851 hello world
851 hello world
852 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
852 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
853 Wall time: 0.00
853 Wall time: 0.00
854
854
855 Note that the time needed by Python to compile the given expression
855 Note that the time needed by Python to compile the given expression
856 will be reported if it is more than 0.1s. In this example, the
856 will be reported if it is more than 0.1s. In this example, the
857 actual exponentiation is done by Python at compilation time, so while
857 actual exponentiation is done by Python at compilation time, so while
858 the expression can take a noticeable amount of time to compute, that
858 the expression can take a noticeable amount of time to compute, that
859 time is purely due to the compilation:
859 time is purely due to the compilation:
860
860
861 In [5]: time 3**9999;
861 In [5]: time 3**9999;
862 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
862 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
863 Wall time: 0.00 s
863 Wall time: 0.00 s
864
864
865 In [6]: time 3**999999;
865 In [6]: time 3**999999;
866 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
866 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
867 Wall time: 0.00 s
867 Wall time: 0.00 s
868 Compiler : 0.78 s
868 Compiler : 0.78 s
869 """
869 """
870
870
871 # fail immediately if the given expression can't be compiled
871 # fail immediately if the given expression can't be compiled
872
872
873 expr = self.shell.prefilter(parameter_s,False)
873 expr = self.shell.prefilter(parameter_s,False)
874
874
875 # Minimum time above which compilation time will be reported
875 # Minimum time above which compilation time will be reported
876 tc_min = 0.1
876 tc_min = 0.1
877
877
878 try:
878 try:
879 mode = 'eval'
879 mode = 'eval'
880 t0 = clock()
880 t0 = clock()
881 code = compile(expr,'<timed eval>',mode)
881 code = compile(expr,'<timed eval>',mode)
882 tc = clock()-t0
882 tc = clock()-t0
883 except SyntaxError:
883 except SyntaxError:
884 mode = 'exec'
884 mode = 'exec'
885 t0 = clock()
885 t0 = clock()
886 code = compile(expr,'<timed exec>',mode)
886 code = compile(expr,'<timed exec>',mode)
887 tc = clock()-t0
887 tc = clock()-t0
888 # skew measurement as little as possible
888 # skew measurement as little as possible
889 glob = self.shell.user_ns
889 glob = self.shell.user_ns
890 wtime = time.time
890 wtime = time.time
891 # time execution
891 # time execution
892 wall_st = wtime()
892 wall_st = wtime()
893 if mode=='eval':
893 if mode=='eval':
894 st = clock2()
894 st = clock2()
895 out = eval(code, glob, user_locals)
895 out = eval(code, glob, user_locals)
896 end = clock2()
896 end = clock2()
897 else:
897 else:
898 st = clock2()
898 st = clock2()
899 exec code in glob, user_locals
899 exec code in glob, user_locals
900 end = clock2()
900 end = clock2()
901 out = None
901 out = None
902 wall_end = wtime()
902 wall_end = wtime()
903 # Compute actual times and report
903 # Compute actual times and report
904 wall_time = wall_end-wall_st
904 wall_time = wall_end-wall_st
905 cpu_user = end[0]-st[0]
905 cpu_user = end[0]-st[0]
906 cpu_sys = end[1]-st[1]
906 cpu_sys = end[1]-st[1]
907 cpu_tot = cpu_user+cpu_sys
907 cpu_tot = cpu_user+cpu_sys
908 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
908 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
909 (cpu_user,cpu_sys,cpu_tot)
909 (cpu_user,cpu_sys,cpu_tot)
910 print "Wall time: %.2f s" % wall_time
910 print "Wall time: %.2f s" % wall_time
911 if tc > tc_min:
911 if tc > tc_min:
912 print "Compiler : %.2f s" % tc
912 print "Compiler : %.2f s" % tc
913 return out
913 return out
914
914
915 @skip_doctest
915 @skip_doctest
916 @line_magic
916 @line_magic
917 def macro(self, parameter_s=''):
917 def macro(self, parameter_s=''):
918 """Define a macro for future re-execution. It accepts ranges of history,
918 """Define a macro for future re-execution. It accepts ranges of history,
919 filenames or string objects.
919 filenames or string objects.
920
920
921 Usage:\\
921 Usage:\\
922 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
922 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
923
923
924 Options:
924 Options:
925
925
926 -r: use 'raw' input. By default, the 'processed' history is used,
926 -r: use 'raw' input. By default, the 'processed' history is used,
927 so that magics are loaded in their transformed version to valid
927 so that magics are loaded in their transformed version to valid
928 Python. If this option is given, the raw input as typed as the
928 Python. If this option is given, the raw input as typed as the
929 command line is used instead.
929 command line is used instead.
930
930
931 This will define a global variable called `name` which is a string
931 This will define a global variable called `name` which is a string
932 made of joining the slices and lines you specify (n1,n2,... numbers
932 made of joining the slices and lines you specify (n1,n2,... numbers
933 above) from your input history into a single string. This variable
933 above) from your input history into a single string. This variable
934 acts like an automatic function which re-executes those lines as if
934 acts like an automatic function which re-executes those lines as if
935 you had typed them. You just type 'name' at the prompt and the code
935 you had typed them. You just type 'name' at the prompt and the code
936 executes.
936 executes.
937
937
938 The syntax for indicating input ranges is described in %history.
938 The syntax for indicating input ranges is described in %history.
939
939
940 Note: as a 'hidden' feature, you can also use traditional python slice
940 Note: as a 'hidden' feature, you can also use traditional python slice
941 notation, where N:M means numbers N through M-1.
941 notation, where N:M means numbers N through M-1.
942
942
943 For example, if your history contains (%hist prints it)::
943 For example, if your history contains (%hist prints it)::
944
944
945 44: x=1
945 44: x=1
946 45: y=3
946 45: y=3
947 46: z=x+y
947 46: z=x+y
948 47: print x
948 47: print x
949 48: a=5
949 48: a=5
950 49: print 'x',x,'y',y
950 49: print 'x',x,'y',y
951
951
952 you can create a macro with lines 44 through 47 (included) and line 49
952 you can create a macro with lines 44 through 47 (included) and line 49
953 called my_macro with::
953 called my_macro with::
954
954
955 In [55]: %macro my_macro 44-47 49
955 In [55]: %macro my_macro 44-47 49
956
956
957 Now, typing `my_macro` (without quotes) will re-execute all this code
957 Now, typing `my_macro` (without quotes) will re-execute all this code
958 in one pass.
958 in one pass.
959
959
960 You don't need to give the line-numbers in order, and any given line
960 You don't need to give the line-numbers in order, and any given line
961 number can appear multiple times. You can assemble macros with any
961 number can appear multiple times. You can assemble macros with any
962 lines from your input history in any order.
962 lines from your input history in any order.
963
963
964 The macro is a simple object which holds its value in an attribute,
964 The macro is a simple object which holds its value in an attribute,
965 but IPython's display system checks for macros and executes them as
965 but IPython's display system checks for macros and executes them as
966 code instead of printing them when you type their name.
966 code instead of printing them when you type their name.
967
967
968 You can view a macro's contents by explicitly printing it with::
968 You can view a macro's contents by explicitly printing it with::
969
969
970 print macro_name
970 print macro_name
971
971
972 """
972 """
973 opts,args = self.parse_options(parameter_s,'r',mode='list')
973 opts,args = self.parse_options(parameter_s,'r',mode='list')
974 if not args: # List existing macros
974 if not args: # List existing macros
975 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
975 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
976 isinstance(v, Macro))
976 isinstance(v, Macro))
977 if len(args) == 1:
977 if len(args) == 1:
978 raise UsageError(
978 raise UsageError(
979 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
979 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
980 name, codefrom = args[0], " ".join(args[1:])
980 name, codefrom = args[0], " ".join(args[1:])
981
981
982 #print 'rng',ranges # dbg
982 #print 'rng',ranges # dbg
983 try:
983 try:
984 lines = self.shell.find_user_code(codefrom, 'r' in opts)
984 lines = self.shell.find_user_code(codefrom, 'r' in opts)
985 except (ValueError, TypeError) as e:
985 except (ValueError, TypeError) as e:
986 print e.args[0]
986 print e.args[0]
987 return
987 return
988 macro = Macro(lines)
988 macro = Macro(lines)
989 self.shell.define_macro(name, macro)
989 self.shell.define_macro(name, macro)
990 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
990 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
991 print '=== Macro contents: ==='
991 print '=== Macro contents: ==='
992 print macro,
992 print macro,
993
993
994 @magic_arguments.magic_arguments()
994 @magic_arguments.magic_arguments()
995 @magic_arguments.argument('-o', '--out', type=str,
995 @magic_arguments.argument('output', type=str, default='', nargs='?',
996 help="""The name of the variable in which to store stdout
996 help="""The name of the variable in which to store output.
997 This is a utils.io.CapturedIO object with stdout/err attributes
998 for the text of the captured output.
997
999
998 If unspecified: stdout is discarded
1000 CapturedOutput also has a show() method for displaying the output,
999 """
1001 and __call__ as well, so you can use that to quickly display the
1000 )
1002 output.
1001 @magic_arguments.argument('-e', '--err', type=str,
1002 help="""The name of the variable in which to store stderr
1003
1003
1004 If unspecified: stderr is discarded
1004 If unspecified, captured output is discarded.
1005 """
1005 """
1006 )
1006 )
1007 @magic_arguments.argument('--no-stderr', action="store_true",
1008 help="""Don't capture stderr."""
1009 )
1010 @magic_arguments.argument('--no-stdout', action="store_true",
1011 help="""Don't capture stdout."""
1012 )
1007 @cell_magic
1013 @cell_magic
1008 def capture(self, line, cell):
1014 def capture(self, line, cell):
1009 """run the cell, capturing stdout/err"""
1015 """run the cell, capturing stdout/err"""
1010 args = magic_arguments.parse_argstring(self.capture, line)
1016 args = magic_arguments.parse_argstring(self.capture, line)
1011 with capture_output() as io:
1017 out = not args.no_stdout
1018 err = not args.no_stderr
1019 with capture_output(out, err) as io:
1012 self.shell.run_cell(cell)
1020 self.shell.run_cell(cell)
1013 if args.out:
1021 if args.output:
1014 self.shell.user_ns[args.out] = io.stdout
1022 self.shell.user_ns[args.output] = io
1015 if args.err:
1016 self.shell.user_ns[args.err] = io.stderr
@@ -1,357 +1,381 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """
2 """
3 IO related utilities.
3 IO related utilities.
4 """
4 """
5
5
6 #-----------------------------------------------------------------------------
6 #-----------------------------------------------------------------------------
7 # Copyright (C) 2008-2011 The IPython Development Team
7 # Copyright (C) 2008-2011 The IPython Development Team
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 from __future__ import print_function
12 from __future__ import print_function
13
13
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15 # Imports
15 # Imports
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17 import os
17 import os
18 import sys
18 import sys
19 import tempfile
19 import tempfile
20 from StringIO import StringIO
20 from StringIO import StringIO
21
21
22 #-----------------------------------------------------------------------------
22 #-----------------------------------------------------------------------------
23 # Code
23 # Code
24 #-----------------------------------------------------------------------------
24 #-----------------------------------------------------------------------------
25
25
26
26
27 class IOStream:
27 class IOStream:
28
28
29 def __init__(self,stream, fallback=None):
29 def __init__(self,stream, fallback=None):
30 if not hasattr(stream,'write') or not hasattr(stream,'flush'):
30 if not hasattr(stream,'write') or not hasattr(stream,'flush'):
31 if fallback is not None:
31 if fallback is not None:
32 stream = fallback
32 stream = fallback
33 else:
33 else:
34 raise ValueError("fallback required, but not specified")
34 raise ValueError("fallback required, but not specified")
35 self.stream = stream
35 self.stream = stream
36 self._swrite = stream.write
36 self._swrite = stream.write
37
37
38 # clone all methods not overridden:
38 # clone all methods not overridden:
39 def clone(meth):
39 def clone(meth):
40 return not hasattr(self, meth) and not meth.startswith('_')
40 return not hasattr(self, meth) and not meth.startswith('_')
41 for meth in filter(clone, dir(stream)):
41 for meth in filter(clone, dir(stream)):
42 setattr(self, meth, getattr(stream, meth))
42 setattr(self, meth, getattr(stream, meth))
43
43
44 def write(self,data):
44 def write(self,data):
45 try:
45 try:
46 self._swrite(data)
46 self._swrite(data)
47 except:
47 except:
48 try:
48 try:
49 # print handles some unicode issues which may trip a plain
49 # print handles some unicode issues which may trip a plain
50 # write() call. Emulate write() by using an empty end
50 # write() call. Emulate write() by using an empty end
51 # argument.
51 # argument.
52 print(data, end='', file=self.stream)
52 print(data, end='', file=self.stream)
53 except:
53 except:
54 # if we get here, something is seriously broken.
54 # if we get here, something is seriously broken.
55 print('ERROR - failed to write data to stream:', self.stream,
55 print('ERROR - failed to write data to stream:', self.stream,
56 file=sys.stderr)
56 file=sys.stderr)
57
57
58 def writelines(self, lines):
58 def writelines(self, lines):
59 if isinstance(lines, basestring):
59 if isinstance(lines, basestring):
60 lines = [lines]
60 lines = [lines]
61 for line in lines:
61 for line in lines:
62 self.write(line)
62 self.write(line)
63
63
64 # This class used to have a writeln method, but regular files and streams
64 # This class used to have a writeln method, but regular files and streams
65 # in Python don't have this method. We need to keep this completely
65 # in Python don't have this method. We need to keep this completely
66 # compatible so we removed it.
66 # compatible so we removed it.
67
67
68 @property
68 @property
69 def closed(self):
69 def closed(self):
70 return self.stream.closed
70 return self.stream.closed
71
71
72 def close(self):
72 def close(self):
73 pass
73 pass
74
74
75 # setup stdin/stdout/stderr to sys.stdin/sys.stdout/sys.stderr
75 # setup stdin/stdout/stderr to sys.stdin/sys.stdout/sys.stderr
76 devnull = open(os.devnull, 'a')
76 devnull = open(os.devnull, 'a')
77 stdin = IOStream(sys.stdin, fallback=devnull)
77 stdin = IOStream(sys.stdin, fallback=devnull)
78 stdout = IOStream(sys.stdout, fallback=devnull)
78 stdout = IOStream(sys.stdout, fallback=devnull)
79 stderr = IOStream(sys.stderr, fallback=devnull)
79 stderr = IOStream(sys.stderr, fallback=devnull)
80
80
81 class IOTerm:
81 class IOTerm:
82 """ Term holds the file or file-like objects for handling I/O operations.
82 """ Term holds the file or file-like objects for handling I/O operations.
83
83
84 These are normally just sys.stdin, sys.stdout and sys.stderr but for
84 These are normally just sys.stdin, sys.stdout and sys.stderr but for
85 Windows they can can replaced to allow editing the strings before they are
85 Windows they can can replaced to allow editing the strings before they are
86 displayed."""
86 displayed."""
87
87
88 # In the future, having IPython channel all its I/O operations through
88 # In the future, having IPython channel all its I/O operations through
89 # this class will make it easier to embed it into other environments which
89 # this class will make it easier to embed it into other environments which
90 # are not a normal terminal (such as a GUI-based shell)
90 # are not a normal terminal (such as a GUI-based shell)
91 def __init__(self, stdin=None, stdout=None, stderr=None):
91 def __init__(self, stdin=None, stdout=None, stderr=None):
92 mymodule = sys.modules[__name__]
92 mymodule = sys.modules[__name__]
93 self.stdin = IOStream(stdin, mymodule.stdin)
93 self.stdin = IOStream(stdin, mymodule.stdin)
94 self.stdout = IOStream(stdout, mymodule.stdout)
94 self.stdout = IOStream(stdout, mymodule.stdout)
95 self.stderr = IOStream(stderr, mymodule.stderr)
95 self.stderr = IOStream(stderr, mymodule.stderr)
96
96
97
97
98 class Tee(object):
98 class Tee(object):
99 """A class to duplicate an output stream to stdout/err.
99 """A class to duplicate an output stream to stdout/err.
100
100
101 This works in a manner very similar to the Unix 'tee' command.
101 This works in a manner very similar to the Unix 'tee' command.
102
102
103 When the object is closed or deleted, it closes the original file given to
103 When the object is closed or deleted, it closes the original file given to
104 it for duplication.
104 it for duplication.
105 """
105 """
106 # Inspired by:
106 # Inspired by:
107 # http://mail.python.org/pipermail/python-list/2007-May/442737.html
107 # http://mail.python.org/pipermail/python-list/2007-May/442737.html
108
108
109 def __init__(self, file_or_name, mode="w", channel='stdout'):
109 def __init__(self, file_or_name, mode="w", channel='stdout'):
110 """Construct a new Tee object.
110 """Construct a new Tee object.
111
111
112 Parameters
112 Parameters
113 ----------
113 ----------
114 file_or_name : filename or open filehandle (writable)
114 file_or_name : filename or open filehandle (writable)
115 File that will be duplicated
115 File that will be duplicated
116
116
117 mode : optional, valid mode for open().
117 mode : optional, valid mode for open().
118 If a filename was give, open with this mode.
118 If a filename was give, open with this mode.
119
119
120 channel : str, one of ['stdout', 'stderr']
120 channel : str, one of ['stdout', 'stderr']
121 """
121 """
122 if channel not in ['stdout', 'stderr']:
122 if channel not in ['stdout', 'stderr']:
123 raise ValueError('Invalid channel spec %s' % channel)
123 raise ValueError('Invalid channel spec %s' % channel)
124
124
125 if hasattr(file_or_name, 'write') and hasattr(file_or_name, 'seek'):
125 if hasattr(file_or_name, 'write') and hasattr(file_or_name, 'seek'):
126 self.file = file_or_name
126 self.file = file_or_name
127 else:
127 else:
128 self.file = open(file_or_name, mode)
128 self.file = open(file_or_name, mode)
129 self.channel = channel
129 self.channel = channel
130 self.ostream = getattr(sys, channel)
130 self.ostream = getattr(sys, channel)
131 setattr(sys, channel, self)
131 setattr(sys, channel, self)
132 self._closed = False
132 self._closed = False
133
133
134 def close(self):
134 def close(self):
135 """Close the file and restore the channel."""
135 """Close the file and restore the channel."""
136 self.flush()
136 self.flush()
137 setattr(sys, self.channel, self.ostream)
137 setattr(sys, self.channel, self.ostream)
138 self.file.close()
138 self.file.close()
139 self._closed = True
139 self._closed = True
140
140
141 def write(self, data):
141 def write(self, data):
142 """Write data to both channels."""
142 """Write data to both channels."""
143 self.file.write(data)
143 self.file.write(data)
144 self.ostream.write(data)
144 self.ostream.write(data)
145 self.ostream.flush()
145 self.ostream.flush()
146
146
147 def flush(self):
147 def flush(self):
148 """Flush both channels."""
148 """Flush both channels."""
149 self.file.flush()
149 self.file.flush()
150 self.ostream.flush()
150 self.ostream.flush()
151
151
152 def __del__(self):
152 def __del__(self):
153 if not self._closed:
153 if not self._closed:
154 self.close()
154 self.close()
155
155
156
156
157 def file_read(filename):
157 def file_read(filename):
158 """Read a file and close it. Returns the file source."""
158 """Read a file and close it. Returns the file source."""
159 fobj = open(filename,'r');
159 fobj = open(filename,'r');
160 source = fobj.read();
160 source = fobj.read();
161 fobj.close()
161 fobj.close()
162 return source
162 return source
163
163
164
164
165 def file_readlines(filename):
165 def file_readlines(filename):
166 """Read a file and close it. Returns the file source using readlines()."""
166 """Read a file and close it. Returns the file source using readlines()."""
167 fobj = open(filename,'r');
167 fobj = open(filename,'r');
168 lines = fobj.readlines();
168 lines = fobj.readlines();
169 fobj.close()
169 fobj.close()
170 return lines
170 return lines
171
171
172
172
173 def raw_input_multi(header='', ps1='==> ', ps2='..> ',terminate_str = '.'):
173 def raw_input_multi(header='', ps1='==> ', ps2='..> ',terminate_str = '.'):
174 """Take multiple lines of input.
174 """Take multiple lines of input.
175
175
176 A list with each line of input as a separate element is returned when a
176 A list with each line of input as a separate element is returned when a
177 termination string is entered (defaults to a single '.'). Input can also
177 termination string is entered (defaults to a single '.'). Input can also
178 terminate via EOF (^D in Unix, ^Z-RET in Windows).
178 terminate via EOF (^D in Unix, ^Z-RET in Windows).
179
179
180 Lines of input which end in \\ are joined into single entries (and a
180 Lines of input which end in \\ are joined into single entries (and a
181 secondary continuation prompt is issued as long as the user terminates
181 secondary continuation prompt is issued as long as the user terminates
182 lines with \\). This allows entering very long strings which are still
182 lines with \\). This allows entering very long strings which are still
183 meant to be treated as single entities.
183 meant to be treated as single entities.
184 """
184 """
185
185
186 try:
186 try:
187 if header:
187 if header:
188 header += '\n'
188 header += '\n'
189 lines = [raw_input(header + ps1)]
189 lines = [raw_input(header + ps1)]
190 except EOFError:
190 except EOFError:
191 return []
191 return []
192 terminate = [terminate_str]
192 terminate = [terminate_str]
193 try:
193 try:
194 while lines[-1:] != terminate:
194 while lines[-1:] != terminate:
195 new_line = raw_input(ps1)
195 new_line = raw_input(ps1)
196 while new_line.endswith('\\'):
196 while new_line.endswith('\\'):
197 new_line = new_line[:-1] + raw_input(ps2)
197 new_line = new_line[:-1] + raw_input(ps2)
198 lines.append(new_line)
198 lines.append(new_line)
199
199
200 return lines[:-1] # don't return the termination command
200 return lines[:-1] # don't return the termination command
201 except EOFError:
201 except EOFError:
202 print()
202 print()
203 return lines
203 return lines
204
204
205
205
206 def raw_input_ext(prompt='', ps2='... '):
206 def raw_input_ext(prompt='', ps2='... '):
207 """Similar to raw_input(), but accepts extended lines if input ends with \\."""
207 """Similar to raw_input(), but accepts extended lines if input ends with \\."""
208
208
209 line = raw_input(prompt)
209 line = raw_input(prompt)
210 while line.endswith('\\'):
210 while line.endswith('\\'):
211 line = line[:-1] + raw_input(ps2)
211 line = line[:-1] + raw_input(ps2)
212 return line
212 return line
213
213
214
214
215 def ask_yes_no(prompt,default=None):
215 def ask_yes_no(prompt,default=None):
216 """Asks a question and returns a boolean (y/n) answer.
216 """Asks a question and returns a boolean (y/n) answer.
217
217
218 If default is given (one of 'y','n'), it is used if the user input is
218 If default is given (one of 'y','n'), it is used if the user input is
219 empty. Otherwise the question is repeated until an answer is given.
219 empty. Otherwise the question is repeated until an answer is given.
220
220
221 An EOF is treated as the default answer. If there is no default, an
221 An EOF is treated as the default answer. If there is no default, an
222 exception is raised to prevent infinite loops.
222 exception is raised to prevent infinite loops.
223
223
224 Valid answers are: y/yes/n/no (match is not case sensitive)."""
224 Valid answers are: y/yes/n/no (match is not case sensitive)."""
225
225
226 answers = {'y':True,'n':False,'yes':True,'no':False}
226 answers = {'y':True,'n':False,'yes':True,'no':False}
227 ans = None
227 ans = None
228 while ans not in answers.keys():
228 while ans not in answers.keys():
229 try:
229 try:
230 ans = raw_input(prompt+' ').lower()
230 ans = raw_input(prompt+' ').lower()
231 if not ans: # response was an empty string
231 if not ans: # response was an empty string
232 ans = default
232 ans = default
233 except KeyboardInterrupt:
233 except KeyboardInterrupt:
234 pass
234 pass
235 except EOFError:
235 except EOFError:
236 if default in answers.keys():
236 if default in answers.keys():
237 ans = default
237 ans = default
238 print()
238 print()
239 else:
239 else:
240 raise
240 raise
241
241
242 return answers[ans]
242 return answers[ans]
243
243
244
244
245 class NLprinter:
245 class NLprinter:
246 """Print an arbitrarily nested list, indicating index numbers.
246 """Print an arbitrarily nested list, indicating index numbers.
247
247
248 An instance of this class called nlprint is available and callable as a
248 An instance of this class called nlprint is available and callable as a
249 function.
249 function.
250
250
251 nlprint(list,indent=' ',sep=': ') -> prints indenting each level by 'indent'
251 nlprint(list,indent=' ',sep=': ') -> prints indenting each level by 'indent'
252 and using 'sep' to separate the index from the value. """
252 and using 'sep' to separate the index from the value. """
253
253
254 def __init__(self):
254 def __init__(self):
255 self.depth = 0
255 self.depth = 0
256
256
257 def __call__(self,lst,pos='',**kw):
257 def __call__(self,lst,pos='',**kw):
258 """Prints the nested list numbering levels."""
258 """Prints the nested list numbering levels."""
259 kw.setdefault('indent',' ')
259 kw.setdefault('indent',' ')
260 kw.setdefault('sep',': ')
260 kw.setdefault('sep',': ')
261 kw.setdefault('start',0)
261 kw.setdefault('start',0)
262 kw.setdefault('stop',len(lst))
262 kw.setdefault('stop',len(lst))
263 # we need to remove start and stop from kw so they don't propagate
263 # we need to remove start and stop from kw so they don't propagate
264 # into a recursive call for a nested list.
264 # into a recursive call for a nested list.
265 start = kw['start']; del kw['start']
265 start = kw['start']; del kw['start']
266 stop = kw['stop']; del kw['stop']
266 stop = kw['stop']; del kw['stop']
267 if self.depth == 0 and 'header' in kw.keys():
267 if self.depth == 0 and 'header' in kw.keys():
268 print(kw['header'])
268 print(kw['header'])
269
269
270 for idx in range(start,stop):
270 for idx in range(start,stop):
271 elem = lst[idx]
271 elem = lst[idx]
272 newpos = pos + str(idx)
272 newpos = pos + str(idx)
273 if type(elem)==type([]):
273 if type(elem)==type([]):
274 self.depth += 1
274 self.depth += 1
275 self.__call__(elem, newpos+",", **kw)
275 self.__call__(elem, newpos+",", **kw)
276 self.depth -= 1
276 self.depth -= 1
277 else:
277 else:
278 print(kw['indent']*self.depth + newpos + kw["sep"] + repr(elem))
278 print(kw['indent']*self.depth + newpos + kw["sep"] + repr(elem))
279
279
280 nlprint = NLprinter()
280 nlprint = NLprinter()
281
281
282
282
283 def temp_pyfile(src, ext='.py'):
283 def temp_pyfile(src, ext='.py'):
284 """Make a temporary python file, return filename and filehandle.
284 """Make a temporary python file, return filename and filehandle.
285
285
286 Parameters
286 Parameters
287 ----------
287 ----------
288 src : string or list of strings (no need for ending newlines if list)
288 src : string or list of strings (no need for ending newlines if list)
289 Source code to be written to the file.
289 Source code to be written to the file.
290
290
291 ext : optional, string
291 ext : optional, string
292 Extension for the generated file.
292 Extension for the generated file.
293
293
294 Returns
294 Returns
295 -------
295 -------
296 (filename, open filehandle)
296 (filename, open filehandle)
297 It is the caller's responsibility to close the open file and unlink it.
297 It is the caller's responsibility to close the open file and unlink it.
298 """
298 """
299 fname = tempfile.mkstemp(ext)[1]
299 fname = tempfile.mkstemp(ext)[1]
300 f = open(fname,'w')
300 f = open(fname,'w')
301 f.write(src)
301 f.write(src)
302 f.flush()
302 f.flush()
303 return fname, f
303 return fname, f
304
304
305
305
306 def raw_print(*args, **kw):
306 def raw_print(*args, **kw):
307 """Raw print to sys.__stdout__, otherwise identical interface to print()."""
307 """Raw print to sys.__stdout__, otherwise identical interface to print()."""
308
308
309 print(*args, sep=kw.get('sep', ' '), end=kw.get('end', '\n'),
309 print(*args, sep=kw.get('sep', ' '), end=kw.get('end', '\n'),
310 file=sys.__stdout__)
310 file=sys.__stdout__)
311 sys.__stdout__.flush()
311 sys.__stdout__.flush()
312
312
313
313
314 def raw_print_err(*args, **kw):
314 def raw_print_err(*args, **kw):
315 """Raw print to sys.__stderr__, otherwise identical interface to print()."""
315 """Raw print to sys.__stderr__, otherwise identical interface to print()."""
316
316
317 print(*args, sep=kw.get('sep', ' '), end=kw.get('end', '\n'),
317 print(*args, sep=kw.get('sep', ' '), end=kw.get('end', '\n'),
318 file=sys.__stderr__)
318 file=sys.__stderr__)
319 sys.__stderr__.flush()
319 sys.__stderr__.flush()
320
320
321
321
322 # Short aliases for quick debugging, do NOT use these in production code.
322 # Short aliases for quick debugging, do NOT use these in production code.
323 rprint = raw_print
323 rprint = raw_print
324 rprinte = raw_print_err
324 rprinte = raw_print_err
325
325
326
326
327 class CapturedIO(object):
327 class CapturedIO(object):
328 """Simple object for containing captured stdout/err StringIO objects"""
328 """Simple object for containing captured stdout/err StringIO objects"""
329
329
330 def __init__(self, stdout, stderr):
330 def __init__(self, stdout, stderr):
331 self.stdout_io = stdout
331 self._stdout = stdout
332 self.stderr_io = stderr
332 self._stderr = stderr
333
333
334 @property
334 @property
335 def stdout(self):
335 def stdout(self):
336 return self.stdout_io.getvalue()
336 if not self._stdout:
337 return ''
338 return self._stdout.getvalue()
337
339
338 @property
340 @property
339 def stderr(self):
341 def stderr(self):
340 return self.stderr_io.getvalue()
342 if not self._stderr:
343 return ''
344 return self._stderr.getvalue()
345
346 def show(self):
347 """write my output to sys.stdout/err as appropriate"""
348 sys.stdout.write(self.stdout)
349 sys.stderr.write(self.stderr)
350 sys.stdout.flush()
351 sys.stderr.flush()
352
353 __call__ = show
341
354
342
355
343 class capture_output(object):
356 class capture_output(object):
344 """context manager for capturing stdout/err"""
357 """context manager for capturing stdout/err"""
358 stdout = True
359 stderr = True
360
361 def __init__(self, stdout=True, stderr=True):
362 self.stdout = stdout
363 self.stderr = stderr
345
364
346 def __enter__(self):
365 def __enter__(self):
347 self.sys_stdout = sys.stdout
366 self.sys_stdout = sys.stdout
348 self.sys_stderr = sys.stderr
367 self.sys_stderr = sys.stderr
368
369 stdout = stderr = False
370 if self.stdout:
349 stdout = sys.stdout = StringIO()
371 stdout = sys.stdout = StringIO()
372 if self.stderr:
350 stderr = sys.stderr = StringIO()
373 stderr = sys.stderr = StringIO()
374
351 return CapturedIO(stdout, stderr)
375 return CapturedIO(stdout, stderr)
352
376
353 def __exit__(self, exc_type, exc_value, traceback):
377 def __exit__(self, exc_type, exc_value, traceback):
354 sys.stdout = self.sys_stdout
378 sys.stdout = self.sys_stdout
355 sys.stderr = self.sys_stderr
379 sys.stderr = self.sys_stderr
356
380
357
381
@@ -1,131 +1,182 b''
1 {
1 {
2 "metadata": {
2 "metadata": {
3 "name": "Capturing Output"
3 "name": "Capturing Output"
4 },
4 },
5 "nbformat": 3,
5 "nbformat": 3,
6 "worksheets": [
6 "worksheets": [
7 {
7 {
8 "cells": [
8 "cells": [
9 {
9 {
10 "cell_type": "heading",
10 "cell_type": "heading",
11 "level": 1,
11 "level": 1,
12 "source": [
12 "source": [
13 "Capturing Output with <tt>%%capture</tt>"
13 "Capturing Output with <tt>%%capture</tt>"
14 ]
14 ]
15 },
15 },
16 {
16 {
17 "cell_type": "markdown",
17 "cell_type": "markdown",
18 "source": [
18 "source": [
19 "One of IPython's new cell magics is `%%capture`, which captures stdout/err for a cell,",
19 "One of IPython's new cell magics is `%%capture`, which captures stdout/err for a cell,",
20 "and discards them or stores them in variables in your namespace."
20 "and discards them or stores them in variables in your namespace."
21 ]
21 ]
22 },
22 },
23 {
23 {
24 "cell_type": "code",
24 "cell_type": "code",
25 "input": [
25 "input": [
26 "import sys"
26 "import sys"
27 ],
27 ],
28 "language": "python",
28 "language": "python",
29 "outputs": []
29 "outputs": []
30 },
30 },
31 {
31 {
32 "cell_type": "markdown",
32 "cell_type": "markdown",
33 "source": [
33 "source": [
34 "By default, it just swallows it up. This is a simple way to suppress unwanted output."
34 "By default, it just swallows it up. This is a simple way to suppress unwanted output."
35 ]
35 ]
36 },
36 },
37 {
37 {
38 "cell_type": "code",
38 "cell_type": "code",
39 "input": [
39 "input": [
40 "%%capture",
40 "%%capture",
41 "print 'hi, stdout'",
41 "print 'hi, stdout'",
42 "print >> sys.stderr, 'hi, stderr'"
42 "print >> sys.stderr, 'hi, stderr'"
43 ],
43 ],
44 "language": "python",
44 "language": "python",
45 "outputs": []
45 "outputs": []
46 },
46 },
47 {
47 {
48 "cell_type": "markdown",
48 "cell_type": "markdown",
49 "source": [
49 "source": [
50 "If you specify `-o` or `-e`, then stdout and/or stderr will be stored in those variables in your namespace."
50 "If you specify a name, then stdout and stderr will be stored in an object in your namespace."
51 ]
51 ]
52 },
52 },
53 {
53 {
54 "cell_type": "code",
54 "cell_type": "code",
55 "input": [
55 "input": [
56 "%%capture -o my_stdout",
56 "%%capture captured",
57 "print 'hi, stdout'",
57 "print 'hi, stdout'",
58 "print >> sys.stderr, 'hi, stderr'"
58 "print >> sys.stderr, 'hi, stderr'"
59 ],
59 ],
60 "language": "python",
60 "language": "python",
61 "outputs": []
61 "outputs": []
62 },
62 },
63 {
63 {
64 "cell_type": "code",
64 "cell_type": "code",
65 "input": [
65 "input": [
66 "my_stdout"
66 "captured"
67 ],
68 "language": "python",
69 "outputs": []
70 },
71 {
72 "cell_type": "markdown",
73 "source": [
74 "Calling the object writes the output to stdout/err as appropriate."
75 ]
76 },
77 {
78 "cell_type": "code",
79 "input": [
80 "captured()"
67 ],
81 ],
68 "language": "python",
82 "language": "python",
69 "outputs": []
83 "outputs": []
70 },
84 },
71 {
85 {
72 "cell_type": "code",
86 "cell_type": "code",
73 "input": [
87 "input": [
74 "%%capture -o my_stdout2 -e my_stderr",
88 "captured.stdout"
75 "print 'hi again, stdout'",
76 "print >> sys.stderr, 'hi there, stderr'"
77 ],
89 ],
78 "language": "python",
90 "language": "python",
79 "outputs": []
91 "outputs": []
80 },
92 },
81 {
93 {
82 "cell_type": "code",
94 "cell_type": "code",
83 "input": [
95 "input": [
84 "sys.stdout.write(my_stdout2)",
96 "captured.stderr"
85 "sys.stderr.write(my_stderr)"
86 ],
97 ],
87 "language": "python",
98 "language": "python",
88 "outputs": []
99 "outputs": []
89 },
100 },
90 {
101 {
91 "cell_type": "markdown",
102 "cell_type": "markdown",
92 "source": [
103 "source": [
93 "`%%capture` only captures stdout/err, not displaypub, so you can still do plots and use the display protocol inside %%capture"
104 "`%%capture` only captures stdout/err, not displaypub, so you can still do plots and use the display protocol inside %%capture"
94 ]
105 ]
95 },
106 },
96 {
107 {
97 "cell_type": "code",
108 "cell_type": "code",
98 "input": [
109 "input": [
99 "%pylab inline"
110 "%pylab inline"
100 ],
111 ],
101 "language": "python",
112 "language": "python",
102 "outputs": []
113 "outputs": []
103 },
114 },
104 {
115 {
105 "cell_type": "code",
116 "cell_type": "code",
106 "input": [
117 "input": [
107 "%%capture -o wontshutup",
118 "%%capture wontshutup",
108 "",
119 "",
109 "print \"setting up X\"",
120 "print \"setting up X\"",
110 "x = np.linspace(0,5,1000)",
121 "x = np.linspace(0,5,1000)",
111 "print \"step 2: constructing y-data\"",
122 "print \"step 2: constructing y-data\"",
112 "y = np.sin(x)",
123 "y = np.sin(x)",
113 "print \"step 3: display info about y\"",
124 "print \"step 3: display info about y\"",
114 "plt.plot(x,y)",
125 "plt.plot(x,y)",
115 "print \"okay, I'm done now\""
126 "print \"okay, I'm done now\""
116 ],
127 ],
117 "language": "python",
128 "language": "python",
118 "outputs": []
129 "outputs": []
119 },
130 },
120 {
131 {
121 "cell_type": "code",
132 "cell_type": "code",
122 "input": [
133 "input": [
123 "print wontshutup"
134 "wontshutup()"
135 ],
136 "language": "python",
137 "outputs": []
138 },
139 {
140 "cell_type": "markdown",
141 "source": [
142 "And you can selectively disable capturing stdout or stderr by passing `--no-stdout/err`."
143 ]
144 },
145 {
146 "cell_type": "code",
147 "input": [
148 "%%capture cap --no-stderr",
149 "print 'hi, stdout'",
150 "print >> sys.stderr, \"hello, stderr\""
151 ],
152 "language": "python",
153 "outputs": []
154 },
155 {
156 "cell_type": "code",
157 "input": [
158 "cap.stdout"
159 ],
160 "language": "python",
161 "outputs": []
162 },
163 {
164 "cell_type": "code",
165 "input": [
166 "cap.stderr"
167 ],
168 "language": "python",
169 "outputs": []
170 },
171 {
172 "cell_type": "code",
173 "input": [
174 ""
124 ],
175 ],
125 "language": "python",
176 "language": "python",
126 "outputs": []
177 "outputs": []
127 }
178 }
128 ]
179 ]
129 }
180 }
130 ]
181 ]
131 } No newline at end of file
182 }
General Comments 0
You need to be logged in to leave comments. Login now