Skip to content

Commit

Permalink
[3.11] gh-92446: Improve argparse choices docs (GH-94627) (#100528)
Browse files Browse the repository at this point in the history
Based on the definition of the collections.abc classes, it is more accurate to use "sequence" instead of "container" when describing argparse choices.

(cherry picked from commit ad3c99e)

Co-authored-by: Guy Yagev <[email protected]>
Co-authored-by: Shantanu <[email protected]>
  • Loading branch information
hauntsaninja and yourlefthandman authored Dec 26, 2022
1 parent 75b75df commit 2cb4b13
Showing 1 changed file with 6 additions and 6 deletions.
12 changes: 6 additions & 6 deletions Doc/library/argparse.rst
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

0 comments on commit 2cb4b13

Please sign in to comment.