Python Tutorial: argparse advanced-help with additional options

Example script: https://gist.github.com/thingsiplay/ae9a26322cd5830e52b036ab411afd1f

Hi all. I just wanted to share a way to handle a so called advanced help menu, where additional options are listed that are otherwise hidden with regular help. Hidden options should still function. This is just to have less clutter in normal view.

I've researched the web to see how people does it, and this is the way I like most so far. If you think this is problematic, please share your thoughts. This is for a commandline terminal application, that could also be automated through a script.

How it works on a high level

Before the ArgumentParser() is called, we check the sys.argv for the trigger option --advanced-help. Depending on this we set a variable to true or false. Then with the setup of the parser after the ArgumenParser() call, we add the --advanced-help option to the list of regular help.

advanced_help = False
for arg in sys.argv:
    if arg == "--":
        break
    if arg == "--advanced-help":
        advanced_help = True

parser = argparse.ArgumentParser()

Continue setting up your options as usual. But for the help description of those you want to exclude when using just regular -h, add an inline if else statement (ternary statement). This statement will put the help description only if advanced_help variable is true, otherwise it puts argparse.SUPPRESS to hide the option. Do this with all the options you want to hide.

parser.add_argument(
    "-c",
    "--count",
    action="store_true",
    default=False,
    help="print only a count of matching items per list, output file unaffected"
    if advanced_help
    else argparse.SUPPRESS,
)

At last we need to actually parse what you just setup. For this we need to assign our custom list, that is based on the sys.argv, plus the regular --help option. This way we can use --advanced-help without the need for -h or --help in addition to show any help message.

if advanced_help:
    args = parser.parse_args(sys.argv[0:0] + ["--help"] + sys.argv[1:])
else:
    args = parser.parse_args()

Run following program once with ./thing.py -h and ./thing.py --advanced-help.

Python Tutorial: argparse advanced-help with additional options

https://gist.github.com/thingsiplay/ae9a26322cd5830e52b036ab411afd1fOpen link View original on beehaw.org

Comments2

thingsiplay

beehaw.org

BTW, you can also have a short description instead suppressing the option. In example:

parser.add_argument(
    "-s",
    "--sort",
    action="append",
    help="sort all game items by value of chosen key, before filter, *multi"
    if advanced_help
    else "sort all items",
)

instead hiding the option, with --help the short description "sort all items" is listed, while the advanced help would then show the long help. Just an additional thing with the above technique is possible.

logging_strict

programming.dev

why click is based on optparse and not argparse

Applies only to optional args long help

Applies only to subcommands short help

Special mention to how to document positional args. The docs explains the intentional lack of help kwarg for positional args.

./thing.py -h
./thing.py subcommand --help

Lists all the subcommands with one line short description for each subcommand.

Lists detailed docs of one subcommand

My opinion having used both argparse and click, click is simpler cleaner and less time consuming.