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