Added more documentation.
diff --git a/Lib/timeit.py b/Lib/timeit.py
index 2c0c146..fd177cd 100644
--- a/Lib/timeit.py
+++ b/Lib/timeit.py
@@ -1,25 +1,44 @@
-"""Framework for timing execution speed of small code snippets.
+"""Framework for measuring execution time for small code snippets.
-This avoids a number of common traps for timing frameworks (see also
-Tim Peters' introduction to the timing chapter in the Python
-Cookbook).
+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.
-(To use this with older versions of Python, the dependency on the
-itertools module is easily removed; instead of itertools.repeat(None,
-count) you can use [None]*count; this is barely slower.)
+Library usage: see the Timer class.
Command line usage:
- python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [statement]
+ python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [statement]
Options:
- -n/--number N: how many times to execute 'statement' (default varies)
+ -n/--number N: how many times to execute 'statement' (default: see below)
-r/--repeat N: how many times to repeat the timer (default 1)
-s/--setup S: statements executed once before 'statement' (default 'pass')
-t/--time: use time.time() (default on Unix)
-c/--clock: use time.clock() (default on Windows)
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.
+
+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 measures 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. On Unix, you can use clock() to measure CPU time.
"""
+# To use this module with older versions of Python, the dependency on
+# the itertools module is easily removed; in the template, instead of
+# itertools.repeat(None, count), use [None]*count. It's barely slower.
+
import sys
import math
import time
@@ -37,6 +56,9 @@
# 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(number, timer):
%(setup)s
@@ -49,11 +71,27 @@
"""
def reindent(src, indent):
+ """Helper to reindent a multi-line statement."""
return ("\n" + " "*indent).join(src.split("\n"))
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
stmt = reindent(stmt, 8)
setup = reindent(setup, 4)
@@ -64,9 +102,26 @@
self.inner = ns["inner"]
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.
+ """
return self.inner(number, self.timer)
def repeat(self, repeat=default_repeat, number=default_number):
+ """Call timer() a few times.
+
+ This is a convenience function that calls the timer()
+ repeatedly, returning a list of results. The first argument
+ specifies how many times to call timer(), defaulting to 10;
+ the second argument specifies the timer argument, defaulting
+ to one million.
+ """
r = []
for i in range(repeat):
t = self.timeit(number)
@@ -74,6 +129,14 @@
return r
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.
+ """
if args is None:
args = sys.argv[1:]
import getopt
@@ -118,6 +181,7 @@
print "best of %d: %.3f usec" % (repeat, usec)
else:
print "time: %.3f usec" % usec
+ return None
if __name__ == "__main__":
sys.exit(main())