Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/IPython/core/magics/execution.py: 17%
578 statements
« prev ^ index » next coverage.py v7.4.4, created at 2024-04-20 06:09 +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 cProfile as profile
12import gc
13import itertools
14import math
15import os
16import pstats
17import re
18import shlex
19import sys
20import time
21import timeit
22from ast import Module
23from io import StringIO
24from logging import error
25from pathlib import Path
26from pdb import Restart
27from warnings import warn
29from IPython.core import magic_arguments, oinspect, page
30from IPython.core.error import UsageError
31from IPython.core.macro import Macro
32from IPython.core.magic import (
33 Magics,
34 cell_magic,
35 line_cell_magic,
36 line_magic,
37 magics_class,
38 needs_local_scope,
39 no_var_expand,
40 output_can_be_silenced,
41 on_off,
42)
43from IPython.testing.skipdoctest import skip_doctest
44from IPython.utils.capture import capture_output
45from IPython.utils.contexts import preserve_keys
46from IPython.utils.ipstruct import Struct
47from IPython.utils.module_paths import find_mod
48from IPython.utils.path import get_py_filename, shellglob
49from IPython.utils.timing import clock, clock2
50from IPython.core.displayhook import DisplayHook
52#-----------------------------------------------------------------------------
53# Magic implementation classes
54#-----------------------------------------------------------------------------
57class TimeitResult(object):
58 """
59 Object returned by the timeit magic with info about the run.
61 Contains the following attributes :
63 loops: (int) number of loops done per measurement
64 repeat: (int) number of times the measurement has been repeated
65 best: (float) best execution time / number
66 all_runs: (list of float) execution time of each run (in s)
67 compile_time: (float) time of statement compilation (s)
69 """
70 def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
71 self.loops = loops
72 self.repeat = repeat
73 self.best = best
74 self.worst = worst
75 self.all_runs = all_runs
76 self.compile_time = compile_time
77 self._precision = precision
78 self.timings = [ dt / self.loops for dt in all_runs]
80 @property
81 def average(self):
82 return math.fsum(self.timings) / len(self.timings)
84 @property
85 def stdev(self):
86 mean = self.average
87 return (math.fsum([(x - mean) ** 2 for x in self.timings]) / len(self.timings)) ** 0.5
89 def __str__(self):
90 pm = '+-'
91 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
92 try:
93 u'\xb1'.encode(sys.stdout.encoding)
94 pm = u'\xb1'
95 except:
96 pass
97 return "{mean} {pm} {std} per loop (mean {pm} std. dev. of {runs} run{run_plural}, {loops:,} loop{loop_plural} each)".format(
98 pm=pm,
99 runs=self.repeat,
100 loops=self.loops,
101 loop_plural="" if self.loops == 1 else "s",
102 run_plural="" if self.repeat == 1 else "s",
103 mean=_format_time(self.average, self._precision),
104 std=_format_time(self.stdev, self._precision),
105 )
107 def _repr_pretty_(self, p , cycle):
108 unic = self.__str__()
109 p.text(u'<TimeitResult : '+unic+u'>')
112class TimeitTemplateFiller(ast.NodeTransformer):
113 """Fill in the AST template for timing execution.
115 This is quite closely tied to the template definition, which is in
116 :meth:`ExecutionMagics.timeit`.
117 """
118 def __init__(self, ast_setup, ast_stmt):
119 self.ast_setup = ast_setup
120 self.ast_stmt = ast_stmt
122 def visit_FunctionDef(self, node):
123 "Fill in the setup statement"
124 self.generic_visit(node)
125 if node.name == "inner":
126 node.body[:1] = self.ast_setup.body
128 return node
130 def visit_For(self, node):
131 "Fill in the statement to be timed"
132 if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
133 node.body = self.ast_stmt.body
134 return node
137class Timer(timeit.Timer):
138 """Timer class that explicitly uses self.inner
140 which is an undocumented implementation detail of CPython,
141 not shared by PyPy.
142 """
143 # Timer.timeit copied from CPython 3.4.2
144 def timeit(self, number=timeit.default_number):
145 """Time 'number' executions of the main statement.
147 To be precise, this executes the setup statement once, and
148 then returns the time it takes to execute the main statement
149 a number of times, as a float measured in seconds. The
150 argument is the number of times through the loop, defaulting
151 to one million. The main statement, the setup statement and
152 the timer function to be used are passed to the constructor.
153 """
154 it = itertools.repeat(None, number)
155 gcold = gc.isenabled()
156 gc.disable()
157 try:
158 timing = self.inner(it, self.timer)
159 finally:
160 if gcold:
161 gc.enable()
162 return timing
165@magics_class
166class ExecutionMagics(Magics):
167 """Magics related to code execution, debugging, profiling, etc.
169 """
171 def __init__(self, shell):
172 super(ExecutionMagics, self).__init__(shell)
173 # Default execution function used to actually run user code.
174 self.default_runner = None
176 @skip_doctest
177 @no_var_expand
178 @line_cell_magic
179 def prun(self, parameter_s='', cell=None):
181 """Run a statement through the python code profiler.
183 Usage, in line mode:
184 %prun [options] statement
186 Usage, in cell mode:
187 %%prun [options] [statement]
188 code...
189 code...
191 In cell mode, the additional code lines are appended to the (possibly
192 empty) statement in the first line. Cell mode allows you to easily
193 profile multiline blocks without having to put them in a separate
194 function.
196 The given statement (which doesn't require quote marks) is run via the
197 python profiler in a manner similar to the profile.run() function.
198 Namespaces are internally managed to work correctly; profile.run
199 cannot be used in IPython because it makes certain assumptions about
200 namespaces which do not hold under IPython.
202 Options:
204 -l <limit>
205 you can place restrictions on what or how much of the
206 profile gets printed. The limit value can be:
208 * A string: only information for function names containing this string
209 is printed.
211 * An integer: only these many lines are printed.
213 * A float (between 0 and 1): this fraction of the report is printed
214 (for example, use a limit of 0.4 to see the topmost 40% only).
216 You can combine several limits with repeated use of the option. For
217 example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
218 information about class constructors.
220 -r
221 return the pstats.Stats object generated by the profiling. This
222 object has all the information about the profile in it, and you can
223 later use it for further analysis or in other functions.
225 -s <key>
226 sort profile by given key. You can provide more than one key
227 by using the option several times: '-s key1 -s key2 -s key3...'. The
228 default sorting key is 'time'.
230 The following is copied verbatim from the profile documentation
231 referenced below:
233 When more than one key is provided, additional keys are used as
234 secondary criteria when the there is equality in all keys selected
235 before them.
237 Abbreviations can be used for any key names, as long as the
238 abbreviation is unambiguous. The following are the keys currently
239 defined:
241 ============ =====================
242 Valid Arg Meaning
243 ============ =====================
244 "calls" call count
245 "cumulative" cumulative time
246 "file" file name
247 "module" file name
248 "pcalls" primitive call count
249 "line" line number
250 "name" function name
251 "nfl" name/file/line
252 "stdname" standard name
253 "time" internal time
254 ============ =====================
256 Note that all sorts on statistics are in descending order (placing
257 most time consuming items first), where as name, file, and line number
258 searches are in ascending order (i.e., alphabetical). The subtle
259 distinction between "nfl" and "stdname" is that the standard name is a
260 sort of the name as printed, which means that the embedded line
261 numbers get compared in an odd way. For example, lines 3, 20, and 40
262 would (if the file names were the same) appear in the string order
263 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
264 line numbers. In fact, sort_stats("nfl") is the same as
265 sort_stats("name", "file", "line").
267 -T <filename>
268 save profile results as shown on screen to a text
269 file. The profile is still shown on screen.
271 -D <filename>
272 save (via dump_stats) profile statistics to given
273 filename. This data is in a format understood by the pstats module, and
274 is generated by a call to the dump_stats() method of profile
275 objects. The profile is still shown on screen.
277 -q
278 suppress output to the pager. Best used with -T and/or -D above.
280 If you want to run complete programs under the profiler's control, use
281 ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
282 contains profiler specific options as described here.
284 You can read the complete documentation for the profile module with::
286 In [1]: import profile; profile.help()
288 .. versionchanged:: 7.3
289 User variables are no longer expanded,
290 the magic line is always left unmodified.
292 """
293 opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
294 list_all=True, posix=False)
295 if cell is not None:
296 arg_str += '\n' + cell
297 arg_str = self.shell.transform_cell(arg_str)
298 return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
300 def _run_with_profiler(self, code, opts, namespace):
301 """
302 Run `code` with profiler. Used by ``%prun`` and ``%run -p``.
304 Parameters
305 ----------
306 code : str
307 Code to be executed.
308 opts : Struct
309 Options parsed by `self.parse_options`.
310 namespace : dict
311 A dictionary for Python namespace (e.g., `self.shell.user_ns`).
313 """
315 # Fill default values for unspecified options:
316 opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
318 prof = profile.Profile()
319 try:
320 prof = prof.runctx(code, namespace, namespace)
321 sys_exit = ''
322 except SystemExit:
323 sys_exit = """*** SystemExit exception caught in code being profiled."""
325 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
327 lims = opts.l
328 if lims:
329 lims = [] # rebuild lims with ints/floats/strings
330 for lim in opts.l:
331 try:
332 lims.append(int(lim))
333 except ValueError:
334 try:
335 lims.append(float(lim))
336 except ValueError:
337 lims.append(lim)
339 # Trap output.
340 stdout_trap = StringIO()
341 stats_stream = stats.stream
342 try:
343 stats.stream = stdout_trap
344 stats.print_stats(*lims)
345 finally:
346 stats.stream = stats_stream
348 output = stdout_trap.getvalue()
349 output = output.rstrip()
351 if 'q' not in opts:
352 page.page(output)
353 print(sys_exit, end=' ')
355 dump_file = opts.D[0]
356 text_file = opts.T[0]
357 if dump_file:
358 prof.dump_stats(dump_file)
359 print(
360 f"\n*** Profile stats marshalled to file {repr(dump_file)}.{sys_exit}"
361 )
362 if text_file:
363 pfile = Path(text_file)
364 pfile.touch(exist_ok=True)
365 pfile.write_text(output, encoding="utf-8")
367 print(
368 f"\n*** Profile printout saved to text file {repr(text_file)}.{sys_exit}"
369 )
371 if 'r' in opts:
372 return stats
374 return None
376 @line_magic
377 def pdb(self, parameter_s=''):
378 """Control the automatic calling of the pdb interactive debugger.
380 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
381 argument it works as a toggle.
383 When an exception is triggered, IPython can optionally call the
384 interactive pdb debugger after the traceback printout. %pdb toggles
385 this feature on and off.
387 The initial state of this feature is set in your configuration
388 file (the option is ``InteractiveShell.pdb``).
390 If you want to just activate the debugger AFTER an exception has fired,
391 without having to type '%pdb on' and rerunning your code, you can use
392 the %debug magic."""
394 par = parameter_s.strip().lower()
396 if par:
397 try:
398 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
399 except KeyError:
400 print ('Incorrect argument. Use on/1, off/0, '
401 'or nothing for a toggle.')
402 return
403 else:
404 # toggle
405 new_pdb = not self.shell.call_pdb
407 # set on the shell
408 self.shell.call_pdb = new_pdb
409 print('Automatic pdb calling has been turned',on_off(new_pdb))
411 @magic_arguments.magic_arguments()
412 @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
413 help="""
414 Set break point at LINE in FILE.
415 """
416 )
417 @magic_arguments.argument('statement', nargs='*',
418 help="""
419 Code to run in debugger.
420 You can omit this in cell magic mode.
421 """
422 )
423 @no_var_expand
424 @line_cell_magic
425 @needs_local_scope
426 def debug(self, line="", cell=None, local_ns=None):
427 """Activate the interactive debugger.
429 This magic command support two ways of activating debugger.
430 One is to activate debugger before executing code. This way, you
431 can set a break point, to step through the code from the point.
432 You can use this mode by giving statements to execute and optionally
433 a breakpoint.
435 The other one is to activate debugger in post-mortem mode. You can
436 activate this mode simply running %debug without any argument.
437 If an exception has just occurred, this lets you inspect its stack
438 frames interactively. Note that this will always work only on the last
439 traceback that occurred, so you must call this quickly after an
440 exception that you wish to inspect has fired, because if another one
441 occurs, it clobbers the previous one.
443 If you want IPython to automatically do this on every exception, see
444 the %pdb magic for more details.
446 .. versionchanged:: 7.3
447 When running code, user variables are no longer expanded,
448 the magic line is always left unmodified.
450 """
451 args = magic_arguments.parse_argstring(self.debug, line)
453 if not (args.breakpoint or args.statement or cell):
454 self._debug_post_mortem()
455 elif not (args.breakpoint or cell):
456 # If there is no breakpoints, the line is just code to execute
457 self._debug_exec(line, None, local_ns)
458 else:
459 # Here we try to reconstruct the code from the output of
460 # parse_argstring. This might not work if the code has spaces
461 # For example this fails for `print("a b")`
462 code = "\n".join(args.statement)
463 if cell:
464 code += "\n" + cell
465 self._debug_exec(code, args.breakpoint, local_ns)
467 def _debug_post_mortem(self):
468 self.shell.debugger(force=True)
470 def _debug_exec(self, code, breakpoint, local_ns=None):
471 if breakpoint:
472 (filename, bp_line) = breakpoint.rsplit(':', 1)
473 bp_line = int(bp_line)
474 else:
475 (filename, bp_line) = (None, None)
476 self._run_with_debugger(
477 code, self.shell.user_ns, filename, bp_line, local_ns=local_ns
478 )
480 @line_magic
481 def tb(self, s):
482 """Print the last traceback.
484 Optionally, specify an exception reporting mode, tuning the
485 verbosity of the traceback. By default the currently-active exception
486 mode is used. See %xmode for changing exception reporting modes.
488 Valid modes: Plain, Context, Verbose, and Minimal.
489 """
490 interactive_tb = self.shell.InteractiveTB
491 if s:
492 # Switch exception reporting mode for this one call.
493 # Ensure it is switched back.
494 def xmode_switch_err(name):
495 warn('Error changing %s exception modes.\n%s' %
496 (name,sys.exc_info()[1]))
498 new_mode = s.strip().capitalize()
499 original_mode = interactive_tb.mode
500 try:
501 try:
502 interactive_tb.set_mode(mode=new_mode)
503 except Exception:
504 xmode_switch_err('user')
505 else:
506 self.shell.showtraceback()
507 finally:
508 interactive_tb.set_mode(mode=original_mode)
509 else:
510 self.shell.showtraceback()
512 @skip_doctest
513 @line_magic
514 def run(self, parameter_s='', runner=None,
515 file_finder=get_py_filename):
516 """Run the named file inside IPython as a program.
518 Usage::
520 %run [-n -i -e -G]
521 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
522 ( -m mod | filename ) [args]
524 The filename argument should be either a pure Python script (with
525 extension ``.py``), or a file with custom IPython syntax (such as
526 magics). If the latter, the file can be either a script with ``.ipy``
527 extension, or a Jupyter notebook with ``.ipynb`` extension. When running
528 a Jupyter notebook, the output from print statements and other
529 displayed objects will appear in the terminal (even matplotlib figures
530 will open, if a terminal-compliant backend is being used). Note that,
531 at the system command line, the ``jupyter run`` command offers similar
532 functionality for executing notebooks (albeit currently with some
533 differences in supported options).
535 Parameters after the filename are passed as command-line arguments to
536 the program (put in sys.argv). Then, control returns to IPython's
537 prompt.
539 This is similar to running at a system prompt ``python file args``,
540 but with the advantage of giving you IPython's tracebacks, and of
541 loading all variables into your interactive namespace for further use
542 (unless -p is used, see below).
544 The file is executed in a namespace initially consisting only of
545 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
546 sees its environment as if it were being run as a stand-alone program
547 (except for sharing global objects such as previously imported
548 modules). But after execution, the IPython interactive namespace gets
549 updated with all variables defined in the program (except for __name__
550 and sys.argv). This allows for very convenient loading of code for
551 interactive work, while giving each program a 'clean sheet' to run in.
553 Arguments are expanded using shell-like glob match. Patterns
554 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
555 tilde '~' will be expanded into user's home directory. Unlike
556 real shells, quotation does not suppress expansions. Use
557 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
558 To completely disable these expansions, you can use -G flag.
560 On Windows systems, the use of single quotes `'` when specifying
561 a file is not supported. Use double quotes `"`.
563 Options:
565 -n
566 __name__ is NOT set to '__main__', but to the running file's name
567 without extension (as python does under import). This allows running
568 scripts and reloading the definitions in them without calling code
569 protected by an ``if __name__ == "__main__"`` clause.
571 -i
572 run the file in IPython's namespace instead of an empty one. This
573 is useful if you are experimenting with code written in a text editor
574 which depends on variables defined interactively.
576 -e
577 ignore sys.exit() calls or SystemExit exceptions in the script
578 being run. This is particularly useful if IPython is being used to
579 run unittests, which always exit with a sys.exit() call. In such
580 cases you are interested in the output of the test results, not in
581 seeing a traceback of the unittest module.
583 -t
584 print timing information at the end of the run. IPython will give
585 you an estimated CPU time consumption for your script, which under
586 Unix uses the resource module to avoid the wraparound problems of
587 time.clock(). Under Unix, an estimate of time spent on system tasks
588 is also given (for Windows platforms this is reported as 0.0).
590 If -t is given, an additional ``-N<N>`` option can be given, where <N>
591 must be an integer indicating how many times you want the script to
592 run. The final timing report will include total and per run results.
594 For example (testing the script uniq_stable.py)::
596 In [1]: run -t uniq_stable
598 IPython CPU timings (estimated):
599 User : 0.19597 s.
600 System: 0.0 s.
602 In [2]: run -t -N5 uniq_stable
604 IPython CPU timings (estimated):
605 Total runs performed: 5
606 Times : Total Per run
607 User : 0.910862 s, 0.1821724 s.
608 System: 0.0 s, 0.0 s.
610 -d
611 run your program under the control of pdb, the Python debugger.
612 This allows you to execute your program step by step, watch variables,
613 etc. Internally, what IPython does is similar to calling::
615 pdb.run('execfile("YOURFILENAME")')
617 with a breakpoint set on line 1 of your file. You can change the line
618 number for this automatic breakpoint to be <N> by using the -bN option
619 (where N must be an integer). For example::
621 %run -d -b40 myscript
623 will set the first breakpoint at line 40 in myscript.py. Note that
624 the first breakpoint must be set on a line which actually does
625 something (not a comment or docstring) for it to stop execution.
627 Or you can specify a breakpoint in a different file::
629 %run -d -b myotherfile.py:20 myscript
631 When the pdb debugger starts, you will see a (Pdb) prompt. You must
632 first enter 'c' (without quotes) to start execution up to the first
633 breakpoint.
635 Entering 'help' gives information about the use of the debugger. You
636 can easily see pdb's full documentation with "import pdb;pdb.help()"
637 at a prompt.
639 -p
640 run program under the control of the Python profiler module (which
641 prints a detailed report of execution times, function calls, etc).
643 You can pass other options after -p which affect the behavior of the
644 profiler itself. See the docs for %prun for details.
646 In this mode, the program's variables do NOT propagate back to the
647 IPython interactive namespace (because they remain in the namespace
648 where the profiler executes them).
650 Internally this triggers a call to %prun, see its documentation for
651 details on the options available specifically for profiling.
653 There is one special usage for which the text above doesn't apply:
654 if the filename ends with .ipy[nb], the file is run as ipython script,
655 just as if the commands were written on IPython prompt.
657 -m
658 specify module name to load instead of script path. Similar to
659 the -m option for the python interpreter. Use this option last if you
660 want to combine with other %run options. Unlike the python interpreter
661 only source modules are allowed no .pyc or .pyo files.
662 For example::
664 %run -m example
666 will run the example module.
668 -G
669 disable shell-like glob expansion of arguments.
671 """
673 # Logic to handle issue #3664
674 # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
675 if '-m' in parameter_s and '--' not in parameter_s:
676 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
677 for idx, arg in enumerate(argv):
678 if arg and arg.startswith('-') and arg != '-':
679 if arg == '-m':
680 argv.insert(idx + 2, '--')
681 break
682 else:
683 # Positional arg, break
684 break
685 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
687 # get arguments and set sys.argv for program to be run.
688 opts, arg_lst = self.parse_options(parameter_s,
689 'nidtN:b:pD:l:rs:T:em:G',
690 mode='list', list_all=1)
691 if "m" in opts:
692 modulename = opts["m"][0]
693 modpath = find_mod(modulename)
694 if modpath is None:
695 msg = '%r is not a valid modulename on sys.path'%modulename
696 raise Exception(msg)
697 arg_lst = [modpath] + arg_lst
698 try:
699 fpath = None # initialize to make sure fpath is in scope later
700 fpath = arg_lst[0]
701 filename = file_finder(fpath)
702 except IndexError as e:
703 msg = 'you must provide at least a filename.'
704 raise Exception(msg) from e
705 except IOError as e:
706 try:
707 msg = str(e)
708 except UnicodeError:
709 msg = e.message
710 if os.name == 'nt' and re.match(r"^'.*'$",fpath):
711 warn('For Windows, use double quotes to wrap a filename: %run "mypath\\myfile.py"')
712 raise Exception(msg) from e
713 except TypeError:
714 if fpath in sys.meta_path:
715 filename = ""
716 else:
717 raise
719 if filename.lower().endswith(('.ipy', '.ipynb')):
720 with preserve_keys(self.shell.user_ns, '__file__'):
721 self.shell.user_ns['__file__'] = filename
722 self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
723 return
725 # Control the response to exit() calls made by the script being run
726 exit_ignore = 'e' in opts
728 # Make sure that the running script gets a proper sys.argv as if it
729 # were run from a system shell.
730 save_argv = sys.argv # save it for later restoring
732 if 'G' in opts:
733 args = arg_lst[1:]
734 else:
735 # tilde and glob expansion
736 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
738 sys.argv = [filename] + args # put in the proper filename
740 if 'n' in opts:
741 name = Path(filename).stem
742 else:
743 name = '__main__'
745 if 'i' in opts:
746 # Run in user's interactive namespace
747 prog_ns = self.shell.user_ns
748 __name__save = self.shell.user_ns['__name__']
749 prog_ns['__name__'] = name
750 main_mod = self.shell.user_module
752 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
753 # set the __file__ global in the script's namespace
754 # TK: Is this necessary in interactive mode?
755 prog_ns['__file__'] = filename
756 else:
757 # Run in a fresh, empty namespace
759 # The shell MUST hold a reference to prog_ns so after %run
760 # exits, the python deletion mechanism doesn't zero it out
761 # (leaving dangling references). See interactiveshell for details
762 main_mod = self.shell.new_main_mod(filename, name)
763 prog_ns = main_mod.__dict__
765 # pickle fix. See interactiveshell for an explanation. But we need to
766 # make sure that, if we overwrite __main__, we replace it at the end
767 main_mod_name = prog_ns['__name__']
769 if main_mod_name == '__main__':
770 restore_main = sys.modules['__main__']
771 else:
772 restore_main = False
774 # This needs to be undone at the end to prevent holding references to
775 # every single object ever created.
776 sys.modules[main_mod_name] = main_mod
778 if 'p' in opts or 'd' in opts:
779 if 'm' in opts:
780 code = 'run_module(modulename, prog_ns)'
781 code_ns = {
782 'run_module': self.shell.safe_run_module,
783 'prog_ns': prog_ns,
784 'modulename': modulename,
785 }
786 else:
787 if 'd' in opts:
788 # allow exceptions to raise in debug mode
789 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
790 else:
791 code = 'execfile(filename, prog_ns)'
792 code_ns = {
793 'execfile': self.shell.safe_execfile,
794 'prog_ns': prog_ns,
795 'filename': get_py_filename(filename),
796 }
798 try:
799 stats = None
800 if 'p' in opts:
801 stats = self._run_with_profiler(code, opts, code_ns)
802 else:
803 if 'd' in opts:
804 bp_file, bp_line = parse_breakpoint(
805 opts.get('b', ['1'])[0], filename)
806 self._run_with_debugger(
807 code, code_ns, filename, bp_line, bp_file)
808 else:
809 if 'm' in opts:
810 def run():
811 self.shell.safe_run_module(modulename, prog_ns)
812 else:
813 if runner is None:
814 runner = self.default_runner
815 if runner is None:
816 runner = self.shell.safe_execfile
818 def run():
819 runner(filename, prog_ns, prog_ns,
820 exit_ignore=exit_ignore)
822 if 't' in opts:
823 # timed execution
824 try:
825 nruns = int(opts['N'][0])
826 if nruns < 1:
827 error('Number of runs must be >=1')
828 return
829 except (KeyError):
830 nruns = 1
831 self._run_with_timing(run, nruns)
832 else:
833 # regular execution
834 run()
836 if 'i' in opts:
837 self.shell.user_ns['__name__'] = __name__save
838 else:
839 # update IPython interactive namespace
841 # Some forms of read errors on the file may mean the
842 # __name__ key was never set; using pop we don't have to
843 # worry about a possible KeyError.
844 prog_ns.pop('__name__', None)
846 with preserve_keys(self.shell.user_ns, '__file__'):
847 self.shell.user_ns.update(prog_ns)
848 finally:
849 # It's a bit of a mystery why, but __builtins__ can change from
850 # being a module to becoming a dict missing some key data after
851 # %run. As best I can see, this is NOT something IPython is doing
852 # at all, and similar problems have been reported before:
853 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
854 # Since this seems to be done by the interpreter itself, the best
855 # we can do is to at least restore __builtins__ for the user on
856 # exit.
857 self.shell.user_ns['__builtins__'] = builtin_mod
859 # Ensure key global structures are restored
860 sys.argv = save_argv
861 if restore_main:
862 sys.modules['__main__'] = restore_main
863 if '__mp_main__' in sys.modules:
864 sys.modules['__mp_main__'] = restore_main
865 else:
866 # Remove from sys.modules the reference to main_mod we'd
867 # added. Otherwise it will trap references to objects
868 # contained therein.
869 del sys.modules[main_mod_name]
871 return stats
873 def _run_with_debugger(
874 self, code, code_ns, filename=None, bp_line=None, bp_file=None, local_ns=None
875 ):
876 """
877 Run `code` in debugger with a break point.
879 Parameters
880 ----------
881 code : str
882 Code to execute.
883 code_ns : dict
884 A namespace in which `code` is executed.
885 filename : str
886 `code` is ran as if it is in `filename`.
887 bp_line : int, optional
888 Line number of the break point.
889 bp_file : str, optional
890 Path to the file in which break point is specified.
891 `filename` is used if not given.
892 local_ns : dict, optional
893 A local namespace in which `code` is executed.
895 Raises
896 ------
897 UsageError
898 If the break point given by `bp_line` is not valid.
900 """
901 deb = self.shell.InteractiveTB.pdb
902 if not deb:
903 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
904 deb = self.shell.InteractiveTB.pdb
906 # deb.checkline() fails if deb.curframe exists but is None; it can
907 # handle it not existing. https://github.com/ipython/ipython/issues/10028
908 if hasattr(deb, 'curframe'):
909 del deb.curframe
911 # reset Breakpoint state, which is moronically kept
912 # in a class
913 bdb.Breakpoint.next = 1
914 bdb.Breakpoint.bplist = {}
915 bdb.Breakpoint.bpbynumber = [None]
916 deb.clear_all_breaks()
917 if bp_line is not None:
918 # Set an initial breakpoint to stop execution
919 maxtries = 10
920 bp_file = bp_file or filename
921 checkline = deb.checkline(bp_file, bp_line)
922 if not checkline:
923 for bp in range(bp_line + 1, bp_line + maxtries + 1):
924 if deb.checkline(bp_file, bp):
925 break
926 else:
927 msg = ("\nI failed to find a valid line to set "
928 "a breakpoint\n"
929 "after trying up to line: %s.\n"
930 "Please set a valid breakpoint manually "
931 "with the -b option." % bp)
932 raise UsageError(msg)
933 # if we find a good linenumber, set the breakpoint
934 deb.do_break('%s:%s' % (bp_file, bp_line))
936 if filename:
937 # Mimic Pdb._runscript(...)
938 deb._wait_for_mainpyfile = True
939 deb.mainpyfile = deb.canonic(filename)
941 # Start file run
942 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
943 try:
944 if filename:
945 # save filename so it can be used by methods on the deb object
946 deb._exec_filename = filename
947 while True:
948 try:
949 trace = sys.gettrace()
950 deb.run(code, code_ns, local_ns)
951 except Restart:
952 print("Restarting")
953 if filename:
954 deb._wait_for_mainpyfile = True
955 deb.mainpyfile = deb.canonic(filename)
956 continue
957 else:
958 break
959 finally:
960 sys.settrace(trace)
963 except:
964 etype, value, tb = sys.exc_info()
965 # Skip three frames in the traceback: the %run one,
966 # one inside bdb.py, and the command-line typed by the
967 # user (run by exec in pdb itself).
968 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
970 @staticmethod
971 def _run_with_timing(run, nruns):
972 """
973 Run function `run` and print timing information.
975 Parameters
976 ----------
977 run : callable
978 Any callable object which takes no argument.
979 nruns : int
980 Number of times to execute `run`.
982 """
983 twall0 = time.perf_counter()
984 if nruns == 1:
985 t0 = clock2()
986 run()
987 t1 = clock2()
988 t_usr = t1[0] - t0[0]
989 t_sys = t1[1] - t0[1]
990 print("\nIPython CPU timings (estimated):")
991 print(" User : %10.2f s." % t_usr)
992 print(" System : %10.2f s." % t_sys)
993 else:
994 runs = range(nruns)
995 t0 = clock2()
996 for nr in runs:
997 run()
998 t1 = clock2()
999 t_usr = t1[0] - t0[0]
1000 t_sys = t1[1] - t0[1]
1001 print("\nIPython CPU timings (estimated):")
1002 print("Total runs performed:", nruns)
1003 print(" Times : %10s %10s" % ('Total', 'Per run'))
1004 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
1005 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
1006 twall1 = time.perf_counter()
1007 print("Wall time: %10.2f s." % (twall1 - twall0))
1009 @skip_doctest
1010 @no_var_expand
1011 @line_cell_magic
1012 @needs_local_scope
1013 def timeit(self, line='', cell=None, local_ns=None):
1014 """Time execution of a Python statement or expression
1016 Usage, in line mode:
1017 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
1018 or in cell mode:
1019 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
1020 code
1021 code...
1023 Time execution of a Python statement or expression using the timeit
1024 module. This function can be used both as a line and cell magic:
1026 - In line mode you can time a single-line statement (though multiple
1027 ones can be chained with using semicolons).
1029 - In cell mode, the statement in the first line is used as setup code
1030 (executed but not timed) and the body of the cell is timed. The cell
1031 body has access to any variables created in the setup code.
1033 Options:
1034 -n<N>: execute the given statement <N> times in a loop. If <N> is not
1035 provided, <N> is determined so as to get sufficient accuracy.
1037 -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
1038 best result.
1039 Default: 7
1041 -t: use time.time to measure the time, which is the default on Unix.
1042 This function measures wall time.
1044 -c: use time.clock to measure the time, which is the default on
1045 Windows and measures wall time. On Unix, resource.getrusage is used
1046 instead and returns the CPU user time.
1048 -p<P>: use a precision of <P> digits to display the timing result.
1049 Default: 3
1051 -q: Quiet, do not print result.
1053 -o: return a TimeitResult that can be stored in a variable to inspect
1054 the result in more details.
1056 .. versionchanged:: 7.3
1057 User variables are no longer expanded,
1058 the magic line is always left unmodified.
1060 Examples
1061 --------
1062 ::
1064 In [1]: %timeit pass
1065 8.26 ns ± 0.12 ns per loop (mean ± std. dev. of 7 runs, 100000000 loops each)
1067 In [2]: u = None
1069 In [3]: %timeit u is None
1070 29.9 ns ± 0.643 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)
1072 In [4]: %timeit -r 4 u == None
1074 In [5]: import time
1076 In [6]: %timeit -n1 time.sleep(2)
1078 The times reported by %timeit will be slightly higher than those
1079 reported by the timeit.py script when variables are accessed. This is
1080 due to the fact that %timeit executes the statement in the namespace
1081 of the shell, compared with timeit.py, which uses a single setup
1082 statement to import function or create variables. Generally, the bias
1083 does not matter as long as results from timeit.py are not mixed with
1084 those from %timeit."""
1086 opts, stmt = self.parse_options(
1087 line, "n:r:tcp:qo", posix=False, strict=False, preserve_non_opts=True
1088 )
1089 if stmt == "" and cell is None:
1090 return
1092 timefunc = timeit.default_timer
1093 number = int(getattr(opts, "n", 0))
1094 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1095 repeat = int(getattr(opts, "r", default_repeat))
1096 precision = int(getattr(opts, "p", 3))
1097 quiet = 'q' in opts
1098 return_result = 'o' in opts
1099 if hasattr(opts, "t"):
1100 timefunc = time.time
1101 if hasattr(opts, "c"):
1102 timefunc = clock
1104 timer = Timer(timer=timefunc)
1105 # this code has tight coupling to the inner workings of timeit.Timer,
1106 # but is there a better way to achieve that the code stmt has access
1107 # to the shell namespace?
1108 transform = self.shell.transform_cell
1110 if cell is None:
1111 # called as line magic
1112 ast_setup = self.shell.compile.ast_parse("pass")
1113 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1114 else:
1115 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1116 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1118 ast_setup = self.shell.transform_ast(ast_setup)
1119 ast_stmt = self.shell.transform_ast(ast_stmt)
1121 # Check that these compile to valid Python code *outside* the timer func
1122 # Invalid code may become valid when put inside the function & loop,
1123 # which messes up error messages.
1124 # https://github.com/ipython/ipython/issues/10636
1125 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1126 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1128 # This codestring is taken from timeit.template - we fill it in as an
1129 # AST, so that we can apply our AST transformations to the user code
1130 # without affecting the timing code.
1131 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1132 ' setup\n'
1133 ' _t0 = _timer()\n'
1134 ' for _i in _it:\n'
1135 ' stmt\n'
1136 ' _t1 = _timer()\n'
1137 ' return _t1 - _t0\n')
1139 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1140 timeit_ast = ast.fix_missing_locations(timeit_ast)
1142 # Track compilation time so it can be reported if too long
1143 # Minimum time above which compilation time will be reported
1144 tc_min = 0.1
1146 t0 = clock()
1147 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1148 tc = clock()-t0
1150 ns = {}
1151 glob = self.shell.user_ns
1152 # handles global vars with same name as local vars. We store them in conflict_globs.
1153 conflict_globs = {}
1154 if local_ns and cell is None:
1155 for var_name, var_val in glob.items():
1156 if var_name in local_ns:
1157 conflict_globs[var_name] = var_val
1158 glob.update(local_ns)
1160 exec(code, glob, ns)
1161 timer.inner = ns["inner"]
1163 # This is used to check if there is a huge difference between the
1164 # best and worst timings.
1165 # Issue: https://github.com/ipython/ipython/issues/6471
1166 if number == 0:
1167 # determine number so that 0.2 <= total time < 2.0
1168 for index in range(0, 10):
1169 number = 10 ** index
1170 time_number = timer.timeit(number)
1171 if time_number >= 0.2:
1172 break
1174 all_runs = timer.repeat(repeat, number)
1175 best = min(all_runs) / number
1176 worst = max(all_runs) / number
1177 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1179 # Restore global vars from conflict_globs
1180 if conflict_globs:
1181 glob.update(conflict_globs)
1183 if not quiet :
1184 # Check best timing is greater than zero to avoid a
1185 # ZeroDivisionError.
1186 # In cases where the slowest timing is lesser than a microsecond
1187 # we assume that it does not really matter if the fastest
1188 # timing is 4 times faster than the slowest timing or not.
1189 if worst > 4 * best and best > 0 and worst > 1e-6:
1190 print("The slowest run took %0.2f times longer than the "
1191 "fastest. This could mean that an intermediate result "
1192 "is being cached." % (worst / best))
1194 print( timeit_result )
1196 if tc > tc_min:
1197 print("Compiler time: %.2f s" % tc)
1198 if return_result:
1199 return timeit_result
1201 @skip_doctest
1202 @no_var_expand
1203 @needs_local_scope
1204 @line_cell_magic
1205 @output_can_be_silenced
1206 def time(self,line='', cell=None, local_ns=None):
1207 """Time execution of a Python statement or expression.
1209 The CPU and wall clock times are printed, and the value of the
1210 expression (if any) is returned. Note that under Win32, system time
1211 is always reported as 0, since it can not be measured.
1213 This function can be used both as a line and cell magic:
1215 - In line mode you can time a single-line statement (though multiple
1216 ones can be chained with using semicolons).
1218 - In cell mode, you can time the cell body (a directly
1219 following statement raises an error).
1221 This function provides very basic timing functionality. Use the timeit
1222 magic for more control over the measurement.
1224 .. versionchanged:: 7.3
1225 User variables are no longer expanded,
1226 the magic line is always left unmodified.
1228 Examples
1229 --------
1230 ::
1232 In [1]: %time 2**128
1233 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1234 Wall time: 0.00
1235 Out[1]: 340282366920938463463374607431768211456L
1237 In [2]: n = 1000000
1239 In [3]: %time sum(range(n))
1240 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1241 Wall time: 1.37
1242 Out[3]: 499999500000L
1244 In [4]: %time print 'hello world'
1245 hello world
1246 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1247 Wall time: 0.00
1249 .. note::
1250 The time needed by Python to compile the given expression will be
1251 reported if it is more than 0.1s.
1253 In the example below, the actual exponentiation is done by Python
1254 at compilation time, so while the expression can take a noticeable
1255 amount of time to compute, that time is purely due to the
1256 compilation::
1258 In [5]: %time 3**9999;
1259 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1260 Wall time: 0.00 s
1262 In [6]: %time 3**999999;
1263 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1264 Wall time: 0.00 s
1265 Compiler : 0.78 s
1266 """
1267 # fail immediately if the given expression can't be compiled
1269 if line and cell:
1270 raise UsageError("Can't use statement directly after '%%time'!")
1272 if cell:
1273 expr = self.shell.transform_cell(cell)
1274 else:
1275 expr = self.shell.transform_cell(line)
1277 # Minimum time above which parse time will be reported
1278 tp_min = 0.1
1280 t0 = clock()
1281 expr_ast = self.shell.compile.ast_parse(expr)
1282 tp = clock()-t0
1284 # Apply AST transformations
1285 expr_ast = self.shell.transform_ast(expr_ast)
1287 # Minimum time above which compilation time will be reported
1288 tc_min = 0.1
1290 expr_val=None
1291 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1292 mode = 'eval'
1293 source = '<timed eval>'
1294 expr_ast = ast.Expression(expr_ast.body[0].value)
1295 else:
1296 mode = 'exec'
1297 source = '<timed exec>'
1298 # multi-line %%time case
1299 if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
1300 expr_val= expr_ast.body[-1]
1301 expr_ast = expr_ast.body[:-1]
1302 expr_ast = Module(expr_ast, [])
1303 expr_val = ast.Expression(expr_val.value)
1305 t0 = clock()
1306 code = self.shell.compile(expr_ast, source, mode)
1307 tc = clock()-t0
1309 # skew measurement as little as possible
1310 glob = self.shell.user_ns
1311 wtime = time.time
1312 # time execution
1313 wall_st = wtime()
1314 if mode=='eval':
1315 st = clock2()
1316 try:
1317 out = eval(code, glob, local_ns)
1318 except:
1319 self.shell.showtraceback()
1320 return
1321 end = clock2()
1322 else:
1323 st = clock2()
1324 try:
1325 exec(code, glob, local_ns)
1326 out=None
1327 # multi-line %%time case
1328 if expr_val is not None:
1329 code_2 = self.shell.compile(expr_val, source, 'eval')
1330 out = eval(code_2, glob, local_ns)
1331 except:
1332 self.shell.showtraceback()
1333 return
1334 end = clock2()
1336 wall_end = wtime()
1337 # Compute actual times and report
1338 wall_time = wall_end - wall_st
1339 cpu_user = end[0] - st[0]
1340 cpu_sys = end[1] - st[1]
1341 cpu_tot = cpu_user + cpu_sys
1342 # On windows cpu_sys is always zero, so only total is displayed
1343 if sys.platform != "win32":
1344 print(
1345 f"CPU times: user {_format_time(cpu_user)}, sys: {_format_time(cpu_sys)}, total: {_format_time(cpu_tot)}"
1346 )
1347 else:
1348 print(f"CPU times: total: {_format_time(cpu_tot)}")
1349 print(f"Wall time: {_format_time(wall_time)}")
1350 if tc > tc_min:
1351 print(f"Compiler : {_format_time(tc)}")
1352 if tp > tp_min:
1353 print(f"Parser : {_format_time(tp)}")
1354 return out
1356 @skip_doctest
1357 @line_magic
1358 def macro(self, parameter_s=''):
1359 """Define a macro for future re-execution. It accepts ranges of history,
1360 filenames or string objects.
1362 Usage:\\
1363 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1365 Options:
1367 -r: use 'raw' input. By default, the 'processed' history is used,
1368 so that magics are loaded in their transformed version to valid
1369 Python. If this option is given, the raw input as typed at the
1370 command line is used instead.
1372 -q: quiet macro definition. By default, a tag line is printed
1373 to indicate the macro has been created, and then the contents of
1374 the macro are printed. If this option is given, then no printout
1375 is produced once the macro is created.
1377 This will define a global variable called `name` which is a string
1378 made of joining the slices and lines you specify (n1,n2,... numbers
1379 above) from your input history into a single string. This variable
1380 acts like an automatic function which re-executes those lines as if
1381 you had typed them. You just type 'name' at the prompt and the code
1382 executes.
1384 The syntax for indicating input ranges is described in %history.
1386 Note: as a 'hidden' feature, you can also use traditional python slice
1387 notation, where N:M means numbers N through M-1.
1389 For example, if your history contains (print using %hist -n )::
1391 44: x=1
1392 45: y=3
1393 46: z=x+y
1394 47: print x
1395 48: a=5
1396 49: print 'x',x,'y',y
1398 you can create a macro with lines 44 through 47 (included) and line 49
1399 called my_macro with::
1401 In [55]: %macro my_macro 44-47 49
1403 Now, typing `my_macro` (without quotes) will re-execute all this code
1404 in one pass.
1406 You don't need to give the line-numbers in order, and any given line
1407 number can appear multiple times. You can assemble macros with any
1408 lines from your input history in any order.
1410 The macro is a simple object which holds its value in an attribute,
1411 but IPython's display system checks for macros and executes them as
1412 code instead of printing them when you type their name.
1414 You can view a macro's contents by explicitly printing it with::
1416 print macro_name
1418 """
1419 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1420 if not args: # List existing macros
1421 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1422 if len(args) == 1:
1423 raise UsageError(
1424 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1425 name, codefrom = args[0], " ".join(args[1:])
1427 #print 'rng',ranges # dbg
1428 try:
1429 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1430 except (ValueError, TypeError) as e:
1431 print(e.args[0])
1432 return
1433 macro = Macro(lines)
1434 self.shell.define_macro(name, macro)
1435 if not ( 'q' in opts) :
1436 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1437 print('=== Macro contents: ===')
1438 print(macro, end=' ')
1440 @magic_arguments.magic_arguments()
1441 @magic_arguments.argument('output', type=str, default='', nargs='?',
1442 help="""The name of the variable in which to store output.
1443 This is a utils.io.CapturedIO object with stdout/err attributes
1444 for the text of the captured output.
1446 CapturedOutput also has a show() method for displaying the output,
1447 and __call__ as well, so you can use that to quickly display the
1448 output.
1450 If unspecified, captured output is discarded.
1451 """
1452 )
1453 @magic_arguments.argument('--no-stderr', action="store_true",
1454 help="""Don't capture stderr."""
1455 )
1456 @magic_arguments.argument('--no-stdout', action="store_true",
1457 help="""Don't capture stdout."""
1458 )
1459 @magic_arguments.argument('--no-display', action="store_true",
1460 help="""Don't capture IPython's rich display."""
1461 )
1462 @cell_magic
1463 def capture(self, line, cell):
1464 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1465 args = magic_arguments.parse_argstring(self.capture, line)
1466 out = not args.no_stdout
1467 err = not args.no_stderr
1468 disp = not args.no_display
1469 with capture_output(out, err, disp) as io:
1470 self.shell.run_cell(cell)
1471 if DisplayHook.semicolon_at_end_of_expression(cell):
1472 if args.output in self.shell.user_ns:
1473 del self.shell.user_ns[args.output]
1474 elif args.output:
1475 self.shell.user_ns[args.output] = io
1477def parse_breakpoint(text, current_file):
1478 '''Returns (file, line) for file:line and (current_file, line) for line'''
1479 colon = text.find(':')
1480 if colon == -1:
1481 return current_file, int(text)
1482 else:
1483 return text[:colon], int(text[colon+1:])
1485def _format_time(timespan, precision=3):
1486 """Formats the timespan in a human readable form"""
1488 if timespan >= 60.0:
1489 # we have more than a minute, format that in a human readable form
1490 # Idea from http://snipplr.com/view/5713/
1491 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1492 time = []
1493 leftover = timespan
1494 for suffix, length in parts:
1495 value = int(leftover / length)
1496 if value > 0:
1497 leftover = leftover % length
1498 time.append(u'%s%s' % (str(value), suffix))
1499 if leftover < 1:
1500 break
1501 return " ".join(time)
1504 # Unfortunately the unicode 'micro' symbol can cause problems in
1505 # certain terminals.
1506 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1507 # Try to prevent crashes by being more secure than it needs to
1508 # E.g. eclipse is able to print a µ, but has no sys.stdout.encoding set.
1509 units = [u"s", u"ms",u'us',"ns"] # the save value
1510 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1511 try:
1512 u'\xb5'.encode(sys.stdout.encoding)
1513 units = [u"s", u"ms",u'\xb5s',"ns"]
1514 except:
1515 pass
1516 scaling = [1, 1e3, 1e6, 1e9]
1518 if timespan > 0.0:
1519 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1520 else:
1521 order = 3
1522 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])