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 myscript.py)::
623 In [1]: run -t myscript
625 IPython CPU timings (estimated):
626 User : 0.19597 s.
627 System: 0.0 s.
629 In [2]: run -t -N5 myscript
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 # reset Breakpoint state, which is moronically kept
934 # in a class
935 bdb.Breakpoint.next = 1
936 bdb.Breakpoint.bplist = {}
937 bdb.Breakpoint.bpbynumber = [None]
938 deb.clear_all_breaks()
939 if bp_line is not None:
940 # Set an initial breakpoint to stop execution
941 maxtries = 10
942 bp_file = bp_file or filename
943 checkline = deb.checkline(bp_file, bp_line)
944 if not checkline:
945 for bp in range(bp_line + 1, bp_line + maxtries + 1):
946 if deb.checkline(bp_file, bp):
947 break
948 else:
949 msg = ("\nI failed to find a valid line to set "
950 "a breakpoint\n"
951 "after trying up to line: %s.\n"
952 "Please set a valid breakpoint manually "
953 "with the -b option." % bp)
954 raise UsageError(msg)
955 # if we find a good linenumber, set the breakpoint
956 deb.do_break('%s:%s' % (bp_file, bp_line))
958 if filename:
959 # Mimic Pdb._runscript(...)
960 deb._wait_for_mainpyfile = True
961 deb.mainpyfile = deb.canonic(filename)
963 # Start file run
964 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
965 try:
966 if filename:
967 # save filename so it can be used by methods on the deb object
968 deb._exec_filename = filename
969 while True:
970 try:
971 trace = sys.gettrace()
972 deb.run(code, code_ns, local_ns)
973 except Restart:
974 print("Restarting")
975 if filename:
976 deb._wait_for_mainpyfile = True
977 deb.mainpyfile = deb.canonic(filename)
978 continue
979 else:
980 break
981 finally:
982 sys.settrace(trace)
984 # Perform proper cleanup of the session in case if
985 # it exited with "continue" and not "quit" command
986 if hasattr(deb, "rcLines"):
987 # Run this code defensively in case if custom debugger
988 # class does not implement rcLines, which although public
989 # is an implementation detail of `pdb.Pdb` and not part of
990 # the more generic basic debugger framework (`bdb.Bdb`).
991 deb.set_quit()
992 deb.rcLines.extend(["q"])
993 try:
994 deb.run("", code_ns, local_ns)
995 except StopIteration:
996 # Stop iteration is raised on quit command
997 pass
999 except Exception:
1000 etype, value, tb = sys.exc_info()
1001 # Skip three frames in the traceback: the %run one,
1002 # one inside bdb.py, and the command-line typed by the
1003 # user (run by exec in pdb itself).
1004 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
1006 @staticmethod
1007 def _run_with_timing(run, nruns):
1008 """
1009 Run function `run` and print timing information.
1011 Parameters
1012 ----------
1013 run : callable
1014 Any callable object which takes no argument.
1015 nruns : int
1016 Number of times to execute `run`.
1018 """
1019 twall0 = time.perf_counter()
1020 if nruns == 1:
1021 t0 = clock2()
1022 run()
1023 t1 = clock2()
1024 t_usr = t1[0] - t0[0]
1025 t_sys = t1[1] - t0[1]
1026 print("\nIPython CPU timings (estimated):")
1027 print(" User : %10.2f s." % t_usr)
1028 print(" System : %10.2f s." % t_sys)
1029 else:
1030 runs = range(nruns)
1031 t0 = clock2()
1032 for nr in runs:
1033 run()
1034 t1 = clock2()
1035 t_usr = t1[0] - t0[0]
1036 t_sys = t1[1] - t0[1]
1037 print("\nIPython CPU timings (estimated):")
1038 print("Total runs performed:", nruns)
1039 print(" Times : %10s %10s" % ('Total', 'Per run'))
1040 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
1041 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
1042 twall1 = time.perf_counter()
1043 print("Wall time: %10.2f s." % (twall1 - twall0))
1045 @skip_doctest
1046 @no_var_expand
1047 @line_cell_magic
1048 @needs_local_scope
1049 def timeit(self, line='', cell=None, local_ns=None):
1050 """Time execution of a Python statement or expression
1052 **Usage, in line mode**::
1054 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> [-o|-v <V>]] statement
1056 **or in cell mode**::
1058 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> [-o|-v <V>]] setup_code
1059 code
1060 code...
1062 Time execution of a Python statement or expression using the timeit
1063 module. This function can be used both as a line and cell magic:
1065 - In line mode you can time a single-line statement (though multiple
1066 ones can be chained with using semicolons).
1068 - In cell mode, the statement in the first line is used as setup code
1069 (executed but not timed) and the body of the cell is timed. The cell
1070 body has access to any variables created in the setup code.
1072 Options:
1074 -n<N>
1075 Execute the given statement N times in a loop. If N is not
1076 provided, N is determined so as to get sufficient accuracy.
1078 -r<R>
1079 Number of repeats R, each consisting of N loops, and take the
1080 average result.
1081 Default: 7
1083 -t
1084 Use ``time.time`` to measure the time, which is the default on Unix.
1085 This function measures wall time.
1087 -c
1088 Use ``time.clock`` to measure the time, which is the default on
1089 Windows and measures wall time. On Unix, ``resource.getrusage`` is used
1090 instead and returns the CPU user time.
1092 -p<P>
1093 Use a precision of P digits to display the timing result.
1094 Default: 3
1096 -q
1097 Quiet, do not print result.
1099 -o
1100 Return a ``TimeitResult`` that can be stored in a variable to inspect
1101 the result in more details.
1103 -v <V>
1104 Like ``-o``, but save the ``TimeitResult`` directly to variable <V>.
1106 .. versionchanged:: 7.3
1107 User variables are no longer expanded,
1108 the magic line is always left unmodified.
1110 Examples
1111 --------
1112 ::
1114 In [1]: %timeit pass
1115 8.26 ns ± 0.12 ns per loop (mean ± std. dev. of 7 runs, 100000000 loops each)
1117 In [2]: u = None
1119 In [3]: %timeit u is None
1120 29.9 ns ± 0.643 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)
1122 In [4]: %timeit -r 4 u == None
1124 In [5]: import time
1126 In [6]: %timeit -n1 time.sleep(2)
1128 The times reported by ``%timeit`` will be slightly higher than those
1129 reported by the timeit.py script when variables are accessed. This is
1130 due to the fact that ``%timeit`` executes the statement in the namespace
1131 of the shell, compared with timeit.py, which uses a single setup
1132 statement to import function or create variables. Generally, the bias
1133 does not matter as long as results from timeit.py are not mixed with
1134 those from ``%timeit``."""
1136 # TODO: port to magic_arguments as currently this is duplicated in IPCompleter._extract_code
1137 opts, stmt = self.parse_options(
1138 line, "n:r:tcp:qov:", posix=False, strict=False, preserve_non_opts=True
1139 )
1140 if stmt == "" and cell is None:
1141 return
1143 timefunc = timeit.default_timer
1144 number = int(getattr(opts, "n", 0))
1145 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1146 repeat = int(getattr(opts, "r", default_repeat))
1147 precision = int(getattr(opts, "p", 3))
1148 quiet = "q" in opts
1149 return_result = "o" in opts
1150 save_result = "v" in opts
1151 if hasattr(opts, "t"):
1152 timefunc = time.time
1153 if hasattr(opts, "c"):
1154 timefunc = clock
1156 timer = Timer(timer=timefunc)
1157 # this code has tight coupling to the inner workings of timeit.Timer,
1158 # but is there a better way to achieve that the code stmt has access
1159 # to the shell namespace?
1160 transform = self.shell.transform_cell
1162 if cell is None:
1163 # called as line magic
1164 ast_setup = self.shell.compile.ast_parse("pass")
1165 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1166 else:
1167 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1168 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1170 ast_setup = self.shell.transform_ast(ast_setup)
1171 ast_stmt = self.shell.transform_ast(ast_stmt)
1173 # Check that these compile to valid Python code *outside* the timer func
1174 # Invalid code may become valid when put inside the function & loop,
1175 # which messes up error messages.
1176 # https://github.com/ipython/ipython/issues/10636
1177 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1178 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1180 # This codestring is taken from timeit.template - we fill it in as an
1181 # AST, so that we can apply our AST transformations to the user code
1182 # without affecting the timing code.
1183 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1184 ' setup\n'
1185 ' _t0 = _timer()\n'
1186 ' for _i in _it:\n'
1187 ' stmt\n'
1188 ' _t1 = _timer()\n'
1189 ' return _t1 - _t0\n')
1191 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1192 timeit_ast = ast.fix_missing_locations(timeit_ast)
1194 # Track compilation time so it can be reported if too long
1195 # Minimum time above which compilation time will be reported
1196 tc_min = 0.1
1198 t0 = clock()
1199 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1200 tc = clock()-t0
1202 ns = {}
1203 glob = self.shell.user_ns
1204 # handles global vars with same name as local vars. We store them in conflict_globs.
1205 conflict_globs = {}
1206 if local_ns and cell is None:
1207 for var_name, var_val in glob.items():
1208 if var_name in local_ns:
1209 conflict_globs[var_name] = var_val
1210 glob.update(local_ns)
1212 exec(code, glob, ns)
1213 timer.inner = ns["inner"]
1215 # This is used to check if there is a huge difference between the
1216 # best and worst timings.
1217 # Issue: https://github.com/ipython/ipython/issues/6471
1218 if number == 0:
1219 # determine number so that 0.2 <= total time < 2.0
1220 for index in range(0, 10):
1221 number = 10 ** index
1222 time_number = timer.timeit(number)
1223 if time_number >= 0.2:
1224 break
1226 all_runs = timer.repeat(repeat, number)
1227 best = min(all_runs) / number
1228 worst = max(all_runs) / number
1229 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1231 # Restore global vars from conflict_globs
1232 if conflict_globs:
1233 glob.update(conflict_globs)
1235 if not quiet:
1236 # Check best timing is greater than zero to avoid a
1237 # ZeroDivisionError.
1238 # In cases where the slowest timing is lesser than a microsecond
1239 # we assume that it does not really matter if the fastest
1240 # timing is 4 times faster than the slowest timing or not.
1241 if worst > 4 * best and best > 0 and worst > 1e-6:
1242 print("The slowest run took %0.2f times longer than the "
1243 "fastest. This could mean that an intermediate result "
1244 "is being cached." % (worst / best))
1246 print( timeit_result )
1248 if tc > tc_min:
1249 print("Compiler time: %.2f s" % tc)
1251 if save_result:
1252 self.shell.user_ns[opts.v] = timeit_result
1254 if return_result:
1255 return timeit_result
1257 @no_var_expand
1258 @magic_arguments.magic_arguments()
1259 @magic_arguments.argument(
1260 "--no-raise-error",
1261 action="store_true",
1262 dest="no_raise_error",
1263 help="If given, don't re-raise exceptions",
1264 )
1265 @magic_arguments.kwds(
1266 epilog="""
1267 Any remaining arguments will be treated as code to run.
1268 """
1269 )
1270 @skip_doctest
1271 @needs_local_scope
1272 @line_cell_magic
1273 @output_can_be_silenced
1274 def time(self, line="", cell=None, local_ns=None):
1275 """Time execution of a Python statement or expression.
1277 The CPU and wall clock times are printed, and the value of the
1278 expression (if any) is returned. Note that under Win32, system time
1279 is always reported as 0, since it can not be measured.
1281 This function can be used both as a line and cell magic:
1283 - In line mode you can time a single-line statement (though multiple
1284 ones can be chained with using semicolons).
1286 - In cell mode, you can time the cell body (a directly
1287 following statement raises an error).
1289 This function provides very basic timing functionality. Use the timeit
1290 magic for more control over the measurement.
1292 .. versionchanged:: 7.3
1293 User variables are no longer expanded,
1294 the magic line is always left unmodified.
1296 .. versionchanged:: 8.3
1297 The time magic now correctly propagates system-exiting exceptions
1298 (such as ``KeyboardInterrupt`` invoked when interrupting execution)
1299 rather than just printing out the exception traceback.
1300 The non-system-exception will still be caught as before.
1302 Examples
1303 --------
1304 ::
1306 In [1]: %time 2**128
1307 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1308 Wall time: 0.00
1309 Out[1]: 340282366920938463463374607431768211456L
1311 In [2]: n = 1000000
1313 In [3]: %time sum(range(n))
1314 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1315 Wall time: 1.37
1316 Out[3]: 499999500000L
1318 In [4]: %time print('hello world')
1319 hello world
1320 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1321 Wall time: 0.00
1323 .. note::
1324 The time needed by Python to compile the given expression will be
1325 reported if it is more than 0.1s.
1327 In the example below, the actual exponentiation is done by Python
1328 at compilation time, so while the expression can take a noticeable
1329 amount of time to compute, that time is purely due to the
1330 compilation::
1332 In [5]: %time 3**9999;
1333 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1334 Wall time: 0.00 s
1336 In [6]: %time 3**999999;
1337 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1338 Wall time: 0.00 s
1339 Compiler : 0.78 s
1340 """
1341 args, extra = magic_arguments.parse_argstring(self.time, line, partial=True)
1342 line = " ".join(extra)
1344 if line and cell:
1345 raise UsageError("Can't use statement directly after '%%time'!")
1347 if cell:
1348 expr = self.shell.transform_cell(cell)
1349 else:
1350 expr = self.shell.transform_cell(line)
1352 # Minimum time above which parse time will be reported
1353 tp_min = 0.1
1355 t0 = clock()
1356 expr_ast = self.shell.compile.ast_parse(expr)
1357 tp = clock() - t0
1359 # Apply AST transformations
1360 expr_ast = self.shell.transform_ast(expr_ast)
1362 # Minimum time above which compilation time will be reported
1363 tc_min = 0.1
1365 expr_val = None
1366 if len(expr_ast.body) == 1 and isinstance(expr_ast.body[0], ast.Expr):
1367 mode = 'eval'
1368 source = '<timed eval>'
1369 expr_ast = ast.Expression(expr_ast.body[0].value)
1370 else:
1371 mode = 'exec'
1372 source = '<timed exec>'
1373 # multi-line %%time case
1374 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1375 expr_val = expr_ast.body[-1]
1376 expr_ast = expr_ast.body[:-1]
1377 expr_ast = Module(expr_ast, [])
1378 expr_val = ast.Expression(expr_val.value)
1380 t0 = clock()
1381 code = self.shell.compile(expr_ast, source, mode)
1382 tc = clock() - t0
1384 # skew measurement as little as possible
1385 glob = self.shell.user_ns
1386 wtime = time.time
1387 # time execution
1388 wall_st = wtime()
1389 # Track whether to propagate exceptions or exit
1390 exit_on_interrupt = False
1391 interrupt_occured = False
1392 captured_exception = None
1394 if mode == "eval":
1395 st = clock2()
1396 try:
1397 out = eval(code, glob, local_ns)
1398 except KeyboardInterrupt as e:
1399 captured_exception = e
1400 interrupt_occured = True
1401 exit_on_interrupt = True
1402 except Exception as e:
1403 captured_exception = e
1404 interrupt_occured = True
1405 if not args.no_raise_error:
1406 exit_on_interrupt = True
1407 end = clock2()
1408 else:
1409 st = clock2()
1410 try:
1411 exec(code, glob, local_ns)
1412 out = None
1413 # multi-line %%time case
1414 if expr_val is not None:
1415 code_2 = self.shell.compile(expr_val, source, 'eval')
1416 out = eval(code_2, glob, local_ns)
1417 except KeyboardInterrupt as e:
1418 captured_exception = e
1419 interrupt_occured = True
1420 exit_on_interrupt = True
1421 except Exception as e:
1422 captured_exception = e
1423 interrupt_occured = True
1424 if not args.no_raise_error:
1425 exit_on_interrupt = True
1426 end = clock2()
1427 wall_end = wtime()
1428 # Compute actual times and report
1429 wall_time = wall_end - wall_st
1430 cpu_user = end[0] - st[0]
1431 cpu_sys = end[1] - st[1]
1432 cpu_tot = cpu_user + cpu_sys
1433 # On windows cpu_sys is always zero, so only total is displayed
1434 if sys.platform != "win32":
1435 print(
1436 f"CPU times: user {_format_time(cpu_user)}, sys: {_format_time(cpu_sys)}, total: {_format_time(cpu_tot)}"
1437 )
1438 else:
1439 print(f"CPU times: total: {_format_time(cpu_tot)}")
1440 print(f"Wall time: {_format_time(wall_time)}")
1441 if tc > tc_min:
1442 print(f"Compiler : {_format_time(tc)}")
1443 if tp > tp_min:
1444 print(f"Parser : {_format_time(tp)}")
1445 if interrupt_occured:
1446 if exit_on_interrupt and captured_exception:
1447 raise captured_exception
1448 return
1449 return out
1451 @skip_doctest
1452 @line_magic
1453 def macro(self, parameter_s=''):
1454 """Define a macro for future re-execution. It accepts ranges of history,
1455 filenames or string objects.
1457 Usage::
1459 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1461 Options:
1463 -r
1464 Use 'raw' input. By default, the 'processed' history is used,
1465 so that magics are loaded in their transformed version to valid
1466 Python. If this option is given, the raw input as typed at the
1467 command line is used instead.
1469 -q
1470 Quiet macro definition. By default, a tag line is printed
1471 to indicate the macro has been created, and then the contents of
1472 the macro are printed. If this option is given, then no printout
1473 is produced once the macro is created.
1475 This will define a global variable called `name` which is a string
1476 made of joining the slices and lines you specify (n1,n2,... numbers
1477 above) from your input history into a single string. This variable
1478 acts like an automatic function which re-executes those lines as if
1479 you had typed them. You just type 'name' at the prompt and the code
1480 executes.
1482 The syntax for indicating input ranges is described in %history.
1484 Note: as a 'hidden' feature, you can also use traditional python slice
1485 notation, where N:M means numbers N through M-1.
1487 For example, if your history contains (print using %hist -n )::
1489 44: x=1
1490 45: y=3
1491 46: z=x+y
1492 47: print(x)
1493 48: a=5
1494 49: print('x',x,'y',y)
1496 you can create a macro with lines 44 through 47 (included) and line 49
1497 called my_macro with::
1499 In [55]: %macro my_macro 44-47 49
1501 Now, typing `my_macro` (without quotes) will re-execute all this code
1502 in one pass.
1504 You don't need to give the line-numbers in order, and any given line
1505 number can appear multiple times. You can assemble macros with any
1506 lines from your input history in any order.
1508 The macro is a simple object which holds its value in an attribute,
1509 but IPython's display system checks for macros and executes them as
1510 code instead of printing them when you type their name.
1512 You can view a macro's contents by explicitly printing it with::
1514 print(macro_name)
1516 """
1517 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1518 if not args: # List existing macros
1519 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1520 if len(args) == 1:
1521 raise UsageError(
1522 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1523 name, codefrom = args[0], " ".join(args[1:])
1525 # print('rng',ranges) # dbg
1526 try:
1527 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1528 except (ValueError, TypeError) as e:
1529 print(e.args[0])
1530 return
1531 macro = Macro(lines)
1532 self.shell.define_macro(name, macro)
1533 if "q" not in opts:
1534 print(
1535 "Macro `%s` created. To execute, type its name (without quotes)." % name
1536 )
1537 print("=== Macro contents: ===")
1538 print(macro, end=" ")
1540 @magic_arguments.magic_arguments()
1541 @magic_arguments.argument(
1542 "output",
1543 type=str,
1544 default="",
1545 nargs="?",
1546 help="""
1548 The name of the variable in which to store output.
1549 This is a ``utils.io.CapturedIO`` object with stdout/err attributes
1550 for the text of the captured output.
1552 CapturedOutput also has a ``show()`` method for displaying the output,
1553 and ``__call__`` as well, so you can use that to quickly display the
1554 output.
1556 If unspecified, captured output is discarded.
1557 """,
1558 )
1559 @magic_arguments.argument(
1560 "--no-stderr", action="store_true", help="""Don't capture stderr."""
1561 )
1562 @magic_arguments.argument(
1563 "--no-stdout", action="store_true", help="""Don't capture stdout."""
1564 )
1565 @magic_arguments.argument(
1566 "--no-display",
1567 action="store_true",
1568 help="""Don't capture IPython's rich display."""
1569 )
1570 @cell_magic
1571 def capture(self, line, cell):
1572 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1573 args = magic_arguments.parse_argstring(self.capture, line)
1574 out = not args.no_stdout
1575 err = not args.no_stderr
1576 disp = not args.no_display
1577 with capture_output(out, err, disp) as io:
1578 self.shell.run_cell(cell)
1579 if DisplayHook.semicolon_at_end_of_expression(cell):
1580 if args.output in self.shell.user_ns:
1581 del self.shell.user_ns[args.output]
1582 elif args.output:
1583 self.shell.user_ns[args.output] = io
1585 @skip_doctest
1586 @magic_arguments.magic_arguments()
1587 @magic_arguments.argument("name", type=str, default="default", nargs="?")
1588 @magic_arguments.argument(
1589 "--remove", action="store_true", help="remove the current transformer"
1590 )
1591 @magic_arguments.argument(
1592 "--list", action="store_true", help="list existing transformers name"
1593 )
1594 @magic_arguments.argument(
1595 "--list-all",
1596 action="store_true",
1597 help="list existing transformers name and code template",
1598 )
1599 @line_cell_magic
1600 def code_wrap(self, line, cell=None):
1601 """
1602 Simple magic to quickly define a code transformer for all IPython's future input.
1604 ``__code__`` and ``__ret__`` are special variable that represent the code to run
1605 and the value of the last expression of ``__code__`` respectively.
1607 Examples
1608 --------
1610 .. ipython::
1612 In [1]: %%code_wrap before_after
1613 ...: print('before')
1614 ...: __code__
1615 ...: print('after')
1616 ...: __ret__
1619 In [2]: 1
1620 before
1621 after
1622 Out[2]: 1
1624 In [3]: %code_wrap --list
1625 before_after
1627 In [4]: %code_wrap --list-all
1628 before_after :
1629 print('before')
1630 __code__
1631 print('after')
1632 __ret__
1634 In [5]: %code_wrap --remove before_after
1636 """
1637 args = magic_arguments.parse_argstring(self.code_wrap, line)
1639 if args.list:
1640 for name in self._transformers.keys():
1641 print(name)
1642 return
1643 if args.list_all:
1644 for name, _t in self._transformers.items():
1645 print(name, ":")
1646 print(indent(ast.unparse(_t.template), " "))
1647 print()
1648 return
1650 to_remove = self._transformers.pop(args.name, None)
1651 if to_remove in self.shell.ast_transformers:
1652 self.shell.ast_transformers.remove(to_remove)
1653 if cell is None or args.remove:
1654 return
1656 _trs = ReplaceCodeTransformer(ast.parse(cell))
1658 self._transformers[args.name] = _trs
1659 self.shell.ast_transformers.append(_trs)
1662def parse_breakpoint(text, current_file):
1663 '''Returns (file, line) for file:line and (current_file, line) for line'''
1664 colon = text.find(':')
1665 if colon == -1:
1666 return current_file, int(text)
1667 else:
1668 return text[:colon], int(text[colon+1:])
1671def _format_time(timespan, precision=3):
1672 """Formats the timespan in a human readable form"""
1674 if timespan >= 60.0:
1675 # we have more than a minute, format that in a human readable form
1676 # Idea from http://snipplr.com/view/5713/
1677 parts = [("d", 60 * 60 * 24), ("h", 60 * 60), ("min", 60), ("s", 1)]
1678 time = []
1679 leftover = timespan
1680 for suffix, length in parts:
1681 value = int(leftover / length)
1682 if value > 0:
1683 leftover = leftover % length
1684 time.append("%s%s" % (str(value), suffix))
1685 if leftover < 1:
1686 break
1687 return " ".join(time)
1689 # Unfortunately characters outside of range(128) can cause problems in
1690 # certain terminals.
1691 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1692 # Try to prevent crashes by being more secure than it needs to
1693 # E.g. eclipse is able to print a µ, but has no sys.stdout.encoding set.
1694 units = ["s", "ms", "us", "ns"] # the safe value
1695 if hasattr(sys.stdout, "encoding") and sys.stdout.encoding:
1696 try:
1697 "μ".encode(sys.stdout.encoding)
1698 units = ["s", "ms", "μs", "ns"]
1699 except:
1700 pass
1701 scaling = [1, 1e3, 1e6, 1e9]
1703 if timespan > 0.0:
1704 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1705 else:
1706 order = 3
1707 return "%.*g %s" % (precision, timespan * scaling[order], units[order])