[pythonscripting] Implement debugger support (#20443)

* add python scripting debugger support

Signed-off-by: Holger Hees <holger.hees@gmail.com>

Author: HolgerHees

bundles/org.openhab.automation.pythonscripting/README.md

@@ -117,6 +117,19 @@ If you use the marketplace version of this Add-on, it is necessary to use the co
 # For tips and instructions, please refer to <a href="https://www.graalvm.org/latest/reference-manual/python/Modern-Python-on-JVM">Jython Migration Guide</a>.
 #
 #org.openhab.automation.pythonscripting:jythonEmulation = false
+
+# Enable debugger
+#
+# Enables Chrome Debugger support for Python Scripting. This allows you to attach any debugger compatible with the 
+# <a href="https://chromedevtools.github.io/devtools-protocol/">Chrome DevTools Protocol</a>, such as Chrome's Developer Tools or Visual Studio Code.
+#
+#org.openhab.automation.pythonscripting:debuggerEnabled = false
+
+# Debugger port
+#
+# The port to bind the debugger to.
+#
+#org.openhab.automation.pythonscripting:debuggerPort = 9230
 ```
 
 ### Console

bundles/org.openhab.automation.pythonscripting/src/main/feature/feature.xml

@@ -12,11 +12,12 @@
 		<bundle dependency="true">mvn:org.openhab.osgiify/org.graalvm.llvm.llvm-api/25.0.1</bundle>
 		<bundle dependency="true">mvn:org.openhab.osgiify/org.graalvm.shadowed.json/25.0.1</bundle>
 		<bundle dependency="true">mvn:org.openhab.osgiify/org.graalvm.shadowed.xz/25.0.1</bundle>
-		<bundle dependency="true">mvn:org.openhab.osgiify/org.graalvm.tools.profiler-tool/25.0.1</bundle>
 		<bundle dependency="true">mvn:org.openhab.osgiify/org.graalvm.polyglot.polyglot/25.0.1</bundle>
 		<bundle dependency="true">mvn:org.openhab.osgiify/org.graalvm.truffle.truffle-runtime/25.0.1</bundle>
 		<bundle dependency="true">mvn:org.openhab.osgiify/org.graalvm.truffle.truffle-compiler/25.0.1</bundle>
 		<bundle dependency="true" start-level="78">mvn:org.openhab.osgiify/org.graalvm.regex.regex/25.0.1</bundle>
+		<bundle dependency="true" start-level="78">mvn:org.openhab.osgiify/org.graalvm.tools.chromeinspector-tool/25.0.1</bundle>
+		<bundle dependency="true" start-level="78">mvn:org.openhab.osgiify/org.graalvm.tools.profiler-tool/25.0.1</bundle>
 		<bundle dependency="true" start-level="78">mvn:org.openhab.osgiify/org.graalvm.python.python-resources/25.0.1</bundle>
 		<bundle dependency="true" start-level="78">mvn:org.openhab.osgiify/org.graalvm.python.python-language/25.0.1</bundle>
 		<bundle dependency="true" start-level="78">mvn:org.openhab.osgiify/org.graalvm.truffle.truffle-nfi/25.0.1</bundle>

bundles/org.openhab.automation.pythonscripting/src/main/java/org/openhab/automation/pythonscripting/internal/PythonScriptEngine.java

@@ -45,14 +45,13 @@
 import org.graalvm.polyglot.Context;
 import org.graalvm.polyglot.Engine;
 import org.graalvm.polyglot.HostAccess;
-import org.graalvm.polyglot.Language;
 import org.graalvm.polyglot.PolyglotException;
 import org.graalvm.polyglot.Source;
 import org.graalvm.polyglot.Value;
 import org.graalvm.polyglot.io.IOAccess;
 import org.openhab.automation.pythonscripting.internal.context.ContextInput;
 import org.openhab.automation.pythonscripting.internal.context.ContextOutput;
-import org.openhab.automation.pythonscripting.internal.context.ContextOutputLogger;
+import org.openhab.automation.pythonscripting.internal.context.ThreadLocalContextOutputLogger;
 import org.openhab.automation.pythonscripting.internal.fs.DelegatingFileSystem;
 import org.openhab.automation.pythonscripting.internal.provider.LifecycleTracker;
 import org.openhab.automation.pythonscripting.internal.provider.ScriptExtensionModuleProvider;
@@ -83,10 +82,6 @@ public class PythonScriptEngine extends InvocationInterceptingPythonScriptEngine
     public static final String CONTEXT_KEY_ENGINE_LOGGER_INPUT = "ctx.engine-logger-input";
     private static final String CONTEXT_KEY_SCRIPT_FILENAME = "javax.script.filename";
 
-    private static final String PYTHON_OPTION_ENGINE_WARNINTERPRETERONLY = "engine.WarnInterpreterOnly";
-
-    private static final String SYSTEM_PROPERTY_ATTACH_LIBRARY_FAILURE_ACTION = "polyglotimpl.AttachLibraryFailureAction";
-
     private static final String PYTHON_OPTION_PYTHONPATH = "python.PythonPath";
     private static final String PYTHON_OPTION_EMULATEJYTHON = "python.EmulateJython";
     private static final String PYTHON_OPTION_POSIXMODULEBACKEND = "python.PosixModuleBackend";
@@ -106,16 +101,6 @@ public class PythonScriptEngine extends InvocationInterceptingPythonScriptEngine
 
     private static final String LOGGER_INIT_NAME = "__logger_init__";
 
-    /** Shared Polyglot {@link Engine} across all instances of {@link PythonScriptEngine} */
-    private static Engine engine = Engine.newBuilder()
-            // disable warning about fallback runtime (is only available in graalvm)
-            .option(PYTHON_OPTION_ENGINE_WARNINTERPRETERONLY, Boolean.toString(false)).build();
-
-    static {
-        // disable warning about missing TruffleAttach library (is only available in graalvm)
-        System.getProperties().setProperty(SYSTEM_PROPERTY_ATTACH_LIBRARY_FAILURE_ACTION, "ignore");
-    }
-
     // private static final boolean isPosix = FileSystems.getDefault().supportedFileAttributeViews().contains("posix");
 
     /** Provides unlimited host access as well as custom translations from Python to Java Objects */
@@ -166,12 +151,12 @@ public class PythonScriptEngine extends InvocationInterceptingPythonScriptEngine
      * Creates an implementation of ScriptEngine {@code (& Invocable)}, wrapping the contained engine,
      * that tracks the script lifecycle and provides hooks for scripts to do so too.
      */
-    public PythonScriptEngine(PythonScriptEngineConfiguration pythonScriptEngineConfiguration,
+    public PythonScriptEngine(PythonScriptEngineConfiguration pythonScriptEngineConfiguration, Engine engine,
             PythonScriptEngineFactory pythonScriptEngineFactory) {
         this.pythonScriptEngineConfiguration = pythonScriptEngineConfiguration;
 
-        this.scriptOutputStream = new ContextOutput(new ContextOutputLogger(logger, Level.INFO));
-        this.scriptErrorStream = new ContextOutput(new ContextOutputLogger(logger, Level.ERROR));
+        this.scriptOutputStream = new ContextOutput(new ThreadLocalContextOutputLogger(logger, Level.INFO));
+        this.scriptErrorStream = new ContextOutput(new ThreadLocalContextOutputLogger(logger, Level.ERROR));
         this.scriptInputStream = new ContextInput(null);
 
         this.lifecycleTracker = new LifecycleTracker();
@@ -510,8 +495,8 @@ private void setScriptLogger() {
 
         Logger scriptLogger = LoggerFactory.getLogger("org.openhab.automation.pythonscripting." + identifier);
 
-        scriptOutputStream.setOutputStream(new ContextOutputLogger(scriptLogger, Level.INFO));
-        scriptErrorStream.setOutputStream(new ContextOutputLogger(scriptLogger, Level.ERROR));
+        scriptOutputStream.setOutputStream(new ThreadLocalContextOutputLogger(scriptLogger, Level.INFO));
+        scriptErrorStream.setOutputStream(new ThreadLocalContextOutputLogger(scriptLogger, Level.ERROR));
     }
 
     private String stringifyThrowable(Throwable throwable) {
@@ -631,8 +616,4 @@ private static ZonedDateTime parseDatetime(Value value) {
                         ? OffsetDateTime.now().getOffset().getId()
                         : ""));
     }
-
-    public static @Nullable Language getLanguage() {
-        return engine.getLanguages().get(GraalPythonScriptEngine.LANGUAGE_ID);
-    }
 }

bundles/org.openhab.automation.pythonscripting/src/main/java/org/openhab/automation/pythonscripting/internal/PythonScriptEngineConfiguration.java

@@ -48,7 +48,7 @@ public class PythonScriptEngineConfiguration {
     private final Logger logger = LoggerFactory.getLogger(PythonScriptEngineConfiguration.class);
 
     private static final String SYSTEM_PROPERTY_POLYGLOT_ENGINE_USERRESOURCECACHE = "polyglot.engine.userResourceCache";
-
+    private static final String SYSTEM_PROPERTY_ATTACH_LIBRARY_FAILURE_ACTION = "polyglotimpl.AttachLibraryFailureAction";
     private static final String SYSTEM_PROPERTY_JAVA_IO_TMPDIR = "java.io.tmpdir";
 
     public static final String PATH_SEPARATOR = FileSystems.getDefault().getSeparator();
@@ -67,12 +67,16 @@ public class PythonScriptEngineConfiguration {
     private static final int INJECTION_ENABLED_FOR_SCRIPT_MODULES_AND_TRANSFORMATIONS = 3;
     private static final int INJECTION_ENABLED_FOR_ALL_SCRIPTS = 4;
 
+    private static final int DEBUGGER_PORT_DEFAULT = 9230;
+
     // The variable names must match the configuration keys in config.xml
     public static class PythonScriptingConfiguration {
         public int injectionEnabled = INJECTION_ENABLED_FOR_SCRIPT_MODULES_ONLY;
         public boolean dependencyTrackingEnabled = true;
         public boolean cachingEnabled = true;
         public boolean jythonEmulation = false;
+        public boolean debuggerEnabled = false;
+        public int debuggerPort = DEBUGGER_PORT_DEFAULT;
         public String pipModules = "";
     }
 
@@ -94,6 +98,11 @@ public static Version parseHelperLibVersion(@Nullable String version) throws Ill
         return Version.parse(version != null && version.startsWith("v") ? version.substring(1) : version);
     }
 
+    static {
+        // disable warning about missing TruffleAttach library (is only available in graalvm)
+        System.getProperties().setProperty(SYSTEM_PROPERTY_ATTACH_LIBRARY_FAILURE_ACTION, "ignore");
+    }
+
     @Activate
     public PythonScriptEngineConfiguration(Map<String, Object> config) {
         Path userdataDir = Paths.get(OpenHAB.getUserDataFolder());
@@ -123,6 +132,7 @@ public PythonScriptEngineConfiguration(Map<String, Object> config) {
         Properties props = System.getProperties();
         props.setProperty(SYSTEM_PROPERTY_POLYGLOT_ENGINE_USERRESOURCECACHE,
                 userdataDir.resolve("cache").resolve("org.graalvm.polyglot").toString());
+        props.setProperty(SYSTEM_PROPERTY_ATTACH_LIBRARY_FAILURE_ACTION, "ignore");
 
         String packageName = PythonScriptEngineConfiguration.class.getPackageName();
         packageName = packageName.substring(0, packageName.lastIndexOf("."));
@@ -153,22 +163,31 @@ public void init(PythonScriptEngineFactory factory) {
     public void modified(Map<String, Object> config, PythonScriptEngineFactory factory) {
         int oldInjectionEnabled = configuration.injectionEnabled;
         boolean oldDependencyTrackingEnabled = isDependencyTrackingEnabled();
-
         String oldPipModules = configuration.pipModules;
+        boolean oldDebuggerEnabled = configuration.debuggerEnabled;
+        int oldDebuggerPort = configuration.debuggerPort;
+
         configuration = new Configuration(config).as(PythonScriptingConfiguration.class);
+
         if (!oldPipModules.equals(configuration.pipModules)) {
             PythonScriptEngineHelper.initPipModules(this, factory);
         }
 
         if (oldInjectionEnabled != configuration.injectionEnabled) {
-            logger.info(
+            logger.warn(
                     "Changed helper module setting for Python Scripting. Please resave your python scripts to apply this change.");
         }
         if (oldDependencyTrackingEnabled != isDependencyTrackingEnabled()) {
-            logger.info(
+            logger.warn(
                     "{} dependency tracking for Python Scripting. Please resave your python scripts to apply this change.",
                     isDependencyTrackingEnabled() ? "Enabled" : "Disabled");
         }
+        if (oldDebuggerEnabled != configuration.debuggerEnabled) {
+            logger.warn("{} debugger for Python Scripting. Restart openHAB to apply this change.",
+                    configuration.debuggerEnabled ? "Enabled" : "Disabled");
+        } else if (oldDebuggerPort != configuration.debuggerPort) {
+            logger.warn("Reconfigured debugger for Python Scripting. Restart openHAB to apply this change.");
+        }
     }
 
     public void setHelperLibVersion(Version version) {
@@ -203,6 +222,14 @@ public boolean isJythonEmulation() {
         return configuration.jythonEmulation;
     }
 
+    public boolean isDebuggerEnabled() {
+        return configuration.debuggerEnabled;
+    }
+
+    public int getDebuggerPort() {
+        return configuration.debuggerPort;
+    }
+
     public String getPIPModules() {
         return configuration.pipModules;
     }

bundles/org.openhab.automation.pythonscripting/src/main/java/org/openhab/automation/pythonscripting/internal/PythonScriptEngineFactory.java

@@ -23,8 +23,10 @@
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
+import org.graalvm.polyglot.Engine;
 import org.graalvm.polyglot.Language;
 import org.openhab.automation.pythonscripting.internal.fs.PythonDependencyTracker;
+import org.openhab.automation.pythonscripting.internal.scriptengine.graal.GraalPythonScriptEngine;
 import org.openhab.automation.pythonscripting.internal.scriptengine.graal.GraalPythonScriptEngine.ScriptEngineProvider;
 import org.openhab.core.automation.module.script.ScriptDependencyTracker;
 import org.openhab.core.automation.module.script.ScriptEngineFactory;
@@ -60,19 +62,18 @@ public class PythonScriptEngineFactory implements ScriptEngineFactory, ScriptEng
     private final PythonDependencyTracker pythonDependencyTracker;
     private final PythonScriptEngineConfiguration configuration;
 
-    private final @Nullable Language language;
+    private static final String PYTHON_OPTION_ENGINE_WARNINTERPRETERONLY = "engine.WarnInterpreterOnly";
+
+    /**
+     * Shared Polyglot {@link Engine} instance to be used by all instances of {@link PythonScriptEngine}.
+     */
+    private final Engine engine;
 
     @Activate
     public PythonScriptEngineFactory(final @Reference PythonDependencyTracker pythonDependencyTracker,
             final @Reference TimeZoneProvider timeZoneProvider, Map<String, Object> config) {
         logger.debug("Loading PythonScriptEngineFactory");
 
-        this.language = PythonScriptEngine.getLanguage();
-        if (this.language == null) {
-            logger.error(
-                    "Graal Python language not initialized. Restart openHAB to initialize available Graal languages properly.");
-        }
-
         String defaultTimezone = ZoneId.systemDefault().getId();
         String providerTimezone = timeZoneProvider.getTimeZone().getId();
         if (!defaultTimezone.equals(providerTimezone)) {
@@ -84,6 +85,41 @@ public PythonScriptEngineFactory(final @Reference PythonDependencyTracker python
         this.pythonDependencyTracker = pythonDependencyTracker;
         this.configuration = new PythonScriptEngineConfiguration(config);
         this.configuration.init(this);
+
+        Engine.Builder engineBuilder = createEngineBuilder();
+        if (configuration.isDebuggerEnabled()) {
+            engineBuilder //
+                    .option("inspect", "0.0.0.0:" + configuration.getDebuggerPort()) //
+                    .option("inspect.Suspend", "false") // Don't pause at startup waiting for debugger to attach
+                    .option("inspect.WaitAttached", "false") // Don't block code execution waiting for debugger to
+                                                             // attach
+                    .option("inspect.Secure", "false"); // Disable TLS
+
+            Engine engine;
+            try {
+                engine = engineBuilder.build();
+                logger.info("Debugger support is enabled for Python Scripting on port {}",
+                        configuration.getDebuggerPort());
+            } catch (RuntimeException e) {
+                logger.error(
+                        "Failed to initialize Graal Python engine with debugger support. Continuing without debugger support.",
+                        e);
+                engine = createEngineBuilder().build();
+            }
+            this.engine = engine;
+        } else {
+            this.engine = createEngineBuilder().build();
+        }
+
+        if (getLanguage() == null) {
+            logger.error(
+                    "Graal Python language not initialized. Restart openHAB to initialize available Graal languages properly.");
+        }
+    }
+
+    private Engine.Builder createEngineBuilder() {
+        return Engine.newBuilder().allowExperimentalOptions(true) //
+                .option(PYTHON_OPTION_ENGINE_WARNINTERPRETERONLY, Boolean.toString(false));
     }
 
     @Deactivate
@@ -127,10 +163,10 @@ public void scopeValues(ScriptEngine scriptEngine, Map<String, Object> scopeValu
 
     @Override
     public @Nullable ScriptEngine createScriptEngine() {
-        if (language == null) {
+        if (getLanguage() == null) {
             return null;
         }
-        return new PythonScriptEngine(configuration, this);
+        return new PythonScriptEngine(configuration, engine, this);
     }
 
     @Override
@@ -141,4 +177,13 @@ public void scopeValues(ScriptEngine scriptEngine, Map<String, Object> scopeValu
     public PythonScriptEngineConfiguration getConfiguration() {
         return this.configuration;
     }
+
+    /**
+     * Gets the Graal language of {@link PythonScriptEngine}.
+     *
+     * @return the Graal language of {@link PythonScriptEngine} or {@code null} if not available
+     */
+    public @Nullable Language getLanguage() {
+        return engine.getLanguages().get(GraalPythonScriptEngine.LANGUAGE_ID);
+    }
 }

bundles/org.openhab.automation.pythonscripting/src/main/java/org/openhab/automation/pythonscripting/internal/console/PythonConsoleCommandExtension.java

@@ -174,7 +174,8 @@ public void execute(String[] args, Console console) {
     }
 
     private void info(Console console) {
-        new InfoCmd(pythonScriptEngineConfiguration, console).show(configDescriptionRegistry);
+        new InfoCmd(pythonScriptEngineConfiguration, console, this.pythonScriptEngineFactory.getLanguage())
+                .show(configDescriptionRegistry);
     }
 
     private void startConsole(Console console, String[] args) {

bundles/org.openhab.automation.pythonscripting/src/main/java/org/openhab/automation/pythonscripting/internal/console/handler/InfoCmd.java

@@ -20,8 +20,8 @@
 import java.util.Map;
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
 import org.graalvm.polyglot.Language;
-import org.openhab.automation.pythonscripting.internal.PythonScriptEngine;
 import org.openhab.automation.pythonscripting.internal.PythonScriptEngineConfiguration;
 import org.openhab.automation.pythonscripting.internal.PythonScriptEngineFactory;
 import org.openhab.core.config.core.ConfigDescription;
@@ -38,10 +38,12 @@
 public class InfoCmd {
     private final PythonScriptEngineConfiguration config;
     private final Console console;
+    private final @Nullable Language language;
 
-    public InfoCmd(PythonScriptEngineConfiguration config, Console console) {
+    public InfoCmd(PythonScriptEngineConfiguration config, Console console, @Nullable Language language) {
         this.config = config;
         this.console = console;
+        this.language = language;
     }
 
     public void show(ConfigDescriptionRegistry registry) {
@@ -50,7 +52,6 @@ public void show(ConfigDescriptionRegistry registry) {
         console.println("  Runtime:");
         console.println("    Bundle version: " + config.getBundleVersion());
         console.println("    GraalVM version: " + config.getGraalVersion());
-        Language language = PythonScriptEngine.getLanguage();
         console.println("    Python version: " + (language != null ? language.getVersion() : "unavailable"));
         Version version = config.getInstalledHelperLibVersion();
         console.println("    Helper lib version: " + (version != null ? version.toString() : "disabled"));