gh-157127: Reword the argparse mutually exclusive group error message

[lazerg]

When a required mutually exclusive group is not satisfied, argparse joins the
argument names with a plain space:

error: one of the arguments --stdout repository is required

With a positional in the group this reads as broken grammar, since nothing
separates one name from the next.

The error for missing required arguments a few lines above in
_parse_known_args() puts its names at the end of the sentence and joins them
with ', '. This makes the mutually exclusive group error do the same:

error: one of the following arguments is required: --stdout, repository

The doc example and the three affected test assertions are updated to match.

Fixes #157127

• Issue: argparse exclusive argument group error unintelligible #157127

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34761806 | 📁 Comparing 8dfd696 against main (23180c5)

  🔍 Preview build  

102 files changed · + 8 added · ± 94 modified

+ Added

• builtins/constants.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/index.html
• builtins/stdtypes.html
• builtins/threadsafety.html
• builtins/time-complexity.html
• library/tkinter.dialogs.html

± Modified

• glossary.html
• index.html
• license.html
• c-api/bytearray.html
• c-api/bytes.html
• c-api/complex.html
• c-api/hash.html
• c-api/init_config.html
• c-api/interp-lifecycle.html
• c-api/module.html
• and 84 more...

[picnixz]

I suggest to reweite the error message as follows: "one of the following arguments is required: arg1, arg2, arg3".

Otherwise could we have some examples of what other CLIs in other packages format such errors (if any?) it would be good to take inspiration from them when possible

[lazerg]

@picnixz Reworded in 3f7606e:

PROG: error: one of the following arguments is required: --foo, --bar

It now matches the error argparse raises a few lines above for plain required arguments, the following arguments are required: --foo, --bar, so the two read the same way.

For the other question, here is how three CLIs I checked format it:

• Cobra (docker, kubectl, gh): at least one of the flags in the group [--foo --bar] is required
• clap (Rust): the following required arguments were not provided:, then <--foo|--bar> on the next line
• argparse itself, non-exclusive case: the following arguments are required: --foo, --bar

All three put the names at the end and keep a visible separator between them. Brackets, pipes or commas, but never a bare space. The new message follows that.

[savannahostrowski]

Hmm, I agree that the new message is clearer, especially for groups containing a positional, but I’m slightly concerned about the compatibility impact. The existing wording is documented and has existed since argparse was added in 2010. A quick GitHub scan found downstream projects with exact-string assertions, as well as translation catalogs containing the existing message ID.

That said, since this would land early in the 3.16 development cycle, I think we have enough time to try it and receive feedback before the release.