public
/
openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improved README for Jython scripting (#9447) 

Signed-off-by: Kai Kreuzer <kai@openhab.org>
This commit is contained in:
Kai Kreuzer 2020-12-21 21:32:15 +01:00 committed by GitHub
parent e4554f4aa6
commit f36d6f0998
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 54 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
bundles/org.openhab.automation.jythonscripting/README.md
View File

@ -1,5 +1,56 @@
# Jython Scripting
This addon provides a [Jython](https://www.jython.org/) 2.7.2 for use with scripted automation and eliminates the need to download Jython and create `EXTRA_JAVA_OPTS` entries for `bootclasspath`, `python.home` and `python.path`.
The `python.home` System property will be set to the path of the add-on.
The `python.path` System property will be set to `$OPENHAB_CONF/automation/lib/python`, but any existing `python.path` will be appended to it.
This add-on provides [Jython](https://www.jython.org/) 2.7.2 that can be used as a scripting language within automation rules and which eliminates the need to download Jython and create `EXTRA_JAVA_OPTS` entries for `bootclasspath`, `python.home` and `python.path`.
The `python.home` system property is set to the path of the add-on.
The `python.path` system property is set to `$OPENHAB_CONF/automation/lib/python`, but any existing `python.path` will be appended to it.
## Creating Jython Scripts
When this add-on is installed, you can select Jython as a scripting language when creating a script action within the rule editor of the UI.
Alternatively, you can create scripts in the `automation/jsr223` configuration directory.
If you create an empty file called `test.py`, you will see a log line with information similar to:
```text
... [INFO ] [.a.m.s.r.i.l.ScriptFileWatcher:150 ] - Loading script 'test.py'
```
To enable debug logging, use the [console logging]({{base}}/administration/logging.html) commands to
enable debug logging for the automation functionality:
```text
log:set DEBUG org.openhab.core.automation
```
## Script Examples
Jython scripts provide access to almost all the functionality in an openHAB runtime environment.
As a simple example, the following script logs "Hello, World!".
Note that `print` will usually not work since the output has no terminal to display the text.
The openHAB server uses the [SLF4J](https://www.slf4j.org/) library for logging.
```python
from org.slf4j import LoggerFactory
LoggerFactory.getLogger("org.openhab.core.automation.examples").info("Hello world!")
```
Jython can [import Java classes](https://jython.readthedocs.io/en/latest/ModulesPackages/).
Depending on the openHAB logging configuration, you may need to prefix logger names with `org.openhab.core.automation` for them to show up in the log file (or you modify the logging configuration).
::: tip Note
Be careful with using wildcards when importing Java packages (e.g., `import org.slf4j.*`).
This will work in some cases, but it might not work in some situations.
It is best to use explicit imports with Java packages.
For more details, see the Jython documentation on
[Java package scanning](https://jython.readthedocs.io/en/latest/ModulesPackages/#java-package-scanning).
:::
The script uses the [LoggerFactory](https://www.slf4j.org/apidocs/org/slf4j/Logger.html)
to obtain a named logger and then logs a message like:
```text
... [INFO ] [.openhab.core.automation.examples:-2 ] - Hello world!
```