8000 gh-132558: Improve `argparse` docs on combining `type` and `choices` by hansthen · Pull Request #133827 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-132558: Improve argparse docs on combining type and choices #133827

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 6 commits into
base: main
Choose a base branch
from
Open

gh-132558: Improve argparse docs on combining type and choices #133827

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0bbe65c
Improve docs on *type* and *choices*.
hansthen May 10, 2025
615e96f
Updated after review comments
hansthen May 10, 2025
ecd4c5f
Update Doc/library/argparse.rst
hansthen Jul 1, 2025
37274cc
Fixed trailing space.
hansthen Jul 1, 2025
2434cd4
Merge branch 'main' into issue-132558-improve-documentation
hansthen Jul 1, 2025
2004934
Merge branch 'main' into issue-132558-improve-documentation
hansthen Jul 3, 2025
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
Next Next commit
Improve docs on *type* and *choices*.
  • Loading branch information
@hansthen
hansthen committed May 10, 2025
commit 0bbe65c690602b82add79a080d1b199323945a28
21 changes: 14 additions & 7 deletions Doc/library/argparse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1124,21 +1124,28 @@ if the argument was not one of the acceptable values::
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*
sequence should match the type_ specified.

Any sequence can be passed as the *choices* value, so :class:`list` objects,
:class:`tuple` objects, and custom sequences are all supported.

Use of :class:`enum.Enum` is not recommended because it is difficult to
control its appearance in usage, help, and error messages.

Formatted choices override the default *metavar* which is normally derived
from *dest*. This is usually what you want because the user never sees the
*dest* parameter. If this display isn't desirable (perhaps because there are
many choices), just specify an explicit metavar_.
Copy link
Member

Choose a reason for hiding this comment

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

This should not be inbetween the choices notes.

Copy link
Author

Choose a reason for hiding this comment

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

It was already with the choices documentation. Where would you move it to?

Copy link
Member

Choose a reason for hiding this comment

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

You should move the text you added above it.


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*
sequence should match the type_ specified. This may interfere with
the display of the choices in usage, help and error messages, because the
*choices* may not be familiar to the end-user.

Use of :class:`enum.Enum` is not recommended because it is difficult to
control its appearance in these messages.
Copy link
Member

Choose a reason for hiding this comment

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

I think it's previous place was fine, it continued naturally from the previous point.


If you have to use both *type* and *choices* you can use a wrapper class
that formats the value after type conversion back to the vocabulary of the
end-user. However, it is usually easier to not specify *type* and perform
type conversion in application code.


.. _required:

Expand Down
Loading
0