--advanced-help for argparse

Ideas
1

When using argparse, users can get a list of parameters by passing the -h or --help parameter.
Sometimes, it’d be nice to hide debug parameters or rare usage parameters from the list of help and only show these w/ an --advanced-help parameter.

2

Does this really need special support in argparse though? In such a case, I would do

import argparse


def make_parser(advanced_help=False):
    def advanced(description):
        return description if advanced_help else argparse.SUPPRESS

    p = argparse.ArgumentParser(prog="foo", description="Program with advanced options")
    p.add_argument("-s", "--simple-arg", metavar="VALUE", help="simple argument")
    p.add_argument(
        "-a", "--advanced-arg", help=advanced("advanced option that does this and that")
    )
    p.add_argument("-H", "--advanced-help", action="store_true", help="show the full list of options")
    return p


args = make_parser().parse_args()
if args.advanced_help:
    make_parser(advanced_help=True).print_help()
    raise SystemExit
3

From argparse — Parser for command-line options, arguments and sub-commands — Python 3.8.17 documentation

argparse supports silencing the help entry for certain options, by setting the help value to argparse.SUPPRESS:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

optional arguments:
  -h, --help show this help message and exit

Not the greatest for having an advanced help, but okay if you just want a hidden option.

4

We actually do something like this…basically prefix a magic string in front of help which is then used to indicate to replace the help string with SUPPRESS just before print_help() is called.
Without it being part of argparse, you have fun edge cases like this though: mutually exclusive group w/ all parameters argparse.SUPPRESS'd causes an assert · Issue #98666 · python/cpython · GitHub

5

That sounds like argparse.SUPPRESS just has a bug that should be fixed. I don’t see how this bug strengthens the case for adding your requested functionality to argparse. (To the contrary actually: if this bug is only noticed now, there must not be a ton of people who use argparse.SUPPRESS.)

6

When I need that some arguments change the way how other arguments are parsed, I first parse the deciding arguments then I parse the rest:

import argparse

def parse_arguments(args=None):
    deciding_args_parser = argparse.ArgumentParser(add_help=False)
    deciding_args_parser.add_argument(
            '--advanced-help', required=False, action='store_true',
            help='show the full list of options')
    deciding_args, _ = deciding_args_parser.parse_known_args(args)

    parser = argparse.ArgumentParser(
            description='This is a demonstration of argument parser.',
            parents=[deciding_args_parser])
    parser.add_argument('-b', '--basic-option', help='Just a basic option.')
    parser.add_argument(
            '-a', '--advanced-option',
            help=('Advanced option!' if deciding_args.advanced_help
                else argparse.SUPPRESS))
    return parser.parse_args(
            args + (['-h'] if deciding_args.advanced_help else []))

parse_arguments(['-h'])

usage: ipykernel_launcher.py [-h] [--advanced-help] [-b BASIC_OPTION]

This is a demonstration of argument parser.

options:
  -h, --help            show this help message and exit
  --advanced-help       show the full list of options
  -b BASIC_OPTION, --basic-option BASIC_OPTION
                        Just a basic option.

parse_arguments(['--advanced-help'])

usage: ipykernel_launcher.py [-h] [--advanced-help] [-b BASIC_OPTION]
                             [-a ADVANCED_OPTION]

This is a demonstration of argument parser.

options:
  -h, --help            show this help message and exit
  --advanced-help       show the full list of options
  -b BASIC_OPTION, --basic-option BASIC_OPTION
                        Just a basic option.
  -a ADVANCED_OPTION, --advanced-option ADVANCED_OPTION
                        Advanced option!
7

hmm…true. Does sound like folks are doing this different ways…the root parser idea sounds reasonable. Might be worth a docs update?

8

I had the same use case than you. What I did was to group all the advanced options under the same group, adding a help message as usual.

Then I crafted a special HelpAction to hide or not the help of the advanced options.
I set this action for -h and for -xh (the latter is for show the advanced options)

So when the user pass -h, he/she will see all the non-advanced options./ When -xh is given, the full help is displayed.

In my case I also have a custom HelpFormatter but probably you can resolve the hide of the advanced options without it.

9

We actually group functionality in different python files and then the main python file grabs all the parsers from the other python files. Sounds like we can pass an advanced option to the other parsers when this is done.

Also sounds like everyone is coming up w/ different ways to do the same concept :slight_smile: