gh-47798: run_pipeline: reject shell=True and executable=

The pipeline replaces the shell; per-stage shell would re-introduce the
quoting and injection surface this API exists to avoid.  A future
Stage() wrapper is the place for the rare stage that needs it.

Author: gpshead

Doc/library/subprocess.rst

@@ -271,9 +271,9 @@ underlying :class:`Popen` interface can be used directly.
    Wait for all commands to complete, then return a :class:`CompletedPipeline`
    instance.
 
-   Each positional argument should be a command (a list of strings, or a string
-   if ``shell=True``) to execute. The standard output of each command is
-   connected to the standard input of the next command in the pipeline.
+   Each positional argument should be a command (a sequence of strings) to
+   execute. The standard output of each command is connected to the standard
+   input of the next command in the pipeline.
 
    This function requires at least two commands. For a single command, use
    :func:`run` instead.
@@ -341,7 +341,10 @@ underlying :class:`Popen` interface can be used directly.
    children (unlike a shell, which can give each command its own fd set).
    ``close_fds=False`` is rejected because inherited copies of the
    inter-process pipe ends in sibling children would prevent EOF from being
-   signaled and cause deadlocks.
+   signaled and cause deadlocks. ``shell=True`` and ``executable=`` are also
+   rejected: the pipeline itself replaces the shell, and per-stage shell
+   interpretation would re-introduce the quoting and injection surface this
+   function exists to avoid.
 
    Examples::
 
@@ -397,8 +400,7 @@ underlying :class:`Popen` interface can be used directly.
 
    .. attribute:: commands
 
-      The list of commands used to launch the pipeline. Each command is a list
-      of strings (or a string if ``shell=True`` was used).
+      The list of commands used to launch the pipeline.
 
    .. attribute:: returncodes
 

Lib/subprocess.py

@@ -962,15 +962,14 @@ def run(*popenargs,
 
 # Future extension point: an opt-in Stage(cmd, **overrides) wrapper could
 # be accepted in place of a bare command to allow per-stage overrides
-# (e.g. stderr=STDOUT, pass_fds, env, cwd) for shell-pipeline-like
-# topologies.
+# (e.g. stderr, shell, env) for shell-pipeline-like topologies.
 def run_pipeline(*commands, input=None, capture_output=False, timeout=None,
                  check=False, **kwargs):
     """Run a pipeline of commands connected via pipes.
 
-    Each positional argument should be a command (list of strings or a string
-    if shell=True) to execute. The stdout of each command is connected to the
-    stdin of the next command in the pipeline, similar to shell pipelines.
+    Each positional argument should be a command (a sequence of strings) to
+    execute. The stdout of each command is connected to the stdin of the next
+    command in the pipeline, similar to shell pipelines.
 
     Returns a CompletedPipeline instance with attributes commands, returncodes,
     stdout, and stderr. By default, stdout and stderr are not captured, and
@@ -1032,6 +1031,14 @@ def run_pipeline(*commands, input=None, capture_output=False, timeout=None,
             'close_fds=False is not supported by run_pipeline; '
             'inherited pipe ends would prevent EOF signaling between commands')
 
+    if kwargs.get('shell'):
+        raise ValueError(
+            'shell=True is not supported by run_pipeline; the pipeline itself '
+            'replaces the shell.  Pass each stage as an argv sequence.')
+    if kwargs.get('executable') is not None:
+        raise ValueError(
+            'executable= is not supported by run_pipeline')
+
     stderr_arg = kwargs.pop('stderr', None)
     capture_stderr = capture_output or (stderr_arg is PIPE)
 

Lib/test/test_subprocess.py

@@ -2588,16 +2588,25 @@ def test_pipeline_error_repr(self):
         self.assertIn('echo', r)
         self.assertIn('false', r)
 
-    @unittest.skipIf(mswindows, "POSIX shell-specific")
-    def test_pipeline_shell_true(self):
-        """shell=True forwards each command to the shell."""
-        result = subprocess.run_pipeline(
-            'echo hello world',
-            'tr a-z A-Z',
-            shell=True, capture_output=True, text=True,
-        )
-        self.assertEqual(result.stdout.strip(), 'HELLO WORLD')
-        self.assertEqual(result.returncodes, [0, 0])
+    def test_pipeline_shell_rejected(self):
+        """shell=True is rejected; the pipeline replaces the shell."""
+        with self.assertRaises(ValueError) as cm:
+            subprocess.run_pipeline(
+                'echo hello world',
+                'tr a-z A-Z',
+                shell=True, capture_output=True,
+            )
+        self.assertIn('shell=True', str(cm.exception))
+
+    def test_pipeline_executable_rejected(self):
+        """executable= is rejected (only meaningful with shell=)."""
+        with self.assertRaises(ValueError) as cm:
+            subprocess.run_pipeline(
+                [sys.executable, '-c', 'pass'],
+                [sys.executable, '-c', 'pass'],
+                executable=sys.executable,
+            )
+        self.assertIn('executable', str(cm.exception))
 
     def test_pipeline_env(self):
         """env= is propagated to every command in the pipeline."""