From 4a2b20b033c17cd0dcaa8619d44020dad56153b9 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Sat, 23 Mar 2019 00:22:58 -0700 Subject: [PATCH 1/3] bpo-33319: Clarify subprocess call docs. --- Doc/library/subprocess.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 9ba0d30da5698e..5d504cef01fbca 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -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 used at the same time. 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``:: From 2c877dd44866f9260489cc0876eb2dfadeb9cc53 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Sat, 23 Mar 2019 00:27:38 -0700 Subject: [PATCH 2/3] further clarification. --- Doc/library/subprocess.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 5d504cef01fbca..d62ec21f923e2c 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -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 at the same time. + 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 From 60005285d30f2f6e155f142412ce19e16df9e0c7 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Sat, 23 Mar 2019 00:28:58 -0700 Subject: [PATCH 3/3] remove extra . --- Doc/library/subprocess.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index d62ec21f923e2c..ca0813c7830ad0 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -1079,7 +1079,7 @@ calls these functions. 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`.. + :ref:`frequently-used-arguments` and :func:`run`. To also capture standard error in the result, use ``stderr=subprocess.STDOUT``::