logilab/common

view optik_ext.py @ 1130:d706bd7eabcf

find changesets by author, revision, files, or words in the commit message
fix help generation for normal optparse using script if optik_ext has been imported (#24450)
author Alexandre Fayolle <alexandre.fayolle@logilab.fr>
date Mon, 03 May 2010 12:12:09 +0200
parents c4e07aed9ae0
children a1a900f7c902
line source
1 # copyright 2003-2010 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 __docformat__ = "restructuredtext en"
50
51 import re
52 import sys
53 import time
54 from copy import copy
55 from os.path import exists
56
57 # python >= 2.3
58 from optparse import OptionParser as BaseParser, Option as BaseOption, \
59 OptionGroup, OptionContainer, OptionValueError, OptionError, \
60 Values, HelpFormatter, NO_DEFAULT, SUPPRESS_HELP
61
62 try:
63 from mx import DateTime
64 HAS_MX_DATETIME = True
65 except ImportError:
66 HAS_MX_DATETIME = False
67
68
69 OPTPARSE_FORMAT_DEFAULT = sys.version_info >= (2, 4)
70
71 from logilab.common.textutils import splitstrip
72
73 def check_regexp(option, opt, value):
74 """check a regexp value by trying to compile it
75 return the compiled regexp
76 """
77 if hasattr(value, 'pattern'):
78 return value
79 try:
80 return re.compile(value)
81 except ValueError:
82 raise OptionValueError(
83 "option %s: invalid regexp value: %r" % (opt, value))
84
85 def check_csv(option, opt, value):
86 """check a csv value by trying to split it
87 return the list of separated values
88 """
89 if isinstance(value, (list, tuple)):
90 return value
91 try:
92 return splitstrip(value)
93 except ValueError:
94 raise OptionValueError(
95 "option %s: invalid csv value: %r" % (opt, value))
96
97 def check_yn(option, opt, value):
98 """check a yn value
99 return true for yes and false for no
100 """
101 if isinstance(value, int):
102 return bool(value)
103 if value in ('y', 'yes'):
104 return True
105 if value in ('n', 'no'):
106 return False
107 msg = "option %s: invalid yn value %r, should be in (y, yes, n, no)"
108 raise OptionValueError(msg % (opt, value))
109
110 def check_named(option, opt, value):
111 """check a named value
112 return a dictionary containing (name, value) associations
113 """
114 if isinstance(value, dict):
115 return value
116 values = []
117 for value in check_csv(option, opt, value):
118 if value.find('=') != -1:
119 values.append(value.split('=', 1))
120 elif value.find(':') != -1:
121 values.append(value.split(':', 1))
122 if values:
123 return dict(values)
124 msg = "option %s: invalid named value %r, should be <NAME>=<VALUE> or \
125 <NAME>:<VALUE>"
126 raise OptionValueError(msg % (opt, value))
127
128 def check_password(option, opt, value):
129 """check a password value (can't be empty)
130 """
131 # no actual checking, monkey patch if you want more
132 return value
133
134 def check_file(option, opt, value):
135 """check a file value
136 return the filepath
137 """
138 if exists(value):
139 return value
140 msg = "option %s: file %r does not exist"
141 raise OptionValueError(msg % (opt, value))
142
143 # XXX use python datetime
144 def check_date(option, opt, value):
145 """check a file value
146 return the filepath
147 """
148 try:
149 return DateTime.strptime(value, "%Y/%m/%d")
150 except DateTime.Error :
151 raise OptionValueError(
152 "expected format of %s is yyyy/mm/dd" % opt)
153
154 def check_color(option, opt, value):
155 """check a color value and returns it
156 /!\ does *not* check color labels (like 'red', 'green'), only
157 checks hexadecimal forms
158 """
159 # Case (1) : color label, we trust the end-user
160 if re.match('[a-z0-9 ]+$', value, re.I):
161 return value
162 # Case (2) : only accepts hexadecimal forms
163 if re.match('#[a-f0-9]{6}', value, re.I):
164 return value
165 # Else : not a color label neither a valid hexadecimal form => error
166 msg = "option %s: invalid color : %r, should be either hexadecimal \
167 value or predefined color"
168 raise OptionValueError(msg % (opt, value))
169
170 def check_time(option, opt, value):
171 from logilab.common.textutils import TIME_UNITS, apply_units
172 if isinstance(value, (int, long, float)):
173 return value
174 return apply_units(value, TIME_UNITS)
175
176 def check_bytes(option, opt, value):
177 from logilab.common.textutils import BYTE_UNITS, apply_units
178 if hasattr(value, '__int__'):
179 return value
180 return apply_units(value, BYTE_UNITS)
181
182 import types
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 type(self.choices) not in (types.TupleType, types.ListType):
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 try:
231 value = self.convert_value(opt, value)
232 except AttributeError: # py < 2.4
233 value = self.check_value(opt, value)
234 if self.type == 'named':
235 existant = getattr(values, self.dest)
236 if existant:
237 existant.update(value)
238 value = existant
239 # And then take whatever action is expected of us.
240 # This is a separate method to make life easier for
241 # subclasses to add new actions.
242 return self.take_action(
243 self.action, self.dest, opt, value, values, parser)
244
245 class OptionParser(BaseParser):
246 """override optik.OptionParser to use our Option class
247 """
248 def __init__(self, option_class=Option, *args, **kwargs):
249 BaseParser.__init__(self, option_class=Option, *args, **kwargs)
250
251 def format_option_help(self, formatter=None):
252 if formatter is None:
253 formatter = self.formatter
254 outputlevel = getattr(formatter, 'output_level', 0)
255 formatter.store_option_strings(self)
256 result = []
257 result.append(formatter.format_heading("Options"))
258 formatter.indent()
259 if self.option_list:
260 result.append(OptionContainer.format_option_help(self, formatter))
261 result.append("\n")
262 for group in self.option_groups:
263 if group.level <= outputlevel:
264 result.append(group.format_help(formatter))
265 result.append("\n")
266 formatter.dedent()
267 # Drop the last "\n", or the header if no options or option groups:
268 return "".join(result[:-1])
269
270
271 OptionGroup.level = 0
272
273 def format_option_help(self, formatter):
274 result = []
275 outputlevel = getattr(formatter, 'output_level', 0)
276 for option in self.option_list:
277 if getattr(option, 'level', 0) <= outputlevel and not option.help is SUPPRESS_HELP:
278 result.append(formatter.format_option(option))
279 return "".join(result)
280 OptionContainer.format_option_help = format_option_help
281 OptionContainer.format_option_help = format_option_help
282
283 class ManHelpFormatter(HelpFormatter):
284 """Format help using man pages ROFF format"""
285
286 def __init__ (self,
287 indent_increment=0,
288 max_help_position=24,
289 width=79,
290 short_first=0):
291 HelpFormatter.__init__ (
292 self, indent_increment, max_help_position, width, short_first)
293
294 def format_heading(self, heading):
295 return '.SH %s\n' % heading.upper()
296
297 def format_description(self, description):
298 return description
299
300 def format_option(self, option):
301 try:
302 optstring = option.option_strings
303 except AttributeError:
304 optstring = self.format_option_strings(option)
305 if option.help:
306 help_text = self.expand_default(option)
307 help = ' '.join([l.strip() for l in help_text.splitlines()])
308 else:
309 help = ''
310 return '''.IP "%s"
311 %s
312 ''' % (optstring, help)
313
314 def format_head(self, optparser, pkginfo, section=1):
315 try:
316 pgm = optparser._get_prog_name()
317 except AttributeError:
318 # py >= 2.4.X (dunno which X exactly, at least 2)
319 pgm = optparser.get_prog_name()
320 short_desc = self.format_short_description(pgm, pkginfo.short_desc)
321 long_desc = self.format_long_description(pgm, pkginfo.long_desc)
322 return '%s\n%s\n%s\n%s' % (self.format_title(pgm, section), short_desc,
323 self.format_synopsis(pgm), long_desc)
324
325 def format_title(self, pgm, section):
326 date = '-'.join([str(num) for num in time.localtime()[:3]])
327 return '.TH %s %s "%s" %s' % (pgm, section, date, pgm)
328
329 def format_short_description(self, pgm, short_desc):
330 return '''.SH NAME
331 .B %s
332 \- %s
333 ''' % (pgm, short_desc.strip())
334
335 def format_synopsis(self, pgm):
336 return '''.SH SYNOPSIS
337 .B %s
338 [
339 .I OPTIONS
340 ] [
341 .I <arguments>
342 ]
343 ''' % pgm
344
345 def format_long_description(self, pgm, long_desc):
346 long_desc = '\n'.join([line.lstrip()
347 for line in long_desc.splitlines()])
348 long_desc = long_desc.replace('\n.\n', '\n\n')
349 if long_desc.lower().startswith(pgm):
350 long_desc = long_desc[len(pgm):]
351 return '''.SH DESCRIPTION
352 .B %s
353 %s
354 ''' % (pgm, long_desc.strip())
355
356 def format_tail(self, pkginfo):
357 return '''.SH SEE ALSO
358 /usr/share/doc/pythonX.Y-%s/
359
360 .SH COPYRIGHT
361 %s
362
363 .SH BUGS
364 Please report bugs on the project\'s mailing list:
365 %s
366
367 .SH AUTHOR
368 %s <%s>
369 ''' % (getattr(pkginfo, 'debian_name', pkginfo.modname), pkginfo.copyright,
370 pkginfo.mailinglist, pkginfo.author, pkginfo.author_email)
371
372
373 def generate_manpage(optparser, pkginfo, section=1, stream=sys.stdout):
374 """generate a man page from an optik parser"""
375 formatter = ManHelpFormatter()
376 formatter.parser = optparser
377 print >> stream, formatter.format_head(optparser, pkginfo, section)
378 print >> stream, optparser.format_option_help(formatter)
379 print >> stream, formatter.format_tail(pkginfo)
380
381
382 __all__ = ('OptionParser', 'Option', 'OptionGroup', 'OptionValueError',
383 'Values')