#3113: document exception chaining.
This commit is contained in:
parent
0f6de936f8
commit
1aea30aa85
|
@ -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:
|
||||
|
||||
* 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.
|
||||
|
||||
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:: print_exc([limit[, file]])
|
||||
.. function:: print_exc([limit[, file[, chain]]])
|
||||
|
||||
This is a shorthand for ``print_exception(*sys.exc_info())``.
|
||||
|
||||
|
||||
.. function:: format_exc([limit])
|
||||
|
||||
This is like ``print_exc(limit)`` but returns a string instead of printing to a
|
||||
file.
|
||||
|
||||
|
||||
.. 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))``.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
.. 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::
|
||||
|
||||
The "from" clause is used for exception chaining, which is not documented yet.
|
||||
>>> 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`.
|
||||
|
|
Loading…
Reference in New Issue