This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author cameron
Recipients cameron, docs@python
Date 2020-09-14.22:49:00
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1600123741.16.0.294796218957.issue41787@roundup.psfhosted.org>
In-reply-to
Content
Add rationale for __length_hint__ and link to PEP 424, per the discussion here:

https://mail.python.org/archives/list/python-dev@python.org/thread/HXNFMIEZH73MXYEBP4TDIK3KFPYJ4QKR/#CXBEWAYSCAZCU7QABRBTKNVPDM3LELUM

Once the phrasing and directives are agreed, continue to chase other references in the docs.

This will produce multiple small PRs, possibly one per PEP as chased.

Phrasing:

I intend to amend the "New in version V." lines to become "New in version V, originally specified by PEPNNN." with a link to the PEP on "PEPNNN". I'm tempted to make "version V" also a link to its Whats New page; that will make for a bit more visual noise but seems pertinent.

The other thing I'd like to consider is a _single sentence_ in the docs identifying the main motivating use case for the feature. The __length_hint__ docs are a prime example here - the purpose of the feature is not mentioned, merely its semantics. While a feature can be used for many purposes, knowing why it was introduces brings a lot of cognitive benefit to the reader.
History
Date User Action Args
2020-09-14 22:49:01cameronsetrecipients: + cameron, docs@python
2020-09-14 22:49:01cameronsetmessageid: <1600123741.16.0.294796218957.issue41787@roundup.psfhosted.org>
2020-09-14 22:49:01cameronlinkissue41787 messages
2020-09-14 22:49:00cameroncreate