Add head comments to functions in widgets.py

Author: ChristianZaccaria

src/codeflare_sdk/cluster/widgets.py

@@ -18,7 +18,7 @@
 import contextlib
 import io
 import os
-from time import sleep
+import warnings
 import time
 import codeflare_sdk
 from kubernetes import client
@@ -103,7 +103,13 @@ def is_notebook() -> bool:
 
 
 def view_clusters(namespace: str = None):
-    """view_clusters function will display existing clusters with their specs, and handle user interactions."""
+    """
+    view_clusters function will display existing clusters with their specs, and handle user interactions.
+    """
+    if not is_notebook():
+        warnings.warn("view_clusters can only be used in a Jupyter Notebook environment.")
+        return # Exit function if not in Jupyter Notebook
+
     from .cluster import get_current_namespace
     if not namespace:
         namespace = get_current_namespace()
@@ -112,13 +118,13 @@ def view_clusters(namespace: str = None):
     raycluster_data_output = widgets.Output()
     url_output = widgets.Output()
 
-    df = _fetch_cluster_data(namespace)
-    if df.empty:
+    ray_clusters_df = _fetch_cluster_data(namespace)
+    if ray_clusters_df.empty:
         print(f"No clusters found in the {namespace} namespace.")
         return
 
     classification_widget = widgets.ToggleButtons(
-        options=df["Name"].tolist(), value=df["Name"].tolist()[0],
+        options=ray_clusters_df["Name"].tolist(), value=ray_clusters_df["Name"].tolist()[0],
         description='Select an existing cluster:',
     )
     # Setting the initial value to trigger the event handler to display the cluster details.
@@ -132,28 +138,31 @@ def view_clusters(namespace: str = None):
                 icon='trash',
                 tooltip="Delete the selected cluster"
             )
-    delete_button.on_click(lambda b: _on_delete_button_click(b, classification_widget, df, raycluster_data_output, user_output, delete_button, list_jobs_button, ray_dashboard_button))
+    delete_button.on_click(lambda b: _on_delete_button_click(b, classification_widget, ray_clusters_df, raycluster_data_output, user_output, delete_button, list_jobs_button, ray_dashboard_button))
 
     list_jobs_button = widgets.Button(
                 description='View Jobs',
                 icon='suitcase',
                 tooltip="Open the Ray Job Dashboard"
             )
-    list_jobs_button.on_click(lambda b: _on_list_jobs_button_click(b, classification_widget, df, user_output, url_output))
+    list_jobs_button.on_click(lambda b: _on_list_jobs_button_click(b, classification_widget, ray_clusters_df, user_output, url_output))
 
     ray_dashboard_button = widgets.Button(
                 description='Open Ray Dashboard',
                 icon='dashboard',
                 tooltip="Open the Ray Dashboard in a new tab",
                 layout=widgets.Layout(width='auto'),
             )
-    ray_dashboard_button.on_click(lambda b: _on_ray_dashboard_button_click(b, classification_widget, df, user_output, url_output))
+    ray_dashboard_button.on_click(lambda b: _on_ray_dashboard_button_click(b, classification_widget, ray_clusters_df, user_output, url_output))
 
     display(widgets.VBox([classification_widget, raycluster_data_output]))
     display(widgets.HBox([delete_button, list_jobs_button, ray_dashboard_button]), url_output, user_output)
 
-# Handles the event when a cluster is selected from the toggle buttons, updating the output with cluster details.
+
 def _on_cluster_click(selection_change, raycluster_data_output: widgets.Output, namespace: str, classification_widget: widgets.ToggleButtons):
+    """
+    _on_cluster_click handles the event when a cluster is selected from the toggle buttons, updating the output with cluster details.
+    """
     new_value = selection_change["new"]
     raycluster_data_output.clear_output()
     df = _fetch_cluster_data(namespace)
@@ -163,6 +172,9 @@ def _on_cluster_click(selection_change, raycluster_data_output: widgets.Output,
 
 
 def _on_delete_button_click(b, classification_widget: widgets.ToggleButtons, df: pd.DataFrame, raycluster_data_output: widgets.Output, user_output: widgets.Output, delete_button: widgets.Button, list_jobs_button: widgets.Button, ray_dashboard_button: widgets.Button):
+    """
+    _on_delete_button_click handles the event when the Delete Button is clicked, deleting the selected cluster.
+    """
     cluster_name = classification_widget.value
     namespace = df[df["Name"]==classification_widget.value]["Namespace"].values[0]
 
@@ -186,6 +198,9 @@ def _on_delete_button_click(b, classification_widget: widgets.ToggleButtons, df:
         classification_widget.options = new_df["Name"].tolist()
 
 def _on_ray_dashboard_button_click(b, classification_widget: widgets.ToggleButtons, df: pd.DataFrame, user_output: widgets.Output, url_output: widgets.Output):
+    """
+    _on_ray_dashboard_button_click handles the event when the Open Ray Dashboard button is clicked, opening the Ray Dashboard in a new tab
+    """
     from codeflare_sdk.cluster import Cluster
     cluster_name = classification_widget.value
     namespace = df[df["Name"]==classification_widget.value]["Namespace"].values[0]
@@ -202,6 +217,9 @@ def _on_ray_dashboard_button_click(b, classification_widget: widgets.ToggleButto
         display(Javascript(f'window.open("{dashboard_url}", "_blank");'))
 
 def _on_list_jobs_button_click(b, classification_widget: widgets.ToggleButtons, df: pd.DataFrame, user_output: widgets.Output, url_output: widgets.Output):
+    """
+    _on_list_jobs_button_click handles the event when the View Jobs button is clicked, opening the Ray Jobs Dashboard in a new tab
+    """
     from codeflare_sdk.cluster import Cluster
     cluster_name = classification_widget.value
     namespace = df[df["Name"]==classification_widget.value]["Namespace"].values[0]
@@ -217,12 +235,17 @@ def _on_list_jobs_button_click(b, classification_widget: widgets.ToggleButtons,
     with url_output:
         display(Javascript(f'window.open("{dashboard_url}/#/jobs", "_blank");'))
 
+
 def _delete_cluster(
     cluster_name: str,
     namespace: str,
     timeout: int = 5,
     interval: int = 1,
 ):
+    """
+    _delete_cluster function deletes the cluster with the given name and namespace.
+    It optionally waits for the cluster to be deleted.
+    """
     from .cluster import _check_aw_exists
 
     try:
@@ -276,6 +299,9 @@ def _delete_cluster(
 
 
 def _fetch_cluster_data(namespace):
+    """
+    _fetch_cluster_data function fetches all clusters and their spec in a given namespace and returns a DataFrame.
+    """
     from .cluster import list_all_clusters
     rayclusters = list_all_clusters(namespace, False)
     if not rayclusters:
@@ -323,6 +349,9 @@ def _fetch_cluster_data(namespace):
 
 
 def _format_status(status):
+    """
+    _format_status function formats the status enum.
+    """
     status_map = {
         RayClusterStatus.READY: '<span style="color: green;">Ready ✓</span>',
         RayClusterStatus.SUSPENDED: '<span style="color: #007BFF;">Suspended ❄️</span>',