#3113: document exception chaining.

2 files changed, 45 insertions, 3 deletions

diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst
index fefc146..6ec88f5 100644
--- a/Doc/reference/executionmodel.rst
+++ b/Doc/reference/executionmodel.rst
@@ -230,6 +230,7 @@ handler and can carry additional information about the exceptional condition.
 See also the description of the :keyword:`try` statement in section :ref:`try`
 and :keyword:`raise` statement in section :ref:`raise`.
 
+
 .. rubric:: Footnotes
 
 .. [#] This limitation occurs because the code that is executed by these operations
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 2f9db9d..e4c0192 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -476,6 +476,7 @@ The :keyword:`raise` statement
    statement: raise
    single: exception
    pair: raising; exception
+   single: __traceback__ (exception attribute)
 
 .. productionlist::
    raise_stmt: "raise" [`expression` ["from" `expression`]]
@@ -503,9 +504,49 @@ instance, with its traceback set to its argument), like so::
 
    raise RuntimeError("foo occurred").with_traceback(tracebackobj)
 
-.. XXX document exception chaining 
-
-The "from" clause is used for exception chaining, which is not documented yet.
+.. index:: pair: exception; chaining
+           __cause__ (exception attribute)
+           __context__ (exception attribute)
+   
+The ``from`` clause is used for exception chaining: if given, the second
+*expression* must be another exception class or instance, which will then be
+attached to the raised exception as the :attr:`__cause__` attribute (which is
+writable).  If the raised exception is not handled, both exceptions will be
+printed::
+
+   >>> try:
+   ...     print(1 / 0)
+   ... except Exception as exc:
+   ...     raise RuntimeError("Something bad happened") from exc
+   ...
+   Traceback (most recent call last):
+     File "<stdin>", line 2, in <module>
+   ZeroDivisionError: int division or modulo by zero
+
+   The above exception was the direct cause of the following exception:
+
+   Traceback (most recent call last):
+     File "<stdin>", line 4, in <module>
+   RuntimeError: Something bad happened
+
+A similar mechanism works implicitly if an exception is raised inside an
+exception handler: the previous exception is then attached as the new
+exception's :attr:`__context__` attribute::
+
+   >>> try:
+   ...     print(1 / 0)
+   ... except:
+   ...     raise RuntimeError("Something bad happened")
+   ...
+   Traceback (most recent call last):
+     File "<stdin>", line 2, in <module>
+   ZeroDivisionError: int division or modulo by zero
+
+   During handling of the above exception, another exception occurred:
+
+   Traceback (most recent call last):
+     File "<stdin>", line 4, in <module>
+   RuntimeError: Something bad happened
 
 Additional information on exceptions can be found in section :ref:`exceptions`,
 and information about handling exceptions is in section :ref:`try`.