You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
393 lines
13 KiB
Python
393 lines
13 KiB
Python
# copyright 2003-2011 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
|
|
# contact http://www.logilab.fr/ -- mailto:contact@logilab.fr
|
|
#
|
|
# This file is part of logilab-common.
|
|
#
|
|
# logilab-common is free software: you can redistribute it and/or modify it under
|
|
# the terms of the GNU Lesser General Public License as published by the Free
|
|
# Software Foundation, either version 2.1 of the License, or (at your option) any
|
|
# later version.
|
|
#
|
|
# logilab-common is distributed in the hope that it will be useful, but WITHOUT
|
|
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
|
|
# details.
|
|
#
|
|
# You should have received a copy of the GNU Lesser General Public License along
|
|
# with logilab-common. If not, see <http://www.gnu.org/licenses/>.
|
|
"""Add an abstraction level to transparently import optik classes from optparse
|
|
(python >= 2.3) or the optik package.
|
|
|
|
It also defines three new types for optik/optparse command line parser :
|
|
|
|
* regexp
|
|
argument of this type will be converted using re.compile
|
|
* csv
|
|
argument of this type will be converted using split(',')
|
|
* yn
|
|
argument of this type will be true if 'y' or 'yes', false if 'n' or 'no'
|
|
* named
|
|
argument of this type are in the form <NAME>=<VALUE> or <NAME>:<VALUE>
|
|
* password
|
|
argument of this type wont be converted but this is used by other tools
|
|
such as interactive prompt for configuration to double check value and
|
|
use an invisible field
|
|
* multiple_choice
|
|
same as default "choice" type but multiple choices allowed
|
|
* file
|
|
argument of this type wont be converted but checked that the given file exists
|
|
* color
|
|
argument of this type wont be converted but checked its either a
|
|
named color or a color specified using hexadecimal notation (preceded by a #)
|
|
* time
|
|
argument of this type will be converted to a float value in seconds
|
|
according to time units (ms, s, min, h, d)
|
|
* bytes
|
|
argument of this type will be converted to a float value in bytes
|
|
according to byte units (b, kb, mb, gb, tb)
|
|
"""
|
|
from __future__ import print_function
|
|
|
|
__docformat__ = "restructuredtext en"
|
|
|
|
import re
|
|
import sys
|
|
import time
|
|
from copy import copy
|
|
from os.path import exists
|
|
|
|
# python >= 2.3
|
|
from optparse import OptionParser as BaseParser, Option as BaseOption, \
|
|
OptionGroup, OptionContainer, OptionValueError, OptionError, \
|
|
Values, HelpFormatter, NO_DEFAULT, SUPPRESS_HELP
|
|
|
|
try:
|
|
from mx import DateTime
|
|
HAS_MX_DATETIME = True
|
|
except ImportError:
|
|
HAS_MX_DATETIME = False
|
|
|
|
from logilab.common.textutils import splitstrip, TIME_UNITS, BYTE_UNITS, \
|
|
apply_units
|
|
|
|
|
|
def check_regexp(option, opt, value):
|
|
"""check a regexp value by trying to compile it
|
|
return the compiled regexp
|
|
"""
|
|
if hasattr(value, 'pattern'):
|
|
return value
|
|
try:
|
|
return re.compile(value)
|
|
except ValueError:
|
|
raise OptionValueError(
|
|
"option %s: invalid regexp value: %r" % (opt, value))
|
|
|
|
def check_csv(option, opt, value):
|
|
"""check a csv value by trying to split it
|
|
return the list of separated values
|
|
"""
|
|
if isinstance(value, (list, tuple)):
|
|
return value
|
|
try:
|
|
return splitstrip(value)
|
|
except ValueError:
|
|
raise OptionValueError(
|
|
"option %s: invalid csv value: %r" % (opt, value))
|
|
|
|
def check_yn(option, opt, value):
|
|
"""check a yn value
|
|
return true for yes and false for no
|
|
"""
|
|
if isinstance(value, int):
|
|
return bool(value)
|
|
if value in ('y', 'yes'):
|
|
return True
|
|
if value in ('n', 'no'):
|
|
return False
|
|
msg = "option %s: invalid yn value %r, should be in (y, yes, n, no)"
|
|
raise OptionValueError(msg % (opt, value))
|
|
|
|
def check_named(option, opt, value):
|
|
"""check a named value
|
|
return a dictionary containing (name, value) associations
|
|
"""
|
|
if isinstance(value, dict):
|
|
return value
|
|
values = []
|
|
for value in check_csv(option, opt, value):
|
|
if value.find('=') != -1:
|
|
values.append(value.split('=', 1))
|
|
elif value.find(':') != -1:
|
|
values.append(value.split(':', 1))
|
|
if values:
|
|
return dict(values)
|
|
msg = "option %s: invalid named value %r, should be <NAME>=<VALUE> or \
|
|
<NAME>:<VALUE>"
|
|
raise OptionValueError(msg % (opt, value))
|
|
|
|
def check_password(option, opt, value):
|
|
"""check a password value (can't be empty)
|
|
"""
|
|
# no actual checking, monkey patch if you want more
|
|
return value
|
|
|
|
def check_file(option, opt, value):
|
|
"""check a file value
|
|
return the filepath
|
|
"""
|
|
if exists(value):
|
|
return value
|
|
msg = "option %s: file %r does not exist"
|
|
raise OptionValueError(msg % (opt, value))
|
|
|
|
# XXX use python datetime
|
|
def check_date(option, opt, value):
|
|
"""check a file value
|
|
return the filepath
|
|
"""
|
|
try:
|
|
return DateTime.strptime(value, "%Y/%m/%d")
|
|
except DateTime.Error :
|
|
raise OptionValueError(
|
|
"expected format of %s is yyyy/mm/dd" % opt)
|
|
|
|
def check_color(option, opt, value):
|
|
"""check a color value and returns it
|
|
/!\ does *not* check color labels (like 'red', 'green'), only
|
|
checks hexadecimal forms
|
|
"""
|
|
# Case (1) : color label, we trust the end-user
|
|
if re.match('[a-z0-9 ]+$', value, re.I):
|
|
return value
|
|
# Case (2) : only accepts hexadecimal forms
|
|
if re.match('#[a-f0-9]{6}', value, re.I):
|
|
return value
|
|
# Else : not a color label neither a valid hexadecimal form => error
|
|
msg = "option %s: invalid color : %r, should be either hexadecimal \
|
|
value or predefined color"
|
|
raise OptionValueError(msg % (opt, value))
|
|
|
|
def check_time(option, opt, value):
|
|
if isinstance(value, (int, long, float)):
|
|
return value
|
|
return apply_units(value, TIME_UNITS)
|
|
|
|
def check_bytes(option, opt, value):
|
|
if hasattr(value, '__int__'):
|
|
return value
|
|
return apply_units(value, BYTE_UNITS)
|
|
|
|
|
|
class Option(BaseOption):
|
|
"""override optik.Option to add some new option types
|
|
"""
|
|
TYPES = BaseOption.TYPES + ('regexp', 'csv', 'yn', 'named', 'password',
|
|
'multiple_choice', 'file', 'color',
|
|
'time', 'bytes')
|
|
ATTRS = BaseOption.ATTRS + ['hide', 'level']
|
|
TYPE_CHECKER = copy(BaseOption.TYPE_CHECKER)
|
|
TYPE_CHECKER['regexp'] = check_regexp
|
|
TYPE_CHECKER['csv'] = check_csv
|
|
TYPE_CHECKER['yn'] = check_yn
|
|
TYPE_CHECKER['named'] = check_named
|
|
TYPE_CHECKER['multiple_choice'] = check_csv
|
|
TYPE_CHECKER['file'] = check_file
|
|
TYPE_CHECKER['color'] = check_color
|
|
TYPE_CHECKER['password'] = check_password
|
|
TYPE_CHECKER['time'] = check_time
|
|
TYPE_CHECKER['bytes'] = check_bytes
|
|
if HAS_MX_DATETIME:
|
|
TYPES += ('date',)
|
|
TYPE_CHECKER['date'] = check_date
|
|
|
|
def __init__(self, *opts, **attrs):
|
|
BaseOption.__init__(self, *opts, **attrs)
|
|
if hasattr(self, "hide") and self.hide:
|
|
self.help = SUPPRESS_HELP
|
|
|
|
def _check_choice(self):
|
|
"""FIXME: need to override this due to optik misdesign"""
|
|
if self.type in ("choice", "multiple_choice"):
|
|
if self.choices is None:
|
|
raise OptionError(
|
|
"must supply a list of choices for type 'choice'", self)
|
|
elif not isinstance(self.choices, (tuple, list)):
|
|
raise OptionError(
|
|
"choices must be a list of strings ('%s' supplied)"
|
|
% str(type(self.choices)).split("'")[1], self)
|
|
elif self.choices is not None:
|
|
raise OptionError(
|
|
"must not supply choices for type %r" % self.type, self)
|
|
BaseOption.CHECK_METHODS[2] = _check_choice
|
|
|
|
|
|
def process(self, opt, value, values, parser):
|
|
# First, convert the value(s) to the right type. Howl if any
|
|
# value(s) are bogus.
|
|
value = self.convert_value(opt, value)
|
|
if self.type == 'named':
|
|
existant = getattr(values, self.dest)
|
|
if existant:
|
|
existant.update(value)
|
|
value = existant
|
|
# And then take whatever action is expected of us.
|
|
# This is a separate method to make life easier for
|
|
# subclasses to add new actions.
|
|
return self.take_action(
|
|
self.action, self.dest, opt, value, values, parser)
|
|
|
|
|
|
class OptionParser(BaseParser):
|
|
"""override optik.OptionParser to use our Option class
|
|
"""
|
|
def __init__(self, option_class=Option, *args, **kwargs):
|
|
BaseParser.__init__(self, option_class=Option, *args, **kwargs)
|
|
|
|
def format_option_help(self, formatter=None):
|
|
if formatter is None:
|
|
formatter = self.formatter
|
|
outputlevel = getattr(formatter, 'output_level', 0)
|
|
formatter.store_option_strings(self)
|
|
result = []
|
|
result.append(formatter.format_heading("Options"))
|
|
formatter.indent()
|
|
if self.option_list:
|
|
result.append(OptionContainer.format_option_help(self, formatter))
|
|
result.append("\n")
|
|
for group in self.option_groups:
|
|
if group.level <= outputlevel and (
|
|
group.description or level_options(group, outputlevel)):
|
|
result.append(group.format_help(formatter))
|
|
result.append("\n")
|
|
formatter.dedent()
|
|
# Drop the last "\n", or the header if no options or option groups:
|
|
return "".join(result[:-1])
|
|
|
|
|
|
OptionGroup.level = 0
|
|
|
|
def level_options(group, outputlevel):
|
|
return [option for option in group.option_list
|
|
if (getattr(option, 'level', 0) or 0) <= outputlevel
|
|
and not option.help is SUPPRESS_HELP]
|
|
|
|
def format_option_help(self, formatter):
|
|
result = []
|
|
outputlevel = getattr(formatter, 'output_level', 0) or 0
|
|
for option in level_options(self, outputlevel):
|
|
result.append(formatter.format_option(option))
|
|
return "".join(result)
|
|
OptionContainer.format_option_help = format_option_help
|
|
|
|
|
|
class ManHelpFormatter(HelpFormatter):
|
|
"""Format help using man pages ROFF format"""
|
|
|
|
def __init__ (self,
|
|
indent_increment=0,
|
|
max_help_position=24,
|
|
width=79,
|
|
short_first=0):
|
|
HelpFormatter.__init__ (
|
|
self, indent_increment, max_help_position, width, short_first)
|
|
|
|
def format_heading(self, heading):
|
|
return '.SH %s\n' % heading.upper()
|
|
|
|
def format_description(self, description):
|
|
return description
|
|
|
|
def format_option(self, option):
|
|
try:
|
|
optstring = option.option_strings
|
|
except AttributeError:
|
|
optstring = self.format_option_strings(option)
|
|
if option.help:
|
|
help_text = self.expand_default(option)
|
|
help = ' '.join([l.strip() for l in help_text.splitlines()])
|
|
else:
|
|
help = ''
|
|
return '''.IP "%s"
|
|
%s
|
|
''' % (optstring, help)
|
|
|
|
def format_head(self, optparser, pkginfo, section=1):
|
|
long_desc = ""
|
|
try:
|
|
pgm = optparser._get_prog_name()
|
|
except AttributeError:
|
|
# py >= 2.4.X (dunno which X exactly, at least 2)
|
|
pgm = optparser.get_prog_name()
|
|
short_desc = self.format_short_description(pgm, pkginfo.description)
|
|
if hasattr(pkginfo, "long_desc"):
|
|
long_desc = self.format_long_description(pgm, pkginfo.long_desc)
|
|
return '%s\n%s\n%s\n%s' % (self.format_title(pgm, section),
|
|
short_desc, self.format_synopsis(pgm),
|
|
long_desc)
|
|
|
|
def format_title(self, pgm, section):
|
|
date = '-'.join([str(num) for num in time.localtime()[:3]])
|
|
return '.TH %s %s "%s" %s' % (pgm, section, date, pgm)
|
|
|
|
def format_short_description(self, pgm, short_desc):
|
|
return '''.SH NAME
|
|
.B %s
|
|
\- %s
|
|
''' % (pgm, short_desc.strip())
|
|
|
|
def format_synopsis(self, pgm):
|
|
return '''.SH SYNOPSIS
|
|
.B %s
|
|
[
|
|
.I OPTIONS
|
|
] [
|
|
.I <arguments>
|
|
]
|
|
''' % pgm
|
|
|
|
def format_long_description(self, pgm, long_desc):
|
|
long_desc = '\n'.join([line.lstrip()
|
|
for line in long_desc.splitlines()])
|
|
long_desc = long_desc.replace('\n.\n', '\n\n')
|
|
if long_desc.lower().startswith(pgm):
|
|
long_desc = long_desc[len(pgm):]
|
|
return '''.SH DESCRIPTION
|
|
.B %s
|
|
%s
|
|
''' % (pgm, long_desc.strip())
|
|
|
|
def format_tail(self, pkginfo):
|
|
tail = '''.SH SEE ALSO
|
|
/usr/share/doc/pythonX.Y-%s/
|
|
|
|
.SH BUGS
|
|
Please report bugs on the project\'s mailing list:
|
|
%s
|
|
|
|
.SH AUTHOR
|
|
%s <%s>
|
|
''' % (getattr(pkginfo, 'debian_name', pkginfo.modname),
|
|
pkginfo.mailinglist, pkginfo.author, pkginfo.author_email)
|
|
|
|
if hasattr(pkginfo, "copyright"):
|
|
tail += '''
|
|
.SH COPYRIGHT
|
|
%s
|
|
''' % pkginfo.copyright
|
|
|
|
return tail
|
|
|
|
def generate_manpage(optparser, pkginfo, section=1, stream=sys.stdout, level=0):
|
|
"""generate a man page from an optik parser"""
|
|
formatter = ManHelpFormatter()
|
|
formatter.output_level = level
|
|
formatter.parser = optparser
|
|
print(formatter.format_head(optparser, pkginfo, section), file=stream)
|
|
print(optparser.format_option_help(formatter), file=stream)
|
|
print(formatter.format_tail(pkginfo), file=stream)
|
|
|
|
|
|
__all__ = ('OptionParser', 'Option', 'OptionGroup', 'OptionValueError',
|
|
'Values')
|