summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorIrit Katriel <iritkatriel@yahoo.com>2020-12-16 16:03:32 (GMT)
committerGitHub <noreply@github.com>2020-12-16 16:03:32 (GMT)
commitc590c2338e5a36cf3ce5b55e6d366a0675ed1db5 (patch)
tree9ba30c33c57e23bc0452cd53959da32b712a4657
parentfc3dca3e16a62690707dcdc923a577e5167a8e2a (diff)
downloadcpython-c590c2338e5a36cf3ce5b55e6d366a0675ed1db5.zip
cpython-c590c2338e5a36cf3ce5b55e6d366a0675ed1db5.tar.gz
cpython-c590c2338e5a36cf3ce5b55e6d366a0675ed1db5.tar.bz2
bpo-23915: update and elucidate documentation of with_traceback (GH-23680)
-rw-r--r--Doc/library/exceptions.rst9
1 files changed, 7 insertions, 2 deletions
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 8fb25a5..1028213 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -90,8 +90,13 @@ The following exceptions are used mostly as base classes for other exceptions.
.. method:: with_traceback(tb)
This method sets *tb* as the new traceback for the exception and returns
- the exception object. It is usually used in exception handling code like
- this::
+ the exception object. It was more commonly used before the exception
+ chaining features of :pep:`3134` became available. The following example
+ shows how we can convert an instance of ``SomeException`` into an
+ instance of ``OtherException`` while preserving the traceback. Once
+ raised, the current frame is pushed onto the traceback of the
+ ``OtherException``, as would have happened to the traceback of the
+ original ``SomeException`` had we allowed it to propagate to the caller.
try:
...