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