From e14c01037877768a3fe766e50d14993bd5d8a67e Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Sun, 11 Feb 2018 20:58:23 +0000 Subject: [PATCH] bpo-32815: Improve docs on the subprocess API *text* parameter (GH-5622) Describe *text* as an alias for *universal_newlines* in more places that people are likely to be referred to. --- Doc/library/subprocess.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 8673c4b18d..a22afe0418 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -39,7 +39,7 @@ compatibility with older versions, see the :ref:`call-function-trio` section. .. function:: run(args, *, stdin=None, input=None, stdout=None, stderr=None,\ shell=False, cwd=None, timeout=None, check=False, \ - encoding=None, errors=None) + encoding=None, errors=None, text=None) Run the command described by *args*. Wait for command to complete, then return a :class:`CompletedProcess` instance. @@ -267,7 +267,8 @@ default values. The arguments that are most commonly needed are: .. index:: single: universal newlines; subprocess module - If *encoding* or *errors* are specified, or *universal_newlines* is true, + If *encoding* or *errors* are specified, or *text* (also known as + *universal_newlines*) is true, the file objects *stdin*, *stdout* and *stderr* will be opened in text mode using the *encoding* and *errors* specified in the call or the defaults for :class:`io.TextIOWrapper`. @@ -284,6 +285,9 @@ default values. The arguments that are most commonly needed are: .. versionadded:: 3.6 Added *encoding* and *errors* parameters. + .. versionadded:: 3.7 + Added the *text* parameter as an alias for *universal_newlines*. + .. note:: The newlines attribute of the file objects :attr:`Popen.stdin`, @@ -328,7 +332,7 @@ functions. cwd=None, env=None, universal_newlines=False, \ startupinfo=None, creationflags=0, restore_signals=True, \ start_new_session=False, pass_fds=(), *, \ - encoding=None, errors=None) + encoding=None, errors=None, text=None) Execute a child program in a new process. On POSIX, the class uses :meth:`os.execvp`-like behavior to execute the child program. On Windows, @@ -511,15 +515,18 @@ functions. .. _side-by-side assembly: https://en.wikipedia.org/wiki/Side-by-Side_Assembly - If *encoding* or *errors* are specified, the file objects *stdin*, *stdout* - and *stderr* are opened in text mode with the specified encoding and - *errors*, as described above in :ref:`frequently-used-arguments`. If - *universal_newlines* is ``True``, they are opened in text mode with default - encoding. Otherwise, they are opened as binary streams. + If *encoding* or *errors* are specified, or *text* is true, the file objects + *stdin*, *stdout* and *stderr* are opened in text mode with the specified + encoding and *errors*, as described above in :ref:`frequently-used-arguments`. + The *universal_newlines* argument is equivalent to *text* and is provided + for backwards compatibility. By default, file objects are opened in binary mode. .. versionadded:: 3.6 *encoding* and *errors* were added. + .. versionadded:: 3.7 + *text* was added as a more readable alias for *universal_newlines*. + If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is passed to the underlying ``CreateProcess`` function. *creationflags*, if given, can be one or more of the following flags: -- 2.40.0