From 1aea30aa853759eb9be591ec05e5c809e3aab6a4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 19 Jul 2008 15:51:07 +0000 Subject: [PATCH] #3113: document exception chaining. --- Doc/library/traceback.rst | 41 +++++++++++++++++------------ Doc/reference/executionmodel.rst | 1 + Doc/reference/simple_stmts.rst | 45 ++++++++++++++++++++++++++++++-- 3 files changed, 68 insertions(+), 19 deletions(-) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 389753ac198..dd3ae6947e9 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: + + * 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))``. diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst index fefc14663f0..6ec88f5340a 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 2f9db9dee90..e4c01921539 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 +.. 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 "", line 2, in + ZeroDivisionError: int division or modulo by zero + + The above exception was the direct cause of the following exception: + + Traceback (most recent call last): + File "", line 4, in + 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 "", line 2, in + ZeroDivisionError: int division or modulo by zero + + During handling of the above exception, another exception occurred: + + Traceback (most recent call last): + File "", line 4, in + 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`.