gh-119670: Add 'always' keyword argument to shlex.quote

Doc/library/shlex.rst

@@ -49,12 +49,21 @@ The :mod:`shlex` module defines the following functions:
    .. versionadded:: 3.8
 
 
-.. function:: quote(s)
+.. function:: quote(s, *, always=False)
 
    Return a shell-escaped version of the string *s*.  The returned value is a
    string that can safely be used as one token in a shell command line, for
    cases where you cannot use a list.
 
+   If the *always* keyword argument is set to ``True`` then the string *s*
+   will always be escaped, even in the absence of special characters. This is
+   nice for uniformity, for example when escaping a list of strings.
+
+      >>> from shlex import quote
+      >>> strs = ['escape', 'all of', 'us']
+      >>> [quote(s, always=True) for s in strs]
+      ["'escape'", "'all of'", "'us'"]
+
    .. _shlex-quote-warning:
 
    .. warning::
@@ -98,6 +107,9 @@ The :mod:`shlex` module defines the following functions:
 
    .. versionadded:: 3.3
 
+   .. versionchanged:: 3.14
+      Added the *always* parameter.
+
 The :mod:`shlex` module defines the following class:
 
 

Doc/whatsnew/3.14.rst

@@ -183,6 +183,12 @@ ___
   Use :func:`pty.openpty` instead.
   (Contributed by Nikita Sobolev in :gh:`118824`.)
 
+shlex
+-----
+
+* Add keyword-only argument of *always* to :func:`shlex.quote` for forcing
+  the escaping of the string passed to it.
+
 sqlite3
 -------
 

Lib/shlex.py

@@ -320,17 +320,17 @@ def join(split_command):
 
 _find_unsafe = re.compile(r'[^\w@%+=:,./-]', re.ASCII).search
 
-def quote(s):
+def quote(s, *, always=False):
     """Return a shell-escaped version of the string *s*."""
     if not s:
         return "''"
-    if _find_unsafe(s) is None:
-        return s
 
-    # use single quotes, and put single quotes into double quotes
-    # the string $'b is then quoted as '$'"'"'b'
-    return "'" + s.replace("'", "'\"'\"'") + "'"
+    if always or _find_unsafe(s) is not None:
+        # use single quotes, and put single quotes into double quotes
+        # the string $'b is then quoted as '$'"'"'b'
+        return "'" + s.replace("'", "'\"'\"'") + "'"
 
+    return s
 
 def _print_tokens(lexer):
     while tt := lexer.get_token():

Lib/test/test_shlex.py

@@ -337,6 +337,18 @@ def testQuote(self):
             self.assertEqual(shlex.quote("test%s'name'" % u),
                              "'test%s'\"'\"'name'\"'\"''" % u)
 
+    def testQuoteAlways(self):
+        strs = ['hello', 'to the', 'world', 'escape me', 'no-escape-needed']
+
+        # guarantee escaping all strings
+        strs_always_escaped = [shlex.quote(s, always=True) for s in strs]
+        self.assertTrue(all(s.startswith("'") for s in strs_always_escaped))
+
+        # just escape when necessary ('to the', 'escape me')
+        strs_necessary_escaped = [shlex.quote(s, always=False) for s in strs]
+        self.assertFalse(all(s.startswith("'")
+                             for s in strs_necessary_escaped))
+
     def testJoin(self):
         for split_command, command in [
             (['a ', 'b'], "'a ' b"),

Misc/NEWS.d/next/Library/2024-05-28-17-24-19.gh-issue-119670.P4J3vX.rst

@@ -0,0 +1,2 @@
+:func:`shlex.quote` now has an *always* keyword argument for forcing
+the escaping of the string passed to it