Skip to content
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

[3.11] gh-92446: Improve argparse choices docs (GH-94627) #100528

Merged
merged 1 commit into from
Dec 26, 2022
Merged

[3.11] gh-92446: Improve argparse choices docs (GH-94627) #100528

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
12 changes: 6 additions & 6 deletions Doc/library/argparse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -755,7 +755,7 @@ The add_argument() method

* type_ - The type to which the command-line argument should be converted.

* choices_ - A container of the allowable values for the argument.
* choices_ - A sequence of the allowable values for the argument.

* required_ - Whether or not the command-line option may be omitted
(optionals only).
Expand Down Expand Up @@ -1199,7 +1199,7 @@ choices
^^^^^^^

Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a container object as the *choices* keyword
These can be handled by passing a sequence object as the *choices* keyword
argument to :meth:`~ArgumentParser.add_argument`. When the command line is
parsed, argument values will be checked, and an error message will be displayed
if the argument was not one of the acceptable values::
Expand All @@ -1213,9 +1213,9 @@ 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* container is checked after any type_
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*
container should match the type_ specified::
sequence should match the type_ specified::

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
Expand All @@ -1225,8 +1225,8 @@ container should match the type_ specified::
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

Any container can be passed as the *choices* value, so :class:`list` objects,
:class:`set` objects, and custom containers are all supported.
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.
Expand Down