fedbiomed.common.validator

def is_valid(self) -> bool:
    """
    Status of the scheme passed at creation time.

    Returns:
        True if scheme is valid, False instead
    """
    return (self._scheme is not None) or self._is_valid

def populate_with_defaults(self, value: Dict, only_required: bool = True) -> Dict:
    """
    Inject default values defined in the rule to a given dictionary.

    Parse the given json value and add default value if key was required
    but not provided.
    Of course, the default values must be provided in the scheme.

    Warning: this does not parse the result against the scheme. It has
    to be done by the user.

    Args:
        value (dict):   a json data to verify/populate
        only_required (bool): if True, only force required key. If False, update all
                       keys with default values in the scheme. Defaults to True.

    Returns:
        (dict) a json populated with default values, returns an empty dict if something is wrong

    Raises:
        RuleError: if scheme provided at init contains a required rules without default value
        ValidatorError: if input value was not a dict
    """
    if not self.is_valid():  # pragma: no cover
        return {}

    # check the value against the scheme
    if isinstance(value, dict):
        result = deepcopy(value)
    else:
        raise ValidatorError("input value is not a dict")


    for k, v in self._scheme.items():
        if 'required' in v and v['required'] is True:

            if k in value:
                result[k] = value[k]
            else:
                if 'default' in v:
                    result[k] = v['default']
                else:
                    raise RuleError(f"scheme does not define a default value for required key: {k}")

        else:
            if not only_required:
                if k in value:
                    result[k] = value[k]
                else:
                    if 'default' in v:
                        result[k] = v['default']


    return result

def scheme(self) -> Dict[str, Dict]:
    """
    Scheme getter.

    Returns:
        scheme passed at __init__ if valid, None instead
    """
    return self._scheme

def validate(self, value: Dict) -> bool:
    """
    Validate a value against the scheme passed at creation time.

    Args:
         value (dict):  value (dict) to validate against the scheme passed
                 at __init__
    Returns:
        True if value is valid

    Raises:
        ValidateError: if provided value is invalid
    """
    # TODO: raises error messages
    # or store error string in self._error and provide a error() method
    if not self.is_valid():  # pragma: no cover
        return False

    if not isinstance(value, dict):
        raise ValidateError("value is not a dict")

    # check the value against the scheme
    for k, v in self._scheme.items():
        if 'required' in v and v['required'] is True and k not in value:
            raise ValidateError(f"{k} key is required")

    for k in value:
        if k not in self._scheme:
            raise ValidateError(f"undefined key ({k}) in scheme")

        for hook in self._scheme[k]['rules']:
            if not Validator().validate(value[k], hook):
                # this should already have raised an error
                raise ValidateError(f"invalid value ({value[k]}) for key: {k}")  # pragma: nocover

    return True

def delete(self, rule: str) -> None:
    """
    Delete a rule from the rulebook.

    Args:
        rule:   name (string) of a possibly registered hook
    """
    if rule in self._validation_rulebook:
        del self._validation_rulebook[rule]

def is_known_rule(self, rule: str) -> bool:
    """
    Information about rule registration.

    Args:
        rule:   name [`str`][str] of a possibly registered hook

    Returns:
        True if rule is registered, False instead
    """
    return rule in self._validation_rulebook

def register(self, rule: str, hook: Any, override: bool = False) -> bool:
    """
    Add a rule/validation_function to the rulebook.

    if the rule (entry of the catalog) was already registered,
    it will be rejected, except if override is True

    Args:
        rule:      registration name (string)
        hook:      validation hook to register (the hook is checked against
                   the accepted hook types)
        override:  if True, still register the rule even if it existed. Defaults to False.

    Returns:
        True if rule is accepted, False instead if rule exists and overrride is False

    Raises:
        RuleError: if provided rule name or hook is invalid

    """
    if not isinstance(rule, str):
        raise RuleError("rule name must be a string")

    if not override and rule in self._validation_rulebook:
        sys.stdout.write(f"WARNING - Validator: rule is already registered: {rule} \n")
        return False

    if not Validator._is_hook_type_valid(hook):
        raise RuleError("action associated to the rule is not allowed")

    # hook is a dict, we transform it to a SchemeValidator
    if isinstance(hook, dict):
        try:
            sv = SchemeValidator(hook)
        except RuleError as e:
            raise RuleError(f"validator is an invalid dict: {e}")
        hook = sv

    # rule description is valid -> register it
    self._validation_rulebook[rule] = hook
    return True

def rule(self, rule: str) -> Union[str, None]:
    """
    Return a presumably stored rule.

    Args:
        rule:   name ([`str`][str]) of a possibly registered hook

    Returns:
        the hook associated to the rule name if registered, None if not registered
    """
    if rule in self._validation_rulebook:
        return self._validation_rulebook[rule]
    else:
        return None

def validate(self, value: Any, rule: Any, strict: bool = True) -> bool:
    """
    Validate a value against a validation rule.

    The rule may be one of:
    - (registered) rule
    - a provided function,
    - a simple type checking
    - a SchemeValidator

    Args:
        value:   value to check
        rule:    validation hook (registered name, typecheck, direct hook, ...)
        strict:  Raises error if rule is not defined. Otherwise, prints a warning message.
    Returns:
        True if rule exists and value is compliant.

    Raises:
        ValidateError: if provided value does not comply to the rule
    """
    # rule is in the rulebook -> execute the rule associated function
    if isinstance(rule, str) and rule in self._validation_rulebook:

        status, error = Validator._hook_execute(value,
                                                self._validation_rulebook[rule])
        if not status:
            raise ValidateError(error)

        return status

    # rule is an unknown string
    if isinstance(rule, str):
        if strict:
            raise ValidateError(f"unknown rule: {rule}")
        else:
            sys.stdout.write(f"WARNING - Validator(): unknown rule: {rule} \n")
            return True

    # consider the rule as a direct rule definition
    status, error = Validator._hook_execute(value, rule)

    if not status:
        raise ValidateError(error)

    return status