[Python-checkins] cpython (merge 3.3 -> default): Merge from 3.3 (issue #15209)

[nick.coghlan]

http://hg.python.org/cpython/rev/04eb89e078b5
changeset:   80776:04eb89e078b5
parent:      80774:b10c1c6f869f
parent:      80775:3b67247f0bbb
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Sun Dec 09 16:22:17 2012 +1000
summary:
  Merge from 3.3 (issue #15209)

files:
  Doc/library/exceptions.rst |  24 ++++++++++++++++--------
  1 files changed, 16 insertions(+), 8 deletions(-)


diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -39,19 +39,27 @@
 new exception is not handled the traceback that is eventually displayed will
 include the originating exception(s) and the final exception.
 
-When raising a new exception (rather than using to bare ``raise`` to re-raise
-the exception currently being handled), the implicit exception chain can be
-made explicit by using :keyword:`from` with :keyword:`raise`.  The single
-argument to :keyword:`from` must be an exception or ``None``. It will be set
-as :attr:`__cause__` on the raised exception. Setting :attr:`__cause__`
-also implicitly sets the :attr:`__suppress_context__` attribute to
-``True``.
+When raising a new exception (rather than using a bare ``raise`` to re-raise
+the exception currently being handled), the implicit exception context can be
+supplemented with an explicit cause by using :keyword:`from` with
+:keyword:`raise`::
+
+   raise new_exc from original_exc
+
+The expression following :keyword:`from` must be an exception or ``None``. It
+will be set as :attr:`__cause__` on the raised exception. Setting
+:attr:`__cause__` also implicitly sets the :attr:`__suppress_context__`
+attribute to ``True``, so that using ``raise new_exc from None``
+effectively replaces the old exception with the new one for display
+purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`, while
+leaving the old exception available in :attr:`__context__` for introspection
+when debugging.
 
 The default traceback display code shows these chained exceptions in
 addition to the traceback for the exception itself. An explicitly chained
 exception in :attr:`__cause__` is always shown when present. An implicitly
 chained exception in :attr:`__context__` is shown only if :attr:`__cause__`
-is not set and :attr:`__suppress_context__` is false.
+is :const:`None` and :attr:`__suppress_context__` is false.
 
 In either case, the exception itself is always shown after any chained
 exceptions so that the final line of the traceback always shows the last

-- 
Repository URL: http://hg.python.org/cpython