bpo-47222: Allow pass-thru with stdout/stderr capture (GH-91378)

pprindeville · pprindeville · commit 7f1ef61e4dae · 2023-04-07T15:17:25.000-06:00
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
@@ -699,6 +699,13 @@ functions.
       The ``read_stdout_callback`` and ``read_stderr_callback`` parameters
       were added.
 
+   Add a tee'ing handler that may be accessed by calling
+   ``tee_pipe_to(handle)``. It takes the handle of the file to clone to
+   as an argument, such as *sys.stdout* or *sys.stderr*.
+
+   .. versionadded: 3.11
+      The ``tee_pipe_to()`` method was added.
+
    Popen objects are supported as context managers via the :keyword:`with` statement:
    on exit, standard file descriptors are closed, and the process is waited for.
    ::
diff --git a/Lib/subprocess.py b/Lib/subprocess.py
@@ -1325,6 +1325,12 @@ def _close_pipe_fds(self,
         # Prevent a double close of these handles/fds from __init__ on error.
         self._closed_child_pipe_fds = True
 
+    def tee_pipe_to(output_fh):
+        def _tee_handler(self, buffer, data):
+            buffer.append(data)
+            output_fh.write(data)
+        return _tee_handler
+
     def _read_common_handler(self, buffer, data):
         """Default handler for read_stdout_callback and read_stderr_callback."""
         buffer.append(data)
diff --git a/Lib/test/test_subprocess.py b/Lib/test/test_subprocess.py
@@ -340,6 +340,36 @@ def test_stdout_none(self):
             self.assertEqual(out, b'test_stdout_none' + NEWLINE)
             self.assertEqual(err, b'')
 
+    def test_stdout_tee(self):
+        # .stdout is PIPE when not redirected, and the child's stdout will
+        # be inherited from the parent.  In order to test this we run a
+        # subprocess in a subprocess:
+        # this_test
+        #   \-- subprocess created by this test (parent)
+        #          \-- subprocess created by the parent subprocess (child)
+        # The parent doesn't specify stdout, so the child will use the
+        # parent's stdout.  This test checks that the message printed by the
+        # child goes to the parent stdout.  The parent also checks that the
+        # child's stdout is cloned.  See #47222.
+        code = ('import sys\n'
+                'from subprocess import Popen, PIPE\n'
+                'with Popen([sys.executable, "-c", "print(\'test_stdout_teed\')"],\n'
+                '            stdout=PIPE, stderr=PIPE, read_stdout_callback=Popen.tee_pipe_to(sys.stdout.buffer)) as p:\n'
+                '    out, err = p.communicate()\n'
+                '    assert p.returncode == 0\n'
+                '    assert out.rstrip() == b\'test_stdout_teed\'\n'
+                '    assert err == b\'\'\n'
+                )
+        with subprocess.Popen([sys.executable, "-c", code],
+                              stdout=subprocess.PIPE,
+                              stderr=subprocess.PIPE) as p:
+            self.addCleanup(p.stdout.close)
+            self.addCleanup(p.stderr.close)
+            out, err = p.communicate()
+            self.assertEqual(p.returncode, 0, err.decode())
+            self.assertEqual(out, b'test_stdout_teed' + NEWLINE)
+            self.assertEqual(err, b'')
+
     def test_stderr_none(self):
         # .stderr is None when not redirected
         with subprocess.Popen([sys.executable, "-c", 'print("banana")'],
diff --git a/Misc/NEWS.d/next/Library/2022-04-05-22-15-55.bpo-47222.I5CLHq.rst b/Misc/NEWS.d/next/Library/2022-04-05-22-15-55.bpo-47222.I5CLHq.rst
@@ -1 +1,3 @@
 In the :mod:`subprocess` :class:`Popen`, factor the read callback handler for the ``PIPE`` file descriptors into its own function.  Also add class variables pointing to the *stdout* and *stderr* read handlers.  Lastly, add constructor variable ``read_stdout_callback`` and ``read_stderr_callback`` to allow overriding the handler with a user-supplied function.
+
+Also add the method ``tee_pipe_to(handle)`` to this class, which indicates that output on the pipes should be copied to the parent's buffers, as well as being cloned onto the named *handle*.

Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
`1`	`1`	In the :mod:`subprocess` :class:`Popen`, factor the read callback handler for the ``PIPE`` file descriptors into its own function. Also add class variables pointing to the stdout and stderr read handlers. Lastly, add constructor variable ``read_stdout_callback`` and ``read_stderr_callback`` to allow overriding the handler with a user-supplied function.
	`2`	`+`
	`3`	+Also add the method ``tee_pipe_to(handle)`` to this class, which indicates that output on the pipes should be copied to the parent's buffers, as well as being cloned onto the named handle.