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