PyErr_SetInterrupt and Its Related Functions

Using PyErr_SetInterrupt is similar to calling Py_SetInterruptEx(SIGINT). It is async-signal safe, and simulates the effect of SIGINT arriving. If a Python function or library function fails, Python should raise an exception that can be handled by the function that called it. The function must then clean up the resources used in its invocation, and indicate to the caller that an error has been set. The Python/C API may fail in mysterious ways if an error is not handled.

PyErr_CheckSignals is a function that can be called by a Python function or library function to check a pending signal and call Python’s signal handler for the signal. It can be called by long-running C code. It returns a -1 if it does not do so.

PyErr_CheckSignals() checks whether the errno value is a pending signal, and if it is, calls Python’s signal handler for that signal. It is possible for long-running C code to call PyErr_CheckSignals(), but it does not affect the current thread. For that reason, a non-main Python thread should not use the function.

If the function is called from C code, the return value is either NULL or the error indicator tuple. The tuple is composed of three object pointers: one that is an ASCII-encoded string, one that is a UTF-8 encoded string, and one that is an error indicator. The errno value is always null if the function fails, and is set to the error indicator value on success.

The PyErr_SetFromErrnoWithFilenameObject function takes a filename object and returns a C string that is decoded from the filesystem encoding. It is similar to PyErr_SetFromErrno, but the filename object must be passed to the constructor. It raises an exception if the function has more than two filename objects.

PyErr_CheckSignals calls Python’s signal handler for a pending signal, and if the signal is sent to a process, it returns a message. If it is not sent to a process, it does nothing. If it is sent to a process, the function raises a KeyboardInterrupt exception. It is used by the PyInterpreter module to ensure that an interactive input evaluates to true before a KeyboardInterrupt is taken. It also prevents KeyboardInterrupt from terminating the application.

The PyErr_SetImportError function is similar to PyErr_SetInterruptEx, but the filename, line, and offset information is added to the ImportError. The ImportError subclass is a useful way of specifying a subclass of ImportError.

PyErr_Fetch() saves the current error indicator, but does not affect the normalized values. It is part of the Stable ABI. The PyErr_Fetch() function is also part of the Stable ABI, and is available on Windows. Since version 3.6, the PyErr_WarnFormat function is available in Stable ABI. It is part of the Stable ABI, and uses PyUnicode_from_format to decode an error indicator.

If a Python function or library function fails, it must clear the error indicator, and indicate to the caller that an exception has been set. The error indicator may be set to NULL, and may also be a non-zero value. In most functions, the errno value is not cleared on success. It is therefore necessary to call Py_ReprEnter() after each failure.