Each Option instance represents a set of synonymous command-line option strings, e. You can specify any number of short or long option strings, but you must specify at least one overall option string. The keyword arguments define attributes of the new Option object. The most important option attribute is action , and it largely determines which other attributes are relevant or required.
If you pass irrelevant option attributes, or fail to pass required ones, optparse raises an OptionError exception explaining your mistake. The standard option actions hard-coded into optparse are:. For this action, you may also supply type and dest option attributes; see Standard option actions.
As you can see, most actions involve storing or updating a value somewhere. Option arguments and various other values are stored as attributes of this object, according to the dest destination option attribute. The type and dest option attributes are almost as important as action , but action is the only one that makes sense for all options.
The following option attributes may be passed as keyword arguments to OptionParser. If you pass an option attribute that is not relevant to a particular option, or fail to pass a required option attribute, optparse raises OptionError. The argument type expected by this option e. How many arguments of type type should be consumed when this option is seen.
For options of type "choice" , the list of strings the user may choose from. For options with action "callback" , the callable to call when this option is seen. See section Option Callbacks for detail on the arguments passed to the callable. Additional positional and keyword arguments to pass to callback after the four standard callback arguments. Help text to print for this option when listing all available options after the user supplies a help option such as --help.
If no help text is supplied, the option will be listed without help text. To hide this option, use the special value optparse. Stand-in for the option argument s to use when printing help text. See section Tutorial for an example. The various option actions all have slightly different requirements and effects.
The option must be followed by an argument, which is converted to a value according to type and stored in dest. See the Standard option types section. If choices is supplied a list or tuple of strings , 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 string e.
If there are no long option strings, optparse derives a destination from the first short option string e. The value const is stored in dest. If --noisy is seen, optparse will set. The option must be followed by an argument, which is appended to the list in dest. If no default value for dest is supplied, an empty list is automatically created when optparse first encounters this option on the command-line. The defaults for type and dest are the same as for the "store" action.
If -t3 is seen on the command-line, optparse does the equivalent of:. The append action calls the append method on the current value of the option. This means that any default value specified must have an append method.
It also means that if the default value is non-empty, the default elements will be present in the parsed value for the option, with any values from the command line appended after those default values:.
Increment the integer stored at dest. If no default value is supplied, dest is set to zero before being incremented the first time. The first time -v is seen on the command line, optparse does the equivalent of:. Every subsequent occurrence of -v results in. Call the function specified by callback , which is called as. See section Option Callbacks for more detail.
Prints a complete help message for all the options in the current option parser. 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. If optparse sees either -h or --help on the command line, it will print something like the following help message to stdout assuming sys. After printing the help message, optparse terminates your process with sys. Prints the version number supplied to the OptionParser to stdout and exits.
Generally only relevant if the version argument is supplied to the OptionParser constructor. As with help options, you will rarely create version options, since optparse automatically adds them when needed.
If you need to add new option types, see section Extending optparse. Arguments to string options are not checked or converted in any way: Integer arguments type "int" are parsed as follows:. The conversion is done by calling int with the appropriate base 2, 8, 10, or If this fails, so will optparse , although with a more useful error message. The choices option attribute a sequence of strings defines the set of allowed option arguments. The most common usage is to supply neither keyword argument.
This ultimately terminates your process with an exit status of 2 the traditional Unix exit status for command-line errors. OptionParser provides several methods to help you out:.
Set parsing to stop on the first non-option. For example, if -a and -b are both simple options that take no arguments, optparse normally accepts this syntax:. This restores traditional Unix syntax, where option parsing stops with the first non-option argument.
For example, each command might have a different set of options. Set parsing to not stop on the first non-option, allowing interspersing switches with command arguments. This is the default behavior. If that option provided any other option strings, all of those option strings become invalid. Every time you add an option, optparse checks for conflicts with existing options. If it finds any, it invokes the current conflict-handling mechanism.
You can set the conflict-handling mechanism either in the constructor:. At this point, optparse detects that a previously-added option is already using the -n option string. Now --dry-run is the only way for the user to activate that option.
If the user asks for help, the help message will reflect that:. Carrying on with our existing OptionParser:. OptionParser instances have several cyclic references. This is particularly useful in long-running applications where large object graphs are reachable from your OptionParser. Set the usage string according to the rules described above for the usage constructor keyword argument.
Passing None sets the default usage string; use optparse. Print the usage message for the current program self. Set default values for several option destinations at once. Extending optparse is more general, but overkill for a lot of simple cases. Quite often a simple callback is all you need. As always, the easiest way to define a callback option is by using the OptionParser. Apart from action , the only option attribute you must specify is callback , the function to call:. In some circumstances, though, you might want your callback to consume an arbitrary number of command-line arguments.
Thus, the minimal callback function signature is:. The keyMask is used by checkModifiers. If the keyMask matches the combination of keys down on an event, checkModifiers returns true. Note that this property is not part of the stable API. Use of the evt property should be restricted to controls in the library or other applications that are willing to update with changes to the OpenLayers code.
When touch events are started touch will be true and all mouse related listeners will do nothing. Check the keyMask on the handler. If no keyMask is set, this always returns true. If a keyMask is set and it matches the combination of keys down on an event, this returns true. With each registered browser event, the handler sets its own evt property. This property can be accessed by controls if needed to get more information about the event that the handler is processing. This allows modifier keys on the event to be checked alt, shift, ctrl, and meta cannot be checked with the keyboard handler.
For a control to determine which modifier keys are associated with the event that a handler is currently processing, it should access code handler. With each registered browser event, the handler sets its own evt property. This property can be accessed by controls if needed to get more information about the event that the handler is processing. This allows modifier keys on the event to be checked alt, shift, ctrl, and meta cannot be checked with the keyboard handler.
For a control to determine which modifier keys are associated with the event that a handler is currently processing, it should access code handler. If set as the keyMask , checkModifiers returns false if any key is down.
If set as the keyMask , checkModifiers returns false if Shift is down. If set as the keyMask , checkModifiers returns false if Ctrl is down. If set as the keyMask , checkModifiers returns false if Alt is down. If set as the keyMask , checkModifiers returns false if Cmd is down.
Handler Base class to construct a higher-level handler for event sequences. Handler Construct a handler. Functions setMap checkModifiers Check the keyMask on the handler.