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