Issue #15561: Update subprocess docs to reference io.TextIOWrapper.
Patch by Chris Jerdonek.
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 2a3c5d8..5fec4cd 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -754,7 +754,8 @@
It inherits :class:`TextIOBase`.
*encoding* gives the name of the encoding that the stream will be decoded or
- encoded with. It defaults to ``locale.getpreferredencoding(False)``.
+ encoded with. It defaults to
+ :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`.
*errors* is an optional string that specifies how encoding and decoding
errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError`
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index a67bf64..7557c92 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -156,7 +156,7 @@
decoding to text will often need to be handled at the application level.
This behaviour may be overridden by setting *universal_newlines* to
- :const:`True` as described below in :ref:`frequently-used-arguments`.
+ ``True`` as described below in :ref:`frequently-used-arguments`.
To also capture standard error in the result, use
``stderr=subprocess.STDOUT``::
@@ -285,18 +285,35 @@
:data:`STDOUT`, which indicates that the stderr data from the child
process should be captured into the same file handle as for *stdout*.
- When *stdout* or *stderr* are pipes and *universal_newlines* is
- :const:`True` then the output data is assumed to be encoded as UTF-8 and
- will automatically be decoded to text. All line endings will be converted
- to ``'\n'`` as described for the universal newlines ``'U'`` mode argument
- to :func:`open`.
+ If *universal_newlines* is ``True``, the file objects *stdin*, *stdout*
+ and *stderr* will be opened as text streams with universal newlines support,
+ using the encoding returned by :func:`locale.getpreferredencoding`.
+ For *stdin*, line ending characters ``'\n'`` in the input will be converted
+ to the default line separator :data:`os.linesep`. For *stdout* and
+ *stderr*, all line endings in the output will be converted to ``'\n'``.
+ For more information see the documentation of the :class:`io.TextIOWrapper`
+ class when the *newline* argument to its constructor is ``None``.
- If *shell* is :const:`True`, the specified command will be executed through
+ .. note::
+
+ The *universal_newlines* feature is supported only if Python is built
+ with universal newline support (the default). Also, the newlines
+ attribute of the file objects :attr:`Popen.stdin`, :attr:`Popen.stdout`
+ and :attr:`Popen.stderr` are not updated by the
+ :meth:`Popen.communicate` method.
+
+ If *shell* is ``True``, the specified command will be executed through
the shell. This can be useful if you are using Python primarily for the
enhanced control flow it offers over most system shells and still want
access to other shell features such as filename wildcards, shell pipes and
environment variable expansion.
+ .. versionchanged:: 3.3
+ When *universal_newlines* is ``True``, the class uses the encoding
+ :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`
+ instead of ``locale.getpreferredencoding()``. See the
+ :class:`io.TextIOWrapper` class for more information on this change.
+
.. warning::
Executing shell commands that incorporate unsanitized input from an
@@ -490,18 +507,9 @@
.. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly
- If *universal_newlines* is :const:`True`, the file objects stdout and stderr are
- opened as text files, but lines may be terminated by any of ``'\n'``, the Unix
- end-of-line convention, ``'\r'``, the old Macintosh convention or ``'\r\n'``, the
- Windows convention. All of these external representations are seen as ``'\n'``
- by the Python program.
-
- .. note::
-
- This feature is only available if Python is built with universal newline
- support (the default). Also, the newlines attribute of the file objects
- :attr:`stdout`, :attr:`stdin` and :attr:`stderr` are not updated by the
- :meth:`communicate` method.
+ If *universal_newlines* is ``True``, the file objects *stdin*, *stdout*
+ and *stderr* are opened as text files with universal newlines support, as
+ described above in :ref:`frequently-used-arguments`.
If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
passed to the underlying ``CreateProcess`` function.