diff options
| author | Nick Coghlan <ncoghlan@gmail.com> | 2012-12-08 11:39:24 (GMT) |
|---|---|---|
| committer | Nick Coghlan <ncoghlan@gmail.com> | 2012-12-08 11:39:24 (GMT) |
| commit | 8e18fc8c0b8f9daa13d62c0b674ca5872c6a3b4c (patch) | |
| tree | d62ac2d3bcbf0e5a84a2aef1caaa86f1b7c44ce4 | |
| parent | c990f3b167fab45ff48fd6e7083e68bb44140b82 (diff) | |
| download | cpython-8e18fc8c0b8f9daa13d62c0b674ca5872c6a3b4c.zip cpython-8e18fc8c0b8f9daa13d62c0b674ca5872c6a3b4c.tar.gz cpython-8e18fc8c0b8f9daa13d62c0b674ca5872c6a3b4c.tar.bz2 | |
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
| -rw-r--r-- | Doc/library/exceptions.rst | 28 | ||||
| -rw-r--r-- | Misc/NEWS | 3 |
2 files changed, 20 insertions, 11 deletions
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 5f2db54..4611689 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -39,17 +39,23 @@ When raising (or re-raising) an exception in an :keyword:`except` clause 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. - -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. +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``. + +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 @@ -322,6 +322,9 @@ Tools/Demos 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 |