gh-114570: Add PythonFinalizationError exception (#115352)

Add PythonFinalizationError exception. This exception derived from RuntimeError is raised when an operation is blocked during the Python finalization. The following functions now raise PythonFinalizationError, instead of RuntimeError: * _thread.start_new_thread() * subprocess.Popen * os.fork() * os.fork1() * os.forkpty() Morever, _winapi.Overlapped finalizer now logs an unraisable PythonFinalizationError, instead of an unraisable RuntimeError.

Author: vstinner

Doc/library/exceptions.rst

@@ -416,6 +416,24 @@ The following exceptions are the exceptions that are usually raised.
  handling in C, most floating point operations are not checked.
 
 
+.. exception:: PythonFinalizationError
+
+ This exception is derived from :exc:`RuntimeError`. It is raised when
+ an operation is blocked during interpreter shutdown also known as
+ :term:`Python finalization <interpreter shutdown>`.
+
+ Examples of operations which can be blocked with a
+ :exc:`PythonFinalizationError` during the Python finalization:
+
+ * Creating a new Python thread.
+ * :func:`os.fork`.
+
+ See also the :func:`sys.is_finalizing` function.
+
+ .. versionadded:: 3.13
+ Previously, a plain :exc:`RuntimeError` was raised.
+
+
 .. exception:: RecursionError
 
  This exception is derived from :exc:`RuntimeError`. It is raised when the

Doc/library/sys.rst

@@ -1202,6 +1202,8 @@ always available.
  Return :const:`True` if the main Python interpreter is
  :term:`shutting down <interpreter shutdown>`. Return :const:`False` otherwise.
 
+ See also the :exc:`PythonFinalizationError` exception.
+
  .. versionadded:: 3.5
 
 .. data:: last_exc

Doc/whatsnew/3.13.rst

@@ -160,6 +160,21 @@ Other Language Changes
  (Contributed by Levi Sabah, Zackery Spytz and Hugo van Kemenade in
  :gh:`73965`.)
 
+* Add :exc:`PythonFinalizationError` exception. This exception derived from
+ :exc:`RuntimeError` is raised when an operation is blocked during
+ the :term:`Python finalization <interpreter shutdown>`.
+
+ The following functions now raise PythonFinalizationError, instead of
+ :exc:`RuntimeError`:
+
+ * :func:`_thread.start_new_thread`.
+ * :class:`subprocess.Popen`.
+ * :func:`os.fork`.
+ * :func:`os.forkpty`.
+
+ (Contributed by Victor Stinner in :gh:`114570`.)
+
+
 New Modules
 ===========
 

Include/cpython/pyerrors.h

@@ -122,4 +122,6 @@ PyAPI_FUNC(void) _Py_NO_RETURN _Py_FatalErrorFunc(
 
 PyAPI_FUNC(void) PyErr_FormatUnraisable(const char *, ...);
 
+PyAPI_DATA(PyObject *) PyExc_PythonFinalizationError;
+
 #define Py_FatalError(message) _Py_FatalErrorFunc(__func__, (message))

Lib/test/exception_hierarchy.txt

@@ -40,6 +40,7 @@ BaseException
  ├── ReferenceError
  ├── RuntimeError
  │ ├── NotImplementedError
+ │ ├── PythonFinalizationError
  │ └── RecursionError
  ├── StopAsyncIteration
  ├── StopIteration

Lib/test/test_pickle.py

@@ -564,6 +564,7 @@ def test_exceptions(self):
  if exc in (BlockingIOError,
  ResourceWarning,
  StopAsyncIteration,
+ PythonFinalizationError,
  RecursionError,
  EncodingWarning,
  BaseExceptionGroup,

Misc/NEWS.d/next/Core and Builtins/2024-02-12-17-18-26.gh-issue-114570.BzwMlJ.rst

@@ -0,0 +1,3 @@
+Add :exc:`PythonFinalizationError` exception. This exception derived from
+:exc:`RuntimeError` is raised when an operation is blocked during the
+:term:`Python finalization <interpreter shutdown>`. Patch by Victor Stinner.

Modules/_posixsubprocess.c

@@ -1032,7 +1032,7 @@ subprocess_fork_exec_impl(PyObject *module, PyObject *process_args,
 
  PyInterpreterState *interp = _PyInterpreterState_GET();
  if ((preexec_fn != Py_None) && interp->finalizing) {
- PyErr_SetString(PyExc_RuntimeError,
+ PyErr_SetString(PyExc_PythonFinalizationError,
  "preexec_fn not supported at interpreter shutdown");
  return NULL;
  }

Modules/_threadmodule.c

@@ -1304,7 +1304,7 @@ do_start_new_thread(thread_module_state* state,
  return -1;
  }
  if (interp->finalizing) {
- PyErr_SetString(PyExc_RuntimeError,
+ PyErr_SetString(PyExc_PythonFinalizationError,
  "can't create new thread at interpreter shutdown");
  return -1;
  }

Modules/_winapi.c

@@ -139,7 +139,7 @@ overlapped_dealloc(OverlappedObject *self)
  {
  /* The operation is still pending -- give a warning. This
  will probably only happen on Windows XP. */
- PyErr_SetString(PyExc_RuntimeError,
+ PyErr_SetString(PyExc_PythonFinalizationError,
  "I/O operations still in flight while destroying "
  "Overlapped object, the process may crash");
  PyErr_WriteUnraisable(NULL);