bpo-38438: Simplify argparse "star nargs" usage. (GH-17106)

Author: brandtbucher

Doc/library/argparse.rst

@@ -449,7 +449,7 @@ default values to each of the argument help messages::
    >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
    >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
    >>> parser.print_help()
-   usage: PROG [-h] [--foo FOO] [bar [bar ...]]
+   usage: PROG [-h] [--foo FOO] [bar ...]
 
    positional arguments:
     bar         BAR! (default: [1, 2, 3])

Doc/library/pdb.rst

@@ -296,20 +296,20 @@ by the local file.
    Temporary breakpoint, which is removed automatically when it is first hit.
    The arguments are the same as for :pdbcmd:`break`.
 
-.. pdbcommand:: cl(ear) [filename:lineno | bpnumber [bpnumber ...]]
+.. pdbcommand:: cl(ear) [filename:lineno | bpnumber ...]
 
    With a *filename:lineno* argument, clear all the breakpoints at this line.
    With a space separated list of breakpoint numbers, clear those breakpoints.
    Without argument, clear all breaks (but first ask confirmation).
 
-.. pdbcommand:: disable [bpnumber [bpnumber ...]]
+.. pdbcommand:: disable [bpnumber ...]
 
    Disable the breakpoints given as a space separated list of breakpoint
    numbers.  Disabling a breakpoint means it cannot cause the program to stop
    execution, but unlike clearing a breakpoint, it remains in the list of
    breakpoints and can be (re-)enabled.
 
-.. pdbcommand:: enable [bpnumber [bpnumber ...]]
+.. pdbcommand:: enable [bpnumber ...]
 
    Enable the breakpoints specified.
 

Lib/argparse.py

@@ -591,7 +591,11 @@ def _format_args(self, action, default_metavar):
         elif action.nargs == OPTIONAL:
             result = '[%s]' % get_metavar(1)
         elif action.nargs == ZERO_OR_MORE:
-            result = '[%s [%s ...]]' % get_metavar(2)
+            metavar = get_metavar(1)
+            if len(metavar) == 2:
+                result = '[%s [%s ...]]' % metavar
+            else:
+                result = '[%s ...]' % metavar
         elif action.nargs == ONE_OR_MORE:
             result = '%s [%s ...]' % get_metavar(2)
         elif action.nargs == REMAINDER:

Lib/pydoc_data/topics.py

@@ -3903,7 +3903,7 @@
              'is\n'
              '   first hit. The arguments are the same as for "break".\n'
              '\n'
-             'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n'
+             'cl(ear) [filename:lineno | bpnumber ...]\n'
              '\n'
              '   With a *filename:lineno* argument, clear all the breakpoints '
              'at\n'
@@ -3913,7 +3913,7 @@
              'first\n'
              '   ask confirmation).\n'
              '\n'
-             'disable [bpnumber [bpnumber ...]]\n'
+             'disable [bpnumber ...]\n'
              '\n'
              '   Disable the breakpoints given as a space separated list of\n'
              '   breakpoint numbers.  Disabling a breakpoint means it cannot '
@@ -3922,7 +3922,7 @@
              'breakpoint, it\n'
              '   remains in the list of breakpoints and can be (re-)enabled.\n'
              '\n'
-             'enable [bpnumber [bpnumber ...]]\n'
+             'enable [bpnumber ...]\n'
              '\n'
              '   Enable the breakpoints specified.\n'
              '\n'

Lib/test/test_argparse.py

@@ -2163,7 +2163,7 @@ def test_subparser1_help(self):
 
     def test_subparser2_help(self):
         self._test_subparser_help('5.0 2 -h', textwrap.dedent('''\
-            usage: PROG bar 2 [-h] [-y {1,2,3}] [z [z ...]]
+            usage: PROG bar 2 [-h] [-y {1,2,3}] [z ...]
 
             2 description
 
@@ -2697,10 +2697,10 @@ def get_parser(self, required):
     ]
 
     usage_when_not_required = '''\
-        usage: PROG [-h] [--foo | --spam SPAM | badger [badger ...]]
+        usage: PROG [-h] [--foo | --spam SPAM | badger ...]
         '''
     usage_when_required = '''\
-        usage: PROG [-h] (--foo | --spam SPAM | badger [badger ...])
+        usage: PROG [-h] (--foo | --spam SPAM | badger ...)
         '''
     help = '''\
 
@@ -3494,11 +3494,11 @@ class TestHelpUsage(HelpTestCase):
         ])
     ]
     usage = '''\
-        usage: PROG [-h] [-w W [W ...]] [-x [X [X ...]]] [--foo | --no-foo]
+        usage: PROG [-h] [-w W [W ...]] [-x [X ...]] [--foo | --no-foo]
                     [--bar | --no-bar]
                     [-f | --foobar | --no-foobar | --barfoo | --no-barfoo] [-y [Y]]
                     [-z Z Z Z]
-                    a b b [c] [d [d ...]] e [e ...]
+                    a b b [c] [d ...] e [e ...]
         '''
     help = usage + '''\
 
@@ -3510,7 +3510,7 @@ class TestHelpUsage(HelpTestCase):
         optional arguments:
           -h, --help            show this help message and exit
           -w W [W ...]          w
-          -x [X [X ...]]        x
+          -x [X ...]            x
           --foo, --no-foo       Whether to foo
           --bar, --no-bar       Whether to bar (default: True)
           -f, --foobar, --no-foobar, --barfoo, --no-barfoo
@@ -5113,7 +5113,7 @@ def test_nargs_zeroormore_metavar_length0(self):
         self.do_test_exception(nargs="*", metavar=tuple())
 
     def test_nargs_zeroormore_metavar_length1(self):
-        self.do_test_exception(nargs="*", metavar=("1",))
+        self.do_test_no_exception(nargs="*", metavar=("1",))
 
     def test_nargs_zeroormore_metavar_length2(self):
         self.do_test_no_exception(nargs="*", metavar=("1", "2"))

Misc/NEWS.d/next/Library/2019-11-11-06-14-25.bpo-38438.vSVeHN.rst

@@ -0,0 +1 @@
+Simplify the :mod:`argparse` usage message for ``nargs="*"``.