From 44bb1f1e0c625f78858620ba92e99f7e63b549b0 Mon Sep 17 00:00:00 2001 From: David Goncalves Date: Wed, 30 Mar 2022 17:44:42 -0700 Subject: [PATCH 1/3] bpo-14911: Corrected generator.throw() documentation --- Doc/howto/functional.rst | 2 +- Doc/reference/datamodel.rst | 3 ++- Doc/reference/expressions.rst | 17 +++++++++++++++-- Objects/genobject.c | 14 ++++++++++---- 4 files changed, 28 insertions(+), 8 deletions(-) diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index c7f8bc8f17f43b..695b9b31a762bd 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) ` is used to +* :meth:`throw(value) ` 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 804332ffab6fd6..0c3c53e8d2d9d6 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:: couroutine.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 bb6d1dc1cdd04f..b914c48d3d4cd5 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 f071390d6d32bb..61c51fcdd86ea9 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."); From 07e19b1c581de3eb34dd3dbac49f2ef92c2dd8f6 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Thu, 31 Mar 2022 15:49:31 +0300 Subject: [PATCH 2/3] Fix spaces --- Objects/genobject.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Objects/genobject.c b/Objects/genobject.c index 61c51fcdd86ea9..cdb2a0f76b0858 100644 --- a/Objects/genobject.c +++ b/Objects/genobject.c @@ -1161,7 +1161,7 @@ return next iterated value or raise StopIteration."); PyDoc_STRVAR(coro_throw_doc, "throw(value)\n\ -throw(type[,value[,traceback]])\n\ +throw(type[,value[,traceback]])\n\ \n\ Raise exception in coroutine, return next iterated value or raise\n\ StopIteration."); From 42c84a32763446e73e0fd922737c0271a25a1315 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Thu, 31 Mar 2022 16:19:44 +0300 Subject: [PATCH 3/3] Update Doc/reference/datamodel.rst --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 0c3c53e8d2d9d6..8ac9a8c0566bf7 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2984,7 +2984,7 @@ 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:: couroutine.throw(value) +.. method:: coroutine.throw(value) coroutine.throw(type[, value[, traceback]]) Raises the specified exception in the coroutine. This method delegates