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?
Cheers, Cameron Simpson cs@cskk.id.au
On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson cs@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.
On 13Sep2020 20:51, Guido van Rossum guido@python.org wrote:
On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson cs@cskk.id.au wrote:
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.
[...]
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.
Happy to use the term "originally specified by PEP424 [link]" :-)
I'll make some PRs. How to submit? Here, or a BPO or something?
Cheers, Cameron Simpson cs@cskk.id.au
On Sep 14, 2020, at 01:07, Cameron Simpson cs@cskk.id.au wrote:
On 13Sep2020 20:51, Guido van Rossum guido@python.org wrote:
On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson cs@cskk.id.au wrote:
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.
[...]
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.
Happy to use the term "originally specified by PEP424 [link]" :-)
I'll make some PRs. How to submit? Here, or a BPO or something?
My suggestion would be to open one BPO issue for "adding PEP references to documentation" and then creating PRs as needed against it. As you probably know, the devguide has the details including for the inline markup role :pep:.
https://devguide.python.org/documenting/#rest-inline-markup
-- Ned Deily nad@python.org -- []
On 14Sep2020 01:16, Ned Deily nad@python.org wrote:
I'll make some PRs. How to submit? Here, or a BPO or something?
My suggestion would be to open one BPO issue for "adding PEP references to documentation" and then creating PRs as needed against it. As you probably know, the devguide has the details including for the inline markup role :pep:.
Thanks Ned. - Cameron Simpson cs@cskk.id.au
On 9/14/2020 5:25 AM, Cameron Simpson wrote:
On 14Sep2020 01:16, Ned Deily nad@python.org wrote:
I'll make some PRs. How to submit? Here, or a BPO or something?
My suggestion would be to open one BPO issue for "adding PEP references to documentation" and then creating PRs as needed against it. As you probably know, the devguide has the details including for the inline markup role :pep:.
I agree with one master issue. I would prefer short blurb. "Add rationale for __length_hint__ and link to PEP ###.
bpo lists you as triager only, not committer. If so, I will help review and merge if review is requested on PR.
On 14Sep2020 18:17, Terry Reedy tjreedy@udel.edu wrote:
On 9/14/2020 5:25 AM, Cameron Simpson wrote:
On 14Sep2020 01:16, Ned Deily nad@python.org wrote:
My suggestion would be to open one BPO issue for "adding PEP references to documentation" and then creating PRs as needed against it. As you probably know, the devguide has the details including for the inline markup role :pep:.
I agree with one master issue. I would prefer short blurb. "Add rationale for __length_hint__ and link to PEP ###.
bpo lists you as triager only, not committer. If so, I will help review and merge if review is requested on PR.
BPO 41787: https://bugs.python.org/issue41787
I'll make a PR for PEP424 and __length_hint__ so that we can nail down an agreed approach with a concrete example.
Cheers, Cameron Simpson cs@cskk.id.au
On 14Sep2020 18:17, Terry Reedy tjreedy@udel.edu wrote:
On 9/14/2020 5:25 AM, Cameron Simpson wrote:
On 14Sep2020 01:16, Ned Deily nad@python.org wrote:
I'll make some PRs. How to submit? Here, or a BPO or something?
My suggestion would be to open one BPO issue for "adding PEP references to documentation" and then creating PRs as needed against it. As you probably know, the devguide has the details including for the inline markup role :pep:.
Ned, Terry,
There's a PR here: https://github.com/python/cpython/pull/22269 It's associated with BPO: https://bugs.python.org/issue41787
I agree with one master issue. I would prefer short blurb. "Add rationale for __length_hint__ and link to PEP ###.
I'm not sure this warrants a blurb. Not yet, anyway.
This is a tiny PR so that we can agree on a style for mentioning the PEP. If we agree, I'm hoping to followup with a PR for each whatsnew, working backwards from 3.8, mentioning the relevant PEPs as I locate them. Unless you'd rather something more fine grained.
I guess also if we agree I should patch the doc guidelines about "New in version N" lines (and changed/deprecated too, where those are PEP driven).
Also, for discussion, is a separate feature in the same BPO advocating modifying "New in version V" to put a link on "version V" to reference an anchor for the whatsnew entry, or the more specific in-the-whatsnew anchors where they exist.
Cheers, Cameron Simpson cs@cskk.id.au
-
Cameron Simpson -
Guido van Rossum -
Ned Deily -
Terry Reedy