This arose from this SO question: https://stackoverflow.com/questions/52446415/line-in-iterfp-readline-rather-than-line-in-fp

The example given in the docs:

with open('mydata.txt') as fp:
    for line in iter(fp.readline, ''):
        process_line(line)

Is exactly equivalent to the following because an empty string is only returned by readline at the EOF:

with open('mydata.txt') as fp:
    for line in fp:
        process_line(line)

The empty string '' sentinel value could be changed to another value to provide a possibly more meaningful example where the 2nd code snippet would not always produce the same result?

I concur that the readline() example is problematic. While it succeeds in showing how iter() works, the example itself is not the best way to solve that particular problem.

Here are two possible substitute examples.

1. Simple example that focuses primarily on the behavior of iter() and required little extra knowledge:

    >>> from random import randint
    >>> def roll_dice():
            return randint(1, 6) + randint(1, 6)

    >>> # roll until a seven is seen
    >>> list(iter(roll_dice, 7))
    >>> list(iter(roll_dice, 7))
    [10, 6, 5, 6, 8]

2. Practical application reading binary files in fixed-width blocks for processing with the structure module. This also teaches how to partial() to produce an arity-zero callable suitable for use with iter().

    >>> Read fixed-width blocks from a database binary file
    >>> from functools import partial
    >>> with open('mydata.db', 'rb') as f:
    	    for block in iter(partial(f.read, 64)):
		print(parse_struct(block))

Thank you Raymond, I like both your examples, although I think I prefer 1) for the simplicity

New changeset d378b1f by Raymond Hettinger (Chris Rands) in branch 'master':
bpo-34764: improve docs example of iter() with sentinel value (GH-11222)
d378b1f

New changeset 00a48d5 by Raymond Hettinger (Miss Islington (bot)) in branch '3.7':
bpo-34764: improve docs example of iter() with sentinel value (GH-11222) (bpo-11301)
00a48d5