cpython: 0cd9423770fa (original) (raw)

Mercurial > cpython

changeset 78546:0cd9423770fa

Issue #15561: Update subprocess docs to reference io.TextIOWrapper. Patch by Chris Jerdonek. [#15561]

Andrew Svetlov andrew.svetlov@gmail.com
date	Mon, 13 Aug 2012 22:11:14 +0300
parents	db96fe40de54(current diff)381aaf79c254(diff)
children	1c8a6df94602
files	Doc/library/io.rst Doc/library/subprocess.rst
diffstat	2 files changed, 29 insertions(+), 20 deletions(-)[+] [-] Doc/library/io.rst 3 Doc/library/subprocess.rst 46

line wrap: on

line diff

--- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -754,7 +754,8 @@ Text I/O 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

--- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -156,7 +156,7 @@ use cases, the underlying :class:Popen 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 @@ default values. The arguments that are m :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[](#l2.33)

 with universal newline support (the default).  Also, the newlines[](#l2.34)

 attribute of the file objects :attr:`Popen.stdin`, :attr:`Popen.stdout`[](#l2.35)

 and :attr:`Popen.stderr` are not updated by the[](#l2.36)

 :meth:`Popen.communicate` method.[](#l2.37)

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[](#l2.46)

 :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`[](#l2.47)

 instead of ``locale.getpreferredencoding()``.  See the[](#l2.48)

 :class:`io.TextIOWrapper` class for more information on this change.[](#l2.49)

+ .. warning:: Executing shell commands that incorporate unsanitized input from an @@ -490,18 +507,9 @@ functions. .. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly[](#l2.56)

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[](#l2.66)

 support (the default).  Also, the newlines attribute of the file objects[](#l2.67)

 :attr:`stdout`, :attr:`stdin` and :attr:`stderr` are not updated by the[](#l2.68)

```
 :meth:`communicate` method.[](#l2.69)
```

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.