generator/coroutine terminology

[Marko Rauhamaa]

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.

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

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

> Like many English words, we have two meanings for "generator":
>
> (1) A function containing the `yield` keyword, or "generator-function".
>
> (2) The result of calling such a function, an instance of
> types.GeneratorType. PEP 255 calls that a "generator-iterator", but
> that name doesn't appear to have caught on anywhere.
>
> If people can cope with the difference between a TV program and a
> computer program, they can cope with "generator" having two meanings,
> especially since we have ways to disambiguate between the two when
> needed.

I think that is untenable when you talk about a programming language.

>> I don't think you should read much into what str(obj) returns. It's
>> not much more than a random printable some CPython coder has cooked
>> up in the heat of the moment.
>
> I think that is completely wrong. The repr() and str() of generator
> instances is hardly "random", it reflects the consensus of the PEP
> authors and the Python core developers, in particular the BDFL Guido
> who approved the PEP, that the type of object it is should be called
> "generator".

Be that as it may,

   <URL: https://docs.python.org/3/reference/>

and

   <URL: https://docs.python.org/3/library/>

are the definitive sources for Python application programmers.

Or is there a better reference you would recommend?


Marko