Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/IPython/core/magics/execution.py: 18%
610 statements
« prev ^ index » next coverage.py v7.3.1, created at 2023-09-25 06:05 +0000
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
23from typing import Dict, Any
24from ast import (
25 Assign,
26 Call,
27 Expr,
28 Load,
29 Module,
30 Name,
31 NodeTransformer,
32 Store,
33 parse,
34 unparse,
35)
36from io import StringIO
37from logging import error
38from pathlib import Path
39from pdb import Restart
40from textwrap import dedent, indent
41from warnings import warn
43from IPython.core import magic_arguments, oinspect, page
44from IPython.core.displayhook import DisplayHook
45from IPython.core.error import UsageError
46from IPython.core.macro import Macro
47from IPython.core.magic import (
48 Magics,
49 cell_magic,
50 line_cell_magic,
51 line_magic,
52 magics_class,
53 needs_local_scope,
54 no_var_expand,
55 on_off,
56 output_can_be_silenced,
57)
58from IPython.testing.skipdoctest import skip_doctest
59from IPython.utils.capture import capture_output
60from IPython.utils.contexts import preserve_keys
61from IPython.utils.ipstruct import Struct
62from IPython.utils.module_paths import find_mod
63from IPython.utils.path import get_py_filename, shellglob
64from IPython.utils.timing import clock, clock2
65from IPython.core.magics.ast_mod import ReplaceCodeTransformer
67#-----------------------------------------------------------------------------
68# Magic implementation classes
69#-----------------------------------------------------------------------------
72class TimeitResult(object):
73 """
74 Object returned by the timeit magic with info about the run.
76 Contains the following attributes :
78 loops: (int) number of loops done per measurement
79 repeat: (int) number of times the measurement has been repeated
80 best: (float) best execution time / number
81 all_runs: (list of float) execution time of each run (in s)
82 compile_time: (float) time of statement compilation (s)
84 """
85 def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
86 self.loops = loops
87 self.repeat = repeat
88 self.best = best
89 self.worst = worst
90 self.all_runs = all_runs
91 self.compile_time = compile_time
92 self._precision = precision
93 self.timings = [ dt / self.loops for dt in all_runs]
95 @property
96 def average(self):
97 return math.fsum(self.timings) / len(self.timings)
99 @property
100 def stdev(self):
101 mean = self.average
102 return (math.fsum([(x - mean) ** 2 for x in self.timings]) / len(self.timings)) ** 0.5
104 def __str__(self):
105 pm = '+-'
106 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
107 try:
108 u'\xb1'.encode(sys.stdout.encoding)
109 pm = u'\xb1'
110 except:
111 pass
112 return "{mean} {pm} {std} per loop (mean {pm} std. dev. of {runs} run{run_plural}, {loops:,} loop{loop_plural} each)".format(
113 pm=pm,
114 runs=self.repeat,
115 loops=self.loops,
116 loop_plural="" if self.loops == 1 else "s",
117 run_plural="" if self.repeat == 1 else "s",
118 mean=_format_time(self.average, self._precision),
119 std=_format_time(self.stdev, self._precision),
120 )
122 def _repr_pretty_(self, p , cycle):
123 unic = self.__str__()
124 p.text(u'<TimeitResult : '+unic+u'>')
127class TimeitTemplateFiller(ast.NodeTransformer):
128 """Fill in the AST template for timing execution.
130 This is quite closely tied to the template definition, which is in
131 :meth:`ExecutionMagics.timeit`.
132 """
133 def __init__(self, ast_setup, ast_stmt):
134 self.ast_setup = ast_setup
135 self.ast_stmt = ast_stmt
137 def visit_FunctionDef(self, node):
138 "Fill in the setup statement"
139 self.generic_visit(node)
140 if node.name == "inner":
141 node.body[:1] = self.ast_setup.body
143 return node
145 def visit_For(self, node):
146 "Fill in the statement to be timed"
147 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
148 node.body = self.ast_stmt.body
149 return node
152class Timer(timeit.Timer):
153 """Timer class that explicitly uses self.inner
155 which is an undocumented implementation detail of CPython,
156 not shared by PyPy.
157 """
158 # Timer.timeit copied from CPython 3.4.2
159 def timeit(self, number=timeit.default_number):
160 """Time 'number' executions of the main statement.
162 To be precise, this executes the setup statement once, and
163 then returns the time it takes to execute the main statement
164 a number of times, as a float measured in seconds. The
165 argument is the number of times through the loop, defaulting
166 to one million. The main statement, the setup statement and
167 the timer function to be used are passed to the constructor.
168 """
169 it = itertools.repeat(None, number)
170 gcold = gc.isenabled()
171 gc.disable()
172 try:
173 timing = self.inner(it, self.timer)
174 finally:
175 if gcold:
176 gc.enable()
177 return timing
180@magics_class
181class ExecutionMagics(Magics):
182 """Magics related to code execution, debugging, profiling, etc."""
184 _transformers: Dict[str, Any] = {}
186 def __init__(self, shell):
187 super(ExecutionMagics, self).__init__(shell)
188 # Default execution function used to actually run user code.
189 self.default_runner = None
191 @skip_doctest
192 @no_var_expand
193 @line_cell_magic
194 def prun(self, parameter_s='', cell=None):
196 """Run a statement through the python code profiler.
198 Usage, in line mode:
199 %prun [options] statement
201 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 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
309 list_all=True, posix=False)
310 if cell is not None:
311 arg_str += '\n' + cell
312 arg_str = self.shell.transform_cell(arg_str)
313 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
315 def _run_with_profiler(self, code, opts, namespace):
316 """
317 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
319 Parameters
320 ----------
321 code : str
322 Code to be executed.
323 opts : Struct
324 Options parsed by `self.parse_options`.
325 namespace : dict
326 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
328 """
330 # Fill default values for unspecified options:
331 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
333 prof = profile.Profile()
334 try:
335 prof = prof.runctx(code, namespace, namespace)
336 sys_exit = ''
337 except SystemExit:
338 sys_exit = """*** SystemExit exception caught in code being profiled."""
340 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
342 lims = opts.l
343 if lims:
344 lims = [] # rebuild lims with ints/floats/strings
345 for lim in opts.l:
346 try:
347 lims.append(int(lim))
348 except ValueError:
349 try:
350 lims.append(float(lim))
351 except ValueError:
352 lims.append(lim)
354 # Trap output.
355 stdout_trap = StringIO()
356 stats_stream = stats.stream
357 try:
358 stats.stream = stdout_trap
359 stats.print_stats(*lims)
360 finally:
361 stats.stream = stats_stream
363 output = stdout_trap.getvalue()
364 output = output.rstrip()
366 if 'q' not in opts:
367 page.page(output)
368 print(sys_exit, end=' ')
370 dump_file = opts.D[0]
371 text_file = opts.T[0]
372 if dump_file:
373 prof.dump_stats(dump_file)
374 print(
375 f"\n*** Profile stats marshalled to file {repr(dump_file)}.{sys_exit}"
376 )
377 if text_file:
378 pfile = Path(text_file)
379 pfile.touch(exist_ok=True)
380 pfile.write_text(output, encoding="utf-8")
382 print(
383 f"\n*** Profile printout saved to text file {repr(text_file)}.{sys_exit}"
384 )
386 if 'r' in opts:
387 return stats
389 return None
391 @line_magic
392 def pdb(self, parameter_s=''):
393 """Control the automatic calling of the pdb interactive debugger.
395 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
396 argument it works as a toggle.
398 When an exception is triggered, IPython can optionally call the
399 interactive pdb debugger after the traceback printout. %pdb toggles
400 this feature on and off.
402 The initial state of this feature is set in your configuration
403 file (the option is ``InteractiveShell.pdb``).
405 If you want to just activate the debugger AFTER an exception has fired,
406 without having to type '%pdb on' and rerunning your code, you can use
407 the %debug magic."""
409 par = parameter_s.strip().lower()
411 if par:
412 try:
413 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
414 except KeyError:
415 print ('Incorrect argument. Use on/1, off/0, '
416 'or nothing for a toggle.')
417 return
418 else:
419 # toggle
420 new_pdb = not self.shell.call_pdb
422 # set on the shell
423 self.shell.call_pdb = new_pdb
424 print('Automatic pdb calling has been turned',on_off(new_pdb))
426 @magic_arguments.magic_arguments()
427 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
428 help="""
429 Set break point at LINE in FILE.
430 """
431 )
432 @magic_arguments.argument('statement', nargs='*',
433 help="""
434 Code to run in debugger.
435 You can omit this in cell magic mode.
436 """
437 )
438 @no_var_expand
439 @line_cell_magic
440 @needs_local_scope
441 def debug(self, line="", cell=None, local_ns=None):
442 """Activate the interactive debugger.
444 This magic command support two ways of activating debugger.
445 One is to activate debugger before executing code. This way, you
446 can set a break point, to step through the code from the point.
447 You can use this mode by giving statements to execute and optionally
448 a breakpoint.
450 The other one is to activate debugger in post-mortem mode. You can
451 activate this mode simply running %debug without any argument.
452 If an exception has just occurred, this lets you inspect its stack
453 frames interactively. Note that this will always work only on the last
454 traceback that occurred, so you must call this quickly after an
455 exception that you wish to inspect has fired, because if another one
456 occurs, it clobbers the previous one.
458 If you want IPython to automatically do this on every exception, see
459 the %pdb magic for more details.
461 .. versionchanged:: 7.3
462 When running code, user variables are no longer expanded,
463 the magic line is always left unmodified.
465 """
466 args = magic_arguments.parse_argstring(self.debug, line)
468 if not (args.breakpoint or args.statement or cell):
469 self._debug_post_mortem()
470 elif not (args.breakpoint or cell):
471 # If there is no breakpoints, the line is just code to execute
472 self._debug_exec(line, None, local_ns)
473 else:
474 # Here we try to reconstruct the code from the output of
475 # parse_argstring. This might not work if the code has spaces
476 # For example this fails for `print("a b")`
477 code = "\n".join(args.statement)
478 if cell:
479 code += "\n" + cell
480 self._debug_exec(code, args.breakpoint, local_ns)
482 def _debug_post_mortem(self):
483 self.shell.debugger(force=True)
485 def _debug_exec(self, code, breakpoint, local_ns=None):
486 if breakpoint:
487 (filename, bp_line) = breakpoint.rsplit(':', 1)
488 bp_line = int(bp_line)
489 else:
490 (filename, bp_line) = (None, None)
491 self._run_with_debugger(
492 code, self.shell.user_ns, filename, bp_line, local_ns=local_ns
493 )
495 @line_magic
496 def tb(self, s):
497 """Print the last traceback.
499 Optionally, specify an exception reporting mode, tuning the
500 verbosity of the traceback. By default the currently-active exception
501 mode is used. See %xmode for changing exception reporting modes.
503 Valid modes: Plain, Context, Verbose, and Minimal.
504 """
505 interactive_tb = self.shell.InteractiveTB
506 if s:
507 # Switch exception reporting mode for this one call.
508 # Ensure it is switched back.
509 def xmode_switch_err(name):
510 warn('Error changing %s exception modes.\n%s' %
511 (name,sys.exc_info()[1]))
513 new_mode = s.strip().capitalize()
514 original_mode = interactive_tb.mode
515 try:
516 try:
517 interactive_tb.set_mode(mode=new_mode)
518 except Exception:
519 xmode_switch_err('user')
520 else:
521 self.shell.showtraceback()
522 finally:
523 interactive_tb.set_mode(mode=original_mode)
524 else:
525 self.shell.showtraceback()
527 @skip_doctest
528 @line_magic
529 def run(self, parameter_s='', runner=None,
530 file_finder=get_py_filename):
531 """Run the named file inside IPython as a program.
533 Usage::
535 %run [-n -i -e -G]
536 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
537 ( -m mod | filename ) [args]
539 The filename argument should be either a pure Python script (with
540 extension ``.py``), or a file with custom IPython syntax (such as
541 magics). If the latter, the file can be either a script with ``.ipy``
542 extension, or a Jupyter notebook with ``.ipynb`` extension. When running
543 a Jupyter notebook, the output from print statements and other
544 displayed objects will appear in the terminal (even matplotlib figures
545 will open, if a terminal-compliant backend is being used). Note that,
546 at the system command line, the ``jupyter run`` command offers similar
547 functionality for executing notebooks (albeit currently with some
548 differences in supported options).
550 Parameters after the filename are passed as command-line arguments to
551 the program (put in sys.argv). Then, control returns to IPython's
552 prompt.
554 This is similar to running at a system prompt ``python file args``,
555 but with the advantage of giving you IPython's tracebacks, and of
556 loading all variables into your interactive namespace for further use
557 (unless -p is used, see below).
559 The file is executed in a namespace initially consisting only of
560 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
561 sees its environment as if it were being run as a stand-alone program
562 (except for sharing global objects such as previously imported
563 modules). But after execution, the IPython interactive namespace gets
564 updated with all variables defined in the program (except for __name__
565 and sys.argv). This allows for very convenient loading of code for
566 interactive work, while giving each program a 'clean sheet' to run in.
568 Arguments are expanded using shell-like glob match. Patterns
569 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
570 tilde '~' will be expanded into user's home directory. Unlike
571 real shells, quotation does not suppress expansions. Use
572 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
573 To completely disable these expansions, you can use -G flag.
575 On Windows systems, the use of single quotes `'` when specifying
576 a file is not supported. Use double quotes `"`.
578 Options:
580 -n
581 __name__ is NOT set to '__main__', but to the running file's name
582 without extension (as python does under import). This allows running
583 scripts and reloading the definitions in them without calling code
584 protected by an ``if __name__ == "__main__"`` clause.
586 -i
587 run the file in IPython's namespace instead of an empty one. This
588 is useful if you are experimenting with code written in a text editor
589 which depends on variables defined interactively.
591 -e
592 ignore sys.exit() calls or SystemExit exceptions in the script
593 being run. This is particularly useful if IPython is being used to
594 run unittests, which always exit with a sys.exit() call. In such
595 cases you are interested in the output of the test results, not in
596 seeing a traceback of the unittest module.
598 -t
599 print timing information at the end of the run. IPython will give
600 you an estimated CPU time consumption for your script, which under
601 Unix uses the resource module to avoid the wraparound problems of
602 time.clock(). Under Unix, an estimate of time spent on system tasks
603 is also given (for Windows platforms this is reported as 0.0).
605 If -t is given, an additional ``-N<N>`` option can be given, where <N>
606 must be an integer indicating how many times you want the script to
607 run. The final timing report will include total and per run results.
609 For example (testing the script uniq_stable.py)::
611 In [1]: run -t uniq_stable
613 IPython CPU timings (estimated):
614 User : 0.19597 s.
615 System: 0.0 s.
617 In [2]: run -t -N5 uniq_stable
619 IPython CPU timings (estimated):
620 Total runs performed: 5
621 Times : Total Per run
622 User : 0.910862 s, 0.1821724 s.
623 System: 0.0 s, 0.0 s.
625 -d
626 run your program under the control of pdb, the Python debugger.
627 This allows you to execute your program step by step, watch variables,
628 etc. Internally, what IPython does is similar to calling::
630 pdb.run('execfile("YOURFILENAME")')
632 with a breakpoint set on line 1 of your file. You can change the line
633 number for this automatic breakpoint to be <N> by using the -bN option
634 (where N must be an integer). For example::
636 %run -d -b40 myscript
638 will set the first breakpoint at line 40 in myscript.py. Note that
639 the first breakpoint must be set on a line which actually does
640 something (not a comment or docstring) for it to stop execution.
642 Or you can specify a breakpoint in a different file::
644 %run -d -b myotherfile.py:20 myscript
646 When the pdb debugger starts, you will see a (Pdb) prompt. You must
647 first enter 'c' (without quotes) to start execution up to the first
648 breakpoint.
650 Entering 'help' gives information about the use of the debugger. You
651 can easily see pdb's full documentation with "import pdb;pdb.help()"
652 at a prompt.
654 -p
655 run program under the control of the Python profiler module (which
656 prints a detailed report of execution times, function calls, etc).
658 You can pass other options after -p which affect the behavior of the
659 profiler itself. See the docs for %prun for details.
661 In this mode, the program's variables do NOT propagate back to the
662 IPython interactive namespace (because they remain in the namespace
663 where the profiler executes them).
665 Internally this triggers a call to %prun, see its documentation for
666 details on the options available specifically for profiling.
668 There is one special usage for which the text above doesn't apply:
669 if the filename ends with .ipy[nb], the file is run as ipython script,
670 just as if the commands were written on IPython prompt.
672 -m
673 specify module name to load instead of script path. Similar to
674 the -m option for the python interpreter. Use this option last if you
675 want to combine with other %run options. Unlike the python interpreter
676 only source modules are allowed no .pyc or .pyo files.
677 For example::
679 %run -m example
681 will run the example module.
683 -G
684 disable shell-like glob expansion of arguments.
686 """
688 # Logic to handle issue #3664
689 # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
690 if '-m' in parameter_s and '--' not in parameter_s:
691 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
692 for idx, arg in enumerate(argv):
693 if arg and arg.startswith('-') and arg != '-':
694 if arg == '-m':
695 argv.insert(idx + 2, '--')
696 break
697 else:
698 # Positional arg, break
699 break
700 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
702 # get arguments and set sys.argv for program to be run.
703 opts, arg_lst = self.parse_options(parameter_s,
704 'nidtN:b:pD:l:rs:T:em:G',
705 mode='list', list_all=1)
706 if "m" in opts:
707 modulename = opts["m"][0]
708 modpath = find_mod(modulename)
709 if modpath is None:
710 msg = '%r is not a valid modulename on sys.path'%modulename
711 raise Exception(msg)
712 arg_lst = [modpath] + arg_lst
713 try:
714 fpath = None # initialize to make sure fpath is in scope later
715 fpath = arg_lst[0]
716 filename = file_finder(fpath)
717 except IndexError as e:
718 msg = 'you must provide at least a filename.'
719 raise Exception(msg) from e
720 except IOError as e:
721 try:
722 msg = str(e)
723 except UnicodeError:
724 msg = e.message
725 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
726 warn('For Windows, use double quotes to wrap a filename: %run "mypath\\myfile.py"')
727 raise Exception(msg) from e
728 except TypeError:
729 if fpath in sys.meta_path:
730 filename = ""
731 else:
732 raise
734 if filename.lower().endswith(('.ipy', '.ipynb')):
735 with preserve_keys(self.shell.user_ns, '__file__'):
736 self.shell.user_ns['__file__'] = filename
737 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
738 return
740 # Control the response to exit() calls made by the script being run
741 exit_ignore = 'e' in opts
743 # Make sure that the running script gets a proper sys.argv as if it
744 # were run from a system shell.
745 save_argv = sys.argv # save it for later restoring
747 if 'G' in opts:
748 args = arg_lst[1:]
749 else:
750 # tilde and glob expansion
751 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
753 sys.argv = [filename] + args # put in the proper filename
755 if 'n' in opts:
756 name = Path(filename).stem
757 else:
758 name = '__main__'
760 if 'i' in opts:
761 # Run in user's interactive namespace
762 prog_ns = self.shell.user_ns
763 __name__save = self.shell.user_ns['__name__']
764 prog_ns['__name__'] = name
765 main_mod = self.shell.user_module
767 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
768 # set the __file__ global in the script's namespace
769 # TK: Is this necessary in interactive mode?
770 prog_ns['__file__'] = filename
771 else:
772 # Run in a fresh, empty namespace
774 # The shell MUST hold a reference to prog_ns so after %run
775 # exits, the python deletion mechanism doesn't zero it out
776 # (leaving dangling references). See interactiveshell for details
777 main_mod = self.shell.new_main_mod(filename, name)
778 prog_ns = main_mod.__dict__
780 # pickle fix. See interactiveshell for an explanation. But we need to
781 # make sure that, if we overwrite __main__, we replace it at the end
782 main_mod_name = prog_ns['__name__']
784 if main_mod_name == '__main__':
785 restore_main = sys.modules['__main__']
786 else:
787 restore_main = False
789 # This needs to be undone at the end to prevent holding references to
790 # every single object ever created.
791 sys.modules[main_mod_name] = main_mod
793 if 'p' in opts or 'd' in opts:
794 if 'm' in opts:
795 code = 'run_module(modulename, prog_ns)'
796 code_ns = {
797 'run_module': self.shell.safe_run_module,
798 'prog_ns': prog_ns,
799 'modulename': modulename,
800 }
801 else:
802 if 'd' in opts:
803 # allow exceptions to raise in debug mode
804 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
805 else:
806 code = 'execfile(filename, prog_ns)'
807 code_ns = {
808 'execfile': self.shell.safe_execfile,
809 'prog_ns': prog_ns,
810 'filename': get_py_filename(filename),
811 }
813 try:
814 stats = None
815 if 'p' in opts:
816 stats = self._run_with_profiler(code, opts, code_ns)
817 else:
818 if 'd' in opts:
819 bp_file, bp_line = parse_breakpoint(
820 opts.get('b', ['1'])[0], filename)
821 self._run_with_debugger(
822 code, code_ns, filename, bp_line, bp_file)
823 else:
824 if 'm' in opts:
825 def run():
826 self.shell.safe_run_module(modulename, prog_ns)
827 else:
828 if runner is None:
829 runner = self.default_runner
830 if runner is None:
831 runner = self.shell.safe_execfile
833 def run():
834 runner(filename, prog_ns, prog_ns,
835 exit_ignore=exit_ignore)
837 if 't' in opts:
838 # timed execution
839 try:
840 nruns = int(opts['N'][0])
841 if nruns < 1:
842 error('Number of runs must be >=1')
843 return
844 except (KeyError):
845 nruns = 1
846 self._run_with_timing(run, nruns)
847 else:
848 # regular execution
849 run()
851 if 'i' in opts:
852 self.shell.user_ns['__name__'] = __name__save
853 else:
854 # update IPython interactive namespace
856 # Some forms of read errors on the file may mean the
857 # __name__ key was never set; using pop we don't have to
858 # worry about a possible KeyError.
859 prog_ns.pop('__name__', None)
861 with preserve_keys(self.shell.user_ns, '__file__'):
862 self.shell.user_ns.update(prog_ns)
863 finally:
864 # It's a bit of a mystery why, but __builtins__ can change from
865 # being a module to becoming a dict missing some key data after
866 # %run. As best I can see, this is NOT something IPython is doing
867 # at all, and similar problems have been reported before:
868 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
869 # Since this seems to be done by the interpreter itself, the best
870 # we can do is to at least restore __builtins__ for the user on
871 # exit.
872 self.shell.user_ns['__builtins__'] = builtin_mod
874 # Ensure key global structures are restored
875 sys.argv = save_argv
876 if restore_main:
877 sys.modules['__main__'] = restore_main
878 if '__mp_main__' in sys.modules:
879 sys.modules['__mp_main__'] = restore_main
880 else:
881 # Remove from sys.modules the reference to main_mod we'd
882 # added. Otherwise it will trap references to objects
883 # contained therein.
884 del sys.modules[main_mod_name]
886 return stats
888 def _run_with_debugger(
889 self, code, code_ns, filename=None, bp_line=None, bp_file=None, local_ns=None
890 ):
891 """
892 Run `code` in debugger with a break point.
894 Parameters
895 ----------
896 code : str
897 Code to execute.
898 code_ns : dict
899 A namespace in which `code` is executed.
900 filename : str
901 `code` is ran as if it is in `filename`.
902 bp_line : int, optional
903 Line number of the break point.
904 bp_file : str, optional
905 Path to the file in which break point is specified.
906 `filename` is used if not given.
907 local_ns : dict, optional
908 A local namespace in which `code` is executed.
910 Raises
911 ------
912 UsageError
913 If the break point given by `bp_line` is not valid.
915 """
916 deb = self.shell.InteractiveTB.pdb
917 if not deb:
918 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
919 deb = self.shell.InteractiveTB.pdb
921 # deb.checkline() fails if deb.curframe exists but is None; it can
922 # handle it not existing. https://github.com/ipython/ipython/issues/10028
923 if hasattr(deb, 'curframe'):
924 del deb.curframe
926 # reset Breakpoint state, which is moronically kept
927 # in a class
928 bdb.Breakpoint.next = 1
929 bdb.Breakpoint.bplist = {}
930 bdb.Breakpoint.bpbynumber = [None]
931 deb.clear_all_breaks()
932 if bp_line is not None:
933 # Set an initial breakpoint to stop execution
934 maxtries = 10
935 bp_file = bp_file or filename
936 checkline = deb.checkline(bp_file, bp_line)
937 if not checkline:
938 for bp in range(bp_line + 1, bp_line + maxtries + 1):
939 if deb.checkline(bp_file, bp):
940 break
941 else:
942 msg = ("\nI failed to find a valid line to set "
943 "a breakpoint\n"
944 "after trying up to line: %s.\n"
945 "Please set a valid breakpoint manually "
946 "with the -b option." % bp)
947 raise UsageError(msg)
948 # if we find a good linenumber, set the breakpoint
949 deb.do_break('%s:%s' % (bp_file, bp_line))
951 if filename:
952 # Mimic Pdb._runscript(...)
953 deb._wait_for_mainpyfile = True
954 deb.mainpyfile = deb.canonic(filename)
956 # Start file run
957 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
958 try:
959 if filename:
960 # save filename so it can be used by methods on the deb object
961 deb._exec_filename = filename
962 while True:
963 try:
964 trace = sys.gettrace()
965 deb.run(code, code_ns, local_ns)
966 except Restart:
967 print("Restarting")
968 if filename:
969 deb._wait_for_mainpyfile = True
970 deb.mainpyfile = deb.canonic(filename)
971 continue
972 else:
973 break
974 finally:
975 sys.settrace(trace)
978 except:
979 etype, value, tb = sys.exc_info()
980 # Skip three frames in the traceback: the %run one,
981 # one inside bdb.py, and the command-line typed by the
982 # user (run by exec in pdb itself).
983 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
985 @staticmethod
986 def _run_with_timing(run, nruns):
987 """
988 Run function `run` and print timing information.
990 Parameters
991 ----------
992 run : callable
993 Any callable object which takes no argument.
994 nruns : int
995 Number of times to execute `run`.
997 """
998 twall0 = time.perf_counter()
999 if nruns == 1:
1000 t0 = clock2()
1001 run()
1002 t1 = clock2()
1003 t_usr = t1[0] - t0[0]
1004 t_sys = t1[1] - t0[1]
1005 print("\nIPython CPU timings (estimated):")
1006 print(" User : %10.2f s." % t_usr)
1007 print(" System : %10.2f s." % t_sys)
1008 else:
1009 runs = range(nruns)
1010 t0 = clock2()
1011 for nr in runs:
1012 run()
1013 t1 = clock2()
1014 t_usr = t1[0] - t0[0]
1015 t_sys = t1[1] - t0[1]
1016 print("\nIPython CPU timings (estimated):")
1017 print("Total runs performed:", nruns)
1018 print(" Times : %10s %10s" % ('Total', 'Per run'))
1019 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
1020 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
1021 twall1 = time.perf_counter()
1022 print("Wall time: %10.2f s." % (twall1 - twall0))
1024 @skip_doctest
1025 @no_var_expand
1026 @line_cell_magic
1027 @needs_local_scope
1028 def timeit(self, line='', cell=None, local_ns=None):
1029 """Time execution of a Python statement or expression
1031 Usage, in line mode:
1032 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
1033 or in cell mode:
1034 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
1035 code
1036 code...
1038 Time execution of a Python statement or expression using the timeit
1039 module. This function can be used both as a line and cell magic:
1041 - In line mode you can time a single-line statement (though multiple
1042 ones can be chained with using semicolons).
1044 - In cell mode, the statement in the first line is used as setup code
1045 (executed but not timed) and the body of the cell is timed. The cell
1046 body has access to any variables created in the setup code.
1048 Options:
1049 -n<N>: execute the given statement <N> times in a loop. If <N> is not
1050 provided, <N> is determined so as to get sufficient accuracy.
1052 -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
1053 average result.
1054 Default: 7
1056 -t: use time.time to measure the time, which is the default on Unix.
1057 This function measures wall time.
1059 -c: use time.clock to measure the time, which is the default on
1060 Windows and measures wall time. On Unix, resource.getrusage is used
1061 instead and returns the CPU user time.
1063 -p<P>: use a precision of <P> digits to display the timing result.
1064 Default: 3
1066 -q: Quiet, do not print result.
1068 -o: return a TimeitResult that can be stored in a variable to inspect
1069 the result in more details.
1071 .. versionchanged:: 7.3
1072 User variables are no longer expanded,
1073 the magic line is always left unmodified.
1075 Examples
1076 --------
1077 ::
1079 In [1]: %timeit pass
1080 8.26 ns ± 0.12 ns per loop (mean ± std. dev. of 7 runs, 100000000 loops each)
1082 In [2]: u = None
1084 In [3]: %timeit u is None
1085 29.9 ns ± 0.643 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)
1087 In [4]: %timeit -r 4 u == None
1089 In [5]: import time
1091 In [6]: %timeit -n1 time.sleep(2)
1093 The times reported by %timeit will be slightly higher than those
1094 reported by the timeit.py script when variables are accessed. This is
1095 due to the fact that %timeit executes the statement in the namespace
1096 of the shell, compared with timeit.py, which uses a single setup
1097 statement to import function or create variables. Generally, the bias
1098 does not matter as long as results from timeit.py are not mixed with
1099 those from %timeit."""
1101 opts, stmt = self.parse_options(
1102 line, "n:r:tcp:qo", posix=False, strict=False, preserve_non_opts=True
1103 )
1104 if stmt == "" and cell is None:
1105 return
1107 timefunc = timeit.default_timer
1108 number = int(getattr(opts, "n", 0))
1109 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1110 repeat = int(getattr(opts, "r", default_repeat))
1111 precision = int(getattr(opts, "p", 3))
1112 quiet = 'q' in opts
1113 return_result = 'o' in opts
1114 if hasattr(opts, "t"):
1115 timefunc = time.time
1116 if hasattr(opts, "c"):
1117 timefunc = clock
1119 timer = Timer(timer=timefunc)
1120 # this code has tight coupling to the inner workings of timeit.Timer,
1121 # but is there a better way to achieve that the code stmt has access
1122 # to the shell namespace?
1123 transform = self.shell.transform_cell
1125 if cell is None:
1126 # called as line magic
1127 ast_setup = self.shell.compile.ast_parse("pass")
1128 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1129 else:
1130 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1131 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1133 ast_setup = self.shell.transform_ast(ast_setup)
1134 ast_stmt = self.shell.transform_ast(ast_stmt)
1136 # Check that these compile to valid Python code *outside* the timer func
1137 # Invalid code may become valid when put inside the function & loop,
1138 # which messes up error messages.
1139 # https://github.com/ipython/ipython/issues/10636
1140 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1141 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1143 # This codestring is taken from timeit.template - we fill it in as an
1144 # AST, so that we can apply our AST transformations to the user code
1145 # without affecting the timing code.
1146 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1147 ' setup\n'
1148 ' _t0 = _timer()\n'
1149 ' for _i in _it:\n'
1150 ' stmt\n'
1151 ' _t1 = _timer()\n'
1152 ' return _t1 - _t0\n')
1154 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1155 timeit_ast = ast.fix_missing_locations(timeit_ast)
1157 # Track compilation time so it can be reported if too long
1158 # Minimum time above which compilation time will be reported
1159 tc_min = 0.1
1161 t0 = clock()
1162 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1163 tc = clock()-t0
1165 ns = {}
1166 glob = self.shell.user_ns
1167 # handles global vars with same name as local vars. We store them in conflict_globs.
1168 conflict_globs = {}
1169 if local_ns and cell is None:
1170 for var_name, var_val in glob.items():
1171 if var_name in local_ns:
1172 conflict_globs[var_name] = var_val
1173 glob.update(local_ns)
1175 exec(code, glob, ns)
1176 timer.inner = ns["inner"]
1178 # This is used to check if there is a huge difference between the
1179 # best and worst timings.
1180 # Issue: https://github.com/ipython/ipython/issues/6471
1181 if number == 0:
1182 # determine number so that 0.2 <= total time < 2.0
1183 for index in range(0, 10):
1184 number = 10 ** index
1185 time_number = timer.timeit(number)
1186 if time_number >= 0.2:
1187 break
1189 all_runs = timer.repeat(repeat, number)
1190 best = min(all_runs) / number
1191 worst = max(all_runs) / number
1192 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1194 # Restore global vars from conflict_globs
1195 if conflict_globs:
1196 glob.update(conflict_globs)
1198 if not quiet :
1199 # Check best timing is greater than zero to avoid a
1200 # ZeroDivisionError.
1201 # In cases where the slowest timing is lesser than a microsecond
1202 # we assume that it does not really matter if the fastest
1203 # timing is 4 times faster than the slowest timing or not.
1204 if worst > 4 * best and best > 0 and worst > 1e-6:
1205 print("The slowest run took %0.2f times longer than the "
1206 "fastest. This could mean that an intermediate result "
1207 "is being cached." % (worst / best))
1209 print( timeit_result )
1211 if tc > tc_min:
1212 print("Compiler time: %.2f s" % tc)
1213 if return_result:
1214 return timeit_result
1216 @skip_doctest
1217 @no_var_expand
1218 @needs_local_scope
1219 @line_cell_magic
1220 @output_can_be_silenced
1221 def time(self,line='', cell=None, local_ns=None):
1222 """Time execution of a Python statement or expression.
1224 The CPU and wall clock times are printed, and the value of the
1225 expression (if any) is returned. Note that under Win32, system time
1226 is always reported as 0, since it can not be measured.
1228 This function can be used both as a line and cell magic:
1230 - In line mode you can time a single-line statement (though multiple
1231 ones can be chained with using semicolons).
1233 - In cell mode, you can time the cell body (a directly
1234 following statement raises an error).
1236 This function provides very basic timing functionality. Use the timeit
1237 magic for more control over the measurement.
1239 .. versionchanged:: 7.3
1240 User variables are no longer expanded,
1241 the magic line is always left unmodified.
1243 Examples
1244 --------
1245 ::
1247 In [1]: %time 2**128
1248 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1249 Wall time: 0.00
1250 Out[1]: 340282366920938463463374607431768211456L
1252 In [2]: n = 1000000
1254 In [3]: %time sum(range(n))
1255 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1256 Wall time: 1.37
1257 Out[3]: 499999500000L
1259 In [4]: %time print 'hello world'
1260 hello world
1261 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1262 Wall time: 0.00
1264 .. note::
1265 The time needed by Python to compile the given expression will be
1266 reported if it is more than 0.1s.
1268 In the example below, the actual exponentiation is done by Python
1269 at compilation time, so while the expression can take a noticeable
1270 amount of time to compute, that time is purely due to the
1271 compilation::
1273 In [5]: %time 3**9999;
1274 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1275 Wall time: 0.00 s
1277 In [6]: %time 3**999999;
1278 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1279 Wall time: 0.00 s
1280 Compiler : 0.78 s
1281 """
1282 # fail immediately if the given expression can't be compiled
1284 if line and cell:
1285 raise UsageError("Can't use statement directly after '%%time'!")
1287 if cell:
1288 expr = self.shell.transform_cell(cell)
1289 else:
1290 expr = self.shell.transform_cell(line)
1292 # Minimum time above which parse time will be reported
1293 tp_min = 0.1
1295 t0 = clock()
1296 expr_ast = self.shell.compile.ast_parse(expr)
1297 tp = clock()-t0
1299 # Apply AST transformations
1300 expr_ast = self.shell.transform_ast(expr_ast)
1302 # Minimum time above which compilation time will be reported
1303 tc_min = 0.1
1305 expr_val=None
1306 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1307 mode = 'eval'
1308 source = '<timed eval>'
1309 expr_ast = ast.Expression(expr_ast.body[0].value)
1310 else:
1311 mode = 'exec'
1312 source = '<timed exec>'
1313 # multi-line %%time case
1314 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1315 expr_val= expr_ast.body[-1]
1316 expr_ast = expr_ast.body[:-1]
1317 expr_ast = Module(expr_ast, [])
1318 expr_val = ast.Expression(expr_val.value)
1320 t0 = clock()
1321 code = self.shell.compile(expr_ast, source, mode)
1322 tc = clock()-t0
1324 # skew measurement as little as possible
1325 glob = self.shell.user_ns
1326 wtime = time.time
1327 # time execution
1328 wall_st = wtime()
1329 if mode=='eval':
1330 st = clock2()
1331 try:
1332 out = eval(code, glob, local_ns)
1333 except:
1334 self.shell.showtraceback()
1335 return
1336 end = clock2()
1337 else:
1338 st = clock2()
1339 try:
1340 exec(code, glob, local_ns)
1341 out=None
1342 # multi-line %%time case
1343 if expr_val is not None:
1344 code_2 = self.shell.compile(expr_val, source, 'eval')
1345 out = eval(code_2, glob, local_ns)
1346 except:
1347 self.shell.showtraceback()
1348 return
1349 end = clock2()
1351 wall_end = wtime()
1352 # Compute actual times and report
1353 wall_time = wall_end - wall_st
1354 cpu_user = end[0] - st[0]
1355 cpu_sys = end[1] - st[1]
1356 cpu_tot = cpu_user + cpu_sys
1357 # On windows cpu_sys is always zero, so only total is displayed
1358 if sys.platform != "win32":
1359 print(
1360 f"CPU times: user {_format_time(cpu_user)}, sys: {_format_time(cpu_sys)}, total: {_format_time(cpu_tot)}"
1361 )
1362 else:
1363 print(f"CPU times: total: {_format_time(cpu_tot)}")
1364 print(f"Wall time: {_format_time(wall_time)}")
1365 if tc > tc_min:
1366 print(f"Compiler : {_format_time(tc)}")
1367 if tp > tp_min:
1368 print(f"Parser : {_format_time(tp)}")
1369 return out
1371 @skip_doctest
1372 @line_magic
1373 def macro(self, parameter_s=''):
1374 """Define a macro for future re-execution. It accepts ranges of history,
1375 filenames or string objects.
1377 Usage:\\
1378 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1380 Options:
1382 -r: use 'raw' input. By default, the 'processed' history is used,
1383 so that magics are loaded in their transformed version to valid
1384 Python. If this option is given, the raw input as typed at the
1385 command line is used instead.
1387 -q: quiet macro definition. By default, a tag line is printed
1388 to indicate the macro has been created, and then the contents of
1389 the macro are printed. If this option is given, then no printout
1390 is produced once the macro is created.
1392 This will define a global variable called `name` which is a string
1393 made of joining the slices and lines you specify (n1,n2,... numbers
1394 above) from your input history into a single string. This variable
1395 acts like an automatic function which re-executes those lines as if
1396 you had typed them. You just type 'name' at the prompt and the code
1397 executes.
1399 The syntax for indicating input ranges is described in %history.
1401 Note: as a 'hidden' feature, you can also use traditional python slice
1402 notation, where N:M means numbers N through M-1.
1404 For example, if your history contains (print using %hist -n )::
1406 44: x=1
1407 45: y=3
1408 46: z=x+y
1409 47: print x
1410 48: a=5
1411 49: print 'x',x,'y',y
1413 you can create a macro with lines 44 through 47 (included) and line 49
1414 called my_macro with::
1416 In [55]: %macro my_macro 44-47 49
1418 Now, typing `my_macro` (without quotes) will re-execute all this code
1419 in one pass.
1421 You don't need to give the line-numbers in order, and any given line
1422 number can appear multiple times. You can assemble macros with any
1423 lines from your input history in any order.
1425 The macro is a simple object which holds its value in an attribute,
1426 but IPython's display system checks for macros and executes them as
1427 code instead of printing them when you type their name.
1429 You can view a macro's contents by explicitly printing it with::
1431 print macro_name
1433 """
1434 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1435 if not args: # List existing macros
1436 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1437 if len(args) == 1:
1438 raise UsageError(
1439 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1440 name, codefrom = args[0], " ".join(args[1:])
1442 #print 'rng',ranges # dbg
1443 try:
1444 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1445 except (ValueError, TypeError) as e:
1446 print(e.args[0])
1447 return
1448 macro = Macro(lines)
1449 self.shell.define_macro(name, macro)
1450 if not ( 'q' in opts) :
1451 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1452 print('=== Macro contents: ===')
1453 print(macro, end=' ')
1455 @magic_arguments.magic_arguments()
1456 @magic_arguments.argument('output', type=str, default='', nargs='?',
1457 help="""The name of the variable in which to store output.
1458 This is a utils.io.CapturedIO object with stdout/err attributes
1459 for the text of the captured output.
1461 CapturedOutput also has a show() method for displaying the output,
1462 and __call__ as well, so you can use that to quickly display the
1463 output.
1465 If unspecified, captured output is discarded.
1466 """
1467 )
1468 @magic_arguments.argument('--no-stderr', action="store_true",
1469 help="""Don't capture stderr."""
1470 )
1471 @magic_arguments.argument('--no-stdout', action="store_true",
1472 help="""Don't capture stdout."""
1473 )
1474 @magic_arguments.argument('--no-display', action="store_true",
1475 help="""Don't capture IPython's rich display."""
1476 )
1477 @cell_magic
1478 def capture(self, line, cell):
1479 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1480 args = magic_arguments.parse_argstring(self.capture, line)
1481 out = not args.no_stdout
1482 err = not args.no_stderr
1483 disp = not args.no_display
1484 with capture_output(out, err, disp) as io:
1485 self.shell.run_cell(cell)
1486 if DisplayHook.semicolon_at_end_of_expression(cell):
1487 if args.output in self.shell.user_ns:
1488 del self.shell.user_ns[args.output]
1489 elif args.output:
1490 self.shell.user_ns[args.output] = io
1492 @skip_doctest
1493 @magic_arguments.magic_arguments()
1494 @magic_arguments.argument("name", type=str, default="default", nargs="?")
1495 @magic_arguments.argument(
1496 "--remove", action="store_true", help="remove the current transformer"
1497 )
1498 @magic_arguments.argument(
1499 "--list", action="store_true", help="list existing transformers name"
1500 )
1501 @magic_arguments.argument(
1502 "--list-all",
1503 action="store_true",
1504 help="list existing transformers name and code template",
1505 )
1506 @line_cell_magic
1507 def code_wrap(self, line, cell=None):
1508 """
1509 Simple magic to quickly define a code transformer for all IPython's future imput.
1511 ``__code__`` and ``__ret__`` are special variable that represent the code to run
1512 and the value of the last expression of ``__code__`` respectively.
1514 Examples
1515 --------
1517 .. ipython::
1519 In [1]: %%code_wrap before_after
1520 ...: print('before')
1521 ...: __code__
1522 ...: print('after')
1523 ...: __ret__
1526 In [2]: 1
1527 before
1528 after
1529 Out[2]: 1
1531 In [3]: %code_wrap --list
1532 before_after
1534 In [4]: %code_wrap --list-all
1535 before_after :
1536 print('before')
1537 __code__
1538 print('after')
1539 __ret__
1541 In [5]: %code_wrap --remove before_after
1543 """
1544 args = magic_arguments.parse_argstring(self.code_wrap, line)
1546 if args.list:
1547 for name in self._transformers.keys():
1548 print(name)
1549 return
1550 if args.list_all:
1551 for name, _t in self._transformers.items():
1552 print(name, ":")
1553 print(indent(ast.unparse(_t.template), " "))
1554 print()
1555 return
1557 to_remove = self._transformers.pop(args.name, None)
1558 if to_remove in self.shell.ast_transformers:
1559 self.shell.ast_transformers.remove(to_remove)
1560 if cell is None or args.remove:
1561 return
1563 _trs = ReplaceCodeTransformer(ast.parse(cell))
1565 self._transformers[args.name] = _trs
1566 self.shell.ast_transformers.append(_trs)
1569def parse_breakpoint(text, current_file):
1570 '''Returns (file, line) for file:line and (current_file, line) for line'''
1571 colon = text.find(':')
1572 if colon == -1:
1573 return current_file, int(text)
1574 else:
1575 return text[:colon], int(text[colon+1:])
1577def _format_time(timespan, precision=3):
1578 """Formats the timespan in a human readable form"""
1580 if timespan >= 60.0:
1581 # we have more than a minute, format that in a human readable form
1582 # Idea from http://snipplr.com/view/5713/
1583 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1584 time = []
1585 leftover = timespan
1586 for suffix, length in parts:
1587 value = int(leftover / length)
1588 if value > 0:
1589 leftover = leftover % length
1590 time.append(u'%s%s' % (str(value), suffix))
1591 if leftover < 1:
1592 break
1593 return " ".join(time)
1596 # Unfortunately the unicode 'micro' symbol can cause problems in
1597 # certain terminals.
1598 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1599 # Try to prevent crashes by being more secure than it needs to
1600 # E.g. eclipse is able to print a µ, but has no sys.stdout.encoding set.
1601 units = [u"s", u"ms",u'us',"ns"] # the save value
1602 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1603 try:
1604 u'\xb5'.encode(sys.stdout.encoding)
1605 units = [u"s", u"ms",u'\xb5s',"ns"]
1606 except:
1607 pass
1608 scaling = [1, 1e3, 1e6, 1e9]
1610 if timespan > 0.0:
1611 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1612 else:
1613 order = 3
1614 return "%.*g %s" % (precision, timespan * scaling[order], units[order])