Add ArgumentDefaultsHelpFormatter.

3 files changed, 78 insertions, 1 deletions

diff --git a/argparse.py b/argparse.py
index 4ae1c89..8ee556b 100644
--- a/argparse.py
+++ b/argparse.py
@@ -549,7 +549,7 @@ class HelpFormatter(object):
         if params.get('choices') is not None:

             choices_str = ', '.join([str(c) for c in params['choices']])

             params['choices'] = choices_str

-        return action.help % params

+        return self._get_help_string(action) % params

 

     def _iter_indented_subactions(self, action):

         try:

@@ -571,6 +571,9 @@ class HelpFormatter(object):
         return _textwrap.fill(text, width, initial_indent=indent,

                                            subsequent_indent=indent)

 

+    def _get_help_string(self, action):

+        return action.help

+

 

 class RawDescriptionHelpFormatter(HelpFormatter):

 

@@ -584,6 +587,18 @@ class RawTextHelpFormatter(RawDescriptionHelpFormatter):
         return text.splitlines()

 

 

+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

+

+

 # =====================

 # Options and Arguments

 # =====================

diff --git a/doc/source/ArgumentParser.rst b/doc/source/ArgumentParser.rst
index 1bf5e63..8a103dd 100644
--- a/doc/source/ArgumentParser.rst
+++ b/doc/source/ArgumentParser.rst
@@ -176,6 +176,10 @@ Sometimes, several parsers share a common set of arguments. Rather than repeatin
 formatter_class
 ---------------
 
+ArgumentParser objects allow the help formatting to be customized by specifying an alternate formatting class.
+Currently, there are three such classes: ``argparse.RawDescriptionHelpFormatter``, ``argparse.RawTextHelpFormatter`` and ``argparse.ArgumentDefaultsHelpFormatter``.
+The first two allow more control over how textual descriptions are displayed, while the last automatically adds information about argument default values.
+
 By default, ArgumentParser objects line-wrap the description_ and epilog_ texts in command-line help messages::
 
   >>> parser = argparse.ArgumentParser(
@@ -224,6 +228,23 @@ When you have description_ and epilog_ that is already correctly formatted and s
 
 If you want to maintain whitespace for all sorts of help text (including argument descriptions), you can use ``argparse.RawTextHelpFormatter``.
 
+The other formatter class available, ``argparse.ArgumentDefaultsHelpFormatter``, will add information about the default value of each of the arguments::
+
+  >>> parser = argparse.ArgumentParser(
+  ...     prog='PROG',
+  ...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+  >>> 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 ...]]
+
+  positional arguments:
+    bar         BAR! (default: [1, 2, 3])
+
+  optional arguments:
+    -h, --help  show this help message and exit
+    --foo FOO   FOO! (default: 42)
+
 
 conflict_handler
 ----------------
diff --git a/test/test_argparse.py b/test/test_argparse.py
index 33bec2d..67026d9 100644
--- a/test/test_argparse.py
+++ b/test/test_argparse.py
@@ -3176,6 +3176,47 @@ class TestHelpRawDescription(HelpTestCase):
         '''

     version = ''

 

+

+class TestHelpArgumentDefaults(HelpTestCase):

+    """Test the ArgumentDefaultsHelpFormatter"""

+

+    parser_signature = Sig(

+        prog='PROG', formatter_class=argparse.ArgumentDefaultsHelpFormatter,

+        description='description')

+

+    argument_signatures = [

+        Sig('--foo', help='foo help - oh and by the way, %(default)s'),

+        Sig('--bar', action='store_true', help='bar help'),

+        Sig('spam', help='spam help'),

+        Sig('badger', nargs='?', default='wooden', help='badger help'),

+    ]

+    argument_group_signatures = [

+        (Sig('title', description='description'),

+         [Sig('--baz', type=int, default=42, help='baz help')]),

+    ]

+    usage = '''\

+        usage: PROG [-h] [--foo FOO] [--bar] [--baz BAZ] spam [badger]

+        '''

+    help = usage + '''\

+

+        description

+

+        positional arguments:

+          spam        spam help

+          badger      badger help (default: wooden)

+

+        optional arguments:

+          -h, --help  show this help message and exit

+          --foo FOO   foo help - oh and by the way, None

+          --bar       bar help (default: False)

+

+        title:

+          description

+

+          --baz BAZ   baz help (default: 42)

+        '''

+    version = ''

+

 # =====================================

 # Optional/Positional constructor tests

 # =====================================