[Python-checkins] cpython (2.7): Issue #13237: Make the subprocess convenience helper documentation

[nick.coghlan]

http://hg.python.org/cpython/rev/2a2df6a72ccb
changeset:   73141:2a2df6a72ccb
branch:      2.7
parent:      73135:e0499b2b28aa
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Thu Oct 27 17:55:13 2011 +1000
summary:
  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)

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


diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -42,9 +42,10 @@
    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 @@
 
    .. 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 @@
 
    .. 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::
 
-.. function:: check_output(*callargs, **kwargs)
+      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(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 @@
    :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 @@
 
    .. 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 @@
    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`

-- 
Repository URL: http://hg.python.org/cpython