diff --git a/Doc/glossary.rst b/Doc/glossary.rst --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -242,19 +242,11 @@ performs garbage collection via reference counting and a cyclic garbage collector that is able to detect and break reference cycles. - .. index:: single: generator + generator + A :term:`generator function` or :term:`generator iterator`, depending + on context. - generator - A function which returns an iterator. It looks like a normal function - except that it contains :keyword:`yield` statements for producing a series - a values usable in a for-loop or that can be retrieved one at a time with - the :func:`next` function. Each :keyword:`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). - - .. index:: single: generator expression + .. index:: single: generator; expression generator expression An expression that returns an iterator. It looks like a normal expression @@ -265,6 +257,37 @@ >>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81 285 + .. index:: single: generator; function + + generator function + A function that contains a :keyword:`yield` statement. Calling + a generator function returns a special type of :term:`iterator` called + a :term:`generator iterator`. + + The yield statements are for producing a series of values that can + be used in a for loop or retrieved one at a time with + the :func:`next` function. Each :keyword:`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). + + More information can be found in the :ref:`yieldexpr` documentation. + + .. index:: single: generator; iterator + + generator iterator + An :term:`iterator` constructed by calling a :term:`generator function`. + Generator iterators are also called :dfn:`generator objects` or + more simply :dfn:`generators`. + + More information can be found in the :ref:`yieldexpr` documentation. + + .. index:: single: generator; object + + generator object + See :term:`generator iterator`. + GIL See :term:`global interpreter lock`. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -784,17 +784,18 @@ property are deemed broken. +.. index:: single: generator .. _generator-types: Generator Types --------------- -Python's :term:`generator`\s provide a convenient way to implement the iterator -protocol. If a container object's :meth:`__iter__` method is implemented as a -generator, it will automatically return an iterator object (technically, a -generator object) supplying the :meth:`__iter__` and :meth:`__next__` methods. -More information about generators can be found in :ref:`the documentation for -the yield expression `. +Python's :term:`generator`\s provide a convenient way to implement the +iterator protocol. If a function contains a :keyword:`yield` statement +(a generator function), calling the function automatically returns an +iterator object (technically, a generator iterator) supplying the +:meth:`__iter__` and :meth:`__next__` methods. More information about +generators can be found in the :ref:`yieldexpr` documentation. .. _typesseq: diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -597,16 +597,20 @@ single: generator; function single: generator; iterator - A function or method which uses the :keyword:`yield` statement (see section - :ref:`yield`) is called a :dfn:`generator function`. Such a function, when - called, always returns an iterator object which can be used to execute the - body of the function: calling the iterator's :meth:`__next__` method will + A function or method which uses the :keyword:`yield` statement is + called a :dfn:`generator function`. Calling such a function returns + an iterator object called a :dfn:`generator iterator` which can be + used to execute a code object compiled from the body of the generator + function that created it: + calling the iterator's :meth:`__next__` method will cause the function to execute until it provides a value using the :keyword:`yield` statement. When the function executes a :keyword:`return` statement or falls off the end, a :exc:`StopIteration` exception is raised and the iterator will have reached the end of the set of values to be returned. + More information can be found in the :ref:`yieldexpr` documentation. + Built-in functions .. index:: object: built-in function @@ -870,7 +874,9 @@ :attr:`co_stacksize` is the required stack size (including local variables); :attr:`co_flags` is an integer encoding a number of flags for the interpreter. - .. index:: object: generator + .. index:: + single: object; generator function + single: generator; function code object The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if the function uses the ``*arguments`` syntax to accept an arbitrary number of diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -282,7 +282,6 @@ --------------------- .. index:: pair: generator; expression - object: generator A generator expression is a compact generator notation in parentheses: @@ -325,9 +324,12 @@ :keyword:`yield` expression in a function definition is sufficient to cause that definition to create a generator function instead of a normal function. -When a generator function is called, it returns an iterator known as a -generator. That generator then controls the execution of a generator function. -The execution starts when one of the generator's methods is called. At that +When a generator function is called, it compiles its body into a code object +and returns an iterator known as a generator iterator, or more commonly, +a generator. That generator controls the execution of the code object +coming from the generator function that created it. + +Execution starts when one of the generator's methods is called. At that time, the execution proceeds to the first :keyword:`yield` expression, where it is suspended again, returning the value of :token:`expression_list` to generator's caller. By suspended we mean that all local state is retained, @@ -343,10 +345,11 @@ .. index:: single: coroutine -All of this makes generator functions quite similar to coroutines; they yield -multiple times, they have more than one entry point and their execution can be -suspended. The only difference is that a generator function cannot control -where should the execution continue after it yields; the control is always +All of this makes the code objects coming from generator functions quite +similar to coroutines: they yield +multiple times, they have more than one entry point, and their execution can be +suspended. The only difference is that they cannot control +where execution should continue after they yield; control is always transferred to the generator's caller. :keyword:`yield` expressions are allowed in the :keyword:`try` clause of a @@ -375,10 +378,15 @@ The parentheses can be omitted when the :keyword:`yield` expression is the sole expression on the right hand side of an assignment statement. -.. index:: object: generator +.. index:: + single: object; generator iterator + single: generator; methods -The following generator's methods can be used to control the execution of a -generator function: +Generator-iterator methods +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following generator methods can be used to control the execution of +the generator function code object associated with a generator: .. index:: exception: StopIteration diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -205,6 +205,9 @@ Documentation ------------- +- Issue #15457: Add terminology consistency to generator documentation + and improve indexing. Patch by Chris Jerdonek. + - Issue #15230: Clearly document some of the limitations of the runpy module and nudge readers towards importlib when appropriate.