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,36 @@ >>> 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`. + + 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,9 +597,10 @@ 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 + 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 the body of the function: 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 @@ -607,6 +608,8 @@ 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 +873,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: @@ -326,7 +325,8 @@ 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. +generator iterator, or more commonly, 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 time, the execution proceeds to the first :keyword:`yield` expression, where it is suspended again, returning the value of :token:`expression_list` to @@ -375,7 +375,12 @@ 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 + +Generator-iterator methods +^^^^^^^^^^^^^^^^^^^^^^^^^^ The following generator's methods can be used to control the execution of a generator function: diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -191,6 +191,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.