From 3fa8fe7177bb941aa60ecaf14d1fa1750a26f674 Mon Sep 17 00:00:00 2001
From: richardhob <richardhob@gmail.com>
Date: Thu, 19 Jan 2023 23:56:13 -0800
Subject: [PATCH] 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
---
 Doc/library/subprocess.rst                    | 32 +++++++++----------
 Misc/ACKS                                     |  1 +
 ...2-06-19-22-04-47.gh-issue-88324.GHhSQ1.rst |  3 ++
 3 files changed, 19 insertions(+), 17 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2022-06-19-22-04-47.gh-issue-88324.GHhSQ1.rst

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index e4e38e93368..785251afdf2 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 a51658d79fa..768034516d3 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 00000000000..6c8d192daa7
--- /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.