Make BooleanOptionalAction's addition of default to help more similar to other actions.

Help for other actions omit the default value if default is SUPPRESS or
already contains the special format string '%(default)'.  Add those
special cases to BooleanOptionalAction's help formatting too.

Other actions emit (default: None) when the default value is None.  This
allows documenting that the unset case is treated differently.  Add this
functionality to BooleanOptionalAction as well.

Fixes https://bugs.python.org/issue44587 so that default=SUPPRESS is not
emitted.

Fixes https://bugs.python.org/issue38956 as this code will detect
whether '%(default)s' has already been specified in the help string.

Author: abadger

Lib/argparse.py

@@ -153,6 +153,27 @@ def _copy_items(items):
 # Formatting Help
 # ===============
 
+def _add_default_to_help_string(action):
+    """
+    Add the default value to the option help message.
+
+    ArgumentDefaultsHelpFormatter and BooleanOptionalAction both want to add
+    the default value to the help message when it isn't already present.  This
+    code will do that, detecting cornercases to prevent duplicates or cases
+    where it wouldn't make sense to the end user.
+    """
+    help = action.help
+    if help is None:
+        help = ''
+
+    if '%(default)' not in help:
+        if action.default is not SUPPRESS:
+            defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
+            if action.option_strings or action.nargs in defaulting_nargs:
+                help += ' (default: %(default)s)'
+    return help
+
+
 class HelpFormatter(object):
     """Formatter for generating usage messages and argument help strings.
 
@@ -695,13 +716,7 @@ class ArgumentDefaultsHelpFormatter(HelpFormatter):
     """
 
     def _get_help_string(self, action):
-        help = action.help
-        if '%(default)' not in action.help:
-            if action.default is not SUPPRESS:
-                defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
-                if action.option_strings or action.nargs in defaulting_nargs:
-                    help += ' (default: %(default)s)'
-        return help
+        return _add_default_to_help_string(action)
 
 
 class MetavarTypeHelpFormatter(HelpFormatter):
@@ -719,7 +734,6 @@ def _get_default_metavar_for_positional(self, action):
         return action.type.__name__
 
 
-
 # =====================
 # Options and Arguments
 # =====================
@@ -882,9 +896,6 @@ def __init__(self,
                 option_string = '--no-' + option_string[2:]
                 _option_strings.append(option_string)
 
-        if help is not None and default is not None and default is not SUPPRESS:
-            help += " (default: %(default)s)"
-
         super().__init__(
             option_strings=_option_strings,
             dest=dest,
@@ -896,6 +907,9 @@ def __init__(self,
             help=help,
             metavar=metavar)
 
+        self.help = _add_default_to_help_string(self)
+
+
     def __call__(self, parser, namespace, values, option_string=None):
         if option_string in self.option_strings:
             setattr(namespace, self.dest, not option_string.startswith('--no-'))

Lib/test/test_argparse.py

@@ -3348,6 +3348,7 @@ def _get_parser(self, tester):
             def _test(self, tester, parser_text):
                 expected_text = getattr(tester, self.func_suffix)
                 expected_text = textwrap.dedent(expected_text)
+                tester.maxDiff = None
                 tester.assertEqual(expected_text, parser_text)
 
             def test_format(self, tester):
@@ -3742,9 +3743,10 @@ class TestHelpUsage(HelpTestCase):
           -h, --help            show this help message and exit
           -w W [W ...]          w
           -x [X ...]            x
-          --foo, --no-foo       Whether to foo
+          --foo, --no-foo       Whether to foo (default: None)
           --bar, --no-bar       Whether to bar (default: True)
           -f, --foobar, --no-foobar, --barfoo, --no-barfoo
+                                (default: None)
           --bazz, --no-bazz     Bazz!
 
         group:
@@ -4423,6 +4425,8 @@ class TestHelpArgumentDefaults(HelpTestCase):
         Sig('--bar', action='store_true', help='bar help'),
         Sig('--taz', action=argparse.BooleanOptionalAction,
             help='Whether to taz it', default=True),
+        Sig('--corge', action=argparse.BooleanOptionalAction,
+            help='Whether to corge it', default=argparse.SUPPRESS),
         Sig('--quux', help="Set the quux", default=42),
         Sig('spam', help='spam help'),
         Sig('badger', nargs='?', default='wooden', help='badger help'),
@@ -4432,29 +4436,30 @@ class TestHelpArgumentDefaults(HelpTestCase):
          [Sig('--baz', type=int, default=42, help='baz help')]),
     ]
     usage = '''\
-        usage: PROG [-h] [--foo FOO] [--bar] [--taz | --no-taz] [--quux QUUX]
-                    [--baz BAZ]
+        usage: PROG [-h] [--foo FOO] [--bar] [--taz | --no-taz] [--corge | --no-corge]
+                    [--quux QUUX] [--baz BAZ]
                     spam [badger]
         '''
     help = usage + '''\
 
         description
 
         positional arguments:
-          spam             spam help
-          badger           badger help (default: wooden)
+          spam                 spam help
+          badger               badger help (default: wooden)
 
         options:
-          -h, --help       show this help message and exit
-          --foo FOO        foo help - oh and by the way, None
-          --bar            bar help (default: False)
-          --taz, --no-taz  Whether to taz it (default: True)
-          --quux QUUX      Set the quux (default: 42)
+          -h, --help           show this help message and exit
+          --foo FOO            foo help - oh and by the way, None
+          --bar                bar help (default: False)
+          --taz, --no-taz      Whether to taz it (default: True)
+          --corge, --no-corge  Whether to corge it
+          --quux QUUX          Set the quux (default: 42)
 
         title:
           description
 
-          --baz BAZ        baz help (default: 42)
+          --baz BAZ            baz help (default: 42)
         '''
     version = ''
 

Misc/NEWS.d/next/Library/2021-08-17-21-41-39.bpo-44587.57OKSz.rst

@@ -0,0 +1,4 @@
+Fix BooleanOptionalAction to not automatically add a default string when the
+default was manually specified using ``%(default)s`` or the default was set to
+SUPPRESS.  Add a default string for ``default: None`` to differentiate when
+the unset state has a different meaning.