bpo-35537: Document posix_spawn() change in subprocess (GH-11668)

Document that subprocess.Popen no longer raise an exception on error
like missing program on very specific platforms when using
os.posix_spawn() is used.

2 files changed, 13 insertions, 0 deletions

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index ca0813c..3280c95 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -567,6 +567,13 @@ functions.
       Popen destructor now emits a :exc:`ResourceWarning` warning if the child
       process is still running.
 
+   .. versionchanged:: 3.8
+      Popen can use :func:`os.posix_spawn` in some cases for better
+      performance. On Windows Subsystem for Linux and QEMU User Emulation,
+      Popen constructor using :func:`os.posix_spawn` no longer raise an
+      exception on errors like missing program, but the child process fails
+      with a non-zero :attr:`~Popen.returncode`.
+
 
 Exceptions
 ^^^^^^^^^^
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index ae8163a..344656b 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -729,6 +729,12 @@ Changes in Python behavior
 Changes in the Python API
 -------------------------
 
+* :class:`subprocess.Popen` can now use :func:`os.posix_spawn` in some cases
+  for better performance. On Windows Subsystem for Linux and QEMU User
+  Emulation, Popen constructor using :func:`os.posix_spawn` no longer raise an
+  exception on errors like missing program, but the child process fails with a
+  non-zero :attr:`~Popen.returncode`.
+
 * The :meth:`imap.IMAP4.logout` method no longer ignores silently arbitrary
   exceptions.