spectre-core 0.0.1__py3-none-any.whl

spectre_core/file_handlers/base.py

@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import os
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+from warnings import warn
+
+class BaseFileHandler(ABC):
+    def __init__(self, 
+                 parent_path: str, 
+                 base_file_name: str, 
+                 extension: Optional[str] = None):
+        self._parent_path = parent_path
+        self._base_file_name = base_file_name
+        self._extension = extension
+
+        
+    @abstractmethod
+    def read(self) -> Any:
+        pass
+ 
+
+    @property
+    def parent_path(self) -> str:
+        return self._parent_path
+    
+
+    @property
+    def base_file_name(self) -> str:
+        return self._base_file_name
+    
+
+    @property
+    def extension(self) -> Optional[str]:
+        return self._extension
+    
+
+    @property
+    def file_name(self) -> str:
+        return self._base_file_name if (self._extension is None) else f"{self._base_file_name}.{self._extension}"
+    
+
+    @property
+    def file_path(self) -> str:
+        return os.path.join(self._parent_path, self.file_name)
+    
+    
+    @property
+    def exists(self) -> bool:
+        return os.path.exists(self.file_path) 
+
+
+    def make_parent_path(self) -> None:
+        os.makedirs(self.parent_path, exist_ok=True) 
+    
+
+    def delete(self, 
+               doublecheck_delete = True) -> None:
+        if not self.exists:
+            warn(f"{self.file_path} does not exist. No deletion taking place")
+            return
+        else:
+            if doublecheck_delete:
+                self.doublecheck_delete()
+            os.remove(self.file_path)
+    
+
+    def cat(self) -> None:
+        print(self.read())
+
+
+    def _doublecheck_action(self, 
+                            action_message: str) -> None:
+        proceed_with_action = False
+        while not proceed_with_action:
+            user_input = input(f"{action_message} [y/n]: ").strip().lower()
+            if user_input == "y":
+                proceed_with_action = True
+            elif user_input == "n":
+                print("Operation cancelled by the user")
+                raise exit(1)
+            else:
+                print(f"Please enter one of [y/n], received {user_input}")
+                proceed_with_action = False
+
+
+    def doublecheck_overwrite(self) -> None:
+        self._doublecheck_action(action_message=f"The file '{self.file_path}' already exists. Overwrite?")
+
+
+    def doublecheck_delete(self) -> None:
+        self._doublecheck_action(action_message=f"Are you sure you would like to delete '{self.file_path}'?")

spectre_core/file_handlers/configs.py

@@ -0,0 +1,269 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Any, Optional, Type, Tuple
+from abc import ABC
+import ast
+
+from spectre_core.file_handlers.json import JsonHandler
+from spectre_core.cfg import JSON_CONFIGS_DIR_PATH
+from spectre_core.exceptions import InvalidTagError
+
+
+def _unpack_param(param: str) -> list[str, str]:
+    """Seperate a string of the form "a=b" into a list [a,b]."""
+    if not param or '=' not in param:
+        raise ValueError(f'Invalid format: "{param}". Expected "KEY=VALUE".')
+    if param.startswith('=') or param.endswith('='):
+        raise ValueError(f'Invalid format: "{param}". Expected "KEY=VALUE".')
+    # remove leading and trailing whitespace.
+    param = param.strip()
+    return param.split('=', 1)
+
+
+def _params_to_string_dict(params: list[str]) -> dict[str, str]:
+    """Converts a list with string elements of the form "a=b" into a dictionary where the key value pairs are "a": "b"."""
+    d = {}
+    for param in params:
+        key, value = _unpack_param(param)
+        d[key] = value
+    return d
+
+
+def _convert_to_dict(v: str) -> dict:
+    """Evaluate literally a string containing a Python dictionary expression."""
+    return ast.literal_eval(v)
+
+
+def _convert_to_bool(v: str) -> bool:
+    """Evaluate literally a string representation of a boolean as a boolean"""
+    v = v.lower()
+    if v in ('true', '1', 't', 'y', 'yes'):
+        return True
+    if v in ('false', '0', 'f', 'n', 'no'):
+        return False
+    raise ValueError(f'Cannot convert {v} to bool.')
+    
+
+def _convert_string_to_type(value: str, 
+                           target_type: Type) -> Any:
+    """Cast a string as the target type."""
+    if target_type == bool:
+        return _convert_to_bool(value)
+    elif target_type == dict:
+        return _convert_to_dict(value)
+    return target_type(value)
+
+
+def _type_cast_string_dict(d: dict[str, str], 
+                           type_template: dict[str, Type]) -> dict[str, Any]:
+    """Cast the values of the input dictionary according to a type template."""
+    casted_d = {}
+    for key, value in d.items():
+        target_type = type_template.get(key)
+        if target_type is None:
+            raise KeyError(f'Key "{key}" not found in type template. Expected keys: {list(type_template.keys())}')
+        try:
+            casted_d[key] = _convert_string_to_type(value, target_type)
+        except ValueError:
+            raise ValueError(f'Failed to convert key "{key}" with value "{value}" to {target_type.__name__}.')
+    return casted_d
+
+
+def _validate_keys(d: dict[str, Any], 
+                   type_template: dict[str, type], 
+                   ignore_keys: Optional[list] = None) -> None:
+    """Validate that the keys in the input dictionary map one-to-one to the input type template."""
+    if ignore_keys is None:
+        ignore_keys = []
+
+    type_template_keys = set(type_template.keys())
+    input_keys = set(d.keys())
+    ignore_keys = set(ignore_keys)
+
+    missing_keys = type_template_keys - input_keys
+    invalid_keys = input_keys - type_template_keys - ignore_keys
+
+    errors = []
+    
+    if missing_keys:
+        errors.append(f"Missing keys: {', '.join(missing_keys)}")
+
+    if invalid_keys:
+        errors.append(f"Invalid keys: {', '.join(invalid_keys)}")
+    
+    if errors:
+        raise KeyError("Key errors found! " + " ".join(errors))
+
+
+def _validate_types(d: dict[str, Any], 
+                    type_template: dict[str, type], 
+                    ignore_keys: Optional[list] = None) -> None:
+    """Validate the types in the input dictionary are consistent with the input type template."""
+
+    if ignore_keys is None:
+        ignore_keys = []
+        
+    for k, v in d.items():
+        if k in ignore_keys:
+            continue
+        expected_type = type_template[k]
+        if expected_type is None:
+            raise KeyError(f'Type not found for key "{k}" in the type template.')
+        
+        if not isinstance(v, expected_type):
+            raise TypeError(f'Expected {expected_type} for "{k}", but got {type(v)}.')
+
+
+def validate_against_type_template(d: dict[str, Any], 
+                                   type_template: dict[str, type], 
+                                   ignore_keys: Optional[list] = None) -> None:
+    """Validates the keys and values of the input dictionary, according to the input type template."""
+    _validate_keys(d, 
+                   type_template, 
+                   ignore_keys = ignore_keys)
+    _validate_types(d, 
+                    type_template, 
+                    ignore_keys = ignore_keys)
+
+
+def type_cast_params(params: list[str], 
+                     type_template: dict[str, type]) -> dict[str, Any]:
+    d = _params_to_string_dict(params)
+    return _type_cast_string_dict(d, 
+                                  type_template)
+
+
+
+class SPECTREConfig(JsonHandler, ABC):
+    def __init__(self, 
+                 tag: str, 
+                 config_type: str, 
+                 **kwargs):
+        self._validate_tag(tag)
+        self._tag = tag
+        self._config_type = config_type
+
+        self._dict = None # cache
+        super().__init__(JSON_CONFIGS_DIR_PATH, 
+                         f"{config_type}_config_{tag}", 
+                         **kwargs)
+
+
+    @property
+    def tag(self) -> str:
+        return self._tag
+    
+
+    @property
+    def config_type(self) -> str:
+        return self._config_type
+    
+
+    @property
+    def dict(self) -> dict[str, Any]:
+        if self._dict is None:
+            self._dict = self.read()
+        return self._dict
+    
+
+    def _validate_tag(self, tag: str) -> None:
+        if "_" in tag:
+            raise InvalidTagError(f"Tags cannot contain an underscore. Received {tag}")
+        if "callisto" in tag:
+            raise InvalidTagError(f'"callisto" cannot be a substring in a native tag. Received "{tag}"')
+
+    
+    def __getitem__(self, 
+                    key: str) -> Any:
+        return self.dict[key]
+    
+
+    def get(self, 
+            *args, 
+            **kwargs) -> Any:
+        return self.dict.get(*args, 
+                             **kwargs)
+    
+    
+    def update(self, 
+               *args, 
+               **kwargs) -> None:
+        self.dict.update(*args, **kwargs)
+
+    
+    def items(self):
+        return self.dict.items()
+    
+    
+    def keys(self):
+        return self.dict.keys()
+    
+    
+    def values(self):
+        return self.dict.values()
+
+
+class FitsConfig(SPECTREConfig):
+
+    type_template = {
+        "ORIGIN": str,
+        "TELESCOP": str,
+        "INSTRUME": str,
+        "OBJECT": str,
+        "OBS_LAT": float,
+        "OBS_LONG": float,
+        "OBS_ALT": float
+    }
+
+    def __init__(self, 
+                 tag: str, 
+                 **kwargs):
+        super().__init__(tag, 
+                         "fits", 
+                         **kwargs)
+
+    def get_create_fits_config_cmd(self, 
+                                   tag: str, 
+                                   as_string: bool = False) -> list[str] | str:
+        command_as_list = ["spectre", "create", "fits-config", "-t", tag]
+        for key, value in self.type_template.items():
+            command_as_list += ["-p"]
+            command_as_list += [f"{key}={value.__name__}"]
+        if as_string:
+            return " ".join(command_as_list)
+        else:
+            return command_as_list
+        
+
+    def save_params(self, 
+                    params: list[str], 
+                    doublecheck_overwrite: bool = True
+                    ) -> None:
+        d = type_cast_params(params, 
+                             self.type_template)
+        self.save(d, 
+                  doublecheck_overwrite = doublecheck_overwrite)
+        
+    
+class CaptureConfig(SPECTREConfig):
+    def __init__(self, 
+                 tag: str, 
+                 **kwargs):
+        super().__init__(tag, 
+                         "capture", 
+                         **kwargs)
+        
+
+    def get_receiver_metadata(self) -> Tuple[str, str]:
+
+        receiver_name, mode = self.get("receiver"), self.get("mode")
+
+        if receiver_name is None:
+            raise ValueError("Invalid capture config! Receiver name is not specified.")
+    
+        if mode is None:
+            raise ValueError("Invalid capture config! Receiver mode is not specified.")
+        
+        return receiver_name, mode

spectre_core/file_handlers/json.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Any
+import json
+
+from spectre_core.file_handlers.base import BaseFileHandler
+
+class JsonHandler(BaseFileHandler):
+    def __init__(self, 
+                 parent_path: str, 
+                 base_file_name: str,
+                 extension: str = "json",
+                 **kwargs):
+        super().__init__(parent_path, 
+                         base_file_name, 
+                         extension,
+                         **kwargs)
+    
+    
+    def read(self) -> dict[str, Any]:
+        with open(self.file_path, 'r') as f:
+            return json.load(f)
+        
+
+    def save(self, 
+             d: dict, 
+             doublecheck_overwrite: bool = True) -> None:
+        self.make_parent_path()
+
+        if self.exists and doublecheck_overwrite:
+            self.doublecheck_overwrite()
+        
+        with open(self.file_path, 'w') as file:
+            json.dump(d, file, indent=4)

spectre_core/file_handlers/text.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from spectre_core.file_handlers.base import BaseFileHandler
+
+class TextHandler(BaseFileHandler):
+    def __init__(self, 
+                 parent_path: str,
+                 base_file_name: str, 
+                 extension: str = "txt",
+                 **kwargs):
+        super().__init__(parent_path,
+                         base_file_name,
+                         extension, 
+                         **kwargs)
+    
+
+    def read(self) -> dict:
+        with open(self.file_path, 'r') as f:
+            return f.read()

spectre_core/logging.py

@@ -0,0 +1,222 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+
+from logging import getLogger
+_LOGGER = getLogger(__name__)
+
+import os
+import logging
+from typing import Callable, Optional
+import warnings
+from collections import OrderedDict
+from datetime import datetime
+
+from spectre_core.file_handlers.text import TextHandler
+from spectre_core.cfg import (
+    LOGS_DIR_PATH, 
+    DEFAULT_DATETIME_FORMAT, 
+    get_logs_dir_path
+)
+
+PROCESS_TYPES = [
+    "USER", 
+    "WORKER"
+]
+
+
+def validate_process_type(process_type: str
+) -> None:
+    if process_type not in PROCESS_TYPES:
+        raise ValueError(f"Invalid process type: {process_type}. Expected one of {PROCESS_TYPES}")
+
+
+class LogHandler(TextHandler):
+    def __init__(self, 
+                 datetime_stamp: str, 
+                 pid: str, 
+                 process_type: str):
+        self._datetime_stamp = datetime_stamp
+        self._pid = pid
+        validate_process_type(process_type)
+        self._process_type = process_type
+
+        dt = datetime.strptime(datetime_stamp, DEFAULT_DATETIME_FORMAT)
+        date_dir = os.path.join(dt.strftime("%Y"), dt.strftime("%m"), dt.strftime("%d"))
+        parent_path = os.path.join(LOGS_DIR_PATH, date_dir)
+        base_file_name = f"{datetime_stamp}_{pid}_{process_type}"
+
+        super().__init__(parent_path, base_file_name, extension = "log")
+    
+
+    @property
+    def datetime_stamp(self) -> str:
+        return self._datetime_stamp
+    
+
+    @property
+    def pid(self) -> str:
+        return self._pid
+    
+
+    @property
+    def process_type(self) -> str:
+        return self._process_type
+
+
+class LogHandlers:
+    def __init__(self, 
+                 process_type: Optional[str] = None, 
+                 year: Optional[int] = None, 
+                 month: Optional[int] = None, 
+                 day: Optional[int] = None):
+        self._log_handler_map: dict[str, LogHandler] = OrderedDict()
+        self._process_type = process_type
+        self.set_date(year, month, day)
+
+
+    @property
+    def process_type(self) -> str:
+        return self._process_type
+    
+
+    @property
+    def year(self) -> Optional[int]:
+        return self._year
+
+
+    @property 
+    def month(self) -> Optional[int]:
+        return self._month
+    
+
+    @property
+    def day(self) -> Optional[int]:
+        return self._day
+
+
+    @property
+    def logs_dir_path(self) -> str:
+        return get_logs_dir_path(self.year, self.month, self.day)
+
+
+    @property 
+    def log_handler_map(self) -> dict[str, LogHandler]:
+        if not self._log_handler_map: # check for empty dictionary
+            self._update_log_handler_map()
+        return self._log_handler_map
+        
+
+    @property
+    def log_handler_list(self) -> list[LogHandler]:
+        return list(self.log_handler_map.values())
+
+
+    @property
+    def num_logs(self) -> int:
+        return len(self.log_handler_list) 
+
+
+    @property
+    def file_names(self) -> list[str]:
+        return list(self.log_handler_map.keys())
+
+
+    def set_date(self, 
+                 year: Optional[int],
+                 month: Optional[int],
+                 day: Optional[int]) -> None:
+        self._year = year
+        self._month = month
+        self._day = day
+        self._update_log_handler_map()
+
+
+    def _update_log_handler_map(self) -> None:
+        log_files = [f for (_, _, files) in os.walk(self.logs_dir_path) for f in files]
+
+        if not log_files:
+            warning_message = "No logs found, setting log map to an empty dictionary"
+            _LOGGER.warning(warning_message)
+            warnings.warn(warning_message)
+            return
+
+        for log_file in log_files:
+            file_name, _ = os.path.splitext(log_file)
+            log_start_time, pid, process_type = file_name.split("_")
+
+            if self.process_type and process_type != self.process_type:
+                continue
+
+            self._log_handler_map[file_name] = LogHandler(log_start_time, pid, process_type)
+
+        self._log_handler_map = OrderedDict(sorted(self._log_handler_map.items()))
+
+
+    def update(self) -> None:
+        """Public alias for setting log handler map"""
+        self._update_log_handler_map()
+
+
+    def __iter__(self):
+        yield from self.log_handler_list
+
+
+    def get_log_handler_from_file_name(self, 
+                                       file_name: str) -> LogHandler:
+        # auto strip the extension if present
+        file_name, _ = os.path.splitext(file_name)
+        try:
+            return self.log_handler_map[file_name]
+        except KeyError:
+            raise FileNotFoundError(f"Log handler for file name '{file_name}' not found in log map")
+
+
+    def get_log_handler_from_pid(self, 
+                                 pid: str) -> LogHandler:
+        for log_handler in self.log_handler_list:
+            if log_handler.pid == pid:
+                return log_handler
+        raise FileNotFoundError(f"Log handler for PID '{pid}' not found in log map")
+
+
+def configure_root_logger(process_type: str, 
+                          level: int = logging.INFO
+) -> LogHandler:
+    system_datetime = datetime.now()
+    datetime_stamp = system_datetime.strftime(DEFAULT_DATETIME_FORMAT)
+    pid = os.getpid()
+    log_handler = LogHandler(datetime_stamp, pid, process_type)
+    log_handler.make_parent_path()
+
+    # configure the root logger
+    logger = logging.getLogger()
+    logger.setLevel(level)
+    # Remove any existing handlers to avoid duplicate logs
+    for handler in logger.handlers:
+        logger.removeHandler(handler)
+    # Set up file handler with specific filename
+    file_handler = logging.FileHandler(log_handler.file_path)
+    file_handler.setLevel(level)
+    formatter = logging.Formatter("[%(asctime)s] [%(levelname)8s] --- %(message)s (%(name)s:%(lineno)s)")
+    file_handler.setFormatter(formatter)
+    # and add it to the root logger
+    logger.addHandler(file_handler)
+
+    return log_handler
+
+# Logger must be passed in to preserve context of the service function
+def log_call(logger: logging.Logger
+) -> Callable:
+    def decorator(func: Callable) -> Callable:
+        def wrapper(*args, **kwargs):
+            try:
+                logger.info(f"Calling the function: {func.__name__}")
+                return func(*args, **kwargs)
+            except Exception as e:
+                logger.error(f"An error occurred while calling the function: {func.__name__}",
+                              exc_info=True)
+                raise
+        return wrapper
+    return decorator

spectre_core/plotting/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import spectre_core.plotting.library