src.fairreckitlib.core.config.config_value_param

  1"""This module contains functionality for configuration value parameters.
  2
  3Classes:
  4
  5    ConfigNumberParam: parameter that can be a number between a minimum and maximum.
  6    ConfigRandomParam: parameter that can be used to pick the (optional) random seed.
  7    ConfigRangeParam: parameter that can be a range between a minimum and maximum.
  8
  9Functions:
 10
 11    validate_min_max:
 12    validate_type:
 13
 14This program has been developed by students from the bachelor Computer Science at
 15Utrecht University within the Software Project course.
 16© Copyright Utrecht University (Department of Information and Computing Sciences)
 17"""
 18
 19import sys
 20from typing import Any, Dict, Optional, Tuple, Type, Union
 21
 22from .config_base_param import ConfigValueParam, PARAM_KEY_MIN, PARAM_KEY_MAX
 23
 24
 25class ConfigNumberParam(ConfigValueParam):
 26    """Config Number Parameter.
 27
 28    The value_type of default_value and min_max_value types are all expected to be either
 29    int or float, conversions between the two during validation is available.
 30    The default_value is expected to be between the min_max_value.
 31    The min_max_value is expected to have min_value <= max_value.
 32    """
 33
 34    def __init__(
 35            self,
 36            name: str,
 37            value_type: Type,
 38            default_value: Union[int, float],
 39            min_max_value: Union[Tuple[int, int], Tuple[float, float]]):
 40        """Construct the ConfigNumberParam.
 41
 42        Args:
 43            name: the name of the parameter.
 44            value_type: the type of the parameter.
 45            default_value: the default value of the parameter.
 46            min_max_value: tuple with the minimum and maximum value of the parameter.
 47        """
 48        ConfigValueParam.__init__(self, name, value_type, default_value, min_max_value)
 49
 50    def validate_value(self, value: Any) -> Tuple[bool, Union[int, float], str]:
 51        """Validate the specified value with the parameter.
 52
 53        Checks for None, type mismatch (conversion between int and float is allowed) and if
 54        the value is between the minimum and maximum value of the parameter.
 55
 56        Args:
 57            value: the number to verify with the parameter.
 58
 59        Returns:
 60            whether it was successful, the validated value and (optional) message.
 61        """
 62        if value is None:
 63            return False, self.default_value, 'No value specified for \'' + \
 64                   self.name  + '\', expected value between ' + \
 65                   str(self.min_value) + ' and ' + str(self.max_value)
 66
 67        # type check
 68        type_success, value, type_error = \
 69            validate_type(self.name, value, self.value_type, self.default_value)
 70
 71        # value check
 72        val_success, value, val_error = \
 73            validate_min_max(self.name, value, self.min_value, self.max_value)
 74
 75        return type_success and val_success, value, type_error + val_error
 76
 77
 78class ConfigRandomParam(ConfigNumberParam):
 79    """Config Random Parameter."""
 80
 81    def __init__(self, name: str):
 82        """Construct the ConfigRandomParam.
 83
 84        Args:
 85            name: the name of the random seed parameter.
 86        """
 87        ConfigNumberParam.__init__(self, name, int, None, (0, sys.maxsize))
 88
 89    def validate_value(self, value: Any) -> Tuple[bool, Optional[int], str]:
 90        """Validate the specified value with the parameter.
 91
 92        Checks are the same as ConfigNumberParam.validate_value, but None is allowed.
 93
 94        Args:
 95            value: the random seed to verify with the parameter.
 96
 97        Returns:
 98            whether it was successful, the validated value and (optional) message.
 99        """
100        # skips the 'None' error from ConfigNumberParam
101        if value is None:
102            return True, value, ''
103
104        return ConfigNumberParam.validate_value(self, value)
105
106
107class ConfigRangeParam(ConfigValueParam):
108    """Config Range Parameter.
109
110    The value_type of default_value and min_max_value types are all expected to be either
111    int or float, conversions between the two during validation is available.
112    The default_value min and max values are expected to be between the min_max_value.
113    The default_value and min_max_value are expected to have min_value <= max_value.
114    """
115
116    def __init__(
117            self,
118            name: str,
119            value_type: Type,
120            default_value: Union[Tuple[int, int], Tuple[float, float]],
121            min_max_value: Union[Tuple[int, int], Tuple[float, float]]):
122        """Construct the ConfigRangeParam.
123
124        Args:
125            name: the name of the parameter.
126            value_type: the type of the parameter.
127            default_value: tuple with the default minimum and maximum value of the parameter.
128            min_max_value: tuple with the minimum and maximum value of the parameter.
129        """
130        ConfigValueParam.__init__(
131            self,
132            name,
133            value_type,
134            {
135                PARAM_KEY_MIN: default_value[0],
136                PARAM_KEY_MAX: default_value[1]
137            },
138            min_max_value
139        )
140
141    def validate_value(self, value: Any) -> Tuple[bool, Dict[str, Union[int, float]], str]:
142        """Validate the specified value with the parameter.
143
144        Checks for None, type mismatch (conversion between int and float is allowed) and if
145        the min-max range is between the minimum and maximum value of the parameter.
146
147        Args:
148            value: the min-max range dictionary to verify with the parameter.
149
150        Returns:
151            whether it was successful, the validated value and (optional) message.
152        """
153        if value is None:
154            return False, self.default_value, 'No value specified, expected \'' + \
155                   PARAM_KEY_MIN + '\' and \'' + PARAM_KEY_MAX + '\' range between ' + \
156                   str(self.min_value) + ' and ' + str(self.max_value)
157
158        # check min-max range dictionary
159        success, min_max_range, error = self.validate_dict(value)
160        # initialize result value with defaults
161        result_val = self.default_value
162
163        # check min-max range type
164        for key, val in min_max_range.items():
165            val_success, val, val_err = validate_type(key, val, self.value_type, result_val[key])
166            success = success and val_success
167            result_val[key] = val
168            error += val_err
169
170        # check min-max range value
171        for key, val in dict(result_val).items():
172            val_success, val, val_err = validate_min_max(key, val, self.min_value, self.max_value)
173            success = success and val_success
174            result_val[key] = val
175            error += val_err
176
177        # swap when min range > max range
178        if result_val[PARAM_KEY_MIN] > result_val[PARAM_KEY_MAX]:
179            result_val[PARAM_KEY_MIN], result_val[PARAM_KEY_MAX] = \
180            result_val[PARAM_KEY_MAX], result_val[PARAM_KEY_MIN]
181            success = False
182            error += 'Swapped \'' + PARAM_KEY_MIN + '\' and \'' + PARAM_KEY_MAX + '\'. '
183
184        return success, result_val, error
185
186    def validate_dict(self, value: Any) -> Tuple[bool, Dict[str, Any], str]:
187        """Validate the specified value to a min-max range dictionary.
188
189        Args:
190            value: the min-max range dictionary to validate.
191
192        Returns:
193            whether it was successful, the validated dictionary and (optional) message.
194        """
195        if not isinstance(value, dict):
196            return False, self.default_value, \
197                   'Expected dictionary with \'min\' and \'max\' range between ' + \
198                   str(self.min_value) + ' and ' + str(self.max_value)
199
200        success = True
201        if PARAM_KEY_MIN in value:
202            min_error = ''
203            min_val = value[PARAM_KEY_MIN]
204        else:
205            min_val = self.min_value
206            min_error = 'Expected \'min\' in dictionary. '
207            success = False
208
209        if PARAM_KEY_MAX in value:
210            max_error = ''
211            max_val = value[PARAM_KEY_MAX]
212        else:
213            max_val = self.max_value
214            max_error = 'Expected \'max\' in dictionary. '
215            success = False
216
217        return success, { PARAM_KEY_MIN: min_val, PARAM_KEY_MAX: max_val }, min_error + max_error
218
219
220def validate_min_max(
221        value_name: str,
222        value: Union[int, float],
223        min_value: Union[int, float],
224        max_value: Union[int, float]) -> Tuple[bool, Union[int, float], str]:
225    """Validate the value with the specified min- and max-value.
226
227    Args:
228        value_name: the name associated with the value.
229        value: the value to validate.
230        min_value: the minimum value to use for validation.
231        max_value: the maximum value to use for validation.
232
233    Returns:
234        whether it was successful, the validated value and (optional) message.
235    """
236    if value < min_value:
237        return False, min_value, 'Expected \'' + value_name + \
238               '\' greater or equal to ' + str(min_value) + '. '
239    if value > max_value:
240        return False, max_value, 'Expected \'' + value_name + \
241               '\' less or equal to ' + str(max_value) + '. '
242
243    return True, value, ''
244
245def validate_type(
246        value_name: str,
247        value: Any,
248        value_type: Type,
249        default_value: Union[int, float]) -> Tuple[bool, Union[int, float], str]:
250    """Validate the value to be of the correct type.
251
252    Conversion between int/float is allowed and will return True, but
253    with the optional message that the value was cast to the correct value_type.
254
255    Args:
256        value_name: the name associated with the value.
257        value: the value to validate the type of.
258        value_type: the type of the value.
259        default_value: the default value to return on invalidation.
260
261    Returns:
262        whether it was successful, the validated value and (optional) message.
263    """
264    if isinstance(value, float) and value_type == int:
265        return True, value_type(value), 'Value \'' + value_name + '\' cast to int. '
266    if isinstance(value, int) and not isinstance(value, bool) and value_type == float:
267        return True, value_type(value), 'Value \'' + value_name + '\' cast to float. '
268    if not isinstance(value, value_type) or isinstance(value, bool):
269        return False, default_value, 'Expected \'' + value_name + '\' to be ' + \
270               str(value_type) + ' got ' + str(type(value)) + '. '
271
272    return True, value, ''