6.20.3.3 Option actions

###
6.20.3.3 Option actions

The various option actions all have slightly different requirements and effects. Except for the ``help'' action, you must supply at least one other keyword argument when creating the `Option`; the exact requirements for each action are listed here.

store
  [relevant: type, dest, nargs, choices]

  The option must be followed by an argument, which is converted to a value according to type and stored in dest. If `nargs > 1`, multiple arguments will be consumed from the command line; all will be converted according to type and stored to dest as a tuple. See section 6.20.3, ``Option types,'' below.

  If choices (a sequence of strings) is supplied, the type defaults to ``choice''.

  If type is not supplied, it defaults to ``string''.

  If dest is not supplied, `optparse` derives a destination from the first long option strings (e.g., --foo-bar becomes `foo_bar`). If there are no long option strings, `optparse` derives a destination from the first short option string (e.g., -f becomes `f`).

  Example:

      make_option("-f")
      make_option("-p", type="float", nargs=3, dest="point")

  Given the following command line:

      -f foo.txt -p 1 -3.5 4 -fbar.txt

  `optparse` will set:

      values.f = "bar.txt"
      values.point = (1.0, -3.5, 4.0)

  (Actually, `values.f` will be set twice, but only the second time is visible in the end.)

store_const
  [required: const, dest]

  The const value supplied to the `Option` constructor is stored in dest.

  Example:

      make_option("-q", "--quiet",
             action="store_const", const=0, dest="verbose"),
      make_option("-v", "--verbose",
             action="store_const", const=1, dest="verbose"),
      make_option("--noisy",
             action="store_const", const=2, dest="verbose"),

  If --noisy is seen, `optparse` will set:

      values.verbose = 2

store_true
  [required: dest]

  A special case of ``store_const'' that stores `True` to dest.

store_false
  [required: dest]

  Like ``store_true'', but stores `False`

  Example:

      make_option(None, "--clobber", action="store_true", dest="clobber")
      make_option(None, "--no-clobber", action="store_false", dest="clobber")

append
  [relevant: type, dest, nargs, choices]

  The option must be followed by an argument, which is appended to the list in dest. If no default value for dest is supplied (i.e. the default is `None`), an empty list is automatically created when `optparse` first encounters this option on the command-line. If `nargs > 1`, multiple arguments are consumed, and a tuple of length nargs is appended to dest.

  The defaults for type and dest are the same as for the ``store'' action.

  Example:

      make_option("-t", "--tracks", action="append", type="int")

  If -t3 is seen on the command-line, `optparse` does the equivalent of:

      values.tracks = []
      values.tracks.append(int("3"))

  If, a little later on, --tracks=4 is seen, it does:

      values.tracks.append(int("4"))

  See ``Error handling'' (section 6.20.2) for information on how `optparse` deals with something like --tracks=x.

count
  [required: dest]

  Increment the integer stored at dest. dest is set to zero before being incremented the first time (unless you supply a default value).

  Example:

      make_option("-v", action="count", dest="verbosity")

  The first time -v is seen on the command line, `optparse` does the equivalent of:

      values.verbosity = 0
      values.verbosity += 1

  Every subsequent occurrence of -v results in:

      values.verbosity += 1

callback
  [required: callback; relevant: type, nargs, callback_args, callback_kwargs]

  Call the function specified by callback. The signature of this function should be:

      func(option : Option,
           opt : string,
           value : any,
           parser : OptionParser,
           *args, **kwargs)

  Callback options are covered in detail in section 6.20.4, ``Callback Options.''

help
  [required: none]

  Prints a complete help message for all the options in the current option parser. The help message is constructed from the usage string passed to `OptionParser`'s constructor and the help string passed to every option.

  If no help string is supplied for an option, it will still be listed in the help message. To omit an option entirely, use the special value `optparse.SUPPRESS_HELP`.

  Example:

      from optparse import Option, OptionParser, SUPPRESS_HELP

      usage = "usage: %prog [options]"
      parser = OptionParser(usage, option_list=[
        make_option("-h", "--help", action="help"),
        make_option("-v", action="store_true", dest="verbose",
                    help="Be moderately verbose")
        make_option("--file", dest="filename",
                    help="Input file to read data from"),
        make_option("--secret", help=SUPPRESS_HELP)
      ])

  If `optparse` sees either -h or --help on the command line, it will print something like the following help message to stdout:

      usage: <yourscript> [options]

      options:
        -h, --help        Show this help message and exit
        -v                Be moderately verbose
        --file=FILENAME   Input file to read data from

  After printing the help message, `optparse` terminates your process with `sys.exit(0)`.

version
  [required: none]

  Prints the version number supplied to the `OptionParser` to stdout and exits. The version number is actually formatted and printed by the `print_version()` method of `OptionParser`. Generally only relevant if the version argument is supplied to the `OptionParser` constructor.