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 5 commits into
base: main
Choose a base branch
from
+8 −4
Open

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

Changes from all commits
Commits
Show all changes
5 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
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
12 changes: 8 additions & 4 deletions Doc/library/argparse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1156,16 +1156,20 @@ 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.

Note that *choices* are checked after any type_
conversions have been performed, so objects in *choices*
should match the type_ specified. This can make *choices*
appear unfamiliar in usage, help, or error messages.

To keep *choices* user-friendly, consider a custom type wrapper that
converts and formats values, or omit type_ and handle conversion in
your application code.
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
Expand Down
Loading
0