Adding new stuff
This commit is contained in:
Viktor Barzin
parent
39ee792ad4
commit
a410da0e04
722 changed files with 331 additions and 189 deletions
|
|
@ -1,334 +0,0 @@
|
|||
# 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/>.
|
||||
"""Helper functions to support command line tools providing more than
|
||||
one command.
|
||||
|
||||
e.g called as "tool command [options] args..." where <options> and <args> are
|
||||
command'specific
|
||||
"""
|
||||
|
||||
from __future__ import print_function
|
||||
|
||||
__docformat__ = "restructuredtext en"
|
||||
|
||||
import sys
|
||||
import logging
|
||||
from os.path import basename
|
||||
|
||||
from logilab.common.configuration import Configuration
|
||||
from logilab.common.logging_ext import init_log, get_threshold
|
||||
from logilab.common.deprecation import deprecated
|
||||
|
||||
|
||||
class BadCommandUsage(Exception):
|
||||
"""Raised when an unknown command is used or when a command is not
|
||||
correctly used (bad options, too much / missing arguments...).
|
||||
|
||||
Trigger display of command usage.
|
||||
"""
|
||||
|
||||
class CommandError(Exception):
|
||||
"""Raised when a command can't be processed and we want to display it and
|
||||
exit, without traceback nor usage displayed.
|
||||
"""
|
||||
|
||||
|
||||
# command line access point ####################################################
|
||||
|
||||
class CommandLine(dict):
|
||||
"""Usage:
|
||||
|
||||
>>> LDI = cli.CommandLine('ldi', doc='Logilab debian installer',
|
||||
version=version, rcfile=RCFILE)
|
||||
>>> LDI.register(MyCommandClass)
|
||||
>>> LDI.register(MyOtherCommandClass)
|
||||
>>> LDI.run(sys.argv[1:])
|
||||
|
||||
Arguments:
|
||||
|
||||
* `pgm`, the program name, default to `basename(sys.argv[0])`
|
||||
|
||||
* `doc`, a short description of the command line tool
|
||||
|
||||
* `copyright`, additional doc string that will be appended to the generated
|
||||
doc
|
||||
|
||||
* `version`, version number of string of the tool. If specified, global
|
||||
--version option will be available.
|
||||
|
||||
* `rcfile`, path to a configuration file. If specified, global --C/--rc-file
|
||||
option will be available? self.rcfile = rcfile
|
||||
|
||||
* `logger`, logger to propagate to commands, default to
|
||||
`logging.getLogger(self.pgm))`
|
||||
"""
|
||||
def __init__(self, pgm=None, doc=None, copyright=None, version=None,
|
||||
rcfile=None, logthreshold=logging.ERROR,
|
||||
check_duplicated_command=True):
|
||||
if pgm is None:
|
||||
pgm = basename(sys.argv[0])
|
||||
self.pgm = pgm
|
||||
self.doc = doc
|
||||
self.copyright = copyright
|
||||
self.version = version
|
||||
self.rcfile = rcfile
|
||||
self.logger = None
|
||||
self.logthreshold = logthreshold
|
||||
self.check_duplicated_command = check_duplicated_command
|
||||
|
||||
def register(self, cls, force=False):
|
||||
"""register the given :class:`Command` subclass"""
|
||||
assert not self.check_duplicated_command or force or not cls.name in self, \
|
||||
'a command %s is already defined' % cls.name
|
||||
self[cls.name] = cls
|
||||
return cls
|
||||
|
||||
def run(self, args):
|
||||
"""main command line access point:
|
||||
* init logging
|
||||
* handle global options (-h/--help, --version, -C/--rc-file)
|
||||
* check command
|
||||
* run command
|
||||
|
||||
Terminate by :exc:`SystemExit`
|
||||
"""
|
||||
init_log(debug=True, # so that we use StreamHandler
|
||||
logthreshold=self.logthreshold,
|
||||
logformat='%(levelname)s: %(message)s')
|
||||
try:
|
||||
arg = args.pop(0)
|
||||
except IndexError:
|
||||
self.usage_and_exit(1)
|
||||
if arg in ('-h', '--help'):
|
||||
self.usage_and_exit(0)
|
||||
if self.version is not None and arg in ('--version'):
|
||||
print(self.version)
|
||||
sys.exit(0)
|
||||
rcfile = self.rcfile
|
||||
if rcfile is not None and arg in ('-C', '--rc-file'):
|
||||
try:
|
||||
rcfile = args.pop(0)
|
||||
arg = args.pop(0)
|
||||
except IndexError:
|
||||
self.usage_and_exit(1)
|
||||
try:
|
||||
command = self.get_command(arg)
|
||||
except KeyError:
|
||||
print('ERROR: no %s command' % arg)
|
||||
print()
|
||||
self.usage_and_exit(1)
|
||||
try:
|
||||
sys.exit(command.main_run(args, rcfile))
|
||||
except KeyboardInterrupt as exc:
|
||||
print('Interrupted', end=' ')
|
||||
if str(exc):
|
||||
print(': %s' % exc, end=' ')
|
||||
print()
|
||||
sys.exit(4)
|
||||
except BadCommandUsage as err:
|
||||
print('ERROR:', err)
|
||||
print()
|
||||
print(command.help())
|
||||
sys.exit(1)
|
||||
|
||||
def create_logger(self, handler, logthreshold=None):
|
||||
logger = logging.Logger(self.pgm)
|
||||
logger.handlers = [handler]
|
||||
if logthreshold is None:
|
||||
logthreshold = get_threshold(self.logthreshold)
|
||||
logger.setLevel(logthreshold)
|
||||
return logger
|
||||
|
||||
def get_command(self, cmd, logger=None):
|
||||
if logger is None:
|
||||
logger = self.logger
|
||||
if logger is None:
|
||||
logger = self.logger = logging.getLogger(self.pgm)
|
||||
logger.setLevel(get_threshold(self.logthreshold))
|
||||
return self[cmd](logger)
|
||||
|
||||
def usage(self):
|
||||
"""display usage for the main program (i.e. when no command supplied)
|
||||
and exit
|
||||
"""
|
||||
print('usage:', self.pgm, end=' ')
|
||||
if self.rcfile:
|
||||
print('[--rc-file=<configuration file>]', end=' ')
|
||||
print('<command> [options] <command argument>...')
|
||||
if self.doc:
|
||||
print('\n%s' % self.doc)
|
||||
print('''
|
||||
Type "%(pgm)s <command> --help" for more information about a specific
|
||||
command. Available commands are :\n''' % self.__dict__)
|
||||
max_len = max([len(cmd) for cmd in self])
|
||||
padding = ' ' * max_len
|
||||
for cmdname, cmd in sorted(self.items()):
|
||||
if not cmd.hidden:
|
||||
print(' ', (cmdname + padding)[:max_len], cmd.short_description())
|
||||
if self.rcfile:
|
||||
print('''
|
||||
Use --rc-file=<configuration file> / -C <configuration file> before the command
|
||||
to specify a configuration file. Default to %s.
|
||||
''' % self.rcfile)
|
||||
print('''%(pgm)s -h/--help
|
||||
display this usage information and exit''' % self.__dict__)
|
||||
if self.version:
|
||||
print('''%(pgm)s -v/--version
|
||||
display version configuration and exit''' % self.__dict__)
|
||||
if self.copyright:
|
||||
print('\n', self.copyright)
|
||||
|
||||
def usage_and_exit(self, status):
|
||||
self.usage()
|
||||
sys.exit(status)
|
||||
|
||||
|
||||
# base command classes #########################################################
|
||||
|
||||
class Command(Configuration):
|
||||
"""Base class for command line commands.
|
||||
|
||||
Class attributes:
|
||||
|
||||
* `name`, the name of the command
|
||||
|
||||
* `min_args`, minimum number of arguments, None if unspecified
|
||||
|
||||
* `max_args`, maximum number of arguments, None if unspecified
|
||||
|
||||
* `arguments`, string describing arguments, used in command usage
|
||||
|
||||
* `hidden`, boolean flag telling if the command should be hidden, e.g. does
|
||||
not appear in help's commands list
|
||||
|
||||
* `options`, options list, as allowed by :mod:configuration
|
||||
"""
|
||||
|
||||
arguments = ''
|
||||
name = ''
|
||||
# hidden from help ?
|
||||
hidden = False
|
||||
# max/min args, None meaning unspecified
|
||||
min_args = None
|
||||
max_args = None
|
||||
|
||||
@classmethod
|
||||
def description(cls):
|
||||
return cls.__doc__.replace(' ', '')
|
||||
|
||||
@classmethod
|
||||
def short_description(cls):
|
||||
return cls.description().split('.')[0]
|
||||
|
||||
def __init__(self, logger):
|
||||
usage = '%%prog %s %s\n\n%s' % (self.name, self.arguments,
|
||||
self.description())
|
||||
Configuration.__init__(self, usage=usage)
|
||||
self.logger = logger
|
||||
|
||||
def check_args(self, args):
|
||||
"""check command's arguments are provided"""
|
||||
if self.min_args is not None and len(args) < self.min_args:
|
||||
raise BadCommandUsage('missing argument')
|
||||
if self.max_args is not None and len(args) > self.max_args:
|
||||
raise BadCommandUsage('too many arguments')
|
||||
|
||||
def main_run(self, args, rcfile=None):
|
||||
"""Run the command and return status 0 if everything went fine.
|
||||
|
||||
If :exc:`CommandError` is raised by the underlying command, simply log
|
||||
the error and return status 2.
|
||||
|
||||
Any other exceptions, including :exc:`BadCommandUsage` will be
|
||||
propagated.
|
||||
"""
|
||||
if rcfile:
|
||||
self.load_file_configuration(rcfile)
|
||||
args = self.load_command_line_configuration(args)
|
||||
try:
|
||||
self.check_args(args)
|
||||
self.run(args)
|
||||
except CommandError as err:
|
||||
self.logger.error(err)
|
||||
return 2
|
||||
return 0
|
||||
|
||||
def run(self, args):
|
||||
"""run the command with its specific arguments"""
|
||||
raise NotImplementedError()
|
||||
|
||||
|
||||
class ListCommandsCommand(Command):
|
||||
"""list available commands, useful for bash completion."""
|
||||
name = 'listcommands'
|
||||
arguments = '[command]'
|
||||
hidden = True
|
||||
|
||||
def run(self, args):
|
||||
"""run the command with its specific arguments"""
|
||||
if args:
|
||||
command = args.pop()
|
||||
cmd = _COMMANDS[command]
|
||||
for optname, optdict in cmd.options:
|
||||
print('--help')
|
||||
print('--' + optname)
|
||||
else:
|
||||
commands = sorted(_COMMANDS.keys())
|
||||
for command in commands:
|
||||
cmd = _COMMANDS[command]
|
||||
if not cmd.hidden:
|
||||
print(command)
|
||||
|
||||
|
||||
# deprecated stuff #############################################################
|
||||
|
||||
_COMMANDS = CommandLine()
|
||||
|
||||
DEFAULT_COPYRIGHT = '''\
|
||||
Copyright (c) 2004-2011 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
|
||||
http://www.logilab.fr/ -- mailto:contact@logilab.fr'''
|
||||
|
||||
@deprecated('use cls.register(cli)')
|
||||
def register_commands(commands):
|
||||
"""register existing commands"""
|
||||
for command_klass in commands:
|
||||
_COMMANDS.register(command_klass)
|
||||
|
||||
@deprecated('use args.pop(0)')
|
||||
def main_run(args, doc=None, copyright=None, version=None):
|
||||
"""command line tool: run command specified by argument list (without the
|
||||
program name). Raise SystemExit with status 0 if everything went fine.
|
||||
|
||||
>>> main_run(sys.argv[1:])
|
||||
"""
|
||||
_COMMANDS.doc = doc
|
||||
_COMMANDS.copyright = copyright
|
||||
_COMMANDS.version = version
|
||||
_COMMANDS.run(args)
|
||||
|
||||
@deprecated('use args.pop(0)')
|
||||
def pop_arg(args_list, expected_size_after=None, msg="Missing argument"):
|
||||
"""helper function to get and check command line arguments"""
|
||||
try:
|
||||
value = args_list.pop(0)
|
||||
except IndexError:
|
||||
raise BadCommandUsage(msg)
|
||||
if expected_size_after is not None and len(args_list) > expected_size_after:
|
||||
raise BadCommandUsage('too many arguments')
|
||||
return value
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue