Skip to content

Commit

Permalink
bpo-9694: Fix misleading phrase "optional arguments" (GH-23858)
Browse files Browse the repository at this point in the history
  • Loading branch information
@rhettinger
rhettinger authored Dec 23, 2020
1 parent bfda4f5 commit 41b223d
Show file tree
Hide file tree
Showing 5 changed files with 98 additions and 95 deletions.
23 changes: 12 additions & 11 deletions Doc/howto/argparse.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
54 changes: 27 additions & 27 deletions Doc/library/argparse.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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)

Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -649,7 +649,7 @@ the help options::
>>> parser.print_help()
usage: PROG [+h]

optional arguments:
options:
+h, ++help show this help message and exit


Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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


Expand All @@ -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

Expand All @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion Lib/argparse.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit 41b223d

Please sign in to comment.