##// END OF EJS Templates
Merge pull request #2554 from bfroehle/pdb_break...
Bradley M. Froehle -
r8697:f32a6467 merge
parent child Browse files
Show More
@@ -1,1030 +1,1035 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 stats_stream = stats.stream
230 stats_stream = stats.stream
231 try:
231 try:
232 stats.stream = stdout_trap
232 stats.stream = stdout_trap
233 stats.print_stats(*lims)
233 stats.print_stats(*lims)
234 finally:
234 finally:
235 stats.stream = stats_stream
235 stats.stream = stats_stream
236
236
237 output = stdout_trap.getvalue()
237 output = stdout_trap.getvalue()
238 output = output.rstrip()
238 output = output.rstrip()
239
239
240 if 'q' not in opts:
240 if 'q' not in opts:
241 page.page(output)
241 page.page(output)
242 print sys_exit,
242 print sys_exit,
243
243
244 dump_file = opts.D[0]
244 dump_file = opts.D[0]
245 text_file = opts.T[0]
245 text_file = opts.T[0]
246 if dump_file:
246 if dump_file:
247 dump_file = unquote_filename(dump_file)
247 dump_file = unquote_filename(dump_file)
248 prof.dump_stats(dump_file)
248 prof.dump_stats(dump_file)
249 print '\n*** Profile stats marshalled to file',\
249 print '\n*** Profile stats marshalled to file',\
250 repr(dump_file)+'.',sys_exit
250 repr(dump_file)+'.',sys_exit
251 if text_file:
251 if text_file:
252 text_file = unquote_filename(text_file)
252 text_file = unquote_filename(text_file)
253 pfile = open(text_file,'w')
253 pfile = open(text_file,'w')
254 pfile.write(output)
254 pfile.write(output)
255 pfile.close()
255 pfile.close()
256 print '\n*** Profile printout saved to text file',\
256 print '\n*** Profile printout saved to text file',\
257 repr(text_file)+'.',sys_exit
257 repr(text_file)+'.',sys_exit
258
258
259 if 'r' in opts:
259 if 'r' in opts:
260 return stats
260 return stats
261 else:
261 else:
262 return None
262 return None
263
263
264 @line_magic
264 @line_magic
265 def pdb(self, parameter_s=''):
265 def pdb(self, parameter_s=''):
266 """Control the automatic calling of the pdb interactive debugger.
266 """Control the automatic calling of the pdb interactive debugger.
267
267
268 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
268 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
269 argument it works as a toggle.
269 argument it works as a toggle.
270
270
271 When an exception is triggered, IPython can optionally call the
271 When an exception is triggered, IPython can optionally call the
272 interactive pdb debugger after the traceback printout. %pdb toggles
272 interactive pdb debugger after the traceback printout. %pdb toggles
273 this feature on and off.
273 this feature on and off.
274
274
275 The initial state of this feature is set in your configuration
275 The initial state of this feature is set in your configuration
276 file (the option is ``InteractiveShell.pdb``).
276 file (the option is ``InteractiveShell.pdb``).
277
277
278 If you want to just activate the debugger AFTER an exception has fired,
278 If you want to just activate the debugger AFTER an exception has fired,
279 without having to type '%pdb on' and rerunning your code, you can use
279 without having to type '%pdb on' and rerunning your code, you can use
280 the %debug magic."""
280 the %debug magic."""
281
281
282 par = parameter_s.strip().lower()
282 par = parameter_s.strip().lower()
283
283
284 if par:
284 if par:
285 try:
285 try:
286 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
286 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
287 except KeyError:
287 except KeyError:
288 print ('Incorrect argument. Use on/1, off/0, '
288 print ('Incorrect argument. Use on/1, off/0, '
289 'or nothing for a toggle.')
289 'or nothing for a toggle.')
290 return
290 return
291 else:
291 else:
292 # toggle
292 # toggle
293 new_pdb = not self.shell.call_pdb
293 new_pdb = not self.shell.call_pdb
294
294
295 # set on the shell
295 # set on the shell
296 self.shell.call_pdb = new_pdb
296 self.shell.call_pdb = new_pdb
297 print 'Automatic pdb calling has been turned',on_off(new_pdb)
297 print 'Automatic pdb calling has been turned',on_off(new_pdb)
298
298
299 @line_magic
299 @line_magic
300 def debug(self, parameter_s=''):
300 def debug(self, parameter_s=''):
301 """Activate the interactive debugger in post-mortem mode.
301 """Activate the interactive debugger in post-mortem mode.
302
302
303 If an exception has just occurred, this lets you inspect its stack
303 If an exception has just occurred, this lets you inspect its stack
304 frames interactively. Note that this will always work only on the last
304 frames interactively. Note that this will always work only on the last
305 traceback that occurred, so you must call this quickly after an
305 traceback that occurred, so you must call this quickly after an
306 exception that you wish to inspect has fired, because if another one
306 exception that you wish to inspect has fired, because if another one
307 occurs, it clobbers the previous one.
307 occurs, it clobbers the previous one.
308
308
309 If you want IPython to automatically do this on every exception, see
309 If you want IPython to automatically do this on every exception, see
310 the %pdb magic for more details.
310 the %pdb magic for more details.
311 """
311 """
312 self.shell.debugger(force=True)
312 self.shell.debugger(force=True)
313
313
314 @line_magic
314 @line_magic
315 def tb(self, s):
315 def tb(self, s):
316 """Print the last traceback with the currently active exception mode.
316 """Print the last traceback with the currently active exception mode.
317
317
318 See %xmode for changing exception reporting modes."""
318 See %xmode for changing exception reporting modes."""
319 self.shell.showtraceback()
319 self.shell.showtraceback()
320
320
321 @skip_doctest
321 @skip_doctest
322 @line_magic
322 @line_magic
323 def run(self, parameter_s='', runner=None,
323 def run(self, parameter_s='', runner=None,
324 file_finder=get_py_filename):
324 file_finder=get_py_filename):
325 """Run the named file inside IPython as a program.
325 """Run the named file inside IPython as a program.
326
326
327 Usage:\\
327 Usage:\\
328 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options] -G] file [args]
328 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options] -G] file [args]
329
329
330 Parameters after the filename are passed as command-line arguments to
330 Parameters after the filename are passed as command-line arguments to
331 the program (put in sys.argv). Then, control returns to IPython's
331 the program (put in sys.argv). Then, control returns to IPython's
332 prompt.
332 prompt.
333
333
334 This is similar to running at a system prompt:\\
334 This is similar to running at a system prompt:\\
335 $ python file args\\
335 $ python file args\\
336 but with the advantage of giving you IPython's tracebacks, and of
336 but with the advantage of giving you IPython's tracebacks, and of
337 loading all variables into your interactive namespace for further use
337 loading all variables into your interactive namespace for further use
338 (unless -p is used, see below).
338 (unless -p is used, see below).
339
339
340 The file is executed in a namespace initially consisting only of
340 The file is executed in a namespace initially consisting only of
341 __name__=='__main__' and sys.argv constructed as indicated. It thus
341 __name__=='__main__' and sys.argv constructed as indicated. It thus
342 sees its environment as if it were being run as a stand-alone program
342 sees its environment as if it were being run as a stand-alone program
343 (except for sharing global objects such as previously imported
343 (except for sharing global objects such as previously imported
344 modules). But after execution, the IPython interactive namespace gets
344 modules). But after execution, the IPython interactive namespace gets
345 updated with all variables defined in the program (except for __name__
345 updated with all variables defined in the program (except for __name__
346 and sys.argv). This allows for very convenient loading of code for
346 and sys.argv). This allows for very convenient loading of code for
347 interactive work, while giving each program a 'clean sheet' to run in.
347 interactive work, while giving each program a 'clean sheet' to run in.
348
348
349 Arguments are expanded using shell-like glob match. Patterns
349 Arguments are expanded using shell-like glob match. Patterns
350 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
350 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
351 tilde '~' will be expanded into user's home directory. Unlike
351 tilde '~' will be expanded into user's home directory. Unlike
352 real shells, quotation does not suppress expansions. Use
352 real shells, quotation does not suppress expansions. Use
353 *two* back slashes (e.g., '\\\\*') to suppress expansions.
353 *two* back slashes (e.g., '\\\\*') to suppress expansions.
354 To completely disable these expansions, you can use -G flag.
354 To completely disable these expansions, you can use -G flag.
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 -G: disable shell-like glob expansion of arguments.
450 -G: disable shell-like glob expansion of arguments.
451
451
452 """
452 """
453
453
454 # get arguments and set sys.argv for program to be run.
454 # get arguments and set sys.argv for program to be run.
455 opts, arg_lst = self.parse_options(parameter_s,
455 opts, arg_lst = self.parse_options(parameter_s,
456 'nidtN:b:pD:l:rs:T:em:G',
456 'nidtN:b:pD:l:rs:T:em:G',
457 mode='list', list_all=1)
457 mode='list', list_all=1)
458 if "m" in opts:
458 if "m" in opts:
459 modulename = opts["m"][0]
459 modulename = opts["m"][0]
460 modpath = find_mod(modulename)
460 modpath = find_mod(modulename)
461 if modpath is None:
461 if modpath is None:
462 warn('%r is not a valid modulename on sys.path'%modulename)
462 warn('%r is not a valid modulename on sys.path'%modulename)
463 return
463 return
464 arg_lst = [modpath] + arg_lst
464 arg_lst = [modpath] + arg_lst
465 try:
465 try:
466 filename = file_finder(arg_lst[0])
466 filename = file_finder(arg_lst[0])
467 except IndexError:
467 except IndexError:
468 warn('you must provide at least a filename.')
468 warn('you must provide at least a filename.')
469 print '\n%run:\n', oinspect.getdoc(self.run)
469 print '\n%run:\n', oinspect.getdoc(self.run)
470 return
470 return
471 except IOError as e:
471 except IOError as e:
472 try:
472 try:
473 msg = str(e)
473 msg = str(e)
474 except UnicodeError:
474 except UnicodeError:
475 msg = e.message
475 msg = e.message
476 error(msg)
476 error(msg)
477 return
477 return
478
478
479 if filename.lower().endswith('.ipy'):
479 if filename.lower().endswith('.ipy'):
480 self.shell.safe_execfile_ipy(filename)
480 self.shell.safe_execfile_ipy(filename)
481 return
481 return
482
482
483 # Control the response to exit() calls made by the script being run
483 # Control the response to exit() calls made by the script being run
484 exit_ignore = 'e' in opts
484 exit_ignore = 'e' in opts
485
485
486 # Make sure that the running script gets a proper sys.argv as if it
486 # Make sure that the running script gets a proper sys.argv as if it
487 # were run from a system shell.
487 # were run from a system shell.
488 save_argv = sys.argv # save it for later restoring
488 save_argv = sys.argv # save it for later restoring
489
489
490 if 'G' in opts:
490 if 'G' in opts:
491 args = arg_lst[1:]
491 args = arg_lst[1:]
492 else:
492 else:
493 # tilde and glob expansion
493 # tilde and glob expansion
494 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
494 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
495
495
496 sys.argv = [filename] + args # put in the proper filename
496 sys.argv = [filename] + args # put in the proper filename
497 # protect sys.argv from potential unicode strings on Python 2:
497 # protect sys.argv from potential unicode strings on Python 2:
498 if not py3compat.PY3:
498 if not py3compat.PY3:
499 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
499 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
500
500
501 if 'i' in opts:
501 if 'i' in opts:
502 # Run in user's interactive namespace
502 # Run in user's interactive namespace
503 prog_ns = self.shell.user_ns
503 prog_ns = self.shell.user_ns
504 __name__save = self.shell.user_ns['__name__']
504 __name__save = self.shell.user_ns['__name__']
505 prog_ns['__name__'] = '__main__'
505 prog_ns['__name__'] = '__main__'
506 main_mod = self.shell.new_main_mod(prog_ns)
506 main_mod = self.shell.new_main_mod(prog_ns)
507 else:
507 else:
508 # Run in a fresh, empty namespace
508 # Run in a fresh, empty namespace
509 if 'n' in opts:
509 if 'n' in opts:
510 name = os.path.splitext(os.path.basename(filename))[0]
510 name = os.path.splitext(os.path.basename(filename))[0]
511 else:
511 else:
512 name = '__main__'
512 name = '__main__'
513
513
514 main_mod = self.shell.new_main_mod()
514 main_mod = self.shell.new_main_mod()
515 prog_ns = main_mod.__dict__
515 prog_ns = main_mod.__dict__
516 prog_ns['__name__'] = name
516 prog_ns['__name__'] = name
517
517
518 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
518 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
519 # set the __file__ global in the script's namespace
519 # set the __file__ global in the script's namespace
520 prog_ns['__file__'] = filename
520 prog_ns['__file__'] = filename
521
521
522 # pickle fix. See interactiveshell for an explanation. But we need to
522 # pickle fix. See interactiveshell for an explanation. But we need to
523 # make sure that, if we overwrite __main__, we replace it at the end
523 # make sure that, if we overwrite __main__, we replace it at the end
524 main_mod_name = prog_ns['__name__']
524 main_mod_name = prog_ns['__name__']
525
525
526 if main_mod_name == '__main__':
526 if main_mod_name == '__main__':
527 restore_main = sys.modules['__main__']
527 restore_main = sys.modules['__main__']
528 else:
528 else:
529 restore_main = False
529 restore_main = False
530
530
531 # This needs to be undone at the end to prevent holding references to
531 # This needs to be undone at the end to prevent holding references to
532 # every single object ever created.
532 # every single object ever created.
533 sys.modules[main_mod_name] = main_mod
533 sys.modules[main_mod_name] = main_mod
534
534
535 try:
535 try:
536 stats = None
536 stats = None
537 with self.shell.readline_no_record:
537 with self.shell.readline_no_record:
538 if 'p' in opts:
538 if 'p' in opts:
539 stats = self.prun('', None, False, opts, arg_lst, prog_ns)
539 stats = self.prun('', None, False, opts, arg_lst, prog_ns)
540 else:
540 else:
541 if 'd' in opts:
541 if 'd' in opts:
542 deb = debugger.Pdb(self.shell.colors)
542 deb = debugger.Pdb(self.shell.colors)
543 # reset Breakpoint state, which is moronically kept
543 # reset Breakpoint state, which is moronically kept
544 # in a class
544 # in a class
545 bdb.Breakpoint.next = 1
545 bdb.Breakpoint.next = 1
546 bdb.Breakpoint.bplist = {}
546 bdb.Breakpoint.bplist = {}
547 bdb.Breakpoint.bpbynumber = [None]
547 bdb.Breakpoint.bpbynumber = [None]
548 # Set an initial breakpoint to stop execution
548 # Set an initial breakpoint to stop execution
549 maxtries = 10
549 maxtries = 10
550 bp = int(opts.get('b', [1])[0])
550 bp = int(opts.get('b', [1])[0])
551 checkline = deb.checkline(filename, bp)
551 checkline = deb.checkline(filename, bp)
552 if not checkline:
552 if not checkline:
553 for bp in range(bp + 1, bp + maxtries + 1):
553 for bp in range(bp + 1, bp + maxtries + 1):
554 if deb.checkline(filename, bp):
554 if deb.checkline(filename, bp):
555 break
555 break
556 else:
556 else:
557 msg = ("\nI failed to find a valid line to set "
557 msg = ("\nI failed to find a valid line to set "
558 "a breakpoint\n"
558 "a breakpoint\n"
559 "after trying up to line: %s.\n"
559 "after trying up to line: %s.\n"
560 "Please set a valid breakpoint manually "
560 "Please set a valid breakpoint manually "
561 "with the -b option." % bp)
561 "with the -b option." % bp)
562 error(msg)
562 error(msg)
563 return
563 return
564 # if we find a good linenumber, set the breakpoint
564 # if we find a good linenumber, set the breakpoint
565 deb.do_break('%s:%s' % (filename, bp))
565 deb.do_break('%s:%s' % (filename, bp))
566
567 # Mimic Pdb._runscript(...)
568 deb._wait_for_mainpyfile = True
569 deb.mainpyfile = deb.canonic(filename)
570
566 # Start file run
571 # Start file run
567 print "NOTE: Enter 'c' at the",
572 print "NOTE: Enter 'c' at the",
568 print "%s prompt to start your script." % deb.prompt
573 print "%s prompt to start your script." % deb.prompt
569 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
574 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
570 try:
575 try:
571 #save filename so it can be used by methods on the deb object
576 #save filename so it can be used by methods on the deb object
572 deb._exec_filename = filename
577 deb._exec_filename = filename
573 deb.run('execfile("%s", prog_ns)' % filename, ns)
578 deb.run('execfile("%s", prog_ns)' % filename, ns)
574
579
575 except:
580 except:
576 etype, value, tb = sys.exc_info()
581 etype, value, tb = sys.exc_info()
577 # Skip three frames in the traceback: the %run one,
582 # Skip three frames in the traceback: the %run one,
578 # one inside bdb.py, and the command-line typed by the
583 # one inside bdb.py, and the command-line typed by the
579 # user (run by exec in pdb itself).
584 # user (run by exec in pdb itself).
580 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
585 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
581 else:
586 else:
582 if runner is None:
587 if runner is None:
583 runner = self.default_runner
588 runner = self.default_runner
584 if runner is None:
589 if runner is None:
585 runner = self.shell.safe_execfile
590 runner = self.shell.safe_execfile
586 if 't' in opts:
591 if 't' in opts:
587 # timed execution
592 # timed execution
588 try:
593 try:
589 nruns = int(opts['N'][0])
594 nruns = int(opts['N'][0])
590 if nruns < 1:
595 if nruns < 1:
591 error('Number of runs must be >=1')
596 error('Number of runs must be >=1')
592 return
597 return
593 except (KeyError):
598 except (KeyError):
594 nruns = 1
599 nruns = 1
595 twall0 = time.time()
600 twall0 = time.time()
596 if nruns == 1:
601 if nruns == 1:
597 t0 = clock2()
602 t0 = clock2()
598 runner(filename, prog_ns, prog_ns,
603 runner(filename, prog_ns, prog_ns,
599 exit_ignore=exit_ignore)
604 exit_ignore=exit_ignore)
600 t1 = clock2()
605 t1 = clock2()
601 t_usr = t1[0] - t0[0]
606 t_usr = t1[0] - t0[0]
602 t_sys = t1[1] - t0[1]
607 t_sys = t1[1] - t0[1]
603 print "\nIPython CPU timings (estimated):"
608 print "\nIPython CPU timings (estimated):"
604 print " User : %10.2f s." % t_usr
609 print " User : %10.2f s." % t_usr
605 print " System : %10.2f s." % t_sys
610 print " System : %10.2f s." % t_sys
606 else:
611 else:
607 runs = range(nruns)
612 runs = range(nruns)
608 t0 = clock2()
613 t0 = clock2()
609 for nr in runs:
614 for nr in runs:
610 runner(filename, prog_ns, prog_ns,
615 runner(filename, prog_ns, prog_ns,
611 exit_ignore=exit_ignore)
616 exit_ignore=exit_ignore)
612 t1 = clock2()
617 t1 = clock2()
613 t_usr = t1[0] - t0[0]
618 t_usr = t1[0] - t0[0]
614 t_sys = t1[1] - t0[1]
619 t_sys = t1[1] - t0[1]
615 print "\nIPython CPU timings (estimated):"
620 print "\nIPython CPU timings (estimated):"
616 print "Total runs performed:", nruns
621 print "Total runs performed:", nruns
617 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
622 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
618 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
623 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
619 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
624 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
620 twall1 = time.time()
625 twall1 = time.time()
621 print "Wall time: %10.2f s." % (twall1 - twall0)
626 print "Wall time: %10.2f s." % (twall1 - twall0)
622
627
623 else:
628 else:
624 # regular execution
629 # regular execution
625 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
630 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
626
631
627 if 'i' in opts:
632 if 'i' in opts:
628 self.shell.user_ns['__name__'] = __name__save
633 self.shell.user_ns['__name__'] = __name__save
629 else:
634 else:
630 # The shell MUST hold a reference to prog_ns so after %run
635 # The shell MUST hold a reference to prog_ns so after %run
631 # exits, the python deletion mechanism doesn't zero it out
636 # exits, the python deletion mechanism doesn't zero it out
632 # (leaving dangling references).
637 # (leaving dangling references).
633 self.shell.cache_main_mod(prog_ns, filename)
638 self.shell.cache_main_mod(prog_ns, filename)
634 # update IPython interactive namespace
639 # update IPython interactive namespace
635
640
636 # Some forms of read errors on the file may mean the
641 # Some forms of read errors on the file may mean the
637 # __name__ key was never set; using pop we don't have to
642 # __name__ key was never set; using pop we don't have to
638 # worry about a possible KeyError.
643 # worry about a possible KeyError.
639 prog_ns.pop('__name__', None)
644 prog_ns.pop('__name__', None)
640
645
641 self.shell.user_ns.update(prog_ns)
646 self.shell.user_ns.update(prog_ns)
642 finally:
647 finally:
643 # It's a bit of a mystery why, but __builtins__ can change from
648 # It's a bit of a mystery why, but __builtins__ can change from
644 # being a module to becoming a dict missing some key data after
649 # being a module to becoming a dict missing some key data after
645 # %run. As best I can see, this is NOT something IPython is doing
650 # %run. As best I can see, this is NOT something IPython is doing
646 # at all, and similar problems have been reported before:
651 # at all, and similar problems have been reported before:
647 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
652 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
648 # Since this seems to be done by the interpreter itself, the best
653 # Since this seems to be done by the interpreter itself, the best
649 # we can do is to at least restore __builtins__ for the user on
654 # we can do is to at least restore __builtins__ for the user on
650 # exit.
655 # exit.
651 self.shell.user_ns['__builtins__'] = builtin_mod
656 self.shell.user_ns['__builtins__'] = builtin_mod
652
657
653 # Ensure key global structures are restored
658 # Ensure key global structures are restored
654 sys.argv = save_argv
659 sys.argv = save_argv
655 if restore_main:
660 if restore_main:
656 sys.modules['__main__'] = restore_main
661 sys.modules['__main__'] = restore_main
657 else:
662 else:
658 # Remove from sys.modules the reference to main_mod we'd
663 # Remove from sys.modules the reference to main_mod we'd
659 # added. Otherwise it will trap references to objects
664 # added. Otherwise it will trap references to objects
660 # contained therein.
665 # contained therein.
661 del sys.modules[main_mod_name]
666 del sys.modules[main_mod_name]
662
667
663 return stats
668 return stats
664
669
665 @skip_doctest
670 @skip_doctest
666 @line_cell_magic
671 @line_cell_magic
667 def timeit(self, line='', cell=None):
672 def timeit(self, line='', cell=None):
668 """Time execution of a Python statement or expression
673 """Time execution of a Python statement or expression
669
674
670 Usage, in line mode:
675 Usage, in line mode:
671 %timeit [-n<N> -r<R> [-t|-c]] statement
676 %timeit [-n<N> -r<R> [-t|-c]] statement
672 or in cell mode:
677 or in cell mode:
673 %%timeit [-n<N> -r<R> [-t|-c]] setup_code
678 %%timeit [-n<N> -r<R> [-t|-c]] setup_code
674 code
679 code
675 code...
680 code...
676
681
677 Time execution of a Python statement or expression using the timeit
682 Time execution of a Python statement or expression using the timeit
678 module. This function can be used both as a line and cell magic:
683 module. This function can be used both as a line and cell magic:
679
684
680 - In line mode you can time a single-line statement (though multiple
685 - In line mode you can time a single-line statement (though multiple
681 ones can be chained with using semicolons).
686 ones can be chained with using semicolons).
682
687
683 - In cell mode, the statement in the first line is used as setup code
688 - In cell mode, the statement in the first line is used as setup code
684 (executed but not timed) and the body of the cell is timed. The cell
689 (executed but not timed) and the body of the cell is timed. The cell
685 body has access to any variables created in the setup code.
690 body has access to any variables created in the setup code.
686
691
687 Options:
692 Options:
688 -n<N>: execute the given statement <N> times in a loop. If this value
693 -n<N>: execute the given statement <N> times in a loop. If this value
689 is not given, a fitting value is chosen.
694 is not given, a fitting value is chosen.
690
695
691 -r<R>: repeat the loop iteration <R> times and take the best result.
696 -r<R>: repeat the loop iteration <R> times and take the best result.
692 Default: 3
697 Default: 3
693
698
694 -t: use time.time to measure the time, which is the default on Unix.
699 -t: use time.time to measure the time, which is the default on Unix.
695 This function measures wall time.
700 This function measures wall time.
696
701
697 -c: use time.clock to measure the time, which is the default on
702 -c: use time.clock to measure the time, which is the default on
698 Windows and measures wall time. On Unix, resource.getrusage is used
703 Windows and measures wall time. On Unix, resource.getrusage is used
699 instead and returns the CPU user time.
704 instead and returns the CPU user time.
700
705
701 -p<P>: use a precision of <P> digits to display the timing result.
706 -p<P>: use a precision of <P> digits to display the timing result.
702 Default: 3
707 Default: 3
703
708
704
709
705 Examples
710 Examples
706 --------
711 --------
707 ::
712 ::
708
713
709 In [1]: %timeit pass
714 In [1]: %timeit pass
710 10000000 loops, best of 3: 53.3 ns per loop
715 10000000 loops, best of 3: 53.3 ns per loop
711
716
712 In [2]: u = None
717 In [2]: u = None
713
718
714 In [3]: %timeit u is None
719 In [3]: %timeit u is None
715 10000000 loops, best of 3: 184 ns per loop
720 10000000 loops, best of 3: 184 ns per loop
716
721
717 In [4]: %timeit -r 4 u == None
722 In [4]: %timeit -r 4 u == None
718 1000000 loops, best of 4: 242 ns per loop
723 1000000 loops, best of 4: 242 ns per loop
719
724
720 In [5]: import time
725 In [5]: import time
721
726
722 In [6]: %timeit -n1 time.sleep(2)
727 In [6]: %timeit -n1 time.sleep(2)
723 1 loops, best of 3: 2 s per loop
728 1 loops, best of 3: 2 s per loop
724
729
725
730
726 The times reported by %timeit will be slightly higher than those
731 The times reported by %timeit will be slightly higher than those
727 reported by the timeit.py script when variables are accessed. This is
732 reported by the timeit.py script when variables are accessed. This is
728 due to the fact that %timeit executes the statement in the namespace
733 due to the fact that %timeit executes the statement in the namespace
729 of the shell, compared with timeit.py, which uses a single setup
734 of the shell, compared with timeit.py, which uses a single setup
730 statement to import function or create variables. Generally, the bias
735 statement to import function or create variables. Generally, the bias
731 does not matter as long as results from timeit.py are not mixed with
736 does not matter as long as results from timeit.py are not mixed with
732 those from %timeit."""
737 those from %timeit."""
733
738
734 import timeit
739 import timeit
735 import math
740 import math
736
741
737 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
742 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
738 # certain terminals. Until we figure out a robust way of
743 # certain terminals. Until we figure out a robust way of
739 # auto-detecting if the terminal can deal with it, use plain 'us' for
744 # auto-detecting if the terminal can deal with it, use plain 'us' for
740 # microseconds. I am really NOT happy about disabling the proper
745 # microseconds. I am really NOT happy about disabling the proper
741 # 'micro' prefix, but crashing is worse... If anyone knows what the
746 # 'micro' prefix, but crashing is worse... If anyone knows what the
742 # right solution for this is, I'm all ears...
747 # right solution for this is, I'm all ears...
743 #
748 #
744 # Note: using
749 # Note: using
745 #
750 #
746 # s = u'\xb5'
751 # s = u'\xb5'
747 # s.encode(sys.getdefaultencoding())
752 # s.encode(sys.getdefaultencoding())
748 #
753 #
749 # is not sufficient, as I've seen terminals where that fails but
754 # is not sufficient, as I've seen terminals where that fails but
750 # print s
755 # print s
751 #
756 #
752 # succeeds
757 # succeeds
753 #
758 #
754 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
759 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
755
760
756 #units = [u"s", u"ms",u'\xb5',"ns"]
761 #units = [u"s", u"ms",u'\xb5',"ns"]
757 units = [u"s", u"ms",u'us',"ns"]
762 units = [u"s", u"ms",u'us',"ns"]
758
763
759 scaling = [1, 1e3, 1e6, 1e9]
764 scaling = [1, 1e3, 1e6, 1e9]
760
765
761 opts, stmt = self.parse_options(line,'n:r:tcp:',
766 opts, stmt = self.parse_options(line,'n:r:tcp:',
762 posix=False, strict=False)
767 posix=False, strict=False)
763 if stmt == "" and cell is None:
768 if stmt == "" and cell is None:
764 return
769 return
765 timefunc = timeit.default_timer
770 timefunc = timeit.default_timer
766 number = int(getattr(opts, "n", 0))
771 number = int(getattr(opts, "n", 0))
767 repeat = int(getattr(opts, "r", timeit.default_repeat))
772 repeat = int(getattr(opts, "r", timeit.default_repeat))
768 precision = int(getattr(opts, "p", 3))
773 precision = int(getattr(opts, "p", 3))
769 if hasattr(opts, "t"):
774 if hasattr(opts, "t"):
770 timefunc = time.time
775 timefunc = time.time
771 if hasattr(opts, "c"):
776 if hasattr(opts, "c"):
772 timefunc = clock
777 timefunc = clock
773
778
774 timer = timeit.Timer(timer=timefunc)
779 timer = timeit.Timer(timer=timefunc)
775 # this code has tight coupling to the inner workings of timeit.Timer,
780 # this code has tight coupling to the inner workings of timeit.Timer,
776 # but is there a better way to achieve that the code stmt has access
781 # but is there a better way to achieve that the code stmt has access
777 # to the shell namespace?
782 # to the shell namespace?
778 transform = self.shell.input_splitter.transform_cell
783 transform = self.shell.input_splitter.transform_cell
779 if cell is None:
784 if cell is None:
780 # called as line magic
785 # called as line magic
781 setup = 'pass'
786 setup = 'pass'
782 stmt = timeit.reindent(transform(stmt), 8)
787 stmt = timeit.reindent(transform(stmt), 8)
783 else:
788 else:
784 setup = timeit.reindent(transform(stmt), 4)
789 setup = timeit.reindent(transform(stmt), 4)
785 stmt = timeit.reindent(transform(cell), 8)
790 stmt = timeit.reindent(transform(cell), 8)
786
791
787 # From Python 3.3, this template uses new-style string formatting.
792 # From Python 3.3, this template uses new-style string formatting.
788 if sys.version_info >= (3, 3):
793 if sys.version_info >= (3, 3):
789 src = timeit.template.format(stmt=stmt, setup=setup)
794 src = timeit.template.format(stmt=stmt, setup=setup)
790 else:
795 else:
791 src = timeit.template % dict(stmt=stmt, setup=setup)
796 src = timeit.template % dict(stmt=stmt, setup=setup)
792
797
793 # Track compilation time so it can be reported if too long
798 # Track compilation time so it can be reported if too long
794 # Minimum time above which compilation time will be reported
799 # Minimum time above which compilation time will be reported
795 tc_min = 0.1
800 tc_min = 0.1
796
801
797 t0 = clock()
802 t0 = clock()
798 code = compile(src, "<magic-timeit>", "exec")
803 code = compile(src, "<magic-timeit>", "exec")
799 tc = clock()-t0
804 tc = clock()-t0
800
805
801 ns = {}
806 ns = {}
802 exec code in self.shell.user_ns, ns
807 exec code in self.shell.user_ns, ns
803 timer.inner = ns["inner"]
808 timer.inner = ns["inner"]
804
809
805 if number == 0:
810 if number == 0:
806 # determine number so that 0.2 <= total time < 2.0
811 # determine number so that 0.2 <= total time < 2.0
807 number = 1
812 number = 1
808 for i in range(1, 10):
813 for i in range(1, 10):
809 if timer.timeit(number) >= 0.2:
814 if timer.timeit(number) >= 0.2:
810 break
815 break
811 number *= 10
816 number *= 10
812
817
813 best = min(timer.repeat(repeat, number)) / number
818 best = min(timer.repeat(repeat, number)) / number
814
819
815 if best > 0.0 and best < 1000.0:
820 if best > 0.0 and best < 1000.0:
816 order = min(-int(math.floor(math.log10(best)) // 3), 3)
821 order = min(-int(math.floor(math.log10(best)) // 3), 3)
817 elif best >= 1000.0:
822 elif best >= 1000.0:
818 order = 0
823 order = 0
819 else:
824 else:
820 order = 3
825 order = 3
821 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
826 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
822 precision,
827 precision,
823 best * scaling[order],
828 best * scaling[order],
824 units[order])
829 units[order])
825 if tc > tc_min:
830 if tc > tc_min:
826 print "Compiler time: %.2f s" % tc
831 print "Compiler time: %.2f s" % tc
827
832
828 @skip_doctest
833 @skip_doctest
829 @needs_local_scope
834 @needs_local_scope
830 @line_magic
835 @line_magic
831 def time(self,parameter_s, local_ns=None):
836 def time(self,parameter_s, local_ns=None):
832 """Time execution of a Python statement or expression.
837 """Time execution of a Python statement or expression.
833
838
834 The CPU and wall clock times are printed, and the value of the
839 The CPU and wall clock times are printed, and the value of the
835 expression (if any) is returned. Note that under Win32, system time
840 expression (if any) is returned. Note that under Win32, system time
836 is always reported as 0, since it can not be measured.
841 is always reported as 0, since it can not be measured.
837
842
838 This function provides very basic timing functionality. In Python
843 This function provides very basic timing functionality. In Python
839 2.3, the timeit module offers more control and sophistication, so this
844 2.3, the timeit module offers more control and sophistication, so this
840 could be rewritten to use it (patches welcome).
845 could be rewritten to use it (patches welcome).
841
846
842 Examples
847 Examples
843 --------
848 --------
844 ::
849 ::
845
850
846 In [1]: time 2**128
851 In [1]: time 2**128
847 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
848 Wall time: 0.00
853 Wall time: 0.00
849 Out[1]: 340282366920938463463374607431768211456L
854 Out[1]: 340282366920938463463374607431768211456L
850
855
851 In [2]: n = 1000000
856 In [2]: n = 1000000
852
857
853 In [3]: time sum(range(n))
858 In [3]: time sum(range(n))
854 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
859 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
855 Wall time: 1.37
860 Wall time: 1.37
856 Out[3]: 499999500000L
861 Out[3]: 499999500000L
857
862
858 In [4]: time print 'hello world'
863 In [4]: time print 'hello world'
859 hello world
864 hello world
860 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
865 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
861 Wall time: 0.00
866 Wall time: 0.00
862
867
863 Note that the time needed by Python to compile the given expression
868 Note that the time needed by Python to compile the given expression
864 will be reported if it is more than 0.1s. In this example, the
869 will be reported if it is more than 0.1s. In this example, the
865 actual exponentiation is done by Python at compilation time, so while
870 actual exponentiation is done by Python at compilation time, so while
866 the expression can take a noticeable amount of time to compute, that
871 the expression can take a noticeable amount of time to compute, that
867 time is purely due to the compilation:
872 time is purely due to the compilation:
868
873
869 In [5]: time 3**9999;
874 In [5]: time 3**9999;
870 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
875 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
871 Wall time: 0.00 s
876 Wall time: 0.00 s
872
877
873 In [6]: time 3**999999;
878 In [6]: time 3**999999;
874 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
879 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
875 Wall time: 0.00 s
880 Wall time: 0.00 s
876 Compiler : 0.78 s
881 Compiler : 0.78 s
877 """
882 """
878
883
879 # fail immediately if the given expression can't be compiled
884 # fail immediately if the given expression can't be compiled
880
885
881 expr = self.shell.prefilter(parameter_s,False)
886 expr = self.shell.prefilter(parameter_s,False)
882
887
883 # Minimum time above which compilation time will be reported
888 # Minimum time above which compilation time will be reported
884 tc_min = 0.1
889 tc_min = 0.1
885
890
886 try:
891 try:
887 mode = 'eval'
892 mode = 'eval'
888 t0 = clock()
893 t0 = clock()
889 code = compile(expr,'<timed eval>',mode)
894 code = compile(expr,'<timed eval>',mode)
890 tc = clock()-t0
895 tc = clock()-t0
891 except SyntaxError:
896 except SyntaxError:
892 mode = 'exec'
897 mode = 'exec'
893 t0 = clock()
898 t0 = clock()
894 code = compile(expr,'<timed exec>',mode)
899 code = compile(expr,'<timed exec>',mode)
895 tc = clock()-t0
900 tc = clock()-t0
896 # skew measurement as little as possible
901 # skew measurement as little as possible
897 glob = self.shell.user_ns
902 glob = self.shell.user_ns
898 wtime = time.time
903 wtime = time.time
899 # time execution
904 # time execution
900 wall_st = wtime()
905 wall_st = wtime()
901 if mode=='eval':
906 if mode=='eval':
902 st = clock2()
907 st = clock2()
903 out = eval(code, glob, local_ns)
908 out = eval(code, glob, local_ns)
904 end = clock2()
909 end = clock2()
905 else:
910 else:
906 st = clock2()
911 st = clock2()
907 exec code in glob, local_ns
912 exec code in glob, local_ns
908 end = clock2()
913 end = clock2()
909 out = None
914 out = None
910 wall_end = wtime()
915 wall_end = wtime()
911 # Compute actual times and report
916 # Compute actual times and report
912 wall_time = wall_end-wall_st
917 wall_time = wall_end-wall_st
913 cpu_user = end[0]-st[0]
918 cpu_user = end[0]-st[0]
914 cpu_sys = end[1]-st[1]
919 cpu_sys = end[1]-st[1]
915 cpu_tot = cpu_user+cpu_sys
920 cpu_tot = cpu_user+cpu_sys
916 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
921 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
917 (cpu_user,cpu_sys,cpu_tot)
922 (cpu_user,cpu_sys,cpu_tot)
918 print "Wall time: %.2f s" % wall_time
923 print "Wall time: %.2f s" % wall_time
919 if tc > tc_min:
924 if tc > tc_min:
920 print "Compiler : %.2f s" % tc
925 print "Compiler : %.2f s" % tc
921 return out
926 return out
922
927
923 @skip_doctest
928 @skip_doctest
924 @line_magic
929 @line_magic
925 def macro(self, parameter_s=''):
930 def macro(self, parameter_s=''):
926 """Define a macro for future re-execution. It accepts ranges of history,
931 """Define a macro for future re-execution. It accepts ranges of history,
927 filenames or string objects.
932 filenames or string objects.
928
933
929 Usage:\\
934 Usage:\\
930 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
935 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
931
936
932 Options:
937 Options:
933
938
934 -r: use 'raw' input. By default, the 'processed' history is used,
939 -r: use 'raw' input. By default, the 'processed' history is used,
935 so that magics are loaded in their transformed version to valid
940 so that magics are loaded in their transformed version to valid
936 Python. If this option is given, the raw input as typed as the
941 Python. If this option is given, the raw input as typed as the
937 command line is used instead.
942 command line is used instead.
938
943
939 This will define a global variable called `name` which is a string
944 This will define a global variable called `name` which is a string
940 made of joining the slices and lines you specify (n1,n2,... numbers
945 made of joining the slices and lines you specify (n1,n2,... numbers
941 above) from your input history into a single string. This variable
946 above) from your input history into a single string. This variable
942 acts like an automatic function which re-executes those lines as if
947 acts like an automatic function which re-executes those lines as if
943 you had typed them. You just type 'name' at the prompt and the code
948 you had typed them. You just type 'name' at the prompt and the code
944 executes.
949 executes.
945
950
946 The syntax for indicating input ranges is described in %history.
951 The syntax for indicating input ranges is described in %history.
947
952
948 Note: as a 'hidden' feature, you can also use traditional python slice
953 Note: as a 'hidden' feature, you can also use traditional python slice
949 notation, where N:M means numbers N through M-1.
954 notation, where N:M means numbers N through M-1.
950
955
951 For example, if your history contains (%hist prints it)::
956 For example, if your history contains (%hist prints it)::
952
957
953 44: x=1
958 44: x=1
954 45: y=3
959 45: y=3
955 46: z=x+y
960 46: z=x+y
956 47: print x
961 47: print x
957 48: a=5
962 48: a=5
958 49: print 'x',x,'y',y
963 49: print 'x',x,'y',y
959
964
960 you can create a macro with lines 44 through 47 (included) and line 49
965 you can create a macro with lines 44 through 47 (included) and line 49
961 called my_macro with::
966 called my_macro with::
962
967
963 In [55]: %macro my_macro 44-47 49
968 In [55]: %macro my_macro 44-47 49
964
969
965 Now, typing `my_macro` (without quotes) will re-execute all this code
970 Now, typing `my_macro` (without quotes) will re-execute all this code
966 in one pass.
971 in one pass.
967
972
968 You don't need to give the line-numbers in order, and any given line
973 You don't need to give the line-numbers in order, and any given line
969 number can appear multiple times. You can assemble macros with any
974 number can appear multiple times. You can assemble macros with any
970 lines from your input history in any order.
975 lines from your input history in any order.
971
976
972 The macro is a simple object which holds its value in an attribute,
977 The macro is a simple object which holds its value in an attribute,
973 but IPython's display system checks for macros and executes them as
978 but IPython's display system checks for macros and executes them as
974 code instead of printing them when you type their name.
979 code instead of printing them when you type their name.
975
980
976 You can view a macro's contents by explicitly printing it with::
981 You can view a macro's contents by explicitly printing it with::
977
982
978 print macro_name
983 print macro_name
979
984
980 """
985 """
981 opts,args = self.parse_options(parameter_s,'r',mode='list')
986 opts,args = self.parse_options(parameter_s,'r',mode='list')
982 if not args: # List existing macros
987 if not args: # List existing macros
983 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
988 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
984 isinstance(v, Macro))
989 isinstance(v, Macro))
985 if len(args) == 1:
990 if len(args) == 1:
986 raise UsageError(
991 raise UsageError(
987 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
992 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
988 name, codefrom = args[0], " ".join(args[1:])
993 name, codefrom = args[0], " ".join(args[1:])
989
994
990 #print 'rng',ranges # dbg
995 #print 'rng',ranges # dbg
991 try:
996 try:
992 lines = self.shell.find_user_code(codefrom, 'r' in opts)
997 lines = self.shell.find_user_code(codefrom, 'r' in opts)
993 except (ValueError, TypeError) as e:
998 except (ValueError, TypeError) as e:
994 print e.args[0]
999 print e.args[0]
995 return
1000 return
996 macro = Macro(lines)
1001 macro = Macro(lines)
997 self.shell.define_macro(name, macro)
1002 self.shell.define_macro(name, macro)
998 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1003 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
999 print '=== Macro contents: ==='
1004 print '=== Macro contents: ==='
1000 print macro,
1005 print macro,
1001
1006
1002 @magic_arguments.magic_arguments()
1007 @magic_arguments.magic_arguments()
1003 @magic_arguments.argument('output', type=str, default='', nargs='?',
1008 @magic_arguments.argument('output', type=str, default='', nargs='?',
1004 help="""The name of the variable in which to store output.
1009 help="""The name of the variable in which to store output.
1005 This is a utils.io.CapturedIO object with stdout/err attributes
1010 This is a utils.io.CapturedIO object with stdout/err attributes
1006 for the text of the captured output.
1011 for the text of the captured output.
1007
1012
1008 CapturedOutput also has a show() method for displaying the output,
1013 CapturedOutput also has a show() method for displaying the output,
1009 and __call__ as well, so you can use that to quickly display the
1014 and __call__ as well, so you can use that to quickly display the
1010 output.
1015 output.
1011
1016
1012 If unspecified, captured output is discarded.
1017 If unspecified, captured output is discarded.
1013 """
1018 """
1014 )
1019 )
1015 @magic_arguments.argument('--no-stderr', action="store_true",
1020 @magic_arguments.argument('--no-stderr', action="store_true",
1016 help="""Don't capture stderr."""
1021 help="""Don't capture stderr."""
1017 )
1022 )
1018 @magic_arguments.argument('--no-stdout', action="store_true",
1023 @magic_arguments.argument('--no-stdout', action="store_true",
1019 help="""Don't capture stdout."""
1024 help="""Don't capture stdout."""
1020 )
1025 )
1021 @cell_magic
1026 @cell_magic
1022 def capture(self, line, cell):
1027 def capture(self, line, cell):
1023 """run the cell, capturing stdout/err"""
1028 """run the cell, capturing stdout/err"""
1024 args = magic_arguments.parse_argstring(self.capture, line)
1029 args = magic_arguments.parse_argstring(self.capture, line)
1025 out = not args.no_stdout
1030 out = not args.no_stdout
1026 err = not args.no_stderr
1031 err = not args.no_stderr
1027 with capture_output(out, err) as io:
1032 with capture_output(out, err) as io:
1028 self.shell.run_cell(cell)
1033 self.shell.run_cell(cell)
1029 if args.output:
1034 if args.output:
1030 self.shell.user_ns[args.output] = io
1035 self.shell.user_ns[args.output] = io
General Comments 0
You need to be logged in to leave comments. Login now