mirror of https://github.com/python/cpython
Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2.
This commit is contained in:
parent
cfb01a5ad0
commit
2a6672b100
|
@ -269,19 +269,26 @@ are able to handle the less common cases not covered by the convenience
|
||||||
functions.
|
functions.
|
||||||
|
|
||||||
|
|
||||||
.. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=False, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0)
|
.. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, \
|
||||||
|
stderr=None, preexec_fn=None, close_fds=False, shell=False, \
|
||||||
|
cwd=None, env=None, universal_newlines=False, \
|
||||||
|
startupinfo=None, creationflags=0)
|
||||||
|
|
||||||
Arguments are:
|
Execute a child program in a new process. On Unix, the class uses
|
||||||
|
:meth:`os.execvp`-like behavior to execute the child program. On Windows,
|
||||||
|
the class uses the Windows ``CreateProcess()`` function. The arguments to
|
||||||
|
:class:`Popen` are as follows.
|
||||||
|
|
||||||
*args* should be a sequence of program arguments or else a single string.
|
*args* should be a sequence of program arguments or else a single string.
|
||||||
By default, the program to execute is the first item in *args* if *args* is
|
By default, the program to execute is the first item in *args* if *args* is
|
||||||
a sequence and the string itself if *args* is a string. However, see the
|
a sequence. If *args* is a string, the interpretation is
|
||||||
*shell* and *executable* arguments for differences from this behavior.
|
platform-dependent and described below. See the *shell* and *executable*
|
||||||
|
arguments for additional differences from the default behavior. Unless
|
||||||
|
otherwise stated, it is recommended to pass *args* as a sequence.
|
||||||
|
|
||||||
On Unix, the :class:`Popen` class uses :meth:`os.execvp`-like behavior to
|
On Unix, if *args* is a string, the string is interpreted as the name or
|
||||||
execute the child program. If *args* is a string, the string is
|
path of the program to execute. However, this can only be done if not
|
||||||
interpreted as the name or path of the program to execute; this only works
|
passing arguments to the program.
|
||||||
if the program is being given no arguments.
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
@ -302,14 +309,13 @@ functions.
|
||||||
used in the shell (such as filenames containing spaces or the *echo* command
|
used in the shell (such as filenames containing spaces or the *echo* command
|
||||||
shown above) are single list elements.
|
shown above) are single list elements.
|
||||||
|
|
||||||
On Windows, the :class:`Popen` class uses ``CreateProcess()`` to
|
On Windows, if *args* is a sequence, it will be converted to a string in a
|
||||||
execute the child program, which operates on strings. If *args* is a
|
manner described in :ref:`converting-argument-sequence`. This is because
|
||||||
sequence, it will be converted to a string in a manner described in
|
the underlying ``CreateProcess()`` operates on strings.
|
||||||
:ref:`converting-argument-sequence`.
|
|
||||||
|
|
||||||
The *shell* argument (which defaults to *False*) specifies whether to use
|
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
|
the shell as the program to execute. If *shell* is *True*, it is
|
||||||
sequence if *shell* is *False* and as a string if *shell* is *True*.
|
recommended to pass *args* as a string rather than as a sequence.
|
||||||
|
|
||||||
On Unix with ``shell=True``, the shell defaults to :file:`/bin/sh`. If
|
On Unix with ``shell=True``, the shell defaults to :file:`/bin/sh`. If
|
||||||
*args* is a string, the string specifies the command
|
*args* is a string, the string specifies the command
|
||||||
|
@ -342,9 +348,10 @@ functions.
|
||||||
|
|
||||||
The *executable* argument specifies a replacement program to execute. It
|
The *executable* argument specifies a replacement program to execute. It
|
||||||
is very seldom needed. When ``shell=False``, *executable* replaces the
|
is very seldom needed. When ``shell=False``, *executable* replaces the
|
||||||
program to execute specified by *args*. However, the *args* program is
|
program to execute specified by *args*. However, the original *args* is
|
||||||
still treated by most programs as the command name, which can then be
|
still passed to the program. Most programs treat the program specified
|
||||||
different from the program actually executed. On Unix, the *args* name
|
by *args* as the command name, which can then be different from the program
|
||||||
|
actually executed. On Unix, the *args* name
|
||||||
becomes the display name for the executable in utilities such as
|
becomes the display name for the executable in utilities such as
|
||||||
:program:`ps`. If ``shell=True``, on Unix the *executable* argument
|
:program:`ps`. If ``shell=True``, on Unix the *executable* argument
|
||||||
specifies a replacement shell for the default :file:`/bin/sh`.
|
specifies a replacement shell for the default :file:`/bin/sh`.
|
||||||
|
|
Loading…
Reference in New Issue