From: Irit Katriel <iritkatriel@yahoo.com>
Date: Wed, 16 Dec 2020 16:03:32 +0000 (+0000)
Subject: bpo-23915: update and elucidate documentation of with_traceback (GH-23680)
X-Git-Tag: v3.10.0a4~150
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=c590c2338e5a36cf3ce5b55e6d366a0675ed1db5;p=thirdparty%2FPython%2Fcpython.git

bpo-23915: update and elucidate documentation of with_traceback (GH-23680)
---

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 8fb25a50e2d4..1028213699d6 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:
              ...