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.

Sign up for GitHub

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
Open

gh-130750: Fix invalid choices documentation #130751

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Doc/library/argparse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 •
edited
Loading

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 •
edited
Loading

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.


If you're writing code that needs to be compatible with older Python versions
and want to opportunistically use ``suggest_on_error`` when it's available, you
Expand Down Expand Up @@ -1121,8 +1121,8 @@ if the argument was not one of the acceptable values::
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')
game.py: error: argument move: invalid choice: 'fire' (choose from rock,
paper, scissors)

Note that inclusion in the *choices* sequence is checked after any type_
conversions have been performed, so the type of the objects in the *choices*
Expand Down
Loading