cgse-common 2023.1.4__py3-none-any.whl → 2024.1.4__py3-none-any.whl

egse/metrics.py

@@ -0,0 +1,106 @@
+import logging
+from typing import Optional
+
+import numpy as np
+from prometheus_client import Gauge
+
+from egse.hk import TmDictionaryColumns
+from egse.settings import Settings
+from egse.setup import SetupError, load_setup, Setup
+
+LOGGER = logging.getLogger(__name__)
+SITE_ID = Settings.load("SITE").ID
+
+
+def define_metrics(origin: str, dashboard: str = None, use_site: bool = False, setup: Optional[Setup] = None) -> dict:
+    """ Creates a metrics dictionary from the telemetry dictionary.
+
+    Read the metric names and their descriptions from the telemetry dictionary, and create Prometheus gauges based on
+    this information.
+
+    If `dashboard` is not provided, all telemetry parameters for the given origin will be returned.
+
+    Args:
+        origin: Storage mnemonics for the requested metrics
+        dashboard: Restrict the metrics selection to those that are defined for the given dashboard. You can select
+                   all dashboards with `dashboard='*'`.
+        use_site: Indicate whether the prefixes of the new HK names are TH-specific
+        setup: Setup.
+
+    Returns: Dictionary with all Prometheus gauges for the given origin and dashboard.
+    """
+
+    setup = setup or load_setup()
+
+    try:
+        hk_info_table = setup.telemetry.dictionary
+    except AttributeError:
+        raise SetupError("Version of the telemetry dictionary not specified in the current setup")
+
+    hk_info_table = hk_info_table.replace(np.nan, "")
+
+    storage_mnemonic = hk_info_table[TmDictionaryColumns.STORAGE_MNEMONIC].values
+    hk_names = hk_info_table[TmDictionaryColumns.CORRECT_HK_NAMES].values
+    descriptions = hk_info_table[TmDictionaryColumns.DESCRIPTION].values
+    mon_screen = hk_info_table[TmDictionaryColumns.DASHBOARD].values
+
+    condition = storage_mnemonic == origin.upper()
+    if dashboard is not None:
+        if dashboard == "*":
+            extra_condition = mon_screen != ""
+        else:
+            extra_condition = mon_screen == dashboard.upper()
+        condition = np.all((condition, extra_condition), axis=0)
+
+    selection = np.where(condition)
+
+    syn_names = hk_names[selection]
+    descriptions = descriptions[selection]
+
+    if not use_site:
+        metrics = {}
+
+        for syn_name, description in zip(syn_names, descriptions):
+            try:
+                metrics[syn_name] = Gauge(syn_name, description)
+            except ValueError:
+                LOGGER.warning(f"ValueError for {syn_name}")
+
+        return metrics
+
+    th_prefix = f"G{SITE_ID}_"
+
+    th_syn_names = []
+    th_descriptions = []
+    for syn_name, description in zip(syn_names, descriptions):
+        if syn_name.startswith(th_prefix):
+            th_syn_names.append(syn_name)
+            th_descriptions.append(description)
+
+    return {
+        syn_name: Gauge(syn_name, description)
+        for syn_name, description in zip(th_syn_names, th_descriptions)
+    }
+
+
+def update_metrics(metrics: dict, updates: dict):
+    """ Updates the metrics parameters with the values from the updates dictionary.
+
+    Only the metrics parameters for which the names are keys in the given updates dict are actually updated. Other
+    metrics remain untouched.
+
+    The functions log a warning when the updates dict contains a name which is not known as a metrics parameter.
+
+    Args:
+        metrics: Metrics dictionary previously defined with the define_metrics function
+        updates: Dictionary with key=metrics name and value is the to-be-updated value
+    """
+
+    for metric_name, value in updates.items():
+        try:
+            if value is None:
+                metrics[metric_name].set(float('nan'))
+            else:
+                metrics[metric_name].set(float(value))
+        except KeyError:
+            LOGGER.warning(f"Unknown metric name: {metric_name=}")

egse/monitoring.py

@@ -90,6 +90,7 @@ def monitoring(hostname: str, port: int, subscribe: str, multipart: bool, use_pi
     receiver.close(linger=0)
     context.term()
 
+
 if __name__ == "__main__":
     multiprocessing.current_process().name = "Monitoring"
     monitoring()

egse/resource.py

@@ -75,20 +75,25 @@ their functionality is fully replaced by this `egse.resource` module.
 
 """
 
+import errno
 import logging
 import re
 from pathlib import Path
+from pathlib import PurePath
 from typing import Dict
 from typing import List
 from typing import Union
 
+from os.path import exists
+from os.path import join
+
 from egse.config import find_first_occurrence_of_dir
 from egse.config import find_files
 from egse.exceptions import InternalError
 from egse.plugin import entry_points
 from egse.system import get_package_location
 
-LOGGER = logging.getLogger(__name__)
+_LOGGER = logging.getLogger(__name__)
 
 
 class ResourceError(Exception):
@@ -106,6 +111,8 @@ class NoSuchFileError(ResourceError):
 __all__ = [
     "get_resource",
     "get_resource_locations",
+    "get_resource_dirs",
+    "get_resource_path",
     "add_resource_id",
     "initialise_resources",
     "ResourceError",
@@ -129,6 +136,8 @@ DEFAULT_RESOURCES = {
     "data": "/data",
 }
 
+_RESOURCE_DIRS = ["resources", "icons", "images", "styles", "data"]
+
 resources = {}
 
 
@@ -180,6 +189,65 @@ def get_resource_locations() -> Dict[str, List[Path]]:
     return resources.copy()
 
 
+def get_resource_dirs(root_dir: Union[str, PurePath]) -> List[Path]:
+    """
+    Define directories that contain resources like images, icons, and data files.
+
+    Resource directories can have the following names: `resources`, `data`, `icons`, or `images`.
+    This function checks if any of the resource directories exist in the `root_dir` that is given as an argument.
+
+    For all existing directories the function returns the absolute path.
+
+    If the argument root_dir is None, an empty list will be returned and a warning message will be issued.
+
+    Args:
+        root_dir (str): the directory to search for resource folders
+
+    Returns:
+        a list of absolute Paths.
+    """
+
+    if root_dir is None:
+        _LOGGER.warning("The argument root_dir can not be None, an empty list is returned.")
+        return []
+
+    root_dir = Path(root_dir).resolve()
+    if not root_dir.is_dir():
+        root_dir = root_dir.parent
+
+    result = []
+    for dir_ in _RESOURCE_DIRS:
+        if (root_dir / dir_).is_dir():
+            result.append(Path(root_dir, dir_).resolve())
+
+    return result
+
+
+def get_resource_path(name: str, resource_root_dir: Union[str, PurePath] = None) -> PurePath:
+    """
+    Searches for a data file (resource) with the given name.
+
+    When `resource_root_dir` is not given, the search for resources will start at the root
+    folder of the project (using the function `get_common_egse_root()`). Any other root
+    directory can be given, e.g. if you want to start the search from the location of your
+    source code file, use `Path(__file__).parent` as the `resource_root_dir` argument.
+
+    Args:
+        name (str): the name of the resource that is requested
+        resource_root_dir (str): the root directory w_HERE the search for resources should be started
+
+    Returns:
+        the absolute path of the data file with the given name. The first name that matches
+        is returned. If no file with the given name or path exists, a FileNotFoundError is raised.
+
+    """
+    for resource_dir in get_resource_dirs(resource_root_dir):
+        resource_path = join(resource_dir, name)
+        if exists(resource_path):
+            return Path(resource_path).absolute()
+    raise FileNotFoundError(errno.ENOENT, f"Could not locate resource '{name}'")
+
+
 def initialise_resources(root: Union[Path, str] = Path(__file__).parent):
     """
     Initialise the default resources and any resource published by a package entry point.
@@ -215,7 +283,7 @@ def initialise_resources(root: Union[Path, str] = Path(__file__).parent):
             if location not in x:
                 x.append(location)
 
-    LOGGER.debug(f"Resources have been initialised: {resources = }")
+    _LOGGER.debug(f"Resources have been initialised: {resources = }")
 
 
 def print_resources():

egse/response.py

@@ -0,0 +1,101 @@
+"""
+This module provides functionality to handle responses from the control servers.
+"""
+__all__ = [
+    "Success",
+    "Failure",
+    "Message",
+]
+
+from typing import Any
+
+import rich.repr
+
+
+class Response:
+    """
+    Base class for any reply or response between client-server communication.
+
+    The idea is that the response is encapsulated in one of the subclasses depending
+    on the type of response.
+    """
+
+    def __init__(self, message: str):
+        self.message = message
+
+    def __str__(self):
+        return self.message
+
+    @property
+    def successful(self):
+        """Returns True if the Response is not an Exception."""
+        return not isinstance(self, Exception)
+
+
+@rich.repr.auto
+class Failure(Response, Exception):
+    """
+    A failure response indicating something went wrong at the other side.
+
+    This class is used to encapsulate an Exception that was caught and needs to be
+    passed to the client. So, the intended use is like this:
+
+        try:
+            # perform some useful action that might raise an Exception
+        except SomeException as exc:
+            return Failure("Our action failed", exc)
+
+    The client can inspect the Exception that was originally raised, in this case `SomeException`
+    with the `cause` variable.
+
+    Since a Failure is also an Exception, the property `successful` will return False.
+    So, the calling method can test for this easily.
+
+        rc: Response = function_that_returns_a_response()
+
+        if not rc.successful:
+            # handle the failure
+        else:
+            # handle success
+
+    """
+
+    def __init__(self, message: str, cause: Exception = None):
+        msg = f"{message}: {cause}" if cause is not None else message
+        super().__init__(msg)
+        self.cause = cause
+
+
+@rich.repr.auto
+class Success(Response):
+    """
+    A success response for the client.
+
+    The return code from any action or function that needs to be returned to the
+    client shall be added.
+
+    Since `Success` doesn't inherit from `Exception`, the property `successful` will return True.
+    """
+
+    def __init__(self, message: str, return_code: Any = None):
+        msg = f"{message}: {return_code}" if return_code is not None else message
+        super().__init__(msg)
+        self.return_code = return_code
+
+    @property
+    def response(self):
+        return self.return_code
+
+
+@rich.repr.auto
+class Message(Response):
+    """
+    A message response from the client.
+
+    Send a Message when there is no Failure, but also no return code. This is the alternative of
+    returning a None.
+
+    Message returns True for the property successful since it doesn't inherit from Exception.
+    """
+
+    pass

egse/settings.py

@@ -62,14 +62,15 @@ import re
 
 import yaml  # This module is provided by the pip package PyYaml - pip install pyyaml
 
-from egse.env import ENV_PLATO_LOCAL_SETTINGS
+from egse.env import get_local_settings
+from egse.env import get_local_settings_env_name
 from egse.exceptions import FileIsEmptyError
 from egse.system import AttributeDict
 from egse.system import get_caller_info
 from egse.system import ignore_m_warning
 from egse.system import recursive_dict_update
 
-logger = logging.getLogger(__name__)
+_LOGGER = logging.getLogger(__name__)
 
 
 class SettingsError(Exception):
@@ -145,13 +146,13 @@ class Settings:
         """
         if force or filename not in cls.__memoized_yaml:
 
-            logger.debug(f"Parsing YAML configuration file {filename}.")
+            _LOGGER.debug(f"Parsing YAML configuration file {filename}.")
 
             with open(filename, "r") as stream:
                 try:
                     yaml_document = yaml.load(stream, Loader=SAFE_LOADER)
                 except yaml.YAMLError as exc:
-                    logger.error(exc)
+                    _LOGGER.error(exc)
                     raise SettingsError(f"Error loading YAML document {filename}") from exc
 
             cls.__memoized_yaml[filename] = yaml_document
@@ -216,13 +217,13 @@ class Settings:
 
             yaml_location = pathlib.Path(location).resolve()
 
-        logger.log(5, f"yaml_location in Settings.load(location={location}) is {yaml_location}")
+        _LOGGER.debug(f"yaml_location in Settings.load(location={location}) is {yaml_location}")
 
         # Load the YAML global document
 
         try:
             yaml_document_global = cls.read_configuration_file(
-                yaml_location / filename, force=force
+                str(yaml_location / filename), force=force
             )
         except FileNotFoundError as exc:
             raise SettingsError(
@@ -236,31 +237,32 @@ class Settings:
 
         # Load the LOCAL settings YAML file
 
+        local_settings = {}
+
         if add_local_settings:
             try:
-                local_settings_location = os.environ[ENV_PLATO_LOCAL_SETTINGS]
-                logger.log(5, f"Using {ENV_PLATO_LOCAL_SETTINGS} to update global settings.")
-                try:
-                    yaml_document_local = cls.read_configuration_file(
-                        local_settings_location, force=force
-                    )
-                    if yaml_document_local is None:
-                        raise FileIsEmptyError()
-                    local_settings = AttributeDict(
-                        {name: value for name, value in yaml_document_local.items()}
-                    )
-                except FileNotFoundError as exc:
-                    raise SettingsError(
-                        f"Local settings YAML file '{local_settings_location}' not found. "
-                        f"Check your environment variable {ENV_PLATO_LOCAL_SETTINGS}."
-                    ) from exc
-                except FileIsEmptyError:
-                    logger.warning(f"Local settings YAML file '{local_settings_location}' is empty. "
-                                   f"No local settings were loaded.")
-                    local_settings = {}
+                local_settings_location = get_local_settings()
+                if local_settings_location:
+                    _LOGGER.debug(f"Using {local_settings_location} to update global settings.")
+                    try:
+                        yaml_document_local = cls.read_configuration_file(
+                            local_settings_location, force=force
+                        )
+                        if yaml_document_local is None:
+                            raise FileIsEmptyError()
+                        local_settings = AttributeDict(
+                            {name: value for name, value in yaml_document_local.items()}
+                        )
+                    except FileNotFoundError as exc:
+                        raise SettingsError(
+                            f"Local settings YAML file '{local_settings_location}' not found. "
+                            f"Check your environment variable {get_local_settings_env_name()}."
+                        ) from exc
+                    except FileIsEmptyError:
+                        _LOGGER.warning(f"Local settings YAML file '{local_settings_location}' is empty. "
+                                       f"No local settings were loaded.")
             except KeyError:
-                logger.debug(f"The environment variable {ENV_PLATO_LOCAL_SETTINGS} is not defined.")
-                local_settings = {}
+                _LOGGER.debug(f"The environment variable {get_local_settings_env_name()} is not defined.")
 
         if group_name in (None, ""):
             global_settings = AttributeDict(
@@ -321,7 +323,7 @@ class Settings:
         return cls.__profile
 
     @classmethod
-    def set_simulation_mode(cls, flag: bool) -> bool:
+    def set_simulation_mode(cls, flag: bool):
         cls.__simulation = flag
 
     @classmethod
@@ -346,7 +348,7 @@ if __name__ == "__main__":
     parser = argparse.ArgumentParser(
         description=(
             f"Print out the default Settings, updated with local settings if the "
-            f"{ENV_PLATO_LOCAL_SETTINGS} environment variable is set."
+            f"{get_local_settings_env_name()} environment variable is set."
         ),
     )
     parser.add_argument("--local", action="store_true", help="print only the local settings.")
@@ -358,7 +360,7 @@ if __name__ == "__main__":
     from rich import print
 
     if args.local:
-        location = os.environ.get(ENV_PLATO_LOCAL_SETTINGS)
+        location = get_local_settings()
         if location:
             settings = Settings.load(filename=location)
             print(settings)