spectre-core 0.0.12__py3-none-any.whl → 0.0.14__py3-none-any.whl

spectre_core/jobs/_workers.py

@@ -0,0 +1,171 @@
+# 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__)
+
+from functools import wraps
+import time
+from typing import Callable, TypeVar, ParamSpec
+import multiprocessing
+
+from spectre_core.logs import configure_root_logger, log_call, ProcessType
+from spectre_core.capture_configs import CaptureConfig
+from spectre_core.receivers import get_receiver, ReceiverName
+from spectre_core.post_processing import start_post_processor
+
+
+def _make_daemon_process(
+    name: str, 
+    target: Callable[[], None]
+) -> multiprocessing.Process:
+    """
+    Creates and returns a daemon `multiprocessing.Process` instance.
+
+    :param name: The name to assign to the process.
+    :param target: The function to execute in the process.
+    :return: A `multiprocessing.Process` instance configured as a daemon.
+    """
+    return multiprocessing.Process(target=target,
+                                   name=name,
+                                   daemon=True)
+
+
+class Worker:
+    """A lightweight wrapper for a `multiprocessing.Process` daemon.
+    
+    Provides a very simple API to start, and restart a multiprocessing process.
+    """
+    def __init__(
+        self,
+        name: str,
+        target: Callable[[], None]
+    ) -> None:
+        """Initialise a `Worker` instance.
+
+        :param name: The name assigned to the process.
+        :param target: The callable to be executed by the worker process.
+        """
+        self._name = name
+        self._target = target
+        self._process = _make_daemon_process(name, target)
+
+
+    @property
+    def name(
+        self
+    ) -> str:
+        """Get the name of the worker process.
+
+        :return: The name of the multiprocessing process.
+        """
+        return self._process.name
+    
+    
+    @property
+    def process(
+        self
+    ) -> multiprocessing.Process:
+        """Access the underlying multiprocessing process.
+
+        :return: The wrapped `multiprocessing.Process` instance.
+        """
+        return self._process
+
+    
+    def start(
+        self
+    ) -> None:
+        """Start the worker process.
+
+        This method runs the `target` in the background as a daemon.
+        """
+        self._process.start()
+
+
+    def restart(
+        self
+    ) -> None:
+        """Restart the worker process.
+
+        Terminates the existing process if it is alive and then starts a new process
+        after a brief pause. 
+        """
+        _LOGGER.info(f"Restarting {self.name} worker")
+        if self._process.is_alive():
+            # forcibly stop if it is still alive
+            self._process.terminate()
+            self._process.join()
+        # a moment of respite
+        time.sleep(1)
+        # make a new process, as we can't start the same process again.
+        self._process = _make_daemon_process(self._name, self._target)
+        self.start()
+
+
+P = ParamSpec("P")
+T = TypeVar("T", bound=Callable[..., None])
+def make_worker(
+    name: str
+) -> Callable[[Callable[P, None]], Callable[P, Worker]]:
+    """
+    Turns a function into a worker.
+
+    This decorator wraps a function, allowing it to run in a separate process
+    managed by a `Worker` object. Use it to easily create long-running or
+    isolated tasks without directly handling multiprocessing.
+
+    :param name: A human-readable name for the worker process.
+    :return: A decorator that creates a `Worker` to run the function in its own process.
+    """
+
+    def decorator(
+        func: Callable[P, None]
+    ) -> Callable[P, Worker]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> Worker:
+            # Worker target funcs must have no arguments
+            def target():
+                configure_root_logger(ProcessType.WORKER)
+                func(*args, **kwargs)
+            return Worker(name, target)
+        return wrapper
+    return decorator
+
+
+@make_worker("capture")
+@log_call
+def do_capture(
+    tag: str,
+) -> None:
+    """Start capturing data from an SDR in real time.
+
+    :param tag: The capture config tag.
+    """
+    _LOGGER.info((f"Reading capture config with tag '{tag}'"))
+
+    # load the receiver and mode from the capture config file
+    capture_config = CaptureConfig(tag)
+
+    _LOGGER.info((f"Starting capture with the receiver '{capture_config.receiver_name}' "
+                  f"operating in mode '{capture_config.receiver_mode}' "
+                  f"with tag '{tag}'"))
+
+    name = ReceiverName( capture_config.receiver_name )
+    receiver = get_receiver(name,
+                            capture_config.receiver_mode)
+    receiver.start_capture(tag)
+
+
+@make_worker("post_processing")
+@log_call
+def do_post_processing(
+    tag: str,
+) -> None:
+    """Start post processing SDR data into spectrograms in real time.
+
+    :param tag: The capture config tag.
+    """
+    _LOGGER.info(f"Starting post processor with tag '{tag}'")
+    start_post_processor(tag)

spectre_core/logs/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+
+"""`spectre` logging configurations."""
+
+from ._process_types import ProcessType
+from ._decorators import log_call
+from ._configure import configure_root_logger, get_root_logger_state
+from ._logs import Log, Logs
+
+
+__all__ = [
+    "log_call", "configure_root_logger", "Log", "Logs", "ProcessType",
+    "get_root_logger_state"
+]

spectre_core/logs/_configure.py

@@ -0,0 +1,67 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import os
+import logging
+from typing import Tuple
+from datetime import datetime
+
+from spectre_core.config import TimeFormat
+from ._logs import Log
+from ._process_types import ProcessType
+
+
+def configure_root_logger(
+    process_type: ProcessType, 
+    level: int = logging.INFO
+) -> str:
+    """Configures the root logger to write logs to a file named based on 
+    the process type, process ID, and the current system time.
+
+    :param process_type: Indicates the type of process, as defined by `ProcessType`.
+    :param level: The logging level, as defined in Python's `logging` module. Defaults to `logging.INFO`.
+    :return: The file path of the created log file.
+    """
+    # create a `spectre` log handler instance, to represent the log file.
+    # get the star time of the log
+    system_datetime = datetime.now()
+    start_time = system_datetime.strftime(TimeFormat.DATETIME)
+    
+    # extract the process identifier, and cast as a string
+    pid = str( os.getpid() )
+    
+    # create a file handler representing the log file
+    log = Log(start_time, 
+              pid, 
+              process_type)
+    log.make_parent_dir_path()
+
+    # get the root logger and set its level.
+    logger = logging.getLogger()
+    logger.setLevel(level)
+    
+    # remove existing handlers
+    for handler in logger.handlers:
+        logger.removeHandler(handler)
+        
+    # Set up a file handler and add it to the root logger
+    file_handler = logging.FileHandler(log.file_path)
+    file_handler.setLevel(level)
+    formatter = logging.Formatter("[%(asctime)s] [%(levelname)8s] --- %(message)s (%(name)s:%(lineno)s)")
+    file_handler.setFormatter(formatter)
+    logger.addHandler(file_handler)
+
+    return log.file_path
+
+
+def get_root_logger_state(
+) -> Tuple[bool, int]:
+    """Get the state of the root logger.
+
+    :return: Whether the root logger has any handlers, and the level of the root logger.
+    """
+    root_logger = logging.getLogger()
+    if root_logger.handlers:
+        return True, root_logger.level
+    return False, logging.NOTSET

spectre_core/logs/_decorators.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import logging
+from typing import Callable, TypeVar, ParamSpec
+from functools import wraps
+
+# ParamSpec for capturing the argument types of the function
+P = ParamSpec("P")
+# TypeVar for capturing the return type of the function
+RT = TypeVar("RT")
+def log_call(
+    func: Callable[P, RT]
+) -> Callable[P, RT]:
+    """Decorator to log the execution of a function.
+
+    Logs an informational message when the decorated function is called,
+    and an error message if the function raises an exception.
+
+    :param func: The function to be decorated.
+    :return: The decorated function with added logging behaviour.
+    """
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> RT:
+        logger = logging.getLogger(func.__module__)
+        try:
+            logger.info(f"Calling the function: {func.__name__}")
+            return func(*args, **kwargs)
+        except Exception as e:
+            logger.error(f"Error in function: {func.__name__}", exc_info=True)
+            raise
+    return wrapper

spectre_core/logs/_logs.py

@@ -0,0 +1,228 @@
+# 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
+from typing import Optional, Iterator
+from collections import OrderedDict
+from datetime import datetime
+
+from spectre_core._file_io import TextHandler
+from spectre_core.config import get_logs_dir_path, TimeFormat
+from ._process_types import ProcessType
+
+class Log(TextHandler):
+    """Interface to read log files generated by `spectre`."""
+    def __init__(
+        self, 
+        start_time: str, 
+        pid: str, 
+        process_type: ProcessType
+    ) -> None:
+        """Initialise a `Log` instance.
+
+        :param start_time: The timestamp when the log file was created.
+        :param pid: The ID of the process writing to the log file.
+        :param process_type: Indicates the type of process, as defined by `ProcessType`.
+        """
+        self._start_time = start_time
+        self._pid = pid
+        self._process_type = process_type.value
+
+        dt = datetime.strptime(start_time, TimeFormat.DATETIME)
+        parent_path = get_logs_dir_path(dt.year, dt.month, dt.day)
+        base_file_name = f"{start_time}_{pid}_{process_type.value}"
+
+        super().__init__(parent_path, base_file_name, "log")
+    
+
+    @property
+    def start_time(
+        self
+    ) -> str:
+        """The system time when the log was created."""
+        return self._start_time
+    
+
+    @property
+    def pid(
+        self
+    ) -> str:
+        """The ID of the process writing to the log file."""
+        return self._pid
+    
+
+    @property
+    def process_type(
+        self
+    ) -> str:
+        """Indicates the type of process, as defined by `ProcessType`."""
+        return self._process_type
+
+
+class Logs:
+    """Filter and read a collection of logs generated by `spectre`."""
+    def __init__(
+        self, 
+        process_type: Optional[ProcessType] = None, 
+        year: Optional[int] = None, 
+        month: Optional[int] = None, 
+        day: Optional[int] = None
+    ) -> None:
+        """Initialise a `Logs` instance.
+
+        :param process_type: Filter by the process type. Defaults to None.
+        :param year: Filter by the numeric year. Defaults to None.
+        :param month: Filter by the numeric month. Defaults to None.
+        :param day: Filter by the numeric day. Defaults to None.
+        """
+        self._process_type = process_type.value if process_type is not None else None
+            
+        self._log_map: dict[str, Log] = OrderedDict()
+        self.set_date(year, month, day)
+
+
+    @property
+    def process_type(
+        self
+    ) -> Optional[str]:
+        """Indicates the type of process, as defined by `ProcessType`."""
+        return self._process_type
+    
+
+    @property
+    def year(
+        self
+    ) -> Optional[int]:
+        """Filter by the numeric year."""
+        return self._year
+
+
+    @property 
+    def month(
+        self
+    ) -> Optional[int]:
+        """Filter by the numeric month."""
+        return self._month
+    
+
+    @property
+    def day(
+        self
+    ) -> Optional[int]:
+        """Filter by the numeric day."""
+        return self._day
+
+
+    @property
+    def logs_dir_path(
+        self
+    ) -> str:
+        """The shared ancestral path for all the log files. `Logs` recursively searches
+        this directory to find all log files according to the date and process type."""
+        return get_logs_dir_path(self.year, self.month, self.day)
+        
+
+    @property
+    def log_list(
+        self
+    ) -> list[Log]:
+        """A list of all log handlers representing files found within `logs_dir_path`."""
+        return list(self._log_map.values())
+
+
+    @property
+    def num_logs(
+        self
+    ) -> int:
+        """The number of log files found within `logs_dir_path`."""
+        return len(self.log_list) 
+
+
+    @property
+    def file_names(
+        self
+    ) -> list[str]:
+        """A list of all log file names found within `logs_dir_path`."""
+        return list(self._log_map.keys())
+
+
+    def set_date(
+        self, 
+        year: Optional[int],
+        month: Optional[int],
+        day: Optional[int]
+    ) -> None:
+        """Reset `logs_dir_path` according to the numeric date, and refresh the list
+        of available log files.
+
+        :param year: The numeric year.
+        :param month: The numeric month of the year.
+        :param day: The numeric day of the month.
+        """
+        self._year = year
+        self._month = month
+        self._day = day
+        self.update()
+
+
+    def update(
+        self
+    ) -> None:
+        """Perform a fresh search of all files in `logs_dir_path` for log files
+        according to the date and process type."""
+        log_files = [f for (_, _, files) in os.walk(self.logs_dir_path) for f in files]
+
+        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_map[file_name] = Log(log_start_time, pid, ProcessType(process_type))
+
+        self._log_map = OrderedDict(sorted(self._log_map.items()))
+
+
+    def __iter__(
+        self
+    ) -> Iterator[Log]:
+        yield from self.log_list
+
+
+    def get_from_file_name(
+        self, 
+        file_name: str
+    ) -> Log:
+        """Retrieve a `Log` instance based on the log file name.
+
+        :param file_name: The name of the log file (with or without extension).
+        :raises FileNotFoundError: If the log file name is not found.
+        :return: The `Log` instance corresponding to the file name.
+        """
+        # auto strip the extension if present
+        file_name, _ = os.path.splitext(file_name)
+        try:
+            return self._log_map[file_name]
+        except KeyError:
+            raise FileNotFoundError(f"Log handler for file name '{file_name}' not found in log map")
+
+
+    def get_from_pid(
+        self, 
+        pid: str
+    ) -> Log:
+        """Retrieve a `Log` instance based on the process ID.
+
+        :param pid: The process ID to search for.
+        :raises FileNotFoundError: If a log file corresponding to the process ID is not found.
+        :return: The `Log` instance corresponding to the process ID.
+        """
+        for log in self.log_list:
+            if log.pid == pid:
+                return log
+        raise FileNotFoundError(f"Log handler for PID '{pid}' not found in log map")

spectre_core/logs/_process_types.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from enum import Enum
+
+class ProcessType(Enum):
+    """The origin of a `spectre` process.
+    
+    :ivar USER: A process is one initiated directly by the user, or part of the main user session.
+    :ivar WORKER: A process is one which is created and managed internally by `spectre`.
+    """
+    USER   = "user"
+    WORKER = "worker"

spectre_core/plotting/__init__.py

@@ -2,10 +2,12 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+"""An intuitive API for plotting spectrogram data."""
+
 from ._format import PanelFormat
-from ._panels import Panels
+from ._panels import SpectrogramPanel, FrequencyCutsPanel, TimeCutsPanel, IntegralOverFrequencyPanel
 from ._panel_stack import PanelStack
 
 __all__ = [
-    "PanelFormat", "Panels", "PanelStack"
+    "PanelFormat", "PanelStack", "SpectrogramPanel", "FrequencyCutsPanel", "TimeCutsPanel", "IntegralOverFrequencyPanel"
 ]