gh-119670: Add `force` keyword only argument to `shlex.quote` by jb2170 · Pull Request #148846 · python/cpython

jb2170 · 2026-04-21T18:24:16Z

Closes #119670
Supersedes my out-of-date PR #119674

We use force instead of always as a word more consistent with other programming jargon (like in rm -f the f is for 'force') as discussed

Commits

ddbe3a5: Add base implementation.
0e722d6: Make shlex.quote's kwargs kwargs-only. Backwards compatible. There are propositions to add a single-quote-double-quote switch, which I'm ambivalent about, but to future-proof against hiccups of people passing force as a positional and it ending up being used as the wrong kwarg, we make the kwargs kwargs-only, eg like json.loads.
fd4af18: Add tests. I've tried to be pretty thorough. Their purposes are commented on.
78b6f3b: Update docs. Contains explanation and examples.
762999d: Add blurb entry.
2a301a5: Add whatsnew entry.

As mentioned I'm also going to open ~~an issue~~ a discussion thread about shlex.quote returning "''" for falsey non-str data. This PR and that discussion seem independent of each other, that is this PR doesn't need to be held back until that discussion is addressed.

Issue: shlex.quote: Add 'always' keyword argument #119670

📚 Documentation preview 📚: https://cpython-previews--148846.org.readthedocs.build/

There are propositions to add a single-quote-double-quote switch (pythongh-90630), so to avoid hiccups of people passing `force` as a positional and it being used for the single-double switch, we make kwargs kwargs-only.

Test special cases of strings that don't need quoting, do need quoting, do use `force`, don't use `force` etc. I've tried to be exhaustive.

…to `shlex.force`

jb2170 · 2026-04-21T22:27:12Z

@vstinner pong 😅

johnslavik

Thanks!

johnslavik · 2026-04-22T08:34:40Z

~~Hmm I also have a hunch that this might be worth calling out in What's New.~~ Nvm it's already there, great job 🚀

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

The comments for why these tests exist can always be found in the git history Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

Missed from last commit

Intended for another branch shlex-quote-typeerror Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

jb2170 · 2026-04-24T12:36:37Z

Looks ready (for review again?) to me 😎

vstinner

LGTM.

@picnixz: Do you want to double check? You reviewed the previous PR gh-119674.

picnixz

Minor tweaks but please add more tets with quotes inside.

picnixz · 2026-04-27T14:04:49Z

+   If *force* is :const:`True` then *s* will be quoted even if it is already
+   safe for a shell without being quoted.


Suggested change

If *force* is :const:`True` then *s* will be quoted even if it is already

safe for a shell without being quoted.

If *force* is :const:`True`, then *s* is unconditionally quoted,

even if it is already safe for a shell without being quoted.

picnixz · 2026-04-27T14:05:15Z

+
+      >>> from shlex import quote
+      >>> filenames = ['my first file', 'file2', 'file 3']
+      >>> filenames_some_escaped = [quote(f, force=False) for f in filenames]


Suggested change

>>> filenames_some_escaped = [quote(f, force=False) for f in filenames]

>>> filenames_some_escaped = [quote(f) for f in filenames]

picnixz · 2026-04-27T14:05:34Z

   .. versionadded:: 3.3

+   .. versionchanged:: next
+      The *force* keyword was added.


Suggested change

The *force* keyword was added.

Add the *force* parameter.

picnixz · 2026-04-27T14:06:50Z

+  * :func:`shlex.quote` has a new keyword-only parameter *force* that ensures
+    a string will always be quoted, even if it is already safe for a shell
+    without being quoted.


Suggested change

* :func:`shlex.quote` has a new keyword-only parameter *force* that ensures

a string will always be quoted, even if it is already safe for a shell

without being quoted.

* Add *force* to :func:`shlex.quote` to force quoting a string,

even if it is already safe for a shell without being quoted.

picnixz · 2026-04-27T14:07:24Z

+    If *force* is *True* then *s* will be quoted even if it is
+    already safe for a shell without being quoted.


Update the docstring with the updated doc I suggested as well.

picnixz · 2026-04-27T14:07:43Z

-    if s.isascii() and not s.encode().translate(None, delete=safe_chars):
+    if (not force
+        and s.isascii() and not s.encode().translate(None, delete=safe_chars)):
+        # No quoting is needed if we're not forcing quoting


Suggested change

# No quoting is needed if we're not forcing quoting

# No quoting is needed if we are not forcing quoting

picnixz · 2026-04-27T14:07:49Z

+    if (not force
+        and s.isascii() and not s.encode().translate(None, delete=safe_chars)):
+        # No quoting is needed if we're not forcing quoting
+        # and `s` is an ASCII string consisting only of `safe_chars`


Suggested change

# and `s` is an ASCII string consisting only of `safe_chars`

# and `s` is an ASCII string consisting only of `safe_chars`.

picnixz · 2026-04-27T14:08:12Z

        self.assertRaises(TypeError, shlex.quote, b"abc")

+    def testForceQuote(self):
+        self.assertEqual(shlex.quote("spam"), "spam")


Please add some tests where the input has quotes inside.

picnixz · 2026-04-27T14:08:36Z

@@ -0,0 +1,3 @@
+Add *force* keyword only argument to :func:`shlex.quote` to always quote the


Update the NEWS entry with the updated What's New as well.

jb2170 added 5 commits April 21, 2026 04:41

shlex: Implement force parameter behavior for shlex.quote

ddbe3a5

shlex: Make force a keyword only argument in shlex.quote

0e722d6

There are propositions to add a single-quote-double-quote switch (pythongh-90630), so to avoid hiccups of people passing `force` as a positional and it being used for the single-double switch, we make kwargs kwargs-only.

shlex tests: Add testForceQuote

fd4af18

Test special cases of strings that don't need quoting, do need quoting, do use `force`, don't use `force` etc. I've tried to be exhaustive.

shlex: Update documentation to mention shlex.quote's force kwarg

78b6f3b

Add blurb entry for pythongh-119670: Add force keyword only argument …

762999d

…to `shlex.force`

bedevere-app Bot added the awaiting review label Apr 21, 2026

bedevere-app Bot mentioned this pull request Apr 21, 2026

shlex.quote: Add 'always' keyword argument #119670

Open

jb2170 mentioned this pull request Apr 21, 2026

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

Closed

Add whatsnew entry for shlex.quote gaining force kwarg

2a301a5

jb2170 requested a review from AA-Turner as a code owner April 21, 2026 18:43

johnslavik requested changes Apr 22, 2026

View reviewed changes

Comment thread Lib/shlex.py Outdated

Comment thread Lib/test/test_shlex.py Outdated

Comment thread Lib/test/test_shlex.py Outdated

bedevere-app Bot added awaiting core review and removed awaiting review labels Apr 22, 2026

jb2170 and others added 4 commits April 22, 2026 18:59

shlex.quote: improve formatting

f470aa1

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

shlex.quote tests: Remove comments

5450159

The comments for why these tests exist can always be found in the git history Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

shlex.quote tests: Remove another comment

bcd8b63

Missed from last commit

shlex tests: Remove misplaced comment

d000ccd

Intended for another branch shlex-quote-typeerror Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

vstinner approved these changes Apr 27, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Apr 27, 2026

picnixz self-requested a review April 27, 2026 14:03

picnixz reviewed Apr 27, 2026

View reviewed changes

		If force is :const:`True` then s will be quoted even if it is already
		safe for a shell without being quoted.

	>>> filenames_some_escaped = [quote(f, force=False) for f in filenames]
	>>> filenames_some_escaped = [quote(f) for f in filenames]

		If force is True then s will be quoted even if it is
		already safe for a shell without being quoted.

	# No quoting is needed if we're not forcing quoting
	# No quoting is needed if we are not forcing quoting

	# and `s` is an ASCII string consisting only of `safe_chars`
	# and `s` is an ASCII string consisting only of `safe_chars`.

		@@ -0,0 +1,3 @@
		Add force keyword only argument to :func:`shlex.quote` to always quote the

Uh oh!

Conversation

jb2170 commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jb2170 commented Apr 21, 2026

Uh oh!

johnslavik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

johnslavik commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jb2170 commented Apr 24, 2026

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jb2170 commented Apr 21, 2026 •

edited

Loading

johnslavik commented Apr 22, 2026 •

edited

Loading