mlrl-util 0.12.0__py3-none-any.whl

mlrl/util/arrays.py

@@ -0,0 +1,169 @@
+"""
+Author: Michael Rapp (michael.rapp.ml@gmail.com)
+
+Provides utility functions for handling arrays.
+"""
+from enum import Enum
+from typing import Optional, Set
+
+import numpy as np
+
+from scipy.sparse import issparse, isspmatrix_coo, isspmatrix_csc, isspmatrix_csr, isspmatrix_dok, isspmatrix_lil, \
+    sparray
+
+from mlrl.util.format import format_iterable
+
+
+class SparseFormat(Enum):
+    """
+    Specifies all valid textual representations of sparse matrix formats.
+    """
+    LIL = 'lil'
+    COO = 'coo'
+    DOK = 'dok'
+    CSC = 'csc'
+    CSR = 'csr'
+
+
+def is_lil(array) -> bool:
+    """
+    Returns whether a given `scipy.sparse.spmatrix` or `scipy.sparse.sparray` uses the LIL format or not.
+
+    :param array:   A `scipy.sparse.spmatrix` or `scipy.sparse.sparray` to be checked
+    :return:        True, if the given array uses the LIL format, False otherwise
+    """
+    return isspmatrix_lil(array) or (isinstance(array, sparray) and array.format == 'lil')
+
+
+def is_coo(array) -> bool:
+    """
+    Returns whether a given `scipy.sparse.spmatrix` or `scipy.sparse.sparray` uses the COO format or not.
+
+    :param array:   A `scipy.sparse.spmatrix` or `scipy.sparse.sparray` to be checked
+    :return:        True, if the given array uses the COO format, False otherwise
+    """
+    return isspmatrix_coo(array) or (isinstance(array, sparray) and array.format == 'coo')
+
+
+def is_dok(array) -> bool:
+    """
+    Returns whether a given `scipy.sparse.spmatrix` or `scipy.sparse.sparray` uses the DOK format or not.
+
+    :param array:   A `scipy.sparse.spmatrix` or `scipy.sparse.sparray` to be checked
+    :return:        True, if the given array uses the DOK format, False otherwise
+    """
+    return isspmatrix_dok(array) or (isinstance(array, sparray) and array.format == 'dok')
+
+
+def is_csc(array) -> bool:
+    """
+    Returns whether a given `scipy.sparse.spmatrix` or `scipy.sparse.sparray` uses the CSC format or not.
+
+    :param array:   A `scipy.sparse.spmatrix` or `scipy.sparse.sparray` to be checked
+    :return:        True, if the given array uses the CSC format, False otherwise
+    """
+    return isspmatrix_csc(array) or (isinstance(array, sparray) and array.format == 'csc')
+
+
+def is_csr(array) -> bool:
+    """
+    Returns whether a given `scipy.sparse.spmatrix` or `scipy.sparse.sparray` uses the CSR format or not.
+
+    :param array:   A `scipy.sparse.spmatrix` or `scipy.sparse.sparray` to be checked
+    :return:        True, if the given array uses the CSR format, False otherwise
+    """
+    return isspmatrix_csr(array) or (isinstance(array, sparray) and array.format == 'csr')
+
+
+def is_sparse(array, supported_formats: Optional[Set[SparseFormat]] = None) -> bool:
+    """
+    Returns whether a given array is a `scipy.sparse.spmatrix` or `scipy.sparse.sparray` or not.
+
+    :param array:               A `np.ndarray`, `scipy.sparse.spmatrix` or `scipy.sparse.sparray` to be checked
+    :param supported_formats:   A set of supported `SparseFormat`s, the `scipy.sparse.spmatrix` or
+                                `scipy.sparse.sparray` may use or None, if the format should not be checked
+    :return:                    True, if the given array is a `scipy.sparse.spmatrix` or `scipy.sparse.sparray` using
+                                one of the supported formats, False otherwise
+    """
+    if supported_formats:
+        lil = SparseFormat.LIL in supported_formats and is_lil(array)
+        coo = SparseFormat.COO in supported_formats and is_coo(array)
+        dok = SparseFormat.DOK in supported_formats and is_dok(array)
+        csc = SparseFormat.CSC in supported_formats and is_csc(array)
+        csr = SparseFormat.CSR in supported_formats and is_csr(array)
+
+        if lil or coo or dok or csc or csr:
+            return True
+        return False
+
+    return issparse(array)
+
+
+def is_sparse_and_memory_efficient(array,
+                                   sparse_format: SparseFormat,
+                                   dtype: Optional[np.dtype] = None,
+                                   sparse_values: bool = True) -> bool:
+    """
+    Returns whether a given matrix uses sparse format and is expected to occupy less memory than a dense matrix.
+
+    :param array:           A `np.ndarray`, `scipy.sparse.spmatrix` or `scipy.sparse.sparray` to be checked
+    :param sparse_format:   The `SparseFormat` to be used. Must be `SparseFormat.CSC` or `SparseFormat.CSR`
+    :param dtype:           The type of the values that should be stored in the matrix or None, if it should be obtained
+                            from the given array
+    :param sparse_values:   True, if the values must explicitly be stored when using a sparse format, False otherwise
+    :return:                True, if the given matrix uses a sparse format an is expected to occupy less memory than a
+                            dense matrix, False otherwise
+    """
+    supported_formats = {SparseFormat.CSC, SparseFormat.CSR}
+
+    if sparse_format not in supported_formats:
+        raise ValueError('Unable to estimate memory requirements of given sparse format: Must be one of '
+                         + format_iterable(supported_formats) + ', but is "' + str(sparse_format) + '"')
+
+    if is_sparse(array):
+        num_pointers = array.shape[1 if sparse_format == SparseFormat.CSC else 0]
+        size_int = np.dtype(np.uint32).itemsize
+        dtype = dtype if dtype else array.dtype
+        size_data = np.dtype(dtype).itemsize
+        size_sparse_data = size_data if sparse_values else 0
+        num_dense_elements = array.nnz
+        size_sparse = (num_dense_elements * size_sparse_data) + (num_dense_elements * size_int) + (num_pointers
+                                                                                                   * size_int)
+        size_dense = np.prod(array.shape) * size_data
+        return size_sparse < size_dense
+    return False
+
+
+def enforce_dense(array, order: str, dtype: Optional[np.dtype] = None, sparse_value=0) -> np.ndarray:
+    """
+    Converts a given array into a `np.ndarray`, if necessary, and enforces a specific memory layout and data type to be
+    used.
+
+    :param array:           A `np.ndarray`, `scipy.sparse.spmatrix` or `scipy.sparse.sparray` to be converted
+    :param order:           The memory layout to be used. Must be `C` or `F`
+    :param dtype:           The data type to be used or None, if the data type should not be changed
+    :param sparse_value:    The value that should be used for sparse elements in the given array
+    :return:                A `np.ndarray` that uses the given memory layout and data type
+    """
+    dtype = dtype if dtype else array.dtype
+
+    if is_sparse(array):
+        if sparse_value != 0:
+            dense_array = np.full(shape=array.shape, fill_value=sparse_value, dtype=dtype, order=order)
+            dense_array[array.nonzero()] = 0
+            dense_array += array
+            return np.asarray(dense_array, dtype=dtype, order=order)
+        return np.require(array.toarray(order=order), dtype=dtype)
+    return np.require(array, dtype=dtype, requirements=[order])
+
+
+def enforce_2d(array: np.ndarray) -> np.ndarray:
+    """
+    Converts a given `np.ndarray` into a two-dimensional array if it is one-dimensional.
+
+    :param array:   A `np.ndarray` to be converted
+    :return:        A `np.ndarray` with at least two dimensions
+    """
+    if array.ndim == 1:
+        return np.expand_dims(array, axis=1)
+    return array

mlrl/util/cli.py

@@ -0,0 +1,340 @@
+"""
+Author: Michael Rapp (michael.rapp.ml@gmail.com)
+
+Provides classes for configuring the arguments of a command line interface.
+"""
+import sys
+
+from argparse import ArgumentError, ArgumentParser, Namespace
+from enum import Enum, EnumType
+from functools import cached_property
+from typing import Any, Dict, Optional, Set
+
+from mlrl.util.format import format_enum_values, format_set
+from mlrl.util.options import BooleanOption, parse_enum, parse_param, parse_param_and_options
+
+NONE = 'none'
+
+
+class Argument:
+    """
+    A single argument of a command line interface for which the user can provide a custom value.
+    """
+
+    def __init__(self, *names: str, required: Optional[bool] = False, default: Optional[Any] = None, **kwargs: Any):
+        """
+        :param names:       One of several names of the argument
+        :param required:    True, if the argument is mandatory, False otherwise
+        :param default:     The default value of the argument, if any
+        :param kwargs:      Optional keyword argument to be passed to an `ArgumentParser`
+        """
+        self.names = set(names)
+        self.required = required
+        self.default = default
+        self.kwargs = dict(kwargs)
+
+    @cached_property
+    def name(self) -> str:
+        """
+        The name of the argument.
+        """
+        return next(iter(self.names))
+
+    @cached_property
+    def key(self) -> str:
+        """
+        The key of the argument in a `Namespace`.
+        """
+        return self.name.lstrip('--').replace('-', '_')
+
+    def get_value(self, args: Namespace, default: Optional[Any] = None) -> Optional[Any]:
+        """
+        Returns the value provided by the user for this argument.
+
+        :param args:    A `Namespace` that provides access to the values provided by the user
+        :param default: The default value to be returned if no value is available
+        :return:        The value provided by the user or `default`, if no value is available
+        """
+        value = getattr(args, self.key, None)
+        value = self.default if value is None else value
+        return default if value is None else value
+
+    def __hash__(self) -> int:
+        return hash(self.key)
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, type(self)) and self.key == other.key
+
+
+class StringArgument(Argument):
+    """
+    An argument of a command line interface for which the user can provide a custom string value.
+    """
+
+    def __init__(self,
+                 *names: str,
+                 description: Optional[str] = None,
+                 default: Optional[str] = None,
+                 required: bool = False):
+        """
+        :param names:       One or several names of the argument
+        :param description: An optional description of the argument
+        :param default:     The default value
+        :param required:    True, if the argument is mandatory, False otherwise
+        """
+        super().__init__(*names, default=default, help=description, type=str, required=required)
+
+    def get_value(self, args: Namespace, default: Optional[Any] = None) -> Optional[Any]:
+        value = super().get_value(args, default=default)
+        return None if value is None else str(value)
+
+
+class IntArgument(Argument):
+    """
+    An argument of a command line interface for which the user can provide a custom integer value.
+    """
+
+    def __init__(self,
+                 *names: str,
+                 description: Optional[str] = None,
+                 default: Optional[int] = None,
+                 required: bool = False):
+        """
+        :param names:       One or several names of the argument
+        :param description: An optional description of the argument
+        :param default:     The default value
+        :param required:    True, if the argument is mandatory, False otherwise
+        """
+        super().__init__(*names, default=default, help=description, type=int, required=required)
+
+    def get_value(self, args: Namespace, default: Optional[Any] = None) -> Optional[Any]:
+        value = super().get_value(args, default=default)
+
+        try:
+            return None if value is None else int(value)
+        except ValueError as error:
+            raise ValueError('Expected value of argument ' + self.name + ' to be an integer, but got: '
+                             + str(value)) from error
+
+
+class FloatArgument(Argument):
+    """
+    An argument of a command line interface for which the user can provide a custom floating point value.
+    """
+
+    def __init__(self,
+                 *names: str,
+                 description: Optional[str] = None,
+                 default: Optional[float] = None,
+                 required: bool = False):
+        """
+        :param names:       One or several names of the argument
+        :param description: An optional description of the argument
+        :param default:     The default value
+        :param required:    True, if the argument is mandatory, False otherwise
+        """
+        super().__init__(*names, default=default, help=description, type=float, required=required)
+
+    def get_value(self, args: Namespace, default: Optional[Any] = None) -> Optional[Any]:
+        value = super().get_value(args, default=default)
+
+        try:
+            return None if value is None else float(value)
+        except ValueError as error:
+            raise ValueError('Expected value of argument ' + self.name + ' to be a float, but got: '
+                             + str(value)) from error
+
+
+class BoolArgument(Argument):
+    """
+    An argument of a command line interface for which the user can provide a custom boolean value.
+    """
+
+    @staticmethod
+    def __format_description(description: str, has_options: bool) -> str:
+        if not description.endswith('.'):
+            description += '.'
+
+        description += ' Must be one of ' + format_enum_values(BooleanOption) + '.'
+
+        if has_options:
+            description += ' For additional options refer to the documentation.'
+
+        return description
+
+    def __init__(self,
+                 *names: str,
+                 description: Optional[str] = None,
+                 default: Optional[bool] = None,
+                 required: bool = False,
+                 true_options: Optional[Set[str]] = None,
+                 false_options: Optional[Set[str]] = None):
+        """
+        :param names:           One or several names of the argument
+        :param description:     An optional description of the argument
+        :param default:         The default value
+        :param required:        True, if the argument is mandatory, False otherwise
+        :param true_options:    The names of options that can be provided by the user in addition to the value "true"
+        :param false_options:   The names of options that can be provided by the user in addition to the value "false"
+        """
+        super().__init__(*names,
+                         default=None if default is None else
+                         (BooleanOption.TRUE.value if default else BooleanOption.FALSE.value),
+                         help=self.__format_description(description,
+                                                        bool(true_options) or bool(false_options)),
+                         type=str if true_options or false_options else BooleanOption.parse,
+                         required=required)
+        self.true_options = true_options
+        self.false_options = false_options
+
+    def get_value(self, args: Namespace, default: Optional[Any] = None) -> Optional[Any]:
+        value = str(super().get_value(args, default=default)).lower()
+
+        if value:
+            true_options = self.true_options
+            false_options = self.false_options
+
+            if true_options or false_options:
+                value, options = parse_param_and_options(self.key, value, {
+                    BooleanOption.TRUE.value: true_options,
+                    BooleanOption.FALSE.value: false_options
+                })
+                return BooleanOption.parse(value), options
+
+            return BooleanOption.parse(value)
+
+        return None
+
+
+class SetArgument(Argument):
+    """
+    An argument of a command line interface for which the user can provide one out of a predefined set of string values.
+    """
+
+    @staticmethod
+    def __format_description(description: str, values: Set[str] | Dict[str, Set[str]]) -> str:
+        if not description.endswith('.'):
+            description += '.'
+
+        description += ' Must be one of ' + format_set(values.keys() if isinstance(values, dict) else values) + '.'
+
+        if isinstance(values, dict):
+            description += ' For additional options refer to the documentation.'
+
+        return description
+
+    def __init__(self,
+                 *names: str,
+                 values: Set[str] | Dict[str, Set[str]],
+                 description: Optional[str] = None,
+                 default: Optional[str] = None,
+                 required: bool = False):
+        """
+        :param names:       One or several names of the argument
+        :param values:      A set that contains the predefined values or a dictionary that contains the predefined
+                            values, as well as the names of options that can be provided by the user in addition to the
+                            respective values
+        :param description: An optional description of the argument
+        :param default:     The default value
+        :param required:    True, if the argument is mandatory, False otherwise
+        """
+        super().__init__(*names,
+                         default=default,
+                         help=self.__format_description(description, values),
+                         type=str,
+                         required=required)
+        self.supported_values = values
+
+    def get_value(self, args: Namespace, default: Optional[Any] = None) -> Optional[Any]:
+        value = super().get_value(args, default=default)
+
+        if value:
+            supported_values = self.supported_values
+
+            if isinstance(supported_values, dict):
+                return parse_param_and_options(self.key, value, supported_values)
+
+            return parse_param(self.key, value, supported_values)
+
+        return None
+
+
+class EnumArgument(SetArgument):
+    """
+    An argument of a command line interface for which the user can provide one out of a predefined set enum values.
+    """
+
+    def __init__(self,
+                 *names: str,
+                 enum: EnumType,
+                 description: Optional[str] = None,
+                 default: Optional[Enum] = None,
+                 required: bool = False):
+        """
+        :param names:       One or several names of the argument
+        :param values:      An enum that contains the predefined values
+        :param description: An optional description of the argument
+        :param default:     The default value
+        :param required:    True, if the argument is mandatory, False otherwise
+        """
+        super().__init__(
+            *names,
+            values={x.value if isinstance(x.value, str) else x.name.lower()
+                    for x in enum},
+            description=description,
+            default=(default.value if isinstance(default.value, str) else default.name.lower()) if default else None,
+            required=required)
+        self.enum = enum
+
+    def get_value(self, args: Namespace, default: Optional[Any] = None) -> Optional[Any]:
+        value = super().get_value(args, default=default)
+        return parse_enum(self.name, value, self.enum) if value else None
+
+
+class CommandLineInterface:
+    """
+    Allows to configure a command line interface for running a program.
+    """
+
+    def __init__(self, argument_parser: ArgumentParser, version_text: Optional[str] = None):
+        """
+        :param argument_parser: The parser that should be used for parsing arguments provided to the command line
+                                interface by the user
+        :param version_text:    A text to be shown when the "--version" flag is passed to the command line interface or
+                                None, if the "--version" flag should not be added to the command line interface
+        """
+        self._argument_parser = argument_parser
+
+        if version_text:
+            argument_parser.add_argument('-v',
+                                         '--version',
+                                         action='version',
+                                         version=version_text,
+                                         help='Display information about the program.')
+
+    def add_arguments(self, *arguments: Argument) -> Optional[Namespace]:
+        """
+        Adds a new argument that enables the user to provide a value to the command line interface.
+
+        :param arguments: The arguments to be added
+        """
+        argument_parser = self._argument_parser
+
+        for argument in arguments:
+            try:
+                required = argument.required and '--help' not in sys.argv and '-h' not in sys.argv
+                argument_parser.add_argument(*argument.names,
+                                             required=required,
+                                             default=argument.default,
+                                             **argument.kwargs)
+            except ArgumentError:
+                # Argument has already been added
+                pass
+
+    def parse_known_args(self) -> Namespace:
+        """
+        Parses and returns the values of the arguments already added to the command line interface.
+
+        :return: A `Namespace` providing access to the values of the arguments
+        """
+        return self._argument_parser.parse_known_args()[0]

mlrl/util/format.py

@@ -0,0 +1,40 @@
+"""
+Author: Michael Rapp (michael.rapp.ml@gmail.com)
+
+Provides utility functions for creating textual representations.
+"""
+from enum import EnumType
+from functools import reduce
+from typing import Any, Iterable
+
+
+def format_iterable(objects: Iterable[Any], separator: str = ', ', delimiter: str = '') -> str:
+    """
+    Creates and returns a textual representation of objects in an iterable.
+
+    :param objects:     The iterable of objects to be formatted
+    :param separator:   The string that should be used as a separator
+    :param delimiter:   The string that should be added at the beginning and end of each object
+    :return:            The textual representation that has been created
+    """
+    return reduce(lambda aggr, obj: aggr + (separator if aggr else '') + delimiter + str(obj) + delimiter, objects, '')
+
+
+def format_enum_values(enum: EnumType) -> str:
+    """
+    Creates and returns a textual representation of an enum's values.
+
+    :param enum:    The enum to be formatted
+    :return:        The textual representation that has been created
+    """
+    return format_set({x.value if isinstance(x.value, str) else x.name.lower() for x in enum})
+
+
+def format_set(objects: Iterable[Any]) -> str:
+    """
+    Creates and returns a textual representation of the objects in a set.
+
+    :param objects: The iterable of objects to be formatted
+    :return:        The textual representation that has been created
+    """
+    return '{' + format_iterable(sorted(objects, key=str), delimiter='"') + '}'

mlrl/util/options.py

@@ -0,0 +1,242 @@
+"""
+Author: Michael Rapp (michael.rapp.ml@gmail.com)
+
+Provides a data structure that allows to store and parse options that are provided as key-value pairs.
+"""
+from enum import Enum, EnumType
+from typing import Any, Dict, Optional, Set, Tuple
+
+from mlrl.util.format import format_enum_values, format_set
+
+
+class BooleanOption(Enum):
+    """
+    Specifies all valid textual representations of boolean values.
+    """
+    TRUE = 'true'
+    FALSE = 'false'
+
+    @staticmethod
+    def parse(text: str) -> bool:
+        """
+        Parses a given text that represents a boolean value. If the given text does not represent a valid boolean value,
+        a `ValueError` is raised.
+
+        :param text:    The text to be parsed
+        :return:        True or false, depending on the given text
+        """
+        if text == BooleanOption.TRUE.value:
+            return True
+        if text == BooleanOption.FALSE.value:
+            return False
+        raise ValueError('Invalid boolean value given. Must be one of ' + format_enum_values(BooleanOption)
+                         + ', but is "' + str(text) + '".')
+
+
+class Options:
+    """
+    Stores key-value pairs in a dictionary and provides methods to access and validate them.
+    """
+
+    ERROR_MESSAGE_INVALID_SYNTAX = 'Invalid syntax used to specify additional options'
+
+    ERROR_MESSAGE_INVALID_OPTION = 'Expected comma-separated list of key-value pairs'
+
+    def __init__(self, dictionary: Optional[Dict[str, Any]] = None):
+        self.dictionary = dictionary if dictionary is not None else {}
+
+    @classmethod
+    def create(cls, string: str, allowed_keys: Set[str]):
+        """
+        Parses the options that are provided via a given string that is formatted according to the following syntax:
+        "[key1=value1,key2=value2]". If the given string is malformed, a `ValueError` will be raised.
+
+        :param string:          The string to be parsed
+        :param allowed_keys:    A set that contains all valid keys
+        :return:                An object of type `Options` that stores the key-value pairs that have been parsed from
+                                the given string
+        """
+        options = cls()
+
+        if string:
+            if not string.startswith('{'):
+                raise ValueError(Options.ERROR_MESSAGE_INVALID_SYNTAX + '. Must start with "{", but is "' + string
+                                 + '"')
+            if not string.endswith('}'):
+                raise ValueError(Options.ERROR_MESSAGE_INVALID_SYNTAX + '. Must end with "}", but is "' + string + '"')
+
+            string = string[1:-1]
+
+            if string:
+                for option_index, option in enumerate(string.split(',')):
+                    if option:
+                        parts = option.split('=')
+
+                        if len(parts) != 2:
+                            raise ValueError(Options.ERROR_MESSAGE_INVALID_SYNTAX + '. '
+                                             + Options.ERROR_MESSAGE_INVALID_OPTION + ', but got element "' + option
+                                             + '" at index ' + str(option_index))
+
+                        key = parts[0]
+
+                        if len(key) == 0:
+                            raise ValueError(Options.ERROR_MESSAGE_INVALID_SYNTAX + '. '
+                                             + Options.ERROR_MESSAGE_INVALID_OPTION
+                                             + ', but key is missing from element "' + option + '" at index '
+                                             + str(option_index))
+
+                        if key not in allowed_keys:
+                            raise ValueError('Key must be one of ' + format_set(allowed_keys) + ', but got key "' + key
+                                             + '" at index ' + str(option_index))
+
+                        value = parts[1]
+
+                        if len(value) == 0:
+                            raise ValueError(Options.ERROR_MESSAGE_INVALID_SYNTAX + '. '
+                                             + Options.ERROR_MESSAGE_INVALID_OPTION
+                                             + ', but value is missing from element "' + option + '" at index '
+                                             + str(option_index))
+
+                        options.dictionary[key] = value
+
+        return options
+
+    def get_string(self, key: str, default_value: Optional[str] = None) -> Optional[str]:
+        """
+        Returns a string that corresponds to a specific key.
+
+        :param key:             The key
+        :param default_value:   The default value to be returned, if no value is associated with the given key
+        :return:                The value that is associated with the given key or the given default value
+        """
+        if key in self.dictionary:
+            return str(self.dictionary[key])
+
+        return default_value
+
+    def get_bool(self, key: str, default_value: bool) -> bool:
+        """
+        Returns a boolean that corresponds to a specific key.
+
+        :param key:             The key
+        :param default_value:   The default value to be returned, if no value is associated with the given key
+        :return:                The value that is associated with the given key or the given default value
+        """
+        if key in self.dictionary:
+            value = str(self.dictionary[key])
+            return BooleanOption.parse(value)
+
+        return default_value
+
+    def get_int(self, key: str, default_value: int) -> int:
+        """
+        Returns an integer that corresponds to a specific key.
+
+        :param key:             The key
+        :param default_value:   The default value to be returned, if no value is associated with the given key
+        :return:                The value that is associated with the given key or the given default value
+        """
+        if key in self.dictionary:
+            value = self.dictionary[key]
+
+            try:
+                value = int(value)
+            except ValueError as error:
+                raise ValueError('Value for key "' + key + '" is expected to be an integer, but is "' + str(value)
+                                 + '"') from error
+
+            return value
+
+        return default_value
+
+    def get_float(self, key: str, default_value: float) -> float:
+        """
+        Returns a float that corresponds to a specific key.
+
+        :param key:             The key
+        :param default_value:   The default value to be returned, if no value is associated with the given key
+        :return:                The value that is associated with the given key or the given default value
+        """
+        if key in self.dictionary:
+            value = self.dictionary[key]
+
+            try:
+                value = float(value)
+            except ValueError as error:
+                raise ValueError('Value for key "' + key + '" is expected to be a float, but is "' + str(value)
+                                 + '"') from error
+
+            return value
+
+        return default_value
+
+
+def parse_enum(parameter_name: str,
+               value: Optional[str],
+               enum: EnumType,
+               default: Optional[Enum] = None) -> Optional[EnumType]:
+    """
+    Parses and returns an enum value. If the given value is invalid, a `ValueError` is raised.
+
+    :param parameter_name:  The name of the parameter
+    :param value:           The value to be parsed
+    :param enum:            The enum
+    :param default:         The default value to be returned if `value` is None
+    :return:                The value that has been parsed or `default`, if the given value is None
+    """
+    if value:
+        for enum_value in enum:
+            expected_value = enum_value.value if isinstance(enum_value.value, str) else enum_value.name.lower()
+
+            if expected_value == value:
+                return enum_value
+
+        raise ValueError('Invalid value given for parameter "' + parameter_name + '": Must be one of '
+                         + format_enum_values(enum) + ', but is "' + str(value) + '"')
+
+    return default
+
+
+def parse_param(parameter_name: str, value: str, allowed_values: Set[str]) -> str:
+    """
+    Parses and returns a parameter value. If the given value is invalid, a `ValueError` is raised.
+
+    :param parameter_name:  The name of the parameter
+    :param value:           The value to be parsed
+    :param allowed_values:  A set that contains all valid values
+    :return:                The value that has been parsed
+    """
+    if value in allowed_values:
+        return value
+
+    raise ValueError('Invalid value given for parameter "' + parameter_name + '": Must be one of '
+                     + format_set(allowed_values) + ', but is "' + str(value) + '"')
+
+
+def parse_param_and_options(parameter_name: str, value: str,
+                            allowed_values_and_options: Dict[str, Set[str]]) -> Tuple[str, Options]:
+    """
+    Parses and returns a parameter value, as well as additional `Options` that may be associated with it. If the given
+    value is invalid, a `ValueError` is raised.
+    
+    :param parameter_name:              The name of the parameter
+    :param value:                       The value to be parsed
+    :param allowed_values_and_options:  A dictionary that contains all valid values, as well as their options
+    :return:                            A tuple that contains the value that has been parsed, as well as additional
+                                        `Options`.
+    """
+    for allowed_value, allowed_options in allowed_values_and_options.items():
+        if value.startswith(allowed_value):
+            suffix = value[len(allowed_value):].strip()
+
+            if suffix:
+                try:
+                    return allowed_value, Options.create(suffix, allowed_options)
+                except ValueError as error:
+                    raise ValueError('Invalid options specified for parameter "' + parameter_name + '" with value "'
+                                     + allowed_value + '": ' + str(error)) from error
+
+            return allowed_value, Options()
+
+    raise ValueError('Invalid value given for parameter "' + parameter_name + '": Must be one of '
+                     + format_set(allowed_values_and_options.keys()) + ', but is "' + value + '"')

mlrl/util/validation.py

@@ -0,0 +1,81 @@
+"""
+Author: Michael Rapp (michael.rapp.ml@gmail.com)
+
+Provides utility functions for validation.
+"""
+
+
+def assert_greater(name: str, value, threshold):
+    """
+    Raises a `ValueError` if a given value is not greater than a specific threshold.
+
+    :param name:        The name of the parameter, the value  corresponds to
+    :param value:       The value
+    :param threshold:   The threshold
+    """
+    if value <= threshold:
+        raise ValueError('Invalid value given for parameter "' + name + '": Must be greater than ' + str(threshold)
+                         + ', but is ' + str(value))
+
+
+def assert_greater_or_equal(name: str, value, threshold):
+    """
+    Raises a `ValueError` if a given value is not greater or equal to a specific threshold.
+
+    :param name:        The name of the parameter, the value corresponds to
+    :param value:       The value
+    :param threshold:   The threshold
+    """
+    if value < threshold:
+        raise ValueError('Invalid value given for parameter "' + name + '": Must be greater or equal to '
+                         + str(threshold) + ', but is ' + str(value))
+
+
+def assert_less(name: str, value, threshold):
+    """
+    Raises a `ValueError` if a given value is not less than a specific threshold.
+    
+    :param name:        The name of the parameter, the value corresponds to 
+    :param value:       The value
+    :param threshold:   The threshold
+    """
+    if value >= threshold:
+        raise ValueError('Invalid value given for parameter "' + name + '": Must be less than ' + str(threshold)
+                         + ', but is ' + str(value))
+
+
+def assert_less_or_equal(name: str, value, threshold):
+    """
+    Raises a `ValueError` if a given value is not less or equal to a specific threshold.
+
+    :param name:        The name of the parameter, the value corresponds to
+    :param value:       The value
+    :param threshold:   The threshold
+    """
+    if value > threshold:
+        raise ValueError('Invalid value given for parameter "' + name + '": Must be less or equal to ' + str(threshold)
+                         + ', but is ' + str(value))
+
+
+def assert_multiple(name: str, value, other):
+    """
+    Raises a `ValueError` if a given value is not a multiple of another value.
+
+    :param name:    The name of the parameter, the value corresponds to
+    :param value:   The value that should be a multiple of `other`
+    :param other:   The other value
+    """
+    if value % other != 0:
+        raise ValueError('Invalid value given for parameter "' + name + '": Must be a multiple of ' + str(other)
+                         + ', but is ' + str(value))
+
+
+def assert_not_none(name: str, value):
+    """
+    Raises a `ValueError` if a given value is None.
+
+    :param name:    The name of the parameter, the value corresponds to
+    :param value:   The value
+    """
+    if value is None:
+        raise ValueError('Invalid value given for parameter "' + name + '": Must not be None')

mlrl_util-0.12.0.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: mlrl-util
+Version: 0.12.0
+Summary: Provides common utilities used by the mlrl-* packages.
+Author-email: Michael Rapp <michael.rapp.ml@gmail.com>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/mrapp-ke/MLRL-Boomer
+Project-URL: source, https://github.com/mrapp-ke/MLRL-Boomer.git
+Project-URL: download, https://github.com/mrapp-ke/MLRL-Boomer/releases
+Project-URL: changelog, https://raw.githubusercontent.com/mrapp-ke/MLRL-Boomer/refs/heads/main/CHANGELOG.md
+Project-URL: documentation, https://mlrl-boomer.readthedocs.io/en/latest
+Project-URL: issues, https://github.com/mrapp-ke/MLRL-Boomer/issues
+Keywords: utilities
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy<2.4,>=2.3
+Requires-Dist: scipy<1.17,>=1.16
+
+# "MLRL-Util"
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PyPI version](https://badge.fury.io/py/mlrl-util.svg)](https://badge.fury.io/py/mlrl-util) [![Documentation Status](https://readthedocs.org/projects/mlrl-boomer/badge/?version=latest)](https://mlrl-boomer.readthedocs.io/en/latest/?badge=latest)
+
+**:link: Important links:** [API Reference](https://mlrl-boomer.readthedocs.io/en/latest/developer_guide/api/python/util/mlrl.util.html) | [Issue Tracker](https://github.com/mrapp-ke/MLRL-Boomer/issues) | [Changelog](https://mlrl-boomer.readthedocs.io/en/latest/misc/CHANGELOG.html) | [Contributors](https://mlrl-boomer.readthedocs.io/en/latest/misc/CONTRIBUTORS.html) | [Code of Conduct](https://mlrl-boomer.readthedocs.io/en/latest/misc/CODE_OF_CONDUCT.html) | [License](https://mlrl-boomer.readthedocs.io/en/latest/misc/LICENSE.html)
+
+This software package provides common utilities used by the packages [mlrl-common](https://pypi.org/project/mlrl-common/) and [mlrl-testbed](https://pypi.org/project/mlrl-testbed/). It is not of much use on its own.
+
+## :scroll: License
+
+This project is open source software licensed under the terms of the [MIT license](https://mlrl-boomer.readthedocs.io/en/latest/misc/LICENSE.html). We welcome contributions to the project to enhance its functionality and make it more accessible to a broader audience. A frequently updated list of contributors is available [here](https://mlrl-boomer.readthedocs.io/en/latest/misc/CONTRIBUTORS.html).
+
+All contributions to the project and discussions on the [issue tracker](https://github.com/mrapp-ke/MLRL-Boomer/issues) are expected to follow the [code of conduct](https://mlrl-boomer.readthedocs.io/en/latest/misc/CODE_OF_CONDUCT.html).

mlrl_util-0.12.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mlrl/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mlrl/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mlrl/util/arrays.py,sha256=yGhiDCBfdgmX7SpaZtWgnLd3929o9qTFpGGpV2UWXhQ,7450
+mlrl/util/cli.py,sha256=lIc5oJ6-VQrE6us7qA_7amkrL9Dwcd4TnbFTNOgs_e4,13777
+mlrl/util/format.py,sha256=inBiNMYPEke3BlItHicZRC_NYb2r_jgQ1lF0SmxRyn8,1519
+mlrl/util/options.py,sha256=mWTWGQZgw1AyKNJg4BFMpb32v9Q4fVfuv7i1BMC96yc,10303
+mlrl/util/validation.py,sha256=mkYKbwrrb5zIig0sIX3JnT_baWPN1WvPwe9R8rCWyWA,2962
+mlrl_util-0.12.0.dist-info/METADATA,sha256=HlCWNH6tNraQWoCC2LLv4j-tgf35fDO9Y3Mr82yXiJg,2856
+mlrl_util-0.12.0.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
+mlrl_util-0.12.0.dist-info/top_level.txt,sha256=o9x5YHV4Syk8twE0D3Or7SqyG69Ryp7e-HEYe8aB4j4,5
+mlrl_util-0.12.0.dist-info/RECORD,,

mlrl_util-0.12.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mlrl_util-0.12.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mlrl