[Python-checkins] gh-88324: Clarify documentation for redirected stdout/stderr when using subprocess in Linux (#94035)

[gpshead]

https://github.com/python/cpython/commit/3fa8fe7177bb941aa60ecaf14d1fa1750a26f674
commit: 3fa8fe7177bb941aa60ecaf14d1fa1750a26f674
branch: main
author: richardhob <richardhob at gmail.com>
committer: gpshead <greg at krypto.org>
date: 2023-01-19T23:56:13-08:00
summary:

gh-88324: Clarify documentation for redirected stdout/stderr when using subprocess in Linux (#94035)

* Update description of stdout, stderr, and stdin.

Changes:
- Move the ``None`` option (which is default) to the front of the list
  of input options
- Move the ``None`` option description up to make the default behavior
  more clear (No redirection)
- Remove mention of Child File Descriptors from ``None`` option description

files:
A Misc/NEWS.d/next/Documentation/2022-06-19-22-04-47.gh-issue-88324.GHhSQ1.rst
M Doc/library/subprocess.rst
M Misc/ACKS

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index e4e38e933681..785251afdf26 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -270,15 +270,14 @@ default values. The arguments that are most commonly needed are:
 
    *stdin*, *stdout* and *stderr* specify the executed program's standard input,
    standard output and standard error file handles, respectively.  Valid values
-   are :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a positive
-   integer), an existing file object with a valid file descriptor, and ``None``.
-   :data:`PIPE` indicates that a new pipe to the child should be created.
-   :data:`DEVNULL` indicates that the special file :data:`os.devnull` will
-   be used.  With the default settings of ``None``, no redirection will occur;
-   the child's file handles will be inherited from the parent.
-   Additionally, *stderr* can be :data:`STDOUT`, which indicates that the
-   stderr data from the child process should be captured into the same file
-   handle as for *stdout*.
+   are ``None``, :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a
+   positive integer), and an existing :term:`file object` with a valid file
+   descriptor.  With the default settings of ``None``, no redirection will
+   occur.  :data:`PIPE` indicates that a new pipe to the child should be
+   created.  :data:`DEVNULL` indicates that the special file :data:`os.devnull`
+   will be used.  Additionally, *stderr* can be :data:`STDOUT`, which indicates
+   that the stderr data from the child process should be captured into the same
+   file handle as for *stdout*.
 
    .. index::
       single: universal newlines; subprocess module
@@ -490,15 +489,14 @@ functions.
 
    *stdin*, *stdout* and *stderr* specify the executed program's standard input,
    standard output and standard error file handles, respectively.  Valid values
-   are :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a positive
-   integer), an existing :term:`file object` with a valid file descriptor,
-   and ``None``.  :data:`PIPE` indicates that a new pipe to the child should
-   be created.  :data:`DEVNULL` indicates that the special file
-   :data:`os.devnull` will be used. With the default settings of ``None``,
-   no redirection will occur; the child's file handles will be inherited from
-   the parent.  Additionally, *stderr* can be :data:`STDOUT`, which indicates
+   are ``None``, :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a
+   positive integer), and an existing :term:`file object` with a valid file
+   descriptor.  With the default settings of ``None``, no redirection will
+   occur.  :data:`PIPE` indicates that a new pipe to the child should be
+   created.  :data:`DEVNULL` indicates that the special file :data:`os.devnull`
+   will be used.  Additionally, *stderr* can be :data:`STDOUT`, which indicates
    that the stderr data from the applications should be captured into the same
-   file handle as for stdout.
+   file handle as for *stdout*.
 
    If *preexec_fn* is set to a callable object, this object will be called in the
    child process just before the child is executed.
diff --git a/Misc/ACKS b/Misc/ACKS
index a51658d79fa1..768034516d32 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -747,6 +747,7 @@ Aaron Hill
 Joel Hillacre
 Richie Hindle
 Konrad Hinsen
+Richard Hoberecht
 David Hobley
 Tim Hochberg
 Benjamin Hodgson
diff --git a/Misc/NEWS.d/next/Documentation/2022-06-19-22-04-47.gh-issue-88324.GHhSQ1.rst b/Misc/NEWS.d/next/Documentation/2022-06-19-22-04-47.gh-issue-88324.GHhSQ1.rst
new file mode 100644
index 000000000000..6c8d192daa79
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-06-19-22-04-47.gh-issue-88324.GHhSQ1.rst
@@ -0,0 +1,3 @@
+Reword :mod:`subprocess` to emphasize default behavior of *stdin*, *stdout*,
+and *stderr* arguments. Remove inaccurate statement about child file handle
+inheritance.