pythongh-120952: Add subprocess.shell() function

Doc/library/subprocess.rst

@@ -264,6 +264,18 @@ underlying :class:`Popen` interface can be used directly.
         *stdout* and *stderr* attributes added
 
 
+.. function:: shell(cmd, **kwargs)
+
+   Run a shell command. Wait for command to complete, then return a
+   :class:`CompletedProcess` instance.
+
+   See the :func:`run` function documentation for optional parameters.
+
+   Read the `Security Considerations`_ section before using this function.
+
+   .. versionadded:: 3.14
+
+
 .. _frequently-used-arguments:
 
 Frequently Used Arguments
@@ -764,6 +776,9 @@ quoted appropriately to avoid
 vulnerabilities. On :ref:`some platforms <shlex-quote-warning>`, it is possible
 to use :func:`shlex.quote` for this escaping.
 
+The functions :func:`shell()` and :func:`getstatusoutput()` always use
+``shell=True``.
+
 On Windows, batch files (:file:`*.bat` or :file:`*.cmd`) may be launched by the
 operating system in a system shell regardless of the arguments passed to this
 library. This could result in arguments being parsed according to shell rules,

Doc/whatsnew/3.14.rst

@@ -110,6 +110,14 @@ pathlib
   another.
   (Contributed by Barney Gale in :gh:`73991`.)
 
+subprocess
+----------
+
+* Add :func:`subprocess.shell` function to run a shell command.
+  Read the :ref:`Security Considerations <subprocess-security>` section before
+  using this function.
+  (Contributed by Victor Stinner in :gh:`120952`.)
+
 symtable
 --------
 

Lib/subprocess.py

@@ -2221,3 +2221,16 @@ def kill(self):
             """Kill the process with SIGKILL
             """
             self.send_signal(signal.SIGKILL)
+
+
+def shell(cmd, **kwargs):
+    """
+    Run a shell command.
+
+    Read the Security Considerations section of the documentation before using
+    this function.
+    """
+    if not isinstance(cmd, (str, bytes)):
+        raise TypeError("cmd type must be str or bytes")
+
+    return run(cmd, shell=True, **kwargs)

Lib/test/test_subprocess.py

@@ -1824,6 +1824,25 @@ def test_encoding_warning(self):
         self.assertTrue(lines[0].startswith(b"<string>:2: EncodingWarning: "))
         self.assertTrue(lines[2].startswith(b"<string>:3: EncodingWarning: "))
 
+    def test_shell(self):
+        # Unicode command
+        proc = subprocess.shell("echo Python", stdout=subprocess.PIPE, text=True)
+        self.assertEqual(proc.returncode, 0)
+        self.assertEqual(proc.stdout.rstrip(), "Python")
+
+        # Bytes command
+        proc = subprocess.shell(b"echo Python", stdout=subprocess.PIPE, text=True)
+        self.assertEqual(proc.returncode, 0)
+        self.assertEqual(proc.stdout.rstrip(), "Python")
+
+        # cmd type must be str or bytes, not list
+        with self.assertRaises(TypeError):
+            subprocess.shell(["echo", "Python"])
+
+        # Passing shell=False is invalid
+        with self.assertRaises(TypeError):
+            subprocess.shell("echo Python", shell=False)
+
 
 def _get_test_grp_name():
     for name_group in ('staff', 'nogroup', 'grp', 'nobody', 'nfsnobody'):

Misc/NEWS.d/next/Library/2024-06-27-14-30-58.gh-issue-120952.nu6Ejc.rst

@@ -0,0 +1,3 @@
+Add :func:`subprocess.shell` function to run a shell command. Read the
+:ref:`Security Considerations <subprocess-security>` section before using
+this function. Patch by Victor Stinner.