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

     2 

     3 By Greg Ward <gward@python.net>

     4 

     5 Originally distributed as Optik; see http://optik.sourceforge.net/ .

     6 

     7 If you have problems with this module, please do not file bugs,

     8 patches, or feature requests with Python; instead, use Optik's

     9 SourceForge project page:

    10   http://sourceforge.net/projects/optik

    11 

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

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

    14 """

    15 

    16 # Python developers: please do not make changes to this file, since

    17 # it is automatically generated from the Optik source code.

    18 

    19 __version__ = "1.5.3"

    20 

    21 __all__ = ['Option',

    22            'SUPPRESS_HELP',

    23            'SUPPRESS_USAGE',

    24            'Values',

    25            'OptionContainer',

    26            'OptionGroup',

    27            'OptionParser',

    28            'HelpFormatter',

    29            'IndentedHelpFormatter',

    30            'TitledHelpFormatter',

    31            'OptParseError',

    32            'OptionError',

    33            'OptionConflictError',

    34            'OptionValueError',

    35            'BadOptionError']

    36 

    37 __copyright__ = """

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

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

    40 

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

    42 modification, are permitted provided that the following conditions are

    43 met:

    44 

    45   * Redistributions of source code must retain the above copyright

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

    47 

    48   * Redistributions in binary form must reproduce the above copyright

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

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

    51 

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

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

    54     this software without specific prior written permission.

    55 

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

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

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

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

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

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

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

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

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

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

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

    67 """

    68 

    69 import sys, os

    70 import types

    71 import textwrap

    72 

    73 def _repr(self):

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

    75 

    76 

    77 # This file was generated from:

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

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

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

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

    82 

    83 try:

    84     from gettext import gettext

    85 except ImportError:

    86     def gettext(message):

    87         return message

    88 _ = gettext

    89 

    90 

    91 class OptParseError (Exception):

    92     def __init__(self, msg):

    93         self.msg = msg

    94 

    95     def __str__(self):

    96         return self.msg

    97 

    98 

    99 class OptionError (OptParseError):

   100     """

   101     Raised if an Option instance is created with invalid or

   102     inconsistent arguments.

   103     """

   104 

   105     def __init__(self, msg, option):

   106         self.msg = msg

   107         self.option_id = str(option)

   108 

   109     def __str__(self):

   110         if self.option_id:

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

   112         else:

   113             return self.msg

   114 

   115 class OptionConflictError (OptionError):

   116     """

   117     Raised if conflicting options are added to an OptionParser.

   118     """

   119 

   120 class OptionValueError (OptParseError):

   121     """

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

   123     line.

   124     """

   125 

   126 class BadOptionError (OptParseError):

   127     """

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

   129     """

   130     def __init__(self, opt_str):

   131         self.opt_str = opt_str

   132 

   133     def __str__(self):

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

   135 

   136 class AmbiguousOptionError (BadOptionError):

   137     """

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

   139     """

   140     def __init__(self, opt_str, possibilities):

   141         BadOptionError.__init__(self, opt_str)

   142         self.possibilities = possibilities

   143 

   144     def __str__(self):

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

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

   147 

   148 

   149 class HelpFormatter:

   150 

   151     """

   152     Abstract base class for formatting option help.  OptionParser

   153     instances should use one of the HelpFormatter subclasses for

   154     formatting help; by default IndentedHelpFormatter is used.

   155 

   156     Instance attributes:

   157       parser : OptionParser

   158         the controlling OptionParser instance

   159       indent_increment : int

   160         the number of columns to indent per nesting level

   161       max_help_position : int

   162         the maximum starting column for option help text

   163       help_position : int

   164         the calculated starting column for option help text;

   165         initially the same as the maximum

   166       width : int

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

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

   169       level : int

   170         current indentation level

   171       current_indent : int

   172         current indentation level (in columns)

   173       help_width : int

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

   175       default_tag : str

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

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

   178       option_strings : { Option : str }

   179         maps Option instances to the snippet of help text explaining

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

   181         "-fFILE, --file=FILE"

   182       _short_opt_fmt : str

   183         format string controlling how short options with values are

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

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

   186         Optik supports.

   187       _long_opt_fmt : str

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

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

   190     """

   191 

   192     NO_DEFAULT_VALUE = "none"

   193 

   194     def __init__(self,

   195                  indent_increment,

   196                  max_help_position,

   197                  width,

   198                  short_first):

   199         self.parser = None

   200         self.indent_increment = indent_increment

   201         self.help_position = self.max_help_position = max_help_position

   202         if width is None:

   203             try:

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

   205             except (KeyError, ValueError):

   206                 width = 80

   207             width -= 2

   208         self.width = width

   209         self.current_indent = 0

   210         self.level = 0

   211         self.help_width = None          # computed later

   212         self.short_first = short_first

   213         self.default_tag = "%default"

   214         self.option_strings = {}

   215         self._short_opt_fmt = "%s %s"

   216         self._long_opt_fmt = "%s=%s"

   217 

   218     def set_parser(self, parser):

   219         self.parser = parser

   220 

   221     def set_short_opt_delimiter(self, delim):

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

   223             raise ValueError(

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

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

   226 

   227     def set_long_opt_delimiter(self, delim):

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

   229             raise ValueError(

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

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

   232 

   233     def indent(self):

   234         self.current_indent += self.indent_increment

   235         self.level += 1

   236 

   237     def dedent(self):

   238         self.current_indent -= self.indent_increment

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

   240         self.level -= 1

   241 

   242     def format_usage(self, usage):

   243         raise NotImplementedError, "subclasses must implement"

   244 

   245     def format_heading(self, heading):

   246         raise NotImplementedError, "subclasses must implement"

   247 

   248     def _format_text(self, text):

   249         """

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

   251         help output at the current indentation level.

   252         """

   253         text_width = self.width - self.current_indent

   254         indent = " "*self.current_indent

   255         return textwrap.fill(text,

   256                              text_width,

   257                              initial_indent=indent,

   258                              subsequent_indent=indent)

   259 

   260     def format_description(self, description):

   261         if description:

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

   263         else:

   264             return ""

   265 

   266     def format_epilog(self, epilog):

   267         if epilog:

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

   269         else:

   270             return ""

   271 

   272 

   273     def expand_default(self, option):

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

   275             return option.help

   276 

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

   278         if default_value is NO_DEFAULT or default_value is None:

   279             default_value = self.NO_DEFAULT_VALUE

   280 

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

   282 

   283     def format_option(self, option):

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

   285         #   * the opt strings and metavars

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

   287         #   * the user-supplied help string

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

   289         #

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

   291         #   -x      turn on expert mode

   292         #

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

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

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

   296         #   -fFILENAME, --file=FILENAME

   297         #           read data from FILENAME

   298         result = []

   299         opts = self.option_strings[option]

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

   301         if len(opts) > opt_width:

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

   303             indent_first = self.help_position

   304         else:                       # start help on same line as opts

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

   306             indent_first = 0

   307         result.append(opts)

   308         if option.help:

   309             help_text = self.expand_default(option)

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

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

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

   313                            for line in help_lines[1:]])

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

   315             result.append("\n")

   316         return "".join(result)

   317 

   318     def store_option_strings(self, parser):

   319         self.indent()

   320         max_len = 0

   321         for opt in parser.option_list:

   322             strings = self.format_option_strings(opt)

   323             self.option_strings[opt] = strings

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

   325         self.indent()

   326         for group in parser.option_groups:

   327             for opt in group.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.dedent()

   332         self.dedent()

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

   334         self.help_width = self.width - self.help_position

   335 

   336     def format_option_strings(self, option):

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

   338         if option.takes_value():

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

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

   341                           for sopt in option._short_opts]

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

   343                          for lopt in option._long_opts]

   344         else:

   345             short_opts = option._short_opts

   346             long_opts = option._long_opts

   347 

   348         if self.short_first:

   349             opts = short_opts + long_opts

   350         else:

   351             opts = long_opts + short_opts

   352 

   353         return ", ".join(opts)

   354 

   355 class IndentedHelpFormatter (HelpFormatter):

   356     """Format help with indented section bodies.

   357     """

   358 

   359     def __init__(self,

   360                  indent_increment=2,

   361                  max_help_position=24,

   362                  width=None,

   363                  short_first=1):

   364         HelpFormatter.__init__(

   365             self, indent_increment, max_help_position, width, short_first)

   366 

   367     def format_usage(self, usage):

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

   369 

   370     def format_heading(self, heading):

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

   372 

   373 

   374 class TitledHelpFormatter (HelpFormatter):

   375     """Format help with underlined section headers.

   376     """

   377 

   378     def __init__(self,

   379                  indent_increment=0,

   380                  max_help_position=24,

   381                  width=None,

   382                  short_first=0):

   383         HelpFormatter.__init__ (

   384             self, indent_increment, max_help_position, width, short_first)

   385 

   386     def format_usage(self, usage):

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

   388 

   389     def format_heading(self, heading):

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

   391 

   392 

   393 def _parse_num(val, type):

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

   395         radix = 16

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

   397         radix = 2

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

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

   400         radix = 8

   401     else:                               # decimal

   402         radix = 10

   403 

   404     return type(val, radix)

   405 

   406 def _parse_int(val):

   407     return _parse_num(val, int)

   408 

   409 def _parse_long(val):

   410     return _parse_num(val, long)

   411 

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

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

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

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

   416 

   417 def check_builtin(option, opt, value):

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

   419     try:

   420         return cvt(value)

   421     except ValueError:

   422         raise OptionValueError(

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

   424 

   425 def check_choice(option, opt, value):

   426     if value in option.choices:

   427         return value

   428     else:

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

   430         raise OptionValueError(

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

   432             % (opt, value, choices))

   433 

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

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

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

   437 

   438 

   439 class Option:

   440     """

   441     Instance attributes:

   442       _short_opts : [string]

   443       _long_opts : [string]

   444 

   445       action : string

   446       type : string

   447       dest : string

   448       default : any

   449       nargs : int

   450       const : any

   451       choices : [string]

   452       callback : function

   453       callback_args : (any*)

   454       callback_kwargs : { string : any }

   455       help : string

   456       metavar : string

   457     """

   458 

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

   460     # keyword args to the constructor.

   461     ATTRS = ['action',

   462              'type',

   463              'dest',

   464              'default',

   465              'nargs',

   466              'const',

   467              'choices',

   468              'callback',

   469              'callback_args',

   470              'callback_kwargs',

   471              'help',

   472              'metavar']

   473 

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

   475     # here so the constructor can validate its arguments.

   476     ACTIONS = ("store",

   477                "store_const",

   478                "store_true",

   479                "store_false",

   480                "append",

   481                "append_const",

   482                "count",

   483                "callback",

   484                "help",

   485                "version")

   486 

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

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

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

   490     STORE_ACTIONS = ("store",

   491                      "store_const",

   492                      "store_true",

   493                      "store_false",

   494                      "append",

   495                      "append_const",

   496                      "count")

   497 

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

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

   500     TYPED_ACTIONS = ("store",

   501                      "append",

   502                      "callback")

   503 

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

   505     # always consume an argument from the command line.

   506     ALWAYS_TYPED_ACTIONS = ("store",

   507                             "append")

   508 

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

   510     CONST_ACTIONS = ("store_const",

   511                      "append_const")

   512 

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

   514     # constructor argument validation.

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

   516 

   517     # Dictionary of argument checking functions, which convert and

   518     # validate option arguments according to the option type.

   519     #

   520     # Signature of checking functions is:

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

   522     # where

   523     #   option is the Option instance calling the checker

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

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

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

   527     #

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

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

   530     #

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

   532     # unchecked and remain strings.

   533     TYPE_CHECKER = { "int"    : check_builtin,

   534                      "long"   : check_builtin,

   535                      "float"  : check_builtin,

   536                      "complex": check_builtin,

   537                      "choice" : check_choice,

   538                    }

   539 

   540 

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

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

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

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

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

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

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

   548     # to those from this class.

   549     CHECK_METHODS = None

   550 

   551 

   552     # -- Constructor/initialization methods ----------------------------

   553 

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

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

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

   557         self._short_opts = []

   558         self._long_opts = []

   559         opts = self._check_opt_strings(opts)

   560         self._set_opt_strings(opts)

   561 

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

   563         self._set_attrs(attrs)

   564 

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

   566         # complicated interdependencies, but luckily they can be farmed

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

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

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

   570         for checker in self.CHECK_METHODS:

   571             checker(self)

   572 

   573     def _check_opt_strings(self, opts):

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

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

   576         # could be None.

   577         opts = filter(None, opts)

   578         if not opts:

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

   580         return opts

   581 

   582     def _set_opt_strings(self, opts):

   583         for opt in opts:

   584             if len(opt) < 2:

   585                 raise OptionError(

   586                     "invalid option string %r: "

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

   588             elif len(opt) == 2:

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

   590                     raise OptionError(

   591                         "invalid short option string %r: "

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

   593                         self)

   594                 self._short_opts.append(opt)

   595             else:

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

   597                     raise OptionError(

   598                         "invalid long option string %r: "

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

   600                         self)

   601                 self._long_opts.append(opt)

   602 

   603     def _set_attrs(self, attrs):

   604         for attr in self.ATTRS:

   605             if attrs.has_key(attr):

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

   607                 del attrs[attr]

   608             else:

   609                 if attr == 'default':

   610                     setattr(self, attr, NO_DEFAULT)

   611                 else:

   612                     setattr(self, attr, None)

   613         if attrs:

   614             attrs = attrs.keys()

   615             attrs.sort()

   616             raise OptionError(

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

   618                 self)

   619 

   620 

   621     # -- Constructor validation methods --------------------------------

   622 

   623     def _check_action(self):

   624         if self.action is None:

   625             self.action = "store"

   626         elif self.action not in self.ACTIONS:

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

   628 

   629     def _check_type(self):

   630         if self.type is None:

   631             if self.action in self.ALWAYS_TYPED_ACTIONS:

   632                 if self.choices is not None:

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

   634                     self.type = "choice"

   635                 else:

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

   637                     self.type = "string"

   638         else:

   639             # Allow type objects or builtin type conversion functions

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

   641             # complicated check of __builtin__ is only necessary for

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

   643             # first check on modern Pythons.)

   644             import __builtin__

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

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

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

   648                 self.type = self.type.__name__

   649 

   650             if self.type == "str":

   651                 self.type = "string"

   652 

   653             if self.type not in self.TYPES:

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

   655             if self.action not in self.TYPED_ACTIONS:

   656                 raise OptionError(

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

   658 

   659     def _check_choice(self):

   660         if self.type == "choice":

   661             if self.choices is None:

   662                 raise OptionError(

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

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

   665                 raise OptionError(

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

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

   668         elif self.choices is not None:

   669             raise OptionError(

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

   671 

   672     def _check_dest(self):

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

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

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

   676                        self.type is not None)

   677         if self.dest is None and takes_value:

   678 

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

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

   681             if self._long_opts:

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

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

   684             else:

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

   686 

   687     def _check_const(self):

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

   689             raise OptionError(

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

   691                 self)

   692 

   693     def _check_nargs(self):

   694         if self.action in self.TYPED_ACTIONS:

   695             if self.nargs is None:

   696                 self.nargs = 1

   697         elif self.nargs is not None:

   698             raise OptionError(

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

   700                 self)

   701 

   702     def _check_callback(self):

   703         if self.action == "callback":

   704             if not callable(self.callback):

   705                 raise OptionError(

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

   707             if (self.callback_args is not None and

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

   709                 raise OptionError(

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

   711                     % self.callback_args, self)

   712             if (self.callback_kwargs is not None and

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

   714                 raise OptionError(

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

   716                     % self.callback_kwargs, self)

   717         else:

   718             if self.callback is not None:

   719                 raise OptionError(

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

   721                     % self.callback, self)

   722             if self.callback_args is not None:

   723                 raise OptionError(

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

   725             if self.callback_kwargs is not None:

   726                 raise OptionError(

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

   728 

   729 

   730     CHECK_METHODS = [_check_action,

   731                      _check_type,

   732                      _check_choice,

   733                      _check_dest,

   734                      _check_const,

   735                      _check_nargs,

   736                      _check_callback]

   737 

   738 

   739     # -- Miscellaneous methods -----------------------------------------

   740 

   741     def __str__(self):

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

   743 

   744     __repr__ = _repr

   745 

   746     def takes_value(self):

   747         return self.type is not None

   748 

   749     def get_opt_string(self):

   750         if self._long_opts:

   751             return self._long_opts[0]

   752         else:

   753             return self._short_opts[0]

   754 

   755 

   756     # -- Processing methods --------------------------------------------

   757 

   758     def check_value(self, opt, value):

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

   760         if checker is None:

   761             return value

   762         else:

   763             return checker(self, opt, value)

   764 

   765     def convert_value(self, opt, value):

   766         if value is not None:

   767             if self.nargs == 1:

   768                 return self.check_value(opt, value)

   769             else:

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

   771 

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

   773 

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

   775         # value(s) are bogus.

   776         value = self.convert_value(opt, value)

   777 

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

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

   780         # subclasses to add new actions.

   781         return self.take_action(

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

   783 

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

   785         if action == "store":

   786             setattr(values, dest, value)

   787         elif action == "store_const":

   788             setattr(values, dest, self.const)

   789         elif action == "store_true":

   790             setattr(values, dest, True)

   791         elif action == "store_false":

   792             setattr(values, dest, False)

   793         elif action == "append":

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

   795         elif action == "append_const":

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

   797         elif action == "count":

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

   799         elif action == "callback":

   800             args = self.callback_args or ()

   801             kwargs = self.callback_kwargs or {}

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

   803         elif action == "help":

   804             parser.print_help()

   805             parser.exit()

   806         elif action == "version":

   807             parser.print_version()

   808             parser.exit()

   809         else:

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

   811 

   812         return 1

   813 

   814 # class Option

   815 

   816 

   817 SUPPRESS_HELP = "SUPPRESS"+"HELP"

   818 SUPPRESS_USAGE = "SUPPRESS"+"USAGE"

   819 

   820 # For compatibility with Python 2.2

   821 try:

   822     True, False

   823 except NameError:

   824     (True, False) = (1, 0)

   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 

   836 class Values:

   837 

   838     def __init__(self, defaults=None):

   839         if defaults:

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

   841                 setattr(self, attr, val)

   842 

   843     def __str__(self):

   844         return str(self.__dict__)

   845 

   846     __repr__ = _repr

   847 

   848     def __cmp__(self, other):

   849         if isinstance(other, Values):

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

   851         elif isinstance(other, types.DictType):

   852             return cmp(self.__dict__, other)

   853         else:

   854             return -1

   855 

   856     def _update_careful(self, dict):

   857         """

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

   859         use keys from dict that already have a corresponding attribute

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

   861         are silently ignored.

   862         """

   863         for attr in dir(self):

   864             if dict.has_key(attr):

   865                 dval = dict[attr]

   866                 if dval is not None:

   867                     setattr(self, attr, dval)

   868 

   869     def _update_loose(self, dict):

   870         """

   871         Update the option values from an arbitrary dictionary,

   872         using all keys from the dictionary regardless of whether

   873         they have a corresponding attribute in self or not.

   874         """

   875         self.__dict__.update(dict)

   876 

   877     def _update(self, dict, mode):

   878         if mode == "careful":

   879             self._update_careful(dict)

   880         elif mode == "loose":

   881             self._update_loose(dict)

   882         else:

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

   884 

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

   886         __import__(modname)

   887         mod = sys.modules[modname]

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

   889 

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

   891         vars = {}

   892         execfile(filename, vars)

   893         self._update(vars, mode)

   894 

   895     def ensure_value(self, attr, value):

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

   897             setattr(self, attr, value)

   898         return getattr(self, attr)

   899 

   900 

   901 class OptionContainer:

   902 

   903     """

   904     Abstract base class.

   905 

   906     Class attributes:

   907       standard_option_list : [Option]

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

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

   910 

   911     Instance attributes:

   912       option_list : [Option]

   913         the list of Option objects contained by this OptionContainer

   914       _short_opt : { string : Option }

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

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

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

   918         dictionary multiple times. [1]

   919       _long_opt : { string : Option }

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

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

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

   923         dictionary. [1]

   924       defaults : { string : any }

   925         dictionary mapping option destination names to default

   926         values for each destination [1]

   927 

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

   929         controlling OptionParser, where they are initially created.

   930 

   931     """

   932 

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

   934         # Initialize the option list and related data structures.

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

   936         # initialize at least the following instance attributes:

   937         # option_list, _short_opt, _long_opt, defaults.

   938         self._create_option_list()

   939 

   940         self.option_class = option_class

   941         self.set_conflict_handler(conflict_handler)

   942         self.set_description(description)

   943 

   944     def _create_option_mappings(self):

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

   946         # option mappings used by this OptionParser and all

   947         # OptionGroups that it owns.

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

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

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

   951 

   952 

   953     def _share_option_mappings(self, parser):

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

   955         # mappings from the OptionParser that owns this OptionGroup.

   956         self._short_opt = parser._short_opt

   957         self._long_opt = parser._long_opt

   958         self.defaults = parser.defaults

   959 

   960     def set_conflict_handler(self, handler):

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

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

   963         self.conflict_handler = handler

   964 

   965     def set_description(self, description):

   966         self.description = description

   967 

   968     def get_description(self):

   969         return self.description

   970 

   971 

   972     def destroy(self):

   973         """see OptionParser.destroy()."""

   974         del self._short_opt

   975         del self._long_opt

   976         del self.defaults

   977 

   978 

   979     # -- Option-adding methods -----------------------------------------

   980 

   981     def _check_conflict(self, option):

   982         conflict_opts = []

   983         for opt in option._short_opts:

   984             if self._short_opt.has_key(opt):

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

   986         for opt in option._long_opts:

   987             if self._long_opt.has_key(opt):

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

   989 

   990         if conflict_opts:

   991             handler = self.conflict_handler

   992             if handler == "error":

   993                 raise OptionConflictError(

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

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

   996                     option)

   997             elif handler == "resolve":

   998                 for (opt, c_option) in conflict_opts:

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

  1000                         c_option._long_opts.remove(opt)

  1001                         del self._long_opt[opt]

  1002                     else:

  1003                         c_option._short_opts.remove(opt)

  1004                         del self._short_opt[opt]

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

  1006                         c_option.container.option_list.remove(c_option)

  1007 

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

  1009         """add_option(Option)

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

  1011         """

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

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

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

  1015             option = args[0]

  1016             if not isinstance(option, Option):

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

  1018         else:

  1019             raise TypeError, "invalid arguments"

  1020 

  1021         self._check_conflict(option)

  1022 

  1023         self.option_list.append(option)

  1024         option.container = self

  1025         for opt in option._short_opts:

  1026             self._short_opt[opt] = option

  1027         for opt in option._long_opts:

  1028             self._long_opt[opt] = option

  1029 

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

  1031             if option.default is not NO_DEFAULT:

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

  1033             elif not self.defaults.has_key(option.dest):

  1034                 self.defaults[option.dest] = None

  1035 

  1036         return option

  1037 

  1038     def add_options(self, option_list):

  1039         for option in option_list:

  1040             self.add_option(option)

  1041 

  1042     # -- Option query/removal methods ----------------------------------

  1043 

  1044     def get_option(self, opt_str):

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

  1046                 self._long_opt.get(opt_str))

  1047 

  1048     def has_option(self, opt_str):

  1049         return (self._short_opt.has_key(opt_str) or

  1050                 self._long_opt.has_key(opt_str))

  1051 

  1052     def remove_option(self, opt_str):

  1053         option = self._short_opt.get(opt_str)

  1054         if option is None:

  1055             option = self._long_opt.get(opt_str)

  1056         if option is None:

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

  1058 

  1059         for opt in option._short_opts:

  1060             del self._short_opt[opt]

  1061         for opt in option._long_opts:

  1062             del self._long_opt[opt]

  1063         option.container.option_list.remove(option)

  1064 

  1065 

  1066     # -- Help-formatting methods ---------------------------------------

  1067 

  1068     def format_option_help(self, formatter):

  1069         if not self.option_list:

  1070             return ""

  1071         result = []

  1072         for option in self.option_list:

  1073             if not option.help is SUPPRESS_HELP:

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

  1075         return "".join(result)

  1076 

  1077     def format_description(self, formatter):

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

  1079 

  1080     def format_help(self, formatter):

  1081         result = []

  1082         if self.description:

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

  1084         if self.option_list:

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

  1086         return "\n".join(result)

  1087 

  1088 

  1089 class OptionGroup (OptionContainer):

  1090 

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

  1092         self.parser = parser

  1093         OptionContainer.__init__(

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

  1095         self.title = title

  1096 

  1097     def _create_option_list(self):

  1098         self.option_list = []

  1099         self._share_option_mappings(self.parser)

  1100 

  1101     def set_title(self, title):

  1102         self.title = title

  1103 

  1104     def destroy(self):

  1105         """see OptionParser.destroy()."""

  1106         OptionContainer.destroy(self)

  1107         del self.option_list

  1108 

  1109     # -- Help-formatting methods ---------------------------------------

  1110 

  1111     def format_help(self, formatter):

  1112         result = formatter.format_heading(self.title)

  1113         formatter.indent()

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

  1115         formatter.dedent()

  1116         return result

  1117 

  1118 

  1119 class OptionParser (OptionContainer):

  1120 

  1121     """

  1122     Class attributes:

  1123       standard_option_list : [Option]

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

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

  1126 

  1127     Instance attributes:

  1128       usage : string

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

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

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

  1132       prog : string

  1133         the name of the current program (to override

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

  1135       epilog : string