483

Suppose I have the following argparse snippet:

diags.cmdln_parser.add_argument( '--scan-time',
                     action  = 'store',
                     nargs   = '?',
                     type    = int,
                     default = 5,
                     help    = "Wait SCAN-TIME seconds between status checks.")

Currently, --help returns:

usage: connection_check.py [-h]
                             [--version] [--scan-time [SCAN_TIME]]

          Test the reliability/uptime of a connection.



optional arguments:
-h, --help            show this help message and exit
--version             show program's version number and exit
--scan-time [SCAN_TIME]
                    Wait SCAN-TIME seconds between status checks.

I would prefer something like:

--scan-time [SCAN_TIME]
                    Wait SCAN-TIME seconds between status checks.
                    (Default = 5)

Peeking at the help formatter code revealed limited options. Is there a clever way to get argparse to print the default value for --scan-time in a similar fashion, or should I just subclass the help formatter?

5
  • 7
    You may be interested in docopt. I've never looked at argparse again. Commented Aug 28, 2012 at 0:28
  • 36
    @PauloScardine - Being built in to the language is a major benefit for argparse.
    – jordanm
    Commented Aug 28, 2012 at 0:32
  • 1
    @PauloScardine: Pulling a non-standard library into my current project will indeed be a pain, but I sure like the look of docopt's output. Thanks for the tip!
    – JS.
    Commented Aug 28, 2012 at 17:47
  • @JS. you say "Pulling a non-standard library into my current project will indeed be a pain" Really? There are plenty of very useful libraries at pypi. In my context it is easy to pull in a non-standard library. It is sad, if it is hard in your context.
    – guettli
    Commented Jun 4, 2018 at 12:17
  • 7
    @guettli: That project was for a commercial embedded project. You're right installation was easy. Getting approval from corporate legal was a nightmare.
    – JS.
    Commented Jun 4, 2018 at 16:55

4 Answers 4

701

Use the argparse.ArgumentDefaultsHelpFormatter formatter:

parser = argparse.ArgumentParser(
    # ... other options ...
    formatter_class=argparse.ArgumentDefaultsHelpFormatter)

To quote the documentation:

The other formatter class available, ArgumentDefaultsHelpFormatter, will add information about the default value of each of the arguments.

Note that this only applies to arguments that have help text defined; with no help value for an argument, there is no help message to add information about the default value to.

The exact output for your scan-time option then becomes:

  --scan-time [SCAN_TIME]
                        Wait SCAN-TIME seconds between status checks.
                        (default: 5)
11
  • 25
    Can I control that only the arguments with an explicit default= show the default value? Since I don't like the 'default: None' texts.
    – Ziyuan
    Commented Jun 7, 2013 at 9:55
  • 29
    You can set the default to SUPPRESS: default=argparse.SUPPRESS. Note that in that case no attribute will be added to the namespace result if that argument was omitted, see the default documentation. Commented Jun 7, 2013 at 10:18
  • 12
    Note that you need to specify this for each subparser created as well.
    – KomodoDave
    Commented Nov 19, 2014 at 10:59
  • 3
    What do I do if I've already set a formatter_class? Commented Jan 27, 2021 at 21:34
  • 9
    @AzorAhai-him- create a new class that subclasses both and use that as the formatter; e.g. class RawTextArgumentDefaultsHelpFormatter(argparse.RawTextHelpFormatter, argparse.ArgumentDefaultsHelpFormatter): pass, parser = argparse.ArgumentParser(..., formatter_class=RawTextArgumentDefaultsHelpFormatter). The two variants override two different aspects of the base help formatter and so can be combined trivially. Commented Feb 1, 2021 at 0:04
316

Add '%(default)s' to the help parameter to control what is displayed.

parser.add_argument("--type", default="toto", choices=["toto","titi"],
                              help = "type (default: %(default)s)")

Notes:

  • It is %+ default in parenthesis + format characters (not to be confused with curly brackets {default} we find in format or f-string)
  • Don't forget to add the "specifier character" for the type representation at the end (i.e. s for strings, d for integers, f for floats, etc.)
  • You can also add the usual "printf" format specifiers (like number of digits for floats, leading zeros, etc.)

You can refer to printf documentation for more details.

9
  • 22
    I like this option because I'd already used the format_class=argparse.RawTestHelpFormatter and didn't feel like farting around with OOP.
    – user8710
    Commented Nov 14, 2013 at 18:37
  • 34
    Don't forget to include the variable 'type' in your formatting string-- e.g. '%(default)s' for a string, or '%(default)d' for a digit.
    – strongMA
    Commented Jan 23, 2014 at 22:26
  • 6
    I like this solution much better, it's far simpler, and I don't have to explicitly handle arguments with no default values. Commented Aug 22, 2018 at 14:06
  • @mqsoh multiple inheritance actually just worked, but unfortunately is not public API: stackoverflow.com/a/52025430/895245 Commented Aug 26, 2018 at 10:41
  • 1
    I like this because changing the formatter class adds a bunch of "(default: None)" everywhere which is cluttering the help. Commented Aug 22, 2019 at 3:39
23

Wrapper class

This is the most reliable and DRY approach I've found so far to both show defaults and use another formatter such as argparse.RawTextHelpFormatter at the same time:

#!/usr/bin/env python3

import argparse

class ArgumentParserWithDefaults(argparse.ArgumentParser):
    def add_argument(self, *args, help=None, default=None, **kwargs):
        if help is not None:
            kwargs['help'] = help
        if default is not None and args[0] != '-h':
            kwargs['default'] = default
            if help is not None:
                kwargs['help'] += ' Default: {}'.format(default)
        super().add_argument(*args, **kwargs)

parser = ArgumentParserWithDefaults(
    formatter_class=argparse.RawTextHelpFormatter
)
parser.add_argument('-a', default=13, help='''my help
for a''')
parser.add_argument('-b', default=42, help='''my help
for b''')
parser.add_argument('--no-default', help='''my help
for no-default''')
parser.add_argument('--no-help', default=101)

parser.print_help()
print()
print(parser.parse_args())

Output:

usage: main.py [-h] [-a A] [-b B] [--no-default NO_DEFAULT]
               [--no-help NO_HELP]

optional arguments:
  -h, --help            show this help message and exit
  -a A                  my help
                        for a Default: 13
  -b B                  my help
                        for b Default: 42
  --no-default NO_DEFAULT
                        my help
                        for no-default
  --no-help NO_HELP

Namespace(a=13, b=42, no_default=None, no_help=101)

ArgumentDefaultsHelpFormatter + RawTextHelpFormatter multiple inheritance

Multiple inheritance just works, but it does not seem to be public API:

#!/usr/bin/env python3

import argparse

class RawTextArgumentDefaultsHelpFormatter(
    argparse.ArgumentDefaultsHelpFormatter,
    argparse.RawTextHelpFormatter
):
    pass

parser = argparse.ArgumentParser(
    formatter_class=RawTextArgumentDefaultsHelpFormatter
)
parser.add_argument('-a', default=13, help='''my help
for a''')
parser.add_argument('-b', default=42, help='''my help
for b''')
parser.print_help()

Output:

usage: a.py [-h] [-a A] [-b B]

optional arguments:
  -h, --help  show this help message and exit
  -a A        my help
              for a (default: 13)
  -b B        my help
              for b (default: 42)

It just works works because as we can see trivially from the sources https://github.com/python/cpython/blob/v3.6.5/Lib/argparse.py#L648 that:

  • RawTextHelpFormatter implements _split_lines
  • ArgumentDefaultsHelpFormatter implements _get_help_string

so we can guess that they will work together just fine.

However, this does not seem to be public API, and neither are the methods of formatter_class, so I don't think there is a public API way to do it currently. argparse docstring says:

All other classes in this module are considered implementation details. (Also note that HelpFormatter and RawDescriptionHelpFormatter are only considered public as object names -- the API of the formatter objects is still considered an implementation detail.)

See also: Customize argparse help message

Tested on Python 3.6.5.

1
  • 1
    Great ! Finally have both the formatted docstring And default arguments printed. Thanks
    – Sylvain
    Commented Jan 28, 2020 at 2:27
10

It is often useful to be able to automatically include the default values in the help output, but only those that were explicitly specified (with default=..). The methods already mentioned have some shortcomings in this respect:

  • The ArgumentDefaultsHelpFormatter method prints out (default: None) for every argument whose default was not explicitly specified, and (default: False) for 'flags' (action='store_true'). This clutters the help output. To avoid it, default=argparse.SUPPRESS needs to be manually added for each such argument.

  • The '%(default)s' method requires manually adding it to all the arguments' help strings that we do want printed in help.

Both methods end up needing manual intervention to print out only the "right" defaults. One way to do this automatically is to augment the ArgumentDefaultsHelpFormatter to ignore the Nones and Falses default values:

class ExplicitDefaultsHelpFormatter(argparse.ArgumentDefaultsHelpFormatter):
    def _get_help_string(self, action):
        if action.default is None or action.default is False:
            return action.help
        return super()._get_help_string(action)

Use it in place of ArgumentDefaultsHelpFormatter:

parser = argparse.ArgumentParser(
        formatter_class=ExplicitDefaultsHelpFormatter
                )

This will print only the explicitly set default values in the help output.

Note: if an argument's default was explicitly set as None or False, it won't be shown in help with this class; add %(default)s string to help for that argument if you want it in the help output.

2
  • 1
    This does not display the default for arguments with default=0. Alternative: if action.default is None or action.default is False.
    – sfinkens
    Commented Jul 20, 2022 at 13:46
  • 1
    @sfinkens Thanks for pointing that out! It was due to an implicit intbool type conversion in the in check. I have replaced that line with the is test, as in your suggestion.
    – exquo
    Commented Nov 18, 2023 at 13:04

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.