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

bpo-33319: Clarify subprocess call docs. (GH-12508) 

Clarify capturing or suppressing stdout and stderr on the old call APIs.

Do not state that they are equivalent to run() calls when they are not implemented using run as that was misleading. Unlike run they cannot handle stdout or stderr being set to PIPE without a risk of deadlock.
This commit is contained in:
Gregory P. Smith 2019-03-23 00:40:28 -07:00 committed by GitHub
parent 7c822e50f0
commit 7a2e84c348
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 13 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
Doc/library/subprocess.rst
View File

@ -55,7 +55,7 @@ compatibility with older versions, see the :ref:`call-function-trio` section.
If *capture_output* is true, stdout and stderr will be captured.
When used, the internal :class:`Popen` object is automatically created with
``stdout=PIPE`` and ``stderr=PIPE``. The *stdout* and *stderr* arguments may
not be used as well.
not be supplied at the same time as *capture_output*.
The *timeout* argument is passed to :meth:`Popen.communicate`. If the timeout
expires, the child process will be killed and waited for. The
@ -1002,14 +1002,14 @@ calls these functions.
Run the command described by *args*. Wait for command to complete, then
return the :attr:`~Popen.returncode` attribute.
This is equivalent to::
Code needing to capture stdout or stderr should use :func:`run` instead:
run(...).returncode
(except that the *input* and *check* parameters are not supported)
To suppress stdout or stderr, supply a value of :data:`DEVNULL`.
The arguments shown above are merely the most
common ones. The full function signature is largely the
The arguments shown above are merely some common ones.
The full function signature is the
same as that of the :class:`Popen` constructor - this function passes all
supplied arguments other than *timeout* directly through to that interface.
@ -1030,14 +1030,14 @@ calls these functions.
:exc:`CalledProcessError` object will have the return code in the
:attr:`~CalledProcessError.returncode` attribute.
This is equivalent to::
Code needing to capture stdout or stderr should use :func:`run` instead:
run(..., check=True)
(except that the *input* parameter is not supported)
To suppress stdout or stderr, supply a value of :data:`DEVNULL`.
The arguments shown above are merely the most
common ones. The full function signature is largely the
The arguments shown above are merely some common ones.
The full function signature is the
same as that of the :class:`Popen` constructor - this function passes all
supplied arguments other than *timeout* directly through to that interface.
@ -1067,7 +1067,7 @@ calls these functions.
run(..., check=True, stdout=PIPE).stdout
The arguments shown above are merely the most common ones.
The arguments shown above are merely some common ones.
The full function signature is largely the same as that of :func:`run` -
most arguments are passed directly through to that interface.
However, explicitly passing ``input=None`` to inherit the parent's
@ -1077,8 +1077,9 @@ calls these functions.
encoding of the output data may depend on the command being invoked, so the
decoding to text will often need to be handled at the application level.
This behaviour may be overridden by setting *universal_newlines* to
``True`` as described above in :ref:`frequently-used-arguments`.
This behaviour may be overridden by setting *text*, *encoding*, *errors*,
or *universal_newlines* to ``True`` as described in
:ref:`frequently-used-arguments` and :func:`run`.
To also capture standard error in the result, use
``stderr=subprocess.STDOUT``::