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

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 force keyword argument #119670

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

@vstinner pong 😅

Thanks!

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

Looks ready (for review again?) to me 😎

LGTM.

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

Minor tweaks but please add more tets with quotes inside.

Please avoid force-pushing. It's extremely hard to make reviews otherwise.

Sorry for the force pushes but the 'commit suggestions' commits on GitHub came through as CRLF formatted instead of LF. I don't know if that's a GitHub Microsoft issue, or your IDE settings, or I need to git config autocrlf but hey I got there in the end.

$ git log d000ccd...e3d9b05 is what has changed, addressing the review. The only change I disagreed with is the wording of the .. versionadded. The existing one seems to be worded more similarly to the others.

I think it's a GH issue because other reviews had the same issue...

Ready

@picnixz 30 day courtesy ping 👀

@jb2170: Please move the "What's New in Python" documentation as I explained in my comment below.

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`

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>

…view Show off the default behavior as `force=False`

Try not to use don't and we're and should've etc apostrophes.

Add test to ensure string with single quote inside it (without which the string wouldn't need quoting) is quoted even though `force=False`.

Documentation build overview

📚 cpython-previews | 🛠️ Build #32972607 | 📁 Comparing 7781ca0 against main (0b9146e)

🔍 Preview build

161 files changed · + 5 added · ± 156 modified

+ Added

± Modified

Really sorry for the rebase ffs, worst PR ever! 😭
I normally rebase instead of merge. I thought merging main would cause this exact issue but nope the other way round
$ git range-diff d206d42..7fa8a7a 6453065..a030aa4 shows everything is the same before and after the rebase, there's nothing sneaky going on

@johnslavik's review has been addressed.

Merged. Thanks for your contribution.

…ython#148846) 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. Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

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

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

shlex.quote: Add force keyword argument #119670

Closed

jb2170 mentioned this pull request Apr 21, 2026

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

Closed

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

johnslavik previously 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

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

jb2170 force-pushed the shlex-quote-force branch from a9e06cd to e7bf496 Compare April 28, 2026 07:44

jb2170 force-pushed the shlex-quote-force branch from e7bf496 to e3d9b05 Compare April 28, 2026 08:38

picnixz self-requested a review April 28, 2026 15:30

picnixz reviewed May 28, 2026

View reviewed changes

Comment thread Lib/shlex.py Outdated

jb2170 requested a review from picnixz June 3, 2026 01:00

picnixz approved these changes Jun 3, 2026

View reviewed changes

vstinner reviewed Jun 3, 2026

View reviewed changes

Comment thread Doc/whatsnew/3.15.rst Outdated

jb2170 added 3 commits June 3, 2026 13:59

shlex: Implement force parameter behavior for shlex.quote

6a51ccb

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

36abcf2

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

3b493e6

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.

jb2170 and others added 13 commits June 3, 2026 13:59

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

ca02f2b

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

e2eed91

…to `shlex.force`

Add whatsnew entry for shlex.quote gaining force kwarg

92c680f

shlex.quote: improve formatting

cf31d96

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

shlex.quote tests: Remove comments

2c45177

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

ef4a412

Missed from last commit

shlex tests: Remove misplaced comment

a29eabb

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

Tweak whatsnew and news entry for shlex.quote based on picnixz's review

71b2a42

Tweak shlex.quote docs and doctring based on picnixz's review

2cb6dbf

Tweak shlex.quote docs example of using force based on picnixz's re…

6429221

…view Show off the default behavior as `force=False`

Tweak shlex.quote comments based on picnixz's review

a753be2

Try not to use don't and we're and should've etc apostrophes.

Tweak shlex.quote tests based on picnixz's review

e922280

Add test to ensure string with single quote inside it (without which the string wouldn't need quoting) is quoted even though `force=False`.

shlex.quote: Move comment above if statement

a030aa4

jb2170 force-pushed the shlex-quote-force branch from 7fa8a7a to a030aa4 Compare June 3, 2026 12:59

Move shlex.quote whatsnew entry from 3.15 to 3.16

7781ca0

jb2170 requested a review from johnslavik June 3, 2026 13:36

vstinner merged commit ae507e3 into python:main Jun 4, 2026
52 checks passed

bedevere-app Bot removed the awaiting merge label Jun 4, 2026

jb2170 deleted the shlex-quote-force branch June 4, 2026 10:59

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

Repository navigation

gh-119670: Add force keyword only argument to shlex.quote - #148846

gh-119670: Add force keyword only argument to shlex.quote#148846vstinner merged 17 commits intopython:mainpython/cpython:mainfrom jb2170:shlex-quote-forcejb2170/cpython:shlex-quote-forceCopy head branch name to clipboard

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

picnixz commented Apr 28, 2026

Uh oh!

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

Uh oh!

Uh oh!

picnixz commented Apr 28, 2026

Uh oh!

jb2170 commented Apr 28, 2026

Uh oh!

jb2170 commented May 28, 2026

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

read-the-docs-community Bot commented Jun 3, 2026

Documentation build overview

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

vstinner commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gh-119670: Add force keyword only argument to shlex.quote#148846
vstinner merged 17 commits into
python:mainfrom
jb2170:shlex-quote-force

jb2170 commented Apr 21, 2026 •
edited
Loading

johnslavik commented Apr 22, 2026 •
edited
Loading

jb2170 commented Apr 28, 2026 •
edited
Loading

jb2170 commented Jun 3, 2026 •
edited
Loading