classification
Title: timeit.timeit not in __all__ even though documented
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Rosuav, anuj, docs@python, ezio.melotti, python-dev, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2013-03-14 08:14 by Rosuav, last changed 2013-03-15 07:10 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
timeit_exports.diff anuj, 2013-03-14 12:28 review
Messages (5)
msg184147 - (view) Author: Chris Angelico (Rosuav) * Date: 2013-03-14 08:14
The timeit module is commonly used via the convenience function timeit.timeit, which is listed in the documentation as the recommended "Python Interface":
http://docs.python.org/3/library/timeit.html

However, this function is not listed in __all__, meaning that it does not come up in IDLE when Ctrl-Space is pressed. It is also not mentioned in the module docstring, which says "Library usage: see the Timer class.".

Same applies to timeit.repeat(), save that it's not as commonly used. Both are listed in the online docs but not in the docstring or __all__.
msg184160 - (view) Author: Anuj Gupta (anuj) * Date: 2013-03-14 12:28
I'm a new contributor so, not sure if I'm missing anything:

The issue seems straightforward to me, the exports should definitely be included in both - the docstring and __all__. Also, default_timer is documented and should be imported as well.

I've contributed a patch for the dev version. After a review, I can submit patches for all remaining versions.

Thanks!
msg184209 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-15 01:39
As long as we are editing the module docstring, the last sentence should be deleted in 3.x patches, and the preceding sentence added to the preceding paragraph.

In 3.3+, the paragraph beginning "The difference in default timer function" is obsolete and should be removed.

Anuj, I believe patch is correct for 2.7, so I do not think more patch versions are needed now.

I see the __all__ change as both behavior fix and enhancement, so I don't know whether there should be one fix or four. I posted "Matching __all__ to doc: bugfix or enhancement?" on pydev to see what other think.

(Reminder to self: remove old code to handle absence of itertools from stdlib. This will break the current patch.)
msg184219 - (view) Author: Roundup Robot (python-dev) Date: 2013-03-15 07:04
New changeset dda8a6b8a351 by Terry Jan Reedy in branch 'default':
Issue #17414: Add timeit, repeat, and default_timer to timeit.__all__.
http://hg.python.org/cpython/rev/dda8a6b8a351
msg184220 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-15 07:09
Fred Drake, Eli Bendersky, and in particular, Guido ("I do see that it shouldn't be backported, but I don't see any worries about doing it in 3.4.") said that this is a 3.4-only enhancement.

Anuj, ACKS are alphabetical. ├ůstrand is at the end because that is where ├ů sorts. Thanks for the patch. We hope to see more.
History
Date User Action Args
2013-03-15 07:10:41terry.reedysetstatus: open -> closed
resolution: fixed
stage: needs patch -> resolved
2013-03-15 07:09:02terry.reedysetmessages: + msg184220
versions: - Python 2.6, Python 2.7, Python 3.2, Python 3.3
2013-03-15 07:04:44python-devsetnosy: + python-dev
messages: + msg184219
2013-03-15 01:39:19terry.reedysetmessages: + msg184209
2013-03-14 12:28:46anujsetfiles: + timeit_exports.diff

nosy: + anuj
messages: + msg184160

keywords: + patch
2013-03-14 08:15:43ezio.melottisetnosy: + ezio.melotti, docs@python
versions: + Python 2.7, Python 3.2, Python 3.4
assignee: docs@python
components: + Documentation
keywords: + easy
stage: needs patch
2013-03-14 08:14:50Rosuavcreate