[Python-checkins] [3.11] gh-92446: Improve argparse choices docs (GH-94627) (#100528)
hauntsaninja
webhook-mailer at python.org
Mon Dec 26 02:09:11 EST 2022
https://github.com/python/cpython/commit/2cb4b13af6ac975b1a98ddc7d117c3b25398ccf0
commit: 2cb4b13af6ac975b1a98ddc7d117c3b25398ccf0
branch: 3.11
author: Shantanu <12621235+hauntsaninja at users.noreply.github.com>
committer: hauntsaninja <12621235+hauntsaninja at users.noreply.github.com>
date: 2022-12-26T01:09:06-06:00
summary:
[3.11] gh-92446: Improve argparse choices docs (GH-94627) (#100528)
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 ad3c99e521)
Co-authored-by: Guy Yagev <yourlefthandman8 at gmail.com>
Co-authored-by: Shantanu <12621235+hauntsaninja at users.noreply.github.com>
files:
M Doc/library/argparse.rst
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 67ca6e77bc00..eeb65160bbc8 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -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).
@@ -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::
@@ -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))
@@ -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.
More information about the Python-checkins
mailing list