From 66a86e1246e3853adac4a7e7e111f67c49ca235f Mon Sep 17 00:00:00 2001 From: Connor Denihan Date: Wed, 4 Jun 2025 19:02:25 -0400 Subject: [PATCH 1/4] Fix misleading generator.close() documentation The documentation incorrectly stated that generator.close() 'raises' a GeneratorExit exception. This was misleading because the method doesn't raise the exception to the caller - it sends the exception internally to the generator and returns None. Changed 'raises' to 'sends' in both Doc/reference/expressions.rst and Doc/howto/functional.rst for consistency and accuracy. Fixes #135110 --- Doc/howto/functional.rst | 2 +- Doc/reference/expressions.rst | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index b4f3463afee812..684df79c4f8350 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -602,7 +602,7 @@ generators: raise an exception inside the generator; the exception is raised by the ``yield`` expression where the generator's execution is paused. -* :meth:`~generator.close` raises a :exc:`GeneratorExit` exception inside the +* :meth:`~generator.close` sends a :exc:`GeneratorExit` exception inside the generator to terminate the iteration. On receiving this exception, the generator's code must either raise :exc:`GeneratorExit` or :exc:`StopIteration`; catching the exception and doing anything else is diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 2a550b504ca765..690207b07fd5ee 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -625,8 +625,9 @@ is already executing raises a :exc:`ValueError` exception. .. method:: generator.close() - Raises a :exc:`GeneratorExit` at the point where the generator function was - paused. If the generator function catches the exception and returns a + Sends a :exc:`GeneratorExit` exception to the generator at the point where + the generator function was paused. If the generator function catches the + exception and returns a value, this value is returned from :meth:`close`. If the generator function is already closed, or raises :exc:`GeneratorExit` (by not catching the exception), :meth:`close` returns :const:`None`. If the generator yields a From fe86c406ded58552a09957cf6112140c92a44675 Mon Sep 17 00:00:00 2001 From: Connor Denihan Date: Fri, 20 Jun 2025 11:44:12 -0400 Subject: [PATCH 2/4] Doc: Clarify generator.close() documentation Replace 'sends' with 'raises' and clarify that close() is equivalent to throw(GeneratorExit). This makes the documentation clearer and avoids confusion with generator.send(). --- Doc/reference/expressions.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 690207b07fd5ee..33a5c2af0af8f6 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -625,9 +625,10 @@ is already executing raises a :exc:`ValueError` exception. .. method:: generator.close() - Sends a :exc:`GeneratorExit` exception to the generator at the point where - the generator function was paused. If the generator function catches the - exception and returns a + Raises a :exc:`GeneratorExit` exception at the point where the generator + function was paused (equivalent to calling ``throw(GeneratorExit)``). + The exception is raised by the yield expression where the generator was paused. + If the generator function catches the exception and returns a value, this value is returned from :meth:`close`. If the generator function is already closed, or raises :exc:`GeneratorExit` (by not catching the exception), :meth:`close` returns :const:`None`. If the generator yields a From 941816aea3c59c727f43bc385175623bab2127c8 Mon Sep 17 00:00:00 2001 From: Connor Denihan Date: Fri, 20 Jun 2025 11:51:25 -0400 Subject: [PATCH 3/4] Remove trailing whitespace --- Doc/reference/expressions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 33a5c2af0af8f6..c6b961348be9f6 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -625,8 +625,8 @@ is already executing raises a :exc:`ValueError` exception. .. method:: generator.close() - Raises a :exc:`GeneratorExit` exception at the point where the generator - function was paused (equivalent to calling ``throw(GeneratorExit)``). + Raises a :exc:`GeneratorExit` exception at the point where the generator + function was paused (equivalent to calling ``throw(GeneratorExit)``). The exception is raised by the yield expression where the generator was paused. If the generator function catches the exception and returns a value, this value is returned from :meth:`close`. If the generator function From bad5fe5c9768d76c80d28aaec1a2d61b57f8ac41 Mon Sep 17 00:00:00 2001 From: Connor Denihan <188690869+cdenihan@users.noreply.github.com> Date: Fri, 20 Jun 2025 12:15:49 -0400 Subject: [PATCH 4/4] Update functional.rst Co-authored-by: Peter Bierma --- Doc/howto/functional.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index 684df79c4f8350..78e56e0c64fb10 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -602,7 +602,7 @@ generators: raise an exception inside the generator; the exception is raised by the ``yield`` expression where the generator's execution is paused. -* :meth:`~generator.close` sends a :exc:`GeneratorExit` exception inside the +* :meth:`~generator.close` sends a :exc:`GeneratorExit` exception to the generator to terminate the iteration. On receiving this exception, the generator's code must either raise :exc:`GeneratorExit` or :exc:`StopIteration`; catching the exception and doing anything else is