##// END OF EJS Templates
Minor spelling changes to the docstring of TimeitResult
Justin Zymbaluk -
Show More
@@ -1,1364 +1,1364 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Implementation of execution-related magic functions."""
2 """Implementation of execution-related magic functions."""
3
3
4 # Copyright (c) IPython Development Team.
4 # Copyright (c) IPython Development Team.
5 # Distributed under the terms of the Modified BSD License.
5 # Distributed under the terms of the Modified BSD License.
6
6
7 from __future__ import print_function
7 from __future__ import print_function
8 from __future__ import absolute_import
8 from __future__ import absolute_import
9
9
10 import ast
10 import ast
11 import bdb
11 import bdb
12 import gc
12 import gc
13 import itertools
13 import itertools
14 import os
14 import os
15 import sys
15 import sys
16 import time
16 import time
17 import timeit
17 import timeit
18 from pdb import Restart
18 from pdb import Restart
19
19
20 # cProfile was added in Python2.5
20 # cProfile was added in Python2.5
21 try:
21 try:
22 import cProfile as profile
22 import cProfile as profile
23 import pstats
23 import pstats
24 except ImportError:
24 except ImportError:
25 # profile isn't bundled by default in Debian for license reasons
25 # profile isn't bundled by default in Debian for license reasons
26 try:
26 try:
27 import profile, pstats
27 import profile, pstats
28 except ImportError:
28 except ImportError:
29 profile = pstats = None
29 profile = pstats = None
30
30
31 from IPython.core import debugger, oinspect
31 from IPython.core import debugger, oinspect
32 from IPython.core import magic_arguments
32 from IPython.core import magic_arguments
33 from IPython.core import page
33 from IPython.core import page
34 from IPython.core.error import UsageError
34 from IPython.core.error import UsageError
35 from IPython.core.macro import Macro
35 from IPython.core.macro import Macro
36 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
36 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
37 line_cell_magic, on_off, needs_local_scope)
37 line_cell_magic, on_off, needs_local_scope)
38 from IPython.testing.skipdoctest import skip_doctest
38 from IPython.testing.skipdoctest import skip_doctest
39 from IPython.utils import py3compat
39 from IPython.utils import py3compat
40 from IPython.utils.py3compat import builtin_mod, iteritems, PY3
40 from IPython.utils.py3compat import builtin_mod, iteritems, PY3
41 from IPython.utils.contexts import preserve_keys
41 from IPython.utils.contexts import preserve_keys
42 from IPython.utils.capture import capture_output
42 from IPython.utils.capture import capture_output
43 from IPython.utils.ipstruct import Struct
43 from IPython.utils.ipstruct import Struct
44 from IPython.utils.module_paths import find_mod
44 from IPython.utils.module_paths import find_mod
45 from IPython.utils.path import get_py_filename, unquote_filename, shellglob
45 from IPython.utils.path import get_py_filename, unquote_filename, shellglob
46 from IPython.utils.timing import clock, clock2
46 from IPython.utils.timing import clock, clock2
47 from warnings import warn
47 from warnings import warn
48 from logging import error
48 from logging import error
49
49
50 if PY3:
50 if PY3:
51 from io import StringIO
51 from io import StringIO
52 else:
52 else:
53 from StringIO import StringIO
53 from StringIO import StringIO
54
54
55 #-----------------------------------------------------------------------------
55 #-----------------------------------------------------------------------------
56 # Magic implementation classes
56 # Magic implementation classes
57 #-----------------------------------------------------------------------------
57 #-----------------------------------------------------------------------------
58
58
59
59
60 class TimeitResult(object):
60 class TimeitResult(object):
61 """
61 """
62 Object returned by the timeit magic with info about the run.
62 Object returned by the timeit magic with info about the run.
63
63
64 Contain the following attributes :
64 Contains the following attributes :
65
65
66 loops: (int) number of loop done per measurement
66 loops: (int) number of loops done per measurement
67 repeat: (int) number of time the mesurement has been repeated
67 repeat: (int) number of times the measurement has been repeated
68 best: (float) best execusion time / number
68 best: (float) best execution time / number
69 all_runs: (list of float) execusion time of each run (in s)
69 all_runs: (list of float) execution time of each run (in s)
70 compile_time: (float) time of statement compilation (s)
70 compile_time: (float) time of statement compilation (s)
71
71
72 """
72 """
73
73
74 def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
74 def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
75 self.loops = loops
75 self.loops = loops
76 self.repeat = repeat
76 self.repeat = repeat
77 self.best = best
77 self.best = best
78 self.worst = worst
78 self.worst = worst
79 self.all_runs = all_runs
79 self.all_runs = all_runs
80 self.compile_time = compile_time
80 self.compile_time = compile_time
81 self._precision = precision
81 self._precision = precision
82
82
83 def _repr_pretty_(self, p , cycle):
83 def _repr_pretty_(self, p , cycle):
84 if self.loops == 1: # No s at "loops" if only one loop
84 if self.loops == 1: # No s at "loops" if only one loop
85 unic = u"%d loop, best of %d: %s per loop" % (self.loops, self.repeat,
85 unic = u"%d loop, best of %d: %s per loop" % (self.loops, self.repeat,
86 _format_time(self.best, self._precision))
86 _format_time(self.best, self._precision))
87 else:
87 else:
88 unic = u"%d loops, best of %d: %s per loop" % (self.loops, self.repeat,
88 unic = u"%d loops, best of %d: %s per loop" % (self.loops, self.repeat,
89 _format_time(self.best, self._precision))
89 _format_time(self.best, self._precision))
90 p.text(u'<TimeitResult : '+unic+u'>')
90 p.text(u'<TimeitResult : '+unic+u'>')
91
91
92
92
93 class TimeitTemplateFiller(ast.NodeTransformer):
93 class TimeitTemplateFiller(ast.NodeTransformer):
94 """Fill in the AST template for timing execution.
94 """Fill in the AST template for timing execution.
95
95
96 This is quite closely tied to the template definition, which is in
96 This is quite closely tied to the template definition, which is in
97 :meth:`ExecutionMagics.timeit`.
97 :meth:`ExecutionMagics.timeit`.
98 """
98 """
99 def __init__(self, ast_setup, ast_stmt):
99 def __init__(self, ast_setup, ast_stmt):
100 self.ast_setup = ast_setup
100 self.ast_setup = ast_setup
101 self.ast_stmt = ast_stmt
101 self.ast_stmt = ast_stmt
102
102
103 def visit_FunctionDef(self, node):
103 def visit_FunctionDef(self, node):
104 "Fill in the setup statement"
104 "Fill in the setup statement"
105 self.generic_visit(node)
105 self.generic_visit(node)
106 if node.name == "inner":
106 if node.name == "inner":
107 node.body[:1] = self.ast_setup.body
107 node.body[:1] = self.ast_setup.body
108
108
109 return node
109 return node
110
110
111 def visit_For(self, node):
111 def visit_For(self, node):
112 "Fill in the statement to be timed"
112 "Fill in the statement to be timed"
113 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
113 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
114 node.body = self.ast_stmt.body
114 node.body = self.ast_stmt.body
115 return node
115 return node
116
116
117
117
118 class Timer(timeit.Timer):
118 class Timer(timeit.Timer):
119 """Timer class that explicitly uses self.inner
119 """Timer class that explicitly uses self.inner
120
120
121 which is an undocumented implementation detail of CPython,
121 which is an undocumented implementation detail of CPython,
122 not shared by PyPy.
122 not shared by PyPy.
123 """
123 """
124 # Timer.timeit copied from CPython 3.4.2
124 # Timer.timeit copied from CPython 3.4.2
125 def timeit(self, number=timeit.default_number):
125 def timeit(self, number=timeit.default_number):
126 """Time 'number' executions of the main statement.
126 """Time 'number' executions of the main statement.
127
127
128 To be precise, this executes the setup statement once, and
128 To be precise, this executes the setup statement once, and
129 then returns the time it takes to execute the main statement
129 then returns the time it takes to execute the main statement
130 a number of times, as a float measured in seconds. The
130 a number of times, as a float measured in seconds. The
131 argument is the number of times through the loop, defaulting
131 argument is the number of times through the loop, defaulting
132 to one million. The main statement, the setup statement and
132 to one million. The main statement, the setup statement and
133 the timer function to be used are passed to the constructor.
133 the timer function to be used are passed to the constructor.
134 """
134 """
135 it = itertools.repeat(None, number)
135 it = itertools.repeat(None, number)
136 gcold = gc.isenabled()
136 gcold = gc.isenabled()
137 gc.disable()
137 gc.disable()
138 try:
138 try:
139 timing = self.inner(it, self.timer)
139 timing = self.inner(it, self.timer)
140 finally:
140 finally:
141 if gcold:
141 if gcold:
142 gc.enable()
142 gc.enable()
143 return timing
143 return timing
144
144
145
145
146 @magics_class
146 @magics_class
147 class ExecutionMagics(Magics):
147 class ExecutionMagics(Magics):
148 """Magics related to code execution, debugging, profiling, etc.
148 """Magics related to code execution, debugging, profiling, etc.
149
149
150 """
150 """
151
151
152 def __init__(self, shell):
152 def __init__(self, shell):
153 super(ExecutionMagics, self).__init__(shell)
153 super(ExecutionMagics, self).__init__(shell)
154 if profile is None:
154 if profile is None:
155 self.prun = self.profile_missing_notice
155 self.prun = self.profile_missing_notice
156 # Default execution function used to actually run user code.
156 # Default execution function used to actually run user code.
157 self.default_runner = None
157 self.default_runner = None
158
158
159 def profile_missing_notice(self, *args, **kwargs):
159 def profile_missing_notice(self, *args, **kwargs):
160 error("""\
160 error("""\
161 The profile module could not be found. It has been removed from the standard
161 The profile module could not be found. It has been removed from the standard
162 python packages because of its non-free license. To use profiling, install the
162 python packages because of its non-free license. To use profiling, install the
163 python-profiler package from non-free.""")
163 python-profiler package from non-free.""")
164
164
165 @skip_doctest
165 @skip_doctest
166 @line_cell_magic
166 @line_cell_magic
167 def prun(self, parameter_s='', cell=None):
167 def prun(self, parameter_s='', cell=None):
168
168
169 """Run a statement through the python code profiler.
169 """Run a statement through the python code profiler.
170
170
171 Usage, in line mode:
171 Usage, in line mode:
172 %prun [options] statement
172 %prun [options] statement
173
173
174 Usage, in cell mode:
174 Usage, in cell mode:
175 %%prun [options] [statement]
175 %%prun [options] [statement]
176 code...
176 code...
177 code...
177 code...
178
178
179 In cell mode, the additional code lines are appended to the (possibly
179 In cell mode, the additional code lines are appended to the (possibly
180 empty) statement in the first line. Cell mode allows you to easily
180 empty) statement in the first line. Cell mode allows you to easily
181 profile multiline blocks without having to put them in a separate
181 profile multiline blocks without having to put them in a separate
182 function.
182 function.
183
183
184 The given statement (which doesn't require quote marks) is run via the
184 The given statement (which doesn't require quote marks) is run via the
185 python profiler in a manner similar to the profile.run() function.
185 python profiler in a manner similar to the profile.run() function.
186 Namespaces are internally managed to work correctly; profile.run
186 Namespaces are internally managed to work correctly; profile.run
187 cannot be used in IPython because it makes certain assumptions about
187 cannot be used in IPython because it makes certain assumptions about
188 namespaces which do not hold under IPython.
188 namespaces which do not hold under IPython.
189
189
190 Options:
190 Options:
191
191
192 -l <limit>
192 -l <limit>
193 you can place restrictions on what or how much of the
193 you can place restrictions on what or how much of the
194 profile gets printed. The limit value can be:
194 profile gets printed. The limit value can be:
195
195
196 * A string: only information for function names containing this string
196 * A string: only information for function names containing this string
197 is printed.
197 is printed.
198
198
199 * An integer: only these many lines are printed.
199 * An integer: only these many lines are printed.
200
200
201 * A float (between 0 and 1): this fraction of the report is printed
201 * A float (between 0 and 1): this fraction of the report is printed
202 (for example, use a limit of 0.4 to see the topmost 40% only).
202 (for example, use a limit of 0.4 to see the topmost 40% only).
203
203
204 You can combine several limits with repeated use of the option. For
204 You can combine several limits with repeated use of the option. For
205 example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
205 example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
206 information about class constructors.
206 information about class constructors.
207
207
208 -r
208 -r
209 return the pstats.Stats object generated by the profiling. This
209 return the pstats.Stats object generated by the profiling. This
210 object has all the information about the profile in it, and you can
210 object has all the information about the profile in it, and you can
211 later use it for further analysis or in other functions.
211 later use it for further analysis or in other functions.
212
212
213 -s <key>
213 -s <key>
214 sort profile by given key. You can provide more than one key
214 sort profile by given key. You can provide more than one key
215 by using the option several times: '-s key1 -s key2 -s key3...'. The
215 by using the option several times: '-s key1 -s key2 -s key3...'. The
216 default sorting key is 'time'.
216 default sorting key is 'time'.
217
217
218 The following is copied verbatim from the profile documentation
218 The following is copied verbatim from the profile documentation
219 referenced below:
219 referenced below:
220
220
221 When more than one key is provided, additional keys are used as
221 When more than one key is provided, additional keys are used as
222 secondary criteria when the there is equality in all keys selected
222 secondary criteria when the there is equality in all keys selected
223 before them.
223 before them.
224
224
225 Abbreviations can be used for any key names, as long as the
225 Abbreviations can be used for any key names, as long as the
226 abbreviation is unambiguous. The following are the keys currently
226 abbreviation is unambiguous. The following are the keys currently
227 defined:
227 defined:
228
228
229 ============ =====================
229 ============ =====================
230 Valid Arg Meaning
230 Valid Arg Meaning
231 ============ =====================
231 ============ =====================
232 "calls" call count
232 "calls" call count
233 "cumulative" cumulative time
233 "cumulative" cumulative time
234 "file" file name
234 "file" file name
235 "module" file name
235 "module" file name
236 "pcalls" primitive call count
236 "pcalls" primitive call count
237 "line" line number
237 "line" line number
238 "name" function name
238 "name" function name
239 "nfl" name/file/line
239 "nfl" name/file/line
240 "stdname" standard name
240 "stdname" standard name
241 "time" internal time
241 "time" internal time
242 ============ =====================
242 ============ =====================
243
243
244 Note that all sorts on statistics are in descending order (placing
244 Note that all sorts on statistics are in descending order (placing
245 most time consuming items first), where as name, file, and line number
245 most time consuming items first), where as name, file, and line number
246 searches are in ascending order (i.e., alphabetical). The subtle
246 searches are in ascending order (i.e., alphabetical). The subtle
247 distinction between "nfl" and "stdname" is that the standard name is a
247 distinction between "nfl" and "stdname" is that the standard name is a
248 sort of the name as printed, which means that the embedded line
248 sort of the name as printed, which means that the embedded line
249 numbers get compared in an odd way. For example, lines 3, 20, and 40
249 numbers get compared in an odd way. For example, lines 3, 20, and 40
250 would (if the file names were the same) appear in the string order
250 would (if the file names were the same) appear in the string order
251 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
251 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
252 line numbers. In fact, sort_stats("nfl") is the same as
252 line numbers. In fact, sort_stats("nfl") is the same as
253 sort_stats("name", "file", "line").
253 sort_stats("name", "file", "line").
254
254
255 -T <filename>
255 -T <filename>
256 save profile results as shown on screen to a text
256 save profile results as shown on screen to a text
257 file. The profile is still shown on screen.
257 file. The profile is still shown on screen.
258
258
259 -D <filename>
259 -D <filename>
260 save (via dump_stats) profile statistics to given
260 save (via dump_stats) profile statistics to given
261 filename. This data is in a format understood by the pstats module, and
261 filename. This data is in a format understood by the pstats module, and
262 is generated by a call to the dump_stats() method of profile
262 is generated by a call to the dump_stats() method of profile
263 objects. The profile is still shown on screen.
263 objects. The profile is still shown on screen.
264
264
265 -q
265 -q
266 suppress output to the pager. Best used with -T and/or -D above.
266 suppress output to the pager. Best used with -T and/or -D above.
267
267
268 If you want to run complete programs under the profiler's control, use
268 If you want to run complete programs under the profiler's control, use
269 ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
269 ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
270 contains profiler specific options as described here.
270 contains profiler specific options as described here.
271
271
272 You can read the complete documentation for the profile module with::
272 You can read the complete documentation for the profile module with::
273
273
274 In [1]: import profile; profile.help()
274 In [1]: import profile; profile.help()
275 """
275 """
276 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
276 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
277 list_all=True, posix=False)
277 list_all=True, posix=False)
278 if cell is not None:
278 if cell is not None:
279 arg_str += '\n' + cell
279 arg_str += '\n' + cell
280 arg_str = self.shell.input_splitter.transform_cell(arg_str)
280 arg_str = self.shell.input_splitter.transform_cell(arg_str)
281 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
281 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
282
282
283 def _run_with_profiler(self, code, opts, namespace):
283 def _run_with_profiler(self, code, opts, namespace):
284 """
284 """
285 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
285 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
286
286
287 Parameters
287 Parameters
288 ----------
288 ----------
289 code : str
289 code : str
290 Code to be executed.
290 Code to be executed.
291 opts : Struct
291 opts : Struct
292 Options parsed by `self.parse_options`.
292 Options parsed by `self.parse_options`.
293 namespace : dict
293 namespace : dict
294 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
294 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
295
295
296 """
296 """
297
297
298 # Fill default values for unspecified options:
298 # Fill default values for unspecified options:
299 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
299 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
300
300
301 prof = profile.Profile()
301 prof = profile.Profile()
302 try:
302 try:
303 prof = prof.runctx(code, namespace, namespace)
303 prof = prof.runctx(code, namespace, namespace)
304 sys_exit = ''
304 sys_exit = ''
305 except SystemExit:
305 except SystemExit:
306 sys_exit = """*** SystemExit exception caught in code being profiled."""
306 sys_exit = """*** SystemExit exception caught in code being profiled."""
307
307
308 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
308 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
309
309
310 lims = opts.l
310 lims = opts.l
311 if lims:
311 if lims:
312 lims = [] # rebuild lims with ints/floats/strings
312 lims = [] # rebuild lims with ints/floats/strings
313 for lim in opts.l:
313 for lim in opts.l:
314 try:
314 try:
315 lims.append(int(lim))
315 lims.append(int(lim))
316 except ValueError:
316 except ValueError:
317 try:
317 try:
318 lims.append(float(lim))
318 lims.append(float(lim))
319 except ValueError:
319 except ValueError:
320 lims.append(lim)
320 lims.append(lim)
321
321
322 # Trap output.
322 # Trap output.
323 stdout_trap = StringIO()
323 stdout_trap = StringIO()
324 stats_stream = stats.stream
324 stats_stream = stats.stream
325 try:
325 try:
326 stats.stream = stdout_trap
326 stats.stream = stdout_trap
327 stats.print_stats(*lims)
327 stats.print_stats(*lims)
328 finally:
328 finally:
329 stats.stream = stats_stream
329 stats.stream = stats_stream
330
330
331 output = stdout_trap.getvalue()
331 output = stdout_trap.getvalue()
332 output = output.rstrip()
332 output = output.rstrip()
333
333
334 if 'q' not in opts:
334 if 'q' not in opts:
335 page.page(output)
335 page.page(output)
336 print(sys_exit, end=' ')
336 print(sys_exit, end=' ')
337
337
338 dump_file = opts.D[0]
338 dump_file = opts.D[0]
339 text_file = opts.T[0]
339 text_file = opts.T[0]
340 if dump_file:
340 if dump_file:
341 dump_file = unquote_filename(dump_file)
341 dump_file = unquote_filename(dump_file)
342 prof.dump_stats(dump_file)
342 prof.dump_stats(dump_file)
343 print('\n*** Profile stats marshalled to file',\
343 print('\n*** Profile stats marshalled to file',\
344 repr(dump_file)+'.',sys_exit)
344 repr(dump_file)+'.',sys_exit)
345 if text_file:
345 if text_file:
346 text_file = unquote_filename(text_file)
346 text_file = unquote_filename(text_file)
347 pfile = open(text_file,'w')
347 pfile = open(text_file,'w')
348 pfile.write(output)
348 pfile.write(output)
349 pfile.close()
349 pfile.close()
350 print('\n*** Profile printout saved to text file',\
350 print('\n*** Profile printout saved to text file',\
351 repr(text_file)+'.',sys_exit)
351 repr(text_file)+'.',sys_exit)
352
352
353 if 'r' in opts:
353 if 'r' in opts:
354 return stats
354 return stats
355 else:
355 else:
356 return None
356 return None
357
357
358 @line_magic
358 @line_magic
359 def pdb(self, parameter_s=''):
359 def pdb(self, parameter_s=''):
360 """Control the automatic calling of the pdb interactive debugger.
360 """Control the automatic calling of the pdb interactive debugger.
361
361
362 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
362 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
363 argument it works as a toggle.
363 argument it works as a toggle.
364
364
365 When an exception is triggered, IPython can optionally call the
365 When an exception is triggered, IPython can optionally call the
366 interactive pdb debugger after the traceback printout. %pdb toggles
366 interactive pdb debugger after the traceback printout. %pdb toggles
367 this feature on and off.
367 this feature on and off.
368
368
369 The initial state of this feature is set in your configuration
369 The initial state of this feature is set in your configuration
370 file (the option is ``InteractiveShell.pdb``).
370 file (the option is ``InteractiveShell.pdb``).
371
371
372 If you want to just activate the debugger AFTER an exception has fired,
372 If you want to just activate the debugger AFTER an exception has fired,
373 without having to type '%pdb on' and rerunning your code, you can use
373 without having to type '%pdb on' and rerunning your code, you can use
374 the %debug magic."""
374 the %debug magic."""
375
375
376 par = parameter_s.strip().lower()
376 par = parameter_s.strip().lower()
377
377
378 if par:
378 if par:
379 try:
379 try:
380 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
380 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
381 except KeyError:
381 except KeyError:
382 print ('Incorrect argument. Use on/1, off/0, '
382 print ('Incorrect argument. Use on/1, off/0, '
383 'or nothing for a toggle.')
383 'or nothing for a toggle.')
384 return
384 return
385 else:
385 else:
386 # toggle
386 # toggle
387 new_pdb = not self.shell.call_pdb
387 new_pdb = not self.shell.call_pdb
388
388
389 # set on the shell
389 # set on the shell
390 self.shell.call_pdb = new_pdb
390 self.shell.call_pdb = new_pdb
391 print('Automatic pdb calling has been turned',on_off(new_pdb))
391 print('Automatic pdb calling has been turned',on_off(new_pdb))
392
392
393 @skip_doctest
393 @skip_doctest
394 @magic_arguments.magic_arguments()
394 @magic_arguments.magic_arguments()
395 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
395 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
396 help="""
396 help="""
397 Set break point at LINE in FILE.
397 Set break point at LINE in FILE.
398 """
398 """
399 )
399 )
400 @magic_arguments.argument('statement', nargs='*',
400 @magic_arguments.argument('statement', nargs='*',
401 help="""
401 help="""
402 Code to run in debugger.
402 Code to run in debugger.
403 You can omit this in cell magic mode.
403 You can omit this in cell magic mode.
404 """
404 """
405 )
405 )
406 @line_cell_magic
406 @line_cell_magic
407 def debug(self, line='', cell=None):
407 def debug(self, line='', cell=None):
408 """Activate the interactive debugger.
408 """Activate the interactive debugger.
409
409
410 This magic command support two ways of activating debugger.
410 This magic command support two ways of activating debugger.
411 One is to activate debugger before executing code. This way, you
411 One is to activate debugger before executing code. This way, you
412 can set a break point, to step through the code from the point.
412 can set a break point, to step through the code from the point.
413 You can use this mode by giving statements to execute and optionally
413 You can use this mode by giving statements to execute and optionally
414 a breakpoint.
414 a breakpoint.
415
415
416 The other one is to activate debugger in post-mortem mode. You can
416 The other one is to activate debugger in post-mortem mode. You can
417 activate this mode simply running %debug without any argument.
417 activate this mode simply running %debug without any argument.
418 If an exception has just occurred, this lets you inspect its stack
418 If an exception has just occurred, this lets you inspect its stack
419 frames interactively. Note that this will always work only on the last
419 frames interactively. Note that this will always work only on the last
420 traceback that occurred, so you must call this quickly after an
420 traceback that occurred, so you must call this quickly after an
421 exception that you wish to inspect has fired, because if another one
421 exception that you wish to inspect has fired, because if another one
422 occurs, it clobbers the previous one.
422 occurs, it clobbers the previous one.
423
423
424 If you want IPython to automatically do this on every exception, see
424 If you want IPython to automatically do this on every exception, see
425 the %pdb magic for more details.
425 the %pdb magic for more details.
426 """
426 """
427 args = magic_arguments.parse_argstring(self.debug, line)
427 args = magic_arguments.parse_argstring(self.debug, line)
428
428
429 if not (args.breakpoint or args.statement or cell):
429 if not (args.breakpoint or args.statement or cell):
430 self._debug_post_mortem()
430 self._debug_post_mortem()
431 else:
431 else:
432 code = "\n".join(args.statement)
432 code = "\n".join(args.statement)
433 if cell:
433 if cell:
434 code += "\n" + cell
434 code += "\n" + cell
435 self._debug_exec(code, args.breakpoint)
435 self._debug_exec(code, args.breakpoint)
436
436
437 def _debug_post_mortem(self):
437 def _debug_post_mortem(self):
438 self.shell.debugger(force=True)
438 self.shell.debugger(force=True)
439
439
440 def _debug_exec(self, code, breakpoint):
440 def _debug_exec(self, code, breakpoint):
441 if breakpoint:
441 if breakpoint:
442 (filename, bp_line) = breakpoint.split(':', 1)
442 (filename, bp_line) = breakpoint.split(':', 1)
443 bp_line = int(bp_line)
443 bp_line = int(bp_line)
444 else:
444 else:
445 (filename, bp_line) = (None, None)
445 (filename, bp_line) = (None, None)
446 self._run_with_debugger(code, self.shell.user_ns, filename, bp_line)
446 self._run_with_debugger(code, self.shell.user_ns, filename, bp_line)
447
447
448 @line_magic
448 @line_magic
449 def tb(self, s):
449 def tb(self, s):
450 """Print the last traceback with the currently active exception mode.
450 """Print the last traceback with the currently active exception mode.
451
451
452 See %xmode for changing exception reporting modes."""
452 See %xmode for changing exception reporting modes."""
453 self.shell.showtraceback()
453 self.shell.showtraceback()
454
454
455 @skip_doctest
455 @skip_doctest
456 @line_magic
456 @line_magic
457 def run(self, parameter_s='', runner=None,
457 def run(self, parameter_s='', runner=None,
458 file_finder=get_py_filename):
458 file_finder=get_py_filename):
459 """Run the named file inside IPython as a program.
459 """Run the named file inside IPython as a program.
460
460
461 Usage::
461 Usage::
462
462
463 %run [-n -i -e -G]
463 %run [-n -i -e -G]
464 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
464 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
465 ( -m mod | file ) [args]
465 ( -m mod | file ) [args]
466
466
467 Parameters after the filename are passed as command-line arguments to
467 Parameters after the filename are passed as command-line arguments to
468 the program (put in sys.argv). Then, control returns to IPython's
468 the program (put in sys.argv). Then, control returns to IPython's
469 prompt.
469 prompt.
470
470
471 This is similar to running at a system prompt ``python file args``,
471 This is similar to running at a system prompt ``python file args``,
472 but with the advantage of giving you IPython's tracebacks, and of
472 but with the advantage of giving you IPython's tracebacks, and of
473 loading all variables into your interactive namespace for further use
473 loading all variables into your interactive namespace for further use
474 (unless -p is used, see below).
474 (unless -p is used, see below).
475
475
476 The file is executed in a namespace initially consisting only of
476 The file is executed in a namespace initially consisting only of
477 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
477 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
478 sees its environment as if it were being run as a stand-alone program
478 sees its environment as if it were being run as a stand-alone program
479 (except for sharing global objects such as previously imported
479 (except for sharing global objects such as previously imported
480 modules). But after execution, the IPython interactive namespace gets
480 modules). But after execution, the IPython interactive namespace gets
481 updated with all variables defined in the program (except for __name__
481 updated with all variables defined in the program (except for __name__
482 and sys.argv). This allows for very convenient loading of code for
482 and sys.argv). This allows for very convenient loading of code for
483 interactive work, while giving each program a 'clean sheet' to run in.
483 interactive work, while giving each program a 'clean sheet' to run in.
484
484
485 Arguments are expanded using shell-like glob match. Patterns
485 Arguments are expanded using shell-like glob match. Patterns
486 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
486 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
487 tilde '~' will be expanded into user's home directory. Unlike
487 tilde '~' will be expanded into user's home directory. Unlike
488 real shells, quotation does not suppress expansions. Use
488 real shells, quotation does not suppress expansions. Use
489 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
489 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
490 To completely disable these expansions, you can use -G flag.
490 To completely disable these expansions, you can use -G flag.
491
491
492 Options:
492 Options:
493
493
494 -n
494 -n
495 __name__ is NOT set to '__main__', but to the running file's name
495 __name__ is NOT set to '__main__', but to the running file's name
496 without extension (as python does under import). This allows running
496 without extension (as python does under import). This allows running
497 scripts and reloading the definitions in them without calling code
497 scripts and reloading the definitions in them without calling code
498 protected by an ``if __name__ == "__main__"`` clause.
498 protected by an ``if __name__ == "__main__"`` clause.
499
499
500 -i
500 -i
501 run the file in IPython's namespace instead of an empty one. This
501 run the file in IPython's namespace instead of an empty one. This
502 is useful if you are experimenting with code written in a text editor
502 is useful if you are experimenting with code written in a text editor
503 which depends on variables defined interactively.
503 which depends on variables defined interactively.
504
504
505 -e
505 -e
506 ignore sys.exit() calls or SystemExit exceptions in the script
506 ignore sys.exit() calls or SystemExit exceptions in the script
507 being run. This is particularly useful if IPython is being used to
507 being run. This is particularly useful if IPython is being used to
508 run unittests, which always exit with a sys.exit() call. In such
508 run unittests, which always exit with a sys.exit() call. In such
509 cases you are interested in the output of the test results, not in
509 cases you are interested in the output of the test results, not in
510 seeing a traceback of the unittest module.
510 seeing a traceback of the unittest module.
511
511
512 -t
512 -t
513 print timing information at the end of the run. IPython will give
513 print timing information at the end of the run. IPython will give
514 you an estimated CPU time consumption for your script, which under
514 you an estimated CPU time consumption for your script, which under
515 Unix uses the resource module to avoid the wraparound problems of
515 Unix uses the resource module to avoid the wraparound problems of
516 time.clock(). Under Unix, an estimate of time spent on system tasks
516 time.clock(). Under Unix, an estimate of time spent on system tasks
517 is also given (for Windows platforms this is reported as 0.0).
517 is also given (for Windows platforms this is reported as 0.0).
518
518
519 If -t is given, an additional ``-N<N>`` option can be given, where <N>
519 If -t is given, an additional ``-N<N>`` option can be given, where <N>
520 must be an integer indicating how many times you want the script to
520 must be an integer indicating how many times you want the script to
521 run. The final timing report will include total and per run results.
521 run. The final timing report will include total and per run results.
522
522
523 For example (testing the script uniq_stable.py)::
523 For example (testing the script uniq_stable.py)::
524
524
525 In [1]: run -t uniq_stable
525 In [1]: run -t uniq_stable
526
526
527 IPython CPU timings (estimated):
527 IPython CPU timings (estimated):
528 User : 0.19597 s.
528 User : 0.19597 s.
529 System: 0.0 s.
529 System: 0.0 s.
530
530
531 In [2]: run -t -N5 uniq_stable
531 In [2]: run -t -N5 uniq_stable
532
532
533 IPython CPU timings (estimated):
533 IPython CPU timings (estimated):
534 Total runs performed: 5
534 Total runs performed: 5
535 Times : Total Per run
535 Times : Total Per run
536 User : 0.910862 s, 0.1821724 s.
536 User : 0.910862 s, 0.1821724 s.
537 System: 0.0 s, 0.0 s.
537 System: 0.0 s, 0.0 s.
538
538
539 -d
539 -d
540 run your program under the control of pdb, the Python debugger.
540 run your program under the control of pdb, the Python debugger.
541 This allows you to execute your program step by step, watch variables,
541 This allows you to execute your program step by step, watch variables,
542 etc. Internally, what IPython does is similar to calling::
542 etc. Internally, what IPython does is similar to calling::
543
543
544 pdb.run('execfile("YOURFILENAME")')
544 pdb.run('execfile("YOURFILENAME")')
545
545
546 with a breakpoint set on line 1 of your file. You can change the line
546 with a breakpoint set on line 1 of your file. You can change the line
547 number for this automatic breakpoint to be <N> by using the -bN option
547 number for this automatic breakpoint to be <N> by using the -bN option
548 (where N must be an integer). For example::
548 (where N must be an integer). For example::
549
549
550 %run -d -b40 myscript
550 %run -d -b40 myscript
551
551
552 will set the first breakpoint at line 40 in myscript.py. Note that
552 will set the first breakpoint at line 40 in myscript.py. Note that
553 the first breakpoint must be set on a line which actually does
553 the first breakpoint must be set on a line which actually does
554 something (not a comment or docstring) for it to stop execution.
554 something (not a comment or docstring) for it to stop execution.
555
555
556 Or you can specify a breakpoint in a different file::
556 Or you can specify a breakpoint in a different file::
557
557
558 %run -d -b myotherfile.py:20 myscript
558 %run -d -b myotherfile.py:20 myscript
559
559
560 When the pdb debugger starts, you will see a (Pdb) prompt. You must
560 When the pdb debugger starts, you will see a (Pdb) prompt. You must
561 first enter 'c' (without quotes) to start execution up to the first
561 first enter 'c' (without quotes) to start execution up to the first
562 breakpoint.
562 breakpoint.
563
563
564 Entering 'help' gives information about the use of the debugger. You
564 Entering 'help' gives information about the use of the debugger. You
565 can easily see pdb's full documentation with "import pdb;pdb.help()"
565 can easily see pdb's full documentation with "import pdb;pdb.help()"
566 at a prompt.
566 at a prompt.
567
567
568 -p
568 -p
569 run program under the control of the Python profiler module (which
569 run program under the control of the Python profiler module (which
570 prints a detailed report of execution times, function calls, etc).
570 prints a detailed report of execution times, function calls, etc).
571
571
572 You can pass other options after -p which affect the behavior of the
572 You can pass other options after -p which affect the behavior of the
573 profiler itself. See the docs for %prun for details.
573 profiler itself. See the docs for %prun for details.
574
574
575 In this mode, the program's variables do NOT propagate back to the
575 In this mode, the program's variables do NOT propagate back to the
576 IPython interactive namespace (because they remain in the namespace
576 IPython interactive namespace (because they remain in the namespace
577 where the profiler executes them).
577 where the profiler executes them).
578
578
579 Internally this triggers a call to %prun, see its documentation for
579 Internally this triggers a call to %prun, see its documentation for
580 details on the options available specifically for profiling.
580 details on the options available specifically for profiling.
581
581
582 There is one special usage for which the text above doesn't apply:
582 There is one special usage for which the text above doesn't apply:
583 if the filename ends with .ipy[nb], the file is run as ipython script,
583 if the filename ends with .ipy[nb], the file is run as ipython script,
584 just as if the commands were written on IPython prompt.
584 just as if the commands were written on IPython prompt.
585
585
586 -m
586 -m
587 specify module name to load instead of script path. Similar to
587 specify module name to load instead of script path. Similar to
588 the -m option for the python interpreter. Use this option last if you
588 the -m option for the python interpreter. Use this option last if you
589 want to combine with other %run options. Unlike the python interpreter
589 want to combine with other %run options. Unlike the python interpreter
590 only source modules are allowed no .pyc or .pyo files.
590 only source modules are allowed no .pyc or .pyo files.
591 For example::
591 For example::
592
592
593 %run -m example
593 %run -m example
594
594
595 will run the example module.
595 will run the example module.
596
596
597 -G
597 -G
598 disable shell-like glob expansion of arguments.
598 disable shell-like glob expansion of arguments.
599
599
600 """
600 """
601
601
602 # get arguments and set sys.argv for program to be run.
602 # get arguments and set sys.argv for program to be run.
603 opts, arg_lst = self.parse_options(parameter_s,
603 opts, arg_lst = self.parse_options(parameter_s,
604 'nidtN:b:pD:l:rs:T:em:G',
604 'nidtN:b:pD:l:rs:T:em:G',
605 mode='list', list_all=1)
605 mode='list', list_all=1)
606 if "m" in opts:
606 if "m" in opts:
607 modulename = opts["m"][0]
607 modulename = opts["m"][0]
608 modpath = find_mod(modulename)
608 modpath = find_mod(modulename)
609 if modpath is None:
609 if modpath is None:
610 warn('%r is not a valid modulename on sys.path'%modulename)
610 warn('%r is not a valid modulename on sys.path'%modulename)
611 return
611 return
612 arg_lst = [modpath] + arg_lst
612 arg_lst = [modpath] + arg_lst
613 try:
613 try:
614 filename = file_finder(arg_lst[0])
614 filename = file_finder(arg_lst[0])
615 except IndexError:
615 except IndexError:
616 warn('you must provide at least a filename.')
616 warn('you must provide at least a filename.')
617 print('\n%run:\n', oinspect.getdoc(self.run))
617 print('\n%run:\n', oinspect.getdoc(self.run))
618 return
618 return
619 except IOError as e:
619 except IOError as e:
620 try:
620 try:
621 msg = str(e)
621 msg = str(e)
622 except UnicodeError:
622 except UnicodeError:
623 msg = e.message
623 msg = e.message
624 error(msg)
624 error(msg)
625 return
625 return
626
626
627 if filename.lower().endswith(('.ipy', '.ipynb')):
627 if filename.lower().endswith(('.ipy', '.ipynb')):
628 with preserve_keys(self.shell.user_ns, '__file__'):
628 with preserve_keys(self.shell.user_ns, '__file__'):
629 self.shell.user_ns['__file__'] = filename
629 self.shell.user_ns['__file__'] = filename
630 self.shell.safe_execfile_ipy(filename)
630 self.shell.safe_execfile_ipy(filename)
631 return
631 return
632
632
633 # Control the response to exit() calls made by the script being run
633 # Control the response to exit() calls made by the script being run
634 exit_ignore = 'e' in opts
634 exit_ignore = 'e' in opts
635
635
636 # Make sure that the running script gets a proper sys.argv as if it
636 # Make sure that the running script gets a proper sys.argv as if it
637 # were run from a system shell.
637 # were run from a system shell.
638 save_argv = sys.argv # save it for later restoring
638 save_argv = sys.argv # save it for later restoring
639
639
640 if 'G' in opts:
640 if 'G' in opts:
641 args = arg_lst[1:]
641 args = arg_lst[1:]
642 else:
642 else:
643 # tilde and glob expansion
643 # tilde and glob expansion
644 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
644 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
645
645
646 sys.argv = [filename] + args # put in the proper filename
646 sys.argv = [filename] + args # put in the proper filename
647 # protect sys.argv from potential unicode strings on Python 2:
647 # protect sys.argv from potential unicode strings on Python 2:
648 if not py3compat.PY3:
648 if not py3compat.PY3:
649 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
649 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
650
650
651 if 'i' in opts:
651 if 'i' in opts:
652 # Run in user's interactive namespace
652 # Run in user's interactive namespace
653 prog_ns = self.shell.user_ns
653 prog_ns = self.shell.user_ns
654 __name__save = self.shell.user_ns['__name__']
654 __name__save = self.shell.user_ns['__name__']
655 prog_ns['__name__'] = '__main__'
655 prog_ns['__name__'] = '__main__'
656 main_mod = self.shell.user_module
656 main_mod = self.shell.user_module
657
657
658 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
658 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
659 # set the __file__ global in the script's namespace
659 # set the __file__ global in the script's namespace
660 # TK: Is this necessary in interactive mode?
660 # TK: Is this necessary in interactive mode?
661 prog_ns['__file__'] = filename
661 prog_ns['__file__'] = filename
662 else:
662 else:
663 # Run in a fresh, empty namespace
663 # Run in a fresh, empty namespace
664 if 'n' in opts:
664 if 'n' in opts:
665 name = os.path.splitext(os.path.basename(filename))[0]
665 name = os.path.splitext(os.path.basename(filename))[0]
666 else:
666 else:
667 name = '__main__'
667 name = '__main__'
668
668
669 # The shell MUST hold a reference to prog_ns so after %run
669 # The shell MUST hold a reference to prog_ns so after %run
670 # exits, the python deletion mechanism doesn't zero it out
670 # exits, the python deletion mechanism doesn't zero it out
671 # (leaving dangling references). See interactiveshell for details
671 # (leaving dangling references). See interactiveshell for details
672 main_mod = self.shell.new_main_mod(filename, name)
672 main_mod = self.shell.new_main_mod(filename, name)
673 prog_ns = main_mod.__dict__
673 prog_ns = main_mod.__dict__
674
674
675 # pickle fix. See interactiveshell for an explanation. But we need to
675 # pickle fix. See interactiveshell for an explanation. But we need to
676 # make sure that, if we overwrite __main__, we replace it at the end
676 # make sure that, if we overwrite __main__, we replace it at the end
677 main_mod_name = prog_ns['__name__']
677 main_mod_name = prog_ns['__name__']
678
678
679 if main_mod_name == '__main__':
679 if main_mod_name == '__main__':
680 restore_main = sys.modules['__main__']
680 restore_main = sys.modules['__main__']
681 else:
681 else:
682 restore_main = False
682 restore_main = False
683
683
684 # This needs to be undone at the end to prevent holding references to
684 # This needs to be undone at the end to prevent holding references to
685 # every single object ever created.
685 # every single object ever created.
686 sys.modules[main_mod_name] = main_mod
686 sys.modules[main_mod_name] = main_mod
687
687
688 if 'p' in opts or 'd' in opts:
688 if 'p' in opts or 'd' in opts:
689 if 'm' in opts:
689 if 'm' in opts:
690 code = 'run_module(modulename, prog_ns)'
690 code = 'run_module(modulename, prog_ns)'
691 code_ns = {
691 code_ns = {
692 'run_module': self.shell.safe_run_module,
692 'run_module': self.shell.safe_run_module,
693 'prog_ns': prog_ns,
693 'prog_ns': prog_ns,
694 'modulename': modulename,
694 'modulename': modulename,
695 }
695 }
696 else:
696 else:
697 if 'd' in opts:
697 if 'd' in opts:
698 # allow exceptions to raise in debug mode
698 # allow exceptions to raise in debug mode
699 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
699 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
700 else:
700 else:
701 code = 'execfile(filename, prog_ns)'
701 code = 'execfile(filename, prog_ns)'
702 code_ns = {
702 code_ns = {
703 'execfile': self.shell.safe_execfile,
703 'execfile': self.shell.safe_execfile,
704 'prog_ns': prog_ns,
704 'prog_ns': prog_ns,
705 'filename': get_py_filename(filename),
705 'filename': get_py_filename(filename),
706 }
706 }
707
707
708 try:
708 try:
709 stats = None
709 stats = None
710 with self.shell.readline_no_record:
710 with self.shell.readline_no_record:
711 if 'p' in opts:
711 if 'p' in opts:
712 stats = self._run_with_profiler(code, opts, code_ns)
712 stats = self._run_with_profiler(code, opts, code_ns)
713 else:
713 else:
714 if 'd' in opts:
714 if 'd' in opts:
715 bp_file, bp_line = parse_breakpoint(
715 bp_file, bp_line = parse_breakpoint(
716 opts.get('b', ['1'])[0], filename)
716 opts.get('b', ['1'])[0], filename)
717 self._run_with_debugger(
717 self._run_with_debugger(
718 code, code_ns, filename, bp_line, bp_file)
718 code, code_ns, filename, bp_line, bp_file)
719 else:
719 else:
720 if 'm' in opts:
720 if 'm' in opts:
721 def run():
721 def run():
722 self.shell.safe_run_module(modulename, prog_ns)
722 self.shell.safe_run_module(modulename, prog_ns)
723 else:
723 else:
724 if runner is None:
724 if runner is None:
725 runner = self.default_runner
725 runner = self.default_runner
726 if runner is None:
726 if runner is None:
727 runner = self.shell.safe_execfile
727 runner = self.shell.safe_execfile
728
728
729 def run():
729 def run():
730 runner(filename, prog_ns, prog_ns,
730 runner(filename, prog_ns, prog_ns,
731 exit_ignore=exit_ignore)
731 exit_ignore=exit_ignore)
732
732
733 if 't' in opts:
733 if 't' in opts:
734 # timed execution
734 # timed execution
735 try:
735 try:
736 nruns = int(opts['N'][0])
736 nruns = int(opts['N'][0])
737 if nruns < 1:
737 if nruns < 1:
738 error('Number of runs must be >=1')
738 error('Number of runs must be >=1')
739 return
739 return
740 except (KeyError):
740 except (KeyError):
741 nruns = 1
741 nruns = 1
742 self._run_with_timing(run, nruns)
742 self._run_with_timing(run, nruns)
743 else:
743 else:
744 # regular execution
744 # regular execution
745 run()
745 run()
746
746
747 if 'i' in opts:
747 if 'i' in opts:
748 self.shell.user_ns['__name__'] = __name__save
748 self.shell.user_ns['__name__'] = __name__save
749 else:
749 else:
750 # update IPython interactive namespace
750 # update IPython interactive namespace
751
751
752 # Some forms of read errors on the file may mean the
752 # Some forms of read errors on the file may mean the
753 # __name__ key was never set; using pop we don't have to
753 # __name__ key was never set; using pop we don't have to
754 # worry about a possible KeyError.
754 # worry about a possible KeyError.
755 prog_ns.pop('__name__', None)
755 prog_ns.pop('__name__', None)
756
756
757 with preserve_keys(self.shell.user_ns, '__file__'):
757 with preserve_keys(self.shell.user_ns, '__file__'):
758 self.shell.user_ns.update(prog_ns)
758 self.shell.user_ns.update(prog_ns)
759 finally:
759 finally:
760 # It's a bit of a mystery why, but __builtins__ can change from
760 # It's a bit of a mystery why, but __builtins__ can change from
761 # being a module to becoming a dict missing some key data after
761 # being a module to becoming a dict missing some key data after
762 # %run. As best I can see, this is NOT something IPython is doing
762 # %run. As best I can see, this is NOT something IPython is doing
763 # at all, and similar problems have been reported before:
763 # at all, and similar problems have been reported before:
764 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
764 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
765 # Since this seems to be done by the interpreter itself, the best
765 # Since this seems to be done by the interpreter itself, the best
766 # we can do is to at least restore __builtins__ for the user on
766 # we can do is to at least restore __builtins__ for the user on
767 # exit.
767 # exit.
768 self.shell.user_ns['__builtins__'] = builtin_mod
768 self.shell.user_ns['__builtins__'] = builtin_mod
769
769
770 # Ensure key global structures are restored
770 # Ensure key global structures are restored
771 sys.argv = save_argv
771 sys.argv = save_argv
772 if restore_main:
772 if restore_main:
773 sys.modules['__main__'] = restore_main
773 sys.modules['__main__'] = restore_main
774 else:
774 else:
775 # Remove from sys.modules the reference to main_mod we'd
775 # Remove from sys.modules the reference to main_mod we'd
776 # added. Otherwise it will trap references to objects
776 # added. Otherwise it will trap references to objects
777 # contained therein.
777 # contained therein.
778 del sys.modules[main_mod_name]
778 del sys.modules[main_mod_name]
779
779
780 return stats
780 return stats
781
781
782 def _run_with_debugger(self, code, code_ns, filename=None,
782 def _run_with_debugger(self, code, code_ns, filename=None,
783 bp_line=None, bp_file=None):
783 bp_line=None, bp_file=None):
784 """
784 """
785 Run `code` in debugger with a break point.
785 Run `code` in debugger with a break point.
786
786
787 Parameters
787 Parameters
788 ----------
788 ----------
789 code : str
789 code : str
790 Code to execute.
790 Code to execute.
791 code_ns : dict
791 code_ns : dict
792 A namespace in which `code` is executed.
792 A namespace in which `code` is executed.
793 filename : str
793 filename : str
794 `code` is ran as if it is in `filename`.
794 `code` is ran as if it is in `filename`.
795 bp_line : int, optional
795 bp_line : int, optional
796 Line number of the break point.
796 Line number of the break point.
797 bp_file : str, optional
797 bp_file : str, optional
798 Path to the file in which break point is specified.
798 Path to the file in which break point is specified.
799 `filename` is used if not given.
799 `filename` is used if not given.
800
800
801 Raises
801 Raises
802 ------
802 ------
803 UsageError
803 UsageError
804 If the break point given by `bp_line` is not valid.
804 If the break point given by `bp_line` is not valid.
805
805
806 """
806 """
807 deb = debugger.Pdb(self.shell.colors)
807 deb = debugger.Pdb(self.shell.colors)
808 # reset Breakpoint state, which is moronically kept
808 # reset Breakpoint state, which is moronically kept
809 # in a class
809 # in a class
810 bdb.Breakpoint.next = 1
810 bdb.Breakpoint.next = 1
811 bdb.Breakpoint.bplist = {}
811 bdb.Breakpoint.bplist = {}
812 bdb.Breakpoint.bpbynumber = [None]
812 bdb.Breakpoint.bpbynumber = [None]
813 if bp_line is not None:
813 if bp_line is not None:
814 # Set an initial breakpoint to stop execution
814 # Set an initial breakpoint to stop execution
815 maxtries = 10
815 maxtries = 10
816 bp_file = bp_file or filename
816 bp_file = bp_file or filename
817 checkline = deb.checkline(bp_file, bp_line)
817 checkline = deb.checkline(bp_file, bp_line)
818 if not checkline:
818 if not checkline:
819 for bp in range(bp_line + 1, bp_line + maxtries + 1):
819 for bp in range(bp_line + 1, bp_line + maxtries + 1):
820 if deb.checkline(bp_file, bp):
820 if deb.checkline(bp_file, bp):
821 break
821 break
822 else:
822 else:
823 msg = ("\nI failed to find a valid line to set "
823 msg = ("\nI failed to find a valid line to set "
824 "a breakpoint\n"
824 "a breakpoint\n"
825 "after trying up to line: %s.\n"
825 "after trying up to line: %s.\n"
826 "Please set a valid breakpoint manually "
826 "Please set a valid breakpoint manually "
827 "with the -b option." % bp)
827 "with the -b option." % bp)
828 raise UsageError(msg)
828 raise UsageError(msg)
829 # if we find a good linenumber, set the breakpoint
829 # if we find a good linenumber, set the breakpoint
830 deb.do_break('%s:%s' % (bp_file, bp_line))
830 deb.do_break('%s:%s' % (bp_file, bp_line))
831
831
832 if filename:
832 if filename:
833 # Mimic Pdb._runscript(...)
833 # Mimic Pdb._runscript(...)
834 deb._wait_for_mainpyfile = True
834 deb._wait_for_mainpyfile = True
835 deb.mainpyfile = deb.canonic(filename)
835 deb.mainpyfile = deb.canonic(filename)
836
836
837 # Start file run
837 # Start file run
838 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
838 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
839 try:
839 try:
840 if filename:
840 if filename:
841 # save filename so it can be used by methods on the deb object
841 # save filename so it can be used by methods on the deb object
842 deb._exec_filename = filename
842 deb._exec_filename = filename
843 while True:
843 while True:
844 try:
844 try:
845 deb.run(code, code_ns)
845 deb.run(code, code_ns)
846 except Restart:
846 except Restart:
847 print("Restarting")
847 print("Restarting")
848 if filename:
848 if filename:
849 deb._wait_for_mainpyfile = True
849 deb._wait_for_mainpyfile = True
850 deb.mainpyfile = deb.canonic(filename)
850 deb.mainpyfile = deb.canonic(filename)
851 continue
851 continue
852 else:
852 else:
853 break
853 break
854
854
855
855
856 except:
856 except:
857 etype, value, tb = sys.exc_info()
857 etype, value, tb = sys.exc_info()
858 # Skip three frames in the traceback: the %run one,
858 # Skip three frames in the traceback: the %run one,
859 # one inside bdb.py, and the command-line typed by the
859 # one inside bdb.py, and the command-line typed by the
860 # user (run by exec in pdb itself).
860 # user (run by exec in pdb itself).
861 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
861 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
862
862
863 @staticmethod
863 @staticmethod
864 def _run_with_timing(run, nruns):
864 def _run_with_timing(run, nruns):
865 """
865 """
866 Run function `run` and print timing information.
866 Run function `run` and print timing information.
867
867
868 Parameters
868 Parameters
869 ----------
869 ----------
870 run : callable
870 run : callable
871 Any callable object which takes no argument.
871 Any callable object which takes no argument.
872 nruns : int
872 nruns : int
873 Number of times to execute `run`.
873 Number of times to execute `run`.
874
874
875 """
875 """
876 twall0 = time.time()
876 twall0 = time.time()
877 if nruns == 1:
877 if nruns == 1:
878 t0 = clock2()
878 t0 = clock2()
879 run()
879 run()
880 t1 = clock2()
880 t1 = clock2()
881 t_usr = t1[0] - t0[0]
881 t_usr = t1[0] - t0[0]
882 t_sys = t1[1] - t0[1]
882 t_sys = t1[1] - t0[1]
883 print("\nIPython CPU timings (estimated):")
883 print("\nIPython CPU timings (estimated):")
884 print(" User : %10.2f s." % t_usr)
884 print(" User : %10.2f s." % t_usr)
885 print(" System : %10.2f s." % t_sys)
885 print(" System : %10.2f s." % t_sys)
886 else:
886 else:
887 runs = range(nruns)
887 runs = range(nruns)
888 t0 = clock2()
888 t0 = clock2()
889 for nr in runs:
889 for nr in runs:
890 run()
890 run()
891 t1 = clock2()
891 t1 = clock2()
892 t_usr = t1[0] - t0[0]
892 t_usr = t1[0] - t0[0]
893 t_sys = t1[1] - t0[1]
893 t_sys = t1[1] - t0[1]
894 print("\nIPython CPU timings (estimated):")
894 print("\nIPython CPU timings (estimated):")
895 print("Total runs performed:", nruns)
895 print("Total runs performed:", nruns)
896 print(" Times : %10s %10s" % ('Total', 'Per run'))
896 print(" Times : %10s %10s" % ('Total', 'Per run'))
897 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
897 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
898 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
898 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
899 twall1 = time.time()
899 twall1 = time.time()
900 print("Wall time: %10.2f s." % (twall1 - twall0))
900 print("Wall time: %10.2f s." % (twall1 - twall0))
901
901
902 @skip_doctest
902 @skip_doctest
903 @line_cell_magic
903 @line_cell_magic
904 def timeit(self, line='', cell=None):
904 def timeit(self, line='', cell=None):
905 """Time execution of a Python statement or expression
905 """Time execution of a Python statement or expression
906
906
907 Usage, in line mode:
907 Usage, in line mode:
908 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
908 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
909 or in cell mode:
909 or in cell mode:
910 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
910 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
911 code
911 code
912 code...
912 code...
913
913
914 Time execution of a Python statement or expression using the timeit
914 Time execution of a Python statement or expression using the timeit
915 module. This function can be used both as a line and cell magic:
915 module. This function can be used both as a line and cell magic:
916
916
917 - In line mode you can time a single-line statement (though multiple
917 - In line mode you can time a single-line statement (though multiple
918 ones can be chained with using semicolons).
918 ones can be chained with using semicolons).
919
919
920 - In cell mode, the statement in the first line is used as setup code
920 - In cell mode, the statement in the first line is used as setup code
921 (executed but not timed) and the body of the cell is timed. The cell
921 (executed but not timed) and the body of the cell is timed. The cell
922 body has access to any variables created in the setup code.
922 body has access to any variables created in the setup code.
923
923
924 Options:
924 Options:
925 -n<N>: execute the given statement <N> times in a loop. If this value
925 -n<N>: execute the given statement <N> times in a loop. If this value
926 is not given, a fitting value is chosen.
926 is not given, a fitting value is chosen.
927
927
928 -r<R>: repeat the loop iteration <R> times and take the best result.
928 -r<R>: repeat the loop iteration <R> times and take the best result.
929 Default: 3
929 Default: 3
930
930
931 -t: use time.time to measure the time, which is the default on Unix.
931 -t: use time.time to measure the time, which is the default on Unix.
932 This function measures wall time.
932 This function measures wall time.
933
933
934 -c: use time.clock to measure the time, which is the default on
934 -c: use time.clock to measure the time, which is the default on
935 Windows and measures wall time. On Unix, resource.getrusage is used
935 Windows and measures wall time. On Unix, resource.getrusage is used
936 instead and returns the CPU user time.
936 instead and returns the CPU user time.
937
937
938 -p<P>: use a precision of <P> digits to display the timing result.
938 -p<P>: use a precision of <P> digits to display the timing result.
939 Default: 3
939 Default: 3
940
940
941 -q: Quiet, do not print result.
941 -q: Quiet, do not print result.
942
942
943 -o: return a TimeitResult that can be stored in a variable to inspect
943 -o: return a TimeitResult that can be stored in a variable to inspect
944 the result in more details.
944 the result in more details.
945
945
946
946
947 Examples
947 Examples
948 --------
948 --------
949 ::
949 ::
950
950
951 In [1]: %timeit pass
951 In [1]: %timeit pass
952 10000000 loops, best of 3: 53.3 ns per loop
952 10000000 loops, best of 3: 53.3 ns per loop
953
953
954 In [2]: u = None
954 In [2]: u = None
955
955
956 In [3]: %timeit u is None
956 In [3]: %timeit u is None
957 10000000 loops, best of 3: 184 ns per loop
957 10000000 loops, best of 3: 184 ns per loop
958
958
959 In [4]: %timeit -r 4 u == None
959 In [4]: %timeit -r 4 u == None
960 1000000 loops, best of 4: 242 ns per loop
960 1000000 loops, best of 4: 242 ns per loop
961
961
962 In [5]: import time
962 In [5]: import time
963
963
964 In [6]: %timeit -n1 time.sleep(2)
964 In [6]: %timeit -n1 time.sleep(2)
965 1 loop, best of 3: 2 s per loop
965 1 loop, best of 3: 2 s per loop
966
966
967
967
968 The times reported by %timeit will be slightly higher than those
968 The times reported by %timeit will be slightly higher than those
969 reported by the timeit.py script when variables are accessed. This is
969 reported by the timeit.py script when variables are accessed. This is
970 due to the fact that %timeit executes the statement in the namespace
970 due to the fact that %timeit executes the statement in the namespace
971 of the shell, compared with timeit.py, which uses a single setup
971 of the shell, compared with timeit.py, which uses a single setup
972 statement to import function or create variables. Generally, the bias
972 statement to import function or create variables. Generally, the bias
973 does not matter as long as results from timeit.py are not mixed with
973 does not matter as long as results from timeit.py are not mixed with
974 those from %timeit."""
974 those from %timeit."""
975
975
976 opts, stmt = self.parse_options(line,'n:r:tcp:qo',
976 opts, stmt = self.parse_options(line,'n:r:tcp:qo',
977 posix=False, strict=False)
977 posix=False, strict=False)
978 if stmt == "" and cell is None:
978 if stmt == "" and cell is None:
979 return
979 return
980
980
981 timefunc = timeit.default_timer
981 timefunc = timeit.default_timer
982 number = int(getattr(opts, "n", 0))
982 number = int(getattr(opts, "n", 0))
983 repeat = int(getattr(opts, "r", timeit.default_repeat))
983 repeat = int(getattr(opts, "r", timeit.default_repeat))
984 precision = int(getattr(opts, "p", 3))
984 precision = int(getattr(opts, "p", 3))
985 quiet = 'q' in opts
985 quiet = 'q' in opts
986 return_result = 'o' in opts
986 return_result = 'o' in opts
987 if hasattr(opts, "t"):
987 if hasattr(opts, "t"):
988 timefunc = time.time
988 timefunc = time.time
989 if hasattr(opts, "c"):
989 if hasattr(opts, "c"):
990 timefunc = clock
990 timefunc = clock
991
991
992 timer = Timer(timer=timefunc)
992 timer = Timer(timer=timefunc)
993 # this code has tight coupling to the inner workings of timeit.Timer,
993 # this code has tight coupling to the inner workings of timeit.Timer,
994 # but is there a better way to achieve that the code stmt has access
994 # but is there a better way to achieve that the code stmt has access
995 # to the shell namespace?
995 # to the shell namespace?
996 transform = self.shell.input_splitter.transform_cell
996 transform = self.shell.input_splitter.transform_cell
997
997
998 if cell is None:
998 if cell is None:
999 # called as line magic
999 # called as line magic
1000 ast_setup = self.shell.compile.ast_parse("pass")
1000 ast_setup = self.shell.compile.ast_parse("pass")
1001 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1001 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1002 else:
1002 else:
1003 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1003 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1004 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1004 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1005
1005
1006 ast_setup = self.shell.transform_ast(ast_setup)
1006 ast_setup = self.shell.transform_ast(ast_setup)
1007 ast_stmt = self.shell.transform_ast(ast_stmt)
1007 ast_stmt = self.shell.transform_ast(ast_stmt)
1008
1008
1009 # This codestring is taken from timeit.template - we fill it in as an
1009 # This codestring is taken from timeit.template - we fill it in as an
1010 # AST, so that we can apply our AST transformations to the user code
1010 # AST, so that we can apply our AST transformations to the user code
1011 # without affecting the timing code.
1011 # without affecting the timing code.
1012 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1012 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1013 ' setup\n'
1013 ' setup\n'
1014 ' _t0 = _timer()\n'
1014 ' _t0 = _timer()\n'
1015 ' for _i in _it:\n'
1015 ' for _i in _it:\n'
1016 ' stmt\n'
1016 ' stmt\n'
1017 ' _t1 = _timer()\n'
1017 ' _t1 = _timer()\n'
1018 ' return _t1 - _t0\n')
1018 ' return _t1 - _t0\n')
1019
1019
1020 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1020 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1021 timeit_ast = ast.fix_missing_locations(timeit_ast)
1021 timeit_ast = ast.fix_missing_locations(timeit_ast)
1022
1022
1023 # Track compilation time so it can be reported if too long
1023 # Track compilation time so it can be reported if too long
1024 # Minimum time above which compilation time will be reported
1024 # Minimum time above which compilation time will be reported
1025 tc_min = 0.1
1025 tc_min = 0.1
1026
1026
1027 t0 = clock()
1027 t0 = clock()
1028 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1028 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1029 tc = clock()-t0
1029 tc = clock()-t0
1030
1030
1031 ns = {}
1031 ns = {}
1032 exec(code, self.shell.user_ns, ns)
1032 exec(code, self.shell.user_ns, ns)
1033 timer.inner = ns["inner"]
1033 timer.inner = ns["inner"]
1034
1034
1035 # This is used to check if there is a huge difference between the
1035 # This is used to check if there is a huge difference between the
1036 # best and worst timings.
1036 # best and worst timings.
1037 # Issue: https://github.com/ipython/ipython/issues/6471
1037 # Issue: https://github.com/ipython/ipython/issues/6471
1038 worst_tuning = 0
1038 worst_tuning = 0
1039 if number == 0:
1039 if number == 0:
1040 # determine number so that 0.2 <= total time < 2.0
1040 # determine number so that 0.2 <= total time < 2.0
1041 number = 1
1041 number = 1
1042 for _ in range(1, 10):
1042 for _ in range(1, 10):
1043 time_number = timer.timeit(number)
1043 time_number = timer.timeit(number)
1044 worst_tuning = max(worst_tuning, time_number / number)
1044 worst_tuning = max(worst_tuning, time_number / number)
1045 if time_number >= 0.2:
1045 if time_number >= 0.2:
1046 break
1046 break
1047 number *= 10
1047 number *= 10
1048 all_runs = timer.repeat(repeat, number)
1048 all_runs = timer.repeat(repeat, number)
1049 best = min(all_runs) / number
1049 best = min(all_runs) / number
1050
1050
1051 worst = max(all_runs) / number
1051 worst = max(all_runs) / number
1052 if worst_tuning:
1052 if worst_tuning:
1053 worst = max(worst, worst_tuning)
1053 worst = max(worst, worst_tuning)
1054
1054
1055 if not quiet :
1055 if not quiet :
1056 # Check best timing is greater than zero to avoid a
1056 # Check best timing is greater than zero to avoid a
1057 # ZeroDivisionError.
1057 # ZeroDivisionError.
1058 # In cases where the slowest timing is lesser than a micosecond
1058 # In cases where the slowest timing is lesser than a micosecond
1059 # we assume that it does not really matter if the fastest
1059 # we assume that it does not really matter if the fastest
1060 # timing is 4 times faster than the slowest timing or not.
1060 # timing is 4 times faster than the slowest timing or not.
1061 if worst > 4 * best and best > 0 and worst > 1e-6:
1061 if worst > 4 * best and best > 0 and worst > 1e-6:
1062 print("The slowest run took %0.2f times longer than the "
1062 print("The slowest run took %0.2f times longer than the "
1063 "fastest. This could mean that an intermediate result "
1063 "fastest. This could mean that an intermediate result "
1064 "is being cached." % (worst / best))
1064 "is being cached." % (worst / best))
1065 if number == 1: # No s at "loops" if only one loop
1065 if number == 1: # No s at "loops" if only one loop
1066 print(u"%d loop, best of %d: %s per loop" % (number, repeat,
1066 print(u"%d loop, best of %d: %s per loop" % (number, repeat,
1067 _format_time(best, precision)))
1067 _format_time(best, precision)))
1068 else:
1068 else:
1069 print(u"%d loops, best of %d: %s per loop" % (number, repeat,
1069 print(u"%d loops, best of %d: %s per loop" % (number, repeat,
1070 _format_time(best, precision)))
1070 _format_time(best, precision)))
1071 if tc > tc_min:
1071 if tc > tc_min:
1072 print("Compiler time: %.2f s" % tc)
1072 print("Compiler time: %.2f s" % tc)
1073 if return_result:
1073 if return_result:
1074 return TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1074 return TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1075
1075
1076 @skip_doctest
1076 @skip_doctest
1077 @needs_local_scope
1077 @needs_local_scope
1078 @line_cell_magic
1078 @line_cell_magic
1079 def time(self,line='', cell=None, local_ns=None):
1079 def time(self,line='', cell=None, local_ns=None):
1080 """Time execution of a Python statement or expression.
1080 """Time execution of a Python statement or expression.
1081
1081
1082 The CPU and wall clock times are printed, and the value of the
1082 The CPU and wall clock times are printed, and the value of the
1083 expression (if any) is returned. Note that under Win32, system time
1083 expression (if any) is returned. Note that under Win32, system time
1084 is always reported as 0, since it can not be measured.
1084 is always reported as 0, since it can not be measured.
1085
1085
1086 This function can be used both as a line and cell magic:
1086 This function can be used both as a line and cell magic:
1087
1087
1088 - In line mode you can time a single-line statement (though multiple
1088 - In line mode you can time a single-line statement (though multiple
1089 ones can be chained with using semicolons).
1089 ones can be chained with using semicolons).
1090
1090
1091 - In cell mode, you can time the cell body (a directly
1091 - In cell mode, you can time the cell body (a directly
1092 following statement raises an error).
1092 following statement raises an error).
1093
1093
1094 This function provides very basic timing functionality. Use the timeit
1094 This function provides very basic timing functionality. Use the timeit
1095 magic for more control over the measurement.
1095 magic for more control over the measurement.
1096
1096
1097 Examples
1097 Examples
1098 --------
1098 --------
1099 ::
1099 ::
1100
1100
1101 In [1]: %time 2**128
1101 In [1]: %time 2**128
1102 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1102 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1103 Wall time: 0.00
1103 Wall time: 0.00
1104 Out[1]: 340282366920938463463374607431768211456L
1104 Out[1]: 340282366920938463463374607431768211456L
1105
1105
1106 In [2]: n = 1000000
1106 In [2]: n = 1000000
1107
1107
1108 In [3]: %time sum(range(n))
1108 In [3]: %time sum(range(n))
1109 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1109 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1110 Wall time: 1.37
1110 Wall time: 1.37
1111 Out[3]: 499999500000L
1111 Out[3]: 499999500000L
1112
1112
1113 In [4]: %time print 'hello world'
1113 In [4]: %time print 'hello world'
1114 hello world
1114 hello world
1115 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1115 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1116 Wall time: 0.00
1116 Wall time: 0.00
1117
1117
1118 Note that the time needed by Python to compile the given expression
1118 Note that the time needed by Python to compile the given expression
1119 will be reported if it is more than 0.1s. In this example, the
1119 will be reported if it is more than 0.1s. In this example, the
1120 actual exponentiation is done by Python at compilation time, so while
1120 actual exponentiation is done by Python at compilation time, so while
1121 the expression can take a noticeable amount of time to compute, that
1121 the expression can take a noticeable amount of time to compute, that
1122 time is purely due to the compilation:
1122 time is purely due to the compilation:
1123
1123
1124 In [5]: %time 3**9999;
1124 In [5]: %time 3**9999;
1125 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1125 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1126 Wall time: 0.00 s
1126 Wall time: 0.00 s
1127
1127
1128 In [6]: %time 3**999999;
1128 In [6]: %time 3**999999;
1129 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1129 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1130 Wall time: 0.00 s
1130 Wall time: 0.00 s
1131 Compiler : 0.78 s
1131 Compiler : 0.78 s
1132 """
1132 """
1133
1133
1134 # fail immediately if the given expression can't be compiled
1134 # fail immediately if the given expression can't be compiled
1135
1135
1136 if line and cell:
1136 if line and cell:
1137 raise UsageError("Can't use statement directly after '%%time'!")
1137 raise UsageError("Can't use statement directly after '%%time'!")
1138
1138
1139 if cell:
1139 if cell:
1140 expr = self.shell.input_transformer_manager.transform_cell(cell)
1140 expr = self.shell.input_transformer_manager.transform_cell(cell)
1141 else:
1141 else:
1142 expr = self.shell.input_transformer_manager.transform_cell(line)
1142 expr = self.shell.input_transformer_manager.transform_cell(line)
1143
1143
1144 # Minimum time above which parse time will be reported
1144 # Minimum time above which parse time will be reported
1145 tp_min = 0.1
1145 tp_min = 0.1
1146
1146
1147 t0 = clock()
1147 t0 = clock()
1148 expr_ast = self.shell.compile.ast_parse(expr)
1148 expr_ast = self.shell.compile.ast_parse(expr)
1149 tp = clock()-t0
1149 tp = clock()-t0
1150
1150
1151 # Apply AST transformations
1151 # Apply AST transformations
1152 expr_ast = self.shell.transform_ast(expr_ast)
1152 expr_ast = self.shell.transform_ast(expr_ast)
1153
1153
1154 # Minimum time above which compilation time will be reported
1154 # Minimum time above which compilation time will be reported
1155 tc_min = 0.1
1155 tc_min = 0.1
1156
1156
1157 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1157 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1158 mode = 'eval'
1158 mode = 'eval'
1159 source = '<timed eval>'
1159 source = '<timed eval>'
1160 expr_ast = ast.Expression(expr_ast.body[0].value)
1160 expr_ast = ast.Expression(expr_ast.body[0].value)
1161 else:
1161 else:
1162 mode = 'exec'
1162 mode = 'exec'
1163 source = '<timed exec>'
1163 source = '<timed exec>'
1164 t0 = clock()
1164 t0 = clock()
1165 code = self.shell.compile(expr_ast, source, mode)
1165 code = self.shell.compile(expr_ast, source, mode)
1166 tc = clock()-t0
1166 tc = clock()-t0
1167
1167
1168 # skew measurement as little as possible
1168 # skew measurement as little as possible
1169 glob = self.shell.user_ns
1169 glob = self.shell.user_ns
1170 wtime = time.time
1170 wtime = time.time
1171 # time execution
1171 # time execution
1172 wall_st = wtime()
1172 wall_st = wtime()
1173 if mode=='eval':
1173 if mode=='eval':
1174 st = clock2()
1174 st = clock2()
1175 out = eval(code, glob, local_ns)
1175 out = eval(code, glob, local_ns)
1176 end = clock2()
1176 end = clock2()
1177 else:
1177 else:
1178 st = clock2()
1178 st = clock2()
1179 exec(code, glob, local_ns)
1179 exec(code, glob, local_ns)
1180 end = clock2()
1180 end = clock2()
1181 out = None
1181 out = None
1182 wall_end = wtime()
1182 wall_end = wtime()
1183 # Compute actual times and report
1183 # Compute actual times and report
1184 wall_time = wall_end-wall_st
1184 wall_time = wall_end-wall_st
1185 cpu_user = end[0]-st[0]
1185 cpu_user = end[0]-st[0]
1186 cpu_sys = end[1]-st[1]
1186 cpu_sys = end[1]-st[1]
1187 cpu_tot = cpu_user+cpu_sys
1187 cpu_tot = cpu_user+cpu_sys
1188 # On windows cpu_sys is always zero, so no new information to the next print
1188 # On windows cpu_sys is always zero, so no new information to the next print
1189 if sys.platform != 'win32':
1189 if sys.platform != 'win32':
1190 print("CPU times: user %s, sys: %s, total: %s" % \
1190 print("CPU times: user %s, sys: %s, total: %s" % \
1191 (_format_time(cpu_user),_format_time(cpu_sys),_format_time(cpu_tot)))
1191 (_format_time(cpu_user),_format_time(cpu_sys),_format_time(cpu_tot)))
1192 print("Wall time: %s" % _format_time(wall_time))
1192 print("Wall time: %s" % _format_time(wall_time))
1193 if tc > tc_min:
1193 if tc > tc_min:
1194 print("Compiler : %s" % _format_time(tc))
1194 print("Compiler : %s" % _format_time(tc))
1195 if tp > tp_min:
1195 if tp > tp_min:
1196 print("Parser : %s" % _format_time(tp))
1196 print("Parser : %s" % _format_time(tp))
1197 return out
1197 return out
1198
1198
1199 @skip_doctest
1199 @skip_doctest
1200 @line_magic
1200 @line_magic
1201 def macro(self, parameter_s=''):
1201 def macro(self, parameter_s=''):
1202 """Define a macro for future re-execution. It accepts ranges of history,
1202 """Define a macro for future re-execution. It accepts ranges of history,
1203 filenames or string objects.
1203 filenames or string objects.
1204
1204
1205 Usage:\\
1205 Usage:\\
1206 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1206 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1207
1207
1208 Options:
1208 Options:
1209
1209
1210 -r: use 'raw' input. By default, the 'processed' history is used,
1210 -r: use 'raw' input. By default, the 'processed' history is used,
1211 so that magics are loaded in their transformed version to valid
1211 so that magics are loaded in their transformed version to valid
1212 Python. If this option is given, the raw input as typed at the
1212 Python. If this option is given, the raw input as typed at the
1213 command line is used instead.
1213 command line is used instead.
1214
1214
1215 -q: quiet macro definition. By default, a tag line is printed
1215 -q: quiet macro definition. By default, a tag line is printed
1216 to indicate the macro has been created, and then the contents of
1216 to indicate the macro has been created, and then the contents of
1217 the macro are printed. If this option is given, then no printout
1217 the macro are printed. If this option is given, then no printout
1218 is produced once the macro is created.
1218 is produced once the macro is created.
1219
1219
1220 This will define a global variable called `name` which is a string
1220 This will define a global variable called `name` which is a string
1221 made of joining the slices and lines you specify (n1,n2,... numbers
1221 made of joining the slices and lines you specify (n1,n2,... numbers
1222 above) from your input history into a single string. This variable
1222 above) from your input history into a single string. This variable
1223 acts like an automatic function which re-executes those lines as if
1223 acts like an automatic function which re-executes those lines as if
1224 you had typed them. You just type 'name' at the prompt and the code
1224 you had typed them. You just type 'name' at the prompt and the code
1225 executes.
1225 executes.
1226
1226
1227 The syntax for indicating input ranges is described in %history.
1227 The syntax for indicating input ranges is described in %history.
1228
1228
1229 Note: as a 'hidden' feature, you can also use traditional python slice
1229 Note: as a 'hidden' feature, you can also use traditional python slice
1230 notation, where N:M means numbers N through M-1.
1230 notation, where N:M means numbers N through M-1.
1231
1231
1232 For example, if your history contains (print using %hist -n )::
1232 For example, if your history contains (print using %hist -n )::
1233
1233
1234 44: x=1
1234 44: x=1
1235 45: y=3
1235 45: y=3
1236 46: z=x+y
1236 46: z=x+y
1237 47: print x
1237 47: print x
1238 48: a=5
1238 48: a=5
1239 49: print 'x',x,'y',y
1239 49: print 'x',x,'y',y
1240
1240
1241 you can create a macro with lines 44 through 47 (included) and line 49
1241 you can create a macro with lines 44 through 47 (included) and line 49
1242 called my_macro with::
1242 called my_macro with::
1243
1243
1244 In [55]: %macro my_macro 44-47 49
1244 In [55]: %macro my_macro 44-47 49
1245
1245
1246 Now, typing `my_macro` (without quotes) will re-execute all this code
1246 Now, typing `my_macro` (without quotes) will re-execute all this code
1247 in one pass.
1247 in one pass.
1248
1248
1249 You don't need to give the line-numbers in order, and any given line
1249 You don't need to give the line-numbers in order, and any given line
1250 number can appear multiple times. You can assemble macros with any
1250 number can appear multiple times. You can assemble macros with any
1251 lines from your input history in any order.
1251 lines from your input history in any order.
1252
1252
1253 The macro is a simple object which holds its value in an attribute,
1253 The macro is a simple object which holds its value in an attribute,
1254 but IPython's display system checks for macros and executes them as
1254 but IPython's display system checks for macros and executes them as
1255 code instead of printing them when you type their name.
1255 code instead of printing them when you type their name.
1256
1256
1257 You can view a macro's contents by explicitly printing it with::
1257 You can view a macro's contents by explicitly printing it with::
1258
1258
1259 print macro_name
1259 print macro_name
1260
1260
1261 """
1261 """
1262 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1262 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1263 if not args: # List existing macros
1263 if not args: # List existing macros
1264 return sorted(k for k,v in iteritems(self.shell.user_ns) if\
1264 return sorted(k for k,v in iteritems(self.shell.user_ns) if\
1265 isinstance(v, Macro))
1265 isinstance(v, Macro))
1266 if len(args) == 1:
1266 if len(args) == 1:
1267 raise UsageError(
1267 raise UsageError(
1268 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1268 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1269 name, codefrom = args[0], " ".join(args[1:])
1269 name, codefrom = args[0], " ".join(args[1:])
1270
1270
1271 #print 'rng',ranges # dbg
1271 #print 'rng',ranges # dbg
1272 try:
1272 try:
1273 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1273 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1274 except (ValueError, TypeError) as e:
1274 except (ValueError, TypeError) as e:
1275 print(e.args[0])
1275 print(e.args[0])
1276 return
1276 return
1277 macro = Macro(lines)
1277 macro = Macro(lines)
1278 self.shell.define_macro(name, macro)
1278 self.shell.define_macro(name, macro)
1279 if not ( 'q' in opts) :
1279 if not ( 'q' in opts) :
1280 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1280 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1281 print('=== Macro contents: ===')
1281 print('=== Macro contents: ===')
1282 print(macro, end=' ')
1282 print(macro, end=' ')
1283
1283
1284 @magic_arguments.magic_arguments()
1284 @magic_arguments.magic_arguments()
1285 @magic_arguments.argument('output', type=str, default='', nargs='?',
1285 @magic_arguments.argument('output', type=str, default='', nargs='?',
1286 help="""The name of the variable in which to store output.
1286 help="""The name of the variable in which to store output.
1287 This is a utils.io.CapturedIO object with stdout/err attributes
1287 This is a utils.io.CapturedIO object with stdout/err attributes
1288 for the text of the captured output.
1288 for the text of the captured output.
1289
1289
1290 CapturedOutput also has a show() method for displaying the output,
1290 CapturedOutput also has a show() method for displaying the output,
1291 and __call__ as well, so you can use that to quickly display the
1291 and __call__ as well, so you can use that to quickly display the
1292 output.
1292 output.
1293
1293
1294 If unspecified, captured output is discarded.
1294 If unspecified, captured output is discarded.
1295 """
1295 """
1296 )
1296 )
1297 @magic_arguments.argument('--no-stderr', action="store_true",
1297 @magic_arguments.argument('--no-stderr', action="store_true",
1298 help="""Don't capture stderr."""
1298 help="""Don't capture stderr."""
1299 )
1299 )
1300 @magic_arguments.argument('--no-stdout', action="store_true",
1300 @magic_arguments.argument('--no-stdout', action="store_true",
1301 help="""Don't capture stdout."""
1301 help="""Don't capture stdout."""
1302 )
1302 )
1303 @magic_arguments.argument('--no-display', action="store_true",
1303 @magic_arguments.argument('--no-display', action="store_true",
1304 help="""Don't capture IPython's rich display."""
1304 help="""Don't capture IPython's rich display."""
1305 )
1305 )
1306 @cell_magic
1306 @cell_magic
1307 def capture(self, line, cell):
1307 def capture(self, line, cell):
1308 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1308 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1309 args = magic_arguments.parse_argstring(self.capture, line)
1309 args = magic_arguments.parse_argstring(self.capture, line)
1310 out = not args.no_stdout
1310 out = not args.no_stdout
1311 err = not args.no_stderr
1311 err = not args.no_stderr
1312 disp = not args.no_display
1312 disp = not args.no_display
1313 with capture_output(out, err, disp) as io:
1313 with capture_output(out, err, disp) as io:
1314 self.shell.run_cell(cell)
1314 self.shell.run_cell(cell)
1315 if args.output:
1315 if args.output:
1316 self.shell.user_ns[args.output] = io
1316 self.shell.user_ns[args.output] = io
1317
1317
1318 def parse_breakpoint(text, current_file):
1318 def parse_breakpoint(text, current_file):
1319 '''Returns (file, line) for file:line and (current_file, line) for line'''
1319 '''Returns (file, line) for file:line and (current_file, line) for line'''
1320 colon = text.find(':')
1320 colon = text.find(':')
1321 if colon == -1:
1321 if colon == -1:
1322 return current_file, int(text)
1322 return current_file, int(text)
1323 else:
1323 else:
1324 return text[:colon], int(text[colon+1:])
1324 return text[:colon], int(text[colon+1:])
1325
1325
1326 def _format_time(timespan, precision=3):
1326 def _format_time(timespan, precision=3):
1327 """Formats the timespan in a human readable form"""
1327 """Formats the timespan in a human readable form"""
1328 import math
1328 import math
1329
1329
1330 if timespan >= 60.0:
1330 if timespan >= 60.0:
1331 # we have more than a minute, format that in a human readable form
1331 # we have more than a minute, format that in a human readable form
1332 # Idea from http://snipplr.com/view/5713/
1332 # Idea from http://snipplr.com/view/5713/
1333 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1333 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1334 time = []
1334 time = []
1335 leftover = timespan
1335 leftover = timespan
1336 for suffix, length in parts:
1336 for suffix, length in parts:
1337 value = int(leftover / length)
1337 value = int(leftover / length)
1338 if value > 0:
1338 if value > 0:
1339 leftover = leftover % length
1339 leftover = leftover % length
1340 time.append(u'%s%s' % (str(value), suffix))
1340 time.append(u'%s%s' % (str(value), suffix))
1341 if leftover < 1:
1341 if leftover < 1:
1342 break
1342 break
1343 return " ".join(time)
1343 return " ".join(time)
1344
1344
1345
1345
1346 # Unfortunately the unicode 'micro' symbol can cause problems in
1346 # Unfortunately the unicode 'micro' symbol can cause problems in
1347 # certain terminals.
1347 # certain terminals.
1348 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1348 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1349 # Try to prevent crashes by being more secure than it needs to
1349 # Try to prevent crashes by being more secure than it needs to
1350 # E.g. eclipse is able to print a µ, but has no sys.stdout.encoding set.
1350 # E.g. eclipse is able to print a µ, but has no sys.stdout.encoding set.
1351 units = [u"s", u"ms",u'us',"ns"] # the save value
1351 units = [u"s", u"ms",u'us',"ns"] # the save value
1352 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1352 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1353 try:
1353 try:
1354 u'\xb5'.encode(sys.stdout.encoding)
1354 u'\xb5'.encode(sys.stdout.encoding)
1355 units = [u"s", u"ms",u'\xb5s',"ns"]
1355 units = [u"s", u"ms",u'\xb5s',"ns"]
1356 except:
1356 except:
1357 pass
1357 pass
1358 scaling = [1, 1e3, 1e6, 1e9]
1358 scaling = [1, 1e3, 1e6, 1e9]
1359
1359
1360 if timespan > 0.0:
1360 if timespan > 0.0:
1361 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1361 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1362 else:
1362 else:
1363 order = 3
1363 order = 3
1364 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
1364 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
General Comments 0
You need to be logged in to leave comments. Login now