RFL.settings 1.0.0__py3-none-any.whl

RFL.settings-1.0.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.1
+Name: RFL.settings
+Version: 1.0.0
+Summary: Rackslab Foundation Library: settings package
+Author-email: Rémi Palancher <remi@rackslab.io>
+License: GPLv3+
+Project-URL: Homepage, https://github.com/rackslab/RFL
+Project-URL: Bug Tracker, https://github.com/rackslab/RFL/issues
+Keywords: utility,basic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: RFL.core
+Requires-Dist: PyYAML
+
+# RFL: settings package
+
+Manage configuration files settings.

RFL.settings-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+rfl/settings/__init__.py,sha256=Jge5Y06IjO2aki9gtmTZAiwk8hAUxtdUvWUh6W1tiI0,6074
+rfl/settings/definition.py,sha256=p8vdXRPh9H0HUFsZzYuFOeOziq0Ans9TCFKG642loNA,7077
+rfl/settings/errors.py,sha256=Zaoe_iIN4OT4J6u81X0J7BBQTGm67D9LWJcaNbC-wXU,355
+rfl/settings/loaders.py,sha256=3j3hBAiX0bvkRbgiyfp5BgTqy8foxL6Xd32XytZLgak,1152
+RFL.settings-1.0.0.dist-info/METADATA,sha256=ALFOW8AjwyagCUZLPz6VOYr0VFqmJcyMEauCreK0s5Y,827
+RFL.settings-1.0.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+RFL.settings-1.0.0.dist-info/top_level.txt,sha256=EIloiMrXuRz8n0vqkCE6NM9Ze1S2mrbCKBcdtWaM_og,4
+RFL.settings-1.0.0.dist-info/RECORD,,

RFL.settings-1.0.0.dist-info/WHEEL

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

RFL.settings-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rfl

rfl/settings/__init__.py

@@ -0,0 +1,151 @@
+# Copyright (c) 2023 Rackslab
+#
+# This file is part of RFL.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from pathlib import Path
+import urllib
+
+import logging
+
+from .definition import (
+    SettingsDefinition,
+    SettingsSectionDefinition,
+    SettingsParameterDefinition,
+    SettingsDefinitionLoaderYaml,
+)
+from .loaders import RuntimeSettingsSiteLoader, RuntimeSettingsSiteLoaderIni
+from .errors import SettingsOverrideError
+
+logger = logging.getLogger(__name__)
+
+
+class RuntimeSettingsSection:
+    def __init__(self, section: SettingsSectionDefinition):
+        self._name = section.name
+        for parameter in section.parameters:
+            setattr(self, parameter.name, parameter.default)
+
+
+class RuntimeSettings:
+    def __init__(self, definition: SettingsDefinition):
+        # set to hold all sections names
+        self._sections = set()
+        self._definition = definition
+        for section in definition.sections:
+            o_section = type(
+                f"{self.__class__.__name__}{section.name.capitalize()}",
+                (RuntimeSettingsSection,),
+                dict(),
+            )(section)
+            setattr(self, o_section._name, o_section)
+            self._sections.add(o_section._name)
+
+    def override(self, loader: RuntimeSettingsSiteLoader):
+        # load site ini file and check it matches definition
+        for section_name in loader.content.sections():
+            if not self._definition.has_section(section_name):
+                raise SettingsOverrideError(
+                    f"Section {section_name} loaded in settings overrides is not "
+                    "defined in settings definition"
+                )
+            section = self._definition.section(section_name)
+            for parameter_name in loader.content[section.name]:
+                if not section.has_parameter(parameter_name):
+                    raise SettingsOverrideError(
+                        f"Parameter {parameter_name} loaded in settings overrides is "
+                        f"not defined in section {section.name} of settings definition"
+                    )
+                parameter = section.parameter(parameter_name)
+                self._override_parameter(loader, section, parameter)
+
+        # check required parameters
+        self._check_required()
+
+    def _check_required(self):
+        """Verify that all parameters declared as required in settings definition are
+        properly defined with a real value or raise SettingsOverrideError."""
+        for section in self._definition.sections:
+            for parameter in section.parameters:
+                if (
+                    parameter.required
+                    and getattr(getattr(self, parameter.section), parameter.name)
+                    is None
+                ):
+                    raise SettingsOverrideError(
+                        f"Parameter {str(parameter)} is missing but required in "
+                        "settings overrides"
+                    )
+
+    def _override_parameter(
+        self,
+        loader: RuntimeSettingsSiteLoader,
+        section: SettingsSectionDefinition,
+        parameter: SettingsParameterDefinition,
+    ) -> None:
+        """Load value from INI file, convert it to expected type, verify it is a valid
+        choice and set corresponding object attribute. Special logic is applied for list
+        to iterate over the items."""
+        raw = loader.content[section.name].get(parameter.name)
+        if parameter._type == "list":
+            value = [
+                self._load_parameter_value(parameter, parameter.content, raw)
+                for raw in raw.strip().split("\n")
+            ]
+            for item in value:
+                self._validate_choice(parameter, item)
+        else:
+            value = self._load_parameter_value(parameter, parameter._type, raw)
+            self._validate_choice(parameter, value)
+        setattr(getattr(self, section.name), parameter.name, value)
+
+    def _load_parameter_value(self, parameter, _type: str, raw: str):
+        """Try to convert raw value to expected type or raise SettingsOverrideError."""
+        if _type == "path":
+            # Converting a string to a pathlib.Path basically never fails.
+            return Path(raw)
+        elif _type == "uri":
+            # Converting a string to a urllib.ParseResult basically never fails.
+            return urllib.parse.urlparse(raw)
+        elif _type == "int":
+            try:
+                return int(raw)
+            except ValueError as err:
+                raise SettingsOverrideError(
+                    f"Invalid integer value '{raw}' for {parameter} in site overrides"
+                ) from err
+        elif _type == "float":
+            try:
+                return float(raw)
+            except ValueError as err:
+                raise SettingsOverrideError(
+                    f"Invalid float value '{raw}' for {parameter} in site overrides"
+                ) from err
+        elif _type == "bool":
+            if raw.lower() in ["1", "yes", "true", "on"]:
+                return True
+            elif raw.lower() in ["0", "no", "false", "off"]:
+                return False
+            else:
+                raise SettingsOverrideError(
+                    f"Invalid boolean value '{raw}' for {parameter} in site overrides"
+                )
+        else:
+            # Return unmodified value
+            return raw
+
+    def _validate_choice(self, parameter, value):
+        """Validate value is in parameter choices or raise SettingsOverrideError."""
+        if parameter.choices is not None and value not in parameter.choices:
+            raise SettingsOverrideError(
+                f"Value {value} for parameter {parameter} in site overrides is "
+                f"not one of possible choices {parameter.choices}"
+            )
+
+    def override_ini(self, path: Path) -> None:
+        self.override(RuntimeSettingsSiteLoaderIni(path=path))
+
+    @classmethod
+    def yaml_definition(cls, path: Path):
+        return cls(SettingsDefinition(SettingsDefinitionLoaderYaml(path=path)))

rfl/settings/definition.py

@@ -0,0 +1,201 @@
+# Copyright (c) 2023 Rackslab
+#
+# This file is part of RFL.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from pathlib import Path
+import urllib
+
+import yaml
+
+from .errors import SettingsDefinitionError
+
+
+class SettingsDefinitionLoader:
+    pass
+
+
+class SettingsDefinitionLoaderYaml(SettingsDefinitionLoader):
+    def __init__(self, raw: str = None, path: Path = None):
+        try:
+            if raw is not None:
+                self.content = yaml.safe_load(raw)
+            elif path is not None:
+                try:
+                    with open(path) as fh:
+                        self.content = yaml.safe_load(fh)
+                except FileNotFoundError as err:
+                    raise SettingsDefinitionError(
+                        f"Settings definition file {path} not found"
+                    ) from err
+            else:
+                raise SettingsDefinitionError(
+                    "Either a raw string value or a path must be given to load YAML "
+                    "settings definition"
+                )
+        except yaml.parser.ParserError as err:
+            raise SettingsDefinitionError(
+                f"Invalid YAML settings definition: {str(err)}"
+            ) from err
+        except yaml.scanner.ScannerError as err:
+            raise SettingsDefinitionError(f"YAML scanner error: {str(err)}") from err
+
+
+class SettingsParameterDefinition:
+    # Map properties that can be found in definition file with corresponding
+    # object attributes names.
+    POSSIBLE_PROPERTIES = {
+        "type": "_type",
+        "content": "content",
+        "default": "default",
+        "choices": "choices",
+        "doc": "doc",
+        "ex": "example",
+        "required": "required",
+    }
+    EXPECTED_TYPES = {
+        "str": str,
+        "int": int,
+        "float": float,
+        "path": Path,
+        "bool": bool,
+        "uri": urllib.parse.ParseResult,
+        "list": list,
+    }
+
+    def __init__(self, section: str, name: str, properties: dict):
+        self.section = section
+        self.name = name
+
+        # Check for unsupported properties
+        unsupported_properties = list(
+            set(properties.keys()).difference(self.POSSIBLE_PROPERTIES.keys())
+        )
+        if len(unsupported_properties):
+            raise SettingsDefinitionError(
+                f"Unsupported properties found for {str(self)}: "
+                f"{','.join(unsupported_properties)}"
+            )
+
+        for _property, attribute in self.POSSIBLE_PROPERTIES.items():
+            value = None
+            if _property in properties:
+                value = properties[_property]
+            setattr(self, attribute, value)
+
+        # Check the type of defined parameter is actually supported
+        if self._type not in self.EXPECTED_TYPES:
+            raise SettingsDefinitionError(
+                f"Unsupported type {self._type} for {str(self)}"
+            )
+
+        # Check content property is defined for list and check content type is actually
+        # supported.
+        if self._type == "list":
+            if "content" not in properties:
+                raise SettingsDefinitionError(
+                    f"List content type for parameter {str(self)} must be defined"
+                )
+            elif self.content not in set(self.EXPECTED_TYPES.keys()) - {"list"}:
+                raise SettingsDefinitionError(
+                    f"Unsupported list content type {self.content} for {str(self)}"
+                )
+        # Check content property is not defined if not list
+        if "content" in properties and self._type != "list":
+            raise SettingsDefinitionError(
+                f"Content property is forbidden for parameter {str(self)} with type "
+                f"{self._type}"
+            )
+
+        # If the default value is defined, convert to the expected type and validate it
+        # is a valid choice.
+        if self.default is not None:
+            if self._type == "list":
+                if not isinstance(self.default, list):
+                    raise SettingsDefinitionError(
+                        f"Default value {self.default} for parameter {str(self)} is "
+                        "not a valid list"
+                    )
+                self.default = [
+                    self._load_default(self.content, default)
+                    for default in self.default
+                ]
+                for item in self.default:
+                    self._validate_choice(item)
+            else:
+                self.default = self._load_default(self._type, self.default)
+                self._validate_choice(self.default)
+
+        if self.required is None:
+            self.required = False
+        elif not isinstance(self.required, bool):
+            raise SettingsDefinitionError(
+                f"Invalid boolean value of {str(self)} required property"
+            )
+
+    def _load_default(self, _type, default):
+        """Verify default has the expected type and convert to advanded type if
+        needed."""
+        if _type == "path":
+            return Path(default)
+        elif _type == "uri":
+            return urllib.parse.urlparse(default)
+        if not isinstance(default, self.EXPECTED_TYPES[_type]):
+            raise SettingsDefinitionError(
+                f"Default value {default} for parameter {str(self)} has not "
+                f"the expected type {_type}"
+            )
+        return default
+
+    def _validate_choice(self, default):
+        """Check default is a valid choice or raise SettingsDefinitionError."""
+        if self.choices is not None and default not in self.choices:
+            raise SettingsDefinitionError(
+                f"Default value {default} for parameter {str(self)} is not "
+                f"one of possible choices {self.choices}"
+            )
+
+    def __str__(self):
+        return f"[{self.section}]>{self.name}"
+
+
+class SettingsSectionDefinition:
+    def __init__(self, section: str, parameters: dict):
+        self.name = section
+        self.parameters = [
+            SettingsParameterDefinition(section, parameter, properties)
+            for parameter, properties in parameters.items()
+        ]
+
+    def has_parameter(self, name: str) -> bool:
+        for parameter in self.parameters:
+            if parameter.name == name:
+                return True
+        return False
+
+    def parameter(self, name: str):
+        for parameter in self.parameters:
+            if parameter.name == name:
+                return parameter
+        return None
+
+
+class SettingsDefinition:
+    def __init__(self, loader: SettingsDefinitionLoader):
+        self.sections = [
+            SettingsSectionDefinition(section, parameters)
+            for section, parameters in loader.content.items()
+        ]
+
+    def has_section(self, name: str) -> bool:
+        for section in self.sections:
+            if section.name == name:
+                return True
+        return False
+
+    def section(self, name: str):
+        for section in self.sections:
+            if section.name == name:
+                return section
+        return None

rfl/settings/errors.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2023 Rackslab
+#
+# This file is part of RFL.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from rfl.core.errors import RFLError
+
+
+class SettingsError(RFLError):
+    pass
+
+
+class SettingsDefinitionError(SettingsError):
+    pass
+
+
+class SettingsSiteLoaderError(SettingsError):
+    pass
+
+
+class SettingsOverrideError(SettingsError):
+    pass

rfl/settings/loaders.py

@@ -0,0 +1,38 @@
+# Copyright (c) 2023 Rackslab
+#
+# This file is part of RFL.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import configparser
+from pathlib import Path
+import logging
+
+from .errors import SettingsSiteLoaderError
+
+logger = logging.getLogger(__name__)
+
+
+class RuntimeSettingsSiteLoader:
+    pass
+
+
+class RuntimeSettingsSiteLoaderIni(RuntimeSettingsSiteLoader):
+    def __init__(self, raw: str = None, path: Path = None):
+        self.content = configparser.ConfigParser(
+            interpolation=configparser.ExtendedInterpolation()
+        )
+        try:
+            if raw is not None:
+                logger.debug("Loading site settings in INI format from raw value")
+                self.content.read_string(raw)
+            elif path is not None:
+                logger.debug("Loading site settings file %s", path)
+                self.content.read(path)
+            else:
+                raise SettingsSiteLoaderError(
+                    "Either a raw string value or a path must be given to load site "
+                    "settings"
+                )
+        except configparser.Error as error:
+            raise SettingsSiteLoaderError(error)