1 """A powerful, extensible, and easy-to-use option parser.

     2 

     3 By Greg Ward <gward@python.net>

     4 

     5 Originally distributed as Optik.

     6 

     7 For support, use the optik-users@lists.sourceforge.net mailing list

     8 (http://lists.sourceforge.net/lists/listinfo/optik-users).

     9 """

    10 

    11 __version__ = "1.5.3"

    12 

    13 __all__ = ['Option',

    14            'SUPPRESS_HELP',

    15            'SUPPRESS_USAGE',

    16            'Values',

    17            'OptionContainer',

    18            'OptionGroup',

    19            'OptionParser',

    20            'HelpFormatter',

    21            'IndentedHelpFormatter',

    22            'TitledHelpFormatter',

    23            'OptParseError',

    24            'OptionError',

    25            'OptionConflictError',

    26            'OptionValueError',

    27            'BadOptionError']

    28 

    29 __copyright__ = """

    30 Copyright (c) 2001-2006 Gregory P. Ward.  All rights reserved.

    31 Copyright (c) 2002-2006 Python Software Foundation.  All rights reserved.

    32 

    33 Redistribution and use in source and binary forms, with or without

    34 modification, are permitted provided that the following conditions are

    35 met:

    36 

    37   * Redistributions of source code must retain the above copyright

    38     notice, this list of conditions and the following disclaimer.

    39 

    40   * Redistributions in binary form must reproduce the above copyright

    41     notice, this list of conditions and the following disclaimer in the

    42     documentation and/or other materials provided with the distribution.

    43 

    44   * Neither the name of the author nor the names of its

    45     contributors may be used to endorse or promote products derived from

    46     this software without specific prior written permission.

    47 

    48 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS

    49 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED

    50 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A

    51 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR

    52 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

    53 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

    54 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

    55 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

    56 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

    57 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

    58 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    59 """

    60 

    61 import sys, os

    62 import types

    63 import textwrap

    64 

    65 def _repr(self):

    66     return "<%s at 0x%x: %s>" % (self.__class__.__name__, id(self), self)

    67 

    68 

    69 # This file was generated from:

    70 #   Id: option_parser.py 527 2006-07-23 15:21:30Z greg

    71 #   Id: option.py 522 2006-06-11 16:22:03Z gward

    72 #   Id: help.py 527 2006-07-23 15:21:30Z greg

    73 #   Id: errors.py 509 2006-04-20 00:58:24Z gward

    74 

    75 try:

    76     from gettext import gettext

    77 except ImportError:

    78     def gettext(message):

    79         return message

    80 _ = gettext

    81 

    82 

    83 class OptParseError (Exception):

    84     def __init__(self, msg):

    85         self.msg = msg

    86 

    87     def __str__(self):

    88         return self.msg

    89 

    90 

    91 class OptionError (OptParseError):

    92     """

    93     Raised if an Option instance is created with invalid or

    94     inconsistent arguments.

    95     """

    96 

    97     def __init__(self, msg, option):

    98         self.msg = msg

    99         self.option_id = str(option)

   100 

   101     def __str__(self):

   102         if self.option_id:

   103             return "option %s: %s" % (self.option_id, self.msg)

   104         else:

   105             return self.msg

   106 

   107 class OptionConflictError (OptionError):

   108     """

   109     Raised if conflicting options are added to an OptionParser.

   110     """

   111 

   112 class OptionValueError (OptParseError):

   113     """

   114     Raised if an invalid option value is encountered on the command

   115     line.

   116     """

   117 

   118 class BadOptionError (OptParseError):

   119     """

   120     Raised if an invalid option is seen on the command line.

   121     """

   122     def __init__(self, opt_str):

   123         self.opt_str = opt_str

   124 

   125     def __str__(self):

   126         return _("no such option: %s") % self.opt_str

   127 

   128 class AmbiguousOptionError (BadOptionError):

   129     """

   130     Raised if an ambiguous option is seen on the command line.

   131     """

   132     def __init__(self, opt_str, possibilities):

   133         BadOptionError.__init__(self, opt_str)

   134         self.possibilities = possibilities

   135 

   136     def __str__(self):

   137         return (_("ambiguous option: %s (%s?)")

   138                 % (self.opt_str, ", ".join(self.possibilities)))

   139 

   140 

   141 class HelpFormatter:

   142 

   143     """

   144     Abstract base class for formatting option help.  OptionParser

   145     instances should use one of the HelpFormatter subclasses for

   146     formatting help; by default IndentedHelpFormatter is used.

   147 

   148     Instance attributes:

   149       parser : OptionParser

   150         the controlling OptionParser instance

   151       indent_increment : int

   152         the number of columns to indent per nesting level

   153       max_help_position : int

   154         the maximum starting column for option help text

   155       help_position : int

   156         the calculated starting column for option help text;

   157         initially the same as the maximum

   158       width : int

   159         total number of columns for output (pass None to constructor for

   160         this value to be taken from the $COLUMNS environment variable)

   161       level : int

   162         current indentation level

   163       current_indent : int

   164         current indentation level (in columns)

   165       help_width : int

   166         number of columns available for option help text (calculated)

   167       default_tag : str

   168         text to replace with each option's default value, "%default"

   169         by default.  Set to false value to disable default value expansion.

   170       option_strings : { Option : str }

   171         maps Option instances to the snippet of help text explaining

   172         the syntax of that option, e.g. "-h, --help" or

   173         "-fFILE, --file=FILE"

   174       _short_opt_fmt : str

   175         format string controlling how short options with values are

   176         printed in help text.  Must be either "%s%s" ("-fFILE") or

   177         "%s %s" ("-f FILE"), because those are the two syntaxes that

   178         Optik supports.

   179       _long_opt_fmt : str

   180         similar but for long options; must be either "%s %s" ("--file FILE")

   181         or "%s=%s" ("--file=FILE").

   182     """

   183 

   184     NO_DEFAULT_VALUE = "none"

   185 

   186     def __init__(self,

   187                  indent_increment,

   188                  max_help_position,

   189                  width,

   190                  short_first):

   191         self.parser = None

   192         self.indent_increment = indent_increment

   193         self.help_position = self.max_help_position = max_help_position

   194         if width is None:

   195             try:

   196                 width = int(os.environ['COLUMNS'])

   197             except (KeyError, ValueError):

   198                 width = 80

   199             width -= 2

   200         self.width = width

   201         self.current_indent = 0

   202         self.level = 0

   203         self.help_width = None          # computed later

   204         self.short_first = short_first

   205         self.default_tag = "%default"

   206         self.option_strings = {}

   207         self._short_opt_fmt = "%s %s"

   208         self._long_opt_fmt = "%s=%s"

   209 

   210     def set_parser(self, parser):

   211         self.parser = parser

   212 

   213     def set_short_opt_delimiter(self, delim):

   214         if delim not in ("", " "):

   215             raise ValueError(

   216                 "invalid metavar delimiter for short options: %r" % delim)

   217         self._short_opt_fmt = "%s" + delim + "%s"

   218 

   219     def set_long_opt_delimiter(self, delim):

   220         if delim not in ("=", " "):

   221             raise ValueError(

   222                 "invalid metavar delimiter for long options: %r" % delim)

   223         self._long_opt_fmt = "%s" + delim + "%s"

   224 

   225     def indent(self):

   226         self.current_indent += self.indent_increment

   227         self.level += 1

   228 

   229     def dedent(self):

   230         self.current_indent -= self.indent_increment

   231         assert self.current_indent >= 0, "Indent decreased below 0."

   232         self.level -= 1

   233 

   234     def format_usage(self, usage):

   235         raise NotImplementedError, "subclasses must implement"

   236 

   237     def format_heading(self, heading):

   238         raise NotImplementedError, "subclasses must implement"

   239 

   240     def _format_text(self, text):

   241         """

   242         Format a paragraph of free-form text for inclusion in the

   243         help output at the current indentation level.

   244         """

   245         text_width = self.width - self.current_indent

   246         indent = " "*self.current_indent

   247         return textwrap.fill(text,

   248                              text_width,

   249                              initial_indent=indent,

   250                              subsequent_indent=indent)

   251 

   252     def format_description(self, description):

   253         if description:

   254             return self._format_text(description) + "\n"

   255         else:

   256             return ""

   257 

   258     def format_epilog(self, epilog):

   259         if epilog:

   260             return "\n" + self._format_text(epilog) + "\n"

   261         else:

   262             return ""

   263 

   264 

   265     def expand_default(self, option):

   266         if self.parser is None or not self.default_tag:

   267             return option.help

   268 

   269         default_value = self.parser.defaults.get(option.dest)

   270         if default_value is NO_DEFAULT or default_value is None:

   271             default_value = self.NO_DEFAULT_VALUE

   272 

   273         return option.help.replace(self.default_tag, str(default_value))

   274 

   275     def format_option(self, option):

   276         # The help for each option consists of two parts:

   277         #   * the opt strings and metavars

   278         #     eg. ("-x", or "-fFILENAME, --file=FILENAME")

   279         #   * the user-supplied help string

   280         #     eg. ("turn on expert mode", "read data from FILENAME")

   281         #

   282         # If possible, we write both of these on the same line:

   283         #   -x      turn on expert mode

   284         #

   285         # But if the opt string list is too long, we put the help

   286         # string on a second line, indented to the same column it would

   287         # start in if it fit on the first line.

   288         #   -fFILENAME, --file=FILENAME

   289         #           read data from FILENAME

   290         result = []

   291         opts = self.option_strings[option]

   292         opt_width = self.help_position - self.current_indent - 2

   293         if len(opts) > opt_width:

   294             opts = "%*s%s\n" % (self.current_indent, "", opts)

   295             indent_first = self.help_position

   296         else:                       # start help on same line as opts

   297             opts = "%*s%-*s  " % (self.current_indent, "", opt_width, opts)

   298             indent_first = 0

   299         result.append(opts)

   300         if option.help:

   301             help_text = self.expand_default(option)

   302             help_lines = textwrap.wrap(help_text, self.help_width)

   303             result.append("%*s%s\n" % (indent_first, "", help_lines[0]))

   304             result.extend(["%*s%s\n" % (self.help_position, "", line)

   305                            for line in help_lines[1:]])

   306         elif opts[-1] != "\n":

   307             result.append("\n")

   308         return "".join(result)

   309 

   310     def store_option_strings(self, parser):

   311         self.indent()

   312         max_len = 0

   313         for opt in parser.option_list:

   314             strings = self.format_option_strings(opt)

   315             self.option_strings[opt] = strings

   316             max_len = max(max_len, len(strings) + self.current_indent)

   317         self.indent()

   318         for group in parser.option_groups:

   319             for opt in group.option_list:

   320                 strings = self.format_option_strings(opt)

   321                 self.option_strings[opt] = strings

   322                 max_len = max(max_len, len(strings) + self.current_indent)

   323         self.dedent()

   324         self.dedent()

   325         self.help_position = min(max_len + 2, self.max_help_position)

   326         self.help_width = self.width - self.help_position

   327 

   328     def format_option_strings(self, option):

   329         """Return a comma-separated list of option strings & metavariables."""

   330         if option.takes_value():

   331             metavar = option.metavar or option.dest.upper()

   332             short_opts = [self._short_opt_fmt % (sopt, metavar)

   333                           for sopt in option._short_opts]

   334             long_opts = [self._long_opt_fmt % (lopt, metavar)

   335                          for lopt in option._long_opts]

   336         else:

   337             short_opts = option._short_opts

   338             long_opts = option._long_opts

   339 

   340         if self.short_first:

   341             opts = short_opts + long_opts

   342         else:

   343             opts = long_opts + short_opts

   344 

   345         return ", ".join(opts)

   346 

   347 class IndentedHelpFormatter (HelpFormatter):

   348     """Format help with indented section bodies.

   349     """

   350 

   351     def __init__(self,

   352                  indent_increment=2,

   353                  max_help_position=24,

   354                  width=None,

   355                  short_first=1):

   356         HelpFormatter.__init__(

   357             self, indent_increment, max_help_position, width, short_first)

   358 

   359     def format_usage(self, usage):

   360         return _("Usage: %s\n") % usage

   361 

   362     def format_heading(self, heading):

   363         return "%*s%s:\n" % (self.current_indent, "", heading)

   364 

   365 

   366 class TitledHelpFormatter (HelpFormatter):

   367     """Format help with underlined section headers.

   368     """

   369 

   370     def __init__(self,

   371                  indent_increment=0,

   372                  max_help_position=24,

   373                  width=None,

   374                  short_first=0):

   375         HelpFormatter.__init__ (

   376             self, indent_increment, max_help_position, width, short_first)

   377 

   378     def format_usage(self, usage):

   379         return "%s  %s\n" % (self.format_heading(_("Usage")), usage)

   380 

   381     def format_heading(self, heading):

   382         return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading))

   383 

   384 

   385 def _parse_num(val, type):

   386     if val[:2].lower() == "0x":         # hexadecimal

   387         radix = 16

   388     elif val[:2].lower() == "0b":       # binary

   389         radix = 2

   390         val = val[2:] or "0"            # have to remove "0b" prefix

   391     elif val[:1] == "0":                # octal

   392         radix = 8

   393     else:                               # decimal

   394         radix = 10

   395 

   396     return type(val, radix)

   397 

   398 def _parse_int(val):

   399     return _parse_num(val, int)

   400 

   401 def _parse_long(val):

   402     return _parse_num(val, long)

   403 

   404 _builtin_cvt = { "int" : (_parse_int, _("integer")),

   405                  "long" : (_parse_long, _("long integer")),

   406                  "float" : (float, _("floating-point")),

   407                  "complex" : (complex, _("complex")) }

   408 

   409 def check_builtin(option, opt, value):

   410     (cvt, what) = _builtin_cvt[option.type]

   411     try:

   412         return cvt(value)

   413     except ValueError:

   414         raise OptionValueError(

   415             _("option %s: invalid %s value: %r") % (opt, what, value))

   416 

   417 def check_choice(option, opt, value):

   418     if value in option.choices:

   419         return value

   420     else:

   421         choices = ", ".join(map(repr, option.choices))

   422         raise OptionValueError(

   423             _("option %s: invalid choice: %r (choose from %s)")

   424             % (opt, value, choices))

   425 

   426 # Not supplying a default is different from a default of None,

   427 # so we need an explicit "not supplied" value.

   428 NO_DEFAULT = ("NO", "DEFAULT")

   429 

   430 

   431 class Option:

   432     """

   433     Instance attributes:

   434       _short_opts : [string]

   435       _long_opts : [string]

   436 

   437       action : string

   438       type : string

   439       dest : string

   440       default : any

   441       nargs : int

   442       const : any

   443       choices : [string]

   444       callback : function

   445       callback_args : (any*)

   446       callback_kwargs : { string : any }

   447       help : string

   448       metavar : string

   449     """

   450 

   451     # The list of instance attributes that may be set through

   452     # keyword args to the constructor.

   453     ATTRS = ['action',

   454              'type',

   455              'dest',

   456              'default',

   457              'nargs',

   458              'const',

   459              'choices',

   460              'callback',

   461              'callback_args',

   462              'callback_kwargs',

   463              'help',

   464              'metavar']

   465 

   466     # The set of actions allowed by option parsers.  Explicitly listed

   467     # here so the constructor can validate its arguments.

   468     ACTIONS = ("store",

   469                "store_const",

   470                "store_true",

   471                "store_false",

   472                "append",

   473                "append_const",

   474                "count",

   475                "callback",

   476                "help",

   477                "version")

   478 

   479     # The set of actions that involve storing a value somewhere;

   480     # also listed just for constructor argument validation.  (If

   481     # the action is one of these, there must be a destination.)

   482     STORE_ACTIONS = ("store",

   483                      "store_const",

   484                      "store_true",

   485                      "store_false",

   486                      "append",

   487                      "append_const",

   488                      "count")

   489 

   490     # The set of actions for which it makes sense to supply a value

   491     # type, ie. which may consume an argument from the command line.

   492     TYPED_ACTIONS = ("store",

   493                      "append",

   494                      "callback")

   495 

   496     # The set of actions which *require* a value type, ie. that

   497     # always consume an argument from the command line.

   498     ALWAYS_TYPED_ACTIONS = ("store",

   499                             "append")

   500 

   501     # The set of actions which take a 'const' attribute.

   502     CONST_ACTIONS = ("store_const",

   503                      "append_const")

   504 

   505     # The set of known types for option parsers.  Again, listed here for

   506     # constructor argument validation.

   507     TYPES = ("string", "int", "long", "float", "complex", "choice")

   508 

   509     # Dictionary of argument checking functions, which convert and

   510     # validate option arguments according to the option type.

   511     #

   512     # Signature of checking functions is:

   513     #   check(option : Option, opt : string, value : string) -> any

   514     # where

   515     #   option is the Option instance calling the checker

   516     #   opt is the actual option seen on the command-line

   517     #     (eg. "-a", "--file")

   518     #   value is the option argument seen on the command-line

   519     #

   520     # The return value should be in the appropriate Python type

   521     # for option.type -- eg. an integer if option.type == "int".

   522     #

   523     # If no checker is defined for a type, arguments will be

   524     # unchecked and remain strings.

   525     TYPE_CHECKER = { "int"    : check_builtin,

   526                      "long"   : check_builtin,

   527                      "float"  : check_builtin,

   528                      "complex": check_builtin,

   529                      "choice" : check_choice,

   530                    }

   531 

   532 

   533     # CHECK_METHODS is a list of unbound method objects; they are called

   534     # by the constructor, in order, after all attributes are

   535     # initialized.  The list is created and filled in later, after all

   536     # the methods are actually defined.  (I just put it here because I

   537     # like to define and document all class attributes in the same

   538     # place.)  Subclasses that add another _check_*() method should

   539     # define their own CHECK_METHODS list that adds their check method

   540     # to those from this class.

   541     CHECK_METHODS = None

   542 

   543 

   544     # -- Constructor/initialization methods ----------------------------

   545 

   546     def __init__(self, *opts, **attrs):

   547         # Set _short_opts, _long_opts attrs from 'opts' tuple.

   548         # Have to be set now, in case no option strings are supplied.

   549         self._short_opts = []

   550         self._long_opts = []

   551         opts = self._check_opt_strings(opts)

   552         self._set_opt_strings(opts)

   553 

   554         # Set all other attrs (action, type, etc.) from 'attrs' dict

   555         self._set_attrs(attrs)

   556 

   557         # Check all the attributes we just set.  There are lots of

   558         # complicated interdependencies, but luckily they can be farmed

   559         # out to the _check_*() methods listed in CHECK_METHODS -- which

   560         # could be handy for subclasses!  The one thing these all share

   561         # is that they raise OptionError if they discover a problem.

   562         for checker in self.CHECK_METHODS:

   563             checker(self)

   564 

   565     def _check_opt_strings(self, opts):

   566         # Filter out None because early versions of Optik had exactly

   567         # one short option and one long option, either of which

   568         # could be None.

   569         opts = filter(None, opts)

   570         if not opts:

   571             raise TypeError("at least one option string must be supplied")

   572         return opts

   573 

   574     def _set_opt_strings(self, opts):

   575         for opt in opts:

   576             if len(opt) < 2:

   577                 raise OptionError(

   578                     "invalid option string %r: "

   579                     "must be at least two characters long" % opt, self)

   580             elif len(opt) == 2:

   581                 if not (opt[0] == "-" and opt[1] != "-"):

   582                     raise OptionError(

   583                         "invalid short option string %r: "

   584                         "must be of the form -x, (x any non-dash char)" % opt,

   585                         self)

   586                 self._short_opts.append(opt)

   587             else:

   588                 if not (opt[0:2] == "--" and opt[2] != "-"):

   589                     raise OptionError(

   590                         "invalid long option string %r: "

   591                         "must start with --, followed by non-dash" % opt,

   592                         self)

   593                 self._long_opts.append(opt)

   594 

   595     def _set_attrs(self, attrs):

   596         for attr in self.ATTRS:

   597             if attr in attrs:

   598                 setattr(self, attr, attrs[attr])

   599                 del attrs[attr]

   600             else:

   601                 if attr == 'default':

   602                     setattr(self, attr, NO_DEFAULT)

   603                 else:

   604                     setattr(self, attr, None)

   605         if attrs:

   606             attrs = attrs.keys()

   607             attrs.sort()

   608             raise OptionError(

   609                 "invalid keyword arguments: %s" % ", ".join(attrs),

   610                 self)

   611 

   612 

   613     # -- Constructor validation methods --------------------------------

   614 

   615     def _check_action(self):

   616         if self.action is None:

   617             self.action = "store"

   618         elif self.action not in self.ACTIONS:

   619             raise OptionError("invalid action: %r" % self.action, self)

   620 

   621     def _check_type(self):

   622         if self.type is None:

   623             if self.action in self.ALWAYS_TYPED_ACTIONS:

   624                 if self.choices is not None:

   625                     # The "choices" attribute implies "choice" type.

   626                     self.type = "choice"

   627                 else:

   628                     # No type given?  "string" is the most sensible default.

   629                     self.type = "string"

   630         else:

   631             # Allow type objects or builtin type conversion functions

   632             # (int, str, etc.) as an alternative to their names.  (The

   633             # complicated check of __builtin__ is only necessary for

   634             # Python 2.1 and earlier, and is short-circuited by the

   635             # first check on modern Pythons.)

   636             import __builtin__

   637             if ( type(self.type) is types.TypeType or

   638                  (hasattr(self.type, "__name__") and

   639                   getattr(__builtin__, self.type.__name__, None) is self.type) ):

   640                 self.type = self.type.__name__

   641 

   642             if self.type == "str":

   643                 self.type = "string"

   644 

   645             if self.type not in self.TYPES:

   646                 raise OptionError("invalid option type: %r" % self.type, self)

   647             if self.action not in self.TYPED_ACTIONS:

   648                 raise OptionError(

   649                     "must not supply a type for action %r" % self.action, self)

   650 

   651     def _check_choice(self):

   652         if self.type == "choice":

   653             if self.choices is None:

   654                 raise OptionError(

   655                     "must supply a list of choices for type 'choice'", self)

   656             elif type(self.choices) not in (types.TupleType, types.ListType):

   657                 raise OptionError(

   658                     "choices must be a list of strings ('%s' supplied)"

   659                     % str(type(self.choices)).split("'")[1], self)

   660         elif self.choices is not None:

   661             raise OptionError(

   662                 "must not supply choices for type %r" % self.type, self)

   663 

   664     def _check_dest(self):

   665         # No destination given, and we need one for this action.  The

   666         # self.type check is for callbacks that take a value.

   667         takes_value = (self.action in self.STORE_ACTIONS or

   668                        self.type is not None)

   669         if self.dest is None and takes_value:

   670 

   671             # Glean a destination from the first long option string,

   672             # or from the first short option string if no long options.

   673             if self._long_opts:

   674                 # eg. "--foo-bar" -> "foo_bar"

   675                 self.dest = self._long_opts[0][2:].replace('-', '_')

   676             else:

   677                 self.dest = self._short_opts[0][1]

   678 

   679     def _check_const(self):

   680         if self.action not in self.CONST_ACTIONS and self.const is not None:

   681             raise OptionError(

   682                 "'const' must not be supplied for action %r" % self.action,

   683                 self)

   684 

   685     def _check_nargs(self):

   686         if self.action in self.TYPED_ACTIONS:

   687             if self.nargs is None:

   688                 self.nargs = 1

   689         elif self.nargs is not None:

   690             raise OptionError(

   691                 "'nargs' must not be supplied for action %r" % self.action,

   692                 self)

   693 

   694     def _check_callback(self):

   695         if self.action == "callback":

   696             if not hasattr(self.callback, '__call__'):

   697                 raise OptionError(

   698                     "callback not callable: %r" % self.callback, self)

   699             if (self.callback_args is not None and

   700                 type(self.callback_args) is not types.TupleType):

   701                 raise OptionError(

   702                     "callback_args, if supplied, must be a tuple: not %r"

   703                     % self.callback_args, self)

   704             if (self.callback_kwargs is not None and

   705                 type(self.callback_kwargs) is not types.DictType):

   706                 raise OptionError(

   707                     "callback_kwargs, if supplied, must be a dict: not %r"

   708                     % self.callback_kwargs, self)

   709         else:

   710             if self.callback is not None:

   711                 raise OptionError(

   712                     "callback supplied (%r) for non-callback option"

   713                     % self.callback, self)

   714             if self.callback_args is not None:

   715                 raise OptionError(

   716                     "callback_args supplied for non-callback option", self)

   717             if self.callback_kwargs is not None:

   718                 raise OptionError(

   719                     "callback_kwargs supplied for non-callback option", self)

   720 

   721 

   722     CHECK_METHODS = [_check_action,

   723                      _check_type,

   724                      _check_choice,

   725                      _check_dest,

   726                      _check_const,

   727                      _check_nargs,

   728                      _check_callback]

   729 

   730 

   731     # -- Miscellaneous methods -----------------------------------------

   732 

   733     def __str__(self):

   734         return "/".join(self._short_opts + self._long_opts)

   735 

   736     __repr__ = _repr

   737 

   738     def takes_value(self):

   739         return self.type is not None

   740 

   741     def get_opt_string(self):

   742         if self._long_opts:

   743             return self._long_opts[0]

   744         else:

   745             return self._short_opts[0]

   746 

   747 

   748     # -- Processing methods --------------------------------------------

   749 

   750     def check_value(self, opt, value):

   751         checker = self.TYPE_CHECKER.get(self.type)

   752         if checker is None:

   753             return value

   754         else:

   755             return checker(self, opt, value)

   756 

   757     def convert_value(self, opt, value):

   758         if value is not None:

   759             if self.nargs == 1:

   760                 return self.check_value(opt, value)

   761             else:

   762                 return tuple([self.check_value(opt, v) for v in value])

   763 

   764     def process(self, opt, value, values, parser):

   765 

   766         # First, convert the value(s) to the right type.  Howl if any

   767         # value(s) are bogus.

   768         value = self.convert_value(opt, value)

   769 

   770         # And then take whatever action is expected of us.

   771         # This is a separate method to make life easier for

   772         # subclasses to add new actions.

   773         return self.take_action(

   774             self.action, self.dest, opt, value, values, parser)

   775 

   776     def take_action(self, action, dest, opt, value, values, parser):

   777         if action == "store":

   778             setattr(values, dest, value)

   779         elif action == "store_const":

   780             setattr(values, dest, self.const)

   781         elif action == "store_true":

   782             setattr(values, dest, True)

   783         elif action == "store_false":

   784             setattr(values, dest, False)

   785         elif action == "append":

   786             values.ensure_value(dest, []).append(value)

   787         elif action == "append_const":

   788             values.ensure_value(dest, []).append(self.const)

   789         elif action == "count":

   790             setattr(values, dest, values.ensure_value(dest, 0) + 1)

   791         elif action == "callback":

   792             args = self.callback_args or ()

   793             kwargs = self.callback_kwargs or {}

   794             self.callback(self, opt, value, parser, *args, **kwargs)

   795         elif action == "help":

   796             parser.print_help()

   797             parser.exit()

   798         elif action == "version":

   799             parser.print_version()

   800             parser.exit()

   801         else:

   802             raise RuntimeError, "unknown action %r" % self.action

   803 

   804         return 1

   805 

   806 # class Option

   807 

   808 

   809 SUPPRESS_HELP = "SUPPRESS"+"HELP"

   810 SUPPRESS_USAGE = "SUPPRESS"+"USAGE"

   811 

   812 try:

   813     basestring

   814 except NameError:

   815     def isbasestring(x):

   816         return isinstance(x, (types.StringType, types.UnicodeType))

   817 else:

   818     def isbasestring(x):

   819         return isinstance(x, basestring)

   820 

   821 class Values:

   822 

   823     def __init__(self, defaults=None):

   824         if defaults:

   825             for (attr, val) in defaults.items():

   826                 setattr(self, attr, val)

   827 

   828     def __str__(self):

   829         return str(self.__dict__)

   830 

   831     __repr__ = _repr

   832 

   833     def __cmp__(self, other):

   834         if isinstance(other, Values):

   835             return cmp(self.__dict__, other.__dict__)

   836         elif isinstance(other, types.DictType):

   837             return cmp(self.__dict__, other)

   838         else:

   839             return -1

   840 

   841     def _update_careful(self, dict):

   842         """

   843         Update the option values from an arbitrary dictionary, but only

   844         use keys from dict that already have a corresponding attribute

   845         in self.  Any keys in dict without a corresponding attribute

   846         are silently ignored.

   847         """

   848         for attr in dir(self):

   849             if attr in dict:

   850                 dval = dict[attr]

   851                 if dval is not None:

   852                     setattr(self, attr, dval)

   853 

   854     def _update_loose(self, dict):

   855         """

   856         Update the option values from an arbitrary dictionary,

   857         using all keys from the dictionary regardless of whether

   858         they have a corresponding attribute in self or not.

   859         """

   860         self.__dict__.update(dict)

   861 

   862     def _update(self, dict, mode):

   863         if mode == "careful":

   864             self._update_careful(dict)

   865         elif mode == "loose":

   866             self._update_loose(dict)

   867         else:

   868             raise ValueError, "invalid update mode: %r" % mode

   869 

   870     def read_module(self, modname, mode="careful"):

   871         __import__(modname)

   872         mod = sys.modules[modname]

   873         self._update(vars(mod), mode)

   874 

   875     def read_file(self, filename, mode="careful"):

   876         vars = {}

   877         execfile(filename, vars)

   878         self._update(vars, mode)

   879 

   880     def ensure_value(self, attr, value):

   881         if not hasattr(self, attr) or getattr(self, attr) is None:

   882             setattr(self, attr, value)

   883         return getattr(self, attr)

   884 

   885 

   886 class OptionContainer:

   887 

   888     """

   889     Abstract base class.

   890 

   891     Class attributes:

   892       standard_option_list : [Option]

   893         list of standard options that will be accepted by all instances

   894         of this parser class (intended to be overridden by subclasses).

   895 

   896     Instance attributes:

   897       option_list : [Option]

   898         the list of Option objects contained by this OptionContainer

   899       _short_opt : { string : Option }

   900         dictionary mapping short option strings, eg. "-f" or "-X",

   901         to the Option instances that implement them.  If an Option

   902         has multiple short option strings, it will appears in this

   903         dictionary multiple times. [1]

   904       _long_opt : { string : Option }

   905         dictionary mapping long option strings, eg. "--file" or

   906         "--exclude", to the Option instances that implement them.

   907         Again, a given Option can occur multiple times in this

   908         dictionary. [1]

   909       defaults : { string : any }

   910         dictionary mapping option destination names to default

   911         values for each destination [1]

   912 

   913     [1] These mappings are common to (shared by) all components of the

   914         controlling OptionParser, where they are initially created.

   915 

   916     """

   917 

   918     def __init__(self, option_class, conflict_handler, description):

   919         # Initialize the option list and related data structures.

   920         # This method must be provided by subclasses, and it must

   921         # initialize at least the following instance attributes:

   922         # option_list, _short_opt, _long_opt, defaults.

   923         self._create_option_list()

   924 

   925         self.option_class = option_class

   926         self.set_conflict_handler(conflict_handler)

   927         self.set_description(description)

   928 

   929     def _create_option_mappings(self):

   930         # For use by OptionParser constructor -- create the master

   931         # option mappings used by this OptionParser and all

   932         # OptionGroups that it owns.

   933         self._short_opt = {}            # single letter -> Option instance

   934         self._long_opt = {}             # long option -> Option instance

   935         self.defaults = {}              # maps option dest -> default value

   936 

   937 

   938     def _share_option_mappings(self, parser):

   939         # For use by OptionGroup constructor -- use shared option

   940         # mappings from the OptionParser that owns this OptionGroup.

   941         self._short_opt = parser._short_opt

   942         self._long_opt = parser._long_opt

   943         self.defaults = parser.defaults

   944 

   945     def set_conflict_handler(self, handler):

   946         if handler not in ("error", "resolve"):

   947             raise ValueError, "invalid conflict_resolution value %r" % handler

   948         self.conflict_handler = handler

   949 

   950     def set_description(self, description):

   951         self.description = description

   952 

   953     def get_description(self):

   954         return self.description

   955 

   956 

   957     def destroy(self):

   958         """see OptionParser.destroy()."""

   959         del self._short_opt

   960         del self._long_opt

   961         del self.defaults

   962 

   963 

   964     # -- Option-adding methods -----------------------------------------

   965 

   966     def _check_conflict(self, option):

   967         conflict_opts = []

   968         for opt in option._short_opts:

   969             if opt in self._short_opt:

   970                 conflict_opts.append((opt, self._short_opt[opt]))

   971         for opt in option._long_opts:

   972             if opt in self._long_opt:

   973                 conflict_opts.append((opt, self._long_opt[opt]))

   974 

   975         if conflict_opts:

   976             handler = self.conflict_handler

   977             if handler == "error":

   978                 raise OptionConflictError(

   979                     "conflicting option string(s): %s"

   980                     % ", ".join([co[0] for co in conflict_opts]),

   981                     option)

   982             elif handler == "resolve":

   983                 for (opt, c_option) in conflict_opts:

   984                     if opt.startswith("--"):

   985                         c_option._long_opts.remove(opt)

   986                         del self._long_opt[opt]

   987                     else:

   988                         c_option._short_opts.remove(opt)

   989                         del self._short_opt[opt]

   990                     if not (c_option._short_opts or c_option._long_opts):

   991                         c_option.container.option_list.remove(c_option)

   992 

   993     def add_option(self, *args, **kwargs):

   994         """add_option(Option)

   995            add_option(opt_str, ..., kwarg=val, ...)

   996         """

   997         if type(args[0]) is types.StringType:

   998             option = self.option_class(*args, **kwargs)

   999         elif len(args) == 1 and not kwargs:

  1000             option = args[0]

  1001             if not isinstance(option, Option):

  1002                 raise TypeError, "not an Option instance: %r" % option

  1003         else:

  1004             raise TypeError, "invalid arguments"

  1005 

  1006         self._check_conflict(option)

  1007 

  1008         self.option_list.append(option)

  1009         option.container = self

  1010         for opt in option._short_opts:

  1011             self._short_opt[opt] = option

  1012         for opt in option._long_opts:

  1013             self._long_opt[opt] = option

  1014 

  1015         if option.dest is not None:     # option has a dest, we need a default

  1016             if option.default is not NO_DEFAULT:

  1017                 self.defaults[option.dest] = option.default

  1018             elif option.dest not in self.defaults:

  1019                 self.defaults[option.dest] = None

  1020 

  1021         return option

  1022 

  1023     def add_options(self, option_list):

  1024         for option in option_list:

  1025             self.add_option(option)

  1026 

  1027     # -- Option query/removal methods ----------------------------------

  1028 

  1029     def get_option(self, opt_str):

  1030         return (self._short_opt.get(opt_str) or

  1031                 self._long_opt.get(opt_str))

  1032 

  1033     def has_option(self, opt_str):

  1034         return (opt_str in self._short_opt or

  1035                 opt_str in self._long_opt)

  1036 

  1037     def remove_option(self, opt_str):

  1038         option = self._short_opt.get(opt_str)

  1039         if option is None:

  1040             option = self._long_opt.get(opt_str)

  1041         if option is None:

  1042             raise ValueError("no such option %r" % opt_str)

  1043 

  1044         for opt in option._short_opts:

  1045             del self._short_opt[opt]

  1046         for opt in option._long_opts:

  1047             del self._long_opt[opt]

  1048         option.container.option_list.remove(option)

  1049 

  1050 

  1051     # -- Help-formatting methods ---------------------------------------

  1052 

  1053     def format_option_help(self, formatter):

  1054         if not self.option_list:

  1055             return ""

  1056         result = []

  1057         for option in self.option_list:

  1058             if not option.help is SUPPRESS_HELP:

  1059                 result.append(formatter.format_option(option))

  1060         return "".join(result)

  1061 

  1062     def format_description(self, formatter):

  1063         return formatter.format_description(self.get_description())

  1064 

  1065     def format_help(self, formatter):

  1066         result = []

  1067         if self.description:

  1068             result.append(self.format_description(formatter))

  1069         if self.option_list:

  1070             result.append(self.format_option_help(formatter))

  1071         return "\n".join(result)

  1072 

  1073 

  1074 class OptionGroup (OptionContainer):

  1075 

  1076     def __init__(self, parser, title, description=None):

  1077         self.parser = parser

  1078         OptionContainer.__init__(

  1079             self, parser.option_class, parser.conflict_handler, description)

  1080         self.title = title

  1081 

  1082     def _create_option_list(self):

  1083         self.option_list = []

  1084         self._share_option_mappings(self.parser)

  1085 

  1086     def set_title(self, title):

  1087         self.title = title

  1088 

  1089     def destroy(self):

  1090         """see OptionParser.destroy()."""

  1091         OptionContainer.destroy(self)

  1092         del self.option_list

  1093 

  1094     # -- Help-formatting methods ---------------------------------------

  1095 

  1096     def format_help(self, formatter):

  1097         result = formatter.format_heading(self.title)

  1098         formatter.indent()

  1099         result += OptionContainer.format_help(self, formatter)

  1100         formatter.dedent()

  1101         return result

  1102 

  1103 

  1104 class OptionParser (OptionContainer):

  1105 

  1106     """

  1107     Class attributes:

  1108       standard_option_list : [Option]

  1109         list of standard options that will be accepted by all instances

  1110         of this parser class (intended to be overridden by subclasses).

  1111 

  1112     Instance attributes:

  1113       usage : string

  1114         a usage string for your program.  Before it is displayed

  1115         to the user, "%prog" will be expanded to the name of

  1116         your program (self.prog or os.path.basename(sys.argv[0])).

  1117       prog : string

  1118         the name of the current program (to override

  1119         os.path.basename(sys.argv[0])).

  1120       epilog : string

  1121         paragraph of help text to print after option help

  1122 

  1123       option_groups : [OptionGroup]

  1124         list of option groups in this parser (option groups are

  1125         irrelevant for parsing the command-line, but very useful

  1126         for generating help)

  1127 

  1128       allow_interspersed_args : bool = true

  1129         if true, positional arguments may be interspersed with options.

  1130         Assuming -a and -b each take a single argument, the command-line

  1131           -ablah foo bar -bboo baz

  1132         will be interpreted the same as

  1133           -ablah -bboo -- foo bar baz

  1134         If this flag were false, that command line would be interpreted as

  1135           -ablah -- foo bar -bboo baz