Improve documentation example for using iter() with sentinel value

[chris-rands]

BPO	34764
Nosy	@rhettinger, @chris-rands
PRs	bpo-34764: improve docs example of iter() with sentinel value #11222 [3.7] bpo-34764: improve docs example of iter() with sentinel value (GH-11222) #11301

^{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 = None
closed_at = <Date 2018-12-24.05:20:51.773>
created_at = <Date 2018-09-21.15:41:31.696>
labels = ['docs']
title = 'Improve documentation example for using iter() with sentinel value'
updated_at = <Date 2018-12-24.16:13:21.837>
user = 'https://github.com/chris-rands'

bugs.python.org fields:

activity = <Date 2018-12-24.16:13:21.837>
actor = 'rhettinger'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-12-24.05:20:51.773>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2018-09-21.15:41:31.696>
creator = 'ChrisRands'
dependencies = []
files = []
hgrepos = []
issue_num = 34764
keywords = ['patch']
message_count = 5.0
messages = ['325995', '326017', '326045', '332473', '332480']
nosy_count = 3.0
nosy_names = ['rhettinger', 'docs@python', 'ChrisRands']
pr_nums = ['11222', '11301']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue34764'
versions = []

[chris-rands]

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?

[rhettinger]

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

[chris-rands]

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

[rhettinger]

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

[rhettinger]

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