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

[DimitrisJim]

BPO	29414
Nosy	@rhettinger, @terryjreedy, @marco-buttu, @wm75, @DimitrisJim
PRs	bpo-29414: Change 'the for statement is such an iterator' in Tutorial #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:

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']

[DimitrisJim]

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]

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

[DimitrisJim]

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]

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]

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

[DimitrisJim]

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

[wm75]

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.

[marco-buttu]

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