From 41b223d29cdfeb1f222c12c3abaccc3bc128f5e7 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Wed, 23 Dec 2020 09:40:56 -0800 Subject: bpo-9694: Fix misleading phrase "optional arguments" (GH-23858) --- Doc/howto/argparse.rst | 23 +++-- Doc/library/argparse.rst | 54 +++++----- Lib/argparse.py | 2 +- Lib/test/test_argparse.py | 112 ++++++++++----------- .../2020-12-19-12-33-38.bpo-9694.CkKK9V.rst | 2 + 5 files changed, 98 insertions(+), 95 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2020-12-19-12-33-38.bpo-9694.CkKK9V.rst diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 76d8e6b..a97d10c 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 4542961..80e0f01 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 2fb1da5..8a12dea 100644 --- a/Lib/argparse.py +++ b/Lib/argparse.py @@ -1719,7 +1719,7 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer): 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 e98c15b..ec9711e 100644 --- a/Lib/test/test_argparse.py +++ b/Lib/test/test_argparse.py @@ -2078,7 +2078,7 @@ class TestAddSubparsers(TestCase): 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 @@ class TestAddSubparsers(TestCase): 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 @@ class TestAddSubparsers(TestCase): 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 @@ class TestAddSubparsers(TestCase): 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 @@ class TestAddSubparsers(TestCase): 2 2 help 3 3 help - optional arguments: + options: -h, --help show this help message and exit --foo foo help ''')) @@ -2179,7 +2179,7 @@ class TestAddSubparsers(TestCase): positional arguments: bar bar help - optional arguments: + options: -h, --help show this help message and exit --foo foo help @@ -2203,7 +2203,7 @@ class TestAddSubparsers(TestCase): 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 @@ class TestAddSubparsers(TestCase): 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 @@ class TestAddSubparsers(TestCase): positional arguments: bar bar help - optional arguments: + options: -h, --help show this help message and exit --foo foo help @@ -2437,7 +2437,7 @@ class TestParentParsers(TestCase): a z - optional arguments: + options: -h, --help show this help message and exit -b B --w W @@ -2467,7 +2467,7 @@ class TestParentParsers(TestCase): 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 @@ class TestMutuallyExclusiveGroupErrors(TestCase): 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 @@ class TestMutuallyExclusiveSimple(MEMixin, TestCase): ''' help = '''\ - optional arguments: + options: -h, --help show this help message and exit --bar BAR bar help --baz [BAZ] baz help @@ -2638,7 +2638,7 @@ class TestMutuallyExclusiveLong(MEMixin, TestCase): ''' help = '''\ - optional arguments: + options: -h, --help show this help message and exit --abcde ABCDE abcde help --fghij FGHIJ fghij help @@ -2674,7 +2674,7 @@ class TestMutuallyExclusiveFirstSuppressed(MEMixin, TestCase): ''' help = '''\ - optional arguments: + options: -h, --help show this help message and exit -y y help ''' @@ -2711,7 +2711,7 @@ class TestMutuallyExclusiveManySuppressed(MEMixin, TestCase): ''' help = '''\ - optional arguments: + options: -h, --help show this help message and exit ''' @@ -2754,7 +2754,7 @@ class TestMutuallyExclusiveOptionalAndPositional(MEMixin, TestCase): positional arguments: badger BADGER - optional arguments: + options: -h, --help show this help message and exit --foo FOO --spam SPAM SPAM @@ -2793,7 +2793,7 @@ class TestMutuallyExclusiveOptionalsMixed(MEMixin, TestCase): ''' help = '''\ - optional arguments: + options: -h, --help show this help message and exit -x x help -a a help @@ -2832,7 +2832,7 @@ class TestMutuallyExclusiveInGroup(MEMixin, TestCase): ''' help = '''\ - optional arguments: + options: -h, --help show this help message and exit Titled group: @@ -2877,7 +2877,7 @@ class TestMutuallyExclusiveOptionalsAndPositionalsMixed(MEMixin, TestCase): 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 @@ class TestMutuallyExclusiveNested(MEMixin, TestCase): 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 @@ class TestShortColumns(HelpTestCase): 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 @@ multiple 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 @@ DD DD DD 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 @@ DD DD DD 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 @@ class TestHelpMetavarTypeFormatter(HelpTestCase): positional arguments: int - optional arguments: + options: -h, --help show this help message and exit -b custom_type -c SOME FLOAT @@ -4596,7 +4596,7 @@ class TestConflictHandling(TestCase): 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 @@ class TestConflictHandling(TestCase): 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 @@ class TestWrappingMetavar(TestCase): usage: this_is_spammy_prog_with_a_long_name_sorry_about_the_name [-h] [--proxy ] - optional arguments: + options: -h, --help show this help message and exit --proxy ''')) 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 0000000..7239552 --- /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. -- cgit v0.12