Change 'the for statement is such an iterator' in Tutorial

[b78688f9-6435-4192-9fe9-2f86f7e61fcf]

BPO	29414
Nosy	@rhettinger, @terryjreedy, @marco-buttu, @wm75, @DimitrisJim
PRs	python/cpython#273
Files	issue29414.patch controlflow_datastructures.patch

^{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: ```python assignee = 'https://github.com/rhettinger' closed_at = created_at = labels = ['type-feature', '3.7', 'docs'] title = "Change 'the for statement is such an iterator' in Tutorial" updated_at = user = 'https://github.com/DimitrisJim' ``` bugs.python.org fields: ```python activity = actor = 'rhettinger' assignee = 'rhettinger' closed = True closed_date = closer = 'rhettinger' components = ['Documentation'] creation = 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'] ```

[b78688f9-6435-4192-9fe9-2f86f7e61fcf]

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.

[c6a24554-5737-4174-b47e-54fc0403b8dc]

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() and max()::"

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]

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).

[b78688f9-6435-4192-9fe9-2f86f7e61fcf]

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?)

[c6a24554-5737-4174-b47e-54fc0403b8dc]

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.

[c6a24554-5737-4174-b47e-54fc0403b8dc]

Hello Jim, do you have the time to make a pull request? Let me know, otherwise I will do it

[b78688f9-6435-4192-9fe9-2f86f7e61fcf]

Go ahead with making the PR, marco. I'll take a look at it too when you do.

[db36b1c5-c904-4d78-ae55-de8a610fb115]

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 don't think range() really deserves its own section in a chapter about control flow, so I removed most of it and linked to the relevant stdtypes section instead
• moved the definition of an iterable up into the for loop section
• restructured the for loop section to discuss Python for loops first and only compare them to Pascal/C afterwards
• moved the example for modifying a list while iterating over it to the datastructures chapter

I find this new version much clearer, but lets see what people here think.

[c6a24554-5737-4174-b47e-54fc0403b8dc]

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.

• I don't think range() really deserves its own section in a chapter about control flow, so I removed most of it and linked to the relevant stdtypes section instead

-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.

• moved the definition of an iterable up into the for loop section

-1 for me: IMHO the current definition/introdution of iterable is easier to understand for a beginner.

• restructured the for loop section to discuss Python for loops first and only compare them to Pascal/C afterwards

+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.

• moved the example for modifying a list while iterating over it to the datastructures chapter

+0

[db36b1c5-c904-4d78-ae55-de8a610fb115]

[...] I prefere the chapter as it currently is, because IMHO it introduces the concepts more gradually than your proposal.

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:

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.

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.

> - restructured the for loop section to discuss Python for loops > first and only compare them to Pascal/C afterwards +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.

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.

[c6a24554-5737-4174-b47e-54fc0403b8dc]

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.

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]

New changeset 218e47b61862470477922e9aba1a23fd3dab18ae by Raymond Hettinger (Marco Buttu) in branch 'master': bpo-29414: Change 'the for statement is such an iterator' in Tutorial (GH-273) https://github.com/python/cpython/commit/218e47b61862470477922e9aba1a23fd3dab18ae