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

spectre_core/_file_io/__init__.py

@@ -2,9 +2,7 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-"""
-Internal file handling.
-"""
+"""Basic internal file handling capabilities."""
 
 from .file_handlers import (
     BaseFileHandler, JsonHandler, TextHandler,

spectre_core/_file_io/file_handlers.py

@@ -5,124 +5,229 @@
 import os
 import json
 from abc import ABC, abstractmethod
-from typing import Any, Optional
-
-
-class BaseFileHandler(ABC):
-    def __init__(self, 
-                 parent_dir_path: str, 
-                 base_file_name: str, 
-                 extension: Optional[str] = None):
+from typing import Any, Optional, TypeVar, Generic
+
+T = TypeVar('T')
+
+class BaseFileHandler(ABC, Generic[T]):
+    """
+    Base class for handling file operations.
+
+    When subclassing, specify the return type of `_read` 
+    using `Generic[T]`. 
+
+    Example:
+    .. code-block:: python
+
+        from typing import Any, Generic
+
+        class JsonHandler(BaseFileHandler[dict[str, Any]]):
+            def _read(self) -> dict[str, Any]:
+                # Implementation here
+                ...
+    """
+    def __init__(
+        self, 
+        parent_dir_path: str, 
+        base_file_name: str, 
+        extension: Optional[str] = None
+    ) -> None:
+        """Initialise a `BaseFileHandler` instance.
+
+        :param parent_dir_path: The directory path where the file is located (absolute or relative).
+        :param base_file_name: The name of the file without its extension.
+        :param extension: The file extension (without the dot), defaults to None
+        """
+        self._data_cache: Optional[T] = None
+        
         self._parent_dir_path = parent_dir_path
-        self._base_file_name = base_file_name
+        self._base_file_name  = base_file_name
+        
+        if extension == "":
+            extension = None
         self._extension = extension
 
-        
+     
     @abstractmethod
-    def read(self) -> Any:
-        pass
- 
-
+    def _read(
+        self
+    ) -> T:
+        """The grunt work to return the file contents.
+
+        :return: The file contents.
+        """
+     
+    
     @property
-    def parent_dir_path(self) -> str:
+    def parent_dir_path(
+        self
+    ) -> str:
+        """Return the parent directory path for the file."""
         return self._parent_dir_path
     
 
     @property
-    def base_file_name(self) -> str:
+    def base_file_name(
+        self
+    ) -> str:
+        """Return the file name, stripped of the file extension."""
         return self._base_file_name
     
 
     @property
-    def extension(self) -> Optional[str]:
+    def extension(
+        self
+    ) -> Optional[str]:
+        """Return the file path suffix, excluding the dot."""
         return self._extension
     
 
     @property
-    def file_name(self) -> str:
+    def file_name(
+        self
+    ) -> str:
+        """Generate the file name based on the base name and extension.
+
+        :return: The file name with the extension (including the dot), or the base name if no extension is set.
+        """
         return self._base_file_name if (self._extension is None) else f"{self._base_file_name}.{self._extension}"
     
 
     @property
-    def file_path(self) -> str:
+    def file_path(
+        self
+    ) -> str:
+        """The absolute or relative file path as defined by the parent directory path,
+        base file name and extension."""
         return os.path.join(self._parent_dir_path, self.file_name)
     
     
     @property
-    def exists(self) -> bool:
+    def exists(
+        self
+    ) -> bool:
+        """Check if the file exists in the filesystem."""
         return os.path.exists(self.file_path) 
 
 
-    def make_parent_dir_path(self) -> None:
+    def read(
+        self,
+        cache: bool = True
+    ) -> T:
+        """Read the file contents.
+        
+        :param cache: If False, bypasses the cache and reads the file directly on each `read` call, defaults to True
+        :return: The file contents.
+        """
+        # if the user has specified to ignore the cache, simply read the file.
+        if not cache:
+            return self._read()
+        
+        # otherwise make use of the cache
+        if self._data_cache is None:
+            self._data_cache = self._read()
+        return self._data_cache
+    
+    
+    def make_parent_dir_path(
+        self
+    ) -> None:
+        """Make the parent directory path of the file. No error is raised if the target 
+        directory already exists.
+        """
         os.makedirs(self.parent_dir_path, exist_ok=True) 
     
 
-    def delete(self,
-               ignore_if_missing: bool = False) -> None:
+    def delete(
+        self,
+        ignore_if_missing: bool = False
+    ) -> None:
+        """Delete the file from the filesystem.
+
+        :param ignore_if_missing: If True, skips deletion if the file does not exist, defaults to False
+        :raises FileNotFoundError: If the file is missing and `ignore_if_missing` is False.
+        """
         if not self.exists and not ignore_if_missing:
             raise FileNotFoundError(f"{self.file_name} does not exist, and so cannot be deleted")
         else:
             os.remove(self.file_path)
     
 
-    def cat(self) -> None:
+    def cat(
+        self
+    ) -> None:
+        """Display the file contents on the standard output."""
         print(self.read())
 
 
-class JsonHandler(BaseFileHandler):
-    def __init__(self, 
-                 parent_dir_path: str, 
-                 base_file_name: str,
-                 extension: str = "json",
-                 **kwargs):
-        
-        self._dict = None # cache
+class JsonHandler(BaseFileHandler[dict[str, Any]]):
+    """File handler for JSON formatted files.
+    
+    We assume that the files are of the form
+    {
+        "foo": <JSON compatable structure>
+        ... and so on.
+    }
+
+    """
+    def __init__(
+        self, 
+        parent_dir_path: str, 
+        base_file_name: str,
+        extension: str = "json"
+    ) -> None:
         super().__init__(parent_dir_path, 
                          base_file_name, 
-                         extension,
-                         **kwargs)
+                         extension)
     
     
-    def read(self) -> dict[str, Any]:
+    def _read(
+        self
+    ) -> dict[str, Any]:
         with open(self.file_path, 'r') as f:
             return json.load(f)
         
-
-    def save(self, 
-             d: dict, 
-             force: bool = False) -> None:
+        
+    def save(
+        self, 
+        d: dict[str, Any], 
+        force: bool = False
+    ) -> None:
+        """Save the input dictionary to file in the JSON file format.
+
+        :param d: The dictionary to save.
+        :param force: If True, overwrites the file if it already exists, defaults to False
+        :raises FileExistsError: If the file exists and `force` is False.
+        """
         self.make_parent_dir_path()
 
         if self.exists:
             if force:
                 pass
             else:
-                raise RuntimeError((f"{self.file_name} already exists, write has been abandoned. "
-                                    f"You can override this functionality with `force`"))
+                raise FileExistsError((f"{self.file_name} already exists, write has been abandoned. "
+                                       f"You can override this functionality with `force`"))
 
         with open(self.file_path, 'w') as file:
                 json.dump(d, file, indent=4)
 
+    
 
-    @property
-    def dict(self) -> dict[str, Any]:
-        if self._dict is None:
-            self._dict = self.read()
-        return self._dict
-    
-
-class TextHandler(BaseFileHandler):
-    def __init__(self, 
-                 parent_dir_path: str,
-                 base_file_name: str, 
-                 extension: str = "txt",
-                 **kwargs):
+class TextHandler(BaseFileHandler[str]):
+    """File handler for text formatted files."""
+    def __init__(
+        self, 
+        parent_dir_path: str,
+        base_file_name: str, 
+        extension: str = "txt"
+    ) -> None:
         super().__init__(parent_dir_path,
                          base_file_name,
-                         extension, 
-                         **kwargs)
+                         extension)
     
-
-    def read(self) -> dict:
+    
+    def _read(
+        self
+    ) -> str:
         with open(self.file_path, 'r') as f:
             return f.read()

spectre_core/batches/__init__.py

@@ -2,21 +2,20 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-# register decorators are actioned on import
-from .library._fixed_center_frequency import _Batch
-from .library._swept_center_frequency import _Batch
-from .library._callisto import _Batch
+"""IO operations on batched data files."""
+
+from .plugins._batch_keys import BatchKey
+
+# register decorators take effect on import
+from .plugins._iq_stream import IQStreamBatch, IQMetadata
+from .plugins._callisto import CallistoBatch
 
 from ._base import BaseBatch, BatchFile
-from ._factory import get_batch_cls_from_tag
 from ._batches import Batches
-from .library._swept_center_frequency import SweepMetadata
+from ._factory import get_batch_cls, get_batch_cls_from_tag
 
 __all__ = [
-    "BaseBatch",
-    "BatchFile",
-    "get_batch_cls_from_tag",
-    "Batches",
-    "SweepMetadata"
+    "IQStreamBatch", "IQMetadata", "CallistoBatch", "BaseBatch", "BatchFile", 
+    "Batches", "get_batch_cls", "BatchKey", "get_batch_cls_from_tag"
 ]
 

spectre_core/batches/_base.py

@@ -3,144 +3,236 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 from datetime import datetime
-from typing import Optional
+from typing import TypeVar
+from functools import cached_property
+from abc import ABC, abstractmethod
 
 from spectre_core._file_io import BaseFileHandler
-from spectre_core.config import get_batches_dir_path, TimeFormats
-from spectre_core.exceptions import BatchFileNotFoundError
+from spectre_core.config import get_batches_dir_path, TimeFormat
+from spectre_core.spectrograms import Spectrogram
 
 
-class BatchFile(BaseFileHandler):
-    """A specific file in a given batch, uniquely identified in the batch by the file extension."""
-    def __init__(self, 
-                 batch_parent_dir_path: str, 
-                 batch_name: str, 
-                 extension: str):
+T = TypeVar('T')
+
+class BatchFile(BaseFileHandler[T]):
+    """Abstract base class for files belonging to a batch, identified by their file extension.
+
+    Batch file names must conform to the following structure:
+
+        `<start time>_<tag>.<extension>`
+
+    The substring `<start time>_<tag>` is referred to as the batch name. Files with the same batch name 
+    belong to the same batch.
+    """
+    def __init__(
+        self, 
+        batch_parent_dir_path: str, 
+        batch_name: str, 
+        extension: str
+    ) -> None:
+        """Initialise a `BatchFile` instance.
+
+        :param batch_parent_dir_path: Parent directory of the batch.
+        :param batch_name: Base file name, composed of the batch start time and tag.
+        :param extension: File extension.
+        """
         super().__init__(batch_parent_dir_path, 
                          batch_name, 
                          extension)
         self._start_time, self._tag = batch_name.split("_")
-        # computed if required
-        self._start_datetime: Optional[datetime] = None
-        
-        
+   
+   
     @property
-    def start_time(self) -> str:
-        """The start time of the batch file, up to seconds precision."""
+    def start_time(
+        self
+    ) -> str:
+        """The start time of the batch, formatted as a string up to seconds precision."""
         return self._start_time
 
 
-    @property
-    def start_datetime(self) -> datetime:
-        """The datetime of the batch file, up to seconds precision."""
-        if self._start_datetime is None:
-            self._start_datetime = datetime.strptime(self.start_time, TimeFormats.DATETIME)
-        return self._start_datetime
-    
+    @cached_property
+    def start_datetime(
+        self
+    ) -> datetime:
+        """The start time of the batch, parsed as a datetime up to seconds precision."""
+        return datetime.strptime(self.start_time, TimeFormat.DATETIME)
 
+    
     @property
-    def tag(self) -> str:
-        """The tag identifier for the batch file."""
+    def tag(
+        self
+    ) -> str:
+        """The batch name tag."""
         return self._tag
-    
+   
+ 
+class BaseBatch(ABC):
+    """
+    An abstract base class representing a group of data files over a common time interval.
 
+    All files in a batch share a base file name and differ only by their extension.
+    Subclasses of `BaseBatch` define the expected data for each file extension and 
+    provide an API for accessing their contents using `BatchFile` subclasses.
 
-class BaseBatch:
-    """A group of one or more files which share a common start time and a tag identifier.
-    
-    All files belonging to the same batch will share a batch name, and differ
-    only in their file extension.
+    Subclasses should expose `BatchFile` instances directly as attributes, which
+    simplifies static typing. Additionally, they should call `add_file` in the constructor
+    to formally register each `BatchFile`.
     """
-    def __init__(self, 
-                 start_time: str,
-                 tag: str):
+    def __init__(
+        self, 
+        start_time: str,
+        tag: str
+    ) -> None:
+        """Initialise a `BaseBatch` instance.
+
+        :param start_time: Start time of the batch as a string with seconds precision.
+        :param tag: The batch name tag.
+        """
         self._start_time = start_time
         self._tag: str = tag
-        self._batch_files: dict[str, BatchFile] = {}
-        self._start_datetime = datetime.strptime(self.start_time, TimeFormats.DATETIME)
+        self._start_datetime = datetime.strptime(self.start_time, TimeFormat.DATETIME)
         self._parent_dir_path = get_batches_dir_path(year  = self.start_datetime.year,
                                                      month = self.start_datetime.month,
                                                      day   = self.start_datetime.day)
-
-
+        
+        # internal register of batch files
+        self._batch_files: dict[str, BatchFile] = {}
+    
+    
+    @property
+    @abstractmethod
+    def spectrogram_file(
+        self
+    ) -> BatchFile:
+        """The batch file which contains spectrogram data."""
+        
+    
     @property
-    def start_time(self) -> str:
-        """The start time of the batch, up to seconds precision."""
+    def start_time(
+        self
+    ) -> str:
+        """The start time of the batch, formatted as a string up to seconds precision."""
         return self._start_time
 
 
     @property
-    def tag(self) -> str:
-        """The tag identifier of for the batch."""
-        return self._tag
-      
-
-    @property
-    def start_datetime(self) -> datetime:
-        """The datetime of the batch file, up to seconds precision."""
+    def start_datetime(
+        self
+    ) -> datetime:
+        """The start time of the batch, parsed as a datetime up to seconds precision."""
         return self._start_datetime
     
+    
+    @property
+    def tag(
+        self
+    ) -> str:
+        """The batch name tag."""
+        return self._tag
+    
 
     @property
-    def parent_dir_path(self) -> str:
+    def parent_dir_path(
+        self
+    ) -> str:
         """The parent directory for the batch."""
         return self._parent_dir_path
 
 
     @property
-    def name(self) -> str:
-        """The name of the batch."""
+    def name(
+        self
+    ) -> str:
+        """Return the base file name shared by all files in the batch, 
+        composed of the start time and the batch tag."""
         return f"{self._start_time}_{self._tag}"
     
     
     @property
-    def extensions(self) -> list[str]:
+    def extensions(
+        self
+    ) -> list[str]:
         """All defined file extensions for the batch."""
         return list(self._batch_files.keys())
     
+    
     @property
-    def batch_files(self) -> dict[str, BatchFile]:
-        """Map each file extension in the batch to the corresponding batch file instance."""
+    def batch_files(
+        self
+    ) -> dict[str, BatchFile]:
+        """Map each file extension in the batch to the corresponding batch file instance.
+        
+        Use `add_file` to add a file to the batch.
+        """
         return self._batch_files
     
-    
-    def add_file(self, batch_file: BatchFile) -> None:
-        """Add an instance of a batch file to the batch."""
+
+    def add_file(
+        self, 
+        batch_file: BatchFile
+    ) -> None:
+        """Add an instance of a batch file to the batch.
+
+        :param batch_file: The `BatchFile` instance to add to the batch.
+        :raises ValueError: If the `BatchFile` instance does not have a defined file extension.
+        """
+        if batch_file.extension is None:
+            raise ValueError(f"The `BatchFile` must have a defined file extension. "
+                             f"Received '{batch_file.extension}.")
         self._batch_files[batch_file.extension] = batch_file
     
 
-    def get_file(self, extension: str) -> BatchFile:
-        """Get a batch file instance from the batch, according to the file extension."""
+    def get_file(
+        self, 
+        extension: str
+    ) -> BatchFile:
+        """Get a batch file instance from the batch, according to the file extension.
+
+        :param extension: The file extension of the batch file.
+        :raises NotImplementedError: If the extension is undefined for the batch.
+        :return: The batch file instance registered under the input file extension.
+        """
         try:
             return self._batch_files[extension]
         except KeyError:
-            raise BatchFileNotFoundError(f"No batch file found with extension '{extension}'")
+            raise NotImplementedError(f"A batch file with extension '{extension}' is not implemented for this batch.")
 
 
-    def read_file(self, extension: str):
-        """Read a file from the batch, according to the file extension."""
-        batch_file = self.get_file(extension)
-        return batch_file.read()
-
+    def delete_file(
+        self, 
+        extension: str
+    ) -> None:
+        """Delete a file from the batch, according to the file extension.
 
-    def delete_file(self, extension: str) -> None:
-        """Delete a file from the batch, according to the file extension."""
+        :param extension: The file extension of the batch file.
+        :raises FileNotFoundError: If the batch file does not exist in the file system.
+        """
         batch_file = self.get_file(extension)
-        try:
-            batch_file.delete()
-        except FileNotFoundError as e:
-            raise BatchFileNotFoundError(str(e))
+        batch_file.delete()
 
 
-    def has_file(self, extension: str) -> bool:
-        """Return true if a file exists in the batch with the input file extension."""
+    def has_file(
+        self, 
+        extension: str
+    ) -> bool:
+        """Determine the existance of a batch file in the file system.
+
+        :param extension: The file extension of the batch file.
+        :return: True if the batch file exists in the file system, False otherwise.
+        """
         try:
-            # only return true if both
-            # -> the batch has the extension defined
-            # -> the file with that extension exists in the batch parent directory
             batch_file = self.get_file(extension)
             return batch_file.exists
-        except BatchFileNotFoundError:
+        except FileNotFoundError:
             return False
-
-
+        
+        
+    def read_spectrogram(
+        self
+    ) -> Spectrogram:
+        """Read and return the spectrogram data stored in the batch.
+
+        :return: The spectrogram stored by the batch `spectrogram_file`.
+        """
+        return self.spectrogram_file.read()
+