[Python-checkins] python/dist/src/Lib timeit.py,1.1,1.2

2003年3月05日 18:32:21 -0800

Update of /cvsroot/python/python/dist/src/Lib
In directory sc8-pr-cvs1:/tmp/cvs-serv12260
Modified Files:
	timeit.py 
Log Message:
Added more documentation.
Index: timeit.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/timeit.py,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** timeit.py	5 Mar 2003 23:31:58 -0000	1.1
--- timeit.py	6 Mar 2003 02:32:19 -0000	1.2
***************
*** 1,17 ****
! """Framework for timing execution speed of 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).

! (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.)

 Command line usage:
! python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [statement]

 Options:
! -n/--number N: how many times to execute 'statement' (default varies)
 -r/--repeat N: how many times to repeat the timer (default 1)
 -s/--setup S: statements executed once before 'statement' (default 'pass')
--- 1,15 ----
! """Framework for measuring execution time for 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] [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 1)
 -s/--setup S: statements executed once before 'statement' (default 'pass')
***************
*** 19,24 ****
--- 17,43 ----
 -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
***************
*** 38,41 ****
--- 57,63 ----
 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):
***************
*** 50,58 ****
--- 72,96 ----

 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)
***************
*** 65,71 ****
--- 103,126 ----

 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):
***************
*** 75,78 ****
--- 130,141 ----

 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:]
***************
*** 119,122 ****
--- 182,186 ----
 else:
 print "time: %.3f usec" % usec
+ return None

 if __name__ == "__main__":