Allow Pdb to move between chained exception.

This lets Pdb receive and 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 when reaching the
tot/bottom.

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")         # 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>``.

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

Closes gh-106670

Author: Carreau

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_index = 0
 
     _previous_sigint_handler = None
 
@@ -416,6 +418,17 @@ def preloop(self):
 
     def interaction(self, frame, traceback):
         # Restore the previous signal handler at the Pdb prompt.
+
+        if isinstance(traceback, BaseException):
+            traceback, exception = traceback.__traceback__, traceback
+            self._chained_exceptions = [exception]
+            current = exception
+            while current := current.__context__:
+                self._chained_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)
@@ -1073,6 +1086,26 @@ def _select_frame(self, number):
         self.print_stack_entry(self.stack[self.curindex])
         self.lineno = None
 
+    def do_exceptions(self, arg):
+        if not arg or arg == "list":
+            for ix, exc in enumerate(self._chained_exceptions):
+                print(">" if ix == self._chained_index else " ", ix, repr(exc))
+        else:
+            try:
+                arg = int(arg)
+            except ValueError:
+                self.error("Argument must be an integer")
+                return
+                pass
+            else:
+                if 0 <= arg < len(self._chained_exceptions):
+                    self._chained_index = arg
+                    self.setup(None, self._chained_exceptions[arg].__traceback__)
+                    self.curindex = 0
+                    self._select_frame(0)
+                    return
+            self.error("No exception with that number")
+
     def do_up(self, arg):
         """u(p) [count]
 
@@ -1895,6 +1928,10 @@ def post_mortem(t=None):
     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,7 +1949,9 @@ def post_mortem(t=None):
 
 def pm():
     """Enter post-mortem debugging of the traceback found in sys.last_traceback."""
-    if hasattr(sys, 'last_exc'):
+    if hasattr(sys, "last_value"):
+        tb = sys.last_value
+    elif hasattr(sys, "last_exc"):
         tb = sys.last_exc.__traceback__
     else:
         tb = sys.last_traceback

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',
+    ...     'down',
+    ...     'up',
+    ...     'exceptions 1',
+    ...     'down',
+    ...     'up',
+    ...     'exceptions -1',
+    ...     'exceptions 3',
+    ...     'down',
+    ...     '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[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) up
+    > <doctest test.test_pdb.test_post_mortem_chained[1]>(3)test_function_reraise()
+    -> test_function_2()
+    (Pdb) exceptions 1
+    > <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) up
+    > <doctest test.test_pdb.test_post_mortem_chained[2]>(5)test_function()
+    -> test_function_reraise()
+    (Pdb) exceptions -1
+    *** No exception with that number
+    (Pdb) exceptions 3
+    *** No exception with that number
+    (Pdb) down
+    > <doctest test.test_pdb.test_post_mortem_chained[1]>(5)test_function_reraise()
+    -> raise ZeroDivisionError('reraised') from e
+    (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,47 @@
+Allow Pdb to move between chained exceptions on post_mortem debugging.
+
+If ``Pdb.post_mortem()`` is called with a chained exception, 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.
+
+We do not differentiate ``__cause__`` and ``__context__``.
+
+That is to say if you have the following code
+
+    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
+
+Post mortem debugging allows us to move between the different exception:
+
+    >>> import pdb; pdb.pm()
+
+    > code.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
+    > code.py(10)middle()
+    -> return inner(0)
+
+    (Pdb) down
+    > code.py(16)inner()
+    -> 1 / x
+
+By default, ``pdb.pm()`` will now try to show the exception based on ``sys.last_value`` to allow moving between
+exceptions, instead of ``sys.last_traceback``.