classification
Title: timeit examples should be consistent
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: BreamoreBoy, claymation, docs@python, ezio.melotti, python-dev, rhettinger, serhiy.storchaka, steven.daprano
Priority: normal Keywords: patch

Created on 2013-07-29 17:17 by claymation, last changed 2014-08-04 14:02 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
18588.patch claymation, 2013-07-29 17:20 Documentation patch review
Messages (9)
msg193884 - (view) Author: Clay McClure (claymation) Date: 2013-07-29 17:20
The timeit module documentation includes examples of command-line and programmatic invocation, but the results between the two sets of examples don't agree.

This patch brings the results into agreement with each other.
msg194673 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-08-08 13:52
IIRC those were the actual values I got.  I think I investigated why they were different, but right now I don't remember if I found out why.
msg194681 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-08-08 14:47
In command-line invocation the gc is disabled. And timit.repeat() is used instead of timit.timit().
msg194688 - (view) Author: Clay McClure (claymation) Date: 2013-08-08 15:41
There's a 68% difference in running time between the command-line and programmatic invocations shown in the current documentation, and a 1% difference between the runtimes shown in the patch. I can't speak for why that is the case, but I did find it somewhat confusing when trying to interpret the timeit documentation.

Being a somewhat pedantic and trivial patch, I'm fine if you want to close it wontfix.
msg221000 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-19 16:02
@Steven you're into timeit, do you have anything to add here?
msg221017 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-06-19 20:19
> I did find it somewhat confusing when trying to interpret 
> the timeit documentation.

Perhaps that is a good thing.  Making good, repeatable, meaningful timings  where you have a clear interpretation of the results is non-trivial, learned skill.   Cross-checking results and explaining differences are fundamental skills.  There is really no reason the docs should try to make it look easier that it really is (running the tool is easy, but interpreting results sometimes isn't).

> Being a somewhat pedantic and trivial patch, I'm fine if you 
> want to close it wontfix.

That is reasonable.  I don't that this has caused any actual impediment to learning how to use timeit.  The docs have been somewhat successful in that regard.
msg221833 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-06-29 09:12
I tried to run those timings again and the values I got from the terminal are close to the ones I got from the interactive interpreter.
I'm not sure why when I wrote those examples I got such different values.
It would be fine with me to update them and avoid confusion.

> In command-line invocation the gc is disabled.
> And timit.repeat() is used instead of timit.timit().

Looking at the current code it seems to me that the command-line uses timeit.repeat(), that repeat calls timeit.timeit(), and that timeit.timeit() disables the gc.  Maybe back then it was different; that would explain why I got different results.
msg224719 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-08-04 14:02
New changeset c39457a07caa by Ezio Melotti in branch '3.4':
#18588: update the timeit examples to be consistent.
http://hg.python.org/cpython/rev/c39457a07caa

New changeset 45b208ae9eab by Ezio Melotti in branch 'default':
#18588: merge with 3.4.
http://hg.python.org/cpython/rev/45b208ae9eab
msg224720 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-08-04 14:02
Examples updated, thanks for the report!
History
Date User Action Args
2014-08-04 14:02:48ezio.melottisetstatus: open -> closed
versions: - Python 2.7
messages: + msg224720

resolution: fixed
stage: resolved
2014-08-04 14:02:09python-devsetnosy: + python-dev
messages: + msg224719
2014-06-29 09:12:09ezio.melottisetmessages: + msg221833
2014-06-19 20:19:49rhettingersetnosy: + rhettinger
messages: + msg221017
2014-06-19 16:02:24BreamoreBoysetnosy: + BreamoreBoy, steven.daprano
messages: + msg221000
2013-08-08 15:41:39claymationsetmessages: + msg194688
2013-08-08 14:47:49serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg194681
2013-08-08 13:52:51ezio.melottisetversions: - Python 2.6, Python 3.1, Python 3.2, Python 3.3
nosy: + ezio.melotti

messages: + msg194673

assignee: docs@python -> ezio.melotti
2013-07-29 17:20:38claymationsetfiles: + 18588.patch
keywords: + patch
messages: + msg193884
2013-07-29 17:17:37claymationcreate