#! /usr/bin/env python | |
"""Tool for measuring execution time of small code snippets. | |
This module avoids a number of common traps for measuring execution | |
times. See also Tim Peters' introduction to the Algorithms chapter in | |
the Python Cookbook, published by O'Reilly. | |
Library usage: see the Timer class. | |
Command line usage: | |
python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [--] [statement] | |
Options: | |
-n/--number N: how many times to execute 'statement' (default: see below) | |
-r/--repeat N: how many times to repeat the timer (default 3) | |
-s/--setup S: statement to be executed once initially (default 'pass') | |
-t/--time: use time.time() (default on Unix) | |
-c/--clock: use time.clock() (default on Windows) | |
-v/--verbose: print raw timing results; repeat for more digits precision | |
-h/--help: print this usage message and exit | |
--: separate options from statement, use when statement starts with - | |
statement: statement to be timed (default 'pass') | |
A multi-line statement may be given by specifying each line as a | |
separate argument; indented lines are possible by enclosing an | |
argument in quotes and using leading spaces. Multiple -s options are | |
treated similarly. | |
If -n is not given, a suitable number of loops is calculated by trying | |
successive powers of 10 until the total time is at least 0.2 seconds. | |
The difference in default timer function is because on Windows, | |
clock() has microsecond granularity but time()'s granularity is 1/60th | |
of a second; on Unix, clock() has 1/100th of a second granularity and | |
time() is much more precise. On either platform, the default timer | |
functions measure wall clock time, not the CPU time. This means that | |
other processes running on the same computer may interfere with the | |
timing. The best thing to do when accurate timing is necessary is to | |
repeat the timing a few times and use the best time. The -r option is | |
good for this; the default of 3 repetitions is probably enough in most | |
cases. On Unix, you can use clock() to measure CPU time. | |
Note: there is a certain baseline overhead associated with executing a | |
pass statement. The code here doesn't try to hide it, but you should | |
be aware of it. The baseline overhead can be measured by invoking the | |
program without arguments. | |
The baseline overhead differs between Python versions! Also, to | |
fairly compare older Python versions to Python 2.3, you may want to | |
use python -O for the older versions to avoid timing SET_LINENO | |
instructions. | |
""" | |
import gc | |
import sys | |
import time | |
try: | |
import itertools | |
except ImportError: | |
# Must be an older Python version (see timeit() below) | |
itertools = None | |
__all__ = ["Timer"] | |
dummy_src_name = "<timeit-src>" | |
default_number = 1000000 | |
default_repeat = 3 | |
if sys.platform == "win32": | |
# On Windows, the best timer is time.clock() | |
default_timer = time.clock | |
else: | |
# On most other platforms the best timer is time.time() | |
default_timer = time.time | |
# Don't change the indentation of the template; the reindent() calls | |
# in Timer.__init__() depend on setup being indented 4 spaces and stmt | |
# being indented 8 spaces. | |
template = """ | |
def inner(_it, _timer): | |
%(setup)s | |
_t0 = _timer() | |
for _i in _it: | |
%(stmt)s | |
_t1 = _timer() | |
return _t1 - _t0 | |
""" | |
def reindent(src, indent): | |
"""Helper to reindent a multi-line statement.""" | |
return src.replace("\n", "\n" + " "*indent) | |
def _template_func(setup, func): | |
"""Create a timer function. Used if the "statement" is a callable.""" | |
def inner(_it, _timer, _func=func): | |
setup() | |
_t0 = _timer() | |
for _i in _it: | |
_func() | |
_t1 = _timer() | |
return _t1 - _t0 | |
return inner | |
class Timer: | |
"""Class for timing execution speed of small code snippets. | |
The constructor takes a statement to be timed, an additional | |
statement used for setup, and a timer function. Both statements | |
default to 'pass'; the timer function is platform-dependent (see | |
module doc string). | |
To measure the execution time of the first statement, use the | |
timeit() method. The repeat() method is a convenience to call | |
timeit() multiple times and return a list of results. | |
The statements may contain newlines, as long as they don't contain | |
multi-line string literals. | |
""" | |
def __init__(self, stmt="pass", setup="pass", timer=default_timer): | |
"""Constructor. See class doc string.""" | |
self.timer = timer | |
ns = {} | |
if isinstance(stmt, basestring): | |
stmt = reindent(stmt, 8) | |
if isinstance(setup, basestring): | |
setup = reindent(setup, 4) | |
src = template % {'stmt': stmt, 'setup': setup} | |
elif hasattr(setup, '__call__'): | |
src = template % {'stmt': stmt, 'setup': '_setup()'} | |
ns['_setup'] = setup | |
else: | |
raise ValueError("setup is neither a string nor callable") | |
self.src = src # Save for traceback display | |
code = compile(src, dummy_src_name, "exec") | |
exec code in globals(), ns | |
self.inner = ns["inner"] | |
elif hasattr(stmt, '__call__'): | |
self.src = None | |
if isinstance(setup, basestring): | |
_setup = setup | |
def setup(): | |
exec _setup in globals(), ns | |
elif not hasattr(setup, '__call__'): | |
raise ValueError("setup is neither a string nor callable") | |
self.inner = _template_func(setup, stmt) | |
else: | |
raise ValueError("stmt is neither a string nor callable") | |
def print_exc(self, file=None): | |
"""Helper to print a traceback from the timed code. | |
Typical use: | |
t = Timer(...) # outside the try/except | |
try: | |
t.timeit(...) # or t.repeat(...) | |
except: | |
t.print_exc() | |
The advantage over the standard traceback is that source lines | |
in the compiled template will be displayed. | |
The optional file argument directs where the traceback is | |
sent; it defaults to sys.stderr. | |
""" | |
import linecache, traceback | |
if self.src is not None: | |
linecache.cache[dummy_src_name] = (len(self.src), | |
None, | |
self.src.split("\n"), | |
dummy_src_name) | |
# else the source is already stored somewhere else | |
traceback.print_exc(file=file) | |
def timeit(self, number=default_number): | |
"""Time 'number' executions of the main statement. | |
To be precise, this executes the setup statement once, and | |
then returns the time it takes to execute the main statement | |
a number of times, as a float measured in seconds. The | |
argument is the number of times through the loop, defaulting | |
to one million. The main statement, the setup statement and | |
the timer function to be used are passed to the constructor. | |
""" | |
if itertools: | |
it = itertools.repeat(None, number) | |
else: | |
it = [None] * number | |
gcold = gc.isenabled() | |
gc.disable() | |
timing = self.inner(it, self.timer) | |
if gcold: | |
gc.enable() | |
return timing | |
def repeat(self, repeat=default_repeat, number=default_number): | |
"""Call timeit() a few times. | |
This is a convenience function that calls the timeit() | |
repeatedly, returning a list of results. The first argument | |
specifies how many times to call timeit(), defaulting to 3; | |
the second argument specifies the timer argument, defaulting | |
to one million. | |
Note: it's tempting to calculate mean and standard deviation | |
from the result vector and report these. However, this is not | |
very useful. In a typical case, the lowest value gives a | |
lower bound for how fast your machine can run the given code | |
snippet; higher values in the result vector are typically not | |
caused by variability in Python's speed, but by other | |
processes interfering with your timing accuracy. So the min() | |
of the result is probably the only number you should be | |
interested in. After that, you should look at the entire | |
vector and apply common sense rather than statistics. | |
""" | |
r = [] | |
for i in range(repeat): | |
t = self.timeit(number) | |
r.append(t) | |
return r | |
def timeit(stmt="pass", setup="pass", timer=default_timer, | |
number=default_number): | |
"""Convenience function to create Timer object and call timeit method.""" | |
return Timer(stmt, setup, timer).timeit(number) | |
def repeat(stmt="pass", setup="pass", timer=default_timer, | |
repeat=default_repeat, number=default_number): | |
"""Convenience function to create Timer object and call repeat method.""" | |
return Timer(stmt, setup, timer).repeat(repeat, number) | |
def main(args=None): | |
"""Main program, used when run as a script. | |
The optional argument specifies the command line to be parsed, | |
defaulting to sys.argv[1:]. | |
The return value is an exit code to be passed to sys.exit(); it | |
may be None to indicate success. | |
When an exception happens during timing, a traceback is printed to | |
stderr and the return value is 1. Exceptions at other times | |
(including the template compilation) are not caught. | |
""" | |
if args is None: | |
args = sys.argv[1:] | |
import getopt | |
try: | |
opts, args = getopt.getopt(args, "n:s:r:tcvh", | |
["number=", "setup=", "repeat=", | |
"time", "clock", "verbose", "help"]) | |
except getopt.error, err: | |
print err | |
print "use -h/--help for command line help" | |
return 2 | |
timer = default_timer | |
stmt = "\n".join(args) or "pass" | |
number = 0 # auto-determine | |
setup = [] | |
repeat = default_repeat | |
verbose = 0 | |
precision = 3 | |
for o, a in opts: | |
if o in ("-n", "--number"): | |
number = int(a) | |
if o in ("-s", "--setup"): | |
setup.append(a) | |
if o in ("-r", "--repeat"): | |
repeat = int(a) | |
if repeat <= 0: | |
repeat = 1 | |
if o in ("-t", "--time"): | |
timer = time.time | |
if o in ("-c", "--clock"): | |
timer = time.clock | |
if o in ("-v", "--verbose"): | |
if verbose: | |
precision += 1 | |
verbose += 1 | |
if o in ("-h", "--help"): | |
print __doc__, | |
return 0 | |
setup = "\n".join(setup) or "pass" | |
# Include the current directory, so that local imports work (sys.path | |
# contains the directory of this script, rather than the current | |
# directory) | |
import os | |
sys.path.insert(0, os.curdir) | |
t = Timer(stmt, setup, timer) | |
if number == 0: | |
# determine number so that 0.2 <= total time < 2.0 | |
for i in range(1, 10): | |
number = 10**i | |
try: | |
x = t.timeit(number) | |
except: | |
t.print_exc() | |
return 1 | |
if verbose: | |
print "%d loops -> %.*g secs" % (number, precision, x) | |
if x >= 0.2: | |
break | |
try: | |
r = t.repeat(repeat, number) | |
except: | |
t.print_exc() | |
return 1 | |
best = min(r) | |
if verbose: | |
print "raw times:", " ".join(["%.*g" % (precision, x) for x in r]) | |
print "%d loops," % number, | |
usec = best * 1e6 / number | |
if usec < 1000: | |
print "best of %d: %.*g usec per loop" % (repeat, precision, usec) | |
else: | |
msec = usec / 1000 | |
if msec < 1000: | |
print "best of %d: %.*g msec per loop" % (repeat, precision, msec) | |
else: | |
sec = msec / 1000 | |
print "best of %d: %.*g sec per loop" % (repeat, precision, sec) | |
return None | |
if __name__ == "__main__": | |
sys.exit(main()) |