[issue11163] iter() documentation code doesn't work
New submission from Michael Grazebrook <michael@grazebrook.com>: This code fragment from the documentation of iter() doesn't work as intended. Change "STOP" to "STOP\n". Maybe also check for EOF as it hangs. with open("mydata.txt") as fp: for line in iter(fp.readline, "STOP"): process_line(line) Or maybe this makes a better example because it's clearer wha'ts going on: square_generator = (i * i for i in range(100000)) for n in iter( square_generator.next, 144): print n ---------- assignee: docs@python components: Documentation messages: 128238 nosy: docs@python, mgrazebrook priority: normal severity: normal status: open title: iter() documentation code doesn't work type: behavior versions: Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Changes by Antoine Pitrou <pitrou@free.fr>: ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Bryce Verdier <bryceverdier@gmail.com> added the comment: Here is the patch to fix the documentation. Asked some core developers off the bug tracker how to handle this bug in relation to the bigger issue regarding "STOP" leading to an infinite loop. ---------- keywords: +patch nosy: +louiscipher Added file: http://bugs.python.org/file21898/issue11163.py33.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: I think this is the wrong patch for reasons given below. The example should be replaced instead. Readline is documented as returning '' at EOF for text files. Iter(func,sentinel) is documented as calling func until sentinel is returned. If that never happens, it never stops. That makes it dangerous unless one KNOWS for sure that the sentinel WILL be returned or is willing to continue indefinitely. I think a sentence should be added to the doc to warn about this. So I consider the premise of the example, "One useful application of the second form of iter() is to read lines of a file until a certain line is reached.", to be somewhat dubious. The example could be considered instead to be an example of when NOT to use the second form. This application should better be written to avoid a possible infinite loop as with open(name) as fp: for line in fp: if line == sentinel: break process(line) I think a better example would be (3.2 version, use raw_input for 2.7): def my_input(): return input("Enter data or return to stop: ") for data in iter(my_input, ''): process(data) Your alternative also works, but the above is something one might actually do. Even that is hardly much better than: while True: data = input("Enter data or return to stop} if not data: break process data ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Changes by Terry J. Reedy <tjreedy@udel.edu>: ---------- versions: +Python 2.7, Python 3.1, Python 3.2, Python 3.3 -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: docs@python -> rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: I'll replace this with a better example using binary chunked reads that terminate with an empty string. ---------- priority: normal -> low _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Michael Grazebrook <michael@grazebrook.com> added the comment: Thank you. On 25/06/2011 13:38, Raymond Hettinger wrote:
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
purplezephyr added the comment: This does not seem to have been changed in any version, per msg135246. If it's not going to be replaced, there's another issue, which is that the link to readline() in the text is incorrect - it goes to the readline module, not file.readline(). ---------- nosy: +purplezephyr _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Terry J. Reedy added the comment: In the current 3.3.2 docs, 'STOP' has been replaced by '', so there is a change, and no infinite loop. However, this is still does not strike me as an example of 'useful' as for line in iter(fp.readline, "STOP"): # is a bad version of for line in fp: It does illustrate the behavior though. ---------- stage: -> needs patch versions: +Python 3.4 -Python 3.1, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Changes by Antoine Pitrou <pitrou@free.fr>: ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Bryce Verdier <bryceverdier@gmail.com> added the comment: Here is the patch to fix the documentation. Asked some core developers off the bug tracker how to handle this bug in relation to the bigger issue regarding "STOP" leading to an infinite loop. ---------- keywords: +patch nosy: +louiscipher Added file: http://bugs.python.org/file21898/issue11163.py33.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: I think this is the wrong patch for reasons given below. The example should be replaced instead. Readline is documented as returning '' at EOF for text files. Iter(func,sentinel) is documented as calling func until sentinel is returned. If that never happens, it never stops. That makes it dangerous unless one KNOWS for sure that the sentinel WILL be returned or is willing to continue indefinitely. I think a sentence should be added to the doc to warn about this. So I consider the premise of the example, "One useful application of the second form of iter() is to read lines of a file until a certain line is reached.", to be somewhat dubious. The example could be considered instead to be an example of when NOT to use the second form. This application should better be written to avoid a possible infinite loop as with open(name) as fp: for line in fp: if line == sentinel: break process(line) I think a better example would be (3.2 version, use raw_input for 2.7): def my_input(): return input("Enter data or return to stop: ") for data in iter(my_input, ''): process(data) Your alternative also works, but the above is something one might actually do. Even that is hardly much better than: while True: data = input("Enter data or return to stop} if not data: break process data ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Changes by Terry J. Reedy <tjreedy@udel.edu>: ---------- versions: +Python 2.7, Python 3.1, Python 3.2, Python 3.3 -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: docs@python -> rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: I'll replace this with a better example using binary chunked reads that terminate with an empty string. ---------- priority: normal -> low _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Michael Grazebrook <michael@grazebrook.com> added the comment: Thank you. On 25/06/2011 13:38, Raymond Hettinger wrote:
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
purplezephyr added the comment: This does not seem to have been changed in any version, per msg135246. If it's not going to be replaced, there's another issue, which is that the link to readline() in the text is incorrect - it goes to the readline module, not file.readline(). ---------- nosy: +purplezephyr _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
Terry J. Reedy added the comment: In the current 3.3.2 docs, 'STOP' has been replaced by '', so there is a change, and no infinite loop. However, this is still does not strike me as an example of 'useful' as for line in iter(fp.readline, "STOP"): # is a bad version of for line in fp: It does illustrate the behavior though. ---------- stage: -> needs patch versions: +Python 3.4 -Python 3.1, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________
participants (6)
-
Antoine Pitrou -
Bryce Verdier
-
Michael Grazebrook
-
purplezephyr
-
Raymond Hettinger
-
Terry J. Reedy