Improve the user experience when an ImportError occurs while instantiating tools

Fixes #20

Signed-off-by: Pedro Algarvio <[email protected]>

Author: s0undt3ch

changelog/20.feature.rst

@@ -0,0 +1,4 @@
+Improve the user experience when an `ImportError` occurs while instantiating tools.
+Instead of relying on direct imports, users can now call, `pyscripts.register_tools_module('tools.<whatever>')`.
+Python tools scripts will then import them one by one, catching and reporting any `ImportErrors` occurring.
+Due to these errors, some of the commands might be unavailable, but most likely not all, while providing a clue as to why that is.

src/ptscripts/__init__.py

@@ -6,6 +6,13 @@
 
 import ptscripts.logs
 from ptscripts.parser import command_group
-from ptscripts.parser import Context
+from ptscripts.parser import Context, RegisteredImports
 
-__all__ = ["command_group", "Context", "CWD"]
+__all__ = ["command_group", "register_tools_module", "Context", "CWD"]
+
+
+def register_tools_module(import_module: str) -> None:
+    """
+    Register a module to be imported when instantiating the tools parser.
+    """
+    RegisteredImports.register_import(import_module)

src/ptscripts/__main__.py

@@ -23,7 +23,6 @@ def main():
     except ImportError:
         # No tools/ directory in the current CWD
         pass
-
     parser.parse_args()
 
 

src/ptscripts/parser.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import importlib
 import inspect
 import logging
 import os
@@ -241,6 +242,40 @@ def web(self) -> requests.Session:
         return requests.Session()
 
 
+class RegisteredImports:
+    """
+    Simple class to hold registered imports.
+    """
+
+    _instance: RegisteredImports | None = None
+    _registered_imports: list[str]
+
+    def __new__(cls):
+        """
+        Method that instantiates a singleton class and returns it.
+        """
+        if cls._instance is None:
+            instance = super().__new__(cls)
+            instance._registered_imports = []
+            cls._instance = instance
+        return cls._instance
+
+    @classmethod
+    def register_import(cls, import_module: str) -> None:
+        """
+        Register an import.
+        """
+        instance = cls()
+        if import_module not in instance._registered_imports:
+            instance._registered_imports.append(import_module)
+
+    def __iter__(self):
+        """
+        Return an iterator of all registered imports.
+        """
+        return iter(self._registered_imports)
+
+
 class Parser:
     """
     Singleton parser class that wraps argparse.
@@ -328,10 +363,22 @@ def __new__(cls):
             cls._instance = instance
         return cls._instance
 
+    def _process_registered_tool_modules(self):
+        for module_name in RegisteredImports():
+            try:
+                importlib.import_module(module_name)
+            except ImportError as exc:
+                if os.environ.get("TOOLS_IGNORE_IMPORT_ERRORS", "0") == "0":
+                    self.context.warn(
+                        f"Could not import the registered tools module {module_name!r}: {exc}"
+                    )
+
     def parse_args(self):
         """
         Parse CLI.
         """
+        # Process registered imports to allow other modules to register commands
+        self._process_registered_tool_modules()
         options = self.parser.parse_args()
         if options.quiet:
             logging.root.setLevel(logging.CRITICAL + 1)