On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson
So, today I noticed __length_hint__, and then operator.length_hint. Neither mentions its design purpose, only its specification. And while that is minimally enough, knowing the purpoe (size estimation for use by presized allocation operations) lets an implementor write something more appropriate.
While it'd be nice to have a short sentence with the provoking rationale for the feature in the docs, it would also be nice to reference the PEP.
As a concrete example, for __length_hint__ and operator.length_hint, I wish that in addition to saying "New in version 3.4", it also said "specified by PEP424 [link]", since I had to go find that with a search engine to understand the rationale.
Would PRs with such patches be welcome?
Yeah, I think that's a reasonable idea, and I don't think it needs a news item or bpo bug either. If you know there's a PEP you should be able to find it through the what's new doc for the version where the feature was added (assuming there's a "versionadded" note), but that's pretty indirect, and people might not even think there could be a PEP. A downside of linking to the PEP is that sometimes the PEP has an outdated version of an API. For example asyncio has evolved quite a bit since PEP 3156 (some stuff in the PEP turned out not so hot), and I'm sure that's not the only case. But all in all I like the idea of linking to the PEP from the "versionadded" or "versionchanged" note. -- --Guido van Rossum (python.org/~guido) *Pronouns: he/him **(why is my pronoun here?)* http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-c...