diff options
| -rw-r--r-- | Doc/library/subprocess.rst | 42 |
1 files changed, 25 insertions, 17 deletions
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 268f0b8..5d689e6 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -286,19 +286,27 @@ are able to handle the less common cases not covered by the convenience functions. -.. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=()) +.. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, \ + stderr=None, preexec_fn=None, close_fds=True, shell=False, \ + cwd=None, env=None, universal_newlines=False, \ + startupinfo=None, creationflags=0, restore_signals=True, \ + start_new_session=False, pass_fds=()) - 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. 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 - *shell* and *executable* arguments for differences from this behavior. + a sequence. If *args* is a string, the interpretation is + 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 - execute the child program. If *args* is a string, the string is - interpreted as the name or path of the program to execute; this only works - if the program is being given no arguments. + On Unix, if *args* is a string, the string is interpreted as the name or + path of the program to execute. However, this can only be done if not + passing arguments to the program. .. note:: @@ -319,14 +327,13 @@ functions. used in the shell (such as filenames containing spaces or the *echo* command shown above) are single list elements. - On Windows, the :class:`Popen` class uses ``CreateProcess()`` to - 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`. + On Windows, if *args* is a sequence, it will be converted to a string in a + manner described in :ref:`converting-argument-sequence`. This is because + the underlying ``CreateProcess()`` operates on strings. 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*. + the shell as the program to execute. If *shell* is *True*, it is + 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 *args* is a string, the string specifies the command @@ -365,9 +372,10 @@ functions. The *executable* argument specifies a replacement program to execute. It is very seldom needed. When ``shell=False``, *executable* replaces the - program to execute specified by *args*. However, the *args* program is - still treated by most programs as the command name, which can then be - different from the program actually executed. On Unix, the *args* name + program to execute specified by *args*. However, the original *args* is + still passed to the program. Most programs treat the program specified + 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 :program:`ps`. If ``shell=True``, on Unix the *executable* argument specifies a replacement shell for the default :file:`/bin/sh`. |