From c34616c8e77a7228086e33ba25e00b55dbda1eef Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 18 Feb 2026 22:33:24 -0500 Subject: [PATCH 1/2] Add note about the GC and remote debugging to PyErr_CheckSignals(). --- Doc/c-api/exceptions.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index a1cfb8872345cf..c2d80d1cf73cae 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -686,8 +686,9 @@ Signal Handling other pending signals may not have been handled yet: they will be on the next :c:func:`PyErr_CheckSignals()` invocation). - If the function is called from a non-main thread, or under a non-main - Python interpreter, it does nothing and returns ``0``. + This function may invoke the garbage collector or execute a :ref:`remote + debugger ` script, regardless of the calling thread + or Python interpreter. This function can be called by long-running C code that wants to be interruptible by user requests (such as by pressing Ctrl-C). @@ -696,6 +697,13 @@ Signal Handling The default Python signal handler for :c:macro:`!SIGINT` raises the :exc:`KeyboardInterrupt` exception. + .. versionchanged:: 3.12 + This function may now invoke the garbage collector. + + .. versionchanged:: 3.14 + This function may now execute a remote debugger script, if remote + debugging is enabled. + .. c:function:: void PyErr_SetInterrupt() From b63b5d71e6df6d458b1e0cda55f491944fcb8fc1 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 19 Feb 2026 06:52:54 -0500 Subject: [PATCH 2/2] Update Doc/c-api/exceptions.rst Co-authored-by: Petr Viktorin --- Doc/c-api/exceptions.rst | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index c2d80d1cf73cae..6750f915b7fdab 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -703,6 +703,44 @@ Signal Handling .. versionchanged:: 3.14 This function may now execute a remote debugger script, if remote debugging is enabled. + Handle external interruptions, such as signals (including :kbd:`Ctrl-C`), + or activating a debugger, whose processing has been delayed until it is safe + to run Python code and/or raise exceptions. + The function should be called by long-running C code frequently + enough so that the response appears immediate to humans. + + Handlers invoked by this function currently include: + + - Signal handlers, including Python functions registered using + the :mod:`signal` module. + + Signal handlers are only run in the main thread of the main interpreter. + + (This is where the function got the name: originally, signals + were the only way to interrupt the interpreter.) + + - Running the garbage collector, if necessary. + + - Execuing a pending :ref:`remote debugger ` script. + + If any handler raises an exception, immediately return ``-1`` with that + exception set. + Any remaining interruptions are left to be processed on the next + :c:func:`PyErr_CheckSignals()` invocation, if appropriate. + + If all handlers finish successfully, or there are no handlers to run, + return ``0``. + + .. note:: + The default Python signal handler for :py:data:`signal.SIGINT` raises the + :exc:`KeyboardInterrupt` exception. + + .. versionchanged:: 3.12 + This function may now invoke the garbage collector. + + .. versionchanged:: 3.14 + This function may now execute a remote debugger script, if remote + debugging is enabled. .. c:function:: void PyErr_SetInterrupt()