Title: Document whether strings implement __iter__
Type: enhancement Stage:
Components: Documentation Versions: Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 2.7, Python 2.6
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, georg.brandl, rhettinger
Priority: normal Keywords:

Created on 2012-04-08 10:05 by chris.jerdonek, last changed 2012-04-08 22:05 by chris.jerdonek. This issue is now closed.

Messages (7)
msg157783 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-04-08 10:05
While converting code from Python 2 to Python 3, I came across the "gotcha" that strings implement __iter__ in Python 3 but not in Python 2.

Looking through the documentation, I don't seem to see anything like this mentioned in the library portion of either Python 2 or 3's documentation:

Or in the documentation describing differences between 2 and 3:

In fact, the Python 2 and 3 sections on iterator types seem largely the same.  Python 2's documentation even seems a bit misleading in this regard.  At the beginning of this section, it says, "Sequences, described below in more detail, always support the iteration methods [of which __iter__() is the main one]."  And str and unicode are the first two types mentioned in that next section on sequence types.

Here is a blog post I came across about this issue:

I think it would be worth highlighting this issue somewhere in the Python documentation, or at least acknowledging the change (unless I'm simply looking in the wrong place, in which case maybe it should be made more visible).
msg157784 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-04-08 10:16
Why is it so important if strings implement __iter__?  They are iterable in both versions, since iteration falls back on __getitem__ if no __iter__ is defined.  For user code it is irrelevant which of the iteration protocols is present.
msg157785 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-04-08 10:39
It is not "so important."  I just feel that the change should be acknowledged somewhere -- insofar as the existing user documentation on iterator types already discusses __iter__().  As it stands now, the Python 2 documentation is a bit misleading because it seems to suggest that strings implement __iter__().

With regard to falling back to __getitem__(), that might actually be worth mentioning in the section on iterator types.  Up until today, I didn't know there was a distinction between a "sequence protocol" and an "iterator protocol," as discussed here, for example--

For user code, the user might want different behavior depending on whether something behaves like a list.  For that, they might be relying on something like the presence of __iter__().
msg157786 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-04-08 10:43
"behaves like a list" is misleading.  If you mean checking for iterable-ness, calling iter() on the object is the way to do it.
msg157787 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-04-08 11:04
Okay, then that also might be worth mentioning.  As it stands now, the emphasis in the section on iterator types is on __iter__() (e.g. it is the main focus of the introduction), whereas iter() is barely mentioned (only in the sections on dicts and file objects).  So in addition to the suggestions above, perhaps the introduction to the section on iterator types could include a link to the iter() function with a description of its relationship to iterator types.
msg157808 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-04-08 20:13
Sorry, I agree with Georg, this isn't a bug, not even a documentation bug.  A type is free to implement iteration either by way of __iter__ or by way of __getitem__.  How it chooses to do so is an implementation detail (and different implementations have made different choices).
msg157812 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-04-08 22:05
Is there a mechanism for suggesting improvements to the documentation (e.g. for pedagogical reasons)?  I tried to classify this as an enhancement request rather than as a bug.
Date User Action Args
2012-04-08 22:05:12chris.jerdoneksetmessages: + msg157812
2012-04-08 20:13:20rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg157808

resolution: not a bug
2012-04-08 11:04:01chris.jerdoneksetmessages: + msg157787
2012-04-08 10:43:41georg.brandlsetmessages: + msg157786
2012-04-08 10:39:16chris.jerdoneksetmessages: + msg157785
2012-04-08 10:16:35georg.brandlsetnosy: + georg.brandl
messages: + msg157784
2012-04-08 10:05:37chris.jerdonekcreate