spectre-core 0.0.22__py3-none-any.whl → 0.0.23__py3-none-any.whl

spectre_core/_file_io/__init__.py

@@ -5,9 +5,9 @@
 """Basic internal file handling capabilities."""
 
 from .file_handlers import (
-    BaseFileHandler, JsonHandler, TextHandler,
+    BaseFileHandler,
+    JsonHandler,
+    TextHandler,
 )
 
-__all__ = [ 
-    "BaseFileHandler", "JsonHandler", "TextHandler"
-]
+__all__ = ["BaseFileHandler", "JsonHandler", "TextHandler"]

spectre_core/_file_io/file_handlers.py

@@ -7,14 +7,15 @@ import json
 from abc import ABC, abstractmethod
 from typing import Any, Optional, TypeVar, Generic
 
-T = TypeVar('T')
+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]`. 
+    When subclassing, specify the return type of `_read`
+    using `Generic[T]`.
 
     Example:
     .. code-block:: python
@@ -26,11 +27,9 @@ class BaseFileHandler(ABC, Generic[T]):
                 # Implementation here
                 ...
     """
+
     def __init__(
-        self, 
-        parent_dir_path: str, 
-        base_file_name: str, 
-        extension: Optional[str] = None
+        self, parent_dir_path: str, base_file_name: str, extension: Optional[str] = None
     ) -> None:
         """Initialise a `BaseFileHandler` instance.
 
@@ -39,130 +38,101 @@ class BaseFileHandler(ABC, Generic[T]):
         :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
-    ) -> T:
+    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}"
-    
+        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) 
-
+        return os.path.exists(self.file_path)
 
-    def read(
-        self,
-        cache: bool = True
-    ) -> T:
+    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 
+
+    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) 
-    
+        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")
+            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[dict[str, Any]]):
     """File handler for JSON formatted files.
-    
+
     We assume that the files are of the form
     {
         "foo": <JSON compatable structure>
@@ -170,29 +140,17 @@ class JsonHandler(BaseFileHandler[dict[str, Any]]):
     }
 
     """
+
     def __init__(
-        self, 
-        parent_dir_path: str, 
-        base_file_name: str,
-        extension: str = "json"
+        self, parent_dir_path: str, base_file_name: str, extension: str = "json"
     ) -> None:
-        super().__init__(parent_dir_path, 
-                         base_file_name, 
-                         extension)
-    
-    
-    def _read(
-        self
-    ) -> dict[str, Any]:
-        with open(self.file_path, 'r') as f:
+        super().__init__(parent_dir_path, base_file_name, extension)
+
+    def _read(self) -> dict[str, Any]:
+        with open(self.file_path, "r") as f:
             return json.load(f)
-        
-        
-    def save(
-        self, 
-        d: dict[str, Any], 
-        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.
@@ -205,29 +163,25 @@ class JsonHandler(BaseFileHandler[dict[str, Any]]):
             if force:
                 pass
             else:
-                raise FileExistsError((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)
+        with open(self.file_path, "w") as file:
+            json.dump(d, file, indent=4)
 
-    
 
 class TextHandler(BaseFileHandler[str]):
     """File handler for text formatted files."""
+
     def __init__(
-        self, 
-        parent_dir_path: str,
-        base_file_name: str, 
-        extension: str = "txt"
+        self, parent_dir_path: str, base_file_name: str, extension: str = "txt"
     ) -> None:
-        super().__init__(parent_dir_path,
-                         base_file_name,
-                         extension)
-    
-    
-    def _read(
-        self
-    ) -> str:
-        with open(self.file_path, 'r') as f:
-            return f.read()
+        super().__init__(parent_dir_path, base_file_name, extension)
+
+    def _read(self) -> str:
+        with open(self.file_path, "r") as f:
+            return f.read()

spectre_core/batches/__init__.py

@@ -10,12 +10,29 @@ from .plugins._batch_keys import BatchKey
 from .plugins._iq_stream import IQStreamBatch, IQMetadata
 from .plugins._callisto import CallistoBatch
 
-from ._base import BaseBatch, BatchFile, parse_batch_base_file_name
+from ._base import (
+    BaseBatch,
+    BatchFile,
+    parse_batch_file_name,
+    parse_batch_base_file_name,
+)
 from ._batches import Batches
 from ._factory import get_batch_cls, get_batch_cls_from_tag
 
 __all__ = [
-    "IQStreamBatch", "IQMetadata", "CallistoBatch", "BaseBatch", "BatchFile", 
-    "Batches", "get_batch_cls", "BatchKey", "get_batch_cls_from_tag", "parse_batch_base_file_name"
+    "IQStreamBatch",
+    "IQMetadata",
+    "CallistoBatch",
+    "BaseBatch",
+    "BatchFile",
+    "Batches",
+    "get_batch_cls",
+    "BatchKey",
+    "get_batch_cls_from_tag",
+    "parse_batch_file_name",
 ]
 
+# To be deprecated.
+__all__ += [
+    "parse_batch_base_file_name",
+]

spectre_core/batches/_base.py

@@ -13,21 +13,40 @@ from os.path import splitext
 from spectre_core._file_io import BaseFileHandler
 from spectre_core.config import get_batches_dir_path, TimeFormat
 from spectre_core.spectrograms import Spectrogram
+from spectre_core.exceptions import deprecated
 
 
-def parse_batch_base_file_name(
-    base_file_name: str
-) -> Tuple[str, str, str]:
+@deprecated(
+    "The terminology (base file name) is inconsistent with the `_file_io` submodule. "
+    f"Please use `parse_batch_file_name` instead."
+)
+def parse_batch_base_file_name(base_file_name: str) -> Tuple[str, str, str]:
+    """Included for backwards compatability - please use `parse_batch_file_name` instead."""
+    return parse_batch_file_name(base_file_name)
+
+
+def parse_batch_file_name(file_name: str) -> Tuple[str, str, str]:
     """Parse the base file name of a batch file into a start time, tag and extension.
+
+    :param file_name: The file name of the batch file, with optional extension.
+    :return: The file name decomposed into its start time, tag and extension. If no extension is present,
+    the final element of the tuple will be an empty string.
     """
-    batch_name, extension = splitext(base_file_name)
+    batch_name, extension = splitext(file_name)
+
+    num_underscores = batch_name.count("_")
+    if num_underscores != 1:
+        raise ValueError(
+            f"Expected exactly one underscore in the batch name '{batch_name}'. Found {num_underscores}"
+        )
+
     # strip the dot from the extension
-    extension = extension.lstrip('.')
+    extension = extension.lstrip(".")
     start_time, tag = batch_name.split("_", 1)
     return start_time, tag, extension
 
 
-T = TypeVar('T')
+T = TypeVar("T")
 
 
 class BatchFile(BaseFileHandler[T]):
@@ -37,14 +56,12 @@ class BatchFile(BaseFileHandler[T]):
 
         `<start time>_<tag>.<extension>`
 
-    The substring `<start time>_<tag>` is referred to as the batch name. Files with the same batch name 
+    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
+        self, batch_parent_dir_path: str, batch_name: str, extension: str
     ) -> None:
         """Initialise a `BatchFile` instance.
 
@@ -52,52 +69,39 @@ class BatchFile(BaseFileHandler[T]):
         :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)
+        super().__init__(batch_parent_dir_path, batch_name, extension)
         self._start_time, self._tag = batch_name.split("_")
-   
-   
+
     @property
-    def start_time(
-        self
-    ) -> str:
+    def start_time(self) -> str:
         """The start time of the batch, formatted as a string up to seconds precision."""
         return self._start_time
 
-
     @cached_property
-    def start_datetime(
-        self
-    ) -> datetime:
+    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:
+    def tag(self) -> str:
         """The batch name tag."""
         return self._tag
-  
-  
+
+
 @dataclass(frozen=True)
 class _BatchExtension:
     """Supported extensions for a `BaseBatch`, inherited by all derived classes.
-    
+
     :ivar PNG: Corresponds to the `.png` file extension.
     """
+
     PNG: str = "png"
-      
-    
+
+
 class _PngFile(BatchFile[str]):
     """Stores an image visualising the data for the batch."""
-    def __init__(
-        self, 
-        batch_parent_dir_path: str, 
-        batch_name: str
-    ) -> None:
+
+    def __init__(self, batch_parent_dir_path: str, batch_name: str) -> None:
         """Initialise a `_PngFile` instance.
 
         :param batch_parent_dir_path: The parent directory for the batch.
@@ -105,7 +109,6 @@ class _PngFile(BatchFile[str]):
         """
         super().__init__(batch_parent_dir_path, batch_name, _BatchExtension.PNG)
 
-
     def _read(self) -> str:
         """Reads the PNG file and returns it base64-encoded.
 
@@ -114,25 +117,22 @@ class _PngFile(BatchFile[str]):
         with open(self.file_path, "rb") as f:
             encoded = b64encode(f.read())
             return encoded.decode("ascii")
-   
- 
+
+
 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 
+    Subclasses of `BaseBatch` define the expected data for each file extension and
     provide an API for accessing their contents using `BatchFile` subclasses.
 
     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
-    ) -> None:
+
+    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.
@@ -141,113 +141,82 @@ class BaseBatch(ABC):
         self._start_time = start_time
         self._tag: str = tag
         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)
-        
+        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] = {}
-    
+
         # Add the files shared by all derived classes
-        self._png_file  = _PngFile(self.parent_dir_path, self.name)
-        self.add_file( self._png_file ) 
-    
-    
+        self._png_file = _PngFile(self.parent_dir_path, self.name)
+        self.add_file(self._png_file)
+
     @property
     @abstractmethod
-    def spectrogram_file(
-        self
-    ) -> BatchFile:
+    def spectrogram_file(self) -> BatchFile:
         """The batch file which contains spectrogram data."""
-        
-    
+
     @property
-    def start_time(
-        self
-    ) -> str:
+    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:
+    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:
+    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:
-        """Return the base file name shared by all files in 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]:
+    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
-    
-    
+
     @property
-    def png_file(
-        self
-    ) -> _PngFile:
+    def png_file(self) -> _PngFile:
         """The batch file corresponding to the `.png` extension."""
         return self._png_file
-    
 
-    def add_file(
-        self, 
-        batch_file: BatchFile
-    ) -> None:
+    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}.")
+            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:
+    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.
@@ -257,13 +226,11 @@ class BaseBatch(ABC):
         try:
             return self._batch_files[extension]
         except KeyError:
-            raise NotImplementedError(f"A batch file with extension '{extension}' is not implemented for this batch.")
-
+            raise NotImplementedError(
+                f"A batch file with extension '{extension}' is not implemented for this batch."
+            )
 
-    def delete_file(
-        self, 
-        extension: str
-    ) -> None:
+    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.
@@ -272,11 +239,7 @@ class BaseBatch(ABC):
         batch_file = self.get_file(extension)
         batch_file.delete()
 
-
-    def has_file(
-        self, 
-        extension: str
-    ) -> bool:
+    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.
@@ -287,22 +250,10 @@ class BaseBatch(ABC):
             return batch_file.exists
         except FileNotFoundError:
             return False
-        
-        
-    def read_spectrogram(
-        self
-    ) -> Spectrogram:
+
+    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()
-    
-
-
-
-
-
-
-
-