mirror of
https://github.com/classilla/tenfourfox.git
synced 2024-06-25 04:29:38 +00:00
350 lines
11 KiB
Python
350 lines
11 KiB
Python
# This Source Code Form is subject to the terms of the Mozilla Public
|
|
# License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
|
|
from __future__ import absolute_import, unicode_literals
|
|
|
|
import argparse
|
|
import collections
|
|
import inspect
|
|
import types
|
|
|
|
from .base import MachError
|
|
from .config import ConfigProvider
|
|
from .registrar import Registrar
|
|
|
|
|
|
class _MachCommand(object):
|
|
"""Container for mach command metadata.
|
|
|
|
Mach commands contain lots of attributes. This class exists to capture them
|
|
in a sane way so tuples, etc aren't used instead.
|
|
"""
|
|
__slots__ = (
|
|
# Content from decorator arguments to define the command.
|
|
'name',
|
|
'subcommand',
|
|
'category',
|
|
'description',
|
|
'conditions',
|
|
'_parser',
|
|
'arguments',
|
|
'argument_group_names',
|
|
|
|
# Describes how dispatch is performed.
|
|
|
|
# The Python class providing the command. This is the class type not
|
|
# an instance of the class. Mach will instantiate a new instance of
|
|
# the class if the command is executed.
|
|
'cls',
|
|
|
|
# Whether the __init__ method of the class should receive a mach
|
|
# context instance. This should only affect the mach driver and how
|
|
# it instantiates classes.
|
|
'pass_context',
|
|
|
|
# The name of the method providing the command. In other words, this
|
|
# is the str name of the attribute on the class type corresponding to
|
|
# the name of the function.
|
|
'method',
|
|
|
|
# Dict of string to _MachCommand defining sub-commands for this
|
|
# command.
|
|
'subcommand_handlers',
|
|
)
|
|
|
|
def __init__(self, name=None, subcommand=None, category=None,
|
|
description=None, conditions=None, parser=None):
|
|
self.name = name
|
|
self.subcommand = subcommand
|
|
self.category = category
|
|
self.description = description
|
|
self.conditions = conditions or []
|
|
self._parser = parser
|
|
self.arguments = []
|
|
self.argument_group_names = []
|
|
|
|
self.cls = None
|
|
self.pass_context = None
|
|
self.method = None
|
|
self.subcommand_handlers = {}
|
|
|
|
@property
|
|
def parser(self):
|
|
# Creating CLI parsers at command dispatch time can be expensive. Make
|
|
# it possible to lazy load them by using functions.
|
|
if callable(self._parser):
|
|
self._parser = self._parser()
|
|
|
|
return self._parser
|
|
|
|
@property
|
|
def docstring(self):
|
|
return self.cls.__dict__[self.method].__doc__
|
|
|
|
def __ior__(self, other):
|
|
if not isinstance(other, _MachCommand):
|
|
raise ValueError('can only operate on _MachCommand instances')
|
|
|
|
for a in self.__slots__:
|
|
if not getattr(self, a):
|
|
setattr(self, a, getattr(other, a))
|
|
|
|
return self
|
|
|
|
|
|
def CommandProvider(cls):
|
|
"""Class decorator to denote that it provides subcommands for Mach.
|
|
|
|
When this decorator is present, mach looks for commands being defined by
|
|
methods inside the class.
|
|
"""
|
|
|
|
# The implementation of this decorator relies on the parse-time behavior of
|
|
# decorators. When the module is imported, the method decorators (like
|
|
# @Command and @CommandArgument) are called *before* this class decorator.
|
|
# The side-effect of the method decorators is to store specifically-named
|
|
# attributes on the function types. We just scan over all functions in the
|
|
# class looking for the side-effects of the method decorators.
|
|
|
|
# Tell mach driver whether to pass context argument to __init__.
|
|
pass_context = False
|
|
|
|
if inspect.ismethod(cls.__init__):
|
|
spec = inspect.getargspec(cls.__init__)
|
|
|
|
if len(spec.args) > 2:
|
|
msg = 'Mach @CommandProvider class %s implemented incorrectly. ' + \
|
|
'__init__() must take 1 or 2 arguments. From %s'
|
|
msg = msg % (cls.__name__, inspect.getsourcefile(cls))
|
|
raise MachError(msg)
|
|
|
|
if len(spec.args) == 2:
|
|
pass_context = True
|
|
|
|
seen_commands = set()
|
|
|
|
# We scan __dict__ because we only care about the classes own attributes,
|
|
# not inherited ones. If we did inherited attributes, we could potentially
|
|
# define commands multiple times. We also sort keys so commands defined in
|
|
# the same class are grouped in a sane order.
|
|
for attr in sorted(cls.__dict__.keys()):
|
|
value = cls.__dict__[attr]
|
|
|
|
if not isinstance(value, types.FunctionType):
|
|
continue
|
|
|
|
command = getattr(value, '_mach_command', None)
|
|
if not command:
|
|
continue
|
|
|
|
# Ignore subcommands for now: we handle them later.
|
|
if command.subcommand:
|
|
continue
|
|
|
|
seen_commands.add(command.name)
|
|
|
|
if not command.conditions and Registrar.require_conditions:
|
|
continue
|
|
|
|
msg = 'Mach command \'%s\' implemented incorrectly. ' + \
|
|
'Conditions argument must take a list ' + \
|
|
'of functions. Found %s instead.'
|
|
|
|
if not isinstance(command.conditions, collections.Iterable):
|
|
msg = msg % (command.name, type(command.conditions))
|
|
raise MachError(msg)
|
|
|
|
for c in command.conditions:
|
|
if not hasattr(c, '__call__'):
|
|
msg = msg % (command.name, type(c))
|
|
raise MachError(msg)
|
|
|
|
command.cls = cls
|
|
command.method = attr
|
|
command.pass_context = pass_context
|
|
|
|
Registrar.register_command_handler(command)
|
|
|
|
# Now do another pass to get sub-commands. We do this in two passes so
|
|
# we can check the parent command existence without having to hold
|
|
# state and reconcile after traversal.
|
|
for attr in sorted(cls.__dict__.keys()):
|
|
value = cls.__dict__[attr]
|
|
|
|
if not isinstance(value, types.FunctionType):
|
|
continue
|
|
|
|
command = getattr(value, '_mach_command', None)
|
|
if not command:
|
|
continue
|
|
|
|
# It is a regular command.
|
|
if not command.subcommand:
|
|
continue
|
|
|
|
if command.name not in seen_commands:
|
|
raise MachError('Command referenced by sub-command does not '
|
|
'exist: %s' % command.name)
|
|
|
|
if command.name not in Registrar.command_handlers:
|
|
continue
|
|
|
|
command.cls = cls
|
|
command.method = attr
|
|
command.pass_context = pass_context
|
|
parent = Registrar.command_handlers[command.name]
|
|
|
|
if parent._parser:
|
|
raise MachError('cannot declare sub commands against a command '
|
|
'that has a parser installed: %s' % command)
|
|
if command.subcommand in parent.subcommand_handlers:
|
|
raise MachError('sub-command already defined: %s' % command.subcommand)
|
|
|
|
parent.subcommand_handlers[command.subcommand] = command
|
|
|
|
return cls
|
|
|
|
|
|
class Command(object):
|
|
"""Decorator for functions or methods that provide a mach command.
|
|
|
|
The decorator accepts arguments that define basic attributes of the
|
|
command. The following arguments are recognized:
|
|
|
|
category -- The string category to which this command belongs. Mach's
|
|
help will group commands by category.
|
|
|
|
description -- A brief description of what the command does.
|
|
|
|
parser -- an optional argparse.ArgumentParser instance or callable
|
|
that returns an argparse.ArgumentParser instance to use as the
|
|
basis for the command arguments.
|
|
|
|
For example:
|
|
|
|
@Command('foo', category='misc', description='Run the foo action')
|
|
def foo(self):
|
|
pass
|
|
"""
|
|
def __init__(self, name, **kwargs):
|
|
self._mach_command = _MachCommand(name=name, **kwargs)
|
|
|
|
def __call__(self, func):
|
|
if not hasattr(func, '_mach_command'):
|
|
func._mach_command = _MachCommand()
|
|
|
|
func._mach_command |= self._mach_command
|
|
|
|
return func
|
|
|
|
class SubCommand(object):
|
|
"""Decorator for functions or methods that provide a sub-command.
|
|
|
|
Mach commands can have sub-commands. e.g. ``mach command foo`` or
|
|
``mach command bar``. Each sub-command has its own parser and is
|
|
effectively its own mach command.
|
|
|
|
The decorator accepts arguments that define basic attributes of the
|
|
sub command:
|
|
|
|
command -- The string of the command this sub command should be
|
|
attached to.
|
|
|
|
subcommand -- The string name of the sub command to register.
|
|
|
|
description -- A textual description for this sub command.
|
|
"""
|
|
def __init__(self, command, subcommand, description=None):
|
|
self._mach_command = _MachCommand(name=command, subcommand=subcommand,
|
|
description=description)
|
|
|
|
def __call__(self, func):
|
|
if not hasattr(func, '_mach_command'):
|
|
func._mach_command = _MachCommand()
|
|
|
|
func._mach_command |= self._mach_command
|
|
|
|
return func
|
|
|
|
class CommandArgument(object):
|
|
"""Decorator for additional arguments to mach subcommands.
|
|
|
|
This decorator should be used to add arguments to mach commands. Arguments
|
|
to the decorator are proxied to ArgumentParser.add_argument().
|
|
|
|
For example:
|
|
|
|
@Command('foo', help='Run the foo action')
|
|
@CommandArgument('-b', '--bar', action='store_true', default=False,
|
|
help='Enable bar mode.')
|
|
def foo(self):
|
|
pass
|
|
"""
|
|
def __init__(self, *args, **kwargs):
|
|
if kwargs.get('nargs') == argparse.REMAINDER:
|
|
# These are the assertions we make in dispatcher.py about
|
|
# those types of CommandArguments.
|
|
assert len(args) == 1
|
|
assert all(k in ('default', 'nargs', 'help', 'group') for k in kwargs)
|
|
self._command_args = (args, kwargs)
|
|
|
|
def __call__(self, func):
|
|
if not hasattr(func, '_mach_command'):
|
|
func._mach_command = _MachCommand()
|
|
|
|
func._mach_command.arguments.insert(0, self._command_args)
|
|
|
|
return func
|
|
|
|
|
|
class CommandArgumentGroup(object):
|
|
"""Decorator for additional argument groups to mach commands.
|
|
|
|
This decorator should be used to add arguments groups to mach commands.
|
|
Arguments to the decorator are proxied to
|
|
ArgumentParser.add_argument_group().
|
|
|
|
For example:
|
|
|
|
@Command('foo', helps='Run the foo action')
|
|
@CommandArgumentGroup('group1')
|
|
@CommandArgument('-b', '--bar', group='group1', action='store_true',
|
|
default=False, help='Enable bar mode.')
|
|
def foo(self):
|
|
pass
|
|
|
|
The name should be chosen so that it makes sense as part of the phrase
|
|
'Command Arguments for <name>' because that's how it will be shown in the
|
|
help message.
|
|
"""
|
|
def __init__(self, group_name):
|
|
self._group_name = group_name
|
|
|
|
def __call__(self, func):
|
|
if not hasattr(func, '_mach_command'):
|
|
func._mach_command = _MachCommand()
|
|
|
|
func._mach_command.argument_group_names.insert(0, self._group_name)
|
|
|
|
return func
|
|
|
|
|
|
def SettingsProvider(cls):
|
|
"""Class decorator to denote that this class provides Mach settings.
|
|
|
|
When this decorator is encountered, the underlying class will automatically
|
|
be registered with the Mach registrar and will (likely) be hooked up to the
|
|
mach driver.
|
|
|
|
This decorator is only allowed on mach.config.ConfigProvider classes.
|
|
"""
|
|
if not issubclass(cls, ConfigProvider):
|
|
raise MachError('@SettingsProvider encountered on class that does ' +
|
|
'not derived from mach.config.ConfigProvider.')
|
|
|
|
Registrar.register_settings_provider(cls)
|
|
|
|
return cls
|
|
|