generator/coroutine terminology

[Ian Kelly]

On Sat, Mar 14, 2015 at 1:54 AM, Marko Rauhamaa <marko at pacujo.net> wrote:
> Steven D'Aprano <steve+comp.lang.python at pearwood.info>:
>
>> Marko Rauhamaa wrote:
>>
>>> Your 'factory' is a:
>>>
>>>     generator
>>>         A function which returns an iterator.
>>>     <URL: https://docs.python.org/3/glossary.html>
>>
>> That glossary entry is misleading, or at least incomplete, and it
>> fails to match the way "generator" is used by actual Python
>> programmers.
>
> I am an actual Python programmer (I develop Python programs) and my
> definitive source for Python is the documentation. If there is an error
> in the documentation, I would very much like it to be corrected.

I think that Steven was basing his statement on the definition you
cited. I don't think that he actually went and looked up the
definition. If he had, he would have seen that you omitted 90% of it.
Here's the full entry:

"""
A function which returns an iterator. It looks like a normal function
except that it contains yield statements for producing a series of
values usable in a for-loop or that can be retrieved one at a time
with the next() function. Each yield temporarily suspends processing,
remembering the location execution state (including local variables
and pending try-statements). When the generator resumes, it picks-up
where it left-off (in contrast to functions which start fresh on every
invocation).
"""

>> A generator (function) may be a function which returns an iterator,
>> but not all functions that return iterators are generators, and in
>> some ways returning an iterator is the *least* interesting part of
>> what makes a generator a generator.
>>
>> What distinguishes a generator from a regular function is the use of
>> `yield`. Any definition which fails to mention that fact is useless.

As can be seen above, the glossary definition *does* in fact discuss
the use of yield.

> The language reference had better use more precise language. It *is* the
> definitive source, after all.

Okay, but you cited the glossary entry, not the language reference.
The language reference says this [1]:

"When a generator function is called, it returns an iterator known as
a generator."

Which I think is quite clear, although to be fair the same section
also uses "generator" alone to refer to the function in the preceding
paragraph. That usage however is justified by PEP 255 [2]:

"""
When a generator function is called, the actual arguments are bound to
function-local formal argument names in the usual way, but no code in
the body of the function is executed.  Instead a generator-iterator
object is returned; this conforms to the iterator protocol, so in
particular can be used in for-loops in a natural way.  Note that when
the intent is clear from context, the unqualified name "generator" may
be used to refer either to a generator-function or a
generator-iterator.

"""

Now which should be considered definitive, the language reference or
the PEP? This question is not rhetorical; I don't know the answer.
Regardless of the answer though, the PEP at least illuminates the
design intent of the terminology.


[1] https://docs.python.org/3/reference/expressions.html#yield-expressions

[2] https://www.python.org/dev/peps/pep-0255/