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,24 @@ while True:
     ...
 ```
 
+### `trigger_exception_handler()` function
+`debugpy.trigger_exception_handler(e)` starts post-mortem debugging of a caught exception, similar in spirit to `pdb.post_mortem()`: if a client is attached, it pauses execution as if the exception were uncaught. Pass an exception, a `(type, value, traceback)` tuple, or nothing inside an except block to use the current exception. On resume the program continues as normal; if no client is attached the call does nothing, like `breakpoint()`.
+
+By default (`as_uncaught=True`) the stop respects the exception breakpoint configuration in the debugger UI: if breaking on uncaught exceptions isn't enabled, or its filters exclude the exception, nothing happens. Pass `as_uncaught=False` to stop unconditionally. Since the traceback has already been unwound, you can inspect frames and evaluate expressions at the stop, but not step through the code that raised.
+
+```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_bundle/pydevd_breakpoints.py

@@ -1,6 +1,6 @@
 from _pydev_bundle import pydev_log
 from _pydevd_bundle import pydevd_import_class
-from _pydevd_bundle.pydevd_frame_utils import add_exception_to_frame
+from _pydevd_bundle.pydevd_frame_utils import exception_on_frame
 from _pydev_bundle._pydev_saved_modules import threading
 
 
@@ -155,14 +155,16 @@ def stop_on_unhandled_exception(py_db, thread, additional_info, arg):
         return
 
     frames_byid = dict([(id(frame), frame) for frame in frames])
-    add_exception_to_frame(user_frame, arg)
-    if exception_breakpoint.condition is not None:
-        eval_result = py_db.handle_breakpoint_condition(additional_info, exception_breakpoint, user_frame)
-        if not eval_result:
-            return
-
-    if exception_breakpoint.expression is not None:
-        py_db.handle_breakpoint_expression(exception_breakpoint, additional_info, user_frame)
+    # Attach __exception__ so conditions/expressions can reference it; always
+    # detach as the thread may keep running (do_stop re-adds it while suspended).
+    with exception_on_frame(user_frame, arg):
+        if exception_breakpoint.condition is not None:
+            eval_result = py_db.handle_breakpoint_condition(additional_info, exception_breakpoint, user_frame)
+            if not eval_result:
+                return
+
+        if exception_breakpoint.expression is not None:
+            py_db.handle_breakpoint_expression(exception_breakpoint, additional_info, user_frame)
 
     try:
         additional_info.pydev_message = exception_breakpoint.qname

src/debugpy/_vendored/pydevd/_pydevd_bundle/pydevd_frame_utils.py

@@ -43,6 +43,32 @@ def remove_exception_from_frame(frame):
         frame.f_locals.pop("__exception__", None)
 
 
+_NO_EXCEPTION = object()
+
+
+class exception_on_frame(object):
+    """Exposes '__exception__' in the frame's locals during a stop, then restores
+    whatever was there before. Restoring by assignment (rather than deleting) avoids
+    a ValueError on 3.14+, where FrameLocalsProxy forbids deleting a real local -- as
+    happens when the user's own code has a variable named '__exception__'."""
+
+    def __init__(self, frame, exception_info):
+        self.frame = frame
+        self.exception_info = exception_info
+
+    def __enter__(self):
+        self._previous = self.frame.f_locals.get("__exception__", _NO_EXCEPTION)
+        add_exception_to_frame(self.frame, self.exception_info)
+        return self
+
+    def __exit__(self, *args):
+        if self._previous is _NO_EXCEPTION:
+            remove_exception_from_frame(self.frame)
+        else:
+            self.frame.f_locals["__exception__"] = self._previous
+        self.frame = None
+
+
 FILES_WITH_IMPORT_HOOKS = ["pydev_monkey_qt.py", "pydev_import_hook.py"]
 
 

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

@@ -1866,6 +1866,51 @@ 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 and returns the previous state,
+    to be restored with resume_current_thread_tracing().
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        # Create the ThreadInfo if missing; monitoring events create it with
+        # tracing enabled by default, which would defeat the suspension.
+        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.