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