Terry J. Reedy <tjre...@udel.edu> added the comment:
I agree that the Timer doc is deficient in not saying that timing is done
within a function defined within the timeit module. It is also deficient in not
mentioning the secret of how to successfully pass user-defined functions until
the very bottom instead of where that option is described. (I had missed this
very point until recently.)
The discussion of possible new features for 3.2 (more likely later) does not
affect 2.7/3.1 and should not stop a change in 3.2 either. I propose that the
Timer doc be revised to the following:
PROPOSED REPLACEMENT
'''
Class for timing execution speed of small code snippets. The constructor
creates a function that executes the *setup* statement once and then times some
number of executions of the *stmt* statement (see Timer.timeit). Both
statements default to 'pass'. The *timer* parameter defaults to a
platform-dependent timer function (see the module doc string). Both *stmt* and
*setup* may contain multiple statements separated by ; or newlines as long as
they don’t contain multi-line string literals.
Both *stmt* and *setup* can also be objects that are callable without
arguments. Passing testfunc rather than 'testfunc()' may reduce the timing
overhead. However, if testfunc is a Python function, passing its quoted code
should have even less overhead because doing so eliminates an extra function
call.
To give *stmt* (whether it is a callable name or code string) access to
pre-defined user objects, such as testfunc, *setup* must include an import,
such as 'from __main__ import testfunc'. Note that 'from __main__ import *'
does not work because * imports are not legal within functions.
To measure the execution time of *stmt*, use the timeit() method. The repeat()
method is a convenience to call timeit() multiple times and return a list of
results.
'''
Note 1. testfunc , 'testfunc()' , and 'from ....' should be marked up as code.
Perhaps the first two should be double quoted also, depending of the style
convention. What must be clear is the difference between passing an unquoted
function name and a string.
Note 2. The 'may reduce' comment: timeit.timeit(str) (for instance) runs
noticeably faster than timeit.timeit('str()'). I presume this is because
callables get bound to a local name and local name lookup is faster than
builtin lookup. This difference does not apply to imported user names. The
existing statement "Note that the timing overhead is a little larger in this
case because of the extra function calls." is confusing to me because it does
not specify the alternative to 'this case' and there are two possibilities,
which I specified.
Note 3. The comment about * imports should be deleted for 2.7 version.
ADDITIONAL CHANGE
Add the following to the very bottom as part of the final example:
"
t = Timer(test, "from __main__ import test")
print(t.timeit()) # should be nearly the same
"
----------
keywords: +patch
nosy: +terry.reedy
stage: -> needs patch
type: -> behavior
versions: +Python 2.7, Python 3.1, Python 3.2
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue1397474>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
