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
23import signal
24from typing import Dict, Any
25from ast import (
26 Assign,
27 Call,
28 Expr,
29 Load,
30 Module,
31 Name,
32 NodeTransformer,
33 Store,
34 parse,
35 unparse,
36)
37from io import StringIO
38from logging import error
39from pathlib import Path
40from pdb import Restart
41from textwrap import dedent, indent
42from warnings import warn
44from IPython.core import magic_arguments, oinspect, page
45from IPython.core.displayhook import DisplayHook
46from IPython.core.error import UsageError
47from IPython.core.macro import Macro
48from IPython.core.magic import (
49 Magics,
50 cell_magic,
51 line_cell_magic,
52 line_magic,
53 magics_class,
54 needs_local_scope,
55 no_var_expand,
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 # TODO: port to magic_arguments as currently this is duplicated in IPCompleter._extract_code
320 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
321 list_all=True, posix=False)
322 if cell is not None:
323 arg_str += '\n' + cell
324 arg_str = self.shell.transform_cell(arg_str)
325 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
327 def _run_with_profiler(self, code, opts, namespace):
328 """
329 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
331 Parameters
332 ----------
333 code : str
334 Code to be executed.
335 opts : Struct
336 Options parsed by `self.parse_options`.
337 namespace : dict
338 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
340 """
342 # Fill default values for unspecified options:
343 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
345 prof = profile.Profile()
346 try:
347 prof = prof.runctx(code, namespace, namespace)
348 sys_exit = ''
349 except SystemExit:
350 sys_exit = """*** SystemExit exception caught in code being profiled."""
352 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
354 lims = opts.l
355 if lims:
356 lims = [] # rebuild lims with ints/floats/strings
357 for lim in opts.l:
358 try:
359 lims.append(int(lim))
360 except ValueError:
361 try:
362 lims.append(float(lim))
363 except ValueError:
364 lims.append(lim)
366 # Trap output.
367 stdout_trap = StringIO()
368 stats_stream = stats.stream
369 try:
370 stats.stream = stdout_trap
371 stats.print_stats(*lims)
372 finally:
373 stats.stream = stats_stream
375 output = stdout_trap.getvalue()
376 output = output.rstrip()
378 if 'q' not in opts:
379 page.page(output)
380 print(sys_exit, end=' ')
382 dump_file = opts.D[0]
383 text_file = opts.T[0]
384 if dump_file:
385 prof.dump_stats(dump_file)
386 print(
387 f"\n*** Profile stats marshalled to file {repr(dump_file)}.{sys_exit}"
388 )
389 if text_file:
390 pfile = Path(text_file)
391 pfile.touch(exist_ok=True)
392 pfile.write_text(output, encoding="utf-8")
394 print(
395 f"\n*** Profile printout saved to text file {repr(text_file)}.{sys_exit}"
396 )
398 if 'r' in opts:
399 return stats
401 return None
403 @line_magic
404 def pdb(self, parameter_s=''):
405 """Control the automatic calling of the pdb interactive debugger.
407 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
408 argument it works as a toggle.
410 When an exception is triggered, IPython can optionally call the
411 interactive pdb debugger after the traceback printout. %pdb toggles
412 this feature on and off.
414 The initial state of this feature is set in your configuration
415 file (the option is ``InteractiveShell.pdb``).
417 If you want to just activate the debugger AFTER an exception has fired,
418 without having to type '%pdb on' and rerunning your code, you can use
419 the %debug magic."""
421 par = parameter_s.strip().lower()
423 new_pdb: bool
425 if par:
426 try:
427 new_pdb = {"off": False, "0": False, "on": True, "1": True}[par]
428 except KeyError:
429 print ('Incorrect argument. Use on/1, off/0, '
430 'or nothing for a toggle.')
431 return
432 else:
433 # toggle
434 new_pdb = not self.shell.call_pdb
436 # set on the shell
437 self.shell.call_pdb = new_pdb
438 print("Automatic pdb calling has been turned", "ON" if new_pdb else "OFF")
440 @magic_arguments.magic_arguments()
441 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
442 help="""
443 Set break point at LINE in FILE.
444 """
445 )
446 @magic_arguments.kwds(
447 epilog="""
448 Any remaining arguments will be treated as code to run in the debugger.
449 """
450 )
451 @no_var_expand
452 @line_cell_magic
453 @needs_local_scope
454 def debug(self, line="", cell=None, local_ns=None):
455 """Activate the interactive debugger.
457 This magic command support two ways of activating debugger.
458 One is to activate debugger before executing code. This way, you
459 can set a break point, to step through the code from the point.
460 You can use this mode by giving statements to execute and optionally
461 a breakpoint.
463 The other one is to activate debugger in post-mortem mode. You can
464 activate this mode simply running %debug without any argument.
465 If an exception has just occurred, this lets you inspect its stack
466 frames interactively. Note that this will always work only on the last
467 traceback that occurred, so you must call this quickly after an
468 exception that you wish to inspect has fired, because if another one
469 occurs, it clobbers the previous one.
471 If you want IPython to automatically do this on every exception, see
472 the %pdb magic for more details.
474 .. versionchanged:: 7.3
475 When running code, user variables are no longer expanded,
476 the magic line is always left unmodified.
478 """
479 args, extra = magic_arguments.parse_argstring(self.debug, line, partial=True)
481 if not (args.breakpoint or extra or cell):
482 self._debug_post_mortem()
483 elif not (args.breakpoint or cell):
484 # If there is no breakpoints, the line is just code to execute
485 self._debug_exec(line, None, local_ns)
486 else:
487 # Here we try to reconstruct the code from the output of
488 # parse_argstring. This might not work if the code has spaces
489 # For example this fails for `print("a b")`
490 code = " ".join(extra)
491 if cell:
492 code += "\n" + cell
493 self._debug_exec(code, args.breakpoint, local_ns)
495 def _debug_post_mortem(self):
496 self.shell.debugger(force=True)
498 def _debug_exec(self, code, breakpoint, local_ns=None):
499 if breakpoint:
500 (filename, bp_line) = breakpoint.rsplit(':', 1)
501 bp_line = int(bp_line)
502 else:
503 (filename, bp_line) = (None, None)
504 self._run_with_debugger(
505 code, self.shell.user_ns, filename, bp_line, local_ns=local_ns
506 )
508 @line_magic
509 def tb(self, s):
510 """Print the last traceback.
512 Optionally, specify an exception reporting mode, tuning the
513 verbosity of the traceback. By default the currently-active exception
514 mode is used. See %xmode for changing exception reporting modes.
516 Valid modes: Plain, Context, Verbose, and Minimal.
517 """
518 interactive_tb = self.shell.InteractiveTB
519 if s:
520 # Switch exception reporting mode for this one call.
521 # Ensure it is switched back.
522 def xmode_switch_err(name):
523 warn('Error changing %s exception modes.\n%s' %
524 (name,sys.exc_info()[1]))
526 new_mode = s.strip().capitalize()
527 original_mode = interactive_tb.mode
528 try:
529 try:
530 interactive_tb.set_mode(mode=new_mode)
531 except Exception:
532 xmode_switch_err('user')
533 else:
534 self.shell.showtraceback()
535 finally:
536 interactive_tb.set_mode(mode=original_mode)
537 else:
538 self.shell.showtraceback()
540 @skip_doctest
541 @line_magic
542 def run(self, parameter_s='', runner=None,
543 file_finder=get_py_filename):
544 """Run the named file inside IPython as a program.
546 Usage::
548 %run [-n -i -e -G]
549 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
550 ( -m mod | filename ) [args]
552 The filename argument should be either a pure Python script (with
553 extension ``.py``), or a file with custom IPython syntax (such as
554 magics). If the latter, the file can be either a script with ``.ipy``
555 extension, or a Jupyter notebook with ``.ipynb`` extension. When running
556 a Jupyter notebook, the output from print statements and other
557 displayed objects will appear in the terminal (even matplotlib figures
558 will open, if a terminal-compliant backend is being used). Note that,
559 at the system command line, the ``jupyter run`` command offers similar
560 functionality for executing notebooks (albeit currently with some
561 differences in supported options).
563 Parameters after the filename are passed as command-line arguments to
564 the program (put in sys.argv). Then, control returns to IPython's
565 prompt.
567 This is similar to running at a system prompt ``python file args``,
568 but with the advantage of giving you IPython's tracebacks, and of
569 loading all variables into your interactive namespace for further use
570 (unless -p is used, see below).
572 The file is executed in a namespace initially consisting only of
573 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
574 sees its environment as if it were being run as a stand-alone program
575 (except for sharing global objects such as previously imported
576 modules). But after execution, the IPython interactive namespace gets
577 updated with all variables defined in the program (except for ``__name__``
578 and ``sys.argv``). This allows for very convenient loading of code for
579 interactive work, while giving each program a 'clean sheet' to run in.
581 Arguments are expanded using shell-like glob match. Patterns
582 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
583 tilde '~' will be expanded into user's home directory. Unlike
584 real shells, quotation does not suppress expansions. Use
585 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
586 To completely disable these expansions, you can use -G flag.
588 On Windows systems, the use of single quotes `'` when specifying
589 a file is not supported. Use double quotes `"`.
591 Options:
593 -n
594 __name__ is NOT set to '__main__', but to the running file's name
595 without extension (as python does under import). This allows running
596 scripts and reloading the definitions in them without calling code
597 protected by an ``if __name__ == "__main__"`` clause.
599 -i
600 run the file in IPython's namespace instead of an empty one. This
601 is useful if you are experimenting with code written in a text editor
602 which depends on variables defined interactively.
604 -e
605 ignore sys.exit() calls or SystemExit exceptions in the script
606 being run. This is particularly useful if IPython is being used to
607 run unittests, which always exit with a sys.exit() call. In such
608 cases you are interested in the output of the test results, not in
609 seeing a traceback of the unittest module.
611 -t
612 print timing information at the end of the run. IPython will give
613 you an estimated CPU time consumption for your script, which under
614 Unix uses the resource module to avoid the wraparound problems of
615 time.clock(). Under Unix, an estimate of time spent on system tasks
616 is also given (for Windows platforms this is reported as 0.0).
618 If -t is given, an additional ``-N<N>`` option can be given, where <N>
619 must be an integer indicating how many times you want the script to
620 run. The final timing report will include total and per run results.
622 For example (testing the script myscript.py)::
624 In [1]: run -t myscript
626 IPython CPU timings (estimated):
627 User : 0.19597 s.
628 System: 0.0 s.
630 In [2]: run -t -N5 myscript
632 IPython CPU timings (estimated):
633 Total runs performed: 5
634 Times : Total Per run
635 User : 0.910862 s, 0.1821724 s.
636 System: 0.0 s, 0.0 s.
638 -d
639 run your program under the control of pdb, the Python debugger.
640 This allows you to execute your program step by step, watch variables,
641 etc. Internally, what IPython does is similar to calling::
643 pdb.run('execfile("YOURFILENAME")')
645 with a breakpoint set on line 1 of your file. You can change the line
646 number for this automatic breakpoint to be <N> by using the -bN option
647 (where N must be an integer). For example::
649 %run -d -b40 myscript
651 will set the first breakpoint at line 40 in myscript.py. Note that
652 the first breakpoint must be set on a line which actually does
653 something (not a comment or docstring) for it to stop execution.
655 Or you can specify a breakpoint in a different file::
657 %run -d -b myotherfile.py:20 myscript
659 When the pdb debugger starts, you will see a (Pdb) prompt. You must
660 first enter 'c' (without quotes) to start execution up to the first
661 breakpoint.
663 Entering 'help' gives information about the use of the debugger. You
664 can easily see pdb's full documentation with "import pdb;pdb.help()"
665 at a prompt.
667 -p
668 run program under the control of the Python profiler module (which
669 prints a detailed report of execution times, function calls, etc).
671 You can pass other options after -p which affect the behavior of the
672 profiler itself. See the docs for %prun for details.
674 In this mode, the program's variables do NOT propagate back to the
675 IPython interactive namespace (because they remain in the namespace
676 where the profiler executes them).
678 Internally this triggers a call to %prun, see its documentation for
679 details on the options available specifically for profiling.
681 There is one special usage for which the text above doesn't apply:
682 if the filename ends with .ipy[nb], the file is run as ipython script,
683 just as if the commands were written on IPython prompt.
685 -m
686 specify module name to load instead of script path. Similar to
687 the -m option for the python interpreter. Use this option last if you
688 want to combine with other %run options. Unlike the python interpreter
689 only source modules are allowed no .pyc or .pyo files.
690 For example::
692 %run -m example
694 will run the example module.
696 -G
697 disable shell-like glob expansion of arguments.
699 """
701 # Logic to handle issue #3664
702 # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
703 if '-m' in parameter_s and '--' not in parameter_s:
704 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
705 for idx, arg in enumerate(argv):
706 if arg and arg.startswith('-') and arg != '-':
707 if arg == '-m':
708 argv.insert(idx + 2, '--')
709 break
710 else:
711 # Positional arg, break
712 break
713 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
715 # get arguments and set sys.argv for program to be run.
716 opts, arg_lst = self.parse_options(parameter_s,
717 'nidtN:b:pD:l:rs:T:em:G',
718 mode='list', list_all=1)
719 if "m" in opts:
720 modulename = opts["m"][0]
721 modpath = find_mod(modulename)
722 if modpath is None:
723 msg = '%r is not a valid modulename on sys.path'%modulename
724 raise Exception(msg)
725 arg_lst = [modpath] + arg_lst
726 try:
727 fpath = None # initialize to make sure fpath is in scope later
728 fpath = arg_lst[0]
729 filename = file_finder(fpath)
730 except IndexError as e:
731 msg = 'you must provide at least a filename.'
732 raise Exception(msg) from e
733 except IOError as e:
734 try:
735 msg = str(e)
736 except UnicodeError:
737 msg = e.message
738 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
739 warn('For Windows, use double quotes to wrap a filename: %run "mypath\\myfile.py"')
740 raise Exception(msg) from e
741 except TypeError:
742 if fpath in sys.meta_path:
743 filename = ""
744 else:
745 raise
747 if filename.lower().endswith(('.ipy', '.ipynb')):
748 with preserve_keys(self.shell.user_ns, '__file__'):
749 self.shell.user_ns['__file__'] = filename
750 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
751 return
753 # Control the response to exit() calls made by the script being run
754 exit_ignore = 'e' in opts
756 # Make sure that the running script gets a proper sys.argv as if it
757 # were run from a system shell.
758 save_argv = sys.argv # save it for later restoring
760 if 'G' in opts:
761 args = arg_lst[1:]
762 else:
763 # tilde and glob expansion
764 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
766 sys.argv = [filename] + args # put in the proper filename
768 if 'n' in opts:
769 name = Path(filename).stem
770 else:
771 name = '__main__'
773 if 'i' in opts:
774 # Run in user's interactive namespace
775 prog_ns = self.shell.user_ns
776 __name__save = self.shell.user_ns['__name__']
777 prog_ns['__name__'] = name
778 main_mod = self.shell.user_module
780 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
781 # set the __file__ global in the script's namespace
782 # TK: Is this necessary in interactive mode?
783 prog_ns['__file__'] = filename
784 else:
785 # Run in a fresh, empty namespace
787 # The shell MUST hold a reference to prog_ns so after %run
788 # exits, the python deletion mechanism doesn't zero it out
789 # (leaving dangling references). See interactiveshell for details
790 main_mod = self.shell.new_main_mod(filename, name)
791 prog_ns = main_mod.__dict__
793 # pickle fix. See interactiveshell for an explanation. But we need to
794 # make sure that, if we overwrite __main__, we replace it at the end
795 main_mod_name = prog_ns['__name__']
797 if main_mod_name == '__main__':
798 restore_main = sys.modules['__main__']
799 else:
800 restore_main = False
802 # This needs to be undone at the end to prevent holding references to
803 # every single object ever created.
804 sys.modules[main_mod_name] = main_mod
806 if 'p' in opts or 'd' in opts:
807 if 'm' in opts:
808 code = 'run_module(modulename, prog_ns)'
809 code_ns = {
810 'run_module': self.shell.safe_run_module,
811 'prog_ns': prog_ns,
812 'modulename': modulename,
813 }
814 else:
815 if 'd' in opts:
816 # allow exceptions to raise in debug mode
817 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
818 else:
819 code = 'execfile(filename, prog_ns)'
820 code_ns = {
821 'execfile': self.shell.safe_execfile,
822 'prog_ns': prog_ns,
823 'filename': get_py_filename(filename),
824 }
826 try:
827 stats = None
828 if 'p' in opts:
829 stats = self._run_with_profiler(code, opts, code_ns)
830 else:
831 if 'd' in opts:
832 bp_file, bp_line = parse_breakpoint(
833 opts.get('b', ['1'])[0], filename)
834 self._run_with_debugger(
835 code, code_ns, filename, bp_line, bp_file)
836 else:
837 if 'm' in opts:
838 def run():
839 self.shell.safe_run_module(modulename, prog_ns)
840 else:
841 if runner is None:
842 runner = self.default_runner
843 if runner is None:
844 runner = self.shell.safe_execfile
846 def run():
847 runner(filename, prog_ns, prog_ns,
848 exit_ignore=exit_ignore)
850 if 't' in opts:
851 # timed execution
852 try:
853 nruns = int(opts['N'][0])
854 if nruns < 1:
855 error('Number of runs must be >=1')
856 return
857 except (KeyError):
858 nruns = 1
859 self._run_with_timing(run, nruns)
860 else:
861 # regular execution
862 run()
864 if 'i' in opts:
865 self.shell.user_ns['__name__'] = __name__save
866 else:
867 # update IPython interactive namespace
869 # Some forms of read errors on the file may mean the
870 # __name__ key was never set; using pop we don't have to
871 # worry about a possible KeyError.
872 prog_ns.pop('__name__', None)
874 with preserve_keys(self.shell.user_ns, '__file__'):
875 self.shell.user_ns.update(prog_ns)
876 finally:
877 # It's a bit of a mystery why, but __builtins__ can change from
878 # being a module to becoming a dict missing some key data after
879 # %run. As best I can see, this is NOT something IPython is doing
880 # at all, and similar problems have been reported before:
881 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
882 # Since this seems to be done by the interpreter itself, the best
883 # we can do is to at least restore __builtins__ for the user on
884 # exit.
885 self.shell.user_ns['__builtins__'] = builtin_mod
887 # Ensure key global structures are restored
888 sys.argv = save_argv
889 if restore_main:
890 sys.modules['__main__'] = restore_main
891 if '__mp_main__' in sys.modules:
892 sys.modules['__mp_main__'] = restore_main
893 else:
894 # Remove from sys.modules the reference to main_mod we'd
895 # added. Otherwise it will trap references to objects
896 # contained therein.
897 del sys.modules[main_mod_name]
899 return stats
901 def _run_with_debugger(
902 self, code, code_ns, filename=None, bp_line=None, bp_file=None, local_ns=None
903 ):
904 """
905 Run `code` in debugger with a break point.
907 Parameters
908 ----------
909 code : str
910 Code to execute.
911 code_ns : dict
912 A namespace in which `code` is executed.
913 filename : str
914 `code` is ran as if it is in `filename`.
915 bp_line : int, optional
916 Line number of the break point.
917 bp_file : str, optional
918 Path to the file in which break point is specified.
919 `filename` is used if not given.
920 local_ns : dict, optional
921 A local namespace in which `code` is executed.
923 Raises
924 ------
925 UsageError
926 If the break point given by `bp_line` is not valid.
928 """
929 deb = self.shell.InteractiveTB.pdb
930 if not deb:
931 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
932 deb = self.shell.InteractiveTB.pdb
934 # reset Breakpoint state, which is moronically kept
935 # in a class
936 bdb.Breakpoint.next = 1
937 bdb.Breakpoint.bplist = {}
938 bdb.Breakpoint.bpbynumber = [None]
939 deb.clear_all_breaks()
940 if bp_line is not None:
941 # Set an initial breakpoint to stop execution
942 maxtries = 10
943 bp_file = bp_file or filename
944 checkline = deb.checkline(bp_file, bp_line)
945 if not checkline:
946 for bp in range(bp_line + 1, bp_line + maxtries + 1):
947 if deb.checkline(bp_file, bp):
948 break
949 else:
950 msg = ("\nI failed to find a valid line to set "
951 "a breakpoint\n"
952 "after trying up to line: %s.\n"
953 "Please set a valid breakpoint manually "
954 "with the -b option." % bp)
955 raise UsageError(msg)
956 # if we find a good linenumber, set the breakpoint
957 deb.do_break('%s:%s' % (bp_file, bp_line))
959 if filename:
960 # Mimic Pdb._runscript(...)
961 deb._wait_for_mainpyfile = True
962 deb.mainpyfile = deb.canonic(filename)
964 # Start file run
965 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
966 try:
967 if filename:
968 # save filename so it can be used by methods on the deb object
969 deb._exec_filename = filename
970 while True:
971 try:
972 trace = sys.gettrace()
973 deb.run(code, code_ns, local_ns)
974 except Restart:
975 print("Restarting")
976 if filename:
977 deb._wait_for_mainpyfile = True
978 deb.mainpyfile = deb.canonic(filename)
979 continue
980 else:
981 break
982 finally:
983 sys.settrace(trace)
985 # Perform proper cleanup of the session in case if
986 # it exited with "continue" and not "quit" command
987 if hasattr(deb, "rcLines"):
988 # Run this code defensively in case if custom debugger
989 # class does not implement rcLines, which although public
990 # is an implementation detail of `pdb.Pdb` and not part of
991 # the more generic basic debugger framework (`bdb.Bdb`).
992 deb.set_quit()
993 deb.rcLines.extend(["q"])
994 try:
995 deb.run("", code_ns, local_ns)
996 except StopIteration:
997 # Stop iteration is raised on quit command
998 pass
1000 except Exception:
1001 etype, value, tb = sys.exc_info()
1002 # Skip three frames in the traceback: the %run one,
1003 # one inside bdb.py, and the command-line typed by the
1004 # user (run by exec in pdb itself).
1005 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
1007 @staticmethod
1008 def _run_with_timing(run, nruns):
1009 """
1010 Run function `run` and print timing information.
1012 Parameters
1013 ----------
1014 run : callable
1015 Any callable object which takes no argument.
1016 nruns : int
1017 Number of times to execute `run`.
1019 """
1020 twall0 = time.perf_counter()
1021 if nruns == 1:
1022 t0 = clock2()
1023 run()
1024 t1 = clock2()
1025 t_usr = t1[0] - t0[0]
1026 t_sys = t1[1] - t0[1]
1027 print("\nIPython CPU timings (estimated):")
1028 print(" User : %10.2f s." % t_usr)
1029 print(" System : %10.2f s." % t_sys)
1030 else:
1031 runs = range(nruns)
1032 t0 = clock2()
1033 for nr in runs:
1034 run()
1035 t1 = clock2()
1036 t_usr = t1[0] - t0[0]
1037 t_sys = t1[1] - t0[1]
1038 print("\nIPython CPU timings (estimated):")
1039 print("Total runs performed:", nruns)
1040 print(" Times : %10s %10s" % ('Total', 'Per run'))
1041 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
1042 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
1043 twall1 = time.perf_counter()
1044 print("Wall time: %10.2f s." % (twall1 - twall0))
1046 @skip_doctest
1047 @no_var_expand
1048 @line_cell_magic
1049 @needs_local_scope
1050 def timeit(self, line='', cell=None, local_ns=None):
1051 """Time execution of a Python statement or expression
1053 **Usage, in line mode**::
1055 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> [-o|-v <V>]] statement
1057 **or in cell mode**::
1059 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> [-o|-v <V>]] setup_code
1060 code
1061 code...
1063 Time execution of a Python statement or expression using the timeit
1064 module. This function can be used both as a line and cell magic:
1066 - In line mode you can time a single-line statement (though multiple
1067 ones can be chained with using semicolons).
1069 - In cell mode, the statement in the first line is used as setup code
1070 (executed but not timed) and the body of the cell is timed. The cell
1071 body has access to any variables created in the setup code.
1073 Options:
1075 -n<N>
1076 Execute the given statement N times in a loop. If N is not
1077 provided, N is determined so as to get sufficient accuracy.
1079 -r<R>
1080 Number of repeats R, each consisting of N loops, and take the
1081 average result.
1082 Default: 7
1084 -t
1085 Use ``time.time`` to measure the time, which is the default on Unix.
1086 This function measures wall time.
1088 -c
1089 Use ``time.clock`` to measure the time, which is the default on
1090 Windows and measures wall time. On Unix, ``resource.getrusage`` is used
1091 instead and returns the CPU user time.
1093 -p<P>
1094 Use a precision of P digits to display the timing result.
1095 Default: 3
1097 -q
1098 Quiet, do not print result.
1100 -o
1101 Return a ``TimeitResult`` that can be stored in a variable to inspect
1102 the result in more details.
1104 -v <V>
1105 Like ``-o``, but save the ``TimeitResult`` directly to variable <V>.
1107 .. versionchanged:: 7.3
1108 User variables are no longer expanded,
1109 the magic line is always left unmodified.
1111 Examples
1112 --------
1113 ::
1115 In [1]: %timeit pass
1116 8.26 ns ± 0.12 ns per loop (mean ± std. dev. of 7 runs, 100000000 loops each)
1118 In [2]: u = None
1120 In [3]: %timeit u is None
1121 29.9 ns ± 0.643 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)
1123 In [4]: %timeit -r 4 u == None
1125 In [5]: import time
1127 In [6]: %timeit -n1 time.sleep(2)
1129 The times reported by ``%timeit`` will be slightly higher than those
1130 reported by the timeit.py script when variables are accessed. This is
1131 due to the fact that ``%timeit`` executes the statement in the namespace
1132 of the shell, compared with timeit.py, which uses a single setup
1133 statement to import function or create variables. Generally, the bias
1134 does not matter as long as results from timeit.py are not mixed with
1135 those from ``%timeit``."""
1137 # TODO: port to magic_arguments as currently this is duplicated in IPCompleter._extract_code
1138 opts, stmt = self.parse_options(
1139 line, "n:r:tcp:qov:", posix=False, strict=False, preserve_non_opts=True
1140 )
1141 if stmt == "" and cell is None:
1142 return
1144 timefunc = timeit.default_timer
1145 number = int(getattr(opts, "n", 0))
1146 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1147 repeat = int(getattr(opts, "r", default_repeat))
1148 precision = int(getattr(opts, "p", 3))
1149 quiet = "q" in opts
1150 return_result = "o" in opts
1151 save_result = "v" in opts
1152 if hasattr(opts, "t"):
1153 timefunc = time.time
1154 if hasattr(opts, "c"):
1155 timefunc = clock
1157 timer = Timer(timer=timefunc)
1158 # this code has tight coupling to the inner workings of timeit.Timer,
1159 # but is there a better way to achieve that the code stmt has access
1160 # to the shell namespace?
1161 transform = self.shell.transform_cell
1163 if cell is None:
1164 # called as line magic
1165 ast_setup = self.shell.compile.ast_parse("pass")
1166 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1167 else:
1168 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1169 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1171 ast_setup = self.shell.transform_ast(ast_setup)
1172 ast_stmt = self.shell.transform_ast(ast_stmt)
1174 # Check that these compile to valid Python code *outside* the timer func
1175 # Invalid code may become valid when put inside the function & loop,
1176 # which messes up error messages.
1177 # https://github.com/ipython/ipython/issues/10636
1178 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1179 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1181 # This codestring is taken from timeit.template - we fill it in as an
1182 # AST, so that we can apply our AST transformations to the user code
1183 # without affecting the timing code.
1184 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1185 ' setup\n'
1186 ' _t0 = _timer()\n'
1187 ' for _i in _it:\n'
1188 ' stmt\n'
1189 ' _t1 = _timer()\n'
1190 ' return _t1 - _t0\n')
1192 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1193 timeit_ast = ast.fix_missing_locations(timeit_ast)
1195 # Track compilation time so it can be reported if too long
1196 # Minimum time above which compilation time will be reported
1197 tc_min = 0.1
1199 t0 = clock()
1200 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1201 tc = clock()-t0
1203 ns = {}
1204 glob = self.shell.user_ns
1205 # handles global vars with same name as local vars. We store them in conflict_globs.
1206 conflict_globs = {}
1207 if local_ns and cell is None:
1208 for var_name, var_val in glob.items():
1209 if var_name in local_ns:
1210 conflict_globs[var_name] = var_val
1211 glob.update(local_ns)
1213 exec(code, glob, ns)
1214 timer.inner = ns["inner"]
1216 # This is used to check if there is a huge difference between the
1217 # best and worst timings.
1218 # Issue: https://github.com/ipython/ipython/issues/6471
1219 if number == 0:
1220 # determine number so that 0.2 <= total time < 2.0
1221 for index in range(0, 10):
1222 number = 10 ** index
1223 time_number = timer.timeit(number)
1224 if time_number >= 0.2:
1225 break
1227 all_runs = timer.repeat(repeat, number)
1228 best = min(all_runs) / number
1229 worst = max(all_runs) / number
1230 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1232 # Restore global vars from conflict_globs
1233 if conflict_globs:
1234 glob.update(conflict_globs)
1236 if not quiet:
1237 # Check best timing is greater than zero to avoid a
1238 # ZeroDivisionError.
1239 # In cases where the slowest timing is lesser than a microsecond
1240 # we assume that it does not really matter if the fastest
1241 # timing is 4 times faster than the slowest timing or not.
1242 if worst > 4 * best and best > 0 and worst > 1e-6:
1243 print("The slowest run took %0.2f times longer than the "
1244 "fastest. This could mean that an intermediate result "
1245 "is being cached." % (worst / best))
1247 print( timeit_result )
1249 if tc > tc_min:
1250 print("Compiler time: %.2f s" % tc)
1252 if save_result:
1253 self.shell.user_ns[opts.v] = timeit_result
1255 if return_result:
1256 return timeit_result
1258 @no_var_expand
1259 @magic_arguments.magic_arguments()
1260 @magic_arguments.argument(
1261 "--no-raise-error",
1262 action="store_true",
1263 dest="no_raise_error",
1264 help="If given, don't re-raise exceptions",
1265 )
1266 @magic_arguments.kwds(
1267 epilog="""
1268 Any remaining arguments will be treated as code to run.
1269 """
1270 )
1271 @skip_doctest
1272 @needs_local_scope
1273 @line_cell_magic
1274 @output_can_be_silenced
1275 def time(self, line="", cell=None, local_ns=None):
1276 """Time execution of a Python statement or expression.
1278 The CPU and wall clock times are printed, and the value of the
1279 expression (if any) is returned. Note that under Win32, system time
1280 is always reported as 0, since it can not be measured.
1282 This function can be used both as a line and cell magic:
1284 - In line mode you can time a single-line statement (though multiple
1285 ones can be chained with using semicolons).
1287 - In cell mode, you can time the cell body (a directly
1288 following statement raises an error).
1290 This function provides very basic timing functionality. Use the timeit
1291 magic for more control over the measurement.
1293 .. versionchanged:: 7.3
1294 User variables are no longer expanded,
1295 the magic line is always left unmodified.
1297 .. versionchanged:: 8.3
1298 The time magic now correctly propagates system-exiting exceptions
1299 (such as ``KeyboardInterrupt`` invoked when interrupting execution)
1300 rather than just printing out the exception traceback.
1301 The non-system-exception will still be caught as before.
1303 Examples
1304 --------
1305 ::
1307 In [1]: %time 2**128
1308 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1309 Wall time: 0.00
1310 Out[1]: 340282366920938463463374607431768211456L
1312 In [2]: n = 1000000
1314 In [3]: %time sum(range(n))
1315 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1316 Wall time: 1.37
1317 Out[3]: 499999500000L
1319 In [4]: %time print('hello world')
1320 hello world
1321 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1322 Wall time: 0.00
1324 .. note::
1325 The time needed by Python to compile the given expression will be
1326 reported if it is more than 0.1s.
1328 In the example below, the actual exponentiation is done by Python
1329 at compilation time, so while the expression can take a noticeable
1330 amount of time to compute, that time is purely due to the
1331 compilation::
1333 In [5]: %time 3**9999;
1334 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1335 Wall time: 0.00 s
1337 In [6]: %time 3**999999;
1338 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1339 Wall time: 0.00 s
1340 Compiler : 0.78 s
1341 """
1342 args, extra = magic_arguments.parse_argstring(self.time, line, partial=True)
1343 line = " ".join(extra)
1345 if line and cell:
1346 raise UsageError("Can't use statement directly after '%%time'!")
1348 if cell:
1349 expr = self.shell.transform_cell(cell)
1350 else:
1351 expr = self.shell.transform_cell(line)
1353 # Minimum time above which parse time will be reported
1354 tp_min = 0.1
1356 t0 = clock()
1357 expr_ast = self.shell.compile.ast_parse(expr)
1358 tp = clock() - t0
1360 # Apply AST transformations
1361 expr_ast = self.shell.transform_ast(expr_ast)
1363 # Minimum time above which compilation time will be reported
1364 tc_min = 0.1
1366 expr_val = None
1367 if len(expr_ast.body) == 1 and isinstance(expr_ast.body[0], ast.Expr):
1368 mode = 'eval'
1369 source = '<timed eval>'
1370 expr_ast = ast.Expression(expr_ast.body[0].value)
1371 else:
1372 mode = 'exec'
1373 source = '<timed exec>'
1374 # multi-line %%time case
1375 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1376 expr_val = expr_ast.body[-1]
1377 expr_ast = expr_ast.body[:-1]
1378 expr_ast = Module(expr_ast, [])
1379 expr_val = ast.Expression(expr_val.value)
1381 t0 = clock()
1382 code = self.shell.compile(expr_ast, source, mode)
1383 tc = clock() - t0
1385 # skew measurement as little as possible
1386 glob = self.shell.user_ns
1387 wtime = time.time
1388 # time execution
1389 wall_st = wtime()
1390 # Track whether to propagate exceptions or exit
1391 exit_on_interrupt = False
1392 interrupt_occured = False
1393 captured_exception = None
1395 if mode == "eval":
1396 st = clock2()
1397 try:
1398 out = eval(code, glob, local_ns)
1399 except KeyboardInterrupt as e:
1400 captured_exception = e
1401 interrupt_occured = True
1402 exit_on_interrupt = True
1403 except Exception as e:
1404 captured_exception = e
1405 interrupt_occured = True
1406 if not args.no_raise_error:
1407 exit_on_interrupt = True
1408 end = clock2()
1409 else:
1410 st = clock2()
1411 try:
1412 exec(code, glob, local_ns)
1413 out = None
1414 # multi-line %%time case
1415 if expr_val is not None:
1416 code_2 = self.shell.compile(expr_val, source, 'eval')
1417 out = eval(code_2, glob, local_ns)
1418 except KeyboardInterrupt as e:
1419 captured_exception = e
1420 interrupt_occured = True
1421 exit_on_interrupt = True
1422 except Exception as e:
1423 captured_exception = e
1424 interrupt_occured = True
1425 if not args.no_raise_error:
1426 exit_on_interrupt = True
1427 end = clock2()
1428 wall_end = wtime()
1429 # Compute actual times and report
1430 wall_time = wall_end - wall_st
1431 cpu_user = end[0] - st[0]
1432 cpu_sys = end[1] - st[1]
1433 cpu_tot = cpu_user + cpu_sys
1434 # On windows cpu_sys is always zero, so only total is displayed
1435 if sys.platform != "win32":
1436 print(
1437 f"CPU times: user {_format_time(cpu_user)}, sys: {_format_time(cpu_sys)}, total: {_format_time(cpu_tot)}"
1438 )
1439 else:
1440 print(f"CPU times: total: {_format_time(cpu_tot)}")
1441 print(f"Wall time: {_format_time(wall_time)}")
1442 if tc > tc_min:
1443 print(f"Compiler : {_format_time(tc)}")
1444 if tp > tp_min:
1445 print(f"Parser : {_format_time(tp)}")
1446 if interrupt_occured:
1447 if exit_on_interrupt and captured_exception:
1448 raise captured_exception
1449 return
1450 return out
1452 @skip_doctest
1453 @line_magic
1454 def macro(self, parameter_s=''):
1455 """Define a macro for future re-execution. It accepts ranges of history,
1456 filenames or string objects.
1458 Usage::
1460 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1462 Options:
1464 -r
1465 Use 'raw' input. By default, the 'processed' history is used,
1466 so that magics are loaded in their transformed version to valid
1467 Python. If this option is given, the raw input as typed at the
1468 command line is used instead.
1470 -q
1471 Quiet macro definition. By default, a tag line is printed
1472 to indicate the macro has been created, and then the contents of
1473 the macro are printed. If this option is given, then no printout
1474 is produced once the macro is created.
1476 This will define a global variable called `name` which is a string
1477 made of joining the slices and lines you specify (n1,n2,... numbers
1478 above) from your input history into a single string. This variable
1479 acts like an automatic function which re-executes those lines as if
1480 you had typed them. You just type 'name' at the prompt and the code
1481 executes.
1483 The syntax for indicating input ranges is described in %history.
1485 Note: as a 'hidden' feature, you can also use traditional python slice
1486 notation, where N:M means numbers N through M-1.
1488 For example, if your history contains (print using %hist -n )::
1490 44: x=1
1491 45: y=3
1492 46: z=x+y
1493 47: print(x)
1494 48: a=5
1495 49: print('x',x,'y',y)
1497 you can create a macro with lines 44 through 47 (included) and line 49
1498 called my_macro with::
1500 In [55]: %macro my_macro 44-47 49
1502 Now, typing `my_macro` (without quotes) will re-execute all this code
1503 in one pass.
1505 You don't need to give the line-numbers in order, and any given line
1506 number can appear multiple times. You can assemble macros with any
1507 lines from your input history in any order.
1509 The macro is a simple object which holds its value in an attribute,
1510 but IPython's display system checks for macros and executes them as
1511 code instead of printing them when you type their name.
1513 You can view a macro's contents by explicitly printing it with::
1515 print(macro_name)
1517 """
1518 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1519 if not args: # List existing macros
1520 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1521 if len(args) == 1:
1522 raise UsageError(
1523 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1524 name, codefrom = args[0], " ".join(args[1:])
1526 # print('rng',ranges) # dbg
1527 try:
1528 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1529 except (ValueError, TypeError) as e:
1530 print(e.args[0])
1531 return
1532 macro = Macro(lines)
1533 self.shell.define_macro(name, macro)
1534 if "q" not in opts:
1535 print(
1536 "Macro `%s` created. To execute, type its name (without quotes)." % name
1537 )
1538 print("=== Macro contents: ===")
1539 print(macro, end=" ")
1541 @magic_arguments.magic_arguments()
1542 @magic_arguments.argument(
1543 "output",
1544 type=str,
1545 default="",
1546 nargs="?",
1547 help="""
1549 The name of the variable in which to store output.
1550 This is a ``utils.io.CapturedIO`` object with stdout/err attributes
1551 for the text of the captured output.
1553 CapturedOutput also has a ``show()`` method for displaying the output,
1554 and ``__call__`` as well, so you can use that to quickly display the
1555 output.
1557 If unspecified, captured output is discarded.
1558 """,
1559 )
1560 @magic_arguments.argument(
1561 "--no-stderr", action="store_true", help="""Don't capture stderr."""
1562 )
1563 @magic_arguments.argument(
1564 "--no-stdout", action="store_true", help="""Don't capture stdout."""
1565 )
1566 @magic_arguments.argument(
1567 "--no-display",
1568 action="store_true",
1569 help="""Don't capture IPython's rich display."""
1570 )
1571 @cell_magic
1572 def capture(self, line, cell):
1573 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1574 args = magic_arguments.parse_argstring(self.capture, line)
1575 out = not args.no_stdout
1576 err = not args.no_stderr
1577 disp = not args.no_display
1578 with capture_output(out, err, disp) as io:
1579 self.shell.run_cell(cell)
1580 if DisplayHook.semicolon_at_end_of_expression(cell):
1581 if args.output in self.shell.user_ns:
1582 del self.shell.user_ns[args.output]
1583 elif args.output:
1584 self.shell.user_ns[args.output] = io
1586 @skip_doctest
1587 @magic_arguments.magic_arguments()
1588 @magic_arguments.argument("name", type=str, default="default", nargs="?")
1589 @magic_arguments.argument(
1590 "--remove", action="store_true", help="remove the current transformer"
1591 )
1592 @magic_arguments.argument(
1593 "--list", action="store_true", help="list existing transformers name"
1594 )
1595 @magic_arguments.argument(
1596 "--list-all",
1597 action="store_true",
1598 help="list existing transformers name and code template",
1599 )
1600 @line_cell_magic
1601 def code_wrap(self, line, cell=None):
1602 """
1603 Simple magic to quickly define a code transformer for all IPython's future input.
1605 ``__code__`` and ``__ret__`` are special variable that represent the code to run
1606 and the value of the last expression of ``__code__`` respectively.
1608 Examples
1609 --------
1611 .. ipython::
1613 In [1]: %%code_wrap before_after
1614 ...: print('before')
1615 ...: __code__
1616 ...: print('after')
1617 ...: __ret__
1620 In [2]: 1
1621 before
1622 after
1623 Out[2]: 1
1625 In [3]: %code_wrap --list
1626 before_after
1628 In [4]: %code_wrap --list-all
1629 before_after :
1630 print('before')
1631 __code__
1632 print('after')
1633 __ret__
1635 In [5]: %code_wrap --remove before_after
1637 """
1638 args = magic_arguments.parse_argstring(self.code_wrap, line)
1640 if args.list:
1641 for name in self._transformers.keys():
1642 print(name)
1643 return
1644 if args.list_all:
1645 for name, _t in self._transformers.items():
1646 print(name, ":")
1647 print(indent(ast.unparse(_t.template), " "))
1648 print()
1649 return
1651 to_remove = self._transformers.pop(args.name, None)
1652 if to_remove in self.shell.ast_transformers:
1653 self.shell.ast_transformers.remove(to_remove)
1654 if cell is None or args.remove:
1655 return
1657 _trs = ReplaceCodeTransformer(ast.parse(cell))
1659 self._transformers[args.name] = _trs
1660 self.shell.ast_transformers.append(_trs)
1663def parse_breakpoint(text, current_file):
1664 '''Returns (file, line) for file:line and (current_file, line) for line'''
1665 colon = text.find(':')
1666 if colon == -1:
1667 return current_file, int(text)
1668 else:
1669 return text[:colon], int(text[colon+1:])
1672def _format_time(timespan, precision=3):
1673 """Formats the timespan in a human readable form"""
1675 if timespan >= 60.0:
1676 # we have more than a minute, format that in a human readable form
1677 # Idea from http://snipplr.com/view/5713/
1678 parts = [("d", 60 * 60 * 24), ("h", 60 * 60), ("min", 60), ("s", 1)]
1679 time = []
1680 leftover = timespan
1681 for suffix, length in parts:
1682 value = int(leftover / length)
1683 if value > 0:
1684 leftover = leftover % length
1685 time.append("%s%s" % (str(value), suffix))
1686 if leftover < 1:
1687 break
1688 return " ".join(time)
1690 # Unfortunately characters outside of range(128) can cause problems in
1691 # certain terminals.
1692 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1693 # Try to prevent crashes by being more secure than it needs to
1694 # E.g. eclipse is able to print a µ, but has no sys.stdout.encoding set.
1695 units = ["s", "ms", "us", "ns"] # the safe value
1696 if hasattr(sys.stdout, "encoding") and sys.stdout.encoding:
1697 try:
1698 "μ".encode(sys.stdout.encoding)
1699 units = ["s", "ms", "μs", "ns"]
1700 except:
1701 pass
1702 scaling = [1, 1e3, 1e6, 1e9]
1704 if timespan > 0.0:
1705 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1706 else:
1707 order = 3
1708 return "%.*g %s" % (precision, timespan * scaling[order], units[order])