add: docstrings to setup gdrive dialog

Author: shrey

datashuttle/tui/screens/setup_gdrive.py

@@ -21,7 +21,14 @@
 
 
 class SetupGdriveScreen(ModalScreen):
-    """ """
+    """
+    This dialog window handles the TUI equivalent of API's `setup_google_drive_connection`.
+    If the config contains a  "gdrive_client_id", the user is prompted to enter a client secret.
+    Then, the user is asked if the their machine has access to a browser. If yes, a
+    google drive authentication page on the user's default browser opens up. Else,
+    the user is asked to run an rclone command on a machine with access to a browser and
+    input the config token generated by rclone.
+    """
 
     def __init__(self, interface: Interface) -> None:
         super(SetupGdriveScreen, self).__init__()
@@ -54,7 +61,28 @@ def compose(self) -> ComposeResult:
         )
 
     def on_button_pressed(self, event: Button.Pressed) -> None:
-        """ """
+        """
+        This dialog window operates using 6 buttons.
+
+        1) "ok" button : Starts the connection setup process. It has an intermediate
+            step that asks the user for client secret if "gdrive_client_id" is present
+            in configs. And then proceeds to ask the user for browser availability.
+            This is done via a `stage` variable. If asking the user for client secret,
+            the stage is incremented by 0.5 on two steps. Else, `ask_user_for_browser`
+            increments the stage directly by 1.
+
+        2) "yes" button : A "yes" answer to the availability of browser question. On click,
+            proceeds to a browser authentication.
+
+        3) "no" button : A "no" answer to the availability of browser question. On click,
+            prompts the user to enter a config token by running an rclone command.
+
+        4) "enter" button : To enter the config token generated by rclone.
+
+        5) "finish" button : To finish the setup.
+
+        6) "cancel" button : To cancel the setup at any step before completion.
+        """
         if (
             event.button.id == "setup_gdrive_cancel_button"
             or event.button.id == "setup_gdrive_finish_button"
@@ -88,6 +116,10 @@ def on_button_pressed(self, event: Button.Pressed) -> None:
             self.setup_gdrive_connection_using_config_token()
 
     def ask_user_for_gdrive_client_secret(self) -> None:
+        """
+        Asks the user for google drive client secret. Only called if
+        the datashuttle config has a gdrive_client_id.
+        """
         message = (
             "Please provide the client secret for Google Drive. "
             "You can find it in your Google Cloud Console."
@@ -102,6 +134,9 @@ def ask_user_for_gdrive_client_secret(self) -> None:
         self.stage += 0.5
 
     def ask_user_for_browser(self) -> None:
+        """
+        Asks the user if their machine has access to a browser.
+        """
         message = (
             "Are you running Datashuttle on a machine "
             "that can open a web browser?"
@@ -126,6 +161,13 @@ def ask_user_for_browser(self) -> None:
         self.stage += 0.5 if self.stage == 0.5 else 1
 
     def open_browser_and_setup_gdrive_connection(self) -> None:
+        """
+        This removes the "yes" and "no" buttons that were asked during the
+        browser question and starts an asyncio task that sets up google drive
+        connection and updates the UI with success/failure. The connection setup
+        is asynchronous so that the user is able to cancel the setup if anything
+        goes wrong without quitting datashuttle altogether.
+        """
         message = "Please authenticate through browser."
         self.update_message_box_message(message)
 
@@ -163,6 +205,10 @@ def prompt_user_for_config_token(self) -> None:
         self.mount_input_box_before_buttons()
 
     def setup_gdrive_connection_using_config_token(self) -> None:
+        """
+        Disables the enter button and starts an asyncio task to setup
+        google drive connection and update the UI with success/failure.
+        """
 
         self.input_box.disabled = True
 
@@ -178,6 +224,11 @@ def setup_gdrive_connection_using_config_token(self) -> None:
     async def setup_gdrive_connection_and_update_ui(
         self, config_token: Optional[str] = None
     ) -> None:
+        """
+        This starts the google drive connection setup in a separate thread (required
+        to have asynchronous processing) and awaits for its completion. After completion,
+        it displays a success / failure screen.
+        """
         worker = self.setup_gdrive_connection(config_token)
         self.setup_worker = worker
         if worker.is_running:
@@ -197,6 +248,12 @@ async def setup_gdrive_connection_and_update_ui(
     def setup_gdrive_connection(
         self, config_token: Optional[str] = None
     ) -> Worker[InterfaceOutput]:
+        """
+        This function runs in a worker thread to setup google drive connection.
+        If the user had access to a browser, the underlying rclone commands called
+        by this function are responsible for opening google's auth page to authenticate
+        with google drive.
+        """
         success, output = self.interface.setup_google_drive_connection(
             self.gdrive_client_secret, config_token
         )