gh-114570: Add PythonFinalizationError exception

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 operations is blocked during the :term:`Python finalization <interpreter
+ shutdown>`.
+
+ Examples of operations which can be blocked with a
+ :exc:`PythonFinalizationError` during the Python finalization:
+
+ * create 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);