georg.brandl
2008-07-19 15:51:08 UTC
Author: georg.brandl
Date: Sat Jul 19 17:51:07 2008
New Revision: 65144
Log:
#3113: document exception chaining.
Modified:
python/branches/py3k/Doc/library/traceback.rst
python/branches/py3k/Doc/reference/executionmodel.rst
python/branches/py3k/Doc/reference/simple_stmts.rst
Modified: python/branches/py3k/Doc/library/traceback.rst
==============================================================================
--- python/branches/py3k/Doc/library/traceback.rst (original)
+++ python/branches/py3k/Doc/library/traceback.rst Sat Jul 19 17:51:07 2008
@@ -1,4 +1,3 @@
-
:mod:`traceback` --- Print or retrieve a stack traceback
========================================================
@@ -29,29 +28,31 @@
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.
-
-
-.. function:: print_exc([limit[, file]])
+ *traceback* to *file*. This differs from :func:`print_tb` in the following
+ ways:
- This is a shorthand for ``print_exception(*sys.exc_info())``.
+ * 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:: format_exc([limit])
+.. function:: print_exc([limit[, file[, chain]]])
- This is like ``print_exc(limit)`` but returns a string instead of printing to a
- file.
+ This is a shorthand for ``print_exception(*sys.exc_info())``.
-.. 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 @@
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 @@
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))``.
Modified: python/branches/py3k/Doc/reference/executionmodel.rst
==============================================================================
--- python/branches/py3k/Doc/reference/executionmodel.rst (original)
+++ python/branches/py3k/Doc/reference/executionmodel.rst Sat Jul 19 17:51:07 2008
@@ -230,6 +230,7 @@
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
Modified: python/branches/py3k/Doc/reference/simple_stmts.rst
==============================================================================
--- python/branches/py3k/Doc/reference/simple_stmts.rst (original)
+++ python/branches/py3k/Doc/reference/simple_stmts.rst Sat Jul 19 17:51:07 2008
@@ -476,6 +476,7 @@
statement: raise
single: exception
pair: raising; exception
+ single: __traceback__ (exception attribute)
.. productionlist::
raise_stmt: "raise" [`expression` ["from" `expression`]]
@@ -503,9 +504,49 @@
raise RuntimeError("foo occurred").with_traceback(tracebackobj)
-.. XXX document exception chaining
-
-The "from" clause is used for exception chaining, which is not documented yet.
+.. 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::
+
+ >>> 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`.
Date: Sat Jul 19 17:51:07 2008
New Revision: 65144
Log:
#3113: document exception chaining.
Modified:
python/branches/py3k/Doc/library/traceback.rst
python/branches/py3k/Doc/reference/executionmodel.rst
python/branches/py3k/Doc/reference/simple_stmts.rst
Modified: python/branches/py3k/Doc/library/traceback.rst
==============================================================================
--- python/branches/py3k/Doc/library/traceback.rst (original)
+++ python/branches/py3k/Doc/library/traceback.rst Sat Jul 19 17:51:07 2008
@@ -1,4 +1,3 @@
-
:mod:`traceback` --- Print or retrieve a stack traceback
========================================================
@@ -29,29 +28,31 @@
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.
-
-
-.. function:: print_exc([limit[, file]])
+ *traceback* to *file*. This differs from :func:`print_tb` in the following
+ ways:
- This is a shorthand for ``print_exception(*sys.exc_info())``.
+ * 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:: format_exc([limit])
+.. function:: print_exc([limit[, file[, chain]]])
- This is like ``print_exc(limit)`` but returns a string instead of printing to a
- file.
+ This is a shorthand for ``print_exception(*sys.exc_info())``.
-.. 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 @@
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 @@
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))``.
Modified: python/branches/py3k/Doc/reference/executionmodel.rst
==============================================================================
--- python/branches/py3k/Doc/reference/executionmodel.rst (original)
+++ python/branches/py3k/Doc/reference/executionmodel.rst Sat Jul 19 17:51:07 2008
@@ -230,6 +230,7 @@
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
Modified: python/branches/py3k/Doc/reference/simple_stmts.rst
==============================================================================
--- python/branches/py3k/Doc/reference/simple_stmts.rst (original)
+++ python/branches/py3k/Doc/reference/simple_stmts.rst Sat Jul 19 17:51:07 2008
@@ -476,6 +476,7 @@
statement: raise
single: exception
pair: raising; exception
+ single: __traceback__ (exception attribute)
.. productionlist::
raise_stmt: "raise" [`expression` ["from" `expression`]]
@@ -503,9 +504,49 @@
raise RuntimeError("foo occurred").with_traceback(tracebackobj)
-.. XXX document exception chaining
-
-The "from" clause is used for exception chaining, which is not documented yet.
+.. 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::
+
+ >>> 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`.