On Sat, Mar 14, 2015 at 1:54 AM, Marko Rauhamaa <ma...@pacujo.net> wrote: > Steven D'Aprano <steve+comp.lang.pyt...@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/ -- https://mail.python.org/mailman/listinfo/python-list
