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