Merge pull request #1428 from compas-dev/code-reloader

Added `DevTools` with support for automatic reloading of local python modules

Author: gonzalocasas

CHANGELOG.md

@@ -9,10 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* Added `DevTools` with support for automatic reloading of local python modules.
 * Added implementation for `compas_rhino.geometry.RhinoBrep.from_step`.
 
 ### Changed
 
+* Moved `unload_modules` to be a static method of `DevTools`. The `unload_modules` function is an alias to this. 
 * Fixed unexpected behavior in `compas.geometry.bbox_numpy.minimum_area_rectangle_xy`.
 * Changed `requirements.txt` to allow `numpy>=2`.
 * Fixed bug in `compas.geometry.Polygon.points` setter by removing duplicate points if they exist.

docs/userguide/cad.grasshopper.rst

@@ -49,14 +49,14 @@ Reloading changed libraries
 If you change a Python library during a running Rhino application, which is
 imported in a GhPython component (e.g. via ``import compas_fab``),
 it is necessary to reload the library so that the GhPython interpreter
-recognizes the changes. To avoid restarting Rhino, you can use the function
-``unload_modules``. The following example reloads the library ``compas_fab``.
+recognizes the changes. To avoid restarting Rhino, you can use the method
+``unload_modules`` of ``DevTools``. The following example reloads the library ``compas_fab``.
 
 .. code-block:: python
 
-    from compas_ghpython import unload_modules
+    from compas_rhino import DevTools
 
-    unload_modules('compas_fab')
+    DevTools.unload_modules('compas_fab')
 
 .. note::
 
@@ -65,3 +65,50 @@ recognizes the changes. To avoid restarting Rhino, you can use the function
     in COMPAS not being able to find a `SceneObject` as well as other issues
     related to a mid-workflow re-definition of Python types.
 
+
+Python Scripting Outside Rhino/Grasshopper with Auto-Reloading
+==============================================================
+
+Developing Python scripts outside of Rhino/Grasshopper allows you to take advantage of
+modern code editors. However, this workflow requires two key steps: ensuring the Python
+interpreter can access your script's location and enabling automatic reloading of the
+script when changes are made in your external editor.
+If the scripts or modules you are working on are located in the same folder as the Rhino/Grasshopper file you are editing, the ``DevTools`` class can be used to make them importable and reload them automatically when modified.
+
+This approach provides a seamless workflow for developing Python scripts in modern IDEs,
+such as Visual Studio Code, while running and testing the code inside Rhino/Grasshopper
+with minimal interruptions.
+
+Enabling Auto-Reloading
+-----------------------
+
+To enable this feature, use the ``enable_reloader`` method of the ``DevTools`` class.
+This makes all Python scripts in the same folder as the Grasshopper file importable
+and ensures they automatically reload when changes are applied.
+
+.. code-block:: python
+
+    from compas_rhino import DevTools
+    DevTools.enable_reloader()
+
+.. note::
+
+    Call this method early in your script to start the monitoring service immediately.
+
+Importing Local Modules
+-----------------------
+
+Once auto-reloading is enabled, any script component that needs to use local modules can include the following at the top of the script:
+
+.. code-block:: python
+
+    from compas_rhino import DevTools
+    DevTools.ensure_path()
+
+This ensures local modules are accessible. For instance, if a file named ``my_module.py`` is in
+the same folder as your Grasshopper file, you can import it in a script component like this:
+
+.. code-block:: python
+
+    import my_module
+

src/compas_rhino/__init__.py

@@ -2,10 +2,10 @@
 
 import io
 import os
-import sys
 
 import compas
 import compas._os
+from compas_rhino.devtools import DevTools
 
 __version__ = "2.8.1"
 
@@ -23,6 +23,7 @@
 GRASSHOPPER_PLUGIN_GUID = "b45a29b1-4343-4035-989e-044e8580d9cf"
 RHINOCYCLES_PLUGIN_GUID = "9bc28e9e-7a6c-4b8f-a0c6-3d05e02d1b97"
 
+unload_modules = DevTools.unload_modules
 
 __all__ = [
     "PURGE_ON_DELETE",
@@ -35,6 +36,7 @@
     "RHINOCYCLES_PLUGIN_GUID",
     "clear",
     "redraw",
+    "unload_modules",
 ]
 
 __all_plugins__ = [
@@ -59,30 +61,6 @@
 # =============================================================================
 
 
-def unload_modules(top_level_module_name):
-    """Unloads all modules named starting with the specified string.
-
-    This function eases the development workflow when editing a library that is
-    used from Rhino/Grasshopper.
-
-    Parameters
-    ----------
-    top_level_module_name : :obj:`str`
-        Name of the top-level module to unload.
-
-    Returns
-    -------
-    list
-        List of unloaded module names.
-    """
-    to_remove = [name for name in sys.modules if name.startswith(top_level_module_name)]
-
-    for module in to_remove:
-        sys.modules.pop(module)
-
-    return to_remove
-
-
 def clear(guids=None):
     import compas_rhino.objects
 

src/compas_rhino/devtools.py

@@ -0,0 +1,134 @@
+import os
+import sys
+
+__all__ = [
+    "DevTools",
+]
+
+
+class DevTools(object):
+    """Tools for working with Python code in development mode, unloading, and reloading code."""
+
+    def __init__(self):
+        """Initializes a new instance of the DevTools class."""
+        self.watcher = None
+
+    @staticmethod
+    def unload_modules(top_level_module_name):
+        """Unloads all modules named starting with the specified string.
+
+        This function eases the development workflow when editing a library that is
+        used from Rhino/Grasshopper.
+
+        Parameters
+        ----------
+        top_level_module_name : :obj:`str`
+            Name of the top-level module to unload.
+
+        Returns
+        -------
+        list
+            List of unloaded module names.
+        """
+        to_remove = [name for name in sys.modules if name.startswith(top_level_module_name)]
+
+        for module in to_remove:
+            sys.modules.pop(module)
+
+        return to_remove
+
+    @classmethod
+    def enable_reloader(cls):
+        """Enables the code reload on the current folder.
+
+        The file must have been saved already in order for this to work."""
+        cls._manage_reloader(enable=True)
+
+    @classmethod
+    def disable_reloader(cls):
+        """Disables the code reload on the current folder.
+
+        The file must have been saved already in order for this to work."""
+        cls._manage_reloader(enable=False)
+
+    @classmethod
+    def _manage_reloader(cls, enable):
+        import scriptcontext
+
+        doc_id = scriptcontext.doc.Component.OnPingDocument().DocumentID.ToString()
+        key = "__compas_devtools_{}__".format(doc_id)
+        if key in scriptcontext.sticky:
+            reloader = scriptcontext.sticky[key]
+            reloader.stop_watcher()
+            reloader = None
+            del reloader
+
+        if enable:
+            reloader = DevTools()
+            reloader.start_watcher()
+            scriptcontext.sticky[key] = reloader
+
+    @staticmethod
+    def ensure_path():
+        """Ensures the current folder is in the system path."""
+        # Not sure why we need to import sys inside this method but GH complains otherwise
+        import scriptcontext
+
+        # First ensure the current folder is in the system path
+        filepath = scriptcontext.doc.Component.OnPingDocument().FilePath
+
+        if not filepath:
+            raise Exception("It seems this file is not saved, cannot reload files without knowning where to search for them!")
+
+        dirname = os.path.dirname(filepath)
+        if dirname not in sys.path:
+            sys.path.append(dirname)
+
+        return dirname
+
+    def start_watcher(self):
+        try:
+            from System.IO import FileSystemWatcher  # noqa : F401
+            from System.IO import NotifyFilters  # noqa : F401
+        except ImportError:
+            raise Exception("This component requires the System.IO.FileSystemWatcher class to work")
+
+        dirname = self.ensure_path()
+
+        # Disable previous watchers if any
+        if self.watcher:
+            self.disable()
+
+        # Setup file system watcher on python files
+        self.watcher = FileSystemWatcher()
+        self.watcher.Path = dirname
+        self.watcher.NotifyFilter = NotifyFilters.LastWrite
+        self.watcher.IncludeSubdirectories = False
+        self.watcher.Filter = "*.py"
+        self.watcher.Changed += self.on_changed
+        self.watcher.EnableRaisingEvents = True
+
+    def on_changed(self, sender, args):
+        try:
+            # Get module name from full path
+            filename = os.path.basename(args.FullPath)
+            if filename.lower().endswith(".py"):
+                module_name = filename.split(".")[0]
+
+                # Unload the modified module
+                self.unload_modules(module_name)
+        except Exception:
+            print("Something failed during unload, this message will not be printed anywhere thou, deal with it")
+
+    def stop_watcher(self):
+        try:
+            if self.watcher:
+                self.watcher.Changed
+                self.watcher.Dispose()
+                del self.watcher
+        except:  # noqa : E722
+            pass
+        self.watcher = None
+
+
+unload_modules = DevTools.unload_modules