Lib/timeit.py

   1 #! /usr/bin/env python
   2
   3 """Tool for measuring execution time of small code snippets.
   4
   5 This module avoids a number of common traps for measuring execution
   6 times.  See also Tim Peters' introduction to the Algorithms chapter in
   7 the Python Cookbook, published by O'Reilly.
   8
   9 Library usage: see the Timer class.
  10
  11 Command line usage:
  12     python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement]
  13
  14 Options:
  15   -n/--number N: how many times to execute 'statement' (default: see below)
  16   -r/--repeat N: how many times to repeat the timer (default 3)
  17   -s/--setup S: statement to be executed once initially (default 'pass')
  18   -t/--time: use time.time() (default on Unix)
  19   -c/--clock: use time.clock() (default on Windows)
  20   -v/--verbose: print raw timing results; repeat for more digits precision
  21   -h/--help: print this usage message and exit
  22   statement: statement to be timed (default 'pass')
  23
  24 A multi-line statement may be given by specifying each line as a
  25 separate argument; indented lines are possible by enclosing an
  26 argument in quotes and using leading spaces.  Multiple -s options are
  27 treated similarly.
  28
  29 If -n is not given, a suitable number of loops is calculated by trying
  30 successive powers of 10 until the total time is at least 0.2 seconds.
  31
  32 The difference in default timer function is because on Windows,
  33 clock() has microsecond granularity but time()'s granularity is 1/60th
  34 of a second; on Unix, clock() has 1/100th of a second granularity and
  35 time() is much more precise.  On either platform, the default timer
  36 functions measures wall clock time, not the CPU time.  This means that
  37 other processes running on the same computer may interfere with the
  38 timing.  The best thing to do when accurate timing is necessary is to
  39 repeat the timing a few times and use the best time.  The -r option is
  40 good for this; the default of 3 repetitions is probably enough in most
  41 cases.  On Unix, you can use clock() to measure CPU time.
  42
  43 Note: there is a certain baseline overhead associated with executing a
  44 pass statement.  The code here doesn't try to hide it, but you should
  45 be aware of it.  The baseline overhead can be measured by invoking the
  46 program without arguments.
  47
  48 The baseline overhead differs between Python versions!  Also, to
  49 fairly compare older Python versions to Python 2.3, you may want to
  50 use python -O for the older versions to avoid timing SET_LINENO
  51 instructions.
  52 """
  53
  54 import sys
  55 import math
  56 import time
  57 try:
  58     import itertools
  59 except ImportError:
  60     # Must be an older Python version (see timeit() below)
  61     itertools = None
  62
  63 __all__ = ["Timer"]
  64
  65 dummy_src_name = "<timeit-src>"
  66 default_number = 1000000
  67 default_repeat = 3
  68
  69 if sys.platform == "win32":
  70     # On Windows, the best timer is time.clock()
  71     default_timer = time.clock
  72 else:
  73     # On most other platforms the best timer is time.time()
  74     default_timer = time.time
  75
  76 # Don't change the indentation of the template; the reindent() calls
  77 # in Timer.__init__() depend on setup being indented 4 spaces and stmt
  78 # being indented 8 spaces.
  79 template = """
  80 def inner(_it, _timer):
  81     %(setup)s
  82     _t0 = _timer()
  83     for _i in _it:
  84         %(stmt)s
  85     _t1 = _timer()
  86     return _t1 - _t0
  87 """
  88
  89 def reindent(src, indent):
  90     """Helper to reindent a multi-line statement."""
  91     return src.replace("\n", "\n" + " "*indent)
  92
  93 class Timer:
  94     """Class for timing execution speed of small code snippets.
  95
  96     The constructor takes a statement to be timed, an additional
  97     statement used for setup, and a timer function.  Both statements
  98     default to 'pass'; the timer function is platform-dependent (see
  99     module doc string).
 100
 101     To measure the execution time of the first statement, use the
 102     timeit() method.  The repeat() method is a convenience to call
 103     timeit() multiple times and return a list of results.
 104
 105     The statements may contain newlines, as long as they don't contain
 106     multi-line string literals.
 107     """
 108
 109     def __init__(self, stmt="pass", setup="pass", timer=default_timer):
 110         """Constructor.  See class doc string."""
 111         self.timer = timer
 112         stmt = reindent(stmt, 8)
 113         setup = reindent(setup, 4)
 114         src = template % {'stmt': stmt, 'setup': setup}
 115         self.src = src # Save for traceback display
 116         code = compile(src, dummy_src_name, "exec")
 117         ns = {}
 118         exec code in globals(), ns
 119         self.inner = ns["inner"]
 120
 121     def print_exc(self, file=None):
 122         """Helper to print a traceback from the timed code.
 123
 124         Typical use:
 125
 126             t = Timer(...)       # outside the try/except
 127             try:
 128                 t.timeit(...)    # or t.repeat(...)
 129             except:
 130                 t.print_exc()
 131
 132         The advantage over the standard traceback is that source lines
 133         in the compiled template will be displayed.
 134
 135         The optional file argument directs where the traceback is
 136         sent; it defaults to sys.stderr.
 137         """
 138         import linecache, traceback
 139         linecache.cache[dummy_src_name] = (len(self.src),
 140                                            None,
 141                                            self.src.split("\n"),
 142                                            dummy_src_name)
 143         traceback.print_exc(file=file)
 144
 145     def timeit(self, number=default_number):
 146         """Time 'number' executions of the main statement.
 147
 148         To be precise, this executes the setup statement once, and
 149         then returns the time it takes to execute the main statement
 150         a number of times, as a float measured in seconds.  The
 151         argument is the number of times through the loop, defaulting
 152         to one million.  The main statement, the setup statement and
 153         the timer function to be used are passed to the constructor.
 154         """
 155         if itertools:
 156             it = itertools.repeat(None, number)
 157         else:
 158             it = [None] * number
 159         return self.inner(it, self.timer)
 160
 161     def repeat(self, repeat=default_repeat, number=default_number):
 162         """Call timeit() a few times.
 163
 164         This is a convenience function that calls the timeit()
 165         repeatedly, returning a list of results.  The first argument
 166         specifies how many times to call timeit(), defaulting to 3;
 167         the second argument specifies the timer argument, defaulting
 168         to one million.
 169
 170         Note: it's tempting to calculate mean and standard deviation
 171         from the result vector and report these.  However, this is not
 172         very useful.  In a typical case, the lowest value gives a
 173         lower bound for how fast your machine can run the given code
 174         snippet; higher values in the result vector are typically not
 175         caused by variability in Python's speed, but by other
 176         processes interfering with your timing accuracy.  So the min()
 177         of the result is probably the only number you should be
 178         interested in.  After that, you should look at the entire
 179         vector and apply common sense rather than statistics.
 180         """
 181         r = []
 182         for i in range(repeat):
 183             t = self.timeit(number)
 184             r.append(t)
 185         return r
 186
 187 def main(args=None):
 188     """Main program, used when run as a script.
 189
 190     The optional argument specifies the command line to be parsed,
 191     defaulting to sys.argv[1:].
 192
 193     The return value is an exit code to be passed to sys.exit(); it
 194     may be None to indicate success.
 195
 196     When an exception happens during timing, a traceback is printed to
 197     stderr and the return value is 1.  Exceptions at other times
 198     (including the template compilation) are not caught.
 199     """
 200     if args is None:
 201         args = sys.argv[1:]
 202     import getopt
 203     try:
 204         opts, args = getopt.getopt(args, "n:s:r:tcvh",
 205                                    ["number=", "setup=", "repeat=",
 206                                     "time", "clock", "verbose", "help"])
 207     except getopt.error, err:
 208         print err
 209         print "use -h/--help for command line help"
 210         return 2
 211     timer = default_timer
 212     stmt = "\n".join(args) or "pass"
 213     number = 0 # auto-determine
 214     setup = []
 215     repeat = default_repeat
 216     verbose = 0
 217     precision = 3
 218     for o, a in opts:
 219         if o in ("-n", "--number"):
 220             number = int(a)
 221         if o in ("-s", "--setup"):
 222             setup.append(a)
 223         if o in ("-r", "--repeat"):
 224             repeat = int(a)
 225             if repeat <= 0:
 226                 repeat = 1
 227         if o in ("-t", "--time"):
 228             timer = time.time
 229         if o in ("-c", "--clock"):
 230             timer = time.clock
 231         if o in ("-v", "--verbose"):
 232             if verbose:
 233                 precision += 1
 234             verbose += 1
 235         if o in ("-h", "--help"):
 236             print __doc__,
 237             return 0
 238     setup = "\n".join(setup) or "pass"
 239     t = Timer(stmt, setup, timer)
 240     if number == 0:
 241         # determine number so that 0.2 <= total time < 2.0
 242         for i in range(1, 10):
 243             number = 10**i
 244             try:
 245                 x = t.timeit(number)
 246             except:
 247                 t.print_exc()
 248                 return 1
 249             if verbose:
 250                 print "%d loops -> %.*g secs" % (number, precision, x)
 251             if x >= 0.2:
 252                 break
 253     try:
 254         r = t.repeat(repeat, number)
 255     except:
 256         t.print_exc()
 257         return 1
 258     best = min(r)
 259     if verbose:
 260         print "raw times:", " ".join(["%.*g" % (precision, x) for x in r])
 261     print "%d loops," % number,
 262     usec = best * 1e6 / number
 263     print "best of %d: %.*g usec per loop" % (repeat, precision, usec)
 264     return None
 265
 266 if __name__ == "__main__":
 267     sys.exit(main())