Source code for qudi.core.configoption

# -*- coding: utf-8 -*-
"""
ConfigOption object to be used in qudi modules. The value of each ConfigOption can
(if it has a default value) or must be specified by the user in the config file.
Usually these values should be constant for the duration of a qudi session.

.. Copyright (c) 2021, the qudi developers. See the AUTHORS.md file at the top-level directory of this
.. distribution and on <https://github.com/Ulm-IQO/qudi-core/>
..
.. This file is part of qudi.
..
.. Qudi is free software: you can redistribute it and/or modify it under the terms of
.. the GNU Lesser General Public License as published by the Free Software Foundation,
.. either version 3 of the License, or (at your option) any later version.
..
.. Qudi 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 Lesser General Public License for more details.
..
.. You should have received a copy of the GNU Lesser General Public License along with qudi.
.. If not, see <https://www.gnu.org/licenses/>.
"""

__all__ = ["ConfigOption", "MissingOption"]

import copy
import inspect
from enum import Enum
from typing import Any, Optional, Callable




class MissingOption(Enum):
    """Representation for missing ConfigOption"""

    error = -3
    warn = -2
    info = -1
    nothing = 0





class ConfigOption:
    """This class represents a configuration entry in the config file that is loaded before
    module initalisation.
    """

    def __init__(
        self,
        name: Optional[str] = None,
        default: Optional[Any] = None,
        *,
        missing: Optional[str] = "nothing",
        constructor: Optional[Callable] = None,
        checker: Optional[Callable] = None,
        converter: Optional[Callable] = None,
    ):
        """Create a ConfigOption object.

        Parameters
        ----------
        name : Optional[str], optional
            Identifier of the option in the configuration file.
        default : Optional[Any], optional
            Default value for the case that the option is not set in the config file.
        missing : Optional[str], optional
            Action to take when the option is not set.
            'nothing' does nothing,
            'warn' logs a warning,
            'error' logs an error and prevents the module from loading.
        constructor : Optional[Callable], optional
            Constructor function for complex config option behavior.
        checker : Optional[Callable], optional
            Static function that checks if value is okay.
        converter : Optional[Callable], optional
            Static function that forces type interpretation.

        """
        self.missing = MissingOption[missing]

        self.name = name
        self.default = default
        self.checker = checker
        self.converter = converter
        self.constructor_function = None
        if constructor is not None:
            self.constructor(constructor)

    def __set_name__(self, owner, name):
        if self.name is None:
            self.name = name

    def __copy__(self):
        return self.copy()

    def __deepcopy__(self, memodict={}):
        return self.copy()

    @property
    def optional(self) -> bool:
        return self.missing != MissingOption.error



    def copy(self, **kwargs):
        """Create a new instance of ConfigOption with copied values and update.

        Parameters
        ----------
        **kwargs
            Extra arguments or overrides for the constructor of this class.
        """
        newargs = {
            "name": self.name,
            "default": copy.deepcopy(self.default),
            "missing": self.missing.name,
            "constructor": self.constructor_function,
            "checker": self.checker,
            "converter": self.converter,
        }
        newargs.update(kwargs)
        return ConfigOption(**newargs)




    def check(self, value: Any) -> bool:
        """If checker function set, check value. Assume everything is ok otherwise."""
        if callable(self.checker):
            return self.checker(value)
        return True




    def convert(self, value: Any) -> Any:
        """If converter function set, convert value (pass-through otherwise)."""
        if callable(self.converter):
            return self.converter(value)
        return value




    def constructor(self, func: Callable) -> Callable:
        """Decorator for declaring a constructor function for this ConfigOption.

        Parameters
        ----------
        func : Callable
            Constructor function for this ConfigOption.

        Returns
        -------
        Callable
            Returns the original function so it can be used as a decorator.
        """
        self.constructor_function = self._assert_func_signature(func)
        return func


    @staticmethod
    def _assert_func_signature(func: Callable) -> Callable:
        assert callable(func), "ConfigOption constructor must be callable"
        params = tuple(inspect.signature(func).parameters)
        assert 0 < len(params) < 3, (
            "ConfigOption constructor must be function with "
            "1 (static) or 2 (bound method) parameters."
        )
        if len(params) == 1:

            def wrapper(instance, value):
                return func(value)

            return wrapper
        return func