From: Connor Denihan <188690869+cdenihan@users.noreply.github.com>
Date: Thu, 26 Jun 2025 13:27:25 +0000 (-0400)
Subject: gh-135110: Fix misleading `generator.close()` documentation (GH-135152)
X-Git-Tag: v3.15.0a1~1173
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0d76dccc3b4376ba075a1737f58809e3d83aaaa3;p=thirdparty%2FPython%2Fcpython.git

gh-135110: Fix misleading `generator.close()` documentation (GH-135152)

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.
---

diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
index b4f3463afee8..78e56e0c64fb 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 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
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 17f39aaf5f57..24544a055c3e 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -625,8 +625,10 @@ 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
+   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