summaryrefslogtreecommitdiffstats
path: root/Doc/library/subprocess.rst
diff options
context:
space:
mode:
authorandyclegg <andy2.0@gmail.com>2017-10-23 02:01:19 (GMT)
committerGregory P. Smith <greg@krypto.org>2017-10-23 02:01:19 (GMT)
commit7fed7bd8bb628f0f09c6011871a4ce68afb41b18 (patch)
treea89c99e634133cae2dc33671182f8f4ae0723226 /Doc/library/subprocess.rst
parentae3087c6382011c47db82fea4d05f8bbf514265d (diff)
downloadcpython-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.rst19
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()