On 2020-12-29 16:18, Steven D'Aprano wrote:
On Tue, Dec 29, 2020 at 02:20:05PM -0800, Brendan Barnwell wrote:
So, to give an example, the iterator protocol should be documented
right where the `for` statement is documented, and it should be
explicitly framed as "this is the definition of what the `for` statement
does", not something separate.
Hmmm, that's going to be a bit confusing for people who want to
understand iter() and next() but don't care about for loops directly.
With regard to this and your other comments, I can see that that could
be useful in some cases. But the important points are: 1) if the for
statement uses the iterator protocol (which it does), the part of the
documentation where the for statement is defined absolutely must link to
the docs on the iterator protocol; and 2) the details of how `for` uses
the protocol must be explained in full in the docs for `for`.
I totally agree with you that the connections between features, and
detailed information about protocols and dunders can sometimes be hard
to find, but I think that the solution is not a complete redesign of the
docs, but more hyperlinks and See Alsos.
I would go slightly further than that though. It's not just "see
alsos". It can be hyperlinks, but what needs to be made clear is that
the hyperlinks are to DEFINITIONAL information where that is the case.
In other words, the `for` statement docs need to say that the operation
of the `for` statement is DEFINED by the iterator protocol. Now yes, if
that definiton has many nooks and crannies we can factor those out into
a separate page. But the way that `for` uses the iterator should indeed
be spelled out. For instance, right now it says:
An iterator is created for the result of the expression_list. The suite
is then executed once for each item provided by the iterator, in the
order returned by the iterator. Each item in turn is assigned to the
target list using the standard rules for assignments (see Assignment
statements), and then the suite is executed.
What I'm saying is it should say something like:
An iterator (link to iterator protocol here) is created by calling
iter() on the result of the expression_list. For each loop iteration,
next() is called on the iterator, then the resulting value is assigned
to the target list using the standard rules for assignment (link to
assignment here), and then the suite is executed.
Now, you're right that's a bit different from it maybe sounded like in
my message before. I'm not necessarily saying that the entire
definition of next and iter needs to be in there. But what I am saying
is that the nuts and bolts of how `for` uses the protocol DO need to be
in there. Things like "returned by the iterator" (which is not clear in
the terminology of the iterator protocol) should be replaced by things
like "returned by calling next() on the iterator" or "returned by the
iterator's __next__ method".
My point here is really more about the docs on other parts of Python
rather than the documentation of the iterator protocol itself (or other
such protocols). You're right that they need to be integrated, but it's
not solely a matter of providing links; I think there needs to be
considerably more detail about the precise way in which syntactic
features make use of these protocols. (Or in some cases less detail may
be needed; for instance, right now the `for` docs include a little note
about "modifying the sequence" while it is being iterated over; this
doesn't belong there because the for statement doesn't care about
sequences, but only about the iterator protocol.)
For the same reason, I'm less concerned about people who want to know
about iter() and next() themselves. That information is nice to have,
and it should be there in an easily-findable section of the docs for
sure. But `for` is a basic language construct, and it's in the
documentation of those basic language constructs where we need that
clarity about how they interact with the protocols.
I don't think this would require a complete redesign of the docs,
because sure, a lot of it could stay the same, but what I meant by
"overhaul" is that some restructuring (not just changing of wording) is
necessary. For instance, protocols like iterator, descriptor, etc.,
which, as you say, may be used in various ways, really need their own
section if we're going to be referring to them via hyperlinks. But more
than that, I think a lot of the documentation on basic stuff like loops,
attribute access, even mathematical operators, needs to be
reconceptualized so that it couches the entire description in terms of
the protocols that are actually used. It's not just a few links here
and there.
--
Brendan Barnwell
"Do not follow where the path may lead. Go, instead, where there is no
path, and leave a trail."
--author unknown
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/GNKMQI6BBRG7WSNF5FK5FV7NCRF3Z2HL/
Code of Conduct: http://python.org/psf/codeofconduct/
