bpo-14911: Corrected generator.throw() documentation (GH-32207) · python/cpython@98d5773 (original) (raw)

4 files changed

lines changed

Original file line number Diff line number Diff line change
@@ -589,7 +589,7 @@ generator function.
589 589 In addition to :meth:`~generator.send`, there are two other methods on
590 590 generators:
591 591
592 -* :meth:`throw(type, value=None, traceback=None) <generator.throw>` is used to
592 +* :meth:`throw(value) <generator.throw>` is used to
593 593 raise an exception inside the generator; the exception is raised by the
594 594 ``yield`` expression where the generator's execution is paused.
595 595
Original file line number Diff line number Diff line change
@@ -2854,7 +2854,8 @@ generators, coroutines do not directly support iteration.
2854 2854 :exc:`StopIteration`, or other exception) is the same as when
2855 2855 iterating over the :meth:`__await__` return value, described above.
2856 2856
2857 -.. method:: coroutine.throw(type[, value[, traceback]])
2857 +.. method:: coroutine.throw(value)
2858 + coroutine.throw(type[, value[, traceback]])
2858 2859
2859 2860 Raises the specified exception in the coroutine. This method delegates
2860 2861 to the :meth:`~generator.throw` method of the iterator that caused
Original file line number Diff line number Diff line change
@@ -557,14 +557,27 @@ is already executing raises a :exc:`ValueError` exception.
557 557 could receive the value.
558 558
559 559
560 -.. method:: generator.throw(type[, value[, traceback]])
560 +.. method:: generator.throw(value)
561 + generator.throw(type[, value[, traceback]])
561 562
562 - Raises an exception of type ``type`` at the point where the generator was paused,
563 + Raises an exception at the point where the generator was paused,
563 564 and returns the next value yielded by the generator function. If the generator
564 565 exits without yielding another value, a :exc:`StopIteration` exception is
565 566 raised. If the generator function does not catch the passed-in exception, or
566 567 raises a different exception, then that exception propagates to the caller.
567 568
569 + In typical use, this is called with a single exception instance similar to the
570 + way the :keyword:`raise` keyword is used.
571 +
572 + For backwards compatability, however, the second signature is
573 + supported, following a convention from older versions of Python.
574 + The *type* argument should be an exception class, and *value*
575 + should be an exception instance. If the *value* is not provided, the
576 + *type* constructor is called to get an instance. If *traceback*
577 + is provided, it is set on the exception, otherwise any existing
578 +:attr:`~BaseException.__traceback__` attribute stored in *value* may
579 + be cleared.
580 +
568 581 .. index:: exception: GeneratorExit
569 582
570 583
Original file line number Diff line number Diff line change
@@ -384,8 +384,11 @@ gen_close(PyGenObject *gen, PyObject *args)
384 384
385 385
386 386 PyDoc_STRVAR(throw_doc,
387 -"throw(typ[,val[,tb]]) -> raise exception in generator,\n\
388 -return next yielded value or raise StopIteration.");
387 +"throw(value)\n\
388 +throw(type[,value[,tb]])\n\
389 +\n\
390 +Raise exception in generator, return next yielded value or raise\n\
391 +StopIteration.");
389 392
390 393 static PyObject *
391 394 _gen_throw(PyGenObject *gen, int close_on_genexit,
@@ -943,8 +946,11 @@ PyDoc_STRVAR(coro_send_doc,
943 946 return next iterated value or raise StopIteration.");
944 947
945 948 PyDoc_STRVAR(coro_throw_doc,
946 -"throw(typ[,val[,tb]]) -> raise exception in coroutine,\n\
947 -return next iterated value or raise StopIteration.");
949 +"throw(value)\n\
950 +throw(type[,value[,traceback]])\n\
951 +\n\
952 +Raise exception in coroutine, return next iterated value or raise\n\
953 +StopIteration.");
948 954
949 955 PyDoc_STRVAR(coro_close_doc,
950 956 "close() -> raise GeneratorExit inside coroutine.");