Add postmortem debugging functionality and related tracing controls

Author: nshepperd

.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

src/debugpy/__init__.py

@@ -19,6 +19,7 @@
     "is_client_connected",
     "listen",
     "log_to",
+    "postmortem",
     "trace_this_thread",
     "wait_for_client",
 ]

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

@@ -1823,6 +1823,81 @@ 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() or set_current_thread_tracing_state() to restore.
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        thread_info = _get_thread_info(False, 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.
+
+    This unconditionally enables tracing. For conditional restoration,
+    use set_current_thread_tracing_state().
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        thread_info = _get_thread_info(False, 1)
+        if thread_info is None:
+            return
+    thread_info.trace = True
+
+
+# fmt: off
+# IFDEF CYTHON
+# cpdef set_current_thread_tracing_state(bint trace):
+#     cdef ThreadInfo thread_info
+# ELSE
+def set_current_thread_tracing_state(trace):
+# ENDIF
+# fmt: on
+    """
+    Sets the tracing state for the current thread.
+
+    :param trace: True to enable tracing, False to disable.
+
+    This is typically used to restore a previously saved state from
+    suspend_current_thread_tracing().
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        thread_info = _get_thread_info(False, 1)
+        if thread_info is None:
+            return
+    thread_info.trace = trace
+
+
 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

@@ -1829,6 +1829,81 @@ 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() or set_current_thread_tracing_state() to restore.
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        thread_info = _get_thread_info(False, 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.
+
+    This unconditionally enables tracing. For conditional restoration,
+    use set_current_thread_tracing_state().
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        thread_info = _get_thread_info(False, 1)
+        if thread_info is None:
+            return
+    thread_info.trace = True
+
+
+# fmt: off
+# IFDEF CYTHON -- DONT EDIT THIS FILE (it is automatically generated)
+cpdef set_current_thread_tracing_state(bint trace):
+    cdef ThreadInfo thread_info
+# ELSE
+# def set_current_thread_tracing_state(trace):
+# ENDIF
+# fmt: on
+    """
+    Sets the tracing state for the current thread.
+
+    :param trace: True to enable tracing, False to disable.
+
+    This is typically used to restore a previously saved state from
+    suspend_current_thread_tracing().
+    """
+    try:
+        thread_info = _thread_local_info.thread_info
+    except:
+        thread_info = _get_thread_info(False, 1)
+        if thread_info is None:
+            return
+    thread_info.trace = trace
+
+
 def update_monitor_events(suspend_requested: Optional[bool]=None) -> None:
     """
     This should be called when breakpoints change.

src/debugpy/public_api.py

@@ -212,6 +212,32 @@ def trace_this_thread(__should_trace: bool):
     """
 
 
+@_api()
+def postmortem(
+    __excinfo: typing.Tuple[type, BaseException, typing.Any] | None = None
+) -> 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.postmortem()  # 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,51 @@ def trace_this_thread(should_trace):
         pydb.enable_tracing()
     else:
         pydb.disable_tracing()
+
+
+def postmortem(excinfo=None):
+    ensure_logging()
+
+    if excinfo is None:
+        excinfo = sys.exc_info()
+
+    exctype, value, tb = excinfo
+    if exctype is None or value is None or tb is None:
+        log.debug("postmortem() ignored - no exception info")
+        return
+
+    if not is_client_connected():
+        log.info("postmortem() ignored - debugger not attached")
+        return
+
+    log.debug("postmortem({0!r})", excinfo)
+
+    pydb = get_global_debugger()
+    if pydb is None:
+        log.warning("postmortem() ignored - no global debugger")
+        return
+
+    thread = threading.current_thread()
+    additional_info = pydb.set_additional_thread_info(thread)
+
+    # Save states for restoration
+    saved_is_tracing = additional_info.is_tracing
+    saved_sys_monitoring_trace = None
+
+    try:
+        # Prevent recursive tracing (settrace protection)
+        additional_info.is_tracing += 1
+
+        # For Python 3.12+, suspend sys.monitoring tracing
+        if hasattr(sys, 'monitoring'):
+            from _pydevd_sys_monitoring import pydevd_sys_monitoring
+            saved_sys_monitoring_trace = pydevd_sys_monitoring.suspend_current_thread_tracing()
+
+        from _pydevd_bundle.pydevd_breakpoints import stop_on_unhandled_exception
+        stop_on_unhandled_exception(pydb, thread, additional_info, excinfo)
+
+    finally:
+        additional_info.is_tracing = saved_is_tracing
+        if saved_sys_monitoring_trace is not None:
+            from _pydevd_sys_monitoring import pydevd_sys_monitoring
+            pydevd_sys_monitoring.set_current_thread_tracing_state(saved_sys_monitoring_trace)