diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -430,12 +430,28 @@ .. method:: generator.throw(type[, value[, traceback]]) - Raises an exception of type ``type`` at the point where 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 compatibility, however, the arguments follow a convention from + older versions of python. ``type`` can be an exception class or an exception + instance, and ``value`` can be const:`None`, an exception instance, a single + argument or an argument tuple to be passed to the exception class constructor. + If provided, the ``tb`` argument is used for the raised exception, otherwise + the excepition instance's :attr:`__traceback__` attribute is used. + + Example:: + try: + generator.send(foo()) + except Exception as e: + generator.throw(e.with_traceback(None)) + .. index:: exception: GeneratorExit