tiramisu/tiramisu/option.py

# -*- coding: utf-8 -*-
"option types and option description for the configuration management"
# Copyright (C) 2012-2013 Team tiramisu (see AUTHORS for all contributors)
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program 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 General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
# The original `Config` design model is unproudly borrowed from
# the rough pypy's guys: http://codespeak.net/svn/pypy/dist/pypy/config/
# the whole pypy projet is under MIT licence
# ____________________________________________________________
import re
from copy import copy, deepcopy
from types import FunctionType
from IPy import IP

from tiramisu.error import ConflictError
from tiramisu.setting import groups, multitypes
from tiramisu.i18n import _
from tiramisu.autolib import carry_out_calculation

name_regexp = re.compile(r'^\d+')
forbidden_names = ('iter_all', 'iter_group', 'find', 'find_first',
                   'make_dict', 'unwrap_from_path', 'read_only',
                   'read_write', 'getowner', 'set_contexts')


def valid_name(name):
    "an option's name is a str and does not start with 'impl' or 'cfgimpl'"
    try:
        name = str(name)
    except:
        return False
    if re.match(name_regexp, name) is None and not name.startswith('_') \
            and name not in forbidden_names \
            and not name.startswith('impl_') \
            and not name.startswith('cfgimpl_'):
        return True
    else:
        return False
#____________________________________________________________
#


class BaseInformation(object):
    "interface for an option's information attribute"
    __slots__ = ('_impl_informations',)

    def impl_set_information(self, key, value):
        """updates the information's attribute
        (wich is a dictionnary)

        :param key: information's key (ex: "help", "doc"
        :param value: information's value (ex: "the help string")
        """
        try:
            self._impl_informations[key] = value
        except AttributeError:
            raise AttributeError(_('{0} instance has no attribute '
                                   'impl_set_information').format(self.__class__.__name__))

    def impl_get_information(self, key, default=None):
        """retrieves one information's item

        :param key: the item string (ex: "help")
        """
        try:
            if key in self._impl_informations:
                return self._impl_informations[key]
            elif default is not None:
                return default
            else:
                raise ValueError(_("Information's item not found: {0}").format(key))
        except AttributeError:
            raise AttributeError(_('{0} instance has no attribute '
                                   'impl_get_information').format(self.__class__.__name__))


class Option(BaseInformation):
    """
    Abstract base class for configuration option's.

    Reminder: an Option object is **not** a container for the value
    """
    __slots__ = ('_name', '_requires', '_multi', '_validator', '_default_multi',
                 '_default', '_properties', '_callback', '_multitype',
                 '_master_slaves', '_consistencies', '_empty')
    _empty = ''

    def __init__(self, name, doc, default=None, default_multi=None,
                 requires=None, multi=False, callback=None,
                 callback_params=None, validator=None, validator_args=None,
                 properties=None):
        """
        :param name: the option's name
        :param doc: the option's description
        :param default: specifies the default value of the option,
                        for a multi : ['bla', 'bla', 'bla']
        :param default_multi: 'bla' (used in case of a reset to default only at
                        a given index)
        :param requires: is a list of names of options located anywhere
                         in the configuration.
        :param multi: if true, the option's value is a list
        :param callback: the name of a function. If set, the function's output
                         is responsible of the option's value
        :param callback_params: the callback's parameter
        :param validator: the name of a function wich stands for a custom
                          validation of the value
        :param validator_args: the validator's parameters

        """
        if not valid_name(name):
            raise ValueError(_("invalid name: {0} for option").format(name))
        self._name = name
        self._impl_informations = {}
        self.impl_set_information('doc', doc)
        requires = validate_requires_arg(requires, self._name)
        self._requires = requires
        self._multi = multi
        self._consistencies = None
        if validator is not None:
            if type(validator) != FunctionType:
                raise TypeError(_("validator must be a function"))
            if validator_args is None:
                validator_args = {}
            self._validator = (validator, validator_args)
        else:
            self._validator = None
        if not self._multi and default_multi is not None:
            raise ValueError(_("a default_multi is set whereas multi is False"
                             " in option: {0}").format(name))
        if default_multi is not None and not self._validate(default_multi):
            raise ValueError(_("invalid default_multi value {0} "
                             "for option {1}").format(str(default_multi), name))
        if callback is not None and (default is not None or default_multi is not None):
            raise ValueError(_("defaut values not allowed if option: {0} "
                             "is calculated").format(name))
        if callback is None and callback_params is not None:
            raise ValueError(_("params defined for a callback function but "
                             "no callback defined yet for option {0}").format(name))
        if callback is not None:
            if type(callback) != FunctionType:
                raise ValueError('callback must be a function')
            if callback_params is not None and \
                    not isinstance(callback_params, dict):
                raise ValueError('callback_params must be a dict')
            self._callback = (callback, callback_params)
        else:
            self._callback = None
        if self._multi:
            if default is None:
                default = []
            self._multitype = multitypes.default
            self._default_multi = default_multi
        self.impl_validate(default)
        self._default = default
        if properties is None:
            properties = tuple()
        if not isinstance(properties, tuple):
            raise TypeError(_('invalid properties type {0} for {1},'
                            ' must be a tuple').format(type(properties), self._name))
        self._properties = set(properties)  # 'hidden', 'disabled'...

    def __eq__(self, other):
        "Option comparison"
        if not isinstance(other, Option):
            return False
        slots = list(self.__slots__ + Option.__slots__ + BaseInformation.__slots__)
        for var in slots:
            try:
                val1 = getattr(self, var)
                not_in1 = False
            except:
                not_in1 = True
            try:
                val2 = getattr(other, var)
                not_in2 = False
            except:
                not_in2 = True
            if True in (not_in1, not_in2):
                if not_in1 != not_in2:
                    return False
            elif val1 != val2:
                return False
        return True

    def __ne__(self, other):
        if not isinstance(other, Option):
            return False
        return not self == other

    def _launch_consistency(self, func, opt, vals, context, index, opt_):
        if context is not None:
            descr = context.cfgimpl_get_description()
        if opt is self:
            #values are for self, search opt_ values
            values = vals
            if context is not None:
                path = descr.impl_get_path_by_opt(opt_)
                values_ = context._getattr(path, validate=False)
            else:
                values_ = opt_.impl_getdefault()
            if index is not None:
                #value is not already set, could be higher
                try:
                    values_ = values_[index]
                except IndexError:
                    values_ = None
        else:
            #values are for opt_, search self values
            values_ = vals
            if context is not None:
                path = descr.impl_get_path_by_opt(self)
                values = context._getattr(path, validate=False)
            else:
                values = self.impl_getdefault()
            if index is not None:
                #value is not already set, could be higher
                try:
                    values = values[index]
                except IndexError:
                    values = None
        if index is None and self.impl_is_multi():
            for index in range(0, len(values)):
                try:
                    value = values[index]
                    value_ = values_[index]
                except IndexError:
                    value = None
                    value_ = None
                if None not in (value, value_):
                    getattr(self, func)(opt_._name, value, value_)
        else:
            if None not in (values, values_):
                getattr(self, func)(opt_._name, values, values_)

    def impl_validate(self, value, context=None, validate=True):
        """
        :param value: the option's value
        :param validate: if true enables ``self._validator`` validation
        """
        if not validate:
            return

        def _val_validator(val):
            callback_params = deepcopy(self._validator[1])
            callback_params.setdefault('', []).insert(0, val)
            return carry_out_calculation(self._name, config=context,
                                         callback=self._validator[0],
                                         callback_params=callback_params)

        def val_validator():
            #add current value has first argument
            if self.impl_is_multi():
                for val in value:
                    if not _val_validator(val):
                        return False
                return True
            else:
                return _val_validator(value)

        # generic calculation
        if context is not None:
            descr = context.cfgimpl_get_description()
        if not self._multi:
            if value is not None and ((self._validator is not None and
                                       not val_validator()) or
                                      not self._validate(value)):
                raise ValueError(_("invalid value {0} for option {1}"
                                   "").format(value, self._name))
            if context is not None:
                descr._valid_consistency(self, value, context, None)
        else:
            if not isinstance(value, list):
                raise ValueError(_("invalid value {0} for option {1} "
                                   "which must be a list").format(value,
                                                                  self._name))
            for index in range(0, len(value)):
                val = value[index]
                if val is not None and ((self._validator is not None and
                                         not val_validator()) or
                                        not self._validate(val)):
                        raise ValueError(_("invalid value {0} for option {1}"
                                           "").format(value, self._name))
                if context is not None:
                    descr._valid_consistency(self, val, context, index)

    def impl_getdefault(self, default_multi=False):
        "accessing the default value"
        if not default_multi or not self.impl_is_multi():
            return self._default
        else:
            return self.getdefault_multi()

    def impl_getdefault_multi(self):
        "accessing the default value for a multi"
        return self._default_multi

    def impl_get_multitype(self):
        return self._multitype

    def impl_get_master_slaves(self):
        return self._master_slaves

    def impl_is_empty_by_default(self):
        "no default value has been set yet"
        if ((not self.impl_is_multi() and self._default is None) or
                (self.impl_is_multi() and (self._default == [] or None in self._default))):
            return True
        return False

    def impl_getdoc(self):
        "accesses the Option's doc"
        return self.impl_get_information('doc')

    def impl_has_callback(self):
        "to know if a callback has been defined or not"
        if self._callback is None:
            return False
        else:
            return True

    def impl_getkey(self, value):
        return value

    def impl_is_multi(self):
        return self._multi

    def impl_add_consistency(self, func, opt):
        if self._consistencies is None:
            self._consistencies = []
        if not isinstance(opt, Option):
            raise ValueError('consistency must be set with an option')
        if self is opt:
            raise ValueError('cannot add consistency with itself')
        if self.impl_is_multi() != opt.impl_is_multi():
            raise ValueError('options in consistency should be multi in two sides')
        func = '_cons_{0}'.format(func)
        self._launch_consistency(func, self, self.impl_getdefault(), None, None, opt)
        self._consistencies.append((func, opt))
        self.impl_validate(self.impl_getdefault())

    def _cons_not_equal(self, optname, value, value_):
        if value == value_:
            raise ValueError(_("invalid value {0} for option {1} "
                               "must be different as {2} option"
                               "").format(value, self._name, optname))


class ChoiceOption(Option):
    """represents a choice out of several objects.

    The option can also have the value ``None``
    """

    __slots__ = ('_values', '_open_values', '_opt_type')
    _opt_type = 'string'

    def __init__(self, name, doc, values, default=None, default_multi=None,
                 requires=None, multi=False, callback=None,
                 callback_params=None, open_values=False, validator=None,
                 validator_args=None, properties=()):
        """
        :param values: is a list of values the option can possibly take
        """
        if not isinstance(values, tuple):
            raise TypeError(_('values must be a tuple for {0}').format(name))
        self._values = values
        if open_values not in (True, False):
            raise TypeError(_('open_values must be a boolean for '
                            '{0}').format(name))
        self._open_values = open_values
        super(ChoiceOption, self).__init__(name, doc, default=default,
                                           default_multi=default_multi,
                                           callback=callback,
                                           callback_params=callback_params,
                                           requires=requires,
                                           multi=multi,
                                           validator=validator,
                                           validator_args=validator_args,
                                           properties=properties)

    def impl_get_values(self):
        return self._values

    def impl_is_openvalues(self):
        return self._open_values

    def _validate(self, value):
        if not self._open_values:
            return value is None or value in self._values
        else:
            return True


class BoolOption(Option):
    "represents a choice between ``True`` and ``False``"
    __slots__ = ('_opt_type',)
    _opt_type = 'bool'

    def _validate(self, value):
        return isinstance(value, bool)


class IntOption(Option):
    "represents a choice of an integer"
    __slots__ = ('_opt_type',)
    _opt_type = 'int'

    def _validate(self, value):
        return isinstance(value, int)


class FloatOption(Option):
    "represents a choice of a floating point number"
    __slots__ = ('_opt_type',)
    _opt_type = 'float'

    def _validate(self, value):
        return isinstance(value, float)


class StrOption(Option):
    "represents the choice of a string"
    __slots__ = ('_opt_type',)
    _opt_type = 'string'

    def _validate(self, value):
        return isinstance(value, str)


class UnicodeOption(Option):
    "represents the choice of a unicode string"
    __slots__ = ('_opt_type',)
    _opt_type = 'unicode'
    _empty = u''

    def _validate(self, value):
        return isinstance(value, unicode)


class SymLinkOption(object):
    __slots__ = ('_name', '_opt', '_consistencies')
    _opt_type = 'symlink'
    _consistencies = None

    def __init__(self, name, opt):
        self._name = name
        if not isinstance(opt, Option):
            raise ValueError(_('malformed symlinkoption '
                               'must be an option for symlink {0}').format(name))
        self._opt = opt

    def __getattr__(self, name):
        if name in ('_name', '_opt', '_consistencies'):
            return object.__gettattr__(self, name)
        else:
            return getattr(self._opt, name)


class IPOption(Option):
    "represents the choice of an ip"
    __slots__ = ('_opt_type', '_only_private')
    _opt_type = 'ip'

    def __init__(self, name, doc, default=None, default_multi=None,
                 requires=None, multi=False, callback=None,
                 callback_params=None, validator=None, validator_args=None,
                 properties=None, only_private=False):
        super(IPOption, self).__init__(name, doc, default=default,
                                       default_multi=default_multi,
                                       callback=callback,
                                       callback_params=callback_params,
                                       requires=requires,
                                       multi=multi,
                                       validator=validator,
                                       validator_args=validator_args,
                                       properties=properties)
        self._only_private = only_private

    def _validate(self, value):
        try:
            ip = IP('{0}/32'.format(value))
            if self._only_private:
                return ip.iptype() == 'PRIVATE'
            return True
        except ValueError:
            return False


class NetworkOption(Option):
    "represents the choice of a network"
    __slots__ = ('_opt_type',)
    _opt_type = 'network'

    def _validate(self, value):
        try:
            IP(value)
            return True
        except ValueError:
            return False


class NetmaskOption(Option):
    "represents the choice of a netmask"
    __slots__ = ('_opt_type',)
    _opt_type = 'netmask'

    def _validate(self, value):
        try:
            IP('0.0.0.0/{0}'.format(value))
            return True
        except ValueError:
            return False

    def _cons_network_netmask(self, optname, value, value_):
        #opts must be (netmask, network) options
        self.__cons_netmask(optname, value, value_, False)

    def _cons_ip_netmask(self, optname, value, value_):
        #opts must be (netmask, ip) options
        self.__cons_netmask(optname, value, value_, True)

    #def __cons_netmask(self, opt, value, context, index, opts, make_net):
    def __cons_netmask(self, optname, val_netmask, val_ipnetwork, make_net):
        msg = None
        try:
            ip = IP('{0}/{1}'.format(val_ipnetwork, val_netmask),
                    make_net=make_net)
            #if cidr == 32, ip same has network
            if ip.prefixlen() != 32:
                try:
                    IP('{0}/{1}'.format(val_ipnetwork, val_netmask),
                        make_net=not make_net)
                except ValueError:
                    if not make_net:
                        msg = _("invalid network {0} ({1}) with netmask {2} ({3}),"
                                " this network is an ip")
                else:
                    if make_net:
                        msg = _("invalid ip {0} ({1}) with netmask {2} ({3}),"
                                " this ip is a network")

        except ValueError:
            if make_net:
                msg = _("invalid ip {0} ({1}) with netmask {2} ({3})")
            else:
                msg = _("invalid network {0} ({1}) with netmask {2} ({3})")
        if msg is not None:
            raise ValueError(msg.format(val_ipnetwork, optname,
                                        val_netmask, self._name))


class DomainnameOption(Option):
    "represents the choice of a domain name"
    __slots__ = ('_opt_type', '_type', '_allow_ip')
    _opt_type = 'domainname'

    def __init__(self, name, doc, default=None, default_multi=None,
                 requires=None, multi=False, callback=None,
                 callback_params=None, validator=None, validator_args=None,
                 properties=None, allow_ip=False, type_='domainname'):
        #netbios: for MS domain
        #hostname: to identify the device
        #domainname:
        #fqdn: with tld, not supported yet
        if type_ not in ['netbios', 'hostname', 'domainname']:
            raise ValueError(_('unknown type_ {0} for hostname').format(type_))
        self._type = type_
        if allow_ip not in [True, False]:
            raise ValueError(_('allow_ip must be a boolean'))
        self._allow_ip = allow_ip
        super(DomainnameOption, self).__init__(name, doc, default=default,
                                               default_multi=default_multi,
                                               callback=callback,
                                               callback_params=callback_params,
                                               requires=requires,
                                               multi=multi,
                                               validator=validator,
                                               validator_args=validator_args,
                                               properties=properties)

    def _validate(self, value):
        if self._allow_ip is True:
            try:
                IP('{0}/32'.format(value))
                return True
            except ValueError:
                pass
        if self._type == 'netbios':
            length = 15
            extrachar = ''
        elif self._type == 'hostname':
            length = 63
            extrachar = ''
        elif self._type == 'domainname':
            length = 255
            extrachar = '\.'
            if '.' not in value:
                raise ValueError(_("invalid value for {0}, must have dot"
                                   "").format(self._name))
        if len(value) > length:
            raise ValueError(_("invalid value's length for {0} (max {1})"
                               "").format(self._name, length))
        regexp = r'^[a-z]([a-z\d{0}-])*[a-z\d]$'.format(extrachar)
        return re.match(regexp, value) is not None


class OptionDescription(BaseInformation):
    """Config's schema (organisation, group) and container of Options
    The `OptionsDescription` objects lives in the `tiramisu.config.Config`.
    """
    __slots__ = ('_name', '_requires', '_cache_paths', '_group_type',
                 '_properties', '_children', '_consistencies')

    def __init__(self, name, doc, children, requires=None, properties=None):
        """
        :param children: a list of options (including option descriptions)

        """
        if not valid_name(name):
            raise ValueError(_("invalid name: {0} for option descr").format(name))
        self._name = name
        self._impl_informations = {}
        self.impl_set_information('doc', doc)
        child_names = [child._name for child in children]
        #better performance like this
        valid_child = copy(child_names)
        valid_child.sort()
        old = None
        for child in valid_child:
            if id(child) == id(old):
                raise ConflictError(_('duplicate option name: '
                                      '{0}').format(child))
            old = child
        self._children = (tuple(child_names), tuple(children))
        requires = validate_requires_arg(requires, self._name)
        self._requires = requires
        self._cache_paths = None
        self._consistencies = None
        if properties is None:
            properties = tuple()
        if not isinstance(properties, tuple):
            raise TypeError(_('invalid properties type {0} for {1},'
                              ' must be a tuple').format(type(properties), self._name))
        self._properties = set(properties)  # 'hidden', 'disabled'...
        # the group_type is useful for filtering OptionDescriptions in a config
        self._group_type = groups.default

    def impl_getdoc(self):
        return self.impl_get_information('doc')

    def __getattr__(self, name):
        try:
            return self._children[1][self._children[0].index(name)]
        except ValueError:
            raise AttributeError(_('unknown Option {0} in OptionDescription {1}'
                                 '').format(name, self._name))

    def impl_getkey(self, config):
        return tuple([child.impl_getkey(getattr(config, child._name))
                      for child in self.impl_getchildren()])

    def impl_getpaths(self, include_groups=False, _currpath=None):
        """returns a list of all paths in self, recursively
           _currpath should not be provided (helps with recursion)
        """
        if _currpath is None:
            _currpath = []
        paths = []
        for option in self.impl_getchildren():
            attr = option._name
            if isinstance(option, OptionDescription):
                if include_groups:
                    paths.append('.'.join(_currpath + [attr]))
                paths += option.impl_getpaths(include_groups=include_groups,
                                              _currpath=_currpath + [attr])
            else:
                paths.append('.'.join(_currpath + [attr]))
        return paths

    def impl_getchildren(self):
        return self._children[1]

    def impl_build_cache(self, cache_path=None, cache_option=None, _currpath=None, _consistencies=None):
        if _currpath is None and self._cache_paths is not None:
            return
        if _currpath is None:
            save = True
            _currpath = []
            _consistencies = {}
        else:
            save = False
        if cache_path is None:
            cache_path = [self._name]
            cache_option = [self]
        for option in self.impl_getchildren():
            attr = option._name
            if attr.startswith('_cfgimpl'):
                continue
            cache_option.append(option)
            cache_path.append(str('.'.join(_currpath + [attr])))
            if not isinstance(option, OptionDescription):
                if option._consistencies is not None:
                    for consistency in option._consistencies:
                        func, opt = consistency
                        opts = (option, opt)
                        _consistencies.setdefault(opt, []).append((func, opts))
                        _consistencies.setdefault(option, []).append((func, opts))
            else:
                _currpath.append(attr)
                option.impl_build_cache(cache_path, cache_option, _currpath, _consistencies)
                _currpath.pop()
        if save:
            #valid no duplicated option
            valid_child = copy(cache_option)
            valid_child.sort()
            old = None
            for child in valid_child:
                if id(child) == id(old):
                    raise ConflictError(_('duplicate option: '
                                          '{0}').format(child))
                old = child
            self._cache_paths = (tuple(cache_option), tuple(cache_path))
            self._consistencies = _consistencies

    def impl_get_opt_by_path(self, path):
        try:
            return self._cache_paths[0][self._cache_paths[1].index(path)]
        except ValueError:
            raise AttributeError(_('no option for path {0}').format(path))

    def impl_get_path_by_opt(self, opt):
        try:
            return self._cache_paths[1][self._cache_paths[0].index(opt)]
        except ValueError:
            raise AttributeError(_('no option {0} found').format(opt))

    # ____________________________________________________________
    def impl_set_group_type(self, group_type):
        """sets a given group object to an OptionDescription

        :param group_type: an instance of `GroupType` or `MasterGroupType`
                              that lives in `setting.groups`
        """
        if self._group_type != groups.default:
            raise TypeError(_('cannot change group_type if already set '
                            '(old {0}, new {1})').format(self._group_type, group_type))
        if isinstance(group_type, groups.GroupType):
            self._group_type = group_type
            if isinstance(group_type, groups.MasterGroupType):
                #if master (same name has group) is set
                identical_master_child_name = False
                #for collect all slaves
                slaves = []
                master = None
                for child in self.impl_getchildren():
                    if isinstance(child, OptionDescription):
                        raise ValueError(_("master group {0} shall not have "
                                         "a subgroup").format(self._name))
                    if isinstance(child, SymLinkOption):
                        raise ValueError(_("master group {0} shall not have "
                                         "a symlinkoption").format(self._name))
                    if not child.impl_is_multi():
                        raise ValueError(_("not allowed option {0} in group {1}"
                                         ": this option is not a multi"
                                         "").format(child._name, self._name))
                    if child._name == self._name:
                        identical_master_child_name = True
                        child._multitype = multitypes.master
                        master = child
                    else:
                        slaves.append(child)
                if master is None:
                    raise ValueError(_('master group with wrong master name for {0}'
                                     '').format(self._name))
                master._master_slaves = tuple(slaves)
                for child in self.impl_getchildren():
                    if child != master:
                        child._master_slaves = master
                        child._multitype = multitypes.slave
                if not identical_master_child_name:
                    raise ValueError(_("the master group: {0} has not any "
                                     "master child").format(self._name))
        else:
            raise ValueError(_('not allowed group_type : {0}').format(group_type))

    def impl_get_group_type(self):
        return self._group_type

    def _valid_consistency(self, opt, value, context=None, index=None):
        consistencies = self._consistencies.get(opt)
        if consistencies is not None:
            for consistency in consistencies:
                opt_ = consistency[1]
                ret = opt_[0]._launch_consistency(consistency[0], opt, value, context,
                                                  index, opt_[1])
                if ret is False:
                    return False
        return True


def validate_requires_arg(requires, name):
    """check malformed requirements
    and tranform dict to internal tuple
    """
    if requires is None:
        return None
    ret_requires = {}
    config_action = {}

    for require in requires:
        if not type(require) == dict:
            raise ValueError(_("malformed requirements type for option:"
                               " {0}, must be a dict").format(name))
        valid_keys = ('option', 'expected', 'action', 'inverse', 'transitive',
                      'same_action')
        unknown_keys = frozenset(require.keys()) - frozenset(valid_keys)
        if unknown_keys != frozenset():
            raise ValueError('malformed requirements for option: {0}'
                             ' unknown keys {1}, must only '
                             '{2}'.format(name,
                                          unknown_keys,
                                          valid_keys))
        try:
            option = require['option']
            expected = require['expected']
            action = require['action']
        except KeyError:
            raise ValueError(_("malformed requirements for option: {0}"
                               " require must have option, expected and"
                               " action keys").format(name))
        inverse = require.get('inverse', False)
        if inverse not in [True, False]:
            raise ValueError(_('malformed requirements for option: {0}'
                               ' inverse must be boolean'))
        transitive = require.get('transitive', True)
        if transitive not in [True, False]:
            raise ValueError(_('malformed requirements for option: {0}'
                               ' transitive must be boolean'))
        same_action = require.get('same_action', True)
        if same_action not in [True, False]:
            raise ValueError(_('malformed requirements for option: {0}'
                               ' same_action must be boolean'))

        if not isinstance(option, Option):
            raise ValueError(_('malformed requirements first argument '
                               'must be an option in option {0}').format(name))
        if option.impl_is_multi():
            raise ValueError(_('malformed requirements option {0} '
                               'should not be a multi').format(name))
        if expected is not None and not option._validate(expected):
            raise ValueError(_('malformed requirements second argument '
                               'must be valid for option {0}').format(name))
        if action in config_action:
            if inverse != config_action[action]:
                raise ValueError(_("inconsistency in action types for option: {0}"
                                   " action: {1}").format(name, action))
        else:
            config_action[action] = inverse

        ret_requires.setdefault(action, []).append((option, expected, action,
                                                    inverse, transitive, same_action))

    return tuple(tuple(ret) for ret in ret_requires.values())