changed a few docstrings

.pre-commit-config.yaml

@@ -41,7 +41,7 @@ repos:
       - id: mypy
         name: mypy deepcave
         files: deepcave
-        args: [--check-untyped-defs, --ignore-missing-imports]
+        args: [--check-untyped-defs, --ignore-missing-imports, --install-types, --non-interactive]
         additional_dependencies: [
             'wheel',
             'setuptools',

deepcave/__init__.py

@@ -5,11 +5,6 @@
 This module is used to initialize and set up the configuration for the DeepCAVE framework.
 It also contains Constants and Metadata, as well as the name of the authors and the copyright.
 The Dash application gets created.
-
-## Contents
-    - get_app: Create the Dash application.
-    - interactive: Define the interactive decorator.
-    - inner: The inner function of the decorator.
 """
 
 from typing import Any, Callable, TypeVar, cast

deepcave/custom_queue.py

@@ -274,9 +274,14 @@ def remove_jobs(registry: BaseRegistry, job_id: Optional[str] = None) -> None:
             ----------
             registry : BaseRegistry
                 The registry from where to remove the job.
-            job_id: str, optional
+            job_id: Optional[str], optional
                 The identificator of the job to be removed.
                 Default is None.
+
+            Raises
+            ------
+            Exception
+                If the job could not be removed.
             """
             if job_id is not None:
                 try:

deepcave/layouts/general.py

@@ -175,10 +175,10 @@ def _callback_display_selected_runs(self) -> None:
         input = Input("general-selected-runs", "data")
 
         @app.callback(output, input)  # type: ignore
-        def callback(run_paths: List[str]):  
+        def callback(run_paths: List[str]):
             """
             Display the selected runs.
-            
+
             Parameters
             ----------
             run_paths : List[str]
@@ -293,7 +293,7 @@ def get_layout(
             ) -> Component:
                 """
                 Get the layout for the groups.
-                
+
                 Parameters
                 ----------
                 index : int
@@ -304,7 +304,7 @@ def get_layout(
                     The input value, by default "".
                 dropdown_value : Optional[List[str]], optional
                     The dropdown value, by default None.
-                
+
                 Returns
                 -------
                 Component

deepcave/layouts/header.py

@@ -49,7 +49,22 @@ def update_matplotlib_mode(
             Tuple[Literal["primary"], Literal["on"], str],
             Tuple[Literal["secondary"], Literal["off"], str],
         ]:
-            """Update the matplotlib mode."""
+            """
+            Update the matplotlib mode.
+
+            Parameters
+            ----------
+            n_clicks : int
+                Number of clicks.
+            pathname : str
+                Pathname.
+
+            Returns
+            -------
+            Tuple[Literal["primary"], Literal["on"], str],
+            Tuple[Literal["secondary"], Literal["off"], str]
+                Tuple of either "primary", "on", pathname or "secondary", "off", pathname.
+            """
             update = None
             mode = c.get("matplotlib-mode")
             if mode is None:

deepcave/layouts/main.py

@@ -10,7 +10,7 @@
     - MainLayout: This class defines and provides the main layout.
 """
 
-from typing import Dict, List
+from typing import Any, Dict, List, Union
 
 from urllib.parse import urlparse
 
@@ -37,7 +37,7 @@ class MainLayout(Layout):
 
     Properties
     ----------
-    plugins : dict
+    plugins : Dict[str, Plugin]
         A dictionary containing the different plugins.
     sidebar_layout : SidebarLayout
         A sidebar layout with the categorized plugins.
@@ -69,8 +69,20 @@ def register_callbacks(self) -> None:
         input = Input("on-page-load", "pathname")
 
         @app.callback(output, input)  # type: ignore
-        def display_page(pathname: str):  # type: ignore
-            """Display the page with the given path url, check for plugins."""
+        def display_page(pathname: str) -> Union[Component, Any]:
+            """
+            Display the page with the given path url, check for plugins.
+
+            Parameters
+            ----------
+            pathname : str
+                Pathname.
+
+            Returns
+            -------
+            Union[Component, Any]
+                Either a General Layout, Not Found Layout or an Alert.
+            """
             pathname = urlparse(pathname).path
             paths = pathname.split("/")[1:]
 

deepcave/layouts/notification.py

@@ -45,7 +45,14 @@ def register_callbacks(self) -> None:
             Trigger("global-update", "n_intervals"),
         )  # type: ignore
         def update_alert() -> Tuple[str, str, bool]:
-            """Update the notification alert."""
+            """
+            Update the notification alert.
+
+            Returns
+            -------
+            Tuple[str, str, bool]
+                The message, color and True.
+            """
             if (result := notification.get_latest()) is not None:
                 (message, color) = result
                 return message, color, True

deepcave/layouts/sidebar.py

@@ -57,8 +57,20 @@ def register_callbacks(self) -> None:
         input = Input("on-page-load", "pathname")
 
         @app.callback(output, input)  # type: ignore
-        def update_navigation_items(pathname):  # type: ignore
-            """Update the navigation items."""
+        def update_navigation_items(pathname: str) -> List[Component]:
+            """
+            Update the navigation items.
+
+            Parameters
+            ----------
+            pathname : str
+                The pathname.
+
+            Returns
+            -------
+            List[Component]
+                The navigation items.
+            """
             layouts = []
             for category, points in self.nav_points.items():
                 layouts += [

deepcave/plugins/__init__.py

@@ -286,7 +286,7 @@ def register_callbacks(self) -> None:
         Raises
         ------
         RuntimeError
-            _description_
+            If no run id is found.
         """
         from deepcave import app, c, run_handler
 
@@ -672,7 +672,7 @@ def _list_to_dict(self, values: List[str], input: bool = True) -> Dict[str, Dict
         Returns
         -------
         Dict[str, Dict[str, str]]
-            _description_
+            Dictionary containing the mapping information.
         """
         if input:
             order = self.inputs
@@ -823,7 +823,8 @@ def _clean_inputs(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
 
         Returns
         -------
-            dict: Cleaned inputs.
+        Dict[str, Any]
+            Cleaned inputs.
         """
         used_ids = []
         cleaned_inputs = {}
@@ -847,23 +848,23 @@ def _clean_inputs(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
     @property  # type: ignore
     @interactive
     def runs(self) -> List[AbstractRun]:
-        """Get the runs."""
+        """Get the runs as a list."""
         from deepcave import run_handler
 
         return run_handler.get_runs()
 
     @property  # type: ignore
     @interactive
     def groups(self) -> List[Group]:
-        """Get the groups."""
+        """Get the groups as a list."""
         from deepcave import run_handler
 
         return run_handler.get_groups()
 
     @property  # type: ignore
     @interactive
     def all_runs(self) -> List[AbstractRun]:
-        """Get all runs and include the groups."""
+        """Get all runs and include the groups as a list."""
         from deepcave import run_handler
 
         return run_handler.get_runs(include_groups=True)
@@ -875,10 +876,22 @@ def __call__(self, render_button: bool = False) -> List[Component]:
 
         Basically, all blocks and elements of the plugin are stacked-up here.
 
+        Parameters
+        ----------
+        render_button : bool, optional
+            Whether to render the button or not. By default False.
+
         Returns
         -------
         List[Component]
             Layout as list of components.
+
+        Raises
+        ------
+        NotMergeableError
+            If runs are not compatible, an error is thrown.
+        FileNotFoundError
+            If the help file is not found, an error is thrown.
         """
         from deepcave import c, notification
 
@@ -1063,16 +1076,17 @@ def register_out(a, b):  # type: ignore
 
     @staticmethod
     @interactive
-    def get_run_input_layout(register: Callable[[str, Union[str, List[str]]], str]) -> Component:
+    def get_run_input_layout(register: Callable) -> Component:
         """
         Generate the run selection input.
 
         This is only the case if `activate_run_selection` is True.
 
         Parameters
         ----------
-        register : Callable[[str, Union[str, List[str]]], str]
+        register : Callable
             The register method to register (user) variables.
+            The register_input function is located in the Plugin superclass.
 
         Returns
         -------
@@ -1240,14 +1254,15 @@ def load_dependency_inputs(
         return inputs
 
     @staticmethod
-    def get_input_layout(register: Callable[[str, Union[str, List[str]]], str]) -> List[Component]:
+    def get_input_layout(register: Callable) -> List[Component]:
         """
         Layout for the input block.
 
         Parameters
         ----------
-        register : Callable[[str, Union[str, List[str]]], str]
+        register : Callable
             The register method to register (user) variables.
+            The register_input function is located in the Plugin superclass.
 
         Returns
         -------
@@ -1257,14 +1272,15 @@ def get_input_layout(register: Callable[[str, Union[str, List[str]]], str]) -> L
         return []
 
     @staticmethod
-    def get_filter_layout(register: Callable[[str, Union[str, List[str]]], str]) -> List[Component]:
+    def get_filter_layout(register: Callable) -> List[Component]:
         """
         Layout for the filter block.
 
         Parameters
         ----------
-        register : Callable[[str, Union[str, List[str]]], str]
+        register : Callable[
             The register method to register (user) variables.
+            The register_input function is located in the Plugin superclass.
 
         Returns
         -------
@@ -1274,16 +1290,15 @@ def get_filter_layout(register: Callable[[str, Union[str, List[str]]], str]) ->
         return []
 
     @staticmethod
-    def get_output_layout(
-        register: Callable[[str, Union[str, List[str]]], str]
-    ) -> Optional[Union[Component, List[Component]]]:
+    def get_output_layout(register: Callable) -> Optional[Union[Component, List[Component]]]:
         """
         Layout for the output block.
 
         Parameters
         ----------
-        register : Callable[[str, Union[str, List[str]]], str]
+        register : Callable
             The register method to register outputs.
+            The register_input function is located in the Plugin superclass.
 
         Returns
         -------
@@ -1293,16 +1308,15 @@ def get_output_layout(
         return None
 
     @staticmethod
-    def get_mpl_output_layout(
-        register: Callable[[str, Union[str, List[str]]], str]
-    ) -> Optional[Union[Component, List[Component]]]:
+    def get_mpl_output_layout(register: Callable) -> Optional[Union[Component, List[Component]]]:
         """
         Layout for the matplotlib output block.
 
         Parameters
         ----------
-        register : Callable[[str, Union[str, List[str]]], str]
+        register : Callable
             The register method to register outputs.
+            The register_input function is located in the Plugin superclass.
 
         Returns
         -------
@@ -1468,6 +1482,12 @@ def generate_inputs(self, **kwargs: Any) -> Dict[str, Any]:
         -------
         Dict[str, Any]
             The inputs for the run.
+
+        Raises
+        ------
+        ValueError
+            If an unknown input is passed.
+            If an input is missing.
         """
         mapping = {}
         for id, attribute, *_ in self.inputs: