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