From 90758c0d97ccf9f5b5fbf68e3fef02b6e344040f Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Thu, 4 Jun 2026 09:45:31 +0000 Subject: [PATCH 1/5] Clarify generator, generator function, and generator iterator in glossary --- Doc/glossary.rst | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 3ac622709241717..1aaf8469ee408b3 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -641,23 +641,35 @@ Glossary .. index:: single: generator generator - A function which returns a :term:`generator iterator`. It looks like a - normal function except that it contains :keyword:`yield` expressions - for producing a series of values usable in a for-loop or that can be - retrieved one at a time with the :func:`next` function. + An :term:`iterator` object created by a :term:`generator function` or + a :term:`generator expression`. + + Usually refers to a generator iterator object, but in some contexts + may refer to a :term:`generator function`. In cases where the + intended meaning isn't clear, using the full terms avoids ambiguity. - Usually refers to a generator function, but may refer to a - *generator iterator* in some contexts. In cases where the intended - meaning isn't clear, using the full terms avoids ambiguity. + .. index:: single: generator function + + generator function + A function which returns a :term:`generator` object. It looks like a + normal function except that it contains :keyword:`yield` expressions + for producing a series of values usable in a :keyword:`for`\-loop or + that can be retrieved one at a time with the :func:`next` function. + See :pep:`255`. generator iterator - An object created by a :term:`generator` function. + An object created by a :term:`generator function` or a + :term:`generator expression`. Each :keyword:`yield` temporarily suspends processing, remembering the - execution state (including local variables and pending - try-statements). When the *generator iterator* resumes, it picks up where - it left off (in contrast to functions which start fresh on every - invocation). + execution state (including local variables and pending try-statements). + When the *generator iterator* resumes, it picks up where it left off + (in contrast to functions which start fresh on every invocation). + + Generator iterators also implement the :meth:`~generator.send` method + to send a value into the suspended generator, and the + :meth:`~generator.throw` method to raise an exception at the point + where the generator was paused. See :pep:`342`. .. index:: single: generator expression From 80fde9d5ff46cf88dc6d7a8e99d7235537037c86 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Fri, 5 Jun 2026 14:10:01 +0000 Subject: [PATCH 2/5] improve generator --- Doc/glossary.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 1aaf8469ee408b3..f4276aea90123b7 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -641,12 +641,10 @@ Glossary .. index:: single: generator generator - An :term:`iterator` object created by a :term:`generator function` or - a :term:`generator expression`. - - Usually refers to a generator iterator object, but in some contexts - may refer to a :term:`generator function`. In cases where the - intended meaning isn't clear, using the full terms avoids ambiguity. + Informally used to mean either a :term:`generator function` or a + :term:`generator iterator`, depending on context. The formal terms + :term:`generator function` and :term:`generator iterator` are uncommon + in practice; "generator" alone is almost always sufficient. .. index:: single: generator function From 226dc9018956fc6210c23b7a062ff4f232397007 Mon Sep 17 00:00:00 2001 From: Aniket <148300120+Aniketsy@users.noreply.github.com> Date: Sat, 6 Jun 2026 08:43:36 +0530 Subject: [PATCH 3/5] Update Doc/glossary.rst Co-authored-by: Ned Batchelder --- Doc/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index f4276aea90123b7..631f962d8e24879 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -653,7 +653,7 @@ Glossary normal function except that it contains :keyword:`yield` expressions for producing a series of values usable in a :keyword:`for`\-loop or that can be retrieved one at a time with the :func:`next` function. - See :pep:`255`. + See :ref:`yieldexpr`. generator iterator An object created by a :term:`generator function` or a From c5a8f8dfd5980117ae1c053c632a52d87da78154 Mon Sep 17 00:00:00 2001 From: Aniket <148300120+Aniketsy@users.noreply.github.com> Date: Sat, 6 Jun 2026 08:46:18 +0530 Subject: [PATCH 4/5] Update Doc/glossary.rst --- Doc/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 631f962d8e24879..9166a3d3b308ca5 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -667,7 +667,7 @@ Glossary Generator iterators also implement the :meth:`~generator.send` method to send a value into the suspended generator, and the :meth:`~generator.throw` method to raise an exception at the point - where the generator was paused. See :pep:`342`. + where the generator was paused. See :ref:`generator-methods`. .. index:: single: generator expression From 5121135d4da08bb4ed933a1472ee4400623d0b09 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Mon, 8 Jun 2026 07:47:20 +0000 Subject: [PATCH 5/5] Clarify generator and asynchronous generator glossary terms --- Doc/glossary.rst | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 9166a3d3b308ca5..ead31d526d40bc3 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -96,21 +96,18 @@ Glossary :meth:`~object.__aexit__` methods. Introduced by :pep:`492`. asynchronous generator - A function which returns an :term:`asynchronous generator iterator`. It - looks like a coroutine function defined with :keyword:`async def` except - that it contains :keyword:`yield` expressions for producing a series of - values usable in an :keyword:`async for` loop. - - Usually refers to an asynchronous generator function, but may refer to an - *asynchronous generator iterator* in some contexts. In cases where the - intended meaning isn't clear, using the full terms avoids ambiguity. + Informally used to mean either an :term:`asynchronous generator + function` or an :term:`asynchronous generator iterator`, depending on + context. The formal terms :term:`asynchronous generator function` and + :term:`asynchronous generator iterator` are uncommon in practice; + "asynchronous generator" alone is almost always sufficient. An asynchronous generator function may contain :keyword:`await` expressions as well as :keyword:`async for`, and :keyword:`async with` statements. asynchronous generator iterator - An object created by an :term:`asynchronous generator` function. + An object created by an :term:`asynchronous generator function`. This is an :term:`asynchronous iterator` which when called using the :meth:`~object.__anext__` method returns an awaitable object which will execute