Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2.

Doc/library/subprocess.rst

@@ -273,19 +273,15 @@ functions.
 
    Arguments are:
 
-   *args* should be a string, or a sequence of program arguments.  The program
+   *args* should be a sequence of program arguments or else a single string.
-   to execute is normally the first item in the args sequence or the string if
+   By default, the program to execute is the first item in *args* if *args* is
-   a string is given, but can be explicitly set by using the *executable*
+   a sequence and the string itself if *args* is a string.  However, see the
-   argument.  When *executable* is given, the first item in the args sequence
+   *shell* and *executable* arguments for differences from this behavior.
-   is still treated by most programs as the command name, which can then be
-   different from the actual executable name.  On Unix, it becomes the display
-   name for the executing program in utilities such as :program:`ps`.
 
-   On Unix, with *shell=False* (default): In this case, the Popen class uses
+   On Unix, the :class:`Popen` class uses :meth:`os.execvp`-like behavior to
-   :meth:`os.execvp` to execute the child program. *args* should normally be a
+   execute the child program.  If *args* is a string, the string is
-   sequence.  If a string is specified for *args*, it will be used as the name
+   interpreted as the name or path of the program to execute; this only works
-   or path of the program to execute; this will only work if the program is
+   if the program is being given no arguments.
-   being given no arguments.
 
    .. note::
 
@@ -306,20 +302,31 @@ functions.
       used in the shell (such as filenames containing spaces or the *echo* command
       shown above) are single list elements.
 
-   On Unix, with *shell=True*: If args is a string, it specifies the command
+   On Windows, the :class:`Popen` class uses ``CreateProcess()`` to
-   string to execute through the shell.  This means that the string must be
+   execute the child program, which operates on strings.  If *args* is a
+   sequence, it will be converted to a string in a manner described in
+   :ref:`converting-argument-sequence`.
+
+   The *shell* argument (which defaults to *False*) specifies whether to use
+   the shell as the program to execute.  It is recommended to pass *args* as a
+   sequence if *shell* is *False* and as a string if *shell* is *True*.
+
+   On Unix with ``shell=True``, the shell defaults to :file:`/bin/sh`.  If
+   *args* is a string, the string specifies the command
+   to execute through the shell.  This means that the string must be
    formatted exactly as it would be when typed at the shell prompt.  This
    includes, for example, quoting or backslash escaping filenames with spaces in
    them.  If *args* is a sequence, the first item specifies the command string, and
    any additional items will be treated as additional arguments to the shell
-   itself.  That is to say, *Popen* does the equivalent of::
+   itself.  That is to say, :class:`Popen` does the equivalent of::
 
       Popen(['/bin/sh', '-c', args[0], args[1], ...])
 
-   On Windows: the :class:`Popen` class uses CreateProcess() to execute the
+   On Windows with ``shell=True``, the :envvar:`COMSPEC` environment variable
-   child program, which operates on strings.  If *args* is a sequence, it will
+   specifies the default shell.  The only time you need to specify
-   be converted to a string in a manner described in
+   ``shell=True`` on Windows is when the command you wish to execute is built
-   :ref:`converting-argument-sequence`.
+   into the shell (e.g. :command:`dir` or :command:`copy`).  You do not need
+   ``shell=True`` to run a batch file or console-based executable.
 
    *bufsize*, if given, has the same meaning as the corresponding argument to the
    built-in open() function: :const:`0` means unbuffered, :const:`1` means line
@@ -333,15 +340,14 @@ functions.
       enable buffering by setting *bufsize* to either -1 or a large enough
       positive value (such as 4096).
 
-   The *executable* argument specifies the program to execute. It is very seldom
+   The *executable* argument specifies a replacement program to execute.   It
-   needed: Usually, the program to execute is defined by the *args* argument. If
+   is very seldom needed.  When ``shell=False``, *executable* replaces the
-   ``shell=True``, the *executable* argument specifies which shell to use. On Unix,
+   program to execute specified by *args*.  However, the *args* program is
-   the default shell is :file:`/bin/sh`.  On Windows, the default shell is
+   still treated by most programs as the command name, which can then be
-   specified by the :envvar:`COMSPEC` environment variable. The only reason you
+   different from the program actually executed.  On Unix, the *args* name
-   would need to specify ``shell=True`` on Windows is where the command you
+   becomes the display name for the executable in utilities such as
-   wish to execute is actually built in to the shell, eg ``dir``, ``copy``.
+   :program:`ps`.  If ``shell=True``, on Unix the *executable* argument
-   You don't need ``shell=True`` to run a batch file, nor to run a console-based
+   specifies a replacement shell for the default :file:`/bin/sh`.
-   executable.
 
    *stdin*, *stdout* and *stderr* specify the executed program's standard input,
    standard output and standard error file handles, respectively.  Valid values

Misc/NEWS

@@ -468,6 +468,9 @@ Build
 Documentation
 -------------
 
+- Issue #16115: Improve subprocess.Popen() documentation around args, shell,
+  and executable arguments.
+
 - Issue #15979: Improve timeit documentation.
 
 - Issue #16036: Improve documentation of built-in int()'s signature and