From: Andrew Svetlov <andrew.svetlov@gmail.com>
Date: Mon, 13 Aug 2012 19:11:14 +0000 (+0300)
Subject: Issue #15561: Update subprocess docs to reference io.TextIOWrapper.
X-Git-Tag: v3.3.0rc1~126
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4805fa862ed1041e84c01f3293b73f50d3055693;p=python

Issue #15561: Update subprocess docs to reference io.TextIOWrapper.

Patch by Chris Jerdonek.
---

4805fa862ed1041e84c01f3293b73f50d3055693
diff --cc Doc/library/io.rst
index 2a3c5d8853,09e050196c..5fec4cd46f
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@@ -754,7 -744,7 +754,8 @@@ Text I/
     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`.
++   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 --cc Doc/library/subprocess.rst
index a67bf646e9,b96398300e..7557c928be
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@@ -276,27 -216,37 +276,44 @@@ default values. The arguments that are 
  
     *stdin*, *stdout* and *stderr* specify the executed program's standard input,
     standard output and standard error file handles, respectively.  Valid values
 -   are :data:`PIPE`, an existing file descriptor (a positive integer), an
 -   existing file object, and ``None``.  :data:`PIPE` indicates that a new pipe
 -   to the child should be created.  With the default settings of ``None``, no
 -   redirection will occur; the child's file handles will be inherited from the
 -   parent.  Additionally, *stderr* can be :data:`STDOUT`, which indicates that
 -   the stderr data from the child process should be captured into the same file
 -   handle as for stdout.
 +   are :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a positive
 +   integer), an existing file object, and ``None``.  :data:`PIPE` indicates
 +   that a new pipe to the child should be created.  :data:`DEVNULL` indicates
 +   that the special file :data:`os.devnull` will be used.  With the default
 +   settings of ``None``, no redirection will occur; the child's file handles
 +   will be inherited from the parent.  Additionally, *stderr* can be
 +   :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