Allow Pdb to move between chained exception.

This lets Pdb receive an exception, instead of a traceback, and when
this is the case and the exception are chained, `exceptions` allow to
list and move between the chained exceptions.

That is to say if you have something like

    def out():
        try:
            middle()                                # B
        except Exception as e:
            raise ValueError("foo(): bar failed")   # A

    def middle():
        try:
            return inner(0)                         # D
        except Exception as e:
            raise ValueError("Middle fail") from e  # C

    def inner(x):
        1 / x                                       # E

Only A is reachable after calling `out()` and doing post mortem debug.
With this all A-E points are reachable with a combination of up/down,
and ``exception <number>``.

Note that while above each exception have a unique
`__cause__`/`__context__`, when both are present and different, each one
is separately listed (see later commits)

This also change the default behavior of ``pdb.pm()``, to receive
`sys.last_exc` so that chained exception navigation is enabled.

Closes gh-106670

Author: Carreau

Doc/library/pdb.rst

@@ -175,8 +175,8 @@ slightly different way:
 
 .. function:: pm()
 
-   Enter post-mortem debugging of the traceback found in
-   :data:`sys.last_traceback`.
+   Enter post-mortem debugging of the exception found in
+   :data:`sys.last_exc`.
 
 
 The ``run*`` functions and :func:`set_trace` are aliases for instantiating the
@@ -639,6 +639,54 @@ can be overridden by the local file.
 
    Print the return value for the last return of the current function.
 
+.. pdbcommand:: exceptions [excnumber]
+
+   List or jump between chained exceptions.
+
+   When using ``pdb.pm()``  or ``Pdb.post_mortem(...)`` with a chained exception
+   instead of a traceback, it will now allow the user to move between the
+   chained exceptions using ``exceptions`` command to list exceptions, and
+   ``exception <number>`` to switch to that exception.
+
+
+   Example::
+
+        def out():
+            try:
+                middle()
+            except Exception as e:
+                raise ValueError("reraise middle() error") from e
+
+        def middle():
+            try:
+                return inner(0)
+            except Exception as e:
+                raise ValueError("Middle fail")
+
+        def inner(x):
+            1 / x
+
+         out()
+
+   calling ``pdb.pm()`` will allow to move between exceptions::
+
+    > example.py(5)out()
+    -> raise ValueError("reraise middle() error") from e
+
+    (Pdb) exceptions
+      0 ZeroDivisionError('division by zero')
+      1 ValueError('Middle fail')
+    > 2 ValueError('reraise middle() error')
+
+    (Pdb) exceptions 0
+    > example.py(16)inner()
+    -> 1 / x
+
+    (Pdb) up
+    > example.py(10)middle()
+    -> return inner(0)
+
+
 .. rubric:: Footnotes
 
 .. [1] Whether a frame is considered to originate in a certain module

Lib/pdb.py

@@ -206,6 +206,8 @@ def namespace(self):
 line_prefix = '\n-> '   # Probably a better default
 
 class Pdb(bdb.Bdb, cmd.Cmd):
+    _chained_exceptions = []
+    _chained_exception_index = 0
 
     _previous_sigint_handler = None
 
@@ -414,16 +416,27 @@ def preloop(self):
                     self.message('display %s: %r  [old: %r]' %
                                  (expr, newvalue, oldvalue))
 
-    def interaction(self, frame, traceback):
+    def interaction(self, frame, tb_or_exc):
         # Restore the previous signal handler at the Pdb prompt.
+
+        if isinstance(tb_or_exc, BaseException):
+            tb_or_exc, exception = tb_or_exc.__traceback__, tb_or_exc
+            self._chained_exceptions = [exception]
+            current = exception
+            while current := current.__context__:
+                self._chained_exception_index += 1
+                self._chained_exceptions.insert(0, current)
+        else:
+            self._chained_exceptions = []
+
         if Pdb._previous_sigint_handler:
             try:
                 signal.signal(signal.SIGINT, Pdb._previous_sigint_handler)
             except ValueError:  # ValueError: signal only works in main thread
                 pass
             else:
                 Pdb._previous_sigint_handler = None
-        if self.setup(frame, traceback):
+        if self.setup(frame, tb_or_exc):
             # no interaction desired at this time (happens if .pdbrc contains
             # a command like "continue")
             self.forget()
@@ -1073,6 +1086,24 @@ def _select_frame(self, number):
         self.print_stack_entry(self.stack[self.curindex])
         self.lineno = None
 
+    def do_exceptions(self, arg):
+        if not arg:
+            for ix, exc in enumerate(self._chained_exceptions):
+                prompt = ">" if ix == self._chained_exception_index else " "
+                self.message(f"{prompt} {ix} {exc!r}")
+        else:
+            try:
+                arg = int(arg)
+            except ValueError:
+                self.error("Argument must be an integer")
+                return
+            if 0 <= arg < len(self._chained_exceptions):
+                self._chained_exception_index = arg
+                self.setup(None, self._chained_exceptions[arg].__traceback__)
+                self.print_stack_entry(self.stack[self.curindex])
+            else:
+                self.error("No exception with that number")
+
     def do_up(self, arg):
         """u(p) [count]
 
@@ -1890,11 +1921,16 @@ def set_trace(*, header=None):
 # Post-Mortem interface
 
 def post_mortem(t=None):
-    """Enter post-mortem debugging of the given *traceback* object.
+    """Enter post-mortem debugging of the given *traceback*, or *exception*
+    object.
 
     If no traceback is given, it uses the one of the exception that is
     currently being handled (an exception must be being handled if the
     default is to be used).
+
+    If `t` is an Exception and is a chained exception (i.e it has a __context__),
+    pdb will be able to move to the sub-exception when reaching the bottom
+    frame.
     """
     # handling the default
     if t is None:
@@ -1912,11 +1948,7 @@ def post_mortem(t=None):
 
 def pm():
     """Enter post-mortem debugging of the traceback found in sys.last_traceback."""
-    if hasattr(sys, 'last_exc'):
-        tb = sys.last_exc.__traceback__
-    else:
-        tb = sys.last_traceback
-    post_mortem(tb)
+    post_mortem(sys.last_exc)
 
 
 # Main program for testing

Lib/test/test_pdb.py

@@ -826,6 +826,84 @@ def test_convenience_variables():
     (Pdb) continue
     """
 
+
+def test_post_mortem_chained():
+    """Test post mortem traceback debugging of chained exception
+
+    >>> def test_function_2():
+    ...     try:
+    ...         1/0
+    ...     finally:
+    ...         print('Exception!')
+
+    >>> def test_function_reraise():
+    ...     try:
+    ...         test_function_2()
+    ...     except ZeroDivisionError as e:
+    ...         raise ZeroDivisionError('reraised') from e
+
+    >>> def test_function():
+    ...     import pdb;
+    ...     instance = pdb.Pdb(nosigint=True, readrc=False)
+    ...     try:
+    ...         test_function_reraise()
+    ...     except Exception as e:
+    ...         # same as pdb.post_mortem(e), but with custom pdb instance.
+    ...         instance.reset()
+    ...         instance.interaction(None, e)
+
+    >>> with PdbTestInput([  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+    ...     'exceptions',
+    ...     'exceptions 0',
+    ...     'up',
+    ...     'down',
+    ...     'exceptions 1',
+    ...     'up',
+    ...     'down',
+    ...     'exceptions -1',
+    ...     'exceptions 3',
+    ...     'up',
+    ...     'exit',
+    ... ]):
+    ...    try:
+    ...        test_function()
+    ...    except ZeroDivisionError:
+    ...        print('Correctly reraised.')
+    Exception!
+    > <doctest test.test_pdb.test_post_mortem_chained[1]>(5)test_function_reraise()
+    -> raise ZeroDivisionError('reraised') from e
+    (Pdb) exceptions
+      0 ZeroDivisionError('division by zero')
+    > 1 ZeroDivisionError('reraised')
+    (Pdb) exceptions 0
+    > <doctest test.test_pdb.test_post_mortem_chained[0]>(3)test_function_2()
+    -> 1/0
+    (Pdb) up
+    > <doctest test.test_pdb.test_post_mortem_chained[1]>(3)test_function_reraise()
+    -> test_function_2()
+    (Pdb) down
+    > <doctest test.test_pdb.test_post_mortem_chained[0]>(3)test_function_2()
+    -> 1/0
+    (Pdb) exceptions 1
+    > <doctest test.test_pdb.test_post_mortem_chained[1]>(5)test_function_reraise()
+    -> raise ZeroDivisionError('reraised') from e
+    (Pdb) up
+    > <doctest test.test_pdb.test_post_mortem_chained[2]>(5)test_function()
+    -> test_function_reraise()
+    (Pdb) down
+    > <doctest test.test_pdb.test_post_mortem_chained[1]>(5)test_function_reraise()
+    -> raise ZeroDivisionError('reraised') from e
+    (Pdb) exceptions -1
+    *** No exception with that number
+    (Pdb) exceptions 3
+    *** No exception with that number
+    (Pdb) up
+    > <doctest test.test_pdb.test_post_mortem_chained[2]>(5)test_function()
+    -> test_function_reraise()
+    (Pdb) exit
+    """
+
+
 def test_post_mortem():
     """Test post mortem traceback debugging.
 

Misc/NEWS.d/next/Library/2023-07-12-10-59-08.gh-issue-106670.goQ2Sy.rst

@@ -0,0 +1,3 @@
+Add the new ``exceptions`` command the Pdb debugger to move between chained exceptions when using post mortem debugging.
+
+