""" CommandLine - Get and parse command line options
NOTE: This still is very much work in progress !!!
Different version are likely to be incompatible.
TODO:
* Incorporate the changes made by (see Inbox)
* Add number range option using srange()
"""
__copyright__ = """\
Copyright (c), 1997-2006, Marc-Andre Lemburg ([email protected])
Copyright (c), 2000-2006, eGenix.com Software GmbH ([email protected])
See the documentation for further information on copyrights,
or contact the author. All Rights Reserved.
"""
__version__ = '1.2'
import sys, getopt, string, glob, os, re, exceptions, traceback
### Helpers
def _getopt_flags(options):
""" Convert the option list to a getopt flag string and long opt
list
"""
s = []
l = []
for o in options:
if o.prefix == '-':
# short option
s.append(o.name)
if o.takes_argument:
s.append(':')
else:
# long option
if o.takes_argument:
l.append(o.name+'=')
else:
l.append(o.name)
return string.join(s,''),l
def invisible_input(prompt='>>> '):
""" Get raw input from a terminal without echoing the characters to
the terminal, e.g. for password queries.
"""
import getpass
entry = getpass.getpass(prompt)
if entry is None:
raise KeyboardInterrupt
return entry
def fileopen(name, mode='wb', encoding=None):
""" Open a file using mode.
Default mode is 'wb' meaning to open the file for writing in
binary mode. If encoding is given, I/O to and from the file is
transparently encoded using the given encoding.
Files opened for writing are chmod()ed to 0600.
"""
if name == 'stdout':
return sys.stdout
elif name == 'stderr':
return sys.stderr
elif name == 'stdin':
return sys.stdin
else:
if encoding is not None:
import codecs
f = codecs.open(name, mode, encoding)
else:
f = open(name, mode)
if 'w' in mode:
os.chmod(name, 0600)
return f
def option_dict(options):
""" Return a dictionary mapping option names to Option instances.
"""
d = {}
for option in options:
d[option.name] = option
return d
# Alias
getpasswd = invisible_input
_integerRE = re.compile('\s*(-?\d+)\s*$')
_integerRangeRE = re.compile('\s*(-?\d+)\s*-\s*(-?\d+)\s*$')
def srange(s,
split=string.split,integer=_integerRE,
integerRange=_integerRangeRE):
""" Converts a textual representation of integer numbers and ranges
to a Python list.
Supported formats: 2,3,4,2-10,-1 - -3, 5 - -2
Values are appended to the created list in the order specified
in the string.
"""
l = []
append = l.append
for entry in split(s,','):
m = integer.match(entry)
if m:
append(int(m.groups()[0]))
continue
m = integerRange.match(entry)
if m:
start,end = map(int,m.groups())
l[len(l):] = range(start,end+1)
return l
def abspath(path,
expandvars=os.path.expandvars,expanduser=os.path.expanduser,
join=os.path.join,getcwd=os.getcwd):
""" Return the corresponding absolute path for path.
path is expanded in the usual shell ways before
joining it with the current working directory.
"""
try:
path = expandvars(path)
except AttributeError:
pass
try:
path = expanduser(path)
except AttributeError:
pass
return join(getcwd(), path)
### Option classes
class Option:
""" Option base class. Takes no argument.
"""
default = None
helptext = ''
prefix = '-'
takes_argument = 0
has_default = 0
tab = 15
def __init__(self,name,help=None):
if not name[:1] == '-':
raise TypeError,'option names must start with "-"'
if name[1:2] == '-':
self.prefix = '--'
self.name = name[2:]
else:
self.name = name[1:]
if help:
self.help = help
def __str__(self):
o = self
name = o.prefix + o.name
if o.takes_argument:
name = name + ' arg'
if len(name) > self.tab:
name = name + '\n' + ' ' * (self.tab + 1 + len(o.prefix))
else:
name = '%-*s ' % (self.tab, name)
description = o.help
if o.has_default:
description = description + ' (%s)' % o.default
return '%s %s' % (name, description)
class ArgumentOption(Option):
""" Option that takes an argument.
An optional default argument can be given.
"""
def __init__(self,name,help=None,default=None):
# Basemethod
Option.__init__(self,name,help)
if default is not None:
self.default = default
self.has_default = 1
self.takes_argument = 1
class SwitchOption(Option):
""" Options that can be on or off. Has an optional default value.
"""
def __init__(self,name,help=None,default=None):
# Basemethod
Option.__init__(self,name,help)
if default is not None:
self.default = default
self.has_default = 1
### Application baseclass
class Application:
""" Command line application interface with builtin argument
parsing.
"""
# Options the program accepts (Option instances)
options = []
# Standard settings; these are appended to options in __init__
preset_options = [SwitchOption('-v',
'generate verbose output'),
SwitchOption('-h',
'show this help text'),
SwitchOption('--help',
'show this help text'),
SwitchOption('--debug',
'enable debugging'),
SwitchOption('--copyright',
'show copyright'),
SwitchOption('--examples',
'show examples of usage')]
# The help layout looks like this:
# [header] - defaults to ''
#
# [synopsis] - formatted as '<self.name> %s' % self.synopsis
#
# options:
# [options] - formatted from self.options
#
# [version] - formatted as 'Version:\n %s' % self.version, if given
#
# [about] - defaults to ''
#
# Note: all fields that do not behave as template are formatted
# using the instances dictionary as substitution namespace,
# e.g. %(name)s will be replaced by the applications name.
#
# Header (default to program name)
header = ''
# Name (defaults to program name)
name = ''
# Synopsis (%(name)s is replaced by the program name)
synopsis = '%(name)s [option] files...'
# Version (optional)
version = ''
# General information printed after the possible options (optional)
about = ''
# Examples of usage to show when the --examples option is given (optional)
examples = ''
# Copyright to show
copyright = __copyright__
# Apply file globbing ?
globbing = 1
# Generate debug output ?
debug = 0
# Generate verbose output ?
verbose = 0
# Internal errors to catch
InternalError = exceptions.Exception
# Instance variables:
values = None # Dictionary of passed options (or default values)
# indexed by the options name, e.g. '-h'
files = None # List of passed filenames
optionlist = None # List of passed options
def __init__(self,argv=None):
# Setup application specs
if argv is None:
argv = sys.argv
self.filename = os.path.split(argv[0])[1]
if not self.name:
self.name = os.path.split(self.filename)[1]
else:
self.name = self.name
if not self.header:
self.header = self.name
else:
self.header = self.header
# Init .arguments list
self.arguments = argv[1:]
# Setup Option mapping
self.option_map = option_dict(self.options)
# Append preset options
for option in self.preset_options:
if not self.option_map.has_key(option.name):
self.add_option(option)
# Init .files list
self.files = []
# Start Application
try:
# Process startup
rc = self.startup()
if rc is not None:
raise SystemExit,rc
# Parse command line
rc = self.parse()
if rc is not None:
raise SystemExit,rc
# Start application
rc = self.main()
if rc is None:
rc = 0
except SystemExit,rc:
pass
except KeyboardInterrupt:
print
print '* User Break'
print
rc = 1
except self.InternalError:
print
print '* Internal Error (use --debug to display the traceback)'
if self.debug:
print
traceback.print_exc(20, sys.stdout)
elif self.verbose:
print ' %s: %s' % sys.exc_info()[:2]
print
rc = 1
raise SystemExit,rc
def add_option(self, option):
""" Add a new Option instance to the Application dynamically.
Note that this has to be done *before* .parse() is being
executed.
"""
self.options.append(option)
self.option_map[option.name] = option
def startup(self):
""" Set user defined instance variables.
If this method returns anything other than None, the
process is terminated with the return value as exit code.
"""
return None
def exit(self, rc=0):
""" Exit the program.
rc is used as exit code and passed back to the calling
program. It defaults to 0 which usually means: OK.
"""
raise SystemExit, rc
def parse(self):
""" Parse the command line and fill in self.values and self.files.
After having parsed the options, the remaining command line
arguments are interpreted as files and passed to .handle_files()
for processing.
As final step the option handlers are called in the order
of the options given on the command line.
"""
# Parse arguments
self.values = values = {}
for o in self.options:
if o.has_default:
values[o.prefix+o.name] = o.default
else:
values[o.prefix+o.name] = 0
flags,lflags = _getopt_flags(self.options)
try:
optlist,files = getopt.getopt(self.arguments,flags,lflags)
if self.globbing:
l = []
for f in files:
gf = glob.glob(f)
if not gf:
l.append(f)
else:
l[len(l):] = gf
files = l
self.optionlist = optlist
self.files = files + self.files
except getopt.error,why:
self.help(why)
sys.exit(1)
# Call file handler
rc = self.handle_files(self.files)
if rc is not None:
sys.exit(rc)
# Call option handlers
for optionname, value in optlist:
# Try to convert value to integer
try:
value = string.atoi(value)
except ValueError:
pass
# Find handler and call it (or count the number of option
# instances on the command line)
handlername = 'handle' + string.replace(optionname, '-', '_')
try:
handler = getattr(self, handlername)
except AttributeError:
if value == '':
# count the number of occurances
if values.has_key(optionname):
values[optionname] = values[optionname] + 1
else:
values[optionname] = 1
else:
values[optionname] = value
else:
rc = handler(value)
if rc is not None:
raise SystemExit, rc
# Apply final file check (for backward compatibility)
rc = self.check_files(self.files)
if rc is not None:
sys.exit(rc)
def check_files(self,filelist):
""" Apply some user defined checks on the files given in filelist.
This may modify filelist in place. A typical application
is checking that at least n files are given.
If this method returns anything other than None, the
process is terminated with the return value as exit code.
"""
return None
def help(self,note=''):
self.print_header()
if self.synopsis:
print 'Synopsis:'
# To remain backward compatible:
try:
synopsis = self.synopsis % self.name
except (NameError, KeyError, TypeError):
synopsis = self.synopsis % self.__dict__
print ' ' + synopsis
print
self.print_options()
if self.version:
print 'Version:'
print ' %s' % self.version
print
if self.about:
print string.strip(self.about % self.__dict__)
print
if note:
print '-'*72
print 'Note:',note
print
def notice(self,note):
print '-'*72
print 'Note:',note
print '-'*72
print
def print_header(self):
print '-'*72
print self.header % self.__dict__
print '-'*72
print
def print_options(self):
options = self.options
print 'Options and default settings:'
if not options:
print ' None'
return
long = filter(lambda x: x.prefix == '--', options)
short = filter(lambda x: x.prefix == '-', options)
items = short + long
for o in options:
print ' ',o
print
#
# Example handlers:
#
# If a handler returns anything other than None, processing stops
# and the return value is passed to sys.exit() as argument.
#
# File handler
def handle_files(self,files):
""" This may process the files list in place.
"""
return None
# Short option handler
def handle_h(self,arg):
self.help()
return 0
def handle_v(self, value):
""" Turn on verbose output.
"""
self.verbose = 1
# Handlers for long options have two underscores in their name
def handle__help(self,arg):
self.help()
return 0
def handle__debug(self,arg):
self.debug = 1
# We don't want to catch internal errors:
self.InternalError = None
def handle__copyright(self,arg):
self.print_header()
print string.strip(self.copyright % self.__dict__)
print
return 0
def handle__examples(self,arg):
self.print_header()
if self.examples:
print 'Examples:'
print
print string.strip(self.examples % self.__dict__)
print
else:
print 'No examples available.'
print
return 0
def main(self):
""" Override this method as program entry point.
The return value is passed to sys.exit() as argument. If
it is None, 0 is assumed (meaning OK). Unhandled
exceptions are reported with exit status code 1 (see
__init__ for further details).
"""
return None
# Alias
CommandLine = Application
def _test():
class MyApplication(Application):
header = 'Test Application'
version = __version__
options = [Option('-v','verbose')]
def handle_v(self,arg):
print 'VERBOSE, Yeah !'
cmd = MyApplication()
if not cmd.values['-h']:
cmd.help()
print 'files:',cmd.files
print 'Bye...'
if __name__ == '__main__':
_test()
|
