Python @programming.dev thingsiplay @beehaw.org 3w ago

Python Tutorial: argparse advanced-help with additional options

gist.github.com Python Tutorial: argparse advanced-help with additional options

Python Tutorial: argparse advanced-help with additional options - thing.py

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.

9 comments

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.
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.
- Nice. There is a reason why the standard library of Python does not get rid of optparse. optparse was I think marked to be removed in the future, but its no longer deprecated and will stay in the library.
  
  Click looks good and I would have looked in more detail. The problem to me is, it is a dependency. I usually write and try to write Python programs without external library dependency, unless it is absolutely necessary (like GUI or BeautifulSoup). Click "might" be a better alternative, but it is "only" something that does it a little bit better. This is not a reason for me to use an external library.
  
  What is the root basis of your external package reluctance? Please explain cuz that's really where the juicy story lies.
  
  As technologists things change and advance and we have to adapt (or not) with the times. Maintaining the universe by ourselves is impossible, instead almost all of our tech choices are from what's available. And only if/when that is insufficient do we roll up our sleeves.
  
  More and more packages are using click. So there is a good chance if you look at your requirements .lock file that it's already a transitive dependency from another dependency.
  
  Or said another way, show me 5 popular packages that use argparse and not click and use dataclasses and not attrs

9 comments