doc: yield from expression can be any iterable

[terryjreedy]

BPO	27646
Nosy	@terryjreedy, @miss-islington
PRs	bpo-27646: Say that 'yield from' expression can be any iterable #24595 [3.9] bpo-27646: Say that 'yield from' expression can be any iterable (GH-24595) #24602 [3.8] bpo-27646: Say that 'yield from' expression can be any iterable (GH-24595) #24603

^{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 2021-02-21.05:40:52.786>
created_at = <Date 2016-07-28.18:30:50.864>
labels = ['type-bug', '3.8', '3.9', '3.10', 'docs']
title = 'doc: yield from expression can be any iterable'
updated_at = <Date 2021-02-21.05:40:52.785>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2021-02-21.05:40:52.785>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-02-21.05:40:52.786>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2016-07-28.18:30:50.864>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 27646
keywords = ['patch']
message_count = 4.0
messages = ['271577', '387435', '387436', '387437']
nosy_count = 3.0
nosy_names = ['terry.reedy', 'docs@python', 'miss-islington']
pr_nums = ['24595', '24602', '24603']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue27646'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[terryjreedy]

https://docs.python.org/3/reference/expressions.html#yield-expressions says
"When yield from <expr> is used, it treats the supplied expression
as a subiterator. All values produced by that subiterator ...".
To me "treats..expression as a subiterator" means that the expression must *be* an iterator, such as returned by iter or calling a generator function. Hence I was surprised upon reading "yield from <non-iterator iterable>" in stdlib code.

I confirmed that this usage is correct by trying

>>> def g():
	yield from (1,2)

>>> i = g()
>>> next(i), next(i)
(1, 2)

and then reading the PEP-380 Formal Semantics, which begins with "_i = iter(EXPR)". Hence I suggest the following replacement for the quote above:
"When yield from <expr> is used, the expression must be an iterable.
A subiterator is obtained with iter(<expr>). All values produced
by that subiterator ...".

Note that 'subiterator' is spelled in the following sentences 'underlying iterable' (which I am not sure I like) and 'sub-iterator' (and 'sub-generator'). I think we should be consistent for at least the two short 'yield from' paragraphs.

[terryjreedy]

New changeset 2f9ef51 by Terry Jan Reedy in branch 'master':
bpo-27646: Say that 'yield from' expression can be any iterable (GH-24595)
2f9ef51

[miss-islington]

New changeset 089a21f by Miss Islington (bot) in branch '3.8':
bpo-27646: Say that 'yield from' expression can be any iterable (GH-24595)
089a21f

[miss-islington]

New changeset 7cc5889 by Miss Islington (bot) in branch '3.9':
bpo-27646: Say that 'yield from' expression can be any iterable (GH-24595)
7cc5889