bpo-32815: Improve docs on the subprocess API *text* parameter (GH-5622)

Describe *text* as an alias for *universal_newlines* in more places that people are likely to be referred to.

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 8673c4b18d8caaf6a2d79a9c716012be6659b0fa..a22afe041850bb3075d9d528f6406f07ec4cd76c 100644 (file)
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -39,7 +39,7 @@ compatibility with older versions, see the :ref:`call-function-trio` section.
 
 .. function:: run(args, *, stdin=None, input=None, stdout=None, stderr=None,\
                   shell=False, cwd=None, timeout=None, check=False, \
-                  encoding=None, errors=None)
+                  encoding=None, errors=None, text=None)
 
    Run the command described by *args*.  Wait for command to complete, then
    return a :class:`CompletedProcess` instance.
@@ -267,7 +267,8 @@ default values. The arguments that are most commonly needed are:
    .. index::
       single: universal newlines; subprocess module
 
-   If *encoding* or *errors* are specified, or *universal_newlines* is true,
+   If *encoding* or *errors* are specified, or *text* (also known as
+   *universal_newlines*) is true,
    the file objects *stdin*, *stdout* and *stderr* will be opened in text
    mode using the *encoding* and *errors* specified in the call or the
    defaults for :class:`io.TextIOWrapper`.
@@ -284,6 +285,9 @@ default values. The arguments that are most commonly needed are:
    .. versionadded:: 3.6
       Added *encoding* and *errors* parameters.
 
+   .. versionadded:: 3.7
+      Added the *text* parameter as an alias for *universal_newlines*.
+
    .. note::
 
       The newlines attribute of the file objects :attr:`Popen.stdin`,
@@ -328,7 +332,7 @@ functions.
                  cwd=None, env=None, universal_newlines=False, \
                  startupinfo=None, creationflags=0, restore_signals=True, \
                  start_new_session=False, pass_fds=(), *, \
-                 encoding=None, errors=None)
+                 encoding=None, errors=None, text=None)
 
    Execute a child program in a new process.  On POSIX, the class uses
    :meth:`os.execvp`-like behavior to execute the child program.  On Windows,
@@ -511,15 +515,18 @@ functions.
 
    .. _side-by-side assembly: https://en.wikipedia.org/wiki/Side-by-Side_Assembly
 
-   If *encoding* or *errors* are specified, the file objects *stdin*, *stdout*
-   and *stderr* are opened in text mode with the specified encoding and
-   *errors*, as described above in :ref:`frequently-used-arguments`. If
-   *universal_newlines* is ``True``, they are opened in text mode with default
-   encoding. Otherwise, they are opened as binary streams.
+   If *encoding* or *errors* are specified, or *text* is true, the file objects
+   *stdin*, *stdout* and *stderr* are opened in text mode with the specified
+   encoding and *errors*, as described above in :ref:`frequently-used-arguments`.
+   The *universal_newlines* argument is equivalent  to *text* and is provided
+   for backwards compatibility. By default, file objects are opened in binary mode.
 
    .. versionadded:: 3.6
       *encoding* and *errors* were added.
 
+   .. versionadded:: 3.7
+      *text* was added as a more readable alias for *universal_newlines*.
+
    If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
    passed to the underlying ``CreateProcess`` function.
    *creationflags*, if given, can be one or more of the following flags: