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