gh-106670: Allow Pdb to move between chained exceptions (#106676)

2 files changed, 58 insertions, 2 deletions

diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index ef52370..3aaac15 100644
--- a/Doc/library/pdb.rst
+++ b/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,55 @@ 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 allows 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)
+
+   .. versionadded:: 3.13
+
 .. rubric:: Footnotes
 
 .. [1] Whether a frame is considered to originate in a certain module
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index a17b549..1c94da2 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -158,6 +158,13 @@ pathlib
   :meth:`~pathlib.Path.is_dir`.
   (Contributed by Barney Gale in :gh:`77609` and :gh:`105793`.)
 
+pdb
+---
+
+* Add ability to move between chained exceptions during post mortem debugging in :func:`~pdb.pm` using
+  the new ``exceptions [exc_number]`` command for Pdb. (Contributed by Matthias
+  Bussonnier in :gh:`106676`.)
+
 sqlite3
 -------