Skip to content

Commit

Permalink
plugin docstrings revised
Browse files Browse the repository at this point in the history
  • Loading branch information
@KrissiHub
KrissiHub committed Jan 22, 2024
1 parent affdb1a commit 49e3249
Show file tree
Hide file tree
Showing 8 changed files with 200 additions and 129 deletions.
162 changes: 87 additions & 75 deletions deepcave/plugins/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,15 @@ class Plugin(Layout, ABC):
outputs : List[Tuple[str, str, bool]]
The registered outputs.
previous_inputs : Dict[str, Dict[str, str]]
The previous inputs for the runtime.
The previous inputs.
raw_outputs : Optional[Dict[str, Any]]
The raw outputs.
activate_run_selection : bool
Whether to activate the run selection.
Shows a dropdown to select a run in the inputs layout.
This feature is useful if only one run could be viewed at a time.
Moreover, it prevents the plugin to calculate results across all runs.
id : str
The id of the plugin.
The unique identifier for the plugin.
runs : List[AbstractRun]
A list of the abstract runs.
groups : List[Group]
Expand All @@ -66,8 +68,9 @@ class Plugin(Layout, ABC):
The path to the documentation.
name : str
The name of the plugin.
It is shown in the navigation and title.
button_caption : str
The caption of the plugin button.
Caption of the button. Shown only, if `StaticPlugin` is used.
"""

id: str
Expand Down Expand Up @@ -177,7 +180,7 @@ def register_input(
id : str
Specifies the id of the input.
attributes : Union[str, List[str]], optional
Attributes which should be passed to the (dash) component, by default ("value",)
Attributes which should be passed to the (dash) component, by default ("value",).
filter : bool, optional
Specifies if the input is a filter. By default False.
type : Any, optional
Expand Down Expand Up @@ -286,21 +289,7 @@ def register_callbacks(self) -> None:

@app.callback(outputs, inputs) # type: ignore
def plugin_input_update(pathname: str, *inputs_list: str) -> List[Optional[str]]:
"""
Update the input of the plugin.
Parameters
----------
pathname : str
The name of the path for the passed inputs.
*inputs_list : str
The list of the inputs to check if the page was loaded for the first time.
Returns
-------
List[str]
The list of the cast inputs.
"""
"""Update the input of the plugin."""
# Simple check if page was loaded for the first time
init = all(input is None for input in inputs_list)

Expand Down Expand Up @@ -442,21 +431,7 @@ def plugin_input_update(pathname: str, *inputs_list: str) -> List[Optional[str]]
State(self.get_internal_id("raw_data"), "is_open"),
)
def toggle_raw_data_modal(n: Optional[int], is_open: bool) -> Tuple[bool, str]:
"""
Toggle the raw data modal.
Parameters
----------
n : Optional[int]
A condition.
is_open : bool
Whether the raw data modal is open or not.
Returns
-------
Tuple[bool, str]
A tuple containing the is open information and the code.
"""
"""Toggle the raw data modal."""
code = ""
if n:
if (out := self.raw_outputs) is not None:
Expand All @@ -476,21 +451,7 @@ def toggle_raw_data_modal(n: Optional[int], is_open: bool) -> Tuple[bool, str]:
State(self.get_internal_id("help"), "is_open"),
)
def toggle_help_modal(n: Optional[int], is_open: bool) -> bool:
"""
Toggle the help modal.
Parameters
----------
n : Optional[int]
A condition.
is_open : bool
Whether the help modal is open or not.
Returns
-------
Tuple[bool, str]
A tuple containing the is open information and the code.
"""
"""Toggle the help modal."""
if n:
return not is_open
return is_open
Expand All @@ -504,14 +465,7 @@ def toggle_help_modal(n: Optional[int], is_open: bool) -> bool:
Input(internal_id, "clickData"),
) # type: ignore
def go_to_configuration(click_data: Any):
"""
Go to the configuration described in the hovertext.
Parameters
----------
click_data : Any
The data describing the click.
"""
"""Open link from hovertext."""
if click_data is not None:
# Get hovertext
try:
Expand Down Expand Up @@ -759,7 +713,7 @@ def _dict_as_key(self, d: Dict[str, Any], remove_filters: bool = False) -> str:

def _cast_inputs(self, inputs: Dict[str, Dict[str, str]]) -> Dict[str, Dict[str, str]]:
"""
Casts the inputs based on `self.inputs`.
Cast the inputs based on `self.inputs`.
Background is that dash always casts integers/booleans to strings.
This method ensures that the correct types are returned.
Expand Down Expand Up @@ -810,7 +764,8 @@ def _clean_inputs(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
Parameters
----------
inputs (dict): Inputs to clean.
inputs : Dict[str, Any]
Inputs to clean.
Returns
-------
Expand Down Expand Up @@ -839,31 +794,52 @@ def _clean_inputs(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
@property
@interactive
def runs(self) -> List[AbstractRun]:
"""Get the runs as a list."""
"""
Get the runs as a list.
Returns
-------
List[AbstractRun]
The list with the runs.
"""
from deepcave import run_handler

return run_handler.get_runs()

@property
@interactive
def groups(self) -> List[Group]:
"""Get the groups as a list."""
"""
Get the groups as a list.
Returns
-------
List[Group]
The list with the groups.
"""
from deepcave import run_handler

return run_handler.get_groups()

@property
@interactive
def all_runs(self) -> List[AbstractRun]:
"""Get all runs and include the groups as a list."""
"""
Get all runs and include the groups as a list.
Returns
-------
List[AbstractRun]
The list with all runs and included groups.
"""
from deepcave import run_handler

return run_handler.get_runs(include_groups=True)

@interactive
def __call__(self, render_button: bool = False) -> List[Component]:
"""
Create and return the components for the plugin.
Return the components for the plugin.
Basically, all blocks and elements of the plugin are stacked-up here.
Expand All @@ -880,9 +856,9 @@ def __call__(self, render_button: bool = False) -> List[Component]:
Raises
------
NotMergeableError
If runs are not compatible, an error is thrown.
If runs are not compatible.
FileNotFoundError
If the help file is not found, an error is thrown.
If the help file can not be found.
"""
from deepcave import c, notification

Expand Down Expand Up @@ -981,7 +957,25 @@ def __call__(self, render_button: bool = False) -> List[Component]:
]

def register_in(a: str, b: Union[List[str], str]) -> str:
"""Register the given input."""
"""
Register the given input.
Note
----
For more information, see 'register_input'.
Parameters
----------
a : str
Specifies the id of the input.
b : Union[List[str], str]
Attributes which should be passed to the (dash) component, by default ("value",).
Returns
-------
str
Unique id for the input and plugin. This is necessary because ids are defined globally.
"""
return self.register_input(a, b, filter=True)

filter_layout = self.__class__.get_filter_layout(register_in)
Expand All @@ -1006,7 +1000,25 @@ def register_in(a: str, b: Union[List[str], str]) -> str:
]

def register_out(a: str, b: Union[List[str], str]) -> str:
"""Register the output."""
"""
Register the output.
Note
----
For more information, see 'register_output'
Parameters
----------
a : str
Specifies the id of the output.
b : Union[List[str], str]
Attribute.
Returns
-------
str
Unique id for the output and plugin. This is necessary because ids are defined globally.
"""
return self.register_output(a, b, mpl=True)

output_layout = self.__class__.get_mpl_output_layout(register_out)
Expand Down Expand Up @@ -1077,7 +1089,7 @@ def get_run_input_layout(register: Callable) -> Component:
----------
register : Callable
The register method to register (user) variables.
The register_input function is located in the Plugin superclass.
For more information, see 'register_input'.
Returns
-------
Expand Down Expand Up @@ -1253,7 +1265,7 @@ def get_input_layout(register: Callable) -> List[Component]:
----------
register : Callable
The register method to register (user) variables.
The register_input function is located in the Plugin superclass.
For more information, see 'register_input'.
Returns
-------
Expand All @@ -1269,9 +1281,9 @@ def get_filter_layout(register: Callable) -> List[Component]:
Parameters
----------
register : Callable[
register : Callable
The register method to register (user) variables.
The register_input function is located in the Plugin superclass.
For more information, see 'register_input'.
Returns
-------
Expand All @@ -1289,7 +1301,7 @@ def get_output_layout(register: Callable) -> Optional[Union[Component, List[Comp
----------
register : Callable
The register method to register outputs.
The register_input function is located in the Plugin superclass.
For more information, see 'register_input'.
Returns
-------
Expand All @@ -1307,7 +1319,7 @@ def get_mpl_output_layout(register: Callable) -> Optional[Union[Component, List[
----------
register : Callable
The register method to register outputs.
The register_input function is located in the Plugin superclass.
For more information, see 'register_input'.
Returns
-------
Expand All @@ -1323,7 +1335,7 @@ def load_outputs(
outputs: Dict[str, Union[str, Dict[str, str]]],
) -> Union[Component, List[Component]]:
"""
Read in the raw data and prepares them for the layout.
Read in the raw data and prepare them for the layout.
Note
----
Expand Down
2 changes: 0 additions & 2 deletions deepcave/plugins/budget/budget_correlation.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -242,8 +242,6 @@ def load_outputs(run, _, outputs) -> List[Any]:
compared to 'load_inputs' or 'load_dependency_inputs'.
Please see '_clean_inputs' for more information.
The returned components must be in the same position as defined in 'get_output_layout'.
Parameters
----------
run
Expand Down
24 changes: 20 additions & 4 deletions deepcave/plugins/dynamic.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,13 @@ def __init__(self) -> None:

@interactive
def register_callbacks(self) -> None:
"""Register the callbacks and update the outputs from the inputs."""
"""
Register basic callbacks for the plugin.
Following callbacks are registered:
- If inputs changes, the changes are pasted back. This is in particular interest if input dependencies are used.
- Raw data dialog to display raw data.
- Callback to be redirected to the config if clicked on it.
"""
super().register_callbacks()
from deepcave import app, c, rc

Expand All @@ -65,12 +71,12 @@ def register_callbacks(self) -> None:
@app.callback(outputs, inputs) # type: ignore
def plugin_output_update(_: Any, *inputs_list: str) -> Any:
"""
Update the outputs from the inputs.
Update the outputs.
Parameters
----------
*inputs_list
Values from user.
Input values from user.
Returns
-------
Expand Down Expand Up @@ -111,5 +117,15 @@ def plugin_output_update(_: Any, *inputs_list: str) -> Any:

@interactive
# Return type does not match the superclass
def __call__(self) -> List[Component]: # noqa: D102
def __call__(self) -> List[Component]:
"""
Return the components for the plugin.
Basically, all blocks and elements of the plugin are stacked-up here.
Returns
-------
List[Component]
Layout as list of components.
"""
return super().__call__(False)
Loading

0 comments on commit 49e3249

Please sign in to comment.