mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 10:19:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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

Browse source 
Patch by Chris Jerdonek.
This commit is contained in:
Andrew Svetlov 2012-08-13 22:09:04 +03:00
parent ecd78feb78
commit 50be452e0f
1 changed files with 21 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

40
Doc/library/subprocess.rst
View file

@ -136,7 +136,7 @@ use cases, the underlying :class:`Popen` interface can be used directly.
decoding to text will often need to be handled at the application level. decoding to text will often need to be handled at the application level.
This behaviour may be overridden by setting *universal_newlines* to 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 To also capture standard error in the result, use
``stderr=subprocess.STDOUT``:: ``stderr=subprocess.STDOUT``::
@ -224,13 +224,24 @@ default values. The arguments that are most commonly needed are:
the stderr data from the child process should be captured into the same file the stderr data from the child process should be captured into the same file
handle as for stdout. handle as for stdout.
When *stdout* or *stderr* are pipes and *universal_newlines* is If *universal_newlines* is ``True``, the file objects *stdin*, *stdout*
:const:`True` then the output data is assumed to be encoded as UTF-8 and and *stderr* will be opened as text streams with universal newlines support,
will automatically be decoded to text. All line endings will be converted using the encoding returned by :func:`locale.getpreferredencoding`.
to ``'\n'`` as described for the universal newlines ``'U'`` mode argument For *stdin*, line ending characters ``'\n'`` in the input will be converted
to :func:`open`. 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 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 enhanced control flow it offers over most system shells and still want
access to other shell features such as filename wildcards, shell pipes and access to other shell features such as filename wildcards, shell pipes and
@ -428,18 +439,9 @@ functions.
.. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly .. _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 If *universal_newlines* is ``True``, the file objects *stdin*, *stdout*
opened as text files, but lines may be terminated by any of ``'\n'``, the Unix and *stderr* are opened as text files with universal newlines support, as
end-of-line convention, ``'\r'``, the old Macintosh convention or ``'\r\n'``, the described above in :ref:`frequently-used-arguments`.
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 given, *startupinfo* will be a :class:`STARTUPINFO` object, which is If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
passed to the underlying ``CreateProcess`` function. passed to the underlying ``CreateProcess`` function.