Documentation regressions from adding subprocess.run()

Doc/library/subprocess.rst

 :mod:`subprocess` --- Subprocess management
 ===========================================
 
 .. module:: subprocess
    :synopsis: Subprocess management.
 .. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se>
 .. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
 
 
 The :mod:`subprocess` module allows you to spawn new processes, connect to their
@@ skipping 807 matching lines @@
 Older high-level API
 --------------------
 
 Prior to Python 3.5, these three functions comprised the high level API to
 subprocess. You can now use :func:`run` in many cases, but lots of existing code
 calls these functions.
 
 .. function:: call(args, *, stdin=None, stdout=None, stderr=None, shell=False, timeout=None)
 
    Run the command described by *args*.  Wait for command to complete, then
-   return the :attr:`returncode` attribute.
+   return the :attr:`~Popen.returncode` attribute.
 
    This is equivalent to::
 
        run(...).returncode
 
    (except that the *input* and *check* parameters are not supported)
+
+   The arguments shown above are merely the most
+   common ones. The full function signature is largely the
+   same as that of the :class:`Popen` constructor - this function passes all
+   supplied arguments other than *timeout* directly through to that interface.
 
    .. note::
 
       Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
       function.  The child process will block if it generates enough
       output to a pipe to fill up the OS pipe buffer as the pipes are
       not being read from.
 
    .. versionchanged:: 3.3
       *timeout* was added.
 
 .. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, timeout=None)
 
    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:`~CalledProcessError.returncode` attribute.
 
    This is equivalent to::
 
        run(..., check=True)
 
    (except that the *input* parameter is not supported)
+
+   The arguments shown above are merely the most
+   common ones. The full function signature is largely the
+   same as that of the :class:`Popen` constructor - this function passes all
+   supplied arguments other than *timeout* directly through to that interface.
 
    .. note::
 
       Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
       function.  The child process will block if it generates enough
       output to a pipe to fill up the OS pipe buffer as the pipes are
       not being read from.
 
    .. versionchanged:: 3.3
       *timeout* was added.
 
 
-.. function:: check_output(args, *, input=None, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None)
+.. function:: check_output(args, *[, input], stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None)

[berkerpeksag, 2015/06/25 23:31:14]

I think we can now remove *input* from the signature.

The following paragraph makes the *input* parameter's presence redundant:

+   The arguments shown above are merely the most common ones.
+   The full function signature is largely the same as that of :func:`run` -
+   most arguments are passed directly through to that interface.
+   The differences are that explicitly passing ``input=None`` is not
+   supported, and that *stdout* is not permitted as an argument, as
+   it is used internally to collect the output from the subprocess.

Also, without ``[, input],``, the signature looks more readable to me.

[Martin Panter, 2015/06/26 02:32:56]

Yes I agree. I might tweak the new paragraph and the “versionchanged” note to
add more context, though.

[berkerpeksag, 2015/06/26 13:16:58]

Yes, that would be better.

 
    Run command with arguments and return its output.
 
    If the return code was non-zero it raises a :exc:`CalledProcessError`. The
    :exc:`CalledProcessError` object will have the return code in the
    :attr:`~CalledProcessError.returncode` attribute and any output in the
    :attr:`~CalledProcessError.output` attribute.
 
    This is equivalent to::
 
        run(..., check=True, stdout=PIPE).stdout
+
+   The arguments shown above are merely the most common ones.
+   The full function signature is largely the same as that of :func:`run` -
+   most arguments are passed directly through to that interface.
+   The differences are that explicitly passing ``input=None`` is not
+   supported, and that *stdout* is not permitted as an argument, as
+   it is used internally to collect the output from the subprocess.
 
    By default, this function will return the data as encoded bytes. The actual
    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`.
 
    To also capture standard error in the result, use
    ``stderr=subprocess.STDOUT``::
@@ skipping 284 matching lines @@
    every pair of backslashes is interpreted as a literal
    backslash.  If the number of backslashes is odd, the last
    backslash escapes the next double quotation mark as
    described in rule 3.
 
 
 .. seealso::
 
    :mod:`shlex`
       Module which provides function to parse and escape command lines.