Author terry.reedy
Recipients docs@python, terry.reedy
Date 2016-07-28.18:30:50
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1469730650.89.0.176012351897.issue27646@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2016-07-28 18:30:50terry.reedysetrecipients: + terry.reedy, docs@python
2016-07-28 18:30:50terry.reedysetmessageid: <1469730650.89.0.176012351897.issue27646@psf.upfronthosting.co.za>
2016-07-28 18:30:50terry.reedylinkissue27646 messages
2016-07-28 18:30:50terry.reedycreate