src.fairreckitlib.core.config.config_base_param

  1"""This module contains functionality for base configuration parameters.
  2
  3Classes:
  4
  5    ConfigParam: base class for all parameters.
  6    ConfigOptionParam: (base) parameter that can be a value from a known list of options.
  7    ConfigValueParam: (base) parameter that can be a value between a minimum and maximum.
  8
  9This program has been developed by students from the bachelor Computer Science at
 10Utrecht University within the Software Project course.
 11© Copyright Utrecht University (Department of Information and Computing Sciences)
 12"""
 13
 14from abc import ABCMeta, abstractmethod
 15from typing import Any, Dict, List, Tuple, Type, Union
 16
 17PARAM_KEY_NAME = 'name'
 18PARAM_KEY_DEFAULT = 'default'
 19PARAM_KEY_MIN = 'min'
 20PARAM_KEY_MAX = 'max'
 21PARAM_KEY_OPTIONS = 'options'
 22PARAM_KEY_VALUES = 'values'
 23
 24
 25class ConfigParam(metaclass=ABCMeta):
 26    """Config Param base class.
 27
 28    Public methods:
 29
 30    to_dict
 31    validate_value
 32    """
 33
 34    def __init__(self, name: str, value_type: Type, default_value: Any):
 35        """Construct the ConfigParam.
 36
 37        Args:
 38            name: the name of the parameter.
 39            value_type: the type of the parameter.
 40            default_value: the default value of the parameter.
 41        """
 42        self.name = name
 43        self.value_type = value_type
 44        self.default_value = default_value
 45
 46    @abstractmethod
 47    def to_dict(self) -> Dict[str, Any]:
 48        """Get a dictionary describing the parameter.
 49
 50        The dictionary should at least contains keys for the name
 51        and default value of the parameter.
 52
 53        Returns:
 54            the dictionary containing the parameter descriptions.
 55        """
 56        raise NotImplementedError()
 57
 58    @abstractmethod
 59    def validate_value(self, value: Any) -> Tuple[bool, Any, str]:
 60        """Validate the specified value with the parameter.
 61
 62        Derived implementations should at least check for type mismatch and None.
 63
 64        Args:
 65            value: the value to verify with the parameter.
 66
 67        Returns:
 68            whether it was successful, the validated value and (optional) message.
 69        """
 70        raise NotImplementedError()
 71
 72
 73class ConfigOptionParam(ConfigParam, metaclass=ABCMeta):
 74    """Config Option Parameter.
 75
 76    The default_value and all the options are expected to be of the same value_type.
 77    The default_value is expected to be present in the list of available options.
 78    """
 79
 80    def __init__(
 81            self,
 82            name: str,
 83            value_type: Type,
 84            default_value: Any,
 85            options: List[Any]):
 86        """Construct the ConfigOptionParam.
 87
 88        Args:
 89            name: the name of the parameter.
 90            value_type: the type of the parameter.
 91            default_value: the default option of the parameter.
 92            options: list of available options for the parameter.
 93        """
 94        ConfigParam.__init__(self, name, value_type, default_value)
 95        self.options = options
 96
 97    def to_dict(self) -> Dict[str, Any]:
 98        """Get a dictionary describing the option parameter.
 99
100        The dictionary contains keys for the name, default value
101        and options of the parameter.
102
103        Returns:
104            the dictionary containing the parameter descriptions.
105        """
106        return {
107            PARAM_KEY_NAME: self.name,
108            PARAM_KEY_OPTIONS: self.options,
109            PARAM_KEY_DEFAULT: self.default_value
110        }
111
112
113class ConfigValueParam(ConfigParam, metaclass=ABCMeta):
114    """Config Value Parameter.
115
116    The value_type of default_value and min_max_value types are all expected to be either
117    int or float, conversions between the two during validation is available.
118    The default_value is expected to be between the min_max_value.
119    The min_max_value is expected to have min_value <= max_value.
120    """
121
122    def __init__(
123            self,
124            name: str,
125            value_type: Type,
126            default_value: Any,
127            min_max_value: Union[Tuple[int, int], Tuple[float, float]]):
128        """Construct the ConfigValueParam.
129
130        Args:
131            name: the name of the parameter.
132            value_type: the type of the parameter.
133            default_value: the default value of the parameter.
134            min_max_value: tuple with the minimum and maximum value of the parameter.
135        """
136        ConfigParam.__init__(self, name, value_type, default_value)
137        self.min_value = min_max_value[0]
138        self.max_value = min_max_value[1]
139
140    def to_dict(self) -> Dict[str, Any]:
141        """Get a dictionary describing the value parameter.
142
143        The dictionary contains keys for the name, default value,
144        minimum value and maximum value of the parameter.
145
146        Returns:
147            the dictionary containing the parameter descriptions.
148        """
149        return {
150            PARAM_KEY_NAME: self.name,
151            PARAM_KEY_MIN: self.min_value,
152            PARAM_KEY_MAX: self.max_value,
153            PARAM_KEY_DEFAULT: self.default_value
154        }