Package logilab :: Package common :: Module optik_ext

[frames] | no frames]

# Source Code for Module logilab.common.optik_ext

      1  # copyright 2003-2011 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
      2  # contact http://www.logilab.fr/ -- mailto:contact@logilab.fr
      3  #
      4  # This file is part of logilab-common.
      5  #
      6  # logilab-common is free software: you can redistribute it and/or modify it under
      7  # the terms of the GNU Lesser General Public License as published by the Free
      8  # Software Foundation, either version 2.1 of the License, or (at your option) any
      9  # later version.
     10  #
     11  # logilab-common is distributed in the hope that it will be useful, but WITHOUT
     12  # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
     13  # FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
     14  # details.
     15  #
     16  # You should have received a copy of the GNU Lesser General Public License along
     17  # with logilab-common.  If not, see <http://www.gnu.org/licenses/>.
     18  """Add an abstraction level to transparently import optik classes from optparse
     19  (python >= 2.3) or the optik package.
     20
     21  It also defines three new types for optik/optparse command line parser :
     22
     23    * regexp
     24      argument of this type will be converted using re.compile
     25    * csv
     26      argument of this type will be converted using split(',')
     27    * yn
     28      argument of this type will be true if 'y' or 'yes', false if 'n' or 'no'
     29    * named
     30      argument of this type are in the form <NAME>=<VALUE> or <NAME>:<VALUE>
     31    * password
     32      argument of this type wont be converted but this is used by other tools
     33      such as interactive prompt for configuration to double check value and
     34      use an invisible field
     35    * multiple_choice
     36      same as default "choice" type but multiple choices allowed
     37    * file
     38      argument of this type wont be converted but checked that the given file exists
     39    * color
     40      argument of this type wont be converted but checked its either a
     41      named color or a color specified using hexadecimal notation (preceded by a #)
     42    * time
     43      argument of this type will be converted to a float value in seconds
     44      according to time units (ms, s, min, h, d)
     45    * bytes
     46      argument of this type will be converted to a float value in bytes
     47      according to byte units (b, kb, mb, gb, tb)
     48  """
     49  from __future__ import print_function
     50
     51  __docformat__ = "restructuredtext en"
     52
     53  import re
     54  import sys
     55  import time
     56  from copy import copy
     57  from os.path import exists
     58
     59  from six import integer_types
     60
     61  # python >= 2.3
     62  from optparse import OptionParser as BaseParser, Option as BaseOption, \
     63       OptionGroup, OptionContainer, OptionValueError, OptionError, \
     64       Values, HelpFormatter, NO_DEFAULT, SUPPRESS_HELP
     65
     66  try:
     67      from mx import DateTime
     68      HAS_MX_DATETIME = True
     69  except ImportError:
     70      HAS_MX_DATETIME = False
     71
     72  from logilab.common.textutils import splitstrip, TIME_UNITS, BYTE_UNITS, \
     73      apply_units
     74
     75
     76 -def check_regexp(option, opt, value):
     77      """check a regexp value by trying to compile it
     78      return the compiled regexp
     79      """
     80      if hasattr(value, 'pattern'):
     81          return value
     82      try:
     83          return re.compile(value)
     84      except ValueError:
     85          raise OptionValueError(
     86              "option %s: invalid regexp value: %r" % (opt, value))
     87
     88 -def check_csv(option, opt, value):
     89      """check a csv value by trying to split it
     90      return the list of separated values
     91      """
     92      if isinstance(value, (list, tuple)):
     93          return value
     94      try:
     95          return splitstrip(value)
     96      except ValueError:
     97          raise OptionValueError(
     98              "option %s: invalid csv value: %r" % (opt, value))
     99
    100 -def check_yn(option, opt, value):
    101      """check a yn value
    102      return true for yes and false for no
    103      """
    104      if isinstance(value, int):
    105          return bool(value)
    106      if value in ('y', 'yes'):
    107          return True
    108      if value in ('n', 'no'):
    109          return False
    110      msg = "option %s: invalid yn value %r, should be in (y, yes, n, no)"
    111      raise OptionValueError(msg % (opt, value))
    112
    113 -def check_named(option, opt, value):
    114      """check a named value
    115      return a dictionary containing (name, value) associations
    116      """
    117      if isinstance(value, dict):
    118          return value
    119      values = []
    120      for value in check_csv(option, opt, value):
    121          if value.find('=') != -1:
    122              values.append(value.split('=', 1))
    123          elif value.find(':') != -1:
    124              values.append(value.split(':', 1))
    125      if values:
    126          return dict(values)
    127      msg = "option %s: invalid named value %r, should be <NAME>=<VALUE> or \
    128  <NAME>:<VALUE>"
    129      raise OptionValueError(msg % (opt, value))
    130
    131 -def check_password(option, opt, value):
    132      """check a password value (can't be empty)
    133      """
    134      # no actual checking, monkey patch if you want more
    135      return value
    136
    137 -def check_file(option, opt, value):
    138      """check a file value
    139      return the filepath
    140      """
    141      if exists(value):
    142          return value
    143      msg = "option %s: file %r does not exist"
    144      raise OptionValueError(msg % (opt, value))
    145
    146  # XXX use python datetime
    147 -def check_date(option, opt, value):
    148      """check a file value
    149      return the filepath
    150      """
    151      try:
    152          return DateTime.strptime(value, "%Y/%m/%d")
    153      except DateTime.Error :
    154          raise OptionValueError(
    155              "expected format of %s is yyyy/mm/dd" % opt)
    156
    157 -def check_color(option, opt, value):
    158      """check a color value and returns it
    159      /!\ does *not* check color labels (like 'red', 'green'), only
    160      checks hexadecimal forms
    161      """
    162      # Case (1) : color label, we trust the end-user
    163      if re.match('[a-z0-9 ]+$', value, re.I):
    164          return value
    165      # Case (2) : only accepts hexadecimal forms
    166      if re.match('#[a-f0-9]{6}', value, re.I):
    167          return value
    168      # Else : not a color label neither a valid hexadecimal form => error
    169      msg = "option %s: invalid color : %r, should be either hexadecimal \
    170      value or predefined color"
    171      raise OptionValueError(msg % (opt, value))
    172
    173 -def check_time(option, opt, value):
    174      if isinstance(value, integer_types + (float,)):
    175          return value
    176      return apply_units(value, TIME_UNITS)
    177
    178 -def check_bytes(option, opt, value):
    179      if hasattr(value, '__int__'):
    180          return value
    181      return apply_units(value, BYTE_UNITS, final=int)
    182
    183
    184 -class Option(BaseOption):
    185      """override optik.Option to add some new option types
    186      """
    187      TYPES = BaseOption.TYPES + ('regexp', 'csv', 'yn', 'named', 'password',
    188                                  'multiple_choice', 'file', 'color',
    189                                  'time', 'bytes')
    190      ATTRS = BaseOption.ATTRS + ['hide', 'level']
    191      TYPE_CHECKER = copy(BaseOption.TYPE_CHECKER)
    192      TYPE_CHECKER['regexp'] = check_regexp
    193      TYPE_CHECKER['csv'] = check_csv
    194      TYPE_CHECKER['yn'] = check_yn
    195      TYPE_CHECKER['named'] = check_named
    196      TYPE_CHECKER['multiple_choice'] = check_csv
    197      TYPE_CHECKER['file'] = check_file
    198      TYPE_CHECKER['color'] = check_color
    199      TYPE_CHECKER['password'] = check_password
    200      TYPE_CHECKER['time'] = check_time
    201      TYPE_CHECKER['bytes'] = check_bytes
    202      if HAS_MX_DATETIME:
    203          TYPES += ('date',)
    204          TYPE_CHECKER['date'] = check_date
    205
    206 -    def __init__(self, *opts, **attrs):
    207          BaseOption.__init__(self, *opts, **attrs)
    208          if hasattr(self, "hide") and self.hide:
    209              self.help = SUPPRESS_HELP
    210
    211 -    def _check_choice(self):
    212          """FIXME: need to override this due to optik misdesign"""
    213          if self.type in ("choice", "multiple_choice"):
    214              if self.choices is None:
    215                  raise OptionError(
    216                      "must supply a list of choices for type 'choice'", self)
    217              elif not isinstance(self.choices, (tuple, list)):
    218                  raise OptionError(
    219                      "choices must be a list of strings ('%s' supplied)"
    220                      % str(type(self.choices)).split("'")[1], self)
    221          elif self.choices is not None:
    222              raise OptionError(
    223                  "must not supply choices for type %r" % self.type, self)
    224      BaseOption.CHECK_METHODS[2] = _check_choice
    225
    226
    227 -    def process(self, opt, value, values, parser):
    228          # First, convert the value(s) to the right type.  Howl if any
    229          # value(s) are bogus.
    230          value = self.convert_value(opt, value)
    231          if self.type == 'named':
    232              existant = getattr(values, self.dest)
    233              if existant:
    234                  existant.update(value)
    235                  value = existant
    236         # And then take whatever action is expected of us.
    237          # This is a separate method to make life easier for
    238          # subclasses to add new actions.
    239          return self.take_action(
    240              self.action, self.dest, opt, value, values, parser)
    241
    242
    243 -class OptionParser(BaseParser):
    244      """override optik.OptionParser to use our Option class
    245      """
    246 -    def __init__(self, option_class=Option, *args, **kwargs):
    247          BaseParser.__init__(self, option_class=Option, *args, **kwargs)
    248
    249 -    def format_option_help(self, formatter=None):
    250          if formatter is None:
    251              formatter = self.formatter
    252          outputlevel = getattr(formatter, 'output_level', 0)
    253          formatter.store_option_strings(self)
    254          result = []
    255          result.append(formatter.format_heading("Options"))
    256          formatter.indent()
    257          if self.option_list:
    258              result.append(OptionContainer.format_option_help(self, formatter))
    259              result.append("\n")
    260          for group in self.option_groups:
    261              if group.level <= outputlevel and (
    262                  group.description or level_options(group, outputlevel)):
    263                  result.append(group.format_help(formatter))
    264                  result.append("\n")
    265          formatter.dedent()
    266          # Drop the last "\n", or the header if no options or option groups:
    267          return "".join(result[:-1])
    268
    269
    270  OptionGroup.level = 0
    271
    272 -def level_options(group, outputlevel):
    273      return [option for option in group.option_list
    274              if (getattr(option, 'level', 0) or 0) <= outputlevel
    275              and not option.help is SUPPRESS_HELP]
    276
    277 -def format_option_help(self, formatter):
    278      result = []
    279      outputlevel = getattr(formatter, 'output_level', 0) or 0
    280      for option in level_options(self, outputlevel):
    281          result.append(formatter.format_option(option))
    282      return "".join(result)
    283  OptionContainer.format_option_help = format_option_help
    284
    285
    286 -class ManHelpFormatter(HelpFormatter):
    287      """Format help using man pages ROFF format"""
    288
    289 -    def __init__ (self,
    290                    indent_increment=0,
    291                    max_help_position=24,
    292                    width=79,
    293                    short_first=0):
    294          HelpFormatter.__init__ (
    295              self, indent_increment, max_help_position, width, short_first)
    296
    297 -    def format_heading(self, heading):
    298          return '.SH %s\n' % heading.upper()
    299
    300 -    def format_description(self, description):
    301          return description
    302
    303 -    def format_option(self, option):
    304          try:
    305              optstring = option.option_strings
    306          except AttributeError:
    307              optstring = self.format_option_strings(option)
    308          if option.help:
    309              help_text = self.expand_default(option)
    310              help = ' '.join([l.strip() for l in help_text.splitlines()])
    311          else:
    312              help = ''
    313          return '''.IP "%s"
    314  %s
    315  ''' % (optstring, help)
    316
    317 -    def format_head(self, optparser, pkginfo, section=1):
    318          long_desc = ""
    319          try:
    320              pgm = optparser._get_prog_name()
    321          except AttributeError:
    322              # py >= 2.4.X (dunno which X exactly, at least 2)
    323              pgm = optparser.get_prog_name()
    324          short_desc = self.format_short_description(pgm, pkginfo.description)
    325          if hasattr(pkginfo, "long_desc"):
    326              long_desc = self.format_long_description(pgm, pkginfo.long_desc)
    327          return '%s\n%s\n%s\n%s' % (self.format_title(pgm, section),
    328                                     short_desc, self.format_synopsis(pgm),
    329                                     long_desc)
    330
    331 -    def format_title(self, pgm, section):
    332          date = '-'.join([str(num) for num in time.localtime()[:3]])
    333          return '.TH %s %s "%s" %s' % (pgm, section, date, pgm)
    334
    335 -    def format_short_description(self, pgm, short_desc):
    336          return '''.SH NAME
    337  .B %s
    338  \- %s
    339  ''' % (pgm, short_desc.strip())
    340
    341 -    def format_synopsis(self, pgm):
    342          return '''.SH SYNOPSIS
    343  .B  %s
    344  [
    345  .I OPTIONS
    346  ] [
    347  .I <arguments>
    348  ]
    349  ''' % pgm
    350
    351 -    def format_long_description(self, pgm, long_desc):
    352          long_desc = '\n'.join([line.lstrip()
    353                                 for line in long_desc.splitlines()])
    354          long_desc = long_desc.replace('\n.\n', '\n\n')
    355          if long_desc.lower().startswith(pgm):
    356              long_desc = long_desc[len(pgm):]
    357          return '''.SH DESCRIPTION
    358  .B %s
    359  %s
    360  ''' % (pgm, long_desc.strip())
    361
    362 -    def format_tail(self, pkginfo):
    363          tail = '''.SH SEE ALSO
    364  /usr/share/doc/pythonX.Y-%s/
    365
    366  .SH BUGS
    367  Please report bugs on the project\'s mailing list:
    368  %s
    369
    370  .SH AUTHOR
    371  %s <%s>
    372  ''' % (getattr(pkginfo, 'debian_name', pkginfo.modname),
    373         pkginfo.mailinglist, pkginfo.author, pkginfo.author_email)
    374
    375          if hasattr(pkginfo, "copyright"):
    376              tail += '''
    377  .SH COPYRIGHT
    378  %s
    379  ''' % pkginfo.copyright
    380
    381          return tail
    382
    383 -def generate_manpage(optparser, pkginfo, section=1, stream=sys.stdout, level=0):
    384      """generate a man page from an optik parser"""
    385      formatter = ManHelpFormatter()
    386      formatter.output_level = level
    387      formatter.parser = optparser
    388      print(formatter.format_head(optparser, pkginfo, section), file=stream)
    389      print(optparser.format_option_help(formatter), file=stream)
    390      print(formatter.format_tail(pkginfo), file=stream)
    391
    392
    393  __all__ = ('OptionParser', 'Option', 'OptionGroup', 'OptionValueError',
    394             'Values')
    395