On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <c...@cskk.id.au> wrote:
> 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-change-the-world/>
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/ZGA7ZQDTYYTUTDGILCYDD45YXTSEFDWK/ Code of Conduct: http://python.org/psf/codeofconduct/
