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