From c590c2338e5a36cf3ce5b55e6d366a0675ed1db5 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Wed, 16 Dec 2020 16:03:32 +0000 Subject: bpo-23915: update and elucidate documentation of with_traceback (GH-23680) --- Doc/library/exceptions.rst | 9 +++++++-- 1 file 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: ... -- cgit v0.12