Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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

This commit is contained in:
Chris Jerdonek 2012-10-10 17:55:41 -07:00
parent cfb01a5ad0
commit 2a6672b100
1 changed files with 24 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
Doc/library/subprocess.rst
View File

@ -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`.