Skip to content

gh-130750: Fix invalid choices documentation #130751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

TheDSCPL
Copy link

@TheDSCPL TheDSCPL commented Mar 2, 2025

@ghost
Copy link

ghost commented Mar 2, 2025

All commit authors signed the Contributor License Agreement.
CLA signed

@@ -599,7 +599,7 @@ are strings::
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
... help='an integer for the accumulator')
>>> parser.parse_args(['--action', 'sumn', 1, 2, 3])
tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant 'sum'? (choose from 'sum', 'max')
tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant 'sum'? (choose from sum, max)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, can you please calrify why do you want to change this?
Right now this reads perfectly fine to me: 'sum' and 'max' are strings, defined as choices=['sum', 'max']

Copy link
Member

@picnixz picnixz Mar 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we have a small discrepency here:

cpython/Lib/argparse.py

Lines 2584 to 2587 in c9932a9

if value not in choices:
args = {'value': str(value),
'choices': ', '.join(map(str, action.choices))}
msg = _('invalid choice: %(value)r (choose from %(choices)s)')

Technically, we shouldn't have quotes because we do map(str, ...) and not map(repr, ...). However!!! on 3.12.6 (not latest one):

Python 3.12.6 (main, Sep 13 2024, 13:53:54) [GCC 7.5.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import argparse
>>> p = argparse.ArgumentParser()
>>> p.add_argument('a', choices=["a", "b"])
_StoreAction(option_strings=[], dest='a', nargs=None, const=None, default=None, type=None, choices=['a', 'b'], required=True, help=None, metavar=None)
>>> p.parse_args(['1234'])
usage: [-h] {a,b}
: error: argument a: invalid choice: '1234' (choose from 'a', 'b')

Whereas on main or latest 3.12:

Python 3.14.0a5+ (heads/fix/repl/show-source-129098-dirty:8eb3cca8f76, Mar  2 2025, 12:02:03) [GCC 7.5.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import argparse
>>> p = argparse.ArgumentParser()
>>> p.add_argument('a', choices=["a", "b"])
_StoreAction(option_strings=[], dest='a', nargs=None, const=None, default=None, type=None, choices=['a', 'b'], required=True, help=None, metavar=None, deprecated=False)
>>> p.parse_args(['1234'])
usage: python -m _pyrepl [-h] {a,b}
python -m _pyrepl: error: argument a: invalid choice: '1234' (choose from a, b)

We have indeed a discrepency. We actually changed this in 21524ee, so it was an omission during the backport. But I'm not sure whether str is actually better.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, interesting. Tbh, I prefer the readability of the explicit string, even though it's obvious in the example in question. It reads strangely to me that we'd have the invalid choice with quotes and then the supported choices without quotes. Consistency is good :)

Copy link
Member

@picnixz picnixz Mar 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the issue with the docs is that we're using 1-char choices which make the output slightly disturbing. I would suggest using words such as foo and bar to make it more readable.

However, I personally find it better to use repr() because it also highlights what's being expected. It's quite common to have error messages that contain the repr of the invalid argument instead of its str() so I wouldn't change that part.

Thus, my personal choice would be to use the repr() for the choices as well, though for enumeration choices, I don't know how it renders (for enum members the str() is usually better I think?)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have any preference for this. I was building a package from source that depended on cpython and had a test failing due to the expected stderr being different than the actual output because of the quotation marks. Upon looking into your code and documentation, I noticed the discrepancy and decided to create this PR to make the docs match the actual output. If you'd prefer to go back to the quoted version, then please close this PR and change the code to include the quotes again. Changing the output is a breaking change because tests that are expected to fail usually rely on the error message.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, as I mentioned in the issue for this PR, even though argparse doesn't quote anymore, optparse still does, so it's inconsistent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting review docs Documentation in the Doc dir skip news
Projects
Status: Todo
Development

Successfully merging this pull request may close these issues.

Wrong output example on invalid options documentation
4 participants