cgse-common 2025.0.4__tar.gz → 2025.0.6__tar.gz

{cgse_common-2025.0.4 → cgse_common-2025.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cgse-common
-Version: 2025.0.4
+Version: 2025.0.6
 Summary: Software framework to support hardware testing
 Author: IVS KU Leuven
 Maintainer-email: Rik Huygen <rik.huygen@kuleuven.be>, Sara Regibo <sara.regibo@kuleuven.be>

{cgse_common-2025.0.4 → cgse_common-2025.0.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cgse-common"
-version = "2025.0.4"
+version = "2025.0.6"
 description = "Software framework to support hardware testing"
 authors = [
     {name = "IVS KU Leuven"}
@@ -36,10 +36,13 @@ dependencies = [
 [project.entry-points."cgse.version"]
 cgse-common = 'egse'
 
+[project.entry-points."cgse.settings"]
+cgse-common = "cgse_common:settings.yaml"
+
 [tool.pytest.ini_options]
 pythonpath = "src"
 testpaths = ["tests"]
-addopts = "-ra --cov --cov-report html"
+addopts = "-ra --cov --cov-branch --cov-report html"
 filterwarnings = [
     "ignore::DeprecationWarning"
 ]
@@ -47,6 +50,7 @@ filterwarnings = [
 [tool.coverage.run]
 omit = [
     "tests/*",
+    "conftest.py",
 ]
 
 [tool.hatch.build.targets.sdist]
@@ -59,7 +63,7 @@ exclude = [
 ]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/egse"]
+packages = ["src/egse", "src/cgse-common"]
 
 [tool.ruff]
 line-length = 120

{cgse_common-2025.0.4/src/egse → cgse_common-2025.0.6/src/cgse_common}/settings.yaml

@@ -1,5 +1,8 @@
+PACKAGES:
+    CGSE_COMMON: Common classes, functions, decorators, etc. for the CGSE
+
 SITE:
-    ID:                            XXX
+    ID:                           XXXX         # The SITE ID shall be filled in by the local settings file
     SSH_SERVER:              localhost         # The IP address of the SSH server on your site
     SSH_PORT:                       22         # The TCP/IP port on which the SSH server is listening
 

{cgse_common-2025.0.4 → cgse_common-2025.0.6}/src/egse/control.py

@@ -5,7 +5,6 @@ import abc
 import logging
 import pickle
 import threading
-from typing import Any
 
 import zmq
 

{cgse_common-2025.0.4 → cgse_common-2025.0.6}/src/egse/decorators.py

@@ -10,6 +10,8 @@ import warnings
 from typing import Callable
 from typing import Optional
 
+import rich
+
 from egse.settings import Settings
 from egse.system import get_caller_info
 
@@ -227,7 +229,14 @@ def profile_func(output_file=None, sort_by='cumulative', lines_to_print=None, st
 
 
 def profile(func):
-    """Print the function signature and return value"""
+    """
+    Prints the function signature and return value to stdout.
+
+    This function checks the `Settings.profiling()` value and only prints out
+    profiling information if this returns True.
+
+    Profiling can be activated with `Settings.set_profiling(True)`.
+    """
     if not hasattr(profile, "counter"):
         profile.counter = 0
 
@@ -240,10 +249,10 @@ def profile(func):
             signature = ", ".join(args_repr + kwargs_repr)
             caller = get_caller_info(level=2)
             prefix = f"PROFILE[{profile.counter}]: "
-            _LOGGER.info(f"{prefix}Calling {func.__name__}({signature})")
-            _LOGGER.info(f"{prefix}    from {caller.filename} at {caller.lineno}.")
+            rich.print(f"{prefix}Calling {func.__name__}({signature})")
+            rich.print(f"{prefix}    from {caller.filename} at {caller.lineno}.")
             value = func(*args, **kwargs)
-            _LOGGER.info(f"{prefix}{func.__name__!r} returned {value!r}")
+            rich.print(f"{prefix}{func.__name__!r} returned {value!r}")
             profile.counter -= 1
         else:
             value = func(*args, **kwargs)

{cgse_common-2025.0.4 → cgse_common-2025.0.6}/src/egse/env.py

@@ -40,32 +40,38 @@ WARNING:
 from __future__ import annotations
 
 __all__ = [
-    "get_project_name",
-    "get_site_id",
-    "get_data_storage_location",
-    "set_data_storage_location",
-    "get_data_storage_location_env_name",
+    "env_var",
     "get_conf_data_location",
-    "set_conf_data_location",
     "get_conf_data_location_env_name",
     "get_conf_repo_location",
-    "set_conf_repo_location",
     "get_conf_repo_location_env_name",
+    "get_data_storage_location",
+    "get_data_storage_location_env_name",
+    "get_local_settings_path",
+    "get_local_settings_env_name",
     "get_log_file_location",
-    "set_log_file_location",
     "get_log_file_location_env_name",
-    "get_local_settings",
+    "get_project_name",
+    "get_site_id",
+    "set_conf_data_location",
+    "set_conf_repo_location",
+    "set_data_storage_location",
     "set_local_settings",
-    "get_local_settings_env_name",
+    "set_log_file_location",
 ]
 
+import contextlib
 import os
 import warnings
 from pathlib import Path
 
 from egse.system import all_logging_disabled
+from egse.system import get_caller_info
 from egse.system import ignore_m_warning
 
+from rich.console import Console
+console = Console(width=100)
+
 # Every project shall have a PROJECT and a SITE_ID environment variable set. This variable will be used to
 # create the other environment variables that are specific to the project.
 
@@ -123,11 +129,18 @@ class _Env:
         self._env = {}
 
     def set(self, key, value):
-        self._env[key] = value
+        if value is None:
+            if key in self._env:
+                del self._env[key]
+        else:
+            self._env[key] = value
 
     def get(self, key) -> str:
         return self._env.get(key, NoValue())
 
+    def __rich__(self):
+        return self._env
+
 
 _env = _Env()
 
@@ -159,28 +172,60 @@ def _check_no_value(var_name, value):
     """Raise a ValueError when the value for the variable is NoValue."""
     if value == NoValue():
         project = _env.get("PROJECT")
-        env_name = var_name if var_name == "SITE_ID" else f"{project}_{var_name}"
+        env_name = var_name if var_name in ("PROJECT", "SITE_ID") else f"{project}_{var_name}"
         raise ValueError(
             f"The environment variable {env_name} is not set. "
             f"Please set the environment variable before proceeding."
         )
 
 
+def set_default_environment(
+        project: str,
+        site_id: str,
+        data_storage_location: str | Path,
+        conf_data_location: str | Path | None = None,
+        conf_repo_location: str | Path | None = None,
+        log_file_location: str | Path | None = None,
+        local_settings: str | Path | None = None,
+):
+    set_project_name(project)
+    set_site_id(site_id)
+    set_data_storage_location(data_storage_location)
+    set_conf_data_location(conf_data_location)
+    set_conf_repo_location(conf_repo_location)
+    set_log_file_location(log_file_location)
+    set_local_settings(local_settings)
+
+
 def get_project_name():
+    """Get the PROJECT name. Return None when the PROJECT is not set."""
     return _env.get("PROJECT") or None
 
 
+def set_project_name(name: str):
+    """Set the environment variable PROJECT and its internal representation."""
+    os.environ["PROJECT"] = name
+    _env.set("PROJECT", name)
+
+
 def get_site_id():
+    """Get the SITE_ID. Return None if the SITE_ID is not set."""
     return _env.get("SITE_ID") or None
 
 
+def set_site_id(name: str):
+    """Set the environment variable SITE_ID and its internal representation."""
+    os.environ["SITE_ID"] = name
+    _env.set("SITE_ID", name)
+
+
 def get_data_storage_location_env_name() -> str:
     """Returns the name of the environment variable for the project."""
     project = _env.get("PROJECT")
     return f"{project}_DATA_STORAGE_LOCATION"
 
 
-def set_data_storage_location(location: str | Path):
+def set_data_storage_location(location: str | Path | None):
     """
     Sets the environment variable and the internal representation to the given value.
 
@@ -189,14 +234,19 @@ def set_data_storage_location(location: str | Path):
     """
     env_name = get_data_storage_location_env_name()
 
-    # Check if location exists and is readable
+    if location is None:
+        if env_name in os.environ:
+            del os.environ[env_name]
+        _env.set("DATA_STORAGE_LOCATION", None)
+        return
+
     if not Path(location).exists():
         warnings.warn(
             f"The location you provided for the environment variable {env_name} doesn't exist: {location}."
         )
 
-    os.environ[env_name] = location
-    _env.set('DATA_STORAGE_LOCATION', location)
+    os.environ[env_name] = str(location)
+    _env.set('DATA_STORAGE_LOCATION', str(location))
 
 
 def get_data_storage_location(site_id: str = None) -> str:
@@ -223,6 +273,9 @@ def get_data_storage_location(site_id: str = None) -> str:
     """
     global _env
 
+    project = _env.get("PROJECT")
+    _check_no_value("PROJECT", project)
+
     site_id = site_id or _env.get("SITE_ID")
     _check_no_value("SITE_ID", site_id)
 
@@ -240,7 +293,7 @@ def get_conf_data_location_env_name() -> str:
     return f"{project}_CONF_DATA_LOCATION"
 
 
-def set_conf_data_location(location: str | Path):
+def set_conf_data_location(location: str | Path | None):
     """
     Sets the environment variable and the internal representation to the given value.
 
@@ -250,7 +303,12 @@ def set_conf_data_location(location: str | Path):
 
     env_name = get_conf_data_location_env_name()
 
-    # Check if location exists and is readable
+    if location is None:
+        if env_name in os.environ:
+            del os.environ[env_name]
+        _env.set("CONF_DATA_LOCATION", None)
+        return
+
     if not Path(location).exists():
         warnings.warn(
             f"The location you provided for the environment variable {env_name} doesn't exist: {location}."
@@ -303,7 +361,7 @@ def get_log_file_location_env_name():
     return f"{project}_LOG_FILE_LOCATION"
 
 
-def set_log_file_location(location: str | Path):
+def set_log_file_location(location: str | Path | None):
     """
     Sets the environment variable and the internal representation to the given value.
 
@@ -313,7 +371,12 @@ def set_log_file_location(location: str | Path):
 
     env_name = get_log_file_location_env_name()
 
-    # Check if location exists and is readable
+    if location is None:
+        if env_name in os.environ:
+            del os.environ[env_name]
+        _env.set("LOG_FILE_LOCATION", None)
+        return
+
     if not Path(location).exists():
         warnings.warn(
             f"The location you provided for the environment variable {env_name} doesn't exist: {location}."
@@ -365,17 +428,24 @@ def get_local_settings_env_name() -> str:
     return f"{project}_LOCAL_SETTINGS"
 
 
-def set_local_settings(path: str | Path):
+def set_local_settings(path: str | Path | None):
     """
     Sets the environment variable and the internal representation to the given value.
 
+    When the path is set to None, the environment variable will be unset.
+
     Warnings:
         Issues a warning when the given path doesn't exist.
     """
 
     env_name = get_local_settings_env_name()
 
-    # Check if location exists and is readable
+    if path is None:
+        if env_name in os.environ:
+            del os.environ[env_name]
+        _env.set('LOCAL_SETTINGS', None)
+        return
+
     if not Path(path).exists():
         warnings.warn(
             f"The location you provided for the environment variable {env_name} doesn't exist: {path}."
@@ -385,18 +455,35 @@ def set_local_settings(path: str | Path):
     _env.set('LOCAL_SETTINGS', path)
 
 
-def get_local_settings() -> str:
-    """Returns the fully qualified filename of the local settings YAML file."""
+def get_local_settings_path() -> str or None:
+    """
+    Returns the fully qualified filename of the local settings YAML file. When the local settings environment
+    variable is not defined or is an empty string, None is returned.
+
+    Warnings:
+        - When the local settings environment variable is not defined, or
+        - when the path defined by the environment variable doesn't exist.
+    """
 
     local_settings = _env.get("LOCAL_SETTINGS")
 
-    if local_settings and not Path(local_settings).exists():
+    if not local_settings:
+        warnings.warn(f"The local settings environment variable '{get_local_settings_env_name()}' "
+                      f"is not defined or is an empty string.")
+        return None
+
+    if not Path(local_settings).exists():
         warnings.warn(
-            f"The local settings '{local_settings}' doesn't exist. As a result, "
+            f"The local settings path '{local_settings}' doesn't exist. As a result, "
             f"the local settings for your project will not be loaded."
         )
 
-    return local_settings or None
+    return local_settings
+
+
+def has_conf_repo_location() -> bool:
+    location = _env.get("CONF_REPO_LOCATION")
+    return True if location else False
 
 
 def get_conf_repo_location_env_name() -> str:
@@ -405,28 +492,50 @@ def get_conf_repo_location_env_name() -> str:
     return f"{project}_CONF_REPO_LOCATION"
 
 
-def get_conf_repo_location() -> str:
-    """Returns the fully qualified name of the location of the repository with configuration and calibration data."""
+def get_conf_repo_location() -> str | None:
+    """
+    Returns the fully qualified name of the location of the repository with
+    configuration and calibration data.
+
+    Returns None if no environment variable was defined or if the location doesn't exist.
+    In both cases a Warning is issued.
+    """
 
     location = _env.get("CONF_REPO_LOCATION")
 
-    if location and not Path(location).exists():
+    if location in (None, NoValue()):
+        warnings.warn(
+            f"The environment variable for the configuration data repository is "
+            f"not defined ({get_conf_repo_location_env_name()})."
+        )
+        return None
+
+    if not Path(location).exists():
         warnings.warn(f"The location of the configuration data repository doesn't exist: {location}.")
+        return None
 
-    return location or None
+    return location
 
 
-def set_conf_repo_location(location: str):
+def set_conf_repo_location(location: str | Path | None):
     """
     Sets the environment variable and the internal representation to the given value.
 
+    When the location is None, the environment variable will be unset and its internal
+    representation will be NoValue().
+
     Warnings:
         Issues a warning when the given location doesn't exist.
     """
 
     env_name = get_conf_repo_location_env_name()
 
-    # Check if location exists and is readable
+    if location is None:
+        if env_name in os.environ:
+            del os.environ[env_name]
+        _env.set("CONF_REPO_LOCATION", None)
+        return
+
     if not Path(location).exists():
         warnings.warn(
             f"The location you provided for the environment variable {env_name} doesn't exist: {location}."
@@ -436,7 +545,69 @@ def set_conf_repo_location(location: str):
     _env.set('CONF_REPO_LOCATION', location)
 
 
-ignore_m_warning('egse.env')
+def print_env():
+    """
+    Prints out the mandatory and known environment variables at the time of the
+    function call. The function and lineno is also printed for information.
+    """
+    col_width = 30
+
+    console = Console(width=200)
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        caller_info = get_caller_info(level=2)
+        console.print(f"[b]Environment as in {caller_info.filename}:{caller_info.lineno}[/]")
+        console.print(f"  {'PROJECT':{col_width}s}: {get_project_name()}")
+        console.print(f"  {'SITE_ID':{col_width}s}: {get_site_id()}")
+        console.print(f"  {get_data_storage_location_env_name():{col_width}s}: {get_data_storage_location()}")
+        console.print(f"  {get_log_file_location_env_name():{col_width}s}: {get_log_file_location()}")
+        console.print(f"  {get_conf_data_location_env_name():{col_width}s}: {get_conf_data_location()}")
+        console.print(f"  {get_conf_repo_location_env_name():{col_width}s}: {get_conf_repo_location()}")
+        console.print(f"  {get_local_settings_env_name():{col_width}s}: {get_local_settings_path()}")
+
+
+@contextlib.contextmanager
+def env_var(**kwargs):
+    """
+    Context manager to run some code that need alternate settings for environment variables.
+    This will automatically initialize the CGSE environment upon entry and re-initialize upon exit.
+
+    NOTE: This context manager is different from the one from `egse.system` because of the CGSE environment changes.
+
+    Args:
+        **kwargs: dictionary with environment variables that are needed
+
+    Examples:
+
+        >>> from egse.env import env_var
+        >>> with env_var(PLATO_DATA_STORAGE_LOCATION="/Users/rik/data"):
+        ...    # do stuff that needs these alternate setting
+        ...    pass
+
+    """
+    saved_env = {}
+
+    for k, v in kwargs.items():
+        saved_env[k] = os.environ.get(k)
+        if v is None:
+            if k in os.environ:
+                del os.environ[k]
+        else:
+            os.environ[k] = v
+
+    initialize()
+
+    yield
+
+    for k, v in saved_env.items():
+        if v is None:
+            if k in os.environ:
+                del os.environ[k]
+        else:
+            os.environ[k] = v
+
+    initialize()
 
 
 def main(args: list | None = None):  # pragma: no cover
@@ -517,8 +688,10 @@ def main(args: list | None = None):  # pragma: no cover
             location = get_data_storage_location()
             if not Path(location).exists():
                 if args.mkdir:
-                    rich.print(f"  [green]⟶ Creating data storage location: {location}[/]")
+                    rich.print(f"  [green]⟶ Creating data storage location: {location} (+ daily + obs)[/]")
                     Path(location).mkdir(parents=True)
+                    (Path(location) / "daily").mkdir()
+                    (Path(location) / "obs").mkdir()
                 else:
                     rich.print("  [red]⟶ ERROR: The data storage location doesn't exist![/]")
             else:
@@ -540,6 +713,16 @@ def main(args: list | None = None):  # pragma: no cover
         except ValueError as exc:
             rich.print(f"    get_conf_data_location() = [red]{exc}[/]")
 
+        try:
+            rich.print(f"    {get_conf_repo_location() = }", flush=True, end="")
+            location = get_conf_repo_location()
+            if location is None or not Path(location).exists():
+                rich.print("  [red]⟶ ERROR: The configuration repository location doesn't exist![/]")
+            else:
+                rich.print()
+        except ValueError as exc:
+            rich.print(f"    get_conf_repo_location() = [red]{exc}[/]")
+
         try:
             rich.print(f"    {get_log_file_location() = }", flush=True, end="")
             location = get_log_file_location()
@@ -555,8 +738,8 @@ def main(args: list | None = None):  # pragma: no cover
             rich.print(f"    get_log_file_location() = [red]{exc}[/]")
 
         try:
-            rich.print(f"    {get_local_settings() = }", flush=True, end="")
-            location = get_local_settings()
+            rich.print(f"    {get_local_settings_path() = }", flush=True, end="")
+            location = get_local_settings_path()
             if location is None or not Path(location).exists():
                 rich.print("  [red]⟶ ERROR: The local settings file is not defined or doesn't exist![/]")
             else:
@@ -623,6 +806,9 @@ def main(args: list | None = None):  # pragma: no cover
     # PLATO_COMMON_EGSE_PATH - YES
 
 
+ignore_m_warning('egse.env')
+
+
 if __name__ == "__main__":
     import sys
     main(sys.argv[1:])

{cgse_common-2025.0.4 → cgse_common-2025.0.6}/src/egse/plugin.py

@@ -1,34 +1,96 @@
+"""
+This module provides function to load plugins and settings from entry-points.
+"""
+__all__ = [
+    "load_plugins",
+    "get_file_infos",
+    "entry_points",
+]
 import logging
 import os
 import sys
 import textwrap
 import traceback
+from importlib.metadata import EntryPoint
+from pathlib import Path
 
 import click
 import rich
 
-LOGGER = logging.getLogger(__name__)
+_LOGGER = logging.getLogger(__name__)
 
 
-def entry_points(name: str):
+def entry_points(name: str) -> set[EntryPoint]:
+    """
+    Returns a set with all entry-points for the given group name.
+
+    When the name is not known as an entry-point group, an empty set will be returned.
+    """
+
     import importlib.metadata
 
     try:
         x = importlib.metadata.entry_points()[name]
         return {ep for ep in x}  # use of set here to remove duplicates
     except KeyError:
-        return []
+        return set()
 
 
 def load_plugins(entry_point: str) -> dict:
-
+    """
+    Returns a dictionary with plugins loaded. The keys are the names of the entry-points,
+    the values are the loaded modules or objects.
+    """
     eps = {}
     for ep in entry_points(entry_point):
         try:
             eps[ep.name] = ep.load()
         except Exception as exc:
             eps[ep.name] = None
-            LOGGER.error(f"Couldn't load entry point: {exc}")
+            _LOGGER.error(f"Couldn't load entry point: {exc}")
+
+    return eps
+
+
+def get_file_infos(entry_point: str) -> dict[str, tuple[Path, str]]:
+    """
+    Returns a dictionary with location and filename of all the entries found for
+    the given entry-point name.
+
+    The entry-points are interpreted as follows: <name> = "<module>:<filename>" where
+
+    - <name> is the name of the entry-point given in the pyproject.toml file
+    - <module> is a valid module name that can be imported and from which the location can be determined.
+    - <filename> is the name of the target file, e.g. a YAML file
+
+    As an example, for the `cgse-common` settings, the following entry in the `pyproject.toml`:
+
+        [project.entry-points."cgse.settings"]
+        cgse-common = "cgse_common:settings.yaml"
+
+    Note that the module name for this entry point has an underscore instead of a dash.
+
+    Return:
+        A dictionary with the entry point name as the key and a tuple (location, filename) as the value.
+    """
+    from egse.system import get_module_location
+
+    eps = dict()
+
+    for ep in entry_points(entry_point):
+        try:
+            path = get_module_location(ep.module)
+
+            if path is None:
+                _LOGGER.error(
+                    f"The entry-point '{ep.name}' is ill defined. The module part doesn't exist or is a "
+                    f"namespace. No settings are loaded for this entry-point."
+                )
+            else:
+                eps[ep.name] = (path, ep.attr)
+
+        except Exception as exc:
+            _LOGGER.error(f"The entry point '{ep.name}' is ill defined: {exc}")
 
     return eps
 
@@ -77,7 +139,7 @@ class BrokenCommand(click.Command):
         self.help = textwrap.dedent(
             f"""\
             Warning: entry point could not be loaded. Contact its author for help.
-            
+
             {traceback.format_exc()}
             """
         )

{cgse_common-2025.0.4 → cgse_common-2025.0.6}/src/egse/protocol.py

@@ -20,7 +20,7 @@ from prometheus_client import Summary
 from egse.command import Command
 from egse.command import CommandExecution
 from egse.control import ControlServer
-from egse.control import Failure
+from egse.response import Failure
 from egse.device import DeviceConnectionObserver
 from egse.system import format_datetime
 from egse.zmq_ser import bind_address