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

[gvanrossum@users.sourceforge.net]

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__":