siliconcompiler 0.34.2__py3-none-any.whl → 0.34.3__py3-none-any.whl

siliconcompiler/report/dashboard/web/__init__.py

@@ -16,18 +16,37 @@ from siliconcompiler.report.dashboard.web import utils
 
 
 class WebDashboard(AbstractDashboard):
+    """
+    A web-based dashboard for SiliconCompiler that uses the Streamlit framework.
+
+    This class launches a Streamlit server in a separate process to provide a
+    real-time, interactive web UI for monitoring a chip's compilation flow.
+    It manages a temporary directory for passing manifests and configuration
+    between the main SC process and the Streamlit dashboard process.
+
+    Args:
+        chip (Chip): The main chip object to display.
+        port (int, optional): The port to run the Streamlit server on. If not
+            provided, it will search for an available port.
+        graph_chips (list, optional): A list of other chip objects to include
+            for comparison or display in the dashboard.
+    """
     __port = 8501
 
     @staticmethod
     def __signal_handler(signal, frame):
+        """A no-op signal handler to gracefully manage shutdown."""
         # used to avoid issues during shutdown
         pass
 
     def __init__(self, chip, port=None, graph_chips=None):
+        """
+        Initializes the WebDashboard.
+        """
         try:
             from streamlit.web import bootstrap  # noqa: F401
         except ModuleNotFoundError:
-            raise NotImplementedError('streamlit is not available')
+            raise NotImplementedError('streamlit is not available for dashboard')
 
         super().__init__(chip)
 
@@ -46,6 +65,7 @@ class WebDashboard(AbstractDashboard):
         dirname = os.path.dirname(__file__)
         self.__streamlit_file = os.path.join(dirname, 'viewer.py')
 
+        # Configure Streamlit server options
         self.__streamlit_args = [
             ("browser.gatherUsageStats", False),
             ("browser.serverPort", self.__port),
@@ -57,11 +77,7 @@ class WebDashboard(AbstractDashboard):
         if "PYTEST_CURRENT_TEST" in os.environ:
             self.__streamlit_args.append(("server.headless", True))
 
-        # pass in a json object called __graph_chips
-        # the key is the chip_name and value is the filepath
-        # if another argument is passed
-
-        # use of list is to preserve order
+        # Prepare configuration for any additional chips to be displayed
         self.__graph_chips = []
         graph_chips_config = []
         if graph_chips:
@@ -80,6 +96,7 @@ class WebDashboard(AbstractDashboard):
                         chip_object_and_name['cfg_path'])
                 })
 
+        # Final configuration object to be passed to the Streamlit process
         self.__config = {
             "manifest": self.__manifest,
             "lock": self.__manifest_lock,
@@ -91,27 +108,43 @@ class WebDashboard(AbstractDashboard):
 
         self.__lock = fasteners.InterProcessLock(self.__manifest_lock)
 
+        # Ensure cleanup is called on exit
         atexit.register(self.__cleanup)
 
     def open_dashboard(self):
+        """
+        Starts the Streamlit dashboard server in a new process.
+
+        This method writes the necessary configuration and manifests, then
+        launches the Streamlit bootstrap function in a separate process.
+        """
+        # Write the configuration file for the Streamlit app to read
         with open(self.__get_config_file(), 'w') as f:
             json.dump(self.__config, f, indent=4)
 
         self.update_manifest()
-
         self.update_graph_manifests()
 
+        # Launch Streamlit in a separate process
         self.__dashboard = multiprocessing.Process(
             target=self._run_streamlit_bootstrap)
 
+        # Temporarily override the SIGINT handler for graceful shutdown
         self.__signal_handler = signal.signal(signal.SIGINT, WebDashboard.__signal_handler)
 
         self.__dashboard.start()
 
     def update_manifest(self, payload=None):
+        """
+        Writes the main chip's manifest to the shared temporary directory.
+
+        This method is the primary way data is passed from the main process
+        to the dashboard process. It uses a file lock to prevent race conditions.
+        """
         if not self.__manifest:
             return
 
+        # Write to a new file and then move it to be atomic
         new_file = f"{self.__manifest}.new.json"
         self.__chip.write_manifest(new_file)
 
@@ -119,71 +152,108 @@ class WebDashboard(AbstractDashboard):
             shutil.move(new_file, self.__manifest)
 
     def update_graph_manifests(self):
+        """
+        Writes the manifests for all additional graph chips to the shared directory.
+        """
         for chip_object_and_name in self.__graph_chips:
             chip = chip_object_and_name['chip']
             file_path = chip_object_and_name['name']
             chip.write_manifest(file_path)
 
     def __get_config_file(self):
+        """Returns the path to the dashboard's JSON configuration file."""
         return os.path.join(self.__directory, 'config.json')
 
     def is_running(self):
+        """
+        Checks if the dashboard server process is currently running.
+
+        Returns:
+            bool: True if the dashboard is running, False otherwise.
+        """
         if self.__dashboard is None:
             return False
 
         if self.__dashboard.is_alive():
             return True
 
+        # Process is no longer alive, so clean up
         self.__dashboard = None
         self.__manifest = None
         return False
 
     def end_of_run(self):
+        """A placeholder method to fulfill the AbstractDashboard interface."""
         pass
 
     def stop(self):
+        """
+        Stops the dashboard server process.
+        """
         if not self.is_running():
             return
 
+        # Terminate the process
         while self.__dashboard.is_alive():
             self.__dashboard.terminate()
             self._sleep()
 
+        # Restore the original signal handler
         if self.__signal_handler:
             signal.signal(signal.SIGINT, self.__signal_handler)
 
+        # Clean up state
         self.__dashboard = None
         self.__manifest = None
         self.__signal_handler = None
 
     def wait(self):
-        self.__dashboard.join()
+        """
+        Waits for the dashboard server process to terminate.
+        """
+        if self.is_running():
+            self.__dashboard.join()
 
     def _sleep(self):
+        """Pauses execution for a short duration."""
         time.sleep(self.__sleep_time)
 
     def _run_streamlit_bootstrap(self):
+        """
+        The target function for the multiprocessing.Process.
+
+        This function configures and runs the Streamlit application.
+        """
         from streamlit.web import bootstrap
         from streamlit import config as _config
 
+        # Set all configured Streamlit options
         for config, val in self.__streamlit_args:
             _config.set_option(config, val)
 
+        # Run the Streamlit script
         bootstrap.run(self.__streamlit_file,
                       False,
                       [self.__get_config_file()],
                       flag_options={})
 
     def __run_streamlit_subproc(self):
+        """
+        An alternative (unused) method to run Streamlit using a subprocess.
+        """
         cmd = ['streamlit', 'run',
                self.__streamlit_file, self.__get_config_file()]
         for config, val in self.__streamlit_args:
             cmd.append(f'--{config}')
-            cmd.append(val)
+            cmd.append(str(val))
 
         subprocess.Popen(cmd)
 
     def __cleanup(self):
+        """
+        Cleans up resources by stopping the dashboard and removing the temp directory.
+        This method is registered with atexit to be called on program exit.
+        """
         self.stop()
 
         if os.path.exists(self.__directory):
@@ -191,6 +261,14 @@ class WebDashboard(AbstractDashboard):
 
     @staticmethod
     def get_next_port():
-        with socketserver.TCPServer(("localhost", 0), None) as s:
-            return s.server_address[1]
-        return None
+        """
+        Finds an available TCP port on the local machine.
+
+        Returns:
+            int or None: An available port number, or None if one cannot be found.
+        """
+        try:
+            with socketserver.TCPServer(("localhost", 0), None) as s:
+                return s.server_address[1]
+        except OSError:
+            return None