diff options
author | andyclegg <andy2.0@gmail.com> | 2017-10-23 02:01:19 (GMT) |
---|---|---|
committer | Gregory P. Smith <greg@krypto.org> | 2017-10-23 02:01:19 (GMT) |
commit | 7fed7bd8bb628f0f09c6011871a4ce68afb41b18 (patch) | |
tree | a89c99e634133cae2dc33671182f8f4ae0723226 /Doc/library/subprocess.rst | |
parent | ae3087c6382011c47db82fea4d05f8bbf514265d (diff) | |
download | cpython-7fed7bd8bb628f0f09c6011871a4ce68afb41b18.zip cpython-7fed7bd8bb628f0f09c6011871a4ce68afb41b18.tar.gz cpython-7fed7bd8bb628f0f09c6011871a4ce68afb41b18.tar.bz2 |
bpo-31756: subprocess.run should alias universal_newlines to text (#4049)
Improve human friendliness of the Popen API: Add text=False as a
keyword-only argument to subprocess.Popen along with a Popen
attribute .text_mode and set this based on the
encoding/errors/universal_newlines/text arguments.
The universal_newlines parameter and attribute are maintained for
backwards compatibility.
Diffstat (limited to 'Doc/library/subprocess.rst')
-rw-r--r-- | Doc/library/subprocess.rst | 19 |
1 files changed, 12 insertions, 7 deletions
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 21b1299..693355c 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -61,7 +61,7 @@ compatibility with older versions, see the :ref:`call-function-trio` section. The *input* argument is passed to :meth:`Popen.communicate` and thus to the subprocess's stdin. If used it must be a byte sequence, or a string if - *encoding* or *errors* is specified or *universal_newlines* is true. When + *encoding* or *errors* is specified or *text* is true. When used, the internal :class:`Popen` object is automatically created with ``stdin=PIPE``, and the *stdin* argument may not be used as well. @@ -70,10 +70,11 @@ compatibility with older versions, see the :ref:`call-function-trio` section. exception hold the arguments, the exit code, and stdout and stderr if they were captured. - If *encoding* or *errors* are specified, or *universal_newlines* is true, + If *encoding* or *errors* are specified, or *text* is true, file objects for stdin, stdout and stderr are opened in text mode using the specified *encoding* and *errors* or the :class:`io.TextIOWrapper` default. - Otherwise, file objects are opened in binary mode. + The *universal_newlines* argument is equivalent to *text* and is provided + for backwards compatibility. By default, file objects are opened in binary mode. Examples:: @@ -95,6 +96,10 @@ compatibility with older versions, see the :ref:`call-function-trio` section. Added *encoding* and *errors* parameters + .. versionchanged:: 3.7 + + Added the *text* parameter, as a more understandable alias of *universal_newlines* + .. class:: CompletedProcess The return value from :func:`run`, representing a process that has finished. @@ -114,8 +119,8 @@ compatibility with older versions, see the :ref:`call-function-trio` section. .. attribute:: stdout Captured stdout from the child process. A bytes sequence, or a string if - :func:`run` was called with an encoding or errors. ``None`` if stdout was not - captured. + :func:`run` was called with an encoding, errors, or text=True. + ``None`` if stdout was not captured. If you ran the process with ``stderr=subprocess.STDOUT``, stdout and stderr will be combined in this attribute, and :attr:`stderr` will be @@ -124,8 +129,8 @@ compatibility with older versions, see the :ref:`call-function-trio` section. .. attribute:: stderr Captured stderr from the child process. A bytes sequence, or a string if - :func:`run` was called with an encoding or errors. ``None`` if stderr was not - captured. + :func:`run` was called with an encoding, errors, or text=True. + ``None`` if stderr was not captured. .. method:: check_returncode() |