refactor: add type hinting to data processors

.pre-commit-config.yaml

@@ -102,7 +102,7 @@ repos:
           (?x)(
           ^(.gitlab|.github|config|doc|tests|test_utils)/|
           ^src/(example_simulator_functions|queens_interfaces)/|
-          ^src/queens/(data_processors|drivers|iterators|models)/|
+          ^src/queens/(drivers|iterators|models)/|
           ^src/queens/(schedulers|stochastic_optimizers|visualization)/|
           ^src/queens/(main.py|global_settings.py)
           ).*$

pyproject.toml

@@ -175,7 +175,7 @@ enable_error_code = ["explicit-override"]
 exclude = '''(?x)(
     ^(.gitlab|.github|config|doc|tests|test_utils)/|
     ^src/(example_simulator_functions|queens_interfaces)/|
-    ^src/queens/(data_processors|drivers|iterators|models)/|
+    ^src/queens/(drivers|iterators|models)/|
     ^src/queens/(schedulers|stochastic_optimizers|visualization)/|
     ^src/queens/(main.py|global_settings.py)
 ).*$'''

src/queens/data_processors/__init__.py

@@ -17,11 +17,14 @@
 Modules for extracting and processing data from simulation output files.
 """
 
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 from queens.utils.imports import extract_type_checking_imports, import_class_from_class_module_map
 
 if TYPE_CHECKING:
+    from queens.data_processors._data_processor import DataProcessor
     from queens.data_processors.csv_file import CsvFile
     from queens.data_processors.numpy_file import NumpyFile
     from queens.data_processors.pvd_file import PvdFile
@@ -31,7 +34,7 @@
 class_module_map = extract_type_checking_imports(__file__)
 
 
-def __getattr__(name):
+def __getattr__(name: str) -> type[DataProcessor]:
     """Lazily import a data processor class on first attribute access.
 
     Args:

src/queens/data_processors/_data_processor.py

@@ -26,41 +26,33 @@ class DataProcessor(metaclass=abc.ABCMeta):
     """Base class for data processing.
 
     Attributes:
-        files_to_be_deleted_regex_lst (lst): List with paths to files that should be deleted.
-                                             The paths can contain regex expressions. The
-                                             paths are relative to the particular simulation output
-                                             folder: *experiment_dir/<job_id>/output/<here
-                                             comes your regex>* .
-        file_options_dict (dict): Dictionary with read-in options for
-                                  the file.
-        file_name_identifier (str): Identifier for files.
-                                    The file prefix can contain BASIC regex expression
-                                    and subdirectories. Examples are wildcards `*` or
-                                    expressions like `[ab]`.
+        files_to_be_deleted_regex_lst: List with paths to files that should be deleted. The paths
+            can contain regex expressions. The paths are relative to the particular simulation
+            output folder: *experiment_dir/<job_id>/output/<here comes your regex>* .
+        file_options_dict: Dictionary with read-in options for the file.
+        file_name_identifier: Identifier for files. The file prefix can contain BASIC regex
+            expression and subdirectories. Examples are wildcards `*` or expressions like `[ab]`.
     """
 
     def __init__(
         self,
-        file_name_identifier=None,
-        file_options_dict=None,
-        files_to_be_deleted_regex_lst=None,
-    ):
+        file_name_identifier: str,
+        file_options_dict: dict | None = None,
+        files_to_be_deleted_regex_lst: list[str] | None = None,
+    ) -> None:
         """Init data processor class.
 
         Args:
-            file_name_identifier (str): Identifier for files.
-                                        The file prefix can contain regex expression and
-                                        subdirectories.
-            file_options_dict (dict): Dictionary with read-in options for
-                                      the file. The respective child class will
-                                       implement valid options for this dictionary.
-            files_to_be_deleted_regex_lst (lst): List with paths to files that should be deleted.
-                                                 The paths can contain regex expressions.
+            file_name_identifier: Identifier for files. The file prefix can contain regex
+                expression and subdirectories.
+            file_options_dict: Dictionary with read-in options for the file. The respective child
+                class will implement valid options for this dictionary.
+            files_to_be_deleted_regex_lst: List with paths to files that should be deleted. The
+                paths can contain regex expressions.
         """
         if not file_name_identifier:
             raise ValueError(
-                f"No option 'file_name_identifier' was provided in '{self.__class__.__name__}'! "
-                "DataProcessor object cannot be instantiated! Abort..."
+                f"Provided 'file_name_identifier' was empty in '{self.__class__.__name__}'!"
             )
         if not isinstance(file_name_identifier, str):
             raise TypeError(
@@ -69,10 +61,7 @@ def __init__(
             )
 
         if file_options_dict is None:
-            raise ValueError(
-                f"No option 'file_options_dict' was provided in '{self.__class__.__name__}'! "
-                "DataProcessor object cannot be instantiated! Abort..."
-            )
+            file_options_dict = {}
         if not isinstance(file_options_dict, dict):
             raise TypeError(
                 "The option 'file_options_dict' must be of type 'dict' "
@@ -95,10 +84,10 @@ def get_data_from_file(self, base_dir_file: Path) -> Any:
         """Get data of interest from file.
 
         Args:
-            base_dir_file (Path): Path of the base directory that contains the file of interest
+            base_dir_file: Path of the base directory that contains the file of interest
 
         Returns:
-            processed_data (object): Final data from data processor module
+            Final data from data processor module
         """
         if not base_dir_file:
             raise ValueError(
@@ -125,21 +114,21 @@ def __call__(self, base_dir_file: Path) -> Any:
         """Get data of interest from file.
 
         Args:
-            base_dir_file (Path): Path of the base directory that contains the file of interest
+            base_dir_file: Path of the base directory that contains the file of interest
 
         Returns:
-            processed_data (object): Final data from data processor module
+            Final data from data processor module
         """
         return self.get_data_from_file(base_dir_file)
 
-    def _check_file_exist_and_is_unique(self, base_dir_file):
+    def _check_file_exist_and_is_unique(self, base_dir_file: Path) -> Path | None:
         """Check if file exists.
 
         Args:
-            base_dir_file (Path): Path to base directory that contains file of interest
+            base_dir_file: Path to base directory that contains file of interest
 
         Returns:
-            file_path (str): Actual path to the file of interest.
+            Actual path to the file of interest, or *None* if it does not exist.
         """
         file_list = list(base_dir_file.glob(self.file_name_identifier))
 
@@ -161,28 +150,28 @@ def _check_file_exist_and_is_unique(self, base_dir_file):
         return file_path
 
     @abc.abstractmethod
-    def get_raw_data_from_file(self, file_path):
+    def get_raw_data_from_file(self, file_path: str | Path) -> Any:
         """Get the raw data from the files of interest.
 
         Args:
-            file_path (str): Actual path to the file of interest.
+            file_path: Actual path to the file of interest.
 
         Returns:
-            raw_data (obj): Raw data from file.
+            Raw data from file.
         """
 
-    def filter_and_manipulate_raw_data(self, raw_data):
+    def filter_and_manipulate_raw_data(self, raw_data: Any) -> Any:
         """Filter or clean the raw data for given criteria.
 
         Args:
-            raw_data (obj): Raw data from file.
+            raw_data: Raw data from file.
 
         Returns:
-            processed_data (np.array): Cleaned, filtered or manipulated *data_processor* data.
+            Cleaned, filtered or manipulated *data_processor* data.
         """
         return raw_data
 
-    def _subsequent_data_manipulation(self, processed_data):
+    def _subsequent_data_manipulation(self, processed_data: Any) -> Any:
         """Subsequent manipulate the data_processor data.
 
         This method can be easily implemented by overloading the empty
@@ -191,19 +180,18 @@ def _subsequent_data_manipulation(self, processed_data):
         this file.
 
         Args:
-            processed_data (np.array): Cleaned, filtered or manipulated *data_processor* data.
+            processed_data: Cleaned, filtered or manipulated *data_processor* data.
 
         Returns:
-            processed_data (np.array): Cleaned, filtered or manipulated *data_processor* data.
+            Cleaned, filtered or manipulated *data_processor* data.
         """
         return processed_data
 
-    def _clean_up(self, base_dir_file):
+    def _clean_up(self, base_dir_file: Path) -> None:
         """Clean-up files in the output directory.
 
         Args:
-            base_dir_file (Path): Path of the base directory that
-                                    contains the file of interest.
+            base_dir_file: Path of the base directory that contains the file of interest.
         """
         for regex in self.files_to_be_deleted_regex_lst:
             for file in sorted(base_dir_file.glob(regex)):