#3113: document exception chaining.

3 files changed, 68 insertions, 19 deletions

diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 389753a..dd3ae69 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -1,4 +1,3 @@
-
 :mod:`traceback` --- Print or retrieve a stack traceback
 ========================================================
 
@@ -29,29 +28,31 @@ The module defines the following functions:
    object to receive the output.
 
 
-.. function:: print_exception(type, value, traceback[, limit[, file]])
+.. function:: print_exception(type, value, traceback[, limit[, file[, chain]]])
 
    Print exception information and up to *limit* stack trace entries from
-   *traceback* to *file*. This differs from :func:`print_tb` in the following ways:
-   (1) if *traceback* is not ``None``, it prints a header ``Traceback (most recent
-   call last):``; (2) it prints the exception *type* and *value* after the stack
-   trace; (3) if *type* is :exc:`SyntaxError` and *value* has the appropriate
-   format, it prints the line where the syntax error occurred with a caret
-   indicating the approximate position of the error.
-
+   *traceback* to *file*. This differs from :func:`print_tb` in the following
+   ways:
 
-.. function:: print_exc([limit[, file]])
+   * if *traceback* is not ``None``, it prints a header ``Traceback (most recent
+     call last):``
+   * it prints the exception *type* and *value* after the stack trace
+   * if *type* is :exc:`SyntaxError` and *value* has the appropriate format, it
+     prints the line where the syntax error occurred with a caret indicating the
+     approximate position of the error.
 
-   This is a shorthand for ``print_exception(*sys.exc_info())``.
+   If *chain* is true (the default), then chained exceptions (the
+   :attr:`__cause__` or :attr:`__context__` attributes of the exception) will be
+   printed as well, like the interpreter itself does when printing an unhandled
+   exception.
 
 
-.. function:: format_exc([limit])
+.. function:: print_exc([limit[, file[, chain]]])
 
-   This is like ``print_exc(limit)`` but returns a string instead of printing to a
-   file.
+   This is a shorthand for ``print_exception(*sys.exc_info())``.
 
 
-.. function:: print_last([limit[, file]])
+.. function:: print_last([limit[, file[, chain]]])
 
    This is a shorthand for ``print_exception(sys.last_type, sys.last_value,
    sys.last_traceback, limit, file)``.
@@ -103,7 +104,7 @@ The module defines the following functions:
    occurred is the always last string in the list.
 
 
-.. function:: format_exception(type, value, tb[, limit])
+.. function:: format_exception(type, value, tb[, limit[, chain]])
 
    Format a stack trace and the exception information.  The arguments  have the
    same meaning as the corresponding arguments to :func:`print_exception`.  The
@@ -112,6 +113,12 @@ The module defines the following functions:
    same text is printed as does :func:`print_exception`.
 
 
+.. function:: format_exc([limit[, chain]])
+
+   This is like ``print_exc(limit)`` but returns a string instead of printing to a
+   file.
+
+
 .. function:: format_tb(tb[, limit])
 
    A shorthand for ``format_list(extract_tb(tb, limit))``.
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`.