From 87ba642ce6f325fa8e3ec3beff736cc135d9c754 Mon Sep 17 00:00:00 2001
From: Nick Coghlan <ncoghlan@gmail.com>
Date: Thu, 27 Oct 2011 17:55:13 +1000
Subject: [PATCH] Issue #13237: Make the subprocess convenience helper
 documentation self-contained aside from the shared parameter description.
 Downgrade the pipe warnings at that level to notes (since those pipes are
 hidden, people are unlikely to even try it)

---
 Doc/library/subprocess.rst | 52 ++++++++++++++++++++++++++++++--------
 1 file changed, 42 insertions(+), 10 deletions(-)

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index ee46d728412..4d584bb995f 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -42,9 +42,10 @@ use cases, the underlying :class:`Popen` interface can be used directly.
    return the :attr:`returncode` attribute.
 
    The arguments shown above are merely the most common ones, described below
-   in :ref:`frequently-used-arguments`. The full function signature is the
-   same as that of the :class:`Popen` constructor - the convenience functions
-   pass all supplied arguments directly through to that interface.
+   in :ref:`frequently-used-arguments` (hence the slightly odd notation in
+   the abbreviated signature). The full function signature is the same as
+   that of the :class:`Popen` constructor - this functions passes all
+   supplied arguments directly through to that interface.
 
    Examples::
 
@@ -56,20 +57,32 @@ use cases, the underlying :class:`Popen` interface can be used directly.
 
    .. warning::
 
+      Invoking the system shell with ``shell=True`` can be a security hazard
+      if combined with untrusted input. See the warning under
+      :ref:`frequently-used-arguments` for details.
+
+   .. note::
+
       Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As
       the pipes are not being read in the current process, the child
       process may block if it generates enough output to a pipe to fill up
       the OS pipe buffer.
 
 
-.. function:: check_call(*callargs, **kwargs)
+.. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False)
 
    Run command with arguments.  Wait for command to complete. If the return
    code was zero then return, otherwise raise :exc:`CalledProcessError`. The
    :exc:`CalledProcessError` object will have the return code in the
    :attr:`returncode` attribute.
 
-   The arguments are the same as for :func:`call`.  Examples::
+   The arguments shown above are merely the most common ones, described below
+   in :ref:`frequently-used-arguments` (hence the slightly odd notation in
+   the abbreviated signature). The full function signature is the same as
+   that of the :class:`Popen` constructor - this functions passes all
+   supplied arguments directly through to that interface.
+
+   Examples::
 
       >>> subprocess.check_call(["ls", "-l"])
       0
@@ -83,10 +96,19 @@ use cases, the underlying :class:`Popen` interface can be used directly.
 
    .. warning::
 
-      See the warning for :func:`call`.
+      Invoking the system shell with ``shell=True`` can be a security hazard
+      if combined with untrusted input. See the warning under
+      :ref:`frequently-used-arguments` for details.
+
+   .. note::
+
+      Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As
+      the pipes are not being read in the current process, the child
+      process may block if it generates enough output to a pipe to fill up
+      the OS pipe buffer.
 
 
-.. function:: check_output(*callargs, **kwargs)
+.. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False)
 
    Run command with arguments and return its output as a byte string.
 
@@ -95,8 +117,12 @@ use cases, the underlying :class:`Popen` interface can be used directly.
    :attr:`returncode` attribute and any output in the :attr:`output`
    attribute.
 
-   The arguments are the same as for :func:`call`, except that *stdout* is
-   not permitted as it is used internally.
+   The arguments shown above are merely the most common ones, described below
+   in :ref:`frequently-used-arguments` (hence the slightly odd notation in
+   the abbreviated signature). The full function signature is largely the
+   same as that of the :class:`Popen` constructor, except that *stdout* is
+   not permitted as it is used internally. All other supplied arguments are
+   passed directly through to the :class:`Popen` constructor.
 
    Examples::
 
@@ -121,6 +147,12 @@ use cases, the underlying :class:`Popen` interface can be used directly.
 
    .. warning::
 
+      Invoking the system shell with ``shell=True`` can be a security hazard
+      if combined with untrusted input. See the warning under
+      :ref:`frequently-used-arguments` for details.
+
+   .. note::
+
       Do not use ``stderr=PIPE`` with this function. As the pipe is not being
       read in the current process, the child process may block if it
       generates enough output to the pipe to fill up the OS pipe buffer.
@@ -306,7 +338,7 @@ functions.
    If *shell* is :const:`True`, the specified command will be executed through the
    shell.
 
-   .. note::
+   .. warning::
 
       Enabling this option can be a security hazard if combined with untrusted
       input. See the warning under :ref:`frequently-used-arguments`