[Python-checkins] bpo-9694: Fix misleading phrase "optional arguments" (GH-23858)
rhettinger
webhook-mailer at python.org
Wed Dec 23 12:41:07 EST 2020
https://github.com/python/cpython/commit/41b223d29cdfeb1f222c12c3abaccc3bc128f5e7
commit: 41b223d29cdfeb1f222c12c3abaccc3bc128f5e7
branch: master
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2020-12-23T09:40:56-08:00
summary:
bpo-9694: Fix misleading phrase "optional arguments" (GH-23858)
files:
A Misc/NEWS.d/next/Library/2020-12-19-12-33-38.bpo-9694.CkKK9V.rst
M Doc/howto/argparse.rst
M Doc/library/argparse.rst
M Lib/argparse.py
M Lib/test/test_argparse.py
diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index 76d8e6be42935..a97d10cfe6bb6 100644
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -83,7 +83,7 @@ Following is a result of running the code:
$ python3 prog.py --help
usage: prog.py [-h]
- optional arguments:
+ options:
-h, --help show this help message and exit
$ python3 prog.py --verbose
usage: prog.py [-h]
@@ -130,7 +130,7 @@ And running the code:
positional arguments:
echo
- optional arguments:
+ options:
-h, --help show this help message and exit
$ python3 prog.py foo
foo
@@ -172,7 +172,7 @@ And we get:
positional arguments:
echo echo the string you use here
- optional arguments:
+ options:
-h, --help show this help message and exit
Now, how about doing something even more useful::
@@ -241,7 +241,7 @@ And the output:
$ python3 prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]
- optional arguments:
+ options:
-h, --help show this help message and exit
--verbosity VERBOSITY
increase output verbosity
@@ -289,7 +289,7 @@ And the output:
$ python3 prog.py --help
usage: prog.py [-h] [--verbose]
- optional arguments:
+ options:
-h, --help show this help message and exit
--verbose increase output verbosity
@@ -332,7 +332,7 @@ And here goes:
$ python3 prog.py --help
usage: prog.py [-h] [-v]
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --verbose increase output verbosity
@@ -440,7 +440,7 @@ And the output:
positional arguments:
square display a square of a given number
- optional arguments:
+ options:
-h, --help show this help message and exit
-v {0,1,2}, --verbosity {0,1,2}
increase output verbosity
@@ -468,7 +468,8 @@ verbosity argument (check the output of ``python --help``)::
print(answer)
We have introduced another action, "count",
-to count the number of occurrences of a specific optional arguments:
+to count the number of occurrences of specific options.
+
.. code-block:: shell-session
@@ -489,7 +490,7 @@ to count the number of occurrences of a specific optional arguments:
positional arguments:
square display a square of a given number
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --verbosity increase output verbosity
$ python3 prog.py 4 -vvv
@@ -626,7 +627,7 @@ Output:
x the base
y the exponent
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --verbosity
$ python3 prog.py 4 2 -v
@@ -750,7 +751,7 @@ but not both at the same time:
x the base
y the exponent
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --verbose
-q, --quiet
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 4542961d7816e..80e0f013df09e 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -57,7 +57,7 @@ be run at the command line and provides useful help messages:
positional arguments:
N an integer for the accumulator
- optional arguments:
+ options:
-h, --help show this help message and exit
--sum sum the integers (default: find the max)
@@ -217,14 +217,14 @@ The help for this program will display ``myprogram.py`` as the program name
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help
@@ -235,7 +235,7 @@ To change this default behavior, another value can be supplied using the
>>> parser.print_help()
usage: myprogram [-h]
- optional arguments:
+ options:
-h, --help show this help message and exit
Note that the program name, whether determined from ``sys.argv[0]`` or from the
@@ -249,7 +249,7 @@ specifier.
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
@@ -269,7 +269,7 @@ arguments it contains::
positional arguments:
bar bar help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo [FOO] foo help
@@ -284,7 +284,7 @@ The default message can be overridden with the ``usage=`` keyword argument::
positional arguments:
bar bar help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo [FOO] foo help
@@ -307,7 +307,7 @@ various arguments::
A foo that bars
- optional arguments:
+ options:
-h, --help show this help message and exit
By default, the description will be line-wrapped so that it fits within the
@@ -329,7 +329,7 @@ argument to :class:`ArgumentParser`::
A foo that bars
- optional arguments:
+ options:
-h, --help show this help message and exit
And that's how you'd foo a bar
@@ -403,7 +403,7 @@ epilog_ texts in command-line help messages::
this description was indented weird but that is okay
- optional arguments:
+ options:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
@@ -432,7 +432,7 @@ should not be line-wrapped::
exactly the way
I want it
- optional arguments:
+ options:
-h, --help show this help message and exit
:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
@@ -454,7 +454,7 @@ default values to each of the argument help messages::
positional arguments:
bar BAR! (default: [1, 2, 3])
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
@@ -473,7 +473,7 @@ as the regular formatter does)::
positional arguments:
float
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo int
@@ -592,7 +592,7 @@ older arguments with the same option string. To get this behavior, the value
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
- optional arguments:
+ options:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
@@ -623,7 +623,7 @@ help will be printed:
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help
@@ -636,7 +636,7 @@ This can be achieved by passing ``False`` as the ``add_help=`` argument to
>>> parser.print_help()
usage: PROG [--foo FOO]
- optional arguments:
+ options:
--foo FOO foo help
The help option is typically ``-h/--help``. The exception to this is
@@ -649,7 +649,7 @@ the help options::
>>> parser.print_help()
usage: PROG [+h]
- optional arguments:
+ options:
+h, ++help show this help message and exit
@@ -1203,7 +1203,7 @@ argument::
positional arguments:
bar one of the bars to be frobbled
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo foo the bars before frobbling
@@ -1221,7 +1221,7 @@ specifiers include the program name, ``%(prog)s`` and most keyword arguments to
positional arguments:
bar the bar to frobble (default: 42)
- optional arguments:
+ options:
-h, --help show this help message and exit
As the help string supports %-formatting, if you want a literal ``%`` to appear
@@ -1235,7 +1235,7 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
>>> parser.print_help()
usage: frobble [-h]
- optional arguments:
+ options:
-h, --help show this help message and exit
@@ -1262,7 +1262,7 @@ will be referred to as ``FOO``. An example::
positional arguments:
bar
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO
@@ -1279,7 +1279,7 @@ An alternative name can be specified with ``metavar``::
positional arguments:
XXX
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo YYY
@@ -1297,7 +1297,7 @@ arguments::
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]
- optional arguments:
+ options:
-h, --help show this help message and exit
-x X X
--foo bar baz
@@ -1701,7 +1701,7 @@ Sub-commands
a a help
b b help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo foo help
@@ -1711,13 +1711,13 @@ Sub-commands
positional arguments:
bar bar help
- optional arguments:
+ options:
-h, --help show this help message and exit
>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]
- optional arguments:
+ options:
-h, --help show this help message and exit
--baz {X,Y,Z} baz help
@@ -1734,7 +1734,7 @@ Sub-commands
>>> parser.parse_args(['-h'])
usage: [-h] {foo,bar} ...
- optional arguments:
+ options:
-h, --help show this help message and exit
subcommands:
diff --git a/Lib/argparse.py b/Lib/argparse.py
index 2fb1da59f942c..8a12dea766879 100644
--- a/Lib/argparse.py
+++ b/Lib/argparse.py
@@ -1719,7 +1719,7 @@ def __init__(self,
add_group = self.add_argument_group
self._positionals = add_group(_('positional arguments'))
- self._optionals = add_group(_('optional arguments'))
+ self._optionals = add_group(_('options'))
self._subparsers = None
# register types
diff --git a/Lib/test/test_argparse.py b/Lib/test/test_argparse.py
index e98c15b11afb3..ec9711e4f6a47 100644
--- a/Lib/test/test_argparse.py
+++ b/Lib/test/test_argparse.py
@@ -2078,7 +2078,7 @@ def test_help(self):
bar bar help
{1,2,3} command help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo foo help
'''))
@@ -2097,7 +2097,7 @@ def test_help_extra_prefix_chars(self):
bar bar help
{1,2,3} command help
- optional arguments:
+ options:
-h, --help show this help message and exit
++foo foo help
'''))
@@ -2114,7 +2114,7 @@ def test_help_non_breaking_spaces(self):
main description
- optional arguments:
+ options:
-h, --help show this help message and exit
--non-breaking help message containing non-breaking spaces shall not
wrap\N{NO-BREAK SPACE}at non-breaking spaces
@@ -2133,7 +2133,7 @@ def test_help_alternate_prefix_chars(self):
bar bar help
{1,2,3} command help
- optional arguments:
+ options:
+h, ++help show this help message and exit
++foo foo help
'''))
@@ -2154,7 +2154,7 @@ def test_parser_command_help(self):
2 2 help
3 3 help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo foo help
'''))
@@ -2179,7 +2179,7 @@ def test_subparser_title_help(self):
positional arguments:
bar bar help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo foo help
@@ -2203,7 +2203,7 @@ def test_subparser1_help(self):
positional arguments:
{a,b,c} x help
- optional arguments:
+ options:
-h, --help show this help message and exit
-w W w help
'''))
@@ -2217,7 +2217,7 @@ def test_subparser2_help(self):
positional arguments:
z z help
- optional arguments:
+ options:
-h, --help show this help message and exit
-y {1,2,3} y help
'''))
@@ -2249,7 +2249,7 @@ def test_alias_help(self):
positional arguments:
bar bar help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo foo help
@@ -2437,7 +2437,7 @@ def test_parent_help(self):
a
z
- optional arguments:
+ options:
-h, --help show this help message and exit
-b B
--w W
@@ -2467,7 +2467,7 @@ def test_groups_parents(self):
self.assertEqual(parser_help, textwrap.dedent('''\
usage: {}{}[-h] [-w W] [-x X] [-y Y | -z Z]
- optional arguments:
+ options:
-h, --help show this help message and exit
-y Y
-z Z
@@ -2512,7 +2512,7 @@ def test_help(self):
expected = '''\
usage: PROG [-h] [--foo | --bar] [--soup | --nuts]
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo
--bar
@@ -2597,7 +2597,7 @@ def get_parser(self, required=None):
'''
help = '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
--bar BAR bar help
--baz [BAZ] baz help
@@ -2638,7 +2638,7 @@ def get_parser(self, required=None):
'''
help = '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
--abcde ABCDE abcde help
--fghij FGHIJ fghij help
@@ -2674,7 +2674,7 @@ def get_parser(self, required):
'''
help = '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
-y y help
'''
@@ -2711,7 +2711,7 @@ def get_parser(self, required):
'''
help = '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
'''
@@ -2754,7 +2754,7 @@ def get_parser(self, required):
positional arguments:
badger BADGER
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO
--spam SPAM SPAM
@@ -2793,7 +2793,7 @@ def get_parser(self, required):
'''
help = '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
-x x help
-a a help
@@ -2832,7 +2832,7 @@ def get_parser(self, required=None):
'''
help = '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
Titled group:
@@ -2877,7 +2877,7 @@ def get_parser(self, required):
x x help
a a help
- optional arguments:
+ options:
-h, --help show this help message and exit
-y y help
-b b help
@@ -2908,7 +2908,7 @@ def get_parser(self, required):
help = '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
-a A
-b B
@@ -3226,7 +3226,7 @@ class TestHelpBiggerOptionals(HelpTestCase):
foo FOO HELP
bar BAR HELP
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-x X HELP
@@ -3271,7 +3271,7 @@ def setUp(self):
bar
BAR HELP
- optional arguments:
+ options:
-h, --help
show this
help
@@ -3321,7 +3321,7 @@ class TestHelpBiggerOptionalGroups(HelpTestCase):
foo FOO HELP
bar BAR HELP
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-x X HELP
@@ -3362,7 +3362,7 @@ class TestHelpBiggerPositionals(HelpTestCase):
ekiekiekifekang EKI HELP
bar BAR HELP
- optional arguments:
+ options:
-h, --help show this help message and exit
-x X HELP
--y Y Y HELP
@@ -3409,7 +3409,7 @@ class TestHelpReformatting(HelpTestCase):
positional arguments:
yyy normal y help
- optional arguments:
+ options:
-h, --help show this help message and exit
-x XX oddly formatted -x help
@@ -3449,7 +3449,7 @@ class TestHelpWrappingShortNames(HelpTestCase):
YHYH YHYH
YHYH YHYH YHYH YHYH YHYH YHYH YHYH YH
- optional arguments:
+ options:
-h, --help show this help message and exit
-x XX XHH HXXHH HXXHH HXXHH HXXHH HXXHH HXXHH HXXHH HXXHH \
HXXHH HXXHH
@@ -3492,7 +3492,7 @@ class TestHelpWrappingLongNames(HelpTestCase):
YHYH YHYH
YHYH YHYH YHYH YHYH YHYH YHYH YHYH YHYH YHYH YH
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-x XXXXXXXXXXXXXXXXXXXXXXXXX
@@ -3554,7 +3554,7 @@ class TestHelpUsage(HelpTestCase):
b b
c c
- optional arguments:
+ options:
-h, --help show this help message and exit
-w W [W ...] w
-x [X ...] x
@@ -3623,7 +3623,7 @@ class TestHelpUsageLongProg(HelpTestCase):
a
b
- optional arguments:
+ options:
-h, --help show this help message and exit
-w W
-x X
@@ -3657,7 +3657,7 @@ class TestHelpUsageLongProgOptionsWrap(HelpTestCase):
a
b
- optional arguments:
+ options:
-h, --help show this help message and exit
-w WWWWWWWWWWWWWWWWWWWWWWWWW
-x XXXXXXXXXXXXXXXXXXXXXXXXX
@@ -3720,7 +3720,7 @@ class TestHelpUsageOptionalsWrap(HelpTestCase):
b
c
- optional arguments:
+ options:
-h, --help show this help message and exit
-w WWWWWWWWWWWWWWWWWWWWWWWWW
-x XXXXXXXXXXXXXXXXXXXXXXXXX
@@ -3755,7 +3755,7 @@ class TestHelpUsagePositionalsWrap(HelpTestCase):
bbbbbbbbbbbbbbbbbbbbbbbbb
ccccccccccccccccccccccccc
- optional arguments:
+ options:
-h, --help show this help message and exit
-x X
-y Y
@@ -3791,7 +3791,7 @@ class TestHelpUsageOptionalsPositionalsWrap(HelpTestCase):
bbbbbbbbbbbbbbbbbbbbbbbbb
ccccccccccccccccccccccccc
- optional arguments:
+ options:
-h, --help show this help message and exit
-x XXXXXXXXXXXXXXXXXXXXXXXXX
-y YYYYYYYYYYYYYYYYYYYYYYYYY
@@ -3817,7 +3817,7 @@ class TestHelpUsageOptionalsOnlyWrap(HelpTestCase):
'''
help = usage + '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
-x XXXXXXXXXXXXXXXXXXXXXXXXX
-y YYYYYYYYYYYYYYYYYYYYYYYYY
@@ -3882,7 +3882,7 @@ class TestHelpVariableExpansion(HelpTestCase):
spam spam PROG None
badger badger PROG 0.5
- optional arguments:
+ options:
-h, --help show this help message and exit
-x X x PROG None int %
-y y PROG 42 XXX
@@ -3907,7 +3907,7 @@ class TestHelpVariableExpansionUsageSupplied(HelpTestCase):
''')
help = usage + '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
'''
version = ''
@@ -3939,7 +3939,7 @@ class TestHelpSuppressUsage(HelpTestCase):
positional arguments:
spam spam help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help
'''
@@ -3986,7 +3986,7 @@ class TestHelpSuppressOptionalGroup(HelpTestCase):
positional arguments:
spam spam help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help
'''
@@ -4007,7 +4007,7 @@ class TestHelpSuppressPositional(HelpTestCase):
'''
help = usage + '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help
'''
@@ -4027,7 +4027,7 @@ class TestHelpRequiredOptional(HelpTestCase):
'''
help = usage + '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help
'''
@@ -4048,7 +4048,7 @@ class TestHelpAlternatePrefixChars(HelpTestCase):
'''
help = usage + '''\
- optional arguments:
+ options:
^^foo foo help
;b BAR, ;;bar BAR bar help
'''
@@ -4072,7 +4072,7 @@ class TestHelpNoHelpOptional(HelpTestCase):
positional arguments:
spam spam help
- optional arguments:
+ options:
--foo FOO foo help
'''
version = ''
@@ -4095,7 +4095,7 @@ class TestHelpNone(HelpTestCase):
positional arguments:
spam
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO
'''
@@ -4119,7 +4119,7 @@ class TestHelpTupleMetavar(HelpTestCase):
'''
help = usage + '''\
- optional arguments:
+ options:
-h, --help show this help message and exit
-w W1 [W2 ...] w
-x [X1 [X2 ...]] x
@@ -4163,7 +4163,7 @@ class TestHelpRawText(HelpTestCase):
positional arguments:
spam spam help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help should also
appear as given here
@@ -4212,7 +4212,7 @@ class TestHelpRawDescription(HelpTestCase):
positional arguments:
spam spam help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help should not retain this odd formatting
@@ -4254,7 +4254,7 @@ class TestHelpArgumentDefaults(HelpTestCase):
spam spam help
badger badger help (default: wooden)
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help - oh and by the way, None
--bar bar help (default: False)
@@ -4279,7 +4279,7 @@ class TestHelpVersionAction(HelpTestCase):
description
- optional arguments:
+ options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
'''
@@ -4305,7 +4305,7 @@ class TestHelpVersionActionSuppress(HelpTestCase):
positional arguments:
spam spam help
- optional arguments:
+ options:
-h, --help show this help message and exit
--foo FOO foo help
'''
@@ -4331,7 +4331,7 @@ class TestHelpSubparsersOrdering(HelpTestCase):
positional arguments:
{a,b,c,d,e}
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
'''
@@ -4372,7 +4372,7 @@ class TestHelpSubparsersWithHelpOrdering(HelpTestCase):
d d subcommand help
e e subcommand help
- optional arguments:
+ options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
'''
@@ -4404,7 +4404,7 @@ def custom_type(string):
positional arguments:
int
- optional arguments:
+ options:
-h, --help show this help message and exit
-b custom_type
-c SOME FLOAT
@@ -4596,7 +4596,7 @@ def test_resolve_error(self):
self.assertEqual(parser.format_help(), textwrap.dedent('''\
usage: PROG [-h] [-x X]
- optional arguments:
+ options:
-h, --help show this help message and exit
-x X NEW X
'''))
@@ -4606,7 +4606,7 @@ def test_resolve_error(self):
self.assertEqual(parser.format_help(), textwrap.dedent('''\
usage: PROG [-h] [-x X] [--spam NEW_SPAM]
- optional arguments:
+ options:
-h, --help show this help message and exit
-x X NEW X
--spam NEW_SPAM
@@ -5337,7 +5337,7 @@ def test_help_with_metavar(self):
usage: this_is_spammy_prog_with_a_long_name_sorry_about_the_name
[-h] [--proxy <http[s]://example:1234>]
- optional arguments:
+ options:
-h, --help show this help message and exit
--proxy <http[s]://example:1234>
'''))
diff --git a/Misc/NEWS.d/next/Library/2020-12-19-12-33-38.bpo-9694.CkKK9V.rst b/Misc/NEWS.d/next/Library/2020-12-19-12-33-38.bpo-9694.CkKK9V.rst
new file mode 100644
index 0000000000000..723955270d02c
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2020-12-19-12-33-38.bpo-9694.CkKK9V.rst
@@ -0,0 +1,2 @@
+Argparse help no longer uses the confusing phrase, "optional arguments".
+It uses "options" instead.
More information about the Python-checkins
mailing list