632 lines
20 KiB
Python
632 lines
20 KiB
Python
# -*- test-case-name: twisted.test.test_usage -*-
|
|
# Copyright (c) 2001-2007 Twisted Matrix Laboratories.
|
|
# See LICENSE for details.
|
|
|
|
|
|
"""
|
|
twisted.python.usage is a module for parsing/handling the
|
|
command line of your program.
|
|
|
|
For information on how to use it, see
|
|
U{http://twistedmatrix.com/projects/core/documentation/howto/options.html},
|
|
or doc/howto/options.html in your Twisted directory.
|
|
"""
|
|
|
|
# System Imports
|
|
import os
|
|
import sys
|
|
import getopt
|
|
from os import path
|
|
|
|
# Sibling Imports
|
|
from twisted.python import reflect, text, util
|
|
|
|
|
|
class UsageError(Exception):
|
|
pass
|
|
|
|
|
|
error = UsageError
|
|
|
|
|
|
class CoerceParameter(object):
|
|
"""
|
|
Utility class that can corce a parameter before storing it.
|
|
"""
|
|
def __init__(self, options, coerce):
|
|
"""
|
|
@param options: parent Options object
|
|
@param coerce: callable used to coerce the value.
|
|
"""
|
|
self.options = options
|
|
self.coerce = coerce
|
|
self.doc = getattr(self.coerce, 'coerceDoc', '')
|
|
|
|
def dispatch(self, parameterName, value):
|
|
"""
|
|
When called in dispatch, do the coerce for C{value} and save the
|
|
returned value.
|
|
"""
|
|
if value is None:
|
|
raise UsageError("Parameter '%s' requires an argument."
|
|
% (parameterName,))
|
|
try:
|
|
value = self.coerce(value)
|
|
except ValueError, e:
|
|
raise UsageError("Parameter type enforcement failed: %s" % (e,))
|
|
|
|
self.options.opts[parameterName] = value
|
|
|
|
|
|
class Options(dict):
|
|
"""
|
|
An option list parser class
|
|
|
|
C{optFlags} and C{optParameters} are lists of available parameters
|
|
which your program can handle. The difference between the two
|
|
is the 'flags' have an on(1) or off(0) state (off by default)
|
|
whereas 'parameters' have an assigned value, with an optional
|
|
default. (Compare '--verbose' and '--verbosity=2')
|
|
|
|
optFlags is assigned a list of lists. Each list represents
|
|
a flag parameter, as so::
|
|
|
|
| optFlags = [['verbose', 'v', 'Makes it tell you what it doing.'],
|
|
| ['quiet', 'q', 'Be vewy vewy quiet.']]
|
|
|
|
As you can see, the first item is the long option name
|
|
(prefixed with '--' on the command line), followed by the
|
|
short option name (prefixed with '-'), and the description.
|
|
The description is used for the built-in handling of the
|
|
--help switch, which prints a usage summary.
|
|
|
|
C{optParameters} is much the same, except the list also contains
|
|
a default value::
|
|
|
|
| optParameters = [['outfile', 'O', 'outfile.log', 'Description...']]
|
|
|
|
A coerce function can also be specified as the last element: it will be
|
|
called with the argument and should return the value that will be stored
|
|
for the option. This function can have a C{coerceDoc} attribute which
|
|
will be appended to the documentation of the option.
|
|
|
|
subCommands is a list of 4-tuples of (command name, command shortcut,
|
|
parser class, documentation). If the first non-option argument found is
|
|
one of the given command names, an instance of the given parser class is
|
|
instantiated and given the remainder of the arguments to parse and
|
|
self.opts[command] is set to the command name. For example::
|
|
|
|
| subCommands = [
|
|
| ['inquisition', 'inquest', InquisitionOptions,
|
|
| 'Perform an inquisition'],
|
|
| ['holyquest', 'quest', HolyQuestOptions,
|
|
| 'Embark upon a holy quest']
|
|
| ]
|
|
|
|
In this case, C{"<program> holyquest --horseback --for-grail"} will cause
|
|
C{HolyQuestOptions} to be instantiated and asked to parse
|
|
C{['--horseback', '--for-grail']}. Currently, only the first sub-command
|
|
is parsed, and all options following it are passed to its parser. If a
|
|
subcommand is found, the subCommand attribute is set to its name and the
|
|
subOptions attribute is set to the Option instance that parses the
|
|
remaining options. If a subcommand is not given to parseOptions,
|
|
the subCommand attribute will be None. You can also mark one of
|
|
the subCommands to be the default.
|
|
|
|
| defaultSubCommand = 'holyquest'
|
|
|
|
In this case, the subCommand attribute will never be None, and
|
|
the subOptions attribute will always be set.
|
|
|
|
If you want to handle your own options, define a method named
|
|
C{opt_paramname} that takes C{(self, option)} as arguments. C{option}
|
|
will be whatever immediately follows the parameter on the
|
|
command line. Options fully supports the mapping interface, so you
|
|
can do things like C{'self["option"] = val'} in these methods.
|
|
|
|
Advanced functionality is covered in the howto documentation,
|
|
available at
|
|
U{http://twistedmatrix.com/projects/core/documentation/howto/options.html},
|
|
or doc/howto/options.html in your Twisted directory.
|
|
"""
|
|
|
|
subCommand = None
|
|
defaultSubCommand = None
|
|
parent = None
|
|
def __init__(self):
|
|
super(Options, self).__init__()
|
|
|
|
self.opts = self
|
|
self.defaults = {}
|
|
|
|
# These are strings/lists we will pass to getopt
|
|
self.longOpt = []
|
|
self.shortOpt = ''
|
|
self.docs = {}
|
|
self.synonyms = {}
|
|
self._dispatch = {}
|
|
|
|
|
|
collectors = [
|
|
self._gather_flags,
|
|
self._gather_parameters,
|
|
self._gather_handlers,
|
|
]
|
|
|
|
for c in collectors:
|
|
(longOpt, shortOpt, docs, settings, synonyms, dispatch) = c()
|
|
self.longOpt.extend(longOpt)
|
|
self.shortOpt = self.shortOpt + shortOpt
|
|
self.docs.update(docs)
|
|
|
|
self.opts.update(settings)
|
|
self.defaults.update(settings)
|
|
|
|
self.synonyms.update(synonyms)
|
|
self._dispatch.update(dispatch)
|
|
|
|
def __hash__(self):
|
|
"""
|
|
Define a custom hash function so that Options instances can be used
|
|
as dictionary keys. This is an internal feature used to implement
|
|
the parser. Do not rely on it in application code.
|
|
"""
|
|
return int(id(self) % sys.maxint)
|
|
|
|
def opt_help(self):
|
|
"""
|
|
Display this help and exit.
|
|
"""
|
|
print self.__str__()
|
|
sys.exit(0)
|
|
|
|
def opt_version(self):
|
|
from twisted import copyright
|
|
print "Twisted version:", copyright.version
|
|
sys.exit(0)
|
|
|
|
#opt_h = opt_help # this conflicted with existing 'host' options.
|
|
|
|
def parseOptions(self, options=None):
|
|
"""
|
|
The guts of the command-line parser.
|
|
"""
|
|
|
|
if options is None:
|
|
options = sys.argv[1:]
|
|
try:
|
|
opts, args = getopt.getopt(options,
|
|
self.shortOpt, self.longOpt)
|
|
except getopt.error, e:
|
|
raise UsageError(str(e))
|
|
|
|
for opt, arg in opts:
|
|
if opt[1] == '-':
|
|
opt = opt[2:]
|
|
else:
|
|
opt = opt[1:]
|
|
|
|
optMangled = opt
|
|
if optMangled not in self.synonyms:
|
|
optMangled = opt.replace("-", "_")
|
|
if optMangled not in self.synonyms:
|
|
raise UsageError("No such option '%s'" % (opt,))
|
|
|
|
optMangled = self.synonyms[optMangled]
|
|
if isinstance(self._dispatch[optMangled], CoerceParameter):
|
|
self._dispatch[optMangled].dispatch(optMangled, arg)
|
|
else:
|
|
self._dispatch[optMangled](optMangled, arg)
|
|
|
|
if (getattr(self, 'subCommands', None)
|
|
and (args or self.defaultSubCommand is not None)):
|
|
if not args:
|
|
args = [self.defaultSubCommand]
|
|
sub, rest = args[0], args[1:]
|
|
for (cmd, short, parser, doc) in self.subCommands:
|
|
if sub == cmd or sub == short:
|
|
self.subCommand = cmd
|
|
self.subOptions = parser()
|
|
self.subOptions.parent = self
|
|
self.subOptions.parseOptions(rest)
|
|
break
|
|
else:
|
|
raise UsageError("Unknown command: %s" % sub)
|
|
else:
|
|
try:
|
|
self.parseArgs(*args)
|
|
except TypeError:
|
|
raise UsageError("Wrong number of arguments.")
|
|
|
|
self.postOptions()
|
|
|
|
def postOptions(self):
|
|
"""
|
|
I am called after the options are parsed.
|
|
|
|
Override this method in your subclass to do something after
|
|
the options have been parsed and assigned, like validate that
|
|
all options are sane.
|
|
"""
|
|
|
|
def parseArgs(self):
|
|
"""
|
|
I am called with any leftover arguments which were not options.
|
|
|
|
Override me to do something with the remaining arguments on
|
|
the command line, those which were not flags or options. e.g.
|
|
interpret them as a list of files to operate on.
|
|
|
|
Note that if there more arguments on the command line
|
|
than this method accepts, parseArgs will blow up with
|
|
a getopt.error. This means if you don't override me,
|
|
parseArgs will blow up if I am passed any arguments at
|
|
all!
|
|
"""
|
|
|
|
def _generic_flag(self, flagName, value=None):
|
|
if value not in ('', None):
|
|
raise UsageError("Flag '%s' takes no argument."
|
|
" Not even \"%s\"." % (flagName, value))
|
|
|
|
self.opts[flagName] = 1
|
|
|
|
def _gather_flags(self):
|
|
"""
|
|
Gather up boolean (flag) options.
|
|
"""
|
|
|
|
longOpt, shortOpt = [], ''
|
|
docs, settings, synonyms, dispatch = {}, {}, {}, {}
|
|
|
|
flags = []
|
|
reflect.accumulateClassList(self.__class__, 'optFlags', flags)
|
|
|
|
for flag in flags:
|
|
long, short, doc = util.padTo(3, flag)
|
|
if not long:
|
|
raise ValueError("A flag cannot be without a name.")
|
|
|
|
docs[long] = doc
|
|
settings[long] = 0
|
|
if short:
|
|
shortOpt = shortOpt + short
|
|
synonyms[short] = long
|
|
longOpt.append(long)
|
|
synonyms[long] = long
|
|
dispatch[long] = self._generic_flag
|
|
|
|
return longOpt, shortOpt, docs, settings, synonyms, dispatch
|
|
|
|
def _gather_parameters(self):
|
|
"""
|
|
Gather options which take a value.
|
|
"""
|
|
longOpt, shortOpt = [], ''
|
|
docs, settings, synonyms, dispatch = {}, {}, {}, {}
|
|
|
|
parameters = []
|
|
|
|
reflect.accumulateClassList(self.__class__, 'optStrings',
|
|
parameters)
|
|
if parameters:
|
|
import warnings
|
|
warnings.warn("Options.optStrings is deprecated, "
|
|
"please use optParameters instead.", stacklevel=2)
|
|
|
|
reflect.accumulateClassList(self.__class__, 'optParameters',
|
|
parameters)
|
|
|
|
synonyms = {}
|
|
|
|
for parameter in parameters:
|
|
long, short, default, doc, paramType = util.padTo(5, parameter)
|
|
if not long:
|
|
raise ValueError("A parameter cannot be without a name.")
|
|
|
|
docs[long] = doc
|
|
settings[long] = default
|
|
if short:
|
|
shortOpt = shortOpt + short + ':'
|
|
synonyms[short] = long
|
|
longOpt.append(long + '=')
|
|
synonyms[long] = long
|
|
if paramType is not None:
|
|
dispatch[long] = CoerceParameter(self, paramType)
|
|
else:
|
|
dispatch[long] = CoerceParameter(self, str)
|
|
|
|
return longOpt, shortOpt, docs, settings, synonyms, dispatch
|
|
|
|
|
|
def _gather_handlers(self):
|
|
"""
|
|
Gather up options with their own handler methods.
|
|
"""
|
|
|
|
longOpt, shortOpt = [], ''
|
|
docs, settings, synonyms, dispatch = {}, {}, {}, {}
|
|
|
|
dct = {}
|
|
reflect.addMethodNamesToDict(self.__class__, dct, "opt_")
|
|
|
|
for name in dct.keys():
|
|
method = getattr(self, 'opt_'+name)
|
|
|
|
takesArg = not flagFunction(method, name)
|
|
|
|
prettyName = name.replace('_', '-')
|
|
doc = getattr(method, '__doc__', None)
|
|
if doc:
|
|
## Only use the first line.
|
|
#docs[name] = doc.split('\n')[0]
|
|
docs[prettyName] = doc
|
|
else:
|
|
docs[prettyName] = self.docs.get(prettyName)
|
|
|
|
synonyms[prettyName] = prettyName
|
|
|
|
# A little slight-of-hand here makes dispatching much easier
|
|
# in parseOptions, as it makes all option-methods have the
|
|
# same signature.
|
|
if takesArg:
|
|
fn = lambda name, value, m=method: m(value)
|
|
else:
|
|
# XXX: This won't raise a TypeError if it's called
|
|
# with a value when it shouldn't be.
|
|
fn = lambda name, value=None, m=method: m()
|
|
|
|
dispatch[prettyName] = fn
|
|
|
|
if len(name) == 1:
|
|
shortOpt = shortOpt + name
|
|
if takesArg:
|
|
shortOpt = shortOpt + ':'
|
|
else:
|
|
if takesArg:
|
|
prettyName = prettyName + '='
|
|
longOpt.append(prettyName)
|
|
|
|
reverse_dct = {}
|
|
# Map synonyms
|
|
for name in dct.keys():
|
|
method = getattr(self, 'opt_' + name)
|
|
if method not in reverse_dct:
|
|
reverse_dct[method] = []
|
|
reverse_dct[method].append(name)
|
|
|
|
cmpLength = lambda a, b: cmp(len(a), len(b))
|
|
|
|
for method, names in reverse_dct.items():
|
|
if len(names) < 2:
|
|
continue
|
|
names_ = names[:]
|
|
names_.sort(cmpLength)
|
|
longest = names_.pop()
|
|
for name in names_:
|
|
synonyms[name] = longest
|
|
|
|
return longOpt, shortOpt, docs, settings, synonyms, dispatch
|
|
|
|
|
|
def __str__(self):
|
|
return self.getSynopsis() + '\n' + self.getUsage(width=None)
|
|
|
|
def getSynopsis(self):
|
|
"""
|
|
Returns a string containing a description of these options and how to
|
|
pass them to the executed file.
|
|
"""
|
|
|
|
default = "%s%s" % (path.basename(sys.argv[0]),
|
|
(self.longOpt and " [options]") or '')
|
|
if self.parent is None:
|
|
default = "Usage: %s%s" % (path.basename(sys.argv[0]),
|
|
(self.longOpt and " [options]") or '')
|
|
else:
|
|
default = '%s' % ((self.longOpt and "[options]") or '')
|
|
synopsis = getattr(self, "synopsis", default)
|
|
|
|
synopsis = synopsis.rstrip()
|
|
|
|
if self.parent is not None:
|
|
synopsis = ' '.join((self.parent.getSynopsis(),
|
|
self.parent.subCommand, synopsis))
|
|
|
|
return synopsis
|
|
|
|
def getUsage(self, width=None):
|
|
# If subOptions exists by now, then there was probably an error while
|
|
# parsing its options.
|
|
if hasattr(self, 'subOptions'):
|
|
return self.subOptions.getUsage(width=width)
|
|
|
|
if not width:
|
|
width = int(os.environ.get('COLUMNS', '80'))
|
|
|
|
if hasattr(self, 'subCommands'):
|
|
cmdDicts = []
|
|
for (cmd, short, parser, desc) in self.subCommands:
|
|
cmdDicts.append(
|
|
{'long': cmd,
|
|
'short': short,
|
|
'doc': desc,
|
|
'optType': 'command',
|
|
'default': None
|
|
})
|
|
chunks = docMakeChunks(cmdDicts, width)
|
|
commands = 'Commands:\n' + ''.join(chunks)
|
|
else:
|
|
commands = ''
|
|
|
|
longToShort = {}
|
|
for key, value in self.synonyms.items():
|
|
longname = value
|
|
if (key != longname) and (len(key) == 1):
|
|
longToShort[longname] = key
|
|
else:
|
|
if longname not in longToShort:
|
|
longToShort[longname] = None
|
|
else:
|
|
pass
|
|
|
|
optDicts = []
|
|
for opt in self.longOpt:
|
|
if opt[-1] == '=':
|
|
optType = 'parameter'
|
|
opt = opt[:-1]
|
|
else:
|
|
optType = 'flag'
|
|
|
|
optDicts.append(
|
|
{'long': opt,
|
|
'short': longToShort[opt],
|
|
'doc': self.docs[opt],
|
|
'optType': optType,
|
|
'default': self.defaults.get(opt, None),
|
|
'dispatch': self._dispatch.get(opt, None)
|
|
})
|
|
|
|
if not (getattr(self, "longdesc", None) is None):
|
|
longdesc = self.longdesc
|
|
else:
|
|
import __main__
|
|
if getattr(__main__, '__doc__', None):
|
|
longdesc = __main__.__doc__
|
|
else:
|
|
longdesc = ''
|
|
|
|
if longdesc:
|
|
longdesc = ('\n' +
|
|
'\n'.join(text.wordWrap(longdesc, width)).strip()
|
|
+ '\n')
|
|
|
|
if optDicts:
|
|
chunks = docMakeChunks(optDicts, width)
|
|
s = "Options:\n%s" % (''.join(chunks))
|
|
else:
|
|
s = "Options: None\n"
|
|
|
|
return s + longdesc + commands
|
|
|
|
#def __repr__(self):
|
|
# XXX: It'd be cool if we could return a succinct representation
|
|
# of which flags and options are set here.
|
|
|
|
|
|
def docMakeChunks(optList, width=80):
|
|
"""
|
|
Makes doc chunks for option declarations.
|
|
|
|
Takes a list of dictionaries, each of which may have one or more
|
|
of the keys 'long', 'short', 'doc', 'default', 'optType'.
|
|
|
|
Returns a list of strings.
|
|
The strings may be multiple lines,
|
|
all of them end with a newline.
|
|
"""
|
|
|
|
# XXX: sanity check to make sure we have a sane combination of keys.
|
|
|
|
maxOptLen = 0
|
|
for opt in optList:
|
|
optLen = len(opt.get('long', ''))
|
|
if optLen:
|
|
if opt.get('optType', None) == "parameter":
|
|
# these take up an extra character
|
|
optLen = optLen + 1
|
|
maxOptLen = max(optLen, maxOptLen)
|
|
|
|
colWidth1 = maxOptLen + len(" -s, -- ")
|
|
colWidth2 = width - colWidth1
|
|
# XXX - impose some sane minimum limit.
|
|
# Then if we don't have enough room for the option and the doc
|
|
# to share one line, they can take turns on alternating lines.
|
|
|
|
colFiller1 = " " * colWidth1
|
|
|
|
optChunks = []
|
|
seen = {}
|
|
for opt in optList:
|
|
if opt.get('short', None) in seen or opt.get('long', None) in seen:
|
|
continue
|
|
for x in opt.get('short', None), opt.get('long', None):
|
|
if x is not None:
|
|
seen[x] = 1
|
|
|
|
optLines = []
|
|
comma = " "
|
|
if opt.get('short', None):
|
|
short = "-%c" % (opt['short'],)
|
|
else:
|
|
short = ''
|
|
|
|
if opt.get('long', None):
|
|
long = opt['long']
|
|
if opt.get("optType", None) == "parameter":
|
|
long = long + '='
|
|
|
|
long = "%-*s" % (maxOptLen, long)
|
|
if short:
|
|
comma = ","
|
|
else:
|
|
long = " " * (maxOptLen + len('--'))
|
|
|
|
if opt.get('optType', None) == 'command':
|
|
column1 = ' %s ' % long
|
|
else:
|
|
column1 = " %2s%c --%s " % (short, comma, long)
|
|
|
|
if opt.get('doc', ''):
|
|
doc = opt['doc'].strip()
|
|
else:
|
|
doc = ''
|
|
|
|
if (opt.get("optType", None) == "parameter") \
|
|
and not (opt.get('default', None) is None):
|
|
doc = "%s [default: %s]" % (doc, opt['default'])
|
|
|
|
if (opt.get("optType", None) == "parameter") \
|
|
and opt.get('dispatch', None) is not None:
|
|
d = opt['dispatch']
|
|
if isinstance(d, CoerceParameter) and d.doc:
|
|
doc = "%s. %s" % (doc, d.doc)
|
|
|
|
if doc:
|
|
column2_l = text.wordWrap(doc, colWidth2)
|
|
else:
|
|
column2_l = ['']
|
|
|
|
optLines.append("%s%s\n" % (column1, column2_l.pop(0)))
|
|
|
|
for line in column2_l:
|
|
optLines.append("%s%s\n" % (colFiller1, line))
|
|
|
|
optChunks.append(''.join(optLines))
|
|
|
|
return optChunks
|
|
|
|
|
|
def flagFunction(method, name=None):
|
|
reqArgs = method.im_func.func_code.co_argcount
|
|
if reqArgs > 2:
|
|
raise UsageError('Invalid Option function for %s' %
|
|
(name or method.func_name))
|
|
if reqArgs == 2:
|
|
# argName = method.im_func.func_code.co_varnames[1]
|
|
return 0
|
|
return 1
|
|
|
|
|
|
def portCoerce(value):
|
|
"""
|
|
Coerce a string value to an int port number, and checks the validity.
|
|
"""
|
|
value = int(value)
|
|
if value < 0 or value > 65535:
|
|
raise ValueError("Port number not in range: %s" % (value,))
|
|
return value
|
|
portCoerce.coerceDoc = "Must be an int between 0 and 65535."
|
|
|
|
|