twisted.python.usage.Options : API documentation

An option list parser class

optFlags and optParameters are lists of available parameters which your program can handle. The difference between the two is the 'flags' have an on(1) or off(0) state (off by default) whereas 'parameters' have an assigned value, with an optional default. (Compare '--verbose' and '--verbosity=2')

optFlags is assigned a list of lists. Each list represents a flag parameter, as so:

| optFlags = [['verbose', 'v', 'Makes it tell you what it doing.'], | ['quiet', 'q', 'Be vewy vewy quiet.']]

As you can see, the first item is the long option name (prefixed with '--' on the command line), followed by the short option name (prefixed with '-'), and the description. The description is used for the built-in handling of the --help switch, which prints a usage summary.

optParameters is much the same, except the list also contains a default value:

| optParameters = [['outfile', 'O', 'outfile.log', 'Description...']]

A coerce function can also be specified as the last element: it will be called with the argument and should return the value that will be stored for the option. This function can have a coerceDoc attribute which will be appended to the documentation of the option.

subCommands is a list of 4-tuples of (command name, command shortcut, parser class, documentation). If the first non-option argument found is one of the given command names, an instance of the given parser class is instantiated and given the remainder of the arguments to parse and self.opts[command] is set to the command name. For example:

In this case, "<program> holyquest --horseback --for-grail" will cause HolyQuestOptions to be instantiated and asked to parse ['--horseback', '--for-grail']. Currently, only the first sub-command is parsed, and all options following it are passed to its parser. If a subcommand is found, the subCommand attribute is set to its name and the subOptions attribute is set to the Option instance that parses the remaining options. If a subcommand is not given to parseOptions, the subCommand attribute will be None. You can also mark one of the subCommands to be the default.

| defaultSubCommand = 'holyquest'

In this case, the subCommand attribute will never be None, and the subOptions attribute will always be set.

If you want to handle your own options, define a method named opt_paramname that takes (self, option) as arguments. option will be whatever immediately follows the parameter on the command line. Options fully supports the mapping interface, so you can do things like 'self["option"] = val' in these methods.

Advanced functionality is covered in the howto documentation, available at http://twistedmatrix.com/projects/core/documentation/howto/options.html, or doc/howto/options.html in your Twisted directory.

Method	__init__	Undocumented
Method	__hash__	Define a custom hash function so that Options instances can be used
Method	opt_help	Display this help and exit.
Method	opt_version	Undocumented
Method	parseOptions	The guts of the command-line parser.
Method	postOptions	I am called after the options are parsed.
Method	parseArgs	I am called with any leftover arguments which were not options.
Method	__str__	Undocumented
Method	getSynopsis	Returns a string containing a description of these options and how to
Method	getUsage	Undocumented
Method	_generic_flag	Undocumented
Method	_gather_flags	Gather up boolean (flag) options.
Method	_gather_parameters	Gather options which take a value.
Method	_gather_handlers	Gather up options with their own handler methods.

t.p.u.Options(dict) : class documentation