[Python-checkins] bpo-42041: Clarify how subprocess searches for the executable (GH-22715)

Tue Oct 20 16:02:28 EDT 2020

https://github.com/python/cpython/commit/5ab27cc518f614a0b954ff3eb125290f264242d5
commit: 5ab27cc518f614a0b954ff3eb125290f264242d5
branch: master
author: Paul Moore <p.f.moore at gmail.com>
committer: pfmoore <p.f.moore at gmail.com>
date: 2020年10月20日T21:02:24+01:00
summary:
bpo-42041: Clarify how subprocess searches for the executable (GH-22715)
Clarify in the subprocess documentation how searching for the executable to run works, noting that ``sys.executable`` is the recommended way to find the current interpreter.
files:
M Doc/library/subprocess.rst

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 7993b103f473e..85d0f46624cea 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -344,7 +344,7 @@ functions.
 encoding=None, errors=None, text=None, pipesize=-1)
 
 Execute a child program in a new process. On POSIX, the class uses
- :meth:`os.execvp`-like behavior to execute the child program. On Windows,
+ :meth:`os.execvpe`-like behavior to execute the child program. On Windows,
 the class uses the Windows ``CreateProcess()`` function. The arguments to
 :class:`Popen` are as follows.
 
@@ -356,6 +356,25 @@ functions.
 arguments for additional differences from the default behavior. Unless
 otherwise stated, it is recommended to pass *args* as a sequence.
 
+ .. warning::
+
+ For maximum reliability, use a fully-qualified path for the executable.
+ To search for an unqualified name on :envvar:`PATH`, use
+ :meth:`shutil.which`. On all platforms, passing :data:`sys.executable`
+ is the recommended way to launch the current Python interpreter again,
+ and use the ``-m`` command-line format to launch an installed module.
+
+ Resolving the path of *executable* (or the first item of *args*) is
+ platform dependent. For POSIX, see :meth:`os.execvpe`, and note that
+ when resolving or searching for the executable path, *cwd* overrides the
+ current working directory and *env* can override the ``PATH``
+ environment variable. For Windows, see the documentation of the
+ ``lpApplicationName`` and ``lpCommandLine`` parameters of WinAPI
+ ``CreateProcess``, and note that when resolving or searching for the
+ executable path with ``shell=False``, *cwd* does not override the
+ current working directory and *env* cannot override the ``PATH``
+ environment variable. Using a full path avoids all of these variations.
+
 An example of passing some arguments to an external program
 as a sequence is::
 
@@ -524,7 +543,7 @@ functions.
 
 If *cwd* is not ``None``, the function changes the working directory to
 *cwd* before executing the child. *cwd* can be a string, bytes or
- :term:`path-like <path-like object>` object. In particular, the function
+ :term:`path-like <path-like object>` object. In POSIX, the function
 looks for *executable* (or for the first item in *args*) relative to *cwd*
 if the executable path is a relative path.
 
