changeset: 80751:8ba3c975775b branch: 3.3 parent: 80749:cb40fe08ff43 user: Nick Coghlan date: Sat Dec 08 21:39:24 2012 +1000 files: Doc/library/exceptions.rst Misc/NEWS description: Issue #15209: Clarify exception chaining description - not allowed when implicitly re-raised the current exception - last exception raised is always displayed last - attempt to make it clearer when/if cause and context are shown diff -r cb40fe08ff43 -r 8ba3c975775b Doc/library/exceptions.rst --- a/Doc/library/exceptions.rst Sat Dec 08 12:30:44 2012 +0200 +++ b/Doc/library/exceptions.rst Sat Dec 08 21:39:24 2012 +1000 @@ -39,17 +39,23 @@ new exception is not handled the traceback that is eventually displayed will include the originating exception(s) and the final exception. -This 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__` implicitly sets the :attr:`__suppress_context__` to -``True``. If :attr:`__cause__` is an exception, it will be displayed. If -:attr:`__cause__` is present or :attr:`__suppress_context__` has a true value, -:attr:`__context__` will not be displayed. +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``. -In either case, the default exception handling code will not display any of the -remaining links in the :attr:`__context__` chain if :attr:`__cause__` has been -set. +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. + +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 +exception that was raised. Base classes diff -r cb40fe08ff43 -r 8ba3c975775b Misc/NEWS --- a/Misc/NEWS Sat Dec 08 12:30:44 2012 +0200 +++ b/Misc/NEWS Sat Dec 08 21:39:24 2012 +1000 @@ -322,6 +322,9 @@ Documentation ------------- +- Issue #15209: Clarify exception chaining description in exceptions module + documentation + - Issue #15990: Improve argument/parameter documentation. - Issue #16209: Move the documentation for the str built-in function to a new