cgse-common 2024.1.1__py3-none-any.whl

egse/obsid.py

@@ -0,0 +1,161 @@
+"""
+An ObservationIdentifier or OBSID is a unique identifier for an observation or test.
+
+Each observation or test needs a unique identification that can be used as a key in a
+database or in a filename for test data etc.
+
+"""
+from pathlib import Path
+from typing import Union
+
+from egse.config import find_dir
+from egse.settings import Settings
+
+LAB_SETUP_TEST = 0
+TEST_LAB_SETUP = 1
+TEST_LAB = 3
+
+SITE = Settings.load("SITE")
+
+
+class ObservationIdentifier:
+    """A unique identifier for each observation or test."""
+
+    def __init__(self, lab_id: str = None, setup_id: int = None, test_id: int = None):
+        """
+        Args:
+            lab_id: the identifier for the site or lab that performs the test
+            setup_id: the identifier for the setup that is used for the test
+            test_id: the test identifier or test number
+        """
+        if lab_id is None or setup_id is None or test_id is None:
+            raise ValueError("arguments can not be None or an empty string")
+
+        self._lab_id = lab_id
+        self._setup_id = setup_id
+        self._test_id = test_id
+
+        # Construct the OBSID as it will be used in serialisation etc.
+
+        self._obsid = f"{lab_id}_{setup_id:05d}_{test_id:05d}"
+
+    @staticmethod
+    def create_from_string(obsid: str, order: int = LAB_SETUP_TEST):
+        if order == LAB_SETUP_TEST:
+            lab_id, setup_id, test_id = obsid.split("_")
+        elif order == TEST_LAB_SETUP:
+            test_id, lab_id, setup_id = obsid.split("_")
+        else:
+            raise ValueError(
+                f"The order argument can only be {LAB_SETUP_TEST=} or {TEST_LAB_SETUP=}")
+
+        return ObservationIdentifier(lab_id, int(setup_id), int(test_id))
+
+    @property
+    def lab_id(self):
+        return self._lab_id
+
+    @property
+    def setup_id(self):
+        return self._setup_id
+
+    @property
+    def test_id(self):
+        return self._test_id
+
+    def __eq__(self, other):
+        if not isinstance(other, ObservationIdentifier):
+            return NotImplemented
+        return self._obsid == other._obsid
+
+    def __hash__(self):
+        return hash(self._obsid)
+
+    def __str__(self):
+        return self._obsid
+
+    def create_id(self, *, order: int = LAB_SETUP_TEST, camera_name: str = None) -> str:
+        """
+        Creates a string representation of the observation identifier.
+
+        Args:
+            order: the order in which the parts are concatenated
+            camera_name: if a camera name is given, it will be appended in lower case
+
+        Returns:
+            A string representation of the obsid with or without camera name attached.
+        """
+        camera = f"{f'_{camera_name.lower()}' if camera_name else ''}"
+
+        if order == TEST_LAB_SETUP:
+            return f"{self._test_id:05d}_{self._lab_id}_{self._setup_id:05d}{camera}"
+        if order == TEST_LAB:
+            return f"{self._test_id:05d}_{self._lab_id}{camera}"
+        if order == LAB_SETUP_TEST:
+            return f"{self._lab_id}_{self._setup_id:05d}_{self._test_id:05d}{camera}"
+
+
+def obsid_from_storage(obsid: Union[ObservationIdentifier, str, int], data_dir: str,
+                       site_id: str = None, camera_name: str = None) -> str:
+    """
+    Return the name of the folder for the given obsid in the 'obs' sub-folder of data_dir.
+
+    For the oldest observations, the obsid used in the directory structure and filenames was of the format
+    TEST_LAB_SETUP.  All files in this folder also have the obsid in that format in their name.  At some point, we
+    decided to change this to TEST_LAB, but we still need to be able to re-process the old data (with the setup ID in
+    the names of the directories and files).
+
+    For newer observations (>= 2023.6.0+CGSE), the camera name is appended to the folder name and also included
+    in the filenames in that folder.
+
+    Args:
+        obsid: Observation identifier.  This can be an ObservationIdentifier object, a string in format TEST_LAB or
+            TEST_LAB_SETUP, or an integer representing the test ID. In this last case, the site id is taken from the
+            Settings.
+        data_dir: root folder in which the observations are stored. This folder shall have a sub-folder 'obs'.
+        site_id: a site id like 'CSL1' or 'IAS', when `None`, the `SITE.ID` from the Settings will be used
+        camera_name: if not None, append the camera name to the result
+
+    Returns:
+        The name of the folder for the given obsid in the 'obs' sub-folder of data_dir.
+    """
+
+    obs_dir = f"{data_dir}/obs/"
+    site_id = site_id or SITE.ID
+    camera = f"_{camera_name.lower()}" if camera_name else ""
+
+    if isinstance(obsid, ObservationIdentifier):
+        test, site = obsid.test_id, obsid.lab_id
+    elif isinstance(obsid, str):    # TEST_LAB or TEST_LAB_SETUP
+        test, site = obsid.split("_")[:2]
+    else:
+        test, site = obsid, site_id
+
+    test = int(test)
+
+    # Remember the camera name can be an empty string, so this will match both
+    # '00313_CSL' and '00313_CSL_achel'.
+
+    result_without_setup = Path(f"{obs_dir}/{test:05d}_{site}{camera}")
+
+    if result_without_setup.exists():
+        return result_without_setup.stem
+
+    # If a camera name was provided, but we try to find an old observation where the
+    # camera name was not appended to the folder name yet, the following will match
+    # that folder name.
+
+    result_without_camera = Path(f"{obs_dir}/{test:05d}_{site}")
+
+    if result_without_camera.exists():
+        return result_without_camera.stem
+
+    # When we come here, we can still match old observations that included the setup id in their
+    # folder name.
+
+    pattern = f"{test:05d}_{site}_*{camera}"
+
+    if (match := find_dir(pattern=pattern, root=obs_dir)) is None:
+        raise ValueError(f"Could not find a folder matching '{pattern}' in '{obs_dir}'")
+
+    return match.stem

egse/persistence.py

@@ -0,0 +1,58 @@
+from abc import ABC
+from abc import abstractmethod
+
+
+class PersistenceLayer(ABC):
+    """The Persistence Layer implements the CRUD paradigm for storing data."""
+
+    extension = "no_ext"
+    """The file extension to use for this persistence type."""
+
+    @abstractmethod
+    def open(self, mode=None):
+        """Opens the resource."""
+        raise NotImplementedError("Persistence layers must implement the open method")
+
+    @abstractmethod
+    def close(self):
+        """Closes the resource."""
+        raise NotImplementedError("Persistence layers must implement the close method")
+
+    @abstractmethod
+    def exists(self):
+        """Does the resource exists."""
+        raise NotImplementedError("Persistence layers must implement the exists method")
+
+    @abstractmethod
+    def create(self, data):
+        """Creates an entry in the persistence store."""
+        raise NotImplementedError("Persistence layers must implement a create method")
+
+    @abstractmethod
+    def read(self, select=None):
+        """Returns a list of all entries in the persistence store.
+
+        The list can be filtered based on a selection from the `select` argument which
+        should be a Callable object.
+
+        Args:
+            select (Callable): a filter function to narrow down the list of all entries.
+        Returns:
+            A list or generator for all entries in the persistence store.
+        """
+        raise NotImplementedError("Persistence layers must implement a read method")
+
+    @abstractmethod
+    def update(self, idx, data):
+        """Updates the entry for index `idx` in the persistence store."""
+        raise NotImplementedError("Persistence layers must implement an update method")
+
+    @abstractmethod
+    def delete(self, idx):
+        """Deletes the entry for index `idx` from the persistence store."""
+        raise NotImplementedError("Persistence layers must implement a delete method")
+
+    @abstractmethod
+    def get_filepath(self):
+        """If this persistence class is file based, return its file path, otherwise return None."""
+        raise NotImplementedError("Persistence layers must implement a get_filepath method")

egse/plugin.py

@@ -0,0 +1,97 @@
+import logging
+import os
+import sys
+import textwrap
+import traceback
+
+import click
+import rich
+
+LOGGER = logging.getLogger(__name__)
+
+
+def entry_points(name: str):
+    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 []
+
+
+def load_plugins(entry_point: str) -> dict:
+
+    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}")
+
+    return eps
+
+
+# The following code was adapted from the inspiring package click-plugins
+# at https://github.com/click-contrib/click-plugins/
+
+def handle_click_plugins(plugins):
+    def decorator(group):
+        if not isinstance(group, click.Group):
+            raise TypeError("Plugins can only be attached to an instance of click.Group()")
+
+        for entry_point in plugins or ():
+            try:
+                group.add_command(entry_point.load())
+            except Exception:
+                # Catch this so a busted plugin doesn't take down the CLI.
+                # Handled by registering a dummy command that does nothing
+                # other than explain the error.
+                group.add_command(BrokenCommand(entry_point.name))
+
+        return group
+
+    return decorator
+
+
+class BrokenCommand(click.Command):
+    """
+    Rather than completely crash the CLI when a broken plugin is loaded, this
+    class provides a modified help message informing the user that the plugin is
+    broken, and they should contact the owner.  If the user executes the plugin
+    or specifies `--help` a traceback is reported showing the exception the
+    plugin loader encountered.
+    """
+
+    def __init__(self, name):
+        """
+        Define the special help messages after instantiating a `click.Command()`.
+        """
+
+        click.Command.__init__(self, name)
+
+        util_name = os.path.basename(sys.argv and sys.argv[0] or __file__)
+        icon = u'\u2020'
+
+        self.help = textwrap.dedent(
+            f"""\
+            Warning: entry point could not be loaded. Contact its author for help.
+            
+            {traceback.format_exc()}
+            """
+        )
+
+        self.short_help = f"{icon} Warning: could not load plugin. See `{util_name} {self.name} --help`."
+
+    def invoke(self, ctx):
+        """
+        Print the traceback instead of doing nothing.
+        """
+
+        rich.print()
+        rich.print(self.help)
+        ctx.exit(1)
+
+    def parse_args(self, ctx, args):
+        return args