classification
Title: doc: yield from expression can be any iterable
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, miss-islington, terry.reedy
Priority: normal Keywords: patch

Created on 2016-07-28 18:30 by terry.reedy, last changed 2021-02-21 05:40 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 24595 merged terry.reedy, 2021-02-20 05:14
PR 24602 merged miss-islington, 2021-02-21 02:34
PR 24603 merged miss-islington, 2021-02-21 02:34
Messages (4)
msg271577 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-07-28 18:30
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 PEP380 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.
msg387435 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-02-21 02:33
New changeset 2f9ef514fb24b6a95bd3272885f197752810c107 by Terry Jan Reedy in branch 'master':
bpo-27646: Say that 'yield from' expression can be any iterable (GH-24595)
https://github.com/python/cpython/commit/2f9ef514fb24b6a95bd3272885f197752810c107
msg387436 - (view) Author: miss-islington (miss-islington) Date: 2021-02-21 02:42
New changeset 089a21f7429a3fd3cf78e3779df724757d346d19 by Miss Islington (bot) in branch '3.8':
bpo-27646: Say that 'yield from' expression can be any iterable (GH-24595)
https://github.com/python/cpython/commit/089a21f7429a3fd3cf78e3779df724757d346d19
msg387437 - (view) Author: miss-islington (miss-islington) Date: 2021-02-21 02:55
New changeset 7cc58890b3c16c28360a9abe030258426e89fec1 by Miss Islington (bot) in branch '3.9':
bpo-27646: Say that 'yield from' expression can be any iterable (GH-24595)
https://github.com/python/cpython/commit/7cc58890b3c16c28360a9abe030258426e89fec1
History
Date User Action Args
2021-02-21 05:40:52terry.reedysetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.8, Python 3.9
2021-02-21 02:55:57miss-islingtonsetmessages: + msg387437
2021-02-21 02:42:30miss-islingtonsetmessages: + msg387436
2021-02-21 02:34:11miss-islingtonsetpull_requests: + pull_request23381
2021-02-21 02:34:00miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request23380
2021-02-21 02:33:39terry.reedysetmessages: + msg387435
2021-02-20 05:14:36terry.reedysetkeywords: + patch
pull_requests: + pull_request23373
2021-02-19 13:58:03iritkatrielsettitle: yield from expression can be any iterable -> doc: yield from expression can be any iterable
versions: + Python 3.10, - Python 3.5, Python 3.6
2016-07-28 18:30:50terry.reedycreate