Home | History | Annotate | Download | only in python2.7
      1 """A powerful, extensible, and easy-to-use option parser.
      2 
      3 By Greg Ward <gward (at] python.net>
      4 
      5 Originally distributed as Optik.
      6 
      7 For support, use the optik-users (at] lists.sourceforge.net mailing list
      8 (http://lists.sourceforge.net/lists/listinfo/optik-users).
      9 
     10 Simple usage example:
     11 
     12    from optparse import OptionParser
     13 
     14    parser = OptionParser()
     15    parser.add_option("-f", "--file", dest="filename",
     16                      help="write report to FILE", metavar="FILE")
     17    parser.add_option("-q", "--quiet",
     18                      action="store_false", dest="verbose", default=True,
     19                      help="don't print status messages to stdout")
     20 
     21    (options, args) = parser.parse_args()
     22 """
     23 
     24 __version__ = "1.5.3"
     25 
     26 __all__ = ['Option',
     27            'make_option',
     28            'SUPPRESS_HELP',
     29            'SUPPRESS_USAGE',
     30            'Values',
     31            'OptionContainer',
     32            'OptionGroup',
     33            'OptionParser',
     34            'HelpFormatter',
     35            'IndentedHelpFormatter',
     36            'TitledHelpFormatter',
     37            'OptParseError',
     38            'OptionError',
     39            'OptionConflictError',
     40            'OptionValueError',
     41            'BadOptionError']
     42 
     43 __copyright__ = """
     44 Copyright (c) 2001-2006 Gregory P. Ward.  All rights reserved.
     45 Copyright (c) 2002-2006 Python Software Foundation.  All rights reserved.
     46 
     47 Redistribution and use in source and binary forms, with or without
     48 modification, are permitted provided that the following conditions are
     49 met:
     50 
     51   * Redistributions of source code must retain the above copyright
     52     notice, this list of conditions and the following disclaimer.
     53 
     54   * Redistributions in binary form must reproduce the above copyright
     55     notice, this list of conditions and the following disclaimer in the
     56     documentation and/or other materials provided with the distribution.
     57 
     58   * Neither the name of the author nor the names of its
     59     contributors may be used to endorse or promote products derived from
     60     this software without specific prior written permission.
     61 
     62 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
     63 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
     64 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
     65 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
     66 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     67 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     68 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     69 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
     70 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     71 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     72 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     73 """
     74 
     75 import sys, os
     76 import types
     77 import textwrap
     78 
     79 def _repr(self):
     80     return "<%s at 0x%x: %s>" % (self.__class__.__name__, id(self), self)
     81 
     82 
     83 # This file was generated from:
     84 #   Id: option_parser.py 527 2006-07-23 15:21:30Z greg
     85 #   Id: option.py 522 2006-06-11 16:22:03Z gward
     86 #   Id: help.py 527 2006-07-23 15:21:30Z greg
     87 #   Id: errors.py 509 2006-04-20 00:58:24Z gward
     88 
     89 try:
     90     from gettext import gettext
     91 except ImportError:
     92     def gettext(message):
     93         return message
     94 _ = gettext
     95 
     96 
     97 class OptParseError (Exception):
     98     def __init__(self, msg):
     99         self.msg = msg
    100 
    101     def __str__(self):
    102         return self.msg
    103 
    104 
    105 class OptionError (OptParseError):
    106     """
    107     Raised if an Option instance is created with invalid or
    108     inconsistent arguments.
    109     """
    110 
    111     def __init__(self, msg, option):
    112         self.msg = msg
    113         self.option_id = str(option)
    114 
    115     def __str__(self):
    116         if self.option_id:
    117             return "option %s: %s" % (self.option_id, self.msg)
    118         else:
    119             return self.msg
    120 
    121 class OptionConflictError (OptionError):
    122     """
    123     Raised if conflicting options are added to an OptionParser.
    124     """
    125 
    126 class OptionValueError (OptParseError):
    127     """
    128     Raised if an invalid option value is encountered on the command
    129     line.
    130     """
    131 
    132 class BadOptionError (OptParseError):
    133     """
    134     Raised if an invalid option is seen on the command line.
    135     """
    136     def __init__(self, opt_str):
    137         self.opt_str = opt_str
    138 
    139     def __str__(self):
    140         return _("no such option: %s") % self.opt_str
    141 
    142 class AmbiguousOptionError (BadOptionError):
    143     """
    144     Raised if an ambiguous option is seen on the command line.
    145     """
    146     def __init__(self, opt_str, possibilities):
    147         BadOptionError.__init__(self, opt_str)
    148         self.possibilities = possibilities
    149 
    150     def __str__(self):
    151         return (_("ambiguous option: %s (%s?)")
    152                 % (self.opt_str, ", ".join(self.possibilities)))
    153 
    154 
    155 class HelpFormatter:
    156 
    157     """
    158     Abstract base class for formatting option help.  OptionParser
    159     instances should use one of the HelpFormatter subclasses for
    160     formatting help; by default IndentedHelpFormatter is used.
    161 
    162     Instance attributes:
    163       parser : OptionParser
    164         the controlling OptionParser instance
    165       indent_increment : int
    166         the number of columns to indent per nesting level
    167       max_help_position : int
    168         the maximum starting column for option help text
    169       help_position : int
    170         the calculated starting column for option help text;
    171         initially the same as the maximum
    172       width : int
    173         total number of columns for output (pass None to constructor for
    174         this value to be taken from the $COLUMNS environment variable)
    175       level : int
    176         current indentation level
    177       current_indent : int
    178         current indentation level (in columns)
    179       help_width : int
    180         number of columns available for option help text (calculated)
    181       default_tag : str
    182         text to replace with each option's default value, "%default"
    183         by default.  Set to false value to disable default value expansion.
    184       option_strings : { Option : str }
    185         maps Option instances to the snippet of help text explaining
    186         the syntax of that option, e.g. "-h, --help" or
    187         "-fFILE, --file=FILE"
    188       _short_opt_fmt : str
    189         format string controlling how short options with values are
    190         printed in help text.  Must be either "%s%s" ("-fFILE") or
    191         "%s %s" ("-f FILE"), because those are the two syntaxes that
    192         Optik supports.
    193       _long_opt_fmt : str
    194         similar but for long options; must be either "%s %s" ("--file FILE")
    195         or "%s=%s" ("--file=FILE").
    196     """
    197 
    198     NO_DEFAULT_VALUE = "none"
    199 
    200     def __init__(self,
    201                  indent_increment,
    202                  max_help_position,
    203                  width,
    204                  short_first):
    205         self.parser = None
    206         self.indent_increment = indent_increment
    207         self.help_position = self.max_help_position = max_help_position
    208         if width is None:
    209             try:
    210                 width = int(os.environ['COLUMNS'])
    211             except (KeyError, ValueError):
    212                 width = 80
    213             width -= 2
    214         self.width = width
    215         self.current_indent = 0
    216         self.level = 0
    217         self.help_width = None          # computed later
    218         self.short_first = short_first
    219         self.default_tag = "%default"
    220         self.option_strings = {}
    221         self._short_opt_fmt = "%s %s"
    222         self._long_opt_fmt = "%s=%s"
    223 
    224     def set_parser(self, parser):
    225         self.parser = parser
    226 
    227     def set_short_opt_delimiter(self, delim):
    228         if delim not in ("", " "):
    229             raise ValueError(
    230                 "invalid metavar delimiter for short options: %r" % delim)
    231         self._short_opt_fmt = "%s" + delim + "%s"
    232 
    233     def set_long_opt_delimiter(self, delim):
    234         if delim not in ("=", " "):
    235             raise ValueError(
    236                 "invalid metavar delimiter for long options: %r" % delim)
    237         self._long_opt_fmt = "%s" + delim + "%s"
    238 
    239     def indent(self):
    240         self.current_indent += self.indent_increment
    241         self.level += 1
    242 
    243     def dedent(self):
    244         self.current_indent -= self.indent_increment
    245         assert self.current_indent >= 0, "Indent decreased below 0."
    246         self.level -= 1
    247 
    248     def format_usage(self, usage):
    249         raise NotImplementedError, "subclasses must implement"
    250 
    251     def format_heading(self, heading):
    252         raise NotImplementedError, "subclasses must implement"
    253 
    254     def _format_text(self, text):
    255         """
    256         Format a paragraph of free-form text for inclusion in the
    257         help output at the current indentation level.
    258         """
    259         text_width = self.width - self.current_indent
    260         indent = " "*self.current_indent
    261         return textwrap.fill(text,
    262                              text_width,
    263                              initial_indent=indent,
    264                              subsequent_indent=indent)
    265 
    266     def format_description(self, description):
    267         if description:
    268             return self._format_text(description) + "\n"
    269         else:
    270             return ""
    271 
    272     def format_epilog(self, epilog):
    273         if epilog:
    274             return "\n" + self._format_text(epilog) + "\n"
    275         else:
    276             return ""
    277 
    278 
    279     def expand_default(self, option):
    280         if self.parser is None or not self.default_tag:
    281             return option.help
    282 
    283         default_value = self.parser.defaults.get(option.dest)
    284         if default_value is NO_DEFAULT or default_value is None:
    285             default_value = self.NO_DEFAULT_VALUE
    286 
    287         return option.help.replace(self.default_tag, str(default_value))
    288 
    289     def format_option(self, option):
    290         # The help for each option consists of two parts:
    291         #   * the opt strings and metavars
    292         #     eg. ("-x", or "-fFILENAME, --file=FILENAME")
    293         #   * the user-supplied help string
    294         #     eg. ("turn on expert mode", "read data from FILENAME")
    295         #
    296         # If possible, we write both of these on the same line:
    297         #   -x      turn on expert mode
    298         #
    299         # But if the opt string list is too long, we put the help
    300         # string on a second line, indented to the same column it would
    301         # start in if it fit on the first line.
    302         #   -fFILENAME, --file=FILENAME
    303         #           read data from FILENAME
    304         result = []
    305         opts = self.option_strings[option]
    306         opt_width = self.help_position - self.current_indent - 2
    307         if len(opts) > opt_width:
    308             opts = "%*s%s\n" % (self.current_indent, "", opts)
    309             indent_first = self.help_position
    310         else:                       # start help on same line as opts
    311             opts = "%*s%-*s  " % (self.current_indent, "", opt_width, opts)
    312             indent_first = 0
    313         result.append(opts)
    314         if option.help:
    315             help_text = self.expand_default(option)
    316             help_lines = textwrap.wrap(help_text, self.help_width)
    317             result.append("%*s%s\n" % (indent_first, "", help_lines[0]))
    318             result.extend(["%*s%s\n" % (self.help_position, "", line)
    319                            for line in help_lines[1:]])
    320         elif opts[-1] != "\n":
    321             result.append("\n")
    322         return "".join(result)
    323 
    324     def store_option_strings(self, parser):
    325         self.indent()
    326         max_len = 0
    327         for opt in parser.option_list:
    328             strings = self.format_option_strings(opt)
    329             self.option_strings[opt] = strings
    330             max_len = max(max_len, len(strings) + self.current_indent)
    331         self.indent()
    332         for group in parser.option_groups:
    333             for opt in group.option_list:
    334                 strings = self.format_option_strings(opt)
    335                 self.option_strings[opt] = strings
    336                 max_len = max(max_len, len(strings) + self.current_indent)
    337         self.dedent()
    338         self.dedent()
    339         self.help_position = min(max_len + 2, self.max_help_position)
    340         self.help_width = self.width - self.help_position
    341 
    342     def format_option_strings(self, option):
    343         """Return a comma-separated list of option strings & metavariables."""
    344         if option.takes_value():
    345             metavar = option.metavar or option.dest.upper()
    346             short_opts = [self._short_opt_fmt % (sopt, metavar)
    347                           for sopt in option._short_opts]
    348             long_opts = [self._long_opt_fmt % (lopt, metavar)
    349                          for lopt in option._long_opts]
    350         else:
    351             short_opts = option._short_opts
    352             long_opts = option._long_opts
    353 
    354         if self.short_first:
    355             opts = short_opts + long_opts
    356         else:
    357             opts = long_opts + short_opts
    358 
    359         return ", ".join(opts)
    360 
    361 class IndentedHelpFormatter (HelpFormatter):
    362     """Format help with indented section bodies.
    363     """
    364 
    365     def __init__(self,
    366                  indent_increment=2,
    367                  max_help_position=24,
    368                  width=None,
    369                  short_first=1):
    370         HelpFormatter.__init__(
    371             self, indent_increment, max_help_position, width, short_first)
    372 
    373     def format_usage(self, usage):
    374         return _("Usage: %s\n") % usage
    375 
    376     def format_heading(self, heading):
    377         return "%*s%s:\n" % (self.current_indent, "", heading)
    378 
    379 
    380 class TitledHelpFormatter (HelpFormatter):
    381     """Format help with underlined section headers.
    382     """
    383 
    384     def __init__(self,
    385                  indent_increment=0,
    386                  max_help_position=24,
    387                  width=None,
    388                  short_first=0):
    389         HelpFormatter.__init__ (
    390             self, indent_increment, max_help_position, width, short_first)
    391 
    392     def format_usage(self, usage):
    393         return "%s  %s\n" % (self.format_heading(_("Usage")), usage)
    394 
    395     def format_heading(self, heading):
    396         return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading))
    397 
    398 
    399 def _parse_num(val, type):
    400     if val[:2].lower() == "0x":         # hexadecimal
    401         radix = 16
    402     elif val[:2].lower() == "0b":       # binary
    403         radix = 2
    404         val = val[2:] or "0"            # have to remove "0b" prefix
    405     elif val[:1] == "0":                # octal
    406         radix = 8
    407     else:                               # decimal
    408         radix = 10
    409 
    410     return type(val, radix)
    411 
    412 def _parse_int(val):
    413     return _parse_num(val, int)
    414 
    415 def _parse_long(val):
    416     return _parse_num(val, long)
    417 
    418 _builtin_cvt = { "int" : (_parse_int, _("integer")),
    419                  "long" : (_parse_long, _("long integer")),
    420                  "float" : (float, _("floating-point")),
    421                  "complex" : (complex, _("complex")) }
    422 
    423 def check_builtin(option, opt, value):
    424     (cvt, what) = _builtin_cvt[option.type]
    425     try:
    426         return cvt(value)
    427     except ValueError:
    428         raise OptionValueError(
    429             _("option %s: invalid %s value: %r") % (opt, what, value))
    430 
    431 def check_choice(option, opt, value):
    432     if value in option.choices:
    433         return value
    434     else:
    435         choices = ", ".join(map(repr, option.choices))
    436         raise OptionValueError(
    437             _("option %s: invalid choice: %r (choose from %s)")
    438             % (opt, value, choices))
    439 
    440 # Not supplying a default is different from a default of None,
    441 # so we need an explicit "not supplied" value.
    442 NO_DEFAULT = ("NO", "DEFAULT")
    443 
    444 
    445 class Option:
    446     """
    447     Instance attributes:
    448       _short_opts : [string]
    449       _long_opts : [string]
    450 
    451       action : string
    452       type : string
    453       dest : string
    454       default : any
    455       nargs : int
    456       const : any
    457       choices : [string]
    458       callback : function
    459       callback_args : (any*)
    460       callback_kwargs : { string : any }
    461       help : string
    462       metavar : string
    463     """
    464 
    465     # The list of instance attributes that may be set through
    466     # keyword args to the constructor.
    467     ATTRS = ['action',
    468              'type',
    469              'dest',
    470              'default',
    471              'nargs',
    472              'const',
    473              'choices',
    474              'callback',
    475              'callback_args',
    476              'callback_kwargs',
    477              'help',
    478              'metavar']
    479 
    480     # The set of actions allowed by option parsers.  Explicitly listed
    481     # here so the constructor can validate its arguments.
    482     ACTIONS = ("store",
    483                "store_const",
    484                "store_true",
    485                "store_false",
    486                "append",
    487                "append_const",
    488                "count",
    489                "callback",
    490                "help",
    491                "version")
    492 
    493     # The set of actions that involve storing a value somewhere;
    494     # also listed just for constructor argument validation.  (If
    495     # the action is one of these, there must be a destination.)
    496     STORE_ACTIONS = ("store",
    497                      "store_const",
    498                      "store_true",
    499                      "store_false",
    500                      "append",
    501                      "append_const",
    502                      "count")
    503 
    504     # The set of actions for which it makes sense to supply a value
    505     # type, ie. which may consume an argument from the command line.
    506     TYPED_ACTIONS = ("store",
    507                      "append",
    508                      "callback")
    509 
    510     # The set of actions which *require* a value type, ie. that
    511     # always consume an argument from the command line.
    512     ALWAYS_TYPED_ACTIONS = ("store",
    513                             "append")
    514 
    515     # The set of actions which take a 'const' attribute.
    516     CONST_ACTIONS = ("store_const",
    517                      "append_const")
    518 
    519     # The set of known types for option parsers.  Again, listed here for
    520     # constructor argument validation.
    521     TYPES = ("string", "int", "long", "float", "complex", "choice")
    522 
    523     # Dictionary of argument checking functions, which convert and
    524     # validate option arguments according to the option type.
    525     #
    526     # Signature of checking functions is:
    527     #   check(option : Option, opt : string, value : string) -> any
    528     # where
    529     #   option is the Option instance calling the checker
    530     #   opt is the actual option seen on the command-line
    531     #     (eg. "-a", "--file")
    532     #   value is the option argument seen on the command-line
    533     #
    534     # The return value should be in the appropriate Python type
    535     # for option.type -- eg. an integer if option.type == "int".
    536     #
    537     # If no checker is defined for a type, arguments will be
    538     # unchecked and remain strings.
    539     TYPE_CHECKER = { "int"    : check_builtin,
    540                      "long"   : check_builtin,
    541                      "float"  : check_builtin,
    542                      "complex": check_builtin,
    543                      "choice" : check_choice,
    544                    }
    545 
    546 
    547     # CHECK_METHODS is a list of unbound method objects; they are called
    548     # by the constructor, in order, after all attributes are
    549     # initialized.  The list is created and filled in later, after all
    550     # the methods are actually defined.  (I just put it here because I
    551     # like to define and document all class attributes in the same
    552     # place.)  Subclasses that add another _check_*() method should
    553     # define their own CHECK_METHODS list that adds their check method
    554     # to those from this class.
    555     CHECK_METHODS = None
    556 
    557 
    558     # -- Constructor/initialization methods ----------------------------
    559 
    560     def __init__(self, *opts, **attrs):
    561         # Set _short_opts, _long_opts attrs from 'opts' tuple.
    562         # Have to be set now, in case no option strings are supplied.
    563         self._short_opts = []
    564         self._long_opts = []
    565         opts = self._check_opt_strings(opts)
    566         self._set_opt_strings(opts)
    567 
    568         # Set all other attrs (action, type, etc.) from 'attrs' dict
    569         self._set_attrs(attrs)
    570 
    571         # Check all the attributes we just set.  There are lots of
    572         # complicated interdependencies, but luckily they can be farmed
    573         # out to the _check_*() methods listed in CHECK_METHODS -- which
    574         # could be handy for subclasses!  The one thing these all share
    575         # is that they raise OptionError if they discover a problem.
    576         for checker in self.CHECK_METHODS:
    577             checker(self)
    578 
    579     def _check_opt_strings(self, opts):
    580         # Filter out None because early versions of Optik had exactly
    581         # one short option and one long option, either of which
    582         # could be None.
    583         opts = filter(None, opts)
    584         if not opts:
    585             raise TypeError("at least one option string must be supplied")
    586         return opts
    587 
    588     def _set_opt_strings(self, opts):
    589         for opt in opts:
    590             if len(opt) < 2:
    591                 raise OptionError(
    592                     "invalid option string %r: "
    593                     "must be at least two characters long" % opt, self)
    594             elif len(opt) == 2:
    595                 if not (opt[0] == "-" and opt[1] != "-"):
    596                     raise OptionError(
    597                         "invalid short option string %r: "
    598                         "must be of the form -x, (x any non-dash char)" % opt,
    599                         self)
    600                 self._short_opts.append(opt)
    601             else:
    602                 if not (opt[0:2] == "--" and opt[2] != "-"):
    603                     raise OptionError(
    604                         "invalid long option string %r: "
    605                         "must start with --, followed by non-dash" % opt,
    606                         self)
    607                 self._long_opts.append(opt)
    608 
    609     def _set_attrs(self, attrs):
    610         for attr in self.ATTRS:
    611             if attr in attrs:
    612                 setattr(self, attr, attrs[attr])
    613                 del attrs[attr]
    614             else:
    615                 if attr == 'default':
    616                     setattr(self, attr, NO_DEFAULT)
    617                 else:
    618                     setattr(self, attr, None)
    619         if attrs:
    620             attrs = attrs.keys()
    621             attrs.sort()
    622             raise OptionError(
    623                 "invalid keyword arguments: %s" % ", ".join(attrs),
    624                 self)
    625 
    626 
    627     # -- Constructor validation methods --------------------------------
    628 
    629     def _check_action(self):
    630         if self.action is None:
    631             self.action = "store"
    632         elif self.action not in self.ACTIONS:
    633             raise OptionError("invalid action: %r" % self.action, self)
    634 
    635     def _check_type(self):
    636         if self.type is None:
    637             if self.action in self.ALWAYS_TYPED_ACTIONS:
    638                 if self.choices is not None:
    639                     # The "choices" attribute implies "choice" type.
    640                     self.type = "choice"
    641                 else:
    642                     # No type given?  "string" is the most sensible default.
    643                     self.type = "string"
    644         else:
    645             # Allow type objects or builtin type conversion functions
    646             # (int, str, etc.) as an alternative to their names.  (The
    647             # complicated check of __builtin__ is only necessary for
    648             # Python 2.1 and earlier, and is short-circuited by the
    649             # first check on modern Pythons.)
    650             import __builtin__
    651             if ( type(self.type) is types.TypeType or
    652                  (hasattr(self.type, "__name__") and
    653                   getattr(__builtin__, self.type.__name__, None) is self.type) ):
    654                 self.type = self.type.__name__
    655 
    656             if self.type == "str":
    657                 self.type = "string"
    658 
    659             if self.type not in self.TYPES:
    660                 raise OptionError("invalid option type: %r" % self.type, self)
    661             if self.action not in self.TYPED_ACTIONS:
    662                 raise OptionError(
    663                     "must not supply a type for action %r" % self.action, self)
    664 
    665     def _check_choice(self):
    666         if self.type == "choice":
    667             if self.choices is None:
    668                 raise OptionError(
    669                     "must supply a list of choices for type 'choice'", self)
    670             elif type(self.choices) not in (types.TupleType, types.ListType):
    671                 raise OptionError(
    672                     "choices must be a list of strings ('%s' supplied)"
    673                     % str(type(self.choices)).split("'")[1], self)
    674         elif self.choices is not None:
    675             raise OptionError(
    676                 "must not supply choices for type %r" % self.type, self)
    677 
    678     def _check_dest(self):
    679         # No destination given, and we need one for this action.  The
    680         # self.type check is for callbacks that take a value.
    681         takes_value = (self.action in self.STORE_ACTIONS or
    682                        self.type is not None)
    683         if self.dest is None and takes_value:
    684 
    685             # Glean a destination from the first long option string,
    686             # or from the first short option string if no long options.
    687             if self._long_opts:
    688                 # eg. "--foo-bar" -> "foo_bar"
    689                 self.dest = self._long_opts[0][2:].replace('-', '_')
    690             else:
    691                 self.dest = self._short_opts[0][1]
    692 
    693     def _check_const(self):
    694         if self.action not in self.CONST_ACTIONS and self.const is not None:
    695             raise OptionError(
    696                 "'const' must not be supplied for action %r" % self.action,
    697                 self)
    698 
    699     def _check_nargs(self):
    700         if self.action in self.TYPED_ACTIONS:
    701             if self.nargs is None:
    702                 self.nargs = 1
    703         elif self.nargs is not None:
    704             raise OptionError(
    705                 "'nargs' must not be supplied for action %r" % self.action,
    706                 self)
    707 
    708     def _check_callback(self):
    709         if self.action == "callback":
    710             if not hasattr(self.callback, '__call__'):
    711                 raise OptionError(
    712                     "callback not callable: %r" % self.callback, self)
    713             if (self.callback_args is not None and
    714                 type(self.callback_args) is not types.TupleType):
    715                 raise OptionError(
    716                     "callback_args, if supplied, must be a tuple: not %r"
    717                     % self.callback_args, self)
    718             if (self.callback_kwargs is not None and
    719                 type(self.callback_kwargs) is not types.DictType):
    720                 raise OptionError(
    721                     "callback_kwargs, if supplied, must be a dict: not %r"
    722                     % self.callback_kwargs, self)
    723         else:
    724             if self.callback is not None:
    725                 raise OptionError(
    726                     "callback supplied (%r) for non-callback option"
    727                     % self.callback, self)
    728             if self.callback_args is not None:
    729                 raise OptionError(
    730                     "callback_args supplied for non-callback option", self)
    731             if self.callback_kwargs is not None:
    732                 raise OptionError(
    733                     "callback_kwargs supplied for non-callback option", self)
    734 
    735 
    736     CHECK_METHODS = [_check_action,
    737                      _check_type,
    738                      _check_choice,
    739                      _check_dest,
    740                      _check_const,
    741                      _check_nargs,
    742                      _check_callback]
    743 
    744 
    745     # -- Miscellaneous methods -----------------------------------------
    746 
    747     def __str__(self):
    748         return "/".join(self._short_opts + self._long_opts)
    749 
    750     __repr__ = _repr
    751 
    752     def takes_value(self):
    753         return self.type is not None
    754 
    755     def get_opt_string(self):
    756         if self._long_opts:
    757             return self._long_opts[0]
    758         else:
    759             return self._short_opts[0]
    760 
    761 
    762     # -- Processing methods --------------------------------------------
    763 
    764     def check_value(self, opt, value):
    765         checker = self.TYPE_CHECKER.get(self.type)
    766         if checker is None:
    767             return value
    768         else:
    769             return checker(self, opt, value)
    770 
    771     def convert_value(self, opt, value):
    772         if value is not None:
    773             if self.nargs == 1:
    774                 return self.check_value(opt, value)
    775             else:
    776                 return tuple([self.check_value(opt, v) for v in value])
    777 
    778     def process(self, opt, value, values, parser):
    779 
    780         # First, convert the value(s) to the right type.  Howl if any
    781         # value(s) are bogus.
    782         value = self.convert_value(opt, value)
    783 
    784         # And then take whatever action is expected of us.
    785         # This is a separate method to make life easier for
    786         # subclasses to add new actions.
    787         return self.take_action(
    788             self.action, self.dest, opt, value, values, parser)
    789 
    790     def take_action(self, action, dest, opt, value, values, parser):
    791         if action == "store":
    792             setattr(values, dest, value)
    793         elif action == "store_const":
    794             setattr(values, dest, self.const)
    795         elif action == "store_true":
    796             setattr(values, dest, True)
    797         elif action == "store_false":
    798             setattr(values, dest, False)
    799         elif action == "append":
    800             values.ensure_value(dest, []).append(value)
    801         elif action == "append_const":
    802             values.ensure_value(dest, []).append(self.const)
    803         elif action == "count":
    804             setattr(values, dest, values.ensure_value(dest, 0) + 1)
    805         elif action == "callback":
    806             args = self.callback_args or ()
    807             kwargs = self.callback_kwargs or {}
    808             self.callback(self, opt, value, parser, *args, **kwargs)
    809         elif action == "help":
    810             parser.print_help()
    811             parser.exit()
    812         elif action == "version":
    813             parser.print_version()
    814             parser.exit()
    815         else:
    816             raise ValueError("unknown action %r" % self.action)
    817 
    818         return 1
    819 
    820 # class Option
    821 
    822 
    823 SUPPRESS_HELP = "SUPPRESS"+"HELP"
    824 SUPPRESS_USAGE = "SUPPRESS"+"USAGE"
    825 
    826 try:
    827     basestring
    828 except NameError:
    829     def isbasestring(x):
    830         return isinstance(x, (types.StringType, types.UnicodeType))
    831 else:
    832     def isbasestring(x):
    833         return isinstance(x, basestring)
    834 
    835 class Values:
    836 
    837     def __init__(self, defaults=None):
    838         if defaults:
    839             for (attr, val) in defaults.items():
    840                 setattr(self, attr, val)
    841 
    842     def __str__(self):
    843         return str(self.__dict__)
    844 
    845     __repr__ = _repr
    846 
    847     def __cmp__(self, other):
    848         if isinstance(other, Values):
    849             return cmp(self.__dict__, other.__dict__)
    850         elif isinstance(other, types.DictType):
    851             return cmp(self.__dict__, other)
    852         else:
    853             return -1
    854 
    855     def _update_careful(self, dict):
    856         """
    857         Update the option values from an arbitrary dictionary, but only
    858         use keys from dict that already have a corresponding attribute
    859         in self.  Any keys in dict without a corresponding attribute
    860         are silently ignored.
    861         """
    862         for attr in dir(self):
    863             if attr in dict:
    864                 dval = dict[attr]
    865                 if dval is not None:
    866                     setattr(self, attr, dval)
    867 
    868     def _update_loose(self, dict):
    869         """
    870         Update the option values from an arbitrary dictionary,
    871         using all keys from the dictionary regardless of whether
    872         they have a corresponding attribute in self or not.
    873         """
    874         self.__dict__.update(dict)
    875 
    876     def _update(self, dict, mode):
    877         if mode == "careful":
    878             self._update_careful(dict)
    879         elif mode == "loose":
    880             self._update_loose(dict)
    881         else:
    882             raise ValueError, "invalid update mode: %r" % mode
    883 
    884     def read_module(self, modname, mode="careful"):
    885         __import__(modname)
    886         mod = sys.modules[modname]
    887         self._update(vars(mod), mode)
    888 
    889     def read_file(self, filename, mode="careful"):
    890         vars = {}
    891         execfile(filename, vars)
    892         self._update(vars, mode)
    893 
    894     def ensure_value(self, attr, value):
    895         if not hasattr(self, attr) or getattr(self, attr) is None:
    896             setattr(self, attr, value)
    897         return getattr(self, attr)
    898 
    899 
    900 class OptionContainer:
    901 
    902     """
    903     Abstract base class.
    904 
    905     Class attributes:
    906       standard_option_list : [Option]
    907         list of standard options that will be accepted by all instances
    908         of this parser class (intended to be overridden by subclasses).
    909 
    910     Instance attributes:
    911       option_list : [Option]
    912         the list of Option objects contained by this OptionContainer
    913       _short_opt : { string : Option }
    914         dictionary mapping short option strings, eg. "-f" or "-X",
    915         to the Option instances that implement them.  If an Option
    916         has multiple short option strings, it will appears in this
    917         dictionary multiple times. [1]
    918       _long_opt : { string : Option }
    919         dictionary mapping long option strings, eg. "--file" or
    920         "--exclude", to the Option instances that implement them.
    921         Again, a given Option can occur multiple times in this
    922         dictionary. [1]
    923       defaults : { string : any }
    924         dictionary mapping option destination names to default
    925         values for each destination [1]
    926 
    927     [1] These mappings are common to (shared by) all components of the
    928         controlling OptionParser, where they are initially created.
    929 
    930     """
    931 
    932     def __init__(self, option_class, conflict_handler, description):
    933         # Initialize the option list and related data structures.
    934         # This method must be provided by subclasses, and it must
    935         # initialize at least the following instance attributes:
    936         # option_list, _short_opt, _long_opt, defaults.
    937         self._create_option_list()
    938 
    939         self.option_class = option_class
    940         self.set_conflict_handler(conflict_handler)
    941         self.set_description(description)
    942 
    943     def _create_option_mappings(self):
    944         # For use by OptionParser constructor -- create the master
    945         # option mappings used by this OptionParser and all
    946         # OptionGroups that it owns.
    947         self._short_opt = {}            # single letter -> Option instance
    948         self._long_opt = {}             # long option -> Option instance
    949         self.defaults = {}              # maps option dest -> default value
    950 
    951 
    952     def _share_option_mappings(self, parser):
    953         # For use by OptionGroup constructor -- use shared option
    954         # mappings from the OptionParser that owns this OptionGroup.
    955         self._short_opt = parser._short_opt
    956         self._long_opt = parser._long_opt
    957         self.defaults = parser.defaults
    958 
    959     def set_conflict_handler(self, handler):
    960         if handler not in ("error", "resolve"):
    961             raise ValueError, "invalid conflict_resolution value %r" % handler
    962         self.conflict_handler = handler
    963 
    964     def set_description(self, description):
    965         self.description = description
    966 
    967     def get_description(self):
    968         return self.description
    969 
    970 
    971     def destroy(self):
    972         """see OptionParser.destroy()."""
    973         del self._short_opt
    974         del self._long_opt
    975         del self.defaults
    976 
    977 
    978     # -- Option-adding methods -----------------------------------------
    979 
    980     def _check_conflict(self, option):
    981         conflict_opts = []
    982         for opt in option._short_opts:
    983             if opt in self._short_opt:
    984                 conflict_opts.append((opt, self._short_opt[opt]))
    985         for opt in option._long_opts:
    986             if opt in self._long_opt:
    987                 conflict_opts.append((opt, self._long_opt[opt]))
    988 
    989         if conflict_opts:
    990             handler = self.conflict_handler
    991             if handler == "error":
    992                 raise OptionConflictError(
    993                     "conflicting option string(s): %s"
    994                     % ", ".join([co[0] for co in conflict_opts]),
    995                     option)
    996             elif handler == "resolve":
    997                 for (opt, c_option) in conflict_opts:
    998                     if opt.startswith("--"):
    999                         c_option._long_opts.remove(opt)
   1000                         del self._long_opt[opt]
   1001                     else:
   1002                         c_option._short_opts.remove(opt)
   1003                         del self._short_opt[opt]
   1004                     if not (c_option._short_opts or c_option._long_opts):
   1005                         c_option.container.option_list.remove(c_option)
   1006 
   1007     def add_option(self, *args, **kwargs):
   1008         """add_option(Option)
   1009            add_option(opt_str, ..., kwarg=val, ...)
   1010         """
   1011         if type(args[0]) in types.StringTypes:
   1012             option = self.option_class(*args, **kwargs)
   1013         elif len(args) == 1 and not kwargs:
   1014             option = args[0]
   1015             if not isinstance(option, Option):
   1016                 raise TypeError, "not an Option instance: %r" % option
   1017         else:
   1018             raise TypeError, "invalid arguments"
   1019 
   1020         self._check_conflict(option)
   1021 
   1022         self.option_list.append(option)
   1023         option.container = self
   1024         for opt in option._short_opts:
   1025             self._short_opt[opt] = option
   1026         for opt in option._long_opts:
   1027             self._long_opt[opt] = option
   1028 
   1029         if option.dest is not None:     # option has a dest, we need a default
   1030             if option.default is not NO_DEFAULT:
   1031                 self.defaults[option.dest] = option.default
   1032             elif option.dest not in self.defaults:
   1033                 self.defaults[option.dest] = None
   1034 
   1035         return option
   1036 
   1037     def add_options(self, option_list):
   1038         for option in option_list:
   1039             self.add_option(option)
   1040 
   1041     # -- Option query/removal methods ----------------------------------
   1042 
   1043     def get_option(self, opt_str):
   1044         return (self._short_opt.get(opt_str) or
   1045                 self._long_opt.get(opt_str))
   1046 
   1047     def has_option(self, opt_str):
   1048         return (opt_str in self._short_opt or
   1049                 opt_str in self._long_opt)
   1050 
   1051     def remove_option(self, opt_str):
   1052         option = self._short_opt.get(opt_str)
   1053         if option is None:
   1054             option = self._long_opt.get(opt_str)
   1055         if option is None:
   1056             raise ValueError("no such option %r" % opt_str)
   1057 
   1058         for opt in option._short_opts:
   1059             del self._short_opt[opt]
   1060         for opt in option._long_opts:
   1061             del self._long_opt[opt]
   1062         option.container.option_list.remove(option)
   1063 
   1064 
   1065     # -- Help-formatting methods ---------------------------------------
   1066 
   1067     def format_option_help(self, formatter):
   1068         if not self.option_list:
   1069             return ""
   1070         result = []
   1071         for option in self.option_list:
   1072             if not option.help is SUPPRESS_HELP:
   1073                 result.append(formatter.format_option(option))
   1074         return "".join(result)
   1075 
   1076     def format_description(self, formatter):
   1077         return formatter.format_description(self.get_description())
   1078 
   1079     def format_help(self, formatter):
   1080         result = []
   1081         if self.description:
   1082             result.append(self.format_description(formatter))
   1083         if self.option_list:
   1084             result.append(self.format_option_help(formatter))
   1085         return "\n".join(result)
   1086 
   1087 
   1088 class OptionGroup (OptionContainer):
   1089 
   1090     def __init__(self, parser, title, description=None):
   1091         self.parser = parser
   1092         OptionContainer.__init__(
   1093             self, parser.option_class, parser.conflict_handler, description)
   1094         self.title = title
   1095 
   1096     def _create_option_list(self):
   1097         self.option_list = []
   1098         self._share_option_mappings(self.parser)
   1099 
   1100     def set_title(self, title):
   1101         self.title = title
   1102 
   1103     def destroy(self):
   1104         """see OptionParser.destroy()."""
   1105         OptionContainer.destroy(self)
   1106         del self.option_list
   1107 
   1108     # -- Help-formatting methods ---------------------------------------
   1109 
   1110     def format_help(self, formatter):
   1111         result = formatter.format_heading(self.title)
   1112         formatter.indent()
   1113         result += OptionContainer.format_help(self, formatter)
   1114         formatter.dedent()
   1115         return result
   1116 
   1117 
   1118 class OptionParser (OptionContainer):
   1119 
   1120     """
   1121     Class attributes:
   1122       standard_option_list : [Option]
   1123         list of standard options that will be accepted by all instances
   1124         of this parser class (intended to be overridden by subclasses).
   1125 
   1126     Instance attributes:
   1127       usage : string
   1128         a usage string for your program.  Before it is displayed
   1129         to the user, "%prog" will be expanded to the name of
   1130         your program (self.prog or os.path.basename(sys.argv[0])).
   1131       prog : string
   1132         the name of the current program (to override
   1133         os.path.basename(sys.argv[0])).
   1134       description : string
   1135         A paragraph of text giving a brief overview of your program.
   1136         optparse reformats this paragraph to fit the current terminal
   1137         width and prints it when the user requests help (after usage,
   1138         but before the list of options).
   1139       epilog : string
   1140         paragraph of help text to print after option help
   1141 
   1142       option_groups : [OptionGroup]
   1143         list of option groups in this parser (option groups are
   1144         irrelevant for parsing the command-line, but very useful
   1145         for generating help)
   1146 
   1147       allow_interspersed_args : bool = true
   1148         if true, positional arguments may be interspersed with options.
   1149         Assuming -a and -b each take a single argument, the command-line
   1150           -ablah foo bar -bboo baz
   1151         will be interpreted the same as
   1152           -ablah -bboo -- foo bar baz
   1153         If this flag were false, that command line would be interpreted as
   1154           -ablah -- foo bar -bboo baz
   1155         -- ie. we stop processing options as soon as we see the first
   1156         non-option argument.  (This is the tradition followed by
   1157         Python's getopt module, Perl's Getopt::Std, and other argument-
   1158         parsing libraries, but it is generally annoying to users.)
   1159 
   1160       process_default_values : bool = true
   1161         if true, option default values are processed similarly to option
   1162         values from the command line: that is, they are passed to the
   1163         type-checking function for the option's type (as long as the
   1164         default value is a string).  (This really only matters if you
   1165         have defined custom types; see SF bug #955889.)  Set it to false
   1166         to restore the behaviour of Optik 1.4.1 and earlier.
   1167 
   1168       rargs : [string]
   1169         the argument list currently being parsed.  Only set when
   1170         parse_args() is active, and continually trimmed down as
   1171         we consume arguments.  Mainly there for the benefit of
   1172         callback options.
   1173       largs : [string]
   1174         the list of leftover arguments that we have skipped while
   1175         parsing options.  If allow_interspersed_args is false, this
   1176         list is always empty.
   1177       values : Values
   1178         the set of option values currently being accumulated.  Only
   1179         set when parse_args() is active.  Also mainly for callbacks.
   1180 
   1181     Because of the 'rargs', 'largs', and 'values' attributes,
   1182     OptionParser is not thread-safe.  If, for some perverse reason, you
   1183     need to parse command-line arguments simultaneously in different
   1184     threads, use different OptionParser instances.
   1185 
   1186     """
   1187 
   1188     standard_option_list = []
   1189 
   1190     def __init__(self,
   1191                  usage=None,
   1192                  option_list=None,
   1193                  option_class=Option,
   1194                  version=None,
   1195                  conflict_handler="error",
   1196                  description=None,
   1197                  formatter=None,
   1198                  add_help_option=True,
   1199                  prog=None,
   1200                  epilog=None):
   1201         OptionContainer.__init__(
   1202             self, option_class, conflict_handler, description)
   1203         self.set_usage(usage)
   1204         self.prog = prog
   1205         self.version = version
   1206         self.allow_interspersed_args = True
   1207         self.process_default_values = True
   1208         if formatter is None:
   1209             formatter = IndentedHelpFormatter()
   1210         self.formatter = formatter
   1211         self.formatter.set_parser(self)
   1212         self.epilog = epilog
   1213 
   1214         # Populate the option list; initial sources are the
   1215         # standard_option_list class attribute, the 'option_list'
   1216         # argument, and (if applicable) the _add_version_option() and
   1217         # _add_help_option() methods.
   1218         self._populate_option_list(option_list,
   1219                                    add_help=add_help_option)
   1220 
   1221         self._init_parsing_state()
   1222 
   1223 
   1224     def destroy(self):
   1225         """
   1226         Declare that you are done with this OptionParser.  This cleans up
   1227         reference cycles so the OptionParser (and all objects referenced by
   1228         it) can be garbage-collected promptly.  After calling destroy(), the
   1229         OptionParser is unusable.
   1230         """
   1231         OptionContainer.destroy(self)
   1232         for group in self.option_groups:
   1233             group.destroy()
   1234         del self.option_list
   1235         del self.option_groups
   1236         del self.formatter
   1237 
   1238 
   1239     # -- Private methods -----------------------------------------------
   1240     # (used by our or OptionContainer's constructor)
   1241 
   1242     def _create_option_list(self):
   1243         self.option_list = []
   1244         self.option_groups = []
   1245         self._create_option_mappings()
   1246 
   1247     def _add_help_option(self):
   1248         self.add_option("-h", "--help",
   1249                         action="help",
   1250                         help=_("show this help message and exit"))
   1251 
   1252     def _add_version_option(self):
   1253         self.add_option("--version",
   1254                         action="version",
   1255                         help=_("show program's version number and exit"))
   1256 
   1257     def _populate_option_list(self, option_list, add_help=True):
   1258         if self.standard_option_list:
   1259             self.add_options(self.standard_option_list)
   1260         if option_list:
   1261             self.add_options(option_list)
   1262         if self.version:
   1263             self._add_version_option()
   1264         if add_help:
   1265             self._add_help_option()
   1266 
   1267     def _init_parsing_state(self):
   1268         # These are set in parse_args() for the convenience of callbacks.
   1269         self.rargs = None
   1270         self.largs = None
   1271         self.values = None
   1272 
   1273 
   1274     # -- Simple modifier methods ---------------------------------------
   1275 
   1276     def set_usage(self, usage):
   1277         if usage is None:
   1278             self.usage = _("%prog [options]")
   1279         elif usage is SUPPRESS_USAGE:
   1280             self.usage = None
   1281         # For backwards compatibility with Optik 1.3 and earlier.
   1282         elif usage.lower().startswith("usage: "):
   1283             self.usage = usage[7:]
   1284         else:
   1285             self.usage = usage
   1286 
   1287     def enable_interspersed_args(self):
   1288         """Set parsing to not stop on the first non-option, allowing
   1289         interspersing switches with command arguments. This is the
   1290         default behavior. See also disable_interspersed_args() and the
   1291         class documentation description of the attribute
   1292         allow_interspersed_args."""
   1293         self.allow_interspersed_args = True
   1294 
   1295     def disable_interspersed_args(self):
   1296         """Set parsing to stop on the first non-option. Use this if
   1297         you have a command processor which runs another command that
   1298         has options of its own and you want to make sure these options
   1299         don't get confused.
   1300         """
   1301         self.allow_interspersed_args = False
   1302 
   1303     def set_process_default_values(self, process):
   1304         self.process_default_values = process
   1305 
   1306     def set_default(self, dest, value):
   1307         self.defaults[dest] = value
   1308 
   1309     def set_defaults(self, **kwargs):
   1310         self.defaults.update(kwargs)
   1311 
   1312     def _get_all_options(self):
   1313         options = self.option_list[:]
   1314         for group in self.option_groups:
   1315             options.extend(group.option_list)
   1316         return options
   1317 
   1318     def get_default_values(self):
   1319         if not self.process_default_values:
   1320             # Old, pre-Optik 1.5 behaviour.
   1321             return Values(self.defaults)
   1322 
   1323         defaults = self.defaults.copy()
   1324         for option in self._get_all_options():
   1325             default = defaults.get(option.dest)
   1326             if isbasestring(default):
   1327                 opt_str = option.get_opt_string()
   1328                 defaults[option.dest] = option.check_value(opt_str, default)
   1329 
   1330         return Values(defaults)
   1331 
   1332 
   1333     # -- OptionGroup methods -------------------------------------------
   1334 
   1335     def add_option_group(self, *args, **kwargs):
   1336         # XXX lots of overlap with OptionContainer.add_option()
   1337         if type(args[0]) is types.StringType:
   1338             group = OptionGroup(self, *args, **kwargs)
   1339         elif len(args) == 1 and not kwargs:
   1340             group = args[0]
   1341             if not isinstance(group, OptionGroup):
   1342                 raise TypeError, "not an OptionGroup instance: %r" % group
   1343             if group.parser is not self:
   1344                 raise ValueError, "invalid OptionGroup (wrong parser)"
   1345         else:
   1346             raise TypeError, "invalid arguments"
   1347 
   1348         self.option_groups.append(group)
   1349         return group
   1350 
   1351     def get_option_group(self, opt_str):
   1352         option = (self._short_opt.get(opt_str) or
   1353                   self._long_opt.get(opt_str))
   1354         if option and option.container is not self:
   1355             return option.container
   1356         return None
   1357 
   1358 
   1359     # -- Option-parsing methods ----------------------------------------
   1360 
   1361     def _get_args(self, args):
   1362         if args is None:
   1363             return sys.argv[1:]
   1364         else:
   1365             return args[:]              # don't modify caller's list
   1366 
   1367     def parse_args(self, args=None, values=None):
   1368         """
   1369         parse_args(args : [string] = sys.argv[1:],
   1370                    values : Values = None)
   1371         -> (values : Values, args : [string])
   1372 
   1373         Parse the command-line options found in 'args' (default:
   1374         sys.argv[1:]).  Any errors result in a call to 'error()', which
   1375         by default prints the usage message to stderr and calls
   1376         sys.exit() with an error message.  On success returns a pair
   1377         (values, args) where 'values' is an Values instance (with all
   1378         your option values) and 'args' is the list of arguments left
   1379         over after parsing options.
   1380         """
   1381         rargs = self._get_args(args)
   1382         if values is None:
   1383             values = self.get_default_values()
   1384 
   1385         # Store the halves of the argument list as attributes for the
   1386         # convenience of callbacks:
   1387         #   rargs
   1388         #     the rest of the command-line (the "r" stands for
   1389         #     "remaining" or "right-hand")
   1390         #   largs
   1391         #     the leftover arguments -- ie. what's left after removing
   1392         #     options and their arguments (the "l" stands for "leftover"
   1393         #     or "left-hand")
   1394         self.rargs = rargs
   1395         self.largs = largs = []
   1396         self.values = values
   1397 
   1398         try:
   1399             stop = self._process_args(largs, rargs, values)
   1400         except (BadOptionError, OptionValueError), err:
   1401             self.error(str(err))
   1402 
   1403         args = largs + rargs
   1404         return self.check_values(values, args)
   1405 
   1406     def check_values(self, values, args):
   1407         """
   1408         check_values(values : Values, args : [string])
   1409         -> (values : Values, args : [string])
   1410 
   1411         Check that the supplied option values and leftover arguments are
   1412         valid.  Returns the option values and leftover arguments
   1413         (possibly adjusted, possibly completely new -- whatever you
   1414         like).  Default implementation just returns the passed-in
   1415         values; subclasses may override as desired.
   1416         """
   1417         return (values, args)
   1418 
   1419     def _process_args(self, largs, rargs, values):
   1420         """_process_args(largs : [string],
   1421                          rargs : [string],
   1422                          values : Values)
   1423 
   1424         Process command-line arguments and populate 'values', consuming
   1425         options and arguments from 'rargs'.  If 'allow_interspersed_args' is
   1426         false, stop at the first non-option argument.  If true, accumulate any
   1427         interspersed non-option arguments in 'largs'.
   1428         """
   1429         while rargs:
   1430             arg = rargs[0]
   1431             # We handle bare "--" explicitly, and bare "-" is handled by the
   1432             # standard arg handler since the short arg case ensures that the
   1433             # len of the opt string is greater than 1.
   1434             if arg == "--":
   1435                 del rargs[0]
   1436                 return
   1437             elif arg[0:2] == "--":
   1438                 # process a single long option (possibly with value(s))
   1439                 self._process_long_opt(rargs, values)
   1440             elif arg[:1] == "-" and len(arg) > 1:
   1441                 # process a cluster of short options (possibly with
   1442                 # value(s) for the last one only)
   1443                 self._process_short_opts(rargs, values)
   1444             elif self.allow_interspersed_args:
   1445                 largs.append(arg)
   1446                 del rargs[0]
   1447             else:
   1448                 return                  # stop now, leave this arg in rargs
   1449 
   1450         # Say this is the original argument list:
   1451         # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
   1452         #                            ^
   1453         # (we are about to process arg(i)).
   1454         #
   1455         # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
   1456         # [arg0, ..., arg(i-1)] (any options and their arguments will have
   1457         # been removed from largs).
   1458         #
   1459         # The while loop will usually consume 1 or more arguments per pass.
   1460         # If it consumes 1 (eg. arg is an option that takes no arguments),
   1461         # then after _process_arg() is done the situation is:
   1462         #
   1463         #   largs = subset of [arg0, ..., arg(i)]
   1464         #   rargs = [arg(i+1), ..., arg(N-1)]
   1465         #
   1466         # If allow_interspersed_args is false, largs will always be
   1467         # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
   1468         # not a very interesting subset!
   1469 
   1470     def _match_long_opt(self, opt):
   1471         """_match_long_opt(opt : string) -> string
   1472 
   1473         Determine which long option string 'opt' matches, ie. which one
   1474         it is an unambiguous abbrevation for.  Raises BadOptionError if
   1475         'opt' doesn't unambiguously match any long option string.
   1476         """
   1477         return _match_abbrev(opt, self._long_opt)
   1478 
   1479     def _process_long_opt(self, rargs, values):
   1480         arg = rargs.pop(0)
   1481 
   1482         # Value explicitly attached to arg?  Pretend it's the next
   1483         # argument.
   1484         if "=" in arg:
   1485             (opt, next_arg) = arg.split("=", 1)
   1486             rargs.insert(0, next_arg)
   1487             had_explicit_value = True
   1488         else:
   1489             opt = arg
   1490             had_explicit_value = False
   1491 
   1492         opt = self._match_long_opt(opt)
   1493         option = self._long_opt[opt]
   1494         if option.takes_value():
   1495             nargs = option.nargs
   1496             if len(rargs) < nargs:
   1497                 if nargs == 1:
   1498                     self.error(_("%s option requires an argument") % opt)
   1499                 else:
   1500                     self.error(_("%s option requires %d arguments")
   1501                                % (opt, nargs))
   1502             elif nargs == 1:
   1503                 value = rargs.pop(0)
   1504             else:
   1505                 value = tuple(rargs[0:nargs])
   1506                 del rargs[0:nargs]
   1507 
   1508         elif had_explicit_value:
   1509             self.error(_("%s option does not take a value") % opt)
   1510 
   1511         else:
   1512             value = None
   1513 
   1514         option.process(opt, value, values, self)
   1515 
   1516     def _process_short_opts(self, rargs, values):
   1517         arg = rargs.pop(0)
   1518         stop = False
   1519         i = 1
   1520         for ch in arg[1:]:
   1521             opt = "-" + ch
   1522             option = self._short_opt.get(opt)
   1523             i += 1                      # we have consumed a character
   1524 
   1525             if not option:
   1526                 raise BadOptionError(opt)
   1527             if option.takes_value():
   1528                 # Any characters left in arg?  Pretend they're the
   1529                 # next arg, and stop consuming characters of arg.
   1530                 if i < len(arg):
   1531                     rargs.insert(0, arg[i:])
   1532                     stop = True
   1533 
   1534                 nargs = option.nargs
   1535                 if len(rargs) < nargs:
   1536                     if nargs == 1:
   1537                         self.error(_("%s option requires an argument") % opt)
   1538                     else:
   1539                         self.error(_("%s option requires %d arguments")
   1540                                    % (opt, nargs))
   1541                 elif nargs == 1:
   1542                     value = rargs.pop(0)
   1543                 else:
   1544                     value = tuple(rargs[0:nargs])
   1545                     del rargs[0:nargs]
   1546 
   1547             else:                       # option doesn't take a value
   1548                 value = None
   1549 
   1550             option.process(opt, value, values, self)
   1551 
   1552             if stop:
   1553                 break
   1554 
   1555 
   1556     # -- Feedback methods ----------------------------------------------
   1557 
   1558     def get_prog_name(self):
   1559         if self.prog is None:
   1560             return os.path.basename(sys.argv[0])
   1561         else:
   1562             return self.prog
   1563 
   1564     def expand_prog_name(self, s):
   1565         return s.replace("%prog", self.get_prog_name())
   1566 
   1567     def get_description(self):
   1568         return self.expand_prog_name(self.description)
   1569 
   1570     def exit(self, status=0, msg=None):
   1571         if msg:
   1572             sys.stderr.write(msg)
   1573         sys.exit(status)
   1574 
   1575     def error(self, msg):
   1576         """error(msg : string)
   1577 
   1578         Print a usage message incorporating 'msg' to stderr and exit.
   1579         If you override this in a subclass, it should not return -- it
   1580         should either exit or raise an exception.
   1581         """
   1582         self.print_usage(sys.stderr)
   1583         self.exit(2, "%s: error: %s\n" % (self.get_prog_name(), msg))
   1584 
   1585     def get_usage(self):
   1586         if self.usage:
   1587             return self.formatter.format_usage(
   1588                 self.expand_prog_name(self.usage))
   1589         else:
   1590             return ""
   1591 
   1592     def print_usage(self, file=None):
   1593         """print_usage(file : file = stdout)
   1594 
   1595         Print the usage message for the current program (self.usage) to
   1596         'file' (default stdout).  Any occurrence of the string "%prog" in
   1597         self.usage is replaced with the name of the current program
   1598         (basename of sys.argv[0]).  Does nothing if self.usage is empty
   1599         or not defined.
   1600         """
   1601         if self.usage:
   1602             print >>file, self.get_usage()
   1603 
   1604     def get_version(self):
   1605         if self.version:
   1606             return self.expand_prog_name(self.version)
   1607         else:
   1608             return ""
   1609 
   1610     def print_version(self, file=None):
   1611         """print_version(file : file = stdout)
   1612 
   1613         Print the version message for this program (self.version) to
   1614         'file' (default stdout).  As with print_usage(), any occurrence
   1615         of "%prog" in self.version is replaced by the current program's
   1616         name.  Does nothing if self.version is empty or undefined.
   1617         """
   1618         if self.version:
   1619             print >>file, self.get_version()
   1620 
   1621     def format_option_help(self, formatter=None):
   1622         if formatter is None:
   1623             formatter = self.formatter
   1624         formatter.store_option_strings(self)
   1625         result = []
   1626         result.append(formatter.format_heading(_("Options")))
   1627         formatter.indent()
   1628         if self.option_list:
   1629             result.append(OptionContainer.format_option_help(self, formatter))
   1630             result.append("\n")
   1631         for group in self.option_groups:
   1632             result.append(group.format_help(formatter))
   1633             result.append("\n")
   1634         formatter.dedent()
   1635         # Drop the last "\n", or the header if no options or option groups:
   1636         return "".join(result[:-1])
   1637 
   1638     def format_epilog(self, formatter):
   1639         return formatter.format_epilog(self.epilog)
   1640 
   1641     def format_help(self, formatter=None):
   1642         if formatter is None:
   1643             formatter = self.formatter
   1644         result = []
   1645         if self.usage:
   1646             result.append(self.get_usage() + "\n")
   1647         if self.description:
   1648             result.append(self.format_description(formatter) + "\n")
   1649         result.append(self.format_option_help(formatter))
   1650         result.append(self.format_epilog(formatter))
   1651         return "".join(result)
   1652 
   1653     # used by test suite
   1654     def _get_encoding(self, file):
   1655         encoding = getattr(file, "encoding", None)
   1656         if not encoding:
   1657             encoding = sys.getdefaultencoding()
   1658         return encoding
   1659 
   1660     def print_help(self, file=None):
   1661         """print_help(file : file = stdout)
   1662 
   1663         Print an extended help message, listing all options and any
   1664         help text provided with them, to 'file' (default stdout).
   1665         """
   1666         if file is None:
   1667             file = sys.stdout
   1668         encoding = self._get_encoding(file)
   1669         file.write(self.format_help().encode(encoding, "replace"))
   1670 
   1671 # class OptionParser
   1672 
   1673 
   1674 def _match_abbrev(s, wordmap):
   1675     """_match_abbrev(s : string, wordmap : {string : Option}) -> string
   1676 
   1677     Return the string key in 'wordmap' for which 's' is an unambiguous
   1678     abbreviation.  If 's' is found to be ambiguous or doesn't match any of
   1679     'words', raise BadOptionError.
   1680     """
   1681     # Is there an exact match?
   1682     if s in wordmap:
   1683         return s
   1684     else:
   1685         # Isolate all words with s as a prefix.
   1686         possibilities = [word for word in wordmap.keys()
   1687                          if word.startswith(s)]
   1688         # No exact match, so there had better be just one possibility.
   1689         if len(possibilities) == 1:
   1690             return possibilities[0]
   1691         elif not possibilities:
   1692             raise BadOptionError(s)
   1693         else:
   1694             # More than one possible completion: ambiguous prefix.
   1695             possibilities.sort()
   1696             raise AmbiguousOptionError(s, possibilities)
   1697 
   1698 
   1699 # Some day, there might be many Option classes.  As of Optik 1.3, the
   1700 # preferred way to instantiate Options is indirectly, via make_option(),
   1701 # which will become a factory function when there are many Option
   1702 # classes.
   1703 make_option = Option
   1704