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 # 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 if par:
425 try:
426 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
427 except KeyError:
428 print ('Incorrect argument. Use on/1, off/0, '
429 'or nothing for a toggle.')
430 return
431 else:
432 # toggle
433 new_pdb = not self.shell.call_pdb
435 # set on the shell
436 self.shell.call_pdb = new_pdb
437 print('Automatic pdb calling has been turned',on_off(new_pdb))
439 @magic_arguments.magic_arguments()
440 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
441 help="""
442 Set break point at LINE in FILE.
443 """
444 )
445 @magic_arguments.kwds(
446 epilog="""
447 Any remaining arguments will be treated as code to run in the debugger.
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, extra = magic_arguments.parse_argstring(self.debug, line, partial=True)
480 if not (args.breakpoint or extra 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 = " ".join(extra)
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 # TODO: port to magic_arguments as currently this is duplicated in IPCompleter._extract_code
1142 opts, stmt = self.parse_options(
1143 line, "n:r:tcp:qov:", posix=False, strict=False, preserve_non_opts=True
1144 )
1145 if stmt == "" and cell is None:
1146 return
1148 timefunc = timeit.default_timer
1149 number = int(getattr(opts, "n", 0))
1150 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1151 repeat = int(getattr(opts, "r", default_repeat))
1152 precision = int(getattr(opts, "p", 3))
1153 quiet = "q" in opts
1154 return_result = "o" in opts
1155 save_result = "v" in opts
1156 if hasattr(opts, "t"):
1157 timefunc = time.time
1158 if hasattr(opts, "c"):
1159 timefunc = clock
1161 timer = Timer(timer=timefunc)
1162 # this code has tight coupling to the inner workings of timeit.Timer,
1163 # but is there a better way to achieve that the code stmt has access
1164 # to the shell namespace?
1165 transform = self.shell.transform_cell
1167 if cell is None:
1168 # called as line magic
1169 ast_setup = self.shell.compile.ast_parse("pass")
1170 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1171 else:
1172 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1173 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1175 ast_setup = self.shell.transform_ast(ast_setup)
1176 ast_stmt = self.shell.transform_ast(ast_stmt)
1178 # Check that these compile to valid Python code *outside* the timer func
1179 # Invalid code may become valid when put inside the function & loop,
1180 # which messes up error messages.
1181 # https://github.com/ipython/ipython/issues/10636
1182 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1183 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1185 # This codestring is taken from timeit.template - we fill it in as an
1186 # AST, so that we can apply our AST transformations to the user code
1187 # without affecting the timing code.
1188 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1189 ' setup\n'
1190 ' _t0 = _timer()\n'
1191 ' for _i in _it:\n'
1192 ' stmt\n'
1193 ' _t1 = _timer()\n'
1194 ' return _t1 - _t0\n')
1196 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1197 timeit_ast = ast.fix_missing_locations(timeit_ast)
1199 # Track compilation time so it can be reported if too long
1200 # Minimum time above which compilation time will be reported
1201 tc_min = 0.1
1203 t0 = clock()
1204 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1205 tc = clock()-t0
1207 ns = {}
1208 glob = self.shell.user_ns
1209 # handles global vars with same name as local vars. We store them in conflict_globs.
1210 conflict_globs = {}
1211 if local_ns and cell is None:
1212 for var_name, var_val in glob.items():
1213 if var_name in local_ns:
1214 conflict_globs[var_name] = var_val
1215 glob.update(local_ns)
1217 exec(code, glob, ns)
1218 timer.inner = ns["inner"]
1220 # This is used to check if there is a huge difference between the
1221 # best and worst timings.
1222 # Issue: https://github.com/ipython/ipython/issues/6471
1223 if number == 0:
1224 # determine number so that 0.2 <= total time < 2.0
1225 for index in range(0, 10):
1226 number = 10 ** index
1227 time_number = timer.timeit(number)
1228 if time_number >= 0.2:
1229 break
1231 all_runs = timer.repeat(repeat, number)
1232 best = min(all_runs) / number
1233 worst = max(all_runs) / number
1234 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1236 # Restore global vars from conflict_globs
1237 if conflict_globs:
1238 glob.update(conflict_globs)
1240 if not quiet:
1241 # Check best timing is greater than zero to avoid a
1242 # ZeroDivisionError.
1243 # In cases where the slowest timing is lesser than a microsecond
1244 # we assume that it does not really matter if the fastest
1245 # timing is 4 times faster than the slowest timing or not.
1246 if worst > 4 * best and best > 0 and worst > 1e-6:
1247 print("The slowest run took %0.2f times longer than the "
1248 "fastest. This could mean that an intermediate result "
1249 "is being cached." % (worst / best))
1251 print( timeit_result )
1253 if tc > tc_min:
1254 print("Compiler time: %.2f s" % tc)
1256 if save_result:
1257 self.shell.user_ns[opts.v] = timeit_result
1259 if return_result:
1260 return timeit_result
1262 @no_var_expand
1263 @magic_arguments.magic_arguments()
1264 @magic_arguments.argument(
1265 "--no-raise-error",
1266 action="store_true",
1267 dest="no_raise_error",
1268 help="If given, don't re-raise exceptions",
1269 )
1270 @magic_arguments.kwds(
1271 epilog="""
1272 Any remaining arguments will be treated as code to run.
1273 """
1274 )
1275 @skip_doctest
1276 @needs_local_scope
1277 @line_cell_magic
1278 @output_can_be_silenced
1279 def time(self, line="", cell=None, local_ns=None):
1280 """Time execution of a Python statement or expression.
1282 The CPU and wall clock times are printed, and the value of the
1283 expression (if any) is returned. Note that under Win32, system time
1284 is always reported as 0, since it can not be measured.
1286 This function can be used both as a line and cell magic:
1288 - In line mode you can time a single-line statement (though multiple
1289 ones can be chained with using semicolons).
1291 - In cell mode, you can time the cell body (a directly
1292 following statement raises an error).
1294 This function provides very basic timing functionality. Use the timeit
1295 magic for more control over the measurement.
1297 .. versionchanged:: 7.3
1298 User variables are no longer expanded,
1299 the magic line is always left unmodified.
1301 .. versionchanged:: 8.3
1302 The time magic now correctly propagates system-exiting exceptions
1303 (such as ``KeyboardInterrupt`` invoked when interrupting execution)
1304 rather than just printing out the exception traceback.
1305 The non-system-exception will still be caught as before.
1307 Examples
1308 --------
1309 ::
1311 In [1]: %time 2**128
1312 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1313 Wall time: 0.00
1314 Out[1]: 340282366920938463463374607431768211456L
1316 In [2]: n = 1000000
1318 In [3]: %time sum(range(n))
1319 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1320 Wall time: 1.37
1321 Out[3]: 499999500000L
1323 In [4]: %time print('hello world')
1324 hello world
1325 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1326 Wall time: 0.00
1328 .. note::
1329 The time needed by Python to compile the given expression will be
1330 reported if it is more than 0.1s.
1332 In the example below, the actual exponentiation is done by Python
1333 at compilation time, so while the expression can take a noticeable
1334 amount of time to compute, that time is purely due to the
1335 compilation::
1337 In [5]: %time 3**9999;
1338 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1339 Wall time: 0.00 s
1341 In [6]: %time 3**999999;
1342 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1343 Wall time: 0.00 s
1344 Compiler : 0.78 s
1345 """
1346 args, extra = magic_arguments.parse_argstring(self.time, line, partial=True)
1347 line = " ".join(extra)
1349 if line and cell:
1350 raise UsageError("Can't use statement directly after '%%time'!")
1352 if cell:
1353 expr = self.shell.transform_cell(cell)
1354 else:
1355 expr = self.shell.transform_cell(line)
1357 # Minimum time above which parse time will be reported
1358 tp_min = 0.1
1360 t0 = clock()
1361 expr_ast = self.shell.compile.ast_parse(expr)
1362 tp = clock() - t0
1364 # Apply AST transformations
1365 expr_ast = self.shell.transform_ast(expr_ast)
1367 # Minimum time above which compilation time will be reported
1368 tc_min = 0.1
1370 expr_val = None
1371 if len(expr_ast.body) == 1 and isinstance(expr_ast.body[0], ast.Expr):
1372 mode = 'eval'
1373 source = '<timed eval>'
1374 expr_ast = ast.Expression(expr_ast.body[0].value)
1375 else:
1376 mode = 'exec'
1377 source = '<timed exec>'
1378 # multi-line %%time case
1379 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1380 expr_val = expr_ast.body[-1]
1381 expr_ast = expr_ast.body[:-1]
1382 expr_ast = Module(expr_ast, [])
1383 expr_val = ast.Expression(expr_val.value)
1385 t0 = clock()
1386 code = self.shell.compile(expr_ast, source, mode)
1387 tc = clock() - t0
1389 # skew measurement as little as possible
1390 glob = self.shell.user_ns
1391 wtime = time.time
1392 # time execution
1393 wall_st = wtime()
1394 # Track whether to propagate exceptions or exit
1395 exit_on_interrupt = False
1396 interrupt_occured = False
1397 captured_exception = None
1399 if mode == "eval":
1400 st = clock2()
1401 try:
1402 out = eval(code, glob, local_ns)
1403 except KeyboardInterrupt as e:
1404 captured_exception = e
1405 interrupt_occured = True
1406 exit_on_interrupt = True
1407 except Exception as e:
1408 captured_exception = e
1409 interrupt_occured = True
1410 if not args.no_raise_error:
1411 exit_on_interrupt = True
1412 end = clock2()
1413 else:
1414 st = clock2()
1415 try:
1416 exec(code, glob, local_ns)
1417 out = None
1418 # multi-line %%time case
1419 if expr_val is not None:
1420 code_2 = self.shell.compile(expr_val, source, 'eval')
1421 out = eval(code_2, glob, local_ns)
1422 except KeyboardInterrupt as e:
1423 captured_exception = e
1424 interrupt_occured = True
1425 exit_on_interrupt = True
1426 except Exception as e:
1427 captured_exception = e
1428 interrupt_occured = True
1429 if not args.no_raise_error:
1430 exit_on_interrupt = True
1431 end = clock2()
1432 wall_end = wtime()
1433 # Compute actual times and report
1434 wall_time = wall_end - wall_st
1435 cpu_user = end[0] - st[0]
1436 cpu_sys = end[1] - st[1]
1437 cpu_tot = cpu_user + cpu_sys
1438 # On windows cpu_sys is always zero, so only total is displayed
1439 if sys.platform != "win32":
1440 print(
1441 f"CPU times: user {_format_time(cpu_user)}, sys: {_format_time(cpu_sys)}, total: {_format_time(cpu_tot)}"
1442 )
1443 else:
1444 print(f"CPU times: total: {_format_time(cpu_tot)}")
1445 print(f"Wall time: {_format_time(wall_time)}")
1446 if tc > tc_min:
1447 print(f"Compiler : {_format_time(tc)}")
1448 if tp > tp_min:
1449 print(f"Parser : {_format_time(tp)}")
1450 if interrupt_occured:
1451 if exit_on_interrupt and captured_exception:
1452 raise captured_exception
1453 return
1454 return out
1456 @skip_doctest
1457 @line_magic
1458 def macro(self, parameter_s=''):
1459 """Define a macro for future re-execution. It accepts ranges of history,
1460 filenames or string objects.
1462 Usage::
1464 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1466 Options:
1468 -r
1469 Use 'raw' input. By default, the 'processed' history is used,
1470 so that magics are loaded in their transformed version to valid
1471 Python. If this option is given, the raw input as typed at the
1472 command line is used instead.
1474 -q
1475 Quiet macro definition. By default, a tag line is printed
1476 to indicate the macro has been created, and then the contents of
1477 the macro are printed. If this option is given, then no printout
1478 is produced once the macro is created.
1480 This will define a global variable called `name` which is a string
1481 made of joining the slices and lines you specify (n1,n2,... numbers
1482 above) from your input history into a single string. This variable
1483 acts like an automatic function which re-executes those lines as if
1484 you had typed them. You just type 'name' at the prompt and the code
1485 executes.
1487 The syntax for indicating input ranges is described in %history.
1489 Note: as a 'hidden' feature, you can also use traditional python slice
1490 notation, where N:M means numbers N through M-1.
1492 For example, if your history contains (print using %hist -n )::
1494 44: x=1
1495 45: y=3
1496 46: z=x+y
1497 47: print(x)
1498 48: a=5
1499 49: print('x',x,'y',y)
1501 you can create a macro with lines 44 through 47 (included) and line 49
1502 called my_macro with::
1504 In [55]: %macro my_macro 44-47 49
1506 Now, typing `my_macro` (without quotes) will re-execute all this code
1507 in one pass.
1509 You don't need to give the line-numbers in order, and any given line
1510 number can appear multiple times. You can assemble macros with any
1511 lines from your input history in any order.
1513 The macro is a simple object which holds its value in an attribute,
1514 but IPython's display system checks for macros and executes them as
1515 code instead of printing them when you type their name.
1517 You can view a macro's contents by explicitly printing it with::
1519 print(macro_name)
1521 """
1522 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1523 if not args: # List existing macros
1524 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1525 if len(args) == 1:
1526 raise UsageError(
1527 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1528 name, codefrom = args[0], " ".join(args[1:])
1530 # print('rng',ranges) # dbg
1531 try:
1532 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1533 except (ValueError, TypeError) as e:
1534 print(e.args[0])
1535 return
1536 macro = Macro(lines)
1537 self.shell.define_macro(name, macro)
1538 if "q" not in opts:
1539 print(
1540 "Macro `%s` created. To execute, type its name (without quotes)." % name
1541 )
1542 print("=== Macro contents: ===")
1543 print(macro, end=" ")
1545 @magic_arguments.magic_arguments()
1546 @magic_arguments.argument(
1547 "output",
1548 type=str,
1549 default="",
1550 nargs="?",
1551 help="""
1553 The name of the variable in which to store output.
1554 This is a ``utils.io.CapturedIO`` object with stdout/err attributes
1555 for the text of the captured output.
1557 CapturedOutput also has a ``show()`` method for displaying the output,
1558 and ``__call__`` as well, so you can use that to quickly display the
1559 output.
1561 If unspecified, captured output is discarded.
1562 """,
1563 )
1564 @magic_arguments.argument(
1565 "--no-stderr", action="store_true", help="""Don't capture stderr."""
1566 )
1567 @magic_arguments.argument(
1568 "--no-stdout", action="store_true", help="""Don't capture stdout."""
1569 )
1570 @magic_arguments.argument(
1571 "--no-display",
1572 action="store_true",
1573 help="""Don't capture IPython's rich display."""
1574 )
1575 @cell_magic
1576 def capture(self, line, cell):
1577 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1578 args = magic_arguments.parse_argstring(self.capture, line)
1579 out = not args.no_stdout
1580 err = not args.no_stderr
1581 disp = not args.no_display
1582 with capture_output(out, err, disp) as io:
1583 self.shell.run_cell(cell)
1584 if DisplayHook.semicolon_at_end_of_expression(cell):
1585 if args.output in self.shell.user_ns:
1586 del self.shell.user_ns[args.output]
1587 elif args.output:
1588 self.shell.user_ns[args.output] = io
1590 @skip_doctest
1591 @magic_arguments.magic_arguments()
1592 @magic_arguments.argument("name", type=str, default="default", nargs="?")
1593 @magic_arguments.argument(
1594 "--remove", action="store_true", help="remove the current transformer"
1595 )
1596 @magic_arguments.argument(
1597 "--list", action="store_true", help="list existing transformers name"
1598 )
1599 @magic_arguments.argument(
1600 "--list-all",
1601 action="store_true",
1602 help="list existing transformers name and code template",
1603 )
1604 @line_cell_magic
1605 def code_wrap(self, line, cell=None):
1606 """
1607 Simple magic to quickly define a code transformer for all IPython's future input.
1609 ``__code__`` and ``__ret__`` are special variable that represent the code to run
1610 and the value of the last expression of ``__code__`` respectively.
1612 Examples
1613 --------
1615 .. ipython::
1617 In [1]: %%code_wrap before_after
1618 ...: print('before')
1619 ...: __code__
1620 ...: print('after')
1621 ...: __ret__
1624 In [2]: 1
1625 before
1626 after
1627 Out[2]: 1
1629 In [3]: %code_wrap --list
1630 before_after
1632 In [4]: %code_wrap --list-all
1633 before_after :
1634 print('before')
1635 __code__
1636 print('after')
1637 __ret__
1639 In [5]: %code_wrap --remove before_after
1641 """
1642 args = magic_arguments.parse_argstring(self.code_wrap, line)
1644 if args.list:
1645 for name in self._transformers.keys():
1646 print(name)
1647 return
1648 if args.list_all:
1649 for name, _t in self._transformers.items():
1650 print(name, ":")
1651 print(indent(ast.unparse(_t.template), " "))
1652 print()
1653 return
1655 to_remove = self._transformers.pop(args.name, None)
1656 if to_remove in self.shell.ast_transformers:
1657 self.shell.ast_transformers.remove(to_remove)
1658 if cell is None or args.remove:
1659 return
1661 _trs = ReplaceCodeTransformer(ast.parse(cell))
1663 self._transformers[args.name] = _trs
1664 self.shell.ast_transformers.append(_trs)
1667def parse_breakpoint(text, current_file):
1668 '''Returns (file, line) for file:line and (current_file, line) for line'''
1669 colon = text.find(':')
1670 if colon == -1:
1671 return current_file, int(text)
1672 else:
1673 return text[:colon], int(text[colon+1:])
1676def _format_time(timespan, precision=3):
1677 """Formats the timespan in a human readable form"""
1679 if timespan >= 60.0:
1680 # we have more than a minute, format that in a human readable form
1681 # Idea from http://snipplr.com/view/5713/
1682 parts = [("d", 60 * 60 * 24), ("h", 60 * 60), ("min", 60), ("s", 1)]
1683 time = []
1684 leftover = timespan
1685 for suffix, length in parts:
1686 value = int(leftover / length)
1687 if value > 0:
1688 leftover = leftover % length
1689 time.append("%s%s" % (str(value), suffix))
1690 if leftover < 1:
1691 break
1692 return " ".join(time)
1694 # Unfortunately characters outside of range(128) can cause problems in
1695 # certain terminals.
1696 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1697 # Try to prevent crashes by being more secure than it needs to
1698 # E.g. eclipse is able to print a µ, but has no sys.stdout.encoding set.
1699 units = ["s", "ms", "us", "ns"] # the safe value
1700 if hasattr(sys.stdout, "encoding") and sys.stdout.encoding:
1701 try:
1702 "μ".encode(sys.stdout.encoding)
1703 units = ["s", "ms", "μs", "ns"]
1704 except:
1705 pass
1706 scaling = [1, 1e3, 1e6, 1e9]
1708 if timespan > 0.0:
1709 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1710 else:
1711 order = 3
1712 return "%.*g %s" % (precision, timespan * scaling[order], units[order])