optparse's ability to generate help and usage text automatically is useful for creating user-friendly command-line interfaces. All you have to do is supply a help value for each option, and optionally a short usage message for your whole program. Here's an OptionParser populated with user-friendly (documented) options:
usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
action="store_true", dest="verbose", default=True,
help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose",
help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
metavar="FILE", help="write output to FILE"),
parser.add_option("-m", "--mode",
default="intermediate",
help="interaction mode: novice, intermediate, "
"or expert [default: %default]")
If optparse encounters either -h or --help on the command-line, or if you just call parser.print_help(), it prints the following to standard output:
usage: <yourscript> [options] arg1 arg2 options: -h, --help show this help message and exit -v, --verbose make lots of noise [default] -q, --quiet be vewwy quiet (I'm hunting wabbits) -f FILE, --filename=FILE write output to FILE -m MODE, --mode=MODE interaction mode: novice, intermediate, or expert [default: intermediate]
(If the help output is triggered by a help option, optparse exits after printing the help text.)
There's a lot going on here to help optparse generate the best possible help message:
usage = "usage: %prog [options] arg1 arg2"
optparse expands "%prog" in the usage string to the name of the current
program, i.e. os.path.basename(sys.argv[0]). The expanded string
is then printed before the detailed option help.
If you don't supply a usage string, optparse uses a bland but sensible
default: ``usage: %prog [options]", which is fine if your script
doesn't take any positional arguments.
-m MODE, --mode=MODE
Here, ``MODE'' is called the meta-variable: it stands for the argument
that the user is expected to supply to -m/--mode. By default,
optparse converts the destination variable name to uppercase and uses
that for the meta-variable. Sometimes, that's not what you want--for example, the --filename option explicitly sets
metavar="FILE", resulting in this automatically-generated option
description:
-f FILE, --filename=FILE
This is important for more than just saving space, though: the manually written help text uses the meta-variable ``FILE'' to clue the user in that there's a connection between the semi-formal syntax ``-f FILE'' and the informal semantic description ``write output to FILE''. This is a simple but effective way to make your help text a lot clearer and more useful for end users.
%default in
the help string--optparse will replace it with str() of the
option's default value. If an option has no default value (or the
default value is None), %default expands to none.
When dealing with many options, it is convenient to group these options for better help output. An OptionParser can contain several option groups, each of which can contain several options.
Continuing with the parser defined above, adding an OptionGroup to a parser is easy:
group = OptionGroup(parser, ``Dangerous Options'', ``Caution: use these options at your own risk. `` ``It is believed that some of them bite.'') group.add_option(``-g'', action=''store_true'', help=''Group option.'') parser.add_option_group(group)
This would result in the following help output:
usage: [options] arg1 arg2 options: -h, --help show this help message and exit -v, --verbose make lots of noise [default] -q, --quiet be vewwy quiet (I'm hunting wabbits) -fFILE, --file=FILE write output to FILE -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate' [default], 'expert' Dangerous Options: Caution: use of these options is at your own risk. It is believed that some of them bite. -g Group option.