Add trigger_exception_handler() for post-mortem debugging of caught exceptions

.gitignore

@@ -30,6 +30,7 @@ wheelhouse/
 *.dist-info/
 .installed.cfg
 *.egg
+build/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

README.md

@@ -100,6 +100,22 @@ while True:
     ...
 ```
 
+### `trigger_exception_handler()` function
+Debugpy supports a `trigger_exception_handler()` function for post-mortem inspection of a caught exception, similar in spirit to `pdb.post_mortem()`. Call `debugpy.trigger_exception_handler(e)` with an exception or `(type(e),e,e.__traceback__)` tuple; or with no arguments in an except block. If the debugger is attached, it will pause execution and start post-mortem debugging of the exception stack as-if an uncaught exception. This respects breakpoint filters set by the debugger by default. When resuming afterward, the program will continue executing as normal (including unwinding the stack further if trigger_exception_handler() was invoked in a context manager's `__exit__` for example, or the exception is re-raised). If there's no client attached, this function does nothing, as breakpoint().
+
+```python
+import debugpy
+debugpy.listen(...)
+
+...
+def risky_function():
+    raise ValueError("threw an exception")
+try:
+    risky_function()
+except Exception as e:
+    debugpy.trigger_exception_handler(e)
+```
+
 ## Debugger logging
 
 To enable debugger internal logging via CLI, the `--log-to` switch can be used:

src/debugpy/__init__.py

@@ -20,6 +20,7 @@
     "listen",
     "log_to",
     "trace_this_thread",
+    "trigger_exception_handler",
     "wait_for_client",
 ]
 

src/debugpy/_vendored/pydevd/_pydevd_sys_monitoring/_pydevd_sys_monitoring.py

@@ -1866,6 +1866,56 @@ def stop_monitoring(all_threads=False):
         thread_info.trace = False
 
 
+# fmt: off
+# IFDEF CYTHON
+# cpdef bint suspend_current_thread_tracing():
+#     cdef ThreadInfo thread_info
+# ELSE
+def suspend_current_thread_tracing():
+# ENDIF
+# fmt: on
+    """
+    Suspends tracing for the current thread.
+
+    Returns the previous tracing state (True if tracing was enabled, False otherwise).
+    This is useful for temporarily disabling tracing to prevent recursive debugging.
+
+    Use resume_current_thread_tracing() to restore.
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        # Create the thread info if it doesn't exist yet: if tracing is not
+        # explicitly disabled here, the first monitoring event on this thread
+        # would create it with tracing enabled.
+        thread_info = _get_thread_info(True, 1)
+        if thread_info is None:
+            return False
+    previous_state = thread_info.trace
+    thread_info.trace = False
+    return previous_state
+
+
+# fmt: off
+# IFDEF CYTHON
+# cpdef resume_current_thread_tracing():
+#     cdef ThreadInfo thread_info
+# ELSE
+def resume_current_thread_tracing():
+# ENDIF
+# fmt: on
+    """
+    Resumes tracing for the current thread.
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        thread_info = _get_thread_info(True, 1)
+        if thread_info is None:
+            return
+    thread_info.trace = True
+
+
 def update_monitor_events(suspend_requested: Optional[bool]=None) -> None:
     """
     This should be called when breakpoints change.

src/debugpy/_vendored/pydevd/_pydevd_sys_monitoring/_pydevd_sys_monitoring_cython.pyx

@@ -1858,6 +1858,56 @@ cpdef stop_monitoring(all_threads=False):
         thread_info.trace = False
 
 
+# fmt: off
+# IFDEF CYTHON -- DONT EDIT THIS FILE (it is automatically generated)
+cpdef bint suspend_current_thread_tracing():
+    cdef ThreadInfo thread_info
+# ELSE
+# def suspend_current_thread_tracing():
+# ENDIF
+# fmt: on
+    """
+    Suspends tracing for the current thread.
+
+    Returns the previous tracing state (True if tracing was enabled, False otherwise).
+    This is useful for temporarily disabling tracing to prevent recursive debugging.
+
+    Use resume_current_thread_tracing() to restore.
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        # Create the thread info if it doesn't exist yet: if tracing is not
+        # explicitly disabled here, the first monitoring event on this thread
+        # would create it with tracing enabled.
+        thread_info = _get_thread_info(True, 1)
+        if thread_info is None:
+            return False
+    previous_state = thread_info.trace
+    thread_info.trace = False
+    return previous_state
+
+
+# fmt: off
+# IFDEF CYTHON -- DONT EDIT THIS FILE (it is automatically generated)
+cpdef resume_current_thread_tracing():
+    cdef ThreadInfo thread_info
+# ELSE
+# def resume_current_thread_tracing():
+# ENDIF
+# fmt: on
+    """
+    Resumes tracing for the current thread.
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        thread_info = _get_thread_info(True, 1)
+        if thread_info is None:
+            return
+    thread_info.trace = True
+
+
 def update_monitor_events(suspend_requested: Optional[bool]=None) -> None:
     """
     This should be called when breakpoints change.

src/debugpy/_vendored/pydevd/pydevd.py

@@ -2427,6 +2427,51 @@ def do_stop_on_unhandled_exception(self, thread, frame, frames_byid, arg):
             remove_exception_from_frame(frame)
             frame = None
 
+    def trigger_exception_handler(self, excinfo, as_uncaught=True):
+        """
+        Triggers post-mortem debugging as if handling an uncaught exception.
+
+        If as_uncaught is True (default), respects exception breakpoint configuration and applies breakpoint filters.
+
+        :param excinfo: A tuple of (exc_type, exc_value, exc_traceback).
+        """
+        if not as_uncaught:
+            exctype, value, tb = excinfo
+
+            # Walk traceback to build frames list and find user frame
+            frames = []
+            user_frame = None
+            while tb is not None:
+                frame = tb.tb_frame
+                # Skip debugger-internal frames, use last user frame
+                if self.get_file_type(frame) is None:
+                    user_frame = frame
+                frames.append(frame)
+                tb = tb.tb_next
+
+            if user_frame is None:
+                pydev_log.debug("trigger_exception_handler: no user frame found in traceback")
+                return
+
+            frames_byid = dict([(id(frame), frame) for frame in frames])
+
+        if PYDEVD_USE_SYS_MONITORING:
+            saved_sys_monitoring_trace = pydevd_sys_monitoring.suspend_current_thread_tracing()
+        thread = threading.current_thread()
+        additional_info = self.set_additional_thread_info(thread)
+        additional_info.is_tracing += 1
+
+        try:
+            if as_uncaught:
+                self.stop_on_unhandled_exception(self, thread, additional_info, excinfo)
+            else:
+                self.do_stop_on_unhandled_exception(thread, user_frame, frames_byid, excinfo)
+        finally:
+            if PYDEVD_USE_SYS_MONITORING:
+                if saved_sys_monitoring_trace:
+                    pydevd_sys_monitoring.resume_current_thread_tracing()
+            additional_info.is_tracing -= 1
+
     def set_trace_for_frame_and_parents(self, thread_ident: Optional[int], frame, **kwargs):
         disable = kwargs.pop("disable", False)
         assert not kwargs

src/debugpy/public_api.py

@@ -212,6 +212,33 @@ def trace_this_thread(__should_trace: bool):
     """
 
 
+@_api()
+def trigger_exception_handler(
+    __excinfo: typing.Tuple[type, BaseException, typing.Any] | BaseException | None = None,
+    as_uncaught: bool = True,
+) -> None:
+    """Stops the debugger on an unhandled exception.
+
+    If a debug client is connected, pauses execution as if an
+    unhandled exception was caught. This allows inspection of the
+    exception and call stack at the point of failure.
+
+    If no exception info is provided, uses sys.exc_info() to get
+    the current exception. If there is no current exception and no
+    argument is provided, does nothing.
+
+    Safe to call when no debugger is connected (returns immediately).
+
+    Example::
+
+        try:
+            risky_operation()
+        except Exception:
+            debugpy.trigger_exception_handler()  # Uses current exception
+            raise
+    """
+
+
 def get_cli_options() -> CliOptions | None:
     """Returns the CLI options that were processed by debugpy.
 

src/debugpy/server/api.py

@@ -364,3 +364,32 @@ def trace_this_thread(should_trace):
         pydb.enable_tracing()
     else:
         pydb.disable_tracing()
+
+
+def trigger_exception_handler(excinfo=None, as_uncaught=True):
+    ensure_logging()
+
+    if excinfo is None:
+        excinfo = sys.exc_info()
+
+    if isinstance(excinfo, BaseException):
+        excinfo = (type(excinfo), excinfo, excinfo.__traceback__)
+
+    exctype, value, tb = excinfo
+    if exctype is None or value is None or tb is None:
+        log.debug("trigger_exception_handler() ignored - no exception info")
+        return
+
+    if not is_client_connected():
+        log.info("trigger_exception_handler() ignored - debugger not attached")
+        return
+
+    log.debug("trigger_exception_handler({0!r})", excinfo)
+
+    pydb = get_global_debugger()
+    if pydb is None:
+        log.warning("trigger_exception_handler() ignored - no global debugger")
+        return
+
+    pydb.trigger_exception_handler(excinfo, as_uncaught=as_uncaught)
+