Repository navigation
Change 'the for statement is such an iterator' in Tutorial #73600
Description
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = 'https://github.com/rhettinger'
closed_at = <Date 2019-06-01.21:12:13.299>
created_at = <Date 2017-02-01.19:10:16.616>
labels = ['type-feature', '3.7', 'docs']
title = "Change 'the for statement is such an iterator' in Tutorial"
updated_at = <Date 2019-06-01.21:12:13.298>
user = 'https://github.com/DimitrisJim'bugs.python.org fields:
activity = <Date 2019-06-01.21:12:13.298>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2019-06-01.21:12:13.299>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2017-02-01.19:10:16.616>
creator = 'Jim Fasarakis-Hilliard'
dependencies = []
files = ['46482', '46681']
hgrepos = []
issue_num = 29414
keywords = ['patch']
message_count = 12.0
messages = ['286678', '286763', '286899', '286959', '286979', '288485', '288512', '288718', '288727', '288741', '288746', '344237']
nosy_count = 6.0
nosy_names = ['rhettinger', 'terry.reedy', 'docs@python', 'marco.buttu', 'wolma', 'Jim Fasarakis-Hilliard']
pr_nums = ['273']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29414'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']
Activity
DimitrisJim commentedon Feb 1, 2017
The current line is confusing hinting that the for statement is actually an object, it also makes a reference to iterators which the tutorial doesn't disambiguate until the chapter on Classes.
I've added a small patch that, in my opinion, makes it clearer by using the terminology of the previous sentence.
marco-buttu commentedon Feb 2, 2017
I agree with you that the current sentence:
"We have seen that the for statement is such an iterator"
is wrong. But also the new sentence IMHO is confusing, because it stills compare statementes with objects:
"the for statement expects an object that is iterable. The function list is another; it creates lists from iterables".
Also list is a class, not a function.
IMHO the goal of the sentence you want to patch is to complete the previous one [1], adding an example of "construct" that operates with iterables, and of function that takes an iterable. If you want to follow that purpose, I suggest somethink like this:
"We have seen that the for statement is such a construct, while examples of functions that take an iterable are
sum()andmax()::"Written in better English than mine...
[1] "We say such an object is iterable, that is, suitable as a target for functions and constructs that expect something from which they can obtain successive items until the supply is exhausted."
terryjreedy commentedon Feb 3, 2017
The preceding sentences are also off. "In many ways the object returned by range() behaves as if it is a list, but in fact it isn’t. It is an object which returns the successive items of the desired sequence when you iterate over it, but it doesn’t really make the list, thus saving space."
A range object is more like a tuple than a list. Ranges and tuples are immutable sequences and the only non-dunder methods of both are count and index. Lists, on the other hand, are mutable and several other exposed methods. The difference between range and tuple is that ranges generate items as requested while tuples can be added and multiplied.
"Ranges are similar to tuples in being sequences with count and index methods. Both can be indexed, sliced, and iterated. However, ranges cannot be added or multiplied. They generate their items on request, thus saving space"
I am still thinking about the next two sentences, discussed above. I do not like 'construct' to mean 'statement' (or callable).
DimitrisJim commentedon Feb 4, 2017
Agreed. The issue I see with the additional suggestions by you and Marco (p.s the English was perfect!) is the introduction of other functions and/or objects that haven't been introduced yet.
If you want to draw parallels with tuples, you'll need to introduce them first, right? (or would a link to the definition of tuples suffice?)
marco-buttu commentedon Feb 4, 2017
Even though the Terry suggestion is formally correct, we are just at the beginning of the tutorial, and unluckily the tuples have not been introduced yet. To avoid adding to much complication here, IMHO we can just left the preceding sentences as they are.
marco-buttu commentedon Feb 23, 2017
Hello Jim, do you have the time to make a pull request? Let me know, otherwise I will do it
DimitrisJim commentedon Feb 24, 2017
Go ahead with making the PR, marco. I'll take a look at it too when you do.
wm75 commentedon Feb 28, 2017
I studied the github PR and thought about it carefully, and that made me come to believe that the chapter deserves a larger rewrite not just of one section, but of several.
I'm attaching my proposed change as a "classical" patch here for discussion. I hope that's still a valid way to do this as I did not want to mess with the original PR by Marco and, instead, wanted to see my proposal discussed first.
Some of the changes I made:
I find this new version much clearer, but lets see what people here think.
marco-buttu commentedon Feb 28, 2017
Wolfgang, thanks for your contribution. However, I prefere the chapter as it currently is, because IMHO it introduces the concepts more gradually than your proposal. In addition the modification of the title section from "for Statements" to "for Loops" IMHO makes the title not consistent with the other section titles.
-1 for me: the range() function is used in several examples in the chapter, that is why IMHO it is worth having the range() section as it is now.
-1 for me: IMHO the current definition/introdution of iterable is easier to understand for a beginner.
+0. I think for a reader who is coming from another language is better to have the current introduction. But maybe it is not the same for a reader who is learning Python as a first programming language.
+0
wm75 commentedon Mar 1, 2017
That's ok! It's your PR and I only wanted to show an alternative.
I was hoping for a bit more people to provide feedback though.
The main reason I'm interested in changes to the tutorial is because
I'm teaching Python to undergraduates (not in CS, but in Biology) and
I recommend them to work through the Tutorial alongside the course so
I have a natural interest in its quality and really appreciate any
improvement, which I think your PR is certainly offering :)
Let me still comment on some of your points regarding my suggestion:
I don't see this point. The other section titles are not about loops.
The preceding chapter introduces while loops as a loop, not a
statement, and this chapter talks about while and for loops further
down the page.
I don't agree with you on this. I'm coming from a C background myself,
but if I want to learn a new language the first thing I'm interested in
is not how it's *not* working, but how it does.
Plus, it's 2017, Perl has foreach, Javascript has at least
array.foreach and even C++11 has auto-iteration over collections so starting an explanation of for loops with 'hey, look Python is different
from two > 40 years old languages' feels a bit outdated.
Regarding my main point of removing most of the ranges section it is
possible I went a bit too far with that and maybe one should still
briefly mention the optional start argument and stress that stop is not
included in the range, but my seealso is quite prominent and the linked
section on range is pretty good.
marco-buttu commentedon Mar 1, 2017
What I mean is that currently in every section (of this chapter) about a statemet, the statement is qualified as "statement": "if Statements", "for Statements", "pass Statements", and "break and continue Statements, and else Clauses on Loops". The last one is not an exeption, bacause we have already introduced for and while, and writing "break and continue Statements, and else Clauses on for and while statements" IMO is redundant.
I like the current structure of titles, because IMO helps beginners to better classify things (statements, functions, ...), and it is not clear to me the objective motivation for changing "for Statemets" to "for Loops", breaking the structure given by the original author.
rhettinger commentedon Jun 1, 2019
New changeset 218e47b by Raymond Hettinger (Marco Buttu) in branch 'master':
bpo-29414: Change 'the for statement is such an iterator' in Tutorial (GH-273)
218e47b