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