[Python-checkins] bpo-14911: Corrected generator.throw() documentation (GH-32207)
asvetlov
webhook-mailer at python.org
Thu Mar 31 09:57:03 EDT 2022
https://github.com/python/cpython/commit/8be7c2bc5ad5e295f0f855bb31db412eef2c7c92
commit: 8be7c2bc5ad5e295f0f855bb31db412eef2c7c92
branch: main
author: Dave Goncalves <davegoncalves at gmail.com>
committer: asvetlov <andrew.svetlov at gmail.com>
date: 2022-03-31T16:56:48+03:00
summary:
bpo-14911: Corrected generator.throw() documentation (GH-32207)
Co-authored-by: Andrew Svetlov <andrew.svetlov at gmail.com>
files:
M Doc/howto/functional.rst
M Doc/reference/datamodel.rst
M Doc/reference/expressions.rst
M Objects/genobject.c
diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
index c7f8bc8f17f43..695b9b31a762b 100644
--- a/Doc/howto/functional.rst
+++ b/Doc/howto/functional.rst
@@ -589,7 +589,7 @@ generator function.
In addition to :meth:`~generator.send`, there are two other methods on
generators:
-* :meth:`throw(type, value=None, traceback=None) <generator.throw>` is used to
+* :meth:`throw(value) <generator.throw>` is used to
raise an exception inside the generator; the exception is raised by the
``yield`` expression where the generator's execution is paused.
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 804332ffab6fd..8ac9a8c0566bf 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2984,7 +2984,8 @@ generators, coroutines do not directly support iteration.
:exc:`StopIteration`, or other exception) is the same as when
iterating over the :meth:`__await__` return value, described above.
-.. method:: coroutine.throw(type[, value[, traceback]])
+.. method:: coroutine.throw(value)
+ coroutine.throw(type[, value[, traceback]])
Raises the specified exception in the coroutine. This method delegates
to the :meth:`~generator.throw` method of the iterator that caused
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index bb6d1dc1cdd04..b914c48d3d4cd 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -561,14 +561,27 @@ is already executing raises a :exc:`ValueError` exception.
could receive the value.
-.. method:: generator.throw(type[, value[, traceback]])
+.. method:: generator.throw(value)
+ generator.throw(type[, value[, traceback]])
- Raises an exception of type ``type`` at the point where the generator was paused,
+ Raises an exception at the point where the generator was paused,
and returns the next value yielded by the generator function. If the generator
exits without yielding another value, a :exc:`StopIteration` exception is
raised. If the generator function does not catch the passed-in exception, or
raises a different exception, then that exception propagates to the caller.
+ In typical use, this is called with a single exception instance similar to the
+ way the :keyword:`raise` keyword is used.
+
+ For backwards compatability, however, the second signature is
+ supported, following a convention from older versions of Python.
+ The *type* argument should be an exception class, and *value*
+ should be an exception instance. If the *value* is not provided, the
+ *type* constructor is called to get an instance. If *traceback*
+ is provided, it is set on the exception, otherwise any existing
+ :attr:`~BaseException.__traceback__` attribute stored in *value* may
+ be cleared.
+
.. index:: exception: GeneratorExit
diff --git a/Objects/genobject.c b/Objects/genobject.c
index f071390d6d32b..cdb2a0f76b085 100644
--- a/Objects/genobject.c
+++ b/Objects/genobject.c
@@ -410,8 +410,11 @@ gen_close(PyGenObject *gen, PyObject *args)
PyDoc_STRVAR(throw_doc,
-"throw(typ[,val[,tb]]) -> raise exception in generator,\n\
-return next yielded value or raise StopIteration.");
+"throw(value)\n\
+throw(type[,value[,tb]])\n\
+\n\
+Raise exception in generator, return next yielded value or raise\n\
+StopIteration.");
static PyObject *
_gen_throw(PyGenObject *gen, int close_on_genexit,
@@ -1157,8 +1160,11 @@ PyDoc_STRVAR(coro_send_doc,
return next iterated value or raise StopIteration.");
PyDoc_STRVAR(coro_throw_doc,
-"throw(typ[,val[,tb]]) -> raise exception in coroutine,\n\
-return next iterated value or raise StopIteration.");
+"throw(value)\n\
+throw(type[,value[,traceback]])\n\
+\n\
+Raise exception in coroutine, return next iterated value or raise\n\
+StopIteration.");
PyDoc_STRVAR(coro_close_doc,
"close() -> raise GeneratorExit inside coroutine.");
More information about the Python-checkins
mailing list