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 measure 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 gc
  55 import sys
  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         gcold = gc.isenabled()
 160         gc.disable()
 161         timing = self.inner(it, self.timer)
 162         if gcold:
 163             gc.enable()
 164         return timing
 165
 166     def repeat(self, repeat=default_repeat, number=default_number):
 167         """Call timeit() a few times.
 168
 169         This is a convenience function that calls the timeit()
 170         repeatedly, returning a list of results.  The first argument
 171         specifies how many times to call timeit(), defaulting to 3;
 172         the second argument specifies the timer argument, defaulting
 173         to one million.
 174
 175         Note: it's tempting to calculate mean and standard deviation
 176         from the result vector and report these.  However, this is not
 177         very useful.  In a typical case, the lowest value gives a
 178         lower bound for how fast your machine can run the given code
 179         snippet; higher values in the result vector are typically not
 180         caused by variability in Python's speed, but by other
 181         processes interfering with your timing accuracy.  So the min()
 182         of the result is probably the only number you should be
 183         interested in.  After that, you should look at the entire
 184         vector and apply common sense rather than statistics.
 185         """
 186         r = []
 187         for i in range(repeat):
 188             t = self.timeit(number)
 189             r.append(t)
 190         return r
 191
 192 def main(args=None):
 193     """Main program, used when run as a script.
 194
 195     The optional argument specifies the command line to be parsed,
 196     defaulting to sys.argv[1:].
 197
 198     The return value is an exit code to be passed to sys.exit(); it
 199     may be None to indicate success.
 200
 201     When an exception happens during timing, a traceback is printed to
 202     stderr and the return value is 1.  Exceptions at other times
 203     (including the template compilation) are not caught.
 204     """
 205     if args is None:
 206         args = sys.argv[1:]
 207     import getopt
 208     try:
 209         opts, args = getopt.getopt(args, "n:s:r:tcvh",
 210                                    ["number=", "setup=", "repeat=",
 211                                     "time", "clock", "verbose", "help"])
 212     except getopt.error, err:
 213         print err
 214         print "use -h/--help for command line help"
 215         return 2
 216     timer = default_timer
 217     stmt = "\n".join(args) or "pass"
 218     number = 0 # auto-determine
 219     setup = []
 220     repeat = default_repeat
 221     verbose = 0
 222     precision = 3
 223     for o, a in opts:
 224         if o in ("-n", "--number"):
 225             number = int(a)
 226         if o in ("-s", "--setup"):
 227             setup.append(a)
 228         if o in ("-r", "--repeat"):
 229             repeat = int(a)
 230             if repeat <= 0:
 231                 repeat = 1
 232         if o in ("-t", "--time"):
 233             timer = time.time
 234         if o in ("-c", "--clock"):
 235             timer = time.clock
 236         if o in ("-v", "--verbose"):
 237             if verbose:
 238                 precision += 1
 239             verbose += 1
 240         if o in ("-h", "--help"):
 241             print __doc__,
 242             return 0
 243     setup = "\n".join(setup) or "pass"
 244     # Include the current directory, so that local imports work (sys.path
 245     # contains the directory of this script, rather than the current
 246     # directory)
 247     import os
 248     sys.path.insert(0, os.curdir)
 249     t = Timer(stmt, setup, timer)
 250     if number == 0:
 251         # determine number so that 0.2 <= total time < 2.0
 252         for i in range(1, 10):
 253             number = 10**i
 254             try:
 255                 x = t.timeit(number)
 256             except:
 257                 t.print_exc()
 258                 return 1
 259             if verbose:
 260                 print "%d loops -> %.*g secs" % (number, precision, x)
 261             if x >= 0.2:
 262                 break
 263     try:
 264         r = t.repeat(repeat, number)
 265     except:
 266         t.print_exc()
 267         return 1
 268     best = min(r)
 269     if verbose:
 270         print "raw times:", " ".join(["%.*g" % (precision, x) for x in r])
 271     print "%d loops," % number,
 272     usec = best * 1e6 / number
 273     if usec < 1000:
 274         print "best of %d: %.*g usec per loop" % (repeat, precision, usec)
 275     else:
 276         msec = usec / 1000
 277         if msec < 1000:
 278             print "best of %d: %.*g msec per loop" % (repeat, precision, msec)
 279         else:
 280             sec = msec / 1000
 281             print "best of %d: %.*g sec per loop" % (repeat, precision, sec)
 282     return None
 283
 284 if __name__ == "__main__":
 285     sys.exit(main())