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 def _template_func(setup, func):

    94     """Create a timer function. Used if the "statement" is a callable."""

    95     def inner(_it, _timer):

    96         setup()

    97         _t0 = _timer()

    98         for _i in _it:

    99             func()

   100         _t1 = _timer()

   101         return _t1 - _t0

   102     return inner

   103 

   104 class Timer:

   105     """Class for timing execution speed of small code snippets.

   106 

   107     The constructor takes a statement to be timed, an additional

   108     statement used for setup, and a timer function.  Both statements

   109     default to 'pass'; the timer function is platform-dependent (see

   110     module doc string).

   111 

   112     To measure the execution time of the first statement, use the

   113     timeit() method.  The repeat() method is a convenience to call

   114     timeit() multiple times and return a list of results.

   115 

   116     The statements may contain newlines, as long as they don't contain

   117     multi-line string literals.

   118     """

   119 

   120     def __init__(self, stmt="pass", setup="pass", timer=default_timer):

   121         """Constructor.  See class doc string."""

   122         self.timer = timer

   123         ns = {}

   124         if isinstance(stmt, basestring):

   125             stmt = reindent(stmt, 8)

   126             if isinstance(setup, basestring):

   127                 setup = reindent(setup, 4)

   128                 src = template % {'stmt': stmt, 'setup': setup}

   129             elif callable(setup):

   130                 src = template % {'stmt': stmt, 'setup': '_setup()'}

   131                 ns['_setup'] = setup

   132             else:

   133                 raise ValueError("setup is neither a string nor callable")

   134             self.src = src # Save for traceback display

   135             code = compile(src, dummy_src_name, "exec")

   136             exec code in globals(), ns

   137             self.inner = ns["inner"]

   138         elif callable(stmt):

   139             self.src = None

   140             if isinstance(setup, basestring):

   141                 _setup = setup

   142                 def setup():

   143                     exec _setup in globals(), ns

   144             elif not callable(setup):

   145                 raise ValueError("setup is neither a string nor callable")

   146             self.inner = _template_func(setup, stmt)

   147         else:

   148             raise ValueError("stmt is neither a string nor callable")

   149 

   150     def print_exc(self, file=None):

   151         """Helper to print a traceback from the timed code.

   152 

   153         Typical use:

   154 

   155             t = Timer(...)       # outside the try/except

   156             try:

   157                 t.timeit(...)    # or t.repeat(...)

   158             except:

   159                 t.print_exc()

   160 

   161         The advantage over the standard traceback is that source lines

   162         in the compiled template will be displayed.

   163 

   164         The optional file argument directs where the traceback is

   165         sent; it defaults to sys.stderr.

   166         """

   167         import linecache, traceback

   168         if self.src is not None:

   169             linecache.cache[dummy_src_name] = (len(self.src),

   170                                                None,

   171                                                self.src.split("\n"),

   172                                                dummy_src_name)

   173         # else the source is already stored somewhere else

   174 

   175         traceback.print_exc(file=file)

   176 

   177     def timeit(self, number=default_number):

   178         """Time 'number' executions of the main statement.

   179 

   180         To be precise, this executes the setup statement once, and

   181         then returns the time it takes to execute the main statement

   182         a number of times, as a float measured in seconds.  The

   183         argument is the number of times through the loop, defaulting

   184         to one million.  The main statement, the setup statement and

   185         the timer function to be used are passed to the constructor.

   186         """

   187         if itertools:

   188             it = itertools.repeat(None, number)

   189         else:

   190             it = [None] * number

   191         gcold = gc.isenabled()

   192         gc.disable()

   193         timing = self.inner(it, self.timer)

   194         if gcold:

   195             gc.enable()

   196         return timing

   197 

   198     def repeat(self, repeat=default_repeat, number=default_number):

   199         """Call timeit() a few times.

   200 

   201         This is a convenience function that calls the timeit()

   202         repeatedly, returning a list of results.  The first argument

   203         specifies how many times to call timeit(), defaulting to 3;

   204         the second argument specifies the timer argument, defaulting

   205         to one million.

   206 

   207         Note: it's tempting to calculate mean and standard deviation

   208         from the result vector and report these.  However, this is not

   209         very useful.  In a typical case, the lowest value gives a

   210         lower bound for how fast your machine can run the given code

   211         snippet; higher values in the result vector are typically not

   212         caused by variability in Python's speed, but by other

   213         processes interfering with your timing accuracy.  So the min()

   214         of the result is probably the only number you should be

   215         interested in.  After that, you should look at the entire

   216         vector and apply common sense rather than statistics.

   217         """

   218         r = []

   219         for i in range(repeat):

   220             t = self.timeit(number)

   221             r.append(t)

   222         return r

   223 

   224 def timeit(stmt="pass", setup="pass", timer=default_timer,

   225            number=default_number):

   226     """Convenience function to create Timer object and call timeit method."""

   227     return Timer(stmt, setup, timer).timeit(number)

   228 

   229 def repeat(stmt="pass", setup="pass", timer=default_timer,

   230            repeat=default_repeat, number=default_number):

   231     """Convenience function to create Timer object and call repeat method."""

   232     return Timer(stmt, setup, timer).repeat(repeat, number)

   233 

   234 def main(args=None):

   235     """Main program, used when run as a script.

   236 

   237     The optional argument specifies the command line to be parsed,

   238     defaulting to sys.argv[1:].

   239 

   240     The return value is an exit code to be passed to sys.exit(); it

   241     may be None to indicate success.

   242 

   243     When an exception happens during timing, a traceback is printed to

   244     stderr and the return value is 1.  Exceptions at other times

   245     (including the template compilation) are not caught.

   246     """

   247     if args is None:

   248         args = sys.argv[1:]

   249     import getopt

   250     try:

   251         opts, args = getopt.getopt(args, "n:s:r:tcvh",

   252                                    ["number=", "setup=", "repeat=",

   253                                     "time", "clock", "verbose", "help"])

   254     except getopt.error, err:

   255         print err

   256         print "use -h/--help for command line help"

   257         return 2

   258     timer = default_timer

   259     stmt = "\n".join(args) or "pass"

   260     number = 0 # auto-determine

   261     setup = []

   262     repeat = default_repeat

   263     verbose = 0

   264     precision = 3

   265     for o, a in opts:

   266         if o in ("-n", "--number"):

   267             number = int(a)

   268         if o in ("-s", "--setup"):

   269             setup.append(a)

   270         if o in ("-r", "--repeat"):

   271             repeat = int(a)

   272             if repeat <= 0:

   273                 repeat = 1

   274         if o in ("-t", "--time"):

   275             timer = time.time

   276         if o in ("-c", "--clock"):

   277             timer = time.clock

   278         if o in ("-v", "--verbose"):

   279             if verbose:

   280                 precision += 1

   281             verbose += 1

   282         if o in ("-h", "--help"):

   283             print __doc__,

   284             return 0

   285     setup = "\n".join(setup) or "pass"

   286     # Include the current directory, so that local imports work (sys.path

   287     # contains the directory of this script, rather than the current

   288     # directory)

   289     import os

   290     sys.path.insert(0, os.curdir)

   291     t = Timer(stmt, setup, timer)

   292     if number == 0:

   293         # determine number so that 0.2 <= total time < 2.0

   294         for i in range(1, 10):

   295             number = 10**i

   296             try:

   297                 x = t.timeit(number)

   298             except:

   299                 t.print_exc()

   300                 return 1

   301             if verbose:

   302                 print "%d loops -> %.*g secs" % (number, precision, x)

   303             if x >= 0.2:

   304                 break

   305     try:

   306         r = t.repeat(repeat, number)

   307     except:

   308         t.print_exc()

   309         return 1

   310     best = min(r)

   311     if verbose:

   312         print "raw times:", " ".join(["%.*g" % (precision, x) for x in r])

   313     print "%d loops," % number,

   314     usec = best * 1e6 / number

   315     if usec < 1000:

   316         print "best of %d: %.*g usec per loop" % (repeat, precision, usec)

   317     else:

   318         msec = usec / 1000

   319         if msec < 1000:

   320             print "best of %d: %.*g msec per loop" % (repeat, precision, msec)

   321         else:

   322             sec = msec / 1000

   323             print "best of %d: %.*g sec per loop" % (repeat, precision, sec)

   324     return None

   325 

   326 if __name__ == "__main__":

   327     sys.exit(main())