gh-66333: Handle Ctrl-C during pdb step, next, and until

Author: devjoe

Doc/library/pdb.rst

@@ -278,7 +278,8 @@ access further features, you have to do this yourself:
    that matches one of these patterns. [1]_
 
    By default, Pdb sets a handler for the SIGINT signal (which is sent when the
-   user presses :kbd:`Ctrl-C` on the console) when you give a :pdbcmd:`continue` command.
+   user presses :kbd:`Ctrl-C` on the console) when you resume execution with
+   :pdbcmd:`continue`, :pdbcmd:`step`, :pdbcmd:`next`, or :pdbcmd:`until`.
    This allows you to break into the debugger again by pressing :kbd:`Ctrl-C`.  If you
    want Pdb not to touch the SIGINT handler, set *nosigint* to true.
 
@@ -328,6 +329,10 @@ access further features, you have to do this yourself:
       Inline breakpoints like :func:`breakpoint` or :func:`pdb.set_trace` will
       always stop the program at calling frame, ignoring the *skip* pattern (if any).
 
+   .. versionchanged:: 3.16
+      SIGINT handling also applies to :pdbcmd:`step`, :pdbcmd:`next`, and
+      :pdbcmd:`until`.
+
    .. method:: run(statement, globals=None, locals=None)
                runeval(expression, globals=None, locals=None)
                runcall(function, *args, **kwds)

Lib/pdb.py

@@ -628,11 +628,20 @@ async def set_trace_async(self, frame=None, *, commands=None):
 
         self.start_trace()
 
+    def _install_sigint_handler(self):
+        if self.nosigint:
+            return
+        try:
+            Pdb._previous_sigint_handler = \
+                signal.signal(signal.SIGINT, self.sigint_handler)
+        except ValueError:
+            # signal only works in the main thread.
+            pass
+
     def sigint_handler(self, signum, frame):
         if self.allow_kbdint:
             raise KeyboardInterrupt
         self.message("\nProgram interrupted. (Use 'cont' to resume).")
-        self.set_step()
         self.set_trace(frame)
 
     def reset(self):
@@ -690,6 +699,13 @@ def curframe_locals(self, value):
 
     # Override Bdb methods
 
+    def dispatch_call(self, frame, arg):
+        # Do not step into the debugger's own signal handler.
+        if frame.f_code is Pdb.sigint_handler.__code__:
+            self.stop_trace()
+            return
+        return super().dispatch_call(frame, arg)
+
     def user_call(self, frame, argument_list):
         """This method is called when there is the remote possibility
         that we ever need to stop in this function."""
@@ -2045,6 +2061,7 @@ def do_until(self, arg):
         else:
             lineno = None
         self.set_until(self.curframe, lineno)
+        self._install_sigint_handler()
         return 1
     do_unt = do_until
 
@@ -2059,6 +2076,7 @@ def do_step(self, arg):
             self._print_invalid_arg(arg)
             return
         self.set_step()
+        self._install_sigint_handler()
         return 1
     do_s = do_step
 
@@ -2072,6 +2090,7 @@ def do_next(self, arg):
             self._print_invalid_arg(arg)
             return
         self.set_next(self.curframe)
+        self._install_sigint_handler()
         return 1
     do_n = do_next
 
@@ -2121,16 +2140,7 @@ def do_continue(self, arg):
         if arg:
             self._print_invalid_arg(arg)
             return
-        if not self.nosigint:
-            try:
-                Pdb._previous_sigint_handler = \
-                    signal.signal(signal.SIGINT, self.sigint_handler)
-            except ValueError:
-                # ValueError happens when do_continue() is invoked from
-                # a non-main thread in which case we just continue without
-                # SIGINT set. Would printing a message here (once) make
-                # sense?
-                pass
+        self._install_sigint_handler()
         self.set_continue()
         return 1
     do_c = do_cont = do_continue

Lib/test/test_pdb.py

@@ -7,6 +7,7 @@
 import os
 import pdb
 import re
+import signal
 import sys
 import types
 import codecs
@@ -2973,6 +2974,118 @@ def test_pdb_with_inline_breakpoint():
     (Pdb) c
     """
 
+def test_pdb_sigint_continue():
+    """SIGINT interrupts continue with a breakpoint set.
+
+    >>> def callee():
+    ...     signal.raise_signal(signal.SIGINT)
+    ...     return 42
+    >>> def caller():
+    ...     result = callee()
+    ...     return result
+
+    With a breakpoint after the call, tracing remains active. The signal
+    stops in the callee, and continuing then reaches the breakpoint.
+
+    >>> with PdbTestInput(['break 3', 'continue', 'continue', 'continue']):
+    ...     try:
+    ...         pdb.Pdb(readrc=False).runcall(caller)
+    ...     except KeyboardInterrupt:
+    ...         raise AssertionError('SIGINT unwound the debuggee')
+    > <doctest test.test_pdb.test_pdb_sigint_continue[1]>(2)caller()
+    -> result = callee()
+    (Pdb) break 3
+    Breakpoint 1 at <doctest test.test_pdb.test_pdb_sigint_continue[1]>:3
+    (Pdb) continue
+    <BLANKLINE>
+    Program interrupted. (Use 'cont' to resume).
+    > <doctest test.test_pdb.test_pdb_sigint_continue[0]>(2)callee()
+    -> signal.raise_signal(signal.SIGINT)
+    (Pdb) continue
+    > <doctest test.test_pdb.test_pdb_sigint_continue[1]>(3)caller()
+    -> return result
+    (Pdb) continue
+    42
+    """
+
+
+def test_pdb_sigint_step():
+    """SIGINT during step stops in the debuggee, not in Pdb's handler.
+
+    >>> def test_function():
+    ...     signal.raise_signal(signal.SIGINT)
+    ...     return 42
+
+    >>> with PdbTestInput(['step', 'continue']):
+    ...     try:
+    ...         pdb.Pdb(readrc=False).runcall(test_function)
+    ...     except KeyboardInterrupt:
+    ...         raise AssertionError('SIGINT unwound the debuggee')
+    > <doctest test.test_pdb.test_pdb_sigint_step[0]>(2)test_function()
+    -> signal.raise_signal(signal.SIGINT)
+    (Pdb) step
+    <BLANKLINE>
+    Program interrupted. (Use 'cont' to resume).
+    > <doctest test.test_pdb.test_pdb_sigint_step[0]>(2)test_function()
+    -> signal.raise_signal(signal.SIGINT)
+    (Pdb) continue
+    42
+    """
+
+
+def test_pdb_sigint_next():
+    """SIGINT during next stops inside a previously untraced callee.
+
+    >>> def callee():
+    ...     signal.raise_signal(signal.SIGINT)
+    ...     return 42
+    >>> def caller():
+    ...     result = callee()
+    ...     return result
+
+    >>> with PdbTestInput(['next', 'continue']):
+    ...     try:
+    ...         pdb.Pdb(readrc=False).runcall(caller)
+    ...     except KeyboardInterrupt:
+    ...         raise AssertionError('SIGINT unwound the debuggee')
+    > <doctest test.test_pdb.test_pdb_sigint_next[1]>(2)caller()
+    -> result = callee()
+    (Pdb) next
+    <BLANKLINE>
+    Program interrupted. (Use 'cont' to resume).
+    > <doctest test.test_pdb.test_pdb_sigint_next[0]>(2)callee()
+    -> signal.raise_signal(signal.SIGINT)
+    (Pdb) continue
+    42
+    """
+
+
+def test_pdb_sigint_until():
+    """SIGINT during until stops inside a previously untraced callee.
+
+    >>> def callee():
+    ...     signal.raise_signal(signal.SIGINT)
+    ...     return 42
+    >>> def caller():
+    ...     result = callee()
+    ...     return result
+
+    >>> with PdbTestInput(['until 3', 'continue']):
+    ...     try:
+    ...         pdb.Pdb(readrc=False).runcall(caller)
+    ...     except KeyboardInterrupt:
+    ...         raise AssertionError('SIGINT unwound the debuggee')
+    > <doctest test.test_pdb.test_pdb_sigint_until[1]>(2)caller()
+    -> result = callee()
+    (Pdb) until 3
+    <BLANKLINE>
+    Program interrupted. (Use 'cont' to resume).
+    > <doctest test.test_pdb.test_pdb_sigint_until[0]>(2)callee()
+    -> signal.raise_signal(signal.SIGINT)
+    (Pdb) continue
+    42
+    """
+
 def test_pdb_issue_20766():
     """Test for reference leaks when the SIGINT handler is set.
 
@@ -5432,9 +5545,15 @@ def setUpPdbBackend(backend):
         def setUp(test):
             import pdb
             pdb.set_default_backend(backend)
+            test.original_sigint_handler = signal.getsignal(signal.SIGINT)
+            test.previous_sigint_handler = pdb.Pdb._previous_sigint_handler
         return setUp
 
     def tearDown(test):
+        # Restore signal state even if a SIGINT doctest fails.
+        signal.signal(signal.SIGINT, test.original_sigint_handler)
+        pdb.Pdb._previous_sigint_handler = test.previous_sigint_handler
+
         # Ensure that asyncio state has been cleared at the end of the test.
         # This prevents a "test altered the execution environment" warning if
         # asyncio features are used.

Misc/NEWS.d/next/Library/2026-10-28-16-40-00.gh-issue-66333.pdb-sigint.rst

@@ -0,0 +1,3 @@
+Allow Ctrl-C to interrupt execution resumed with the :mod:`pdb`
+``step``, ``next``, and ``until`` commands without unwinding the debugged
+program, as with ``continue``.