bpo-14911: Corrected generator.throw() documentation (GH-32207)

Co-authored-by: Andrew Svetlov <andrew.svetlov@gmail.com>
This commit is contained in:
Dave Goncalves 2022-03-31 06:56:48 -07:00 committed by GitHub
parent a00518d9ad
commit 8be7c2bc5a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 28 additions and 8 deletions

View File

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

View File

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

View File

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

View File

@ -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.");