[pythonscripting] Simplify configuration and update helper lib to version 1.0.18 (#20289)

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

Author: HolgerHees

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

@@ -70,29 +70,21 @@ Additionally, you can configure the Add-on via a config file `/openhab/services/
 If you use the marketplace version of this Add-on, it is necessary to use the config file. OpenHAB has a bug which prevents the web based config dialog to work correctly for `kar` file based Add-ons.
 :::
 
-```text
-# Use scope and import wrapper
-#
-# This enables a scope module and and import wrapper.
-# A scope module is an encapsulated module containing all openHAB jsr223 objects and can be imported with <code>import scope</code>
-# Additionally you can run an import like <code>from org.openhab.core import OpenHAB</code>
+```ini
+# Activate openHAB Python helper module and inject scope and helper objects into rules
 #
-#org.openhab.automation.pythonscripting:scopeEnabled = true
-
-# Install openHAB Python helper module (requires scope module)
+# Install openHAB Python helper module to support helper classes like rule, logger, Registry, Timer, etc.
+# and automatically injects `from openhab import rule, Registry, logger` into you Python code.
 #
-# Install openHAB Python helper module to support helper classes like rule, logger, Registry, Timer etc...
-# If disabled, the openHAB python helper module can be installed manually by copying it to /conf/automation/python/lib/openhab"
-#
-#org.openhab.automation.pythonscripting:helperEnabled = true
-
-# Inject scope and helper objects into rules (requires helper modules)
+# If auto injection is disabled, the helper module can still be used by importing it manually.
 #
-# This injects the scope and helper Registry and logger into rules.
+# When completely disabled, you get a "pure" Graalpy context that has only been initialized with the default JSR223 presets.
 #
-# 2 => Auto injection enabled only for UI and Transformation scripts (preferred)
-# 1 => Auto injection enabled for all scripts
-# 0 => Disable auto injection and use 'import' statements instead
+# 4 => Auto injection everywhere, including script files and transformations
+# 3 => Auto injection for Script Actions, Script Conditions and transformations
+# 2 => Auto injection only for Script Actions &amp; Script Conditions (recommended)
+# 1 => Disable auto-injection and import manually instead
+# 0 => Disable completely
 #
 #org.openhab.automation.pythonscripting:injectionEnabled = 2
 

bundles/org.openhab.automation.pythonscripting/pom.xml

@@ -15,7 +15,7 @@
   <name>openHAB Add-ons :: Bundles :: Automation :: Python Scripting</name>
 
   <properties>
-    <helperlib.version>1.0.15</helperlib.version>
+    <helperlib.version>1.0.18</helperlib.version>
   </properties>
 
   <dependencies>

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

@@ -59,6 +59,7 @@
 import org.openhab.automation.pythonscripting.internal.scriptengine.InvocationInterceptingPythonScriptEngine;
 import org.openhab.automation.pythonscripting.internal.scriptengine.graal.GraalPythonScriptEngine;
 import org.openhab.core.automation.module.script.ScriptExtensionAccessor;
+import org.openhab.core.automation.module.script.internal.handler.AbstractScriptModuleHandler;
 import org.openhab.core.library.types.DateTimeType;
 import org.openhab.core.library.types.DecimalType;
 import org.openhab.core.library.types.OnOffType;
@@ -289,7 +290,7 @@ public void accept(Path path) {
             }
         }
 
-        if (pythonScriptEngineConfiguration.isScopeEnabled()) {
+        if (pythonScriptEngineConfiguration.isHelperEnabled()) {
             ScriptExtensionAccessor scriptExtensionAccessor = (ScriptExtensionAccessor) ctx
                     .getAttribute(CONTEXT_KEY_EXTENSION_ACCESSOR);
             if (scriptExtensionAccessor == null) {
@@ -305,6 +306,12 @@ public void accept(Path path) {
                 getBindings(ScriptContext.ENGINE_SCOPE).put(ScriptExtensionModuleProvider.IMPORT_PROXY_NAME,
                         wrapImportFn);
                 try {
+                    if (!isScriptFile() && !isScriptModule() && !isTransformation()) {
+                        logger.warn(
+                                "Unknown script environment detected for engine '{}': Neither script file, script module nor transformation.",
+                                engineIdentifier);
+                    }
+
                     String wrapperContent = new String(
                             Files.readAllBytes(PythonScriptEngineConfiguration.PYTHON_WRAPPER_FILE_PATH));
                     getPolyglotContext()
@@ -314,9 +321,11 @@ public void accept(Path path) {
                                     .build());
 
                     // inject scope, Registry and logger
-                    if (!pythonScriptEngineConfiguration.isInjection(PythonScriptEngineConfiguration.INJECTION_DISABLED)
-                            && (ctx.getAttribute(CONTEXT_KEY_SCRIPT_FILENAME) == null || pythonScriptEngineConfiguration
-                                    .isInjection(PythonScriptEngineConfiguration.INJECTION_ENABLED_FOR_ALL_SCRIPTS))) {
+                    if (pythonScriptEngineConfiguration.isInjectionEnabledForAllScripts()
+                            || (isScriptModule()
+                                    && pythonScriptEngineConfiguration.isInjectionEnabledForScriptModules())
+                            || (isTransformation()
+                                    && pythonScriptEngineConfiguration.isInjectionEnabledForTransformations())) {
                         String injectionContent = "import scope\nfrom openhab import Registry, logger";
                         getPolyglotContext().eval(
                                 Source.newBuilder(GraalPythonScriptEngine.LANGUAGE_ID, injectionContent, "<generated>")
@@ -404,7 +413,7 @@ public void put(@Nullable String key, @Nullable Object value) {
                 value = lifecycleTracker;
             }
             if (key != null && value != null) {
-                if (pythonScriptEngineConfiguration.isScopeEnabled()) {
+                if (pythonScriptEngineConfiguration.isHelperEnabled()) {
                     scriptExtensionModuleProvider.put(key, value);
                 } else {
                     super.put(key, value);
@@ -447,32 +456,8 @@ public void unlock() {
         logger.debug("Lock released for engine '{}'.", this.engineIdentifier);
     }
 
-    @Override
-    public Object invokeFunction(String name, Object... objects) throws ScriptException, NoSuchMethodException {
-        if ("scriptUnloaded".equals(name)) {
-            /*
-             * is called from
-             * => org.openhab.core.automation.module.script.internal.ScriptEngineManagerImpl:removeEngine
-             *
-             * must be skipped, because ScriptTransformationService:disposeScriptEngine is calling engine.close several
-             * times before. Specially if the
-             * same script is used for more then 1 transformations. If the engine is already closed, the script
-             * "scriptUnloaded" will fail.
-             */
-            return null;
-        } else {
-            return super.invokeFunction(name, objects);
-        }
-    }
-
     @Override
     public void close() {
-        /*
-         * is called from
-         * => org.openhab.core.automation.module.script.ScriptTransformationService:disposeScriptEngine
-         * => org.openhab.core.automation.module.script.internal.ScriptEngineManagerImpl:removeEngine
-         */
-
         lock.lock();
 
         if (!isClosed()) {
@@ -538,6 +523,64 @@ private String stringifyThrowable(Throwable throwable) {
         return (message != null) ? message + System.lineSeparator() + stackTrace : stackTrace;
     }
 
+    /**
+     * Tests if the script is a script file, i.e. it is loaded from a Python file.
+     *
+     * @return true if the script is loaded from a Python file, false otherwise
+     */
+    private boolean isScriptFile() {
+        ScriptContext ctx = getContext();
+        if (ctx == null) {
+            logger.warn("Failed to retrieve script context from engine '{}'.", engineIdentifier);
+            return false;
+        }
+        return ctx.getAttribute("javax.script.filename") != null;
+    }
+
+    /**
+     * Get the module type id (if any) of the module executing the script.
+     *
+     * @return the module type id (if any) of the module executing the script, or null if the script is not a module
+     */
+    private @Nullable String getModuleTypeId() {
+        ScriptContext ctx = getContext();
+        if (ctx == null) {
+            logger.warn("Failed to retrieve script context from engine '{}'.", engineIdentifier);
+            return null;
+        }
+
+        Object value = ctx.getAttribute(AbstractScriptModuleHandler.CONTEXT_KEY_MODULE_TYPE_ID);
+        if (value instanceof String str) {
+            return str;
+        }
+        return null;
+    }
+
+    /**
+     * Tests if the script is a script module, i.e. executed by an implementation of
+     * {@link AbstractScriptModuleHandler}.
+     *
+     * @return true if the script is a script module, false otherwise
+     */
+    private boolean isScriptModule() {
+        String moduleTypeId = getModuleTypeId();
+        return moduleTypeId != null && moduleTypeId.startsWith("script.");
+    }
+
+    /**
+     * Tests if the script is a transformation script, i.e. created from the script transformation service.
+     *
+     * @return true if it is a transformation script, false otherwise
+     */
+    private boolean isTransformation() {
+        ScriptContext ctx = getContext();
+        if (ctx == null) {
+            logger.warn("Failed to retrieve script context from engine '{}'.", engineIdentifier);
+            return false;
+        }
+        return engineIdentifier.startsWith(OPENHAB_TRANSFORMATION_SCRIPT);
+    }
+
     private static Set<String> transformArrayToSet(Value value) {
         try {
             Set<String> set = new HashSet<>();

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

@@ -62,15 +62,14 @@ public class PythonScriptEngineConfiguration {
     public static final Path PYTHON_WRAPPER_FILE_PATH = PYTHON_OPENHAB_LIB_PATH.resolve("__wrapper__.py");
     public static final Path PYTHON_INIT_FILE_PATH = PYTHON_OPENHAB_LIB_PATH.resolve("__init__.py");
 
-    public static final int INJECTION_DISABLED = 0;
-    public static final int INJECTION_ENABLED_FOR_ALL_SCRIPTS = 1;
-    public static final int INJECTION_ENABLED_FOR_NON_FILE_BASED_SCRIPTS = 2;
+    private static final int INJECTION_DISABLED = 1;
+    private static final int INJECTION_ENABLED_FOR_SCRIPT_MODULES_ONLY = 2;
+    private static final int INJECTION_ENABLED_FOR_SCRIPT_MODULES_AND_TRANSFORMATIONS = 3;
+    private static final int INJECTION_ENABLED_FOR_ALL_SCRIPTS = 4;
 
     // The variable names must match the configuration keys in config.xml
     public static class PythonScriptingConfiguration {
-        public boolean scopeEnabled = true;
-        public boolean helperEnabled = true;
-        public int injectionEnabled = INJECTION_ENABLED_FOR_NON_FILE_BASED_SCRIPTS;
+        public int injectionEnabled = INJECTION_ENABLED_FOR_SCRIPT_MODULES_ONLY;
         public boolean dependencyTrackingEnabled = true;
         public boolean cachingEnabled = true;
         public boolean jythonEmulation = false;
@@ -152,8 +151,7 @@ public void init(PythonScriptEngineFactory factory) {
      * @param initial
      */
     public void modified(Map<String, Object> config, PythonScriptEngineFactory factory) {
-        boolean oldScopeEnabled = configuration.scopeEnabled;
-        boolean oldInjectionEnabled = !isInjection(PythonScriptEngineConfiguration.INJECTION_DISABLED);
+        int oldInjectionEnabled = configuration.injectionEnabled;
         boolean oldDependencyTrackingEnabled = isDependencyTrackingEnabled();
 
         String oldPipModules = configuration.pipModules;
@@ -162,16 +160,13 @@ public void modified(Map<String, Object> config, PythonScriptEngineFactory facto
             PythonScriptEngineHelper.initPipModules(this, factory);
         }
 
-        if (oldScopeEnabled != isScopeEnabled()) {
-            logger.info("{} scope for Python Scripting. Please resave your scripts to apply this change.",
-                    isScopeEnabled() ? "Enabled" : "Disabled");
-        }
-        if (oldInjectionEnabled != !isInjection(PythonScriptEngineConfiguration.INJECTION_DISABLED)) {
-            logger.info("{} injection for Python Scripting. Please resave your UI-based scripts to apply this change.",
-                    !isInjection(PythonScriptEngineConfiguration.INJECTION_DISABLED) ? "Enabled" : "Disabled");
+        if (oldInjectionEnabled != configuration.injectionEnabled) {
+            logger.info(
+                    "Changed helper module setting for Python Scripting. Please resave your python scripts to apply this change.");
         }
         if (oldDependencyTrackingEnabled != isDependencyTrackingEnabled()) {
-            logger.info("{} dependency tracking for Python Scripting. Please resave your scripts to apply this change.",
+            logger.info(
+                    "{} dependency tracking for Python Scripting. Please resave your python scripts to apply this change.",
                     isDependencyTrackingEnabled() ? "Enabled" : "Disabled");
         }
     }
@@ -180,16 +175,20 @@ public void setHelperLibVersion(Version version) {
         installedHelperLibVersion = version;
     }
 
-    public boolean isScopeEnabled() {
-        return configuration.scopeEnabled;
+    public boolean isInjectionEnabledForAllScripts() {
+        return configuration.injectionEnabled == INJECTION_ENABLED_FOR_ALL_SCRIPTS;
     }
 
-    public boolean isHelperEnabled() {
-        return configuration.helperEnabled;
+    public boolean isInjectionEnabledForScriptModules() {
+        return configuration.injectionEnabled == INJECTION_ENABLED_FOR_SCRIPT_MODULES_ONLY;
     }
 
-    public boolean isInjection(int type) {
-        return configuration.injectionEnabled == type;
+    public boolean isInjectionEnabledForTransformations() {
+        return configuration.injectionEnabled == INJECTION_ENABLED_FOR_SCRIPT_MODULES_AND_TRANSFORMATIONS;
+    }
+
+    public boolean isHelperEnabled() {
+        return configuration.injectionEnabled > 0;
     }
 
     public boolean isDependencyTrackingEnabled() {

bundles/org.openhab.automation.pythonscripting/src/main/resources/OH-INF/config/config.xml

@@ -16,41 +16,29 @@
 			<advanced>true</advanced>
 		</parameter-group>
 
-		<parameter name="scopeEnabled" type="boolean" required="true" groupName="environment">
-			<label>Use scope and import wrapper</label>
+		<parameter name="injectionEnabled" type="integer" required="true" min="0" max="4" groupName="environment">
+			<label>Activate openHAB Python helper module and inject scope and helper objects into rules.</label>
 			<description><![CDATA[
-			This enables a scope module and import wrapper.<br>
-			A scope module is an encapsulated module containing all openHAB jsr223 objects and can be imported with <code>import scope</code><br>
-			Additionally, you can run an import like <code>from org.openhab.core import openHAB</code>
+			Install openHAB Python helper module to support helper classes like rule, logger, Registry, Timer, etc. and automatically injects `from openhab import rule, Registry, logger` into you Python code.<br>
+			If auto injection is disabled, the helper module can still be used by importing it manually.<br>
+			When completely disabled, you get a "pure" Graalpy context that has only been initialized with the default JSR223 presets. The openHAB Python helper module cannot be imported manually in this case.
 			]]></description>
-			<default>true</default>
-			<advanced>true</advanced>
-		</parameter>
-		<parameter name="helperEnabled" type="boolean" required="true" groupName="environment">
-			<label>Install openHAB Python helper module (requires scope module)</label>
-			<description><![CDATA[
-			Install openHAB Python helper module to support helper classes like rule, logger, Registry, Timer, etc.<br>
-			If disabled, the openHAB python helper module can be installed manually by copying it to /conf/automation/python/lib/openhab"
-			]]></description>
-			<default>true</default>
-		</parameter>
-		<parameter name="injectionEnabled" type="integer" required="true" min="0" max="2" groupName="environment">
-			<label>Inject scope and helper objects into rules (requires helper modules)</label>
-			<description>This injects the scope and helper Registry and logger into rules.</description>
 			<options>
-				<option value="2">Auto injection enabled only for UI and Transformation scripts (preferred)</option>
-				<option value="1">Auto injection enabled for all scripts</option>
-				<option value="0">Disable auto injection and use 'import' statements instead</option>
+				<option value="4">Auto injection everywhere, including script files and transformations</option>
+				<option value="3">Auto injection for Script Actions, Script Conditions and transformations</option>
+				<option value="2">Auto injection only for Script Actions &amp; Script Conditions (recommended)</option>
+				<option value="1">Disable auto-injection and import manually instead</option>
+				<option value="0">Disable completely</option>
 			</options>
 			<default>2</default>
 		</parameter>
 		<parameter name="pipModules" type="text" required="false" groupName="system">
 			<label>Python pip modules (requires a manually configured venv)</label>
-			<description>
-				<![CDATA[A comma separated list of Python modules to install.
-				Versions may be constrained by separating with an <code>==</code> followed by standard
-				python pip version constraint, such as "<code>tzdata==2025.2</code>".]]>
-			</description>
+			<description><![CDATA[
+			A comma separated list of Python modules to install.
+			Versions may be constrained by separating with an <code>==</code> followed by standard
+			python pip version constraint, such as "<code>tzdata==2025.2</code>".
+			]]></description>
 			<default></default>
 			<advanced>true</advanced>
 		</parameter>