gh-142346: Fix usage formatting for mutually exclusive groups in argparse #142381

serhiy-storchaka · 2025-12-07T15:41:29Z

Support groups preceded by positional arguments or followed or intermixed with other optional arguments. Support empty groups.

Issue: Support of mutually exclusive groups in the argparse help is very limited #142346

…n argparse Support groups preceded by positional arguments or followed or intermixed with other optional arguments. Support empty groups.

serhiy-storchaka

The code of _get_actions_usage_parts() was completely rewritten, besides formatting and colorizing separate arguments. It now uses completely different algorithm.

It does not support groups with multiple positional arguments -- only the first of them is shown included in the group. I am not sure that it is worth to spent effort on supporting the case which AFAIK does not work anyway. We can do this if we will get bug reports.

serhiy-storchaka · 2025-12-07T15:48:51Z

Lib/test/test_argparse.py

        group = parser.add_mutually_exclusive_group()
-        with self.assertRaises(ValueError):
-            parser.parse_args(['-h'])
+        self.assertEqual(parser.format_usage(), 'usage: PROG [-h]\n')


ValueError was only raised to hide IndexError. Now this is not needed, empty groups are simply ignored (as well as groups with all suppressed arguments).

serhiy-storchaka · 2025-12-07T15:50:47Z

Lib/test/test_argparse.py

+        ('-a', NS(a=True, b=False, c=False, x=False, y=False, z=False)),
+        ('-b', NS(a=False, b=True, c=False, x=False, y=False, z=False)),
+        ('-c', NS(a=False, b=False, c=True, x=False, y=False, z=False)),
+        ('-a -x', NS(a=True, b=False, c=False, x=True, y=False, z=False)),
+        ('-y -b', NS(a=False, b=True, c=False, x=False, y=True, z=False)),
+        ('-x -y -c', NS(a=False, b=False, c=True, x=True, y=True, z=False)),
    ]
    successes_when_not_required = [
-        ('', NS(a=False, b=False, c=False, x=False, y=False)),
-        ('-x', NS(a=False, b=False, c=False, x=True, y=False)),
-        ('-y', NS(a=False, b=False, c=False, x=False, y=True)),
+        ('', NS(a=False, b=False, c=False, x=False, y=False, z=False)),
+        ('-x', NS(a=False, b=False, c=False, x=True, y=False, z=False)),
+        ('-y', NS(a=False, b=False, c=False, x=False, y=True, z=False)),


All these changes are not important. They are just the result of adding yet one argument -z (to increase coverage), no other changes.

serhiy-storchaka · 2025-12-07T15:52:04Z

Lib/test/test_argparse.py

+    usage_when_not_required = '''\
+        usage: PROG [-h] [-x] [-a | -b | -c] [-y] [-z]
+        '''
+    usage_when_required = '''\
+        usage: PROG [-h] [-x] (-a | -b | -c) [-y] [-z]


The old result was incorrect (group was not formatted).

serhiy-storchaka · 2025-12-07T15:52:49Z

Lib/test/test_argparse.py

+        ('X A', NS(a='A', b=False, c=False, x='X', y=False, z=False)),
+        ('X -b', NS(a=None, b=True, c=False, x='X', y=False, z=False)),
+        ('X -c', NS(a=None, b=False, c=True, x='X', y=False, z=False)),
+        ('X A -y', NS(a='A', b=False, c=False, x='X', y=True, z=False)),
+        ('X -y -b', NS(a=None, b=True, c=False, x='X', y=True, z=False)),


Should be ignored as above.

serhiy-storchaka · 2025-12-07T15:53:43Z

Lib/test/test_argparse.py

+    usage_when_not_required = '''\
+        usage: PROG [-h] [-y] [-z] x [-b | -c | a]
+        '''
+    usage_when_required = '''\
+        usage: PROG [-h] [-y] [-z] x (-b | -c | a)


Yest one incorrect result in old tests.

serhiy-storchaka · 2025-12-07T15:55:10Z

Lib/test/test_argparse.py

+        usage: PROG [-h]
+                    [-v | -q | -x [EXTRA_LONG_OPTION_NAME] |
+                    -y [YET_ANOTHER_LONG_OPTION] | positional]


The line break is now forced not before the first positional argument, but before the first group containing a positional argument.

savannahostrowski

LGTM. Verified the new behavior against various edge cases (empty groups, non-contiguous members, intermixed optionals/positionals) - all work as expected! Thanks Serhiy, this makes the algorithm easier to follow.

miss-islington-app · 2025-12-07T19:36:05Z

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

…n argparse (pythonGH-142381) Support groups preceded by positional arguments or followed or intermixed with other optional arguments. Support empty groups. (cherry picked from commit 1db9f56) Co-authored-by: Serhiy Storchaka <[email protected]>

miss-islington-app · 2025-12-07T19:36:19Z

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 1db9f56bff5bbb0292b131ea8a928612acb7ec16 3.13

bedevere-app · 2025-12-07T19:36:22Z

GH-142385 is a backport of this pull request to the 3.14 branch.

savannahostrowski · 2025-12-07T19:39:32Z

Wondering if backporting is worth the risk - this changes user-visible output which could break tests.

…in argparse (GH-142381) (GH-142385) Support groups preceded by positional arguments or followed or intermixed with other optional arguments. Support empty groups. (cherry picked from commit 1db9f56) Co-authored-by: Serhiy Storchaka <[email protected]>

serhiy-storchaka · 2025-12-07T20:07:26Z

This algorithm does not support nested mutually exclusive groups (removed in 3.14), so it cannot be backported to 3.13.

It changes the output in the same way as previous bugfixes. For example, it changes the position of the forced line break for a group containing positional argument, but before #142312 the output for such group was incorrect. If the output was correct, it should not be changed.

bedevere-bot · 2025-12-07T20:24:38Z

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot s390x Fedora Stable LTO + PGO 3.x (tier-3) has failed when building commit 1db9f56.

What do you need to do:

Don't panic.
Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/1627/builds/1686) and take a look at the build logs.
Check if the failure is related to this commit (1db9f56) or if it is a false positive.
If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/1627/builds/1686

Failed tests:

test_profiling

Failed subtests:

test_sampling_with_collapsed_export - test.test_profiling.test_sampling_profiler.test_integration.TestSampleProfilerIntegration.test_sampling_with_collapsed_export

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.x.cstratak-fedora-stable-s390x.lto-pgo/build/Lib/test/test_profiling/test_sampling_profiler/test_integration.py", line 525, in test_sampling_with_collapsed_export
    self.assertIn(":", part)
    ~~~~~~~~~~~~~^^^^^^^^^^^
AssertionError: ':' not found in '<GC>'

pythongh-142346: Fix usage formatting for mutually exclusive groups i…

2699561

…n argparse Support groups preceded by positional arguments or followed or intermixed with other optional arguments. Support empty groups.

serhiy-storchaka requested a review from savannahostrowski December 7, 2025 15:41

bedevere-app bot added the awaiting core review label Dec 7, 2025

bedevere-app bot mentioned this pull request Dec 7, 2025

Support of mutually exclusive groups in the argparse help is very limited #142346

Open

serhiy-storchaka commented Dec 7, 2025

View reviewed changes

savannahostrowski approved these changes Dec 7, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Dec 7, 2025

serhiy-storchaka added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Dec 7, 2025

serhiy-storchaka merged commit 1db9f56 into python:main Dec 7, 2025
56 checks passed

bedevere-app bot removed the awaiting merge label Dec 7, 2025

serhiy-storchaka deleted the argparse-help-mutually-exclusive-group branch December 7, 2025 19:36

miss-islington-app bot assigned serhiy-storchaka Dec 7, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Dec 7, 2025

serhiy-storchaka removed the needs backport to 3.13 bugs and security fixes label Dec 7, 2025

Uh oh!

gh-142346: Fix usage formatting for mutually exclusive groups in argparse #142381

gh-142346: Fix usage formatting for mutually exclusive groups in argparse #142381

Conversation

serhiy-storchaka commented Dec 7, 2025 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Dec 7, 2025

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Dec 7, 2025

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Dec 7, 2025

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Dec 7, 2025

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Dec 7, 2025

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Dec 7, 2025

Choose a reason for hiding this comment

Uh oh!

savannahostrowski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app bot commented Dec 7, 2025

Uh oh!

miss-islington-app bot commented Dec 7, 2025

Uh oh!

bedevere-app bot commented Dec 7, 2025

Uh oh!

savannahostrowski commented Dec 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

serhiy-storchaka commented Dec 7, 2025

Uh oh!

bedevere-bot commented Dec 7, 2025

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

serhiy-storchaka commented Dec 7, 2025 •

edited by bedevere-app bot

Loading

savannahostrowski commented Dec 7, 2025 •

edited

Loading