All commit authors signed the Contributor License Agreement.

Most changes to Pythonrequire a NEWS entry. Add one using theblurb_it web app or theblurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply theskip news label instead.

Most changes to Pythonrequire a NEWS entry. Add one using theblurb_it web app or theblurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply theskip news label instead.

Since this changes user-facing behavior, it needs an issue and a NEWS entry.

The change in_get_action_name could use a new unit test; it looks like the existing code there would be broken ifchoices contained a non-str.

Since this changes user-facing behavior, it needs an issue and a NEWS entry.

Done

The change in_get_action_name could use a new unit test; it looks like the existing code there would be broken ifchoices contained a non-str.

True. But that's a job fortyping and some linter, not unit tests, or?

Since this changes user-facing behavior, it needsan issue. Do you want to file one?

As the docs say:

Use ofenum.Enum is not recommended because it is difficult to control its appearance in usage, help, and error messages.

So, in today'sargparse, you should use actual strings inchoices, and convert the value later usingMyEnum(params.foo).

As far as I know,repr is used intentionally, to add quotes around each of the strings. The change you are proposing is not obviously right.

Since this changes user-facing behavior, it needsan issue. Do you want to file one?

Done.#118839

As the docs say:

Use ofenum.Enum is not recommended because it is difficult to control its appearance in usage, help, and error messages.
So, in today'sargparse, you should use actual strings inchoices, and convert the value later usingMyEnum(params.foo).

That concerns#86667, which is unrelated to this one. The fix for the issue then, in fact, introduced another bug, ie., the sentence you quoted. It just comments onthe bad code example the fix deleted and does not hold up on its own, since anything can be used as choices and one can always expect to seestr(choice) in usage, help, etc. I suggest either removing the sentence altogether or reverting the commit and instead just changeenum.Enum toenum.StrEnum. I might do it as part of this PR, too.

As far as I know,repr is used intentionally, to add quotes around each of the strings. The change you are proposing is not obviously right.

Usingrepr() is always wrong in this context. Quoting the choices is debatable, but it's just a cosmetic preference and not used in any other place. Should its omission hinder the merging of this PR, then its trivial to do it the right way instead of therepr() hack.

Could you addgh-118839 to the title?

gh-118839: argparse: use str() consistently and explicitly to print choices

Usingrepr() is always wrong in this context.

That's false.repr is correct for strings, integers, floats, and more.
str works for integers, floats, and StrEnums -- but not plain Enums, and it's not ideal for strings.
There are many other types that people will want to use withchoices.
Theproper function would be one that can reverse the user-suppliedtype, and ideally add quoting when it's useful to set the values apart from other text.

IMO, we should continue in the direction set in#86667: choices are designed forstrings.
Perhaps we should add a way to attach string labels to arbitrary-type choices, butgenerating those labels can only be done for a small set of specific types. StrEnum is not the end here; after it we'll get a request forEnum, and there'll always be another type to support, with special handling.

As Serhiy says, StrEnum aren't well supported in general and may have other issues; that'll also be the case for any other types.

There seems to be some misunderstandings here and there. Therefore, I'll summarize and clarify a few points.

This PR should address inaccuracies in both theargparse code and its documentation, with regards to thechoices parameter. More specifically, what values the parameter accepts and how they're processed.

Premises based on the API documentation:

1. Thechoices parametermust accept anyiterablecontainer, includingStrEnum.
2. The items in such a containermay be of any type, not just strings orStrEnum members.
3. The container item typeshould match thetype parameter.
4. Container itemsmust have a functional__eq__() to ensure the container's__contains__() operates correctly.
5. Type-converted argument stringsshall be checked for presence in the container using__contains__().
6. Container itemsmust be convertible to a string using__str__().
7. The resulting stringshall be used to display help, usage, error messages, etc. to the user.
8. The stringsshall be separated with commas, if the whole container is displayed to the user.

References

Current docs:https://docs.python.org/3/library/argparse.html#choices
Earliest docs:

• https://github.com/ThomasWaldmann/argparse/blob/16f0347e0628c7484bd2c20a229da8c4799a7a8c/doc/source/argparse-vs-optparse.rst#more-choices
• https://github.com/ThomasWaldmann/argparse/blob/16f0347e0628c7484bd2c20a229da8c4799a7a8c/doc/source/add_argument.rst#choices
• https://web.archive.org/web/20060814032155/http://argparse.python-hosting.com/

It would be nice to add a test that uses enums to demonstrate the benefit of this change.

It would be nice to add a test that uses enums to demonstrate the benefit of this change.

Reasonable wish, it’s been granted.

@serhiy-storchaka I fixed the conflicts you introduced and implemented all changes you suggested. Please review the updates so it can be finally merged.

Thanks@rindeal for the PR, and@serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

Thanks@rindeal for the PR, and@serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

Sorry,@rindeal and@serhiy-storchaka, I could not cleanly backport this to3.12 due to a conflict.
Please backport usingcherry_picker on command line.

cherry_picker 66b3922b97388c328c9bd8df050eef11c0261fae 3.12

Sorry,@rindeal and@serhiy-storchaka, I could not cleanly backport this to3.13 due to a conflict.
Please backport usingcherry_picker on command line.

cherry_picker 66b3922b97388c328c9bd8df050eef11c0261fae 3.13

GH-125431 is a backport of this pull request to the3.13 branch.

GH-125432 is a backport of this pull request to the3.12 branch.