New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[doc] timeit execution enviroment #42765
Comments
library reference manual, section 10.10 The documentation for the timeit module This information is available in the examples I think the following text should be appended To measure the execution time of the first Proposed addition: The timed statement is executed in the namespace |
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 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 |
Terry, I'm attaching a patch for 2.7, however it's more proof-of-concept than final, because I have a few comments. The patch generally implements your documentation suggestion without the
Let me know your thoughts and I will update the patch. |
I find the changes suggested by T Reedy and refined in the "...constructor creates a function..." "...that executes the *setup* statement..." Use of "statement" (singular) also directly conflicts with following Since the synopsis line already refers to "snippets", I think "...default to ``'pass'`..." "...or newlines as long as they don’t contain multi-line string literals..." I also think a short explanation of *why* one needs to import Here is my attempt to adjust taking the above observations into Class for timing execution speed of small code snippets. If a string, it may contain a python expression, statement, or If a callable object, (often a function), the object is called The setup and stmt parameters default to When the setup and stmt are run, they are run in a To measure the execution time of *stmt*, use the :meth:`Timer.timeit()` method. Changed in version 2.6: The stmt and setup parameters can now Notes: ----
Should the documentation promise that? The original "Changed in version 2.6" section said | Note that the timing overhead is a little larger in this case Here, "the other case" is presumably the plain code but could |
Terry, I'd like to move this forward. New interfaces or not, making the documentation more comprehensible is an important goal in itself. Could you please comment on rurpy2's latest notes - I will adapt the patch for latest 2.7/3.2/3.3 heads and commit it. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
Linked PRs
The text was updated successfully, but these errors were encountered: