From c34616c8e77a7228086e33ba25e00b55dbda1eef Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 18 Feb 2026 22:33:24 -0500 Subject: [PATCH 1/5] 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/5] 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() From 80a26efbc0db3ba7ac03dc713a3025964d80dc96 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 20 Feb 2026 16:20:19 +0100 Subject: [PATCH 3/5] Remove old content from bad suggestion --- Doc/c-api/exceptions.rst | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 6750f915b7fdab..484082060503c2 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -673,36 +673,8 @@ Signal Handling single: SIGINT (C macro) single: KeyboardInterrupt (built-in exception) - This function interacts with Python's signal handling. - If the function is called from the main thread and under the main Python - interpreter, it checks whether a signal has been sent to the processes - and if so, invokes the corresponding signal handler. If the :mod:`signal` - module is supported, this can invoke a signal handler written in Python. - The function attempts to handle all pending signals, and then returns ``0``. - However, if a Python signal handler raises an exception, the error - indicator is set and the function returns ``-1`` immediately (such that - other pending signals may not have been handled yet: they will be on the - next :c:func:`PyErr_CheckSignals()` invocation). - - 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). - - .. note:: - 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. 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. From 3f295d730d175dcb00c37308f19650f13f86d54a Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 20 Feb 2026 16:20:37 +0100 Subject: [PATCH 4/5] Convert note to a more friendly example --- Doc/c-api/exceptions.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 484082060503c2..3331a2d321ec76 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -673,13 +673,17 @@ Signal Handling single: SIGINT (C macro) single: KeyboardInterrupt (built-in exception) + Handle external interruptions, such as signals or activating a debugger, + whose processing has been delayed until it is safe + to run Python code and/or raise exceptions. + For example, pressing :kbd:`Ctrl-C` causes a terminal to send the + :py:data:`signal.SIGINT` signal. + This function executes the corresponding Python signal handler, which, + by default, raises the :exc:`KeyboardInterrupt` exception. - 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. + :c:func:`!PyErr_CheckSignals` 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: @@ -703,10 +707,6 @@ Signal Handling 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. From f1c162e6c847b53ff2c2f4e6340354f8dedbd09a Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 20 Feb 2026 11:12:34 -0500 Subject: [PATCH 5/5] Update Doc/c-api/exceptions.rst --- Doc/c-api/exceptions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 3331a2d321ec76..72b013612d77f5 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -697,7 +697,7 @@ Signal Handling - Running the garbage collector, if necessary. - - Execuing a pending :ref:`remote debugger ` script. + - Executing a pending :ref:`remote debugger ` script. If any handler raises an exception, immediately return ``-1`` with that exception set.