diff options
author | Georg Brandl <georg@python.org> | 2008-12-06 11:57:12 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2008-12-06 11:57:12 (GMT) |
commit | f5d5a663491bdcf08a135db322eee4ac43522524 (patch) | |
tree | 9770ab1030b5340bafce68da7151fb0067701571 /Doc/library | |
parent | 826f3fefe5d86a5f479a256c535d7f31ce3f88ee (diff) | |
download | cpython-f5d5a663491bdcf08a135db322eee4ac43522524.zip cpython-f5d5a663491bdcf08a135db322eee4ac43522524.tar.gz cpython-f5d5a663491bdcf08a135db322eee4ac43522524.tar.bz2 |
Follow-up to #4488: document PIPE and STDOUT properly.
Diffstat (limited to 'Doc/library')
-rw-r--r-- | Doc/library/subprocess.rst | 51 |
1 files changed, 33 insertions, 18 deletions
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 1a0f134..e0ab96d 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -73,13 +73,13 @@ This module defines one class called :class:`Popen`: specified by the :envvar:`COMSPEC` environment variable. *stdin*, *stdout* and *stderr* specify the executed programs' standard input, - standard output and standard error file handles, respectively. Valid values are - ``PIPE``, an existing file descriptor (a positive integer), an existing file - object, and ``None``. ``PIPE`` indicates that a new pipe to the child should be - created. With ``None``, no redirection will occur; the child's file handles - will be inherited from the parent. Additionally, *stderr* can be ``STDOUT``, - which indicates that the stderr data from the applications should be captured - into the same file handle as for stdout. + standard output and standard error file handles, respectively. Valid values + are :data:`PIPE`, an existing file descriptor (a positive integer), an + existing file object, and ``None``. :data:`PIPE` indicates that a new pipe + to the child should be created. With ``None``, no redirection will occur; + the child's file handles will be inherited from the parent. Additionally, + *stderr* can be :data:`STDOUT`, which indicates that the stderr data from the + applications should be captured into the same file handle as for stdout. If *preexec_fn* is set to a callable object, this object will be called in the child process just before the child is executed. (Unix only) @@ -119,6 +119,20 @@ This module defines one class called :class:`Popen`: of the main window and priority for the new process. (Windows only) +.. data:: PIPE + + Special value that can be used as the *stdin*, *stdout* or *stderr* argument + to :class:`Popen` and indicates that a pipe to the standard stream should be + opened. + + +.. data:: STDOUT + + Special value that can be used as the *stderr* argument to :class:`Popen` and + indicates that standard error should go into the same handle as standard + output. + + Convenience Functions ^^^^^^^^^^^^^^^^^^^^^ @@ -285,20 +299,21 @@ The following attributes are also available: .. attribute:: Popen.stdin - If the *stdin* argument is ``PIPE``, this attribute is a file object that - provides input to the child process. Otherwise, it is ``None``. + If the *stdin* argument was :data:`PIPE`, this attribute is a file object + that provides input to the child process. Otherwise, it is ``None``. .. attribute:: Popen.stdout - If the *stdout* argument is ``PIPE``, this attribute is a file object that - provides output from the child process. Otherwise, it is ``None``. + If the *stdout* argument was :data:`PIPE`, this attribute is a file object + that provides output from the child process. Otherwise, it is ``None``. .. attribute:: Popen.stderr - If the *stderr* argument is ``PIPE``, this attribute is file object that - provides error output from the child process. Otherwise, it is ``None``. + If the *stderr* argument was :data:`PIPE`, this attribute is a file object + that provides error output from the child process. Otherwise, it is + ``None``. .. attribute:: Popen.pid @@ -478,15 +493,15 @@ Replacing functions from the popen2 module stdin=PIPE, stdout=PIPE, close_fds=True) (child_stdout, child_stdin) = (p.stdout, p.stdin) -The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen, except -that: +:class:`popen2.Popen3` and :class:`popen2.Popen4` basically work as +:class:`subprocess.Popen`, except that: -* subprocess.Popen raises an exception if the execution fails +* :class:`Popen` raises an exception if the execution fails. * the *capturestderr* argument is replaced with the *stderr* argument. -* stdin=PIPE and stdout=PIPE must be specified. +* ``stdin=PIPE`` and ``stdout=PIPE`` must be specified. * popen2 closes all file descriptors by default, but you have to specify - close_fds=True with subprocess.Popen. + ``close_fds=True`` with :class:`Popen`. |