Writing a help for python script

Question

I am trying to make my python script very user friendly, so I like to write some sort of help for it. What is your advise for this? I could just put in some logic that if the user passed help as a paramater to the script, they get help. Is there a best practise or convention for this?

Asked By: dublintech

||

Source

Answer 1

Use argparse.

For example, with test.py:

import argparse

parser=argparse.ArgumentParser(
    description='''My Description. And what a lovely description it is. ''',
    epilog="""All is well that ends well.""")
parser.add_argument('--foo', type=int, default=42, help='FOO!')
parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
args=parser.parse_args()

Running

% test.py -h

yields

usage: test.py [-h] [--foo FOO] [bar [bar ...]]

My Description. And what a lovely description it is.
    
positional arguments:
  bar         BAR!
    
optional arguments:
  -h, --help  show this help message and exit
  --foo FOO   FOO!
    
All is well that ends well.

Answered By: unutbu

Answer 2

Best practice is to use argparse to handle all your commandline arguments. It includes a default --help which you can customize to your likings.

Here’s the simplest example:

import argparse

parser = argparse.ArgumentParser(description='This is my help')

args = parser.parse_args()

Which results in:

% python argparse_test.py -h
usage: argparse_test.py [-h]

This is my help

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

You can define all your arguments with argparse and set a help message for each one of them. The resulting filtered/validated arguments are returned by parser.parse_args().

Answered By: Rob Wouters

Answer 3

An alternative to the built-in argparse is a 3rd-party package called Click which features "automatic help page generation" and "arbitrary nesting of commands" (which also produces nested help pages). Internally, it’s based on argparse, but, for me, makes the creation of complex CLI more convenient using decorators.

Here’s a sample code:

import click

@click.command()
@click.argument("things", nargs=-1)
@click.option("-t", show_default=True, default="int", help="Data type")
@click.option("-o", help="Output format")
def combine(things, t):
    """Combines things into a single element"""
    pass

if __name__ == "__main__":
    combine()

And the generated help page:

$ python myapp.py --help
Usage: myapp.py [OPTIONS] [THINGS]...

  Combines things into a single element

Options:
  -t TEXT  Data type  [default: int]
  -o TEXT  Output format
  --help   Show this message and exit.

One of the nice things about it is that it uses the method docstrings as part of the help page, which is convenient because the docstring can now be used both for developer documentation and for script usage help.

You can also have nested command groups:

import click

@click.command()
@click.argument("numbers", nargs=-1)
@click.option("-e", help="Extra option for add")
def add(numbers, e):
    """Adds numbers"""
    print(f"This method should add {numbers}")

@click.command()
@click.argument("numbers", nargs=-1)
@click.option("-e", help="Extra option for mul")
def mul(numbers, e):
    """Multiplies numbers"""
    print(f"This method should multiply {numbers}")

@click.group()
def calc():
    pass

calc.add_command(add)
calc.add_command(mul)

if __name__ == "__main__":
    calc()

And it will produce nested help pages:

$ python myapp.py --help
Usage: myapp.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  add  Adds numbers
  mul  Multiplies numbers

$ python myapp.py add --help
Usage: myapp.py add [OPTIONS] [NUMBERS]...

  Adds numbers

Options:
  -e TEXT  Extra option for add
  --help   Show this message and exit.

$ python myapp.py mul --help
Usage: myapp.py mul [OPTIONS] [NUMBERS]...

  Multiplies numbers

Options:
  -e TEXT  Extra option for mul
  --help   Show this message and exit.

For more information, see the Documenting Scripts section of the docs.

Answered By: Gino Mempin

Writing a help for python script

Question:

Answers: