6.20.4.2 How callbacks are called

All callbacks are called as follows:

func(option, opt_str, value, parser, *args, **kwargs)

where

option
is the Option instance that's calling the callback
opt_str
is the option string seen on the command-line that's triggering the callback. (If an abbreviated long option was used, opt_str will be the full, canonical option string--e.g. if the user puts "-foo" on the command-line as an abbreviation for "-foobar", then opt_str will be "-foobar".)
value
is the argument to this option seen on the command-line. optparse will only expect an argument if type is set; the type of value will be the type implied by the option's type. If type for this option is None (no argument expected), then value will be None. If nargs > 1, value will be a tuple of values of the appropriate type.
parser
is the OptionParser instance driving the whole thing, mainly useful because you can access some other interesting data through its instance attributes:
parser.largs
the current list of leftover arguments, ie. arguments that have been consumed but are neither options nor option arguments. Feel free to modify parser.largs, e.g. by adding more arguments to it. (This list will become args, the second return value of parse_args().)
parser.rargs
the current list of remaining arguments, ie. with opt_str and value (if applicable) removed, and only the arguments following them still there. Feel free to modify parser.rargs, e.g. by consuming more arguments.
parser.values
the object where option values are by default stored (an instance of optparse.OptionValues). This lets callbacks use the same mechanism as the rest of optparse for storing option values; you don't need to mess around with globals or closures. You can also access or modify the value(s) of any options already encountered on the command-line.
args
is a tuple of arbitrary positional arguments supplied via the callback_args option attribute.
kwargs
is a dictionary of arbitrary keyword arguments supplied via callback_kwargs.

See About this document... for information on suggesting changes.