3.1 Help switch

The add_optparse_help_option() method is used to set up the cooperation between the command line and configuration file parsers to automatically generate configuration file help text using a command line switch.

add_optparse_help_option( option_group[, switches][, dest][, help])

option_group is a required positional argument and must be set to an instance of the optparse module's OptionParser class or an option group of that class. The OptionParser instance must also be passed into the parse() method.

switches is an optional keyword argument and is used to set the command line switches the user can use to invoke the configuration file help printout. switches must be a tuple and defaults to ('--cfghelp',) when switches is omitted.

dest is an optional string keyword argument and is used set the name of the destination attribute of the options object returned by the command line option parser. When omitted, dest defaults to 'cfgparse_help'.

help is an optional string keyword argument and is used to set the command line switch help string. When omitted a reasonable default help string is utilized.

For example:

# file: coop_help.py
import optparse, cfgparse
o = optparse.OptionParser()
c = cfgparse.ConfigParser()

c.add_optparse_help_option(o)
c.add_option('retries', type='int', help='Maximum number of retries.')
c.add_option('timeout', type='int', metavar='#SEC', 
             help='Seconds between retries.')
(opts,args) = c.parse(o)

print "Should not get here if command line help switch present"

Results in:

$ python coop_help.py --help
usage: coop_help.py [options]

options:
  -h, --help  show this help message and exit
  --cfghelp   Show configuration file help and exit.

$ python coop_help.py --cfghelp
Configuration file options:
  retries=RETRIES  Maximum number of retries.
  timeout=#SEC     Seconds between retries.