Python Scripting [4.3.0;4.9.9]

Add-on Marketplace Bundles
, ,
1

pythonscripting
pythonscripting500×650 8.43 KB

This add-on provides support for Python 3 that can be used as a scripting language within automation rules. It is based on GraalPy from the GraalVM project.

Also included is a helper library to support automation in openHAB. It provides access to common openHAB functionality within rules including items, things, actions, logging and more.

Please note this binding is in beta stage for openhab4.
There are several bugs right now in the version for openhab4.

  1. a major known bug which may require restarting openhab after installation. If you see an exception like “Native library already loaded in another classloader”, you must restart openHAB until this exception disappears.
  2. jsscripting and pythonscripting can’t run in parallel

:white_check_mark: There is also a separate openhab 5 version available where all of these bugs are fixed :white_check_mark:

Quick Start

  1. Install this binding via marketplace
  2. Wait for a log message like “Deploy helper libs into…” which means the helper lib is initialized
  3. Put your scripts into “/conf/automation/python/” and your modules into “/conf/automation/python/lib/”.

README and Documentation

Please refer the Add-on README.md

Help Wanted

If you want to discuss this Add-on or you found a bug, feel free to join the community forum

Please don’t be afraid to create PRs, refactor code, add documentation

Ressources

Jar file (OH4.3+)

Source code

Last published Date

Last Update: 26.10.2025 08:51

Changelog

Version 26.10.2025 08:51

Add-on changes

  • Same codebase as merged version in openHAB 5.1 Milestone 2
  • Update helper lib to version 1.0.11

Helper lib 1.0.11 changed

  • Stable rule uid generation
  • Fix version parsing

Version 11.08.2025 07:30

Add-on changes

  • Type hint generator fixes
    • Remove instanceid from generated value representations
  • Update helper lib to version 1.0.7

Helper lib 1.0.7 changed

  • BREAKING CHANGE openhab.Timer removed.
    • Can be replaced with default Threading or Timer implementation.
    • No need to register shutdown procedure in the lifecycleTracker anymore
    • Old timer can be found as an example

Version 09.08.2025 10:27

Add-on changes

  • Type hint generator fixes
    • Path handling on windows
    • Fix for dictionaries
    • Fix nested lists
    • Fix for type parameters
  • Pip console command fixed

Version 08.08.2025 15:00

Add-on

  • Fix internal addon log prefix (without .py) to align with script file log prefix
  • Added Type Hint Stub Generator as new console command
  • Fix update check console command
  • Fix ‘update install latest’ command, if a newer preview version was manuell installed
  • Update helper lib to version 1.0.6

Helper lib 1.0.6 changes

  • Register lifecycleTracker dispose hook only if a Timer is used
  • Global ZonedDateTime to datetime conversion. ZonedDateTime & Instant is now a registered interop_type
  • Add Registry.removeItem, Item.getThings, Item.getChannels, Item.getChannelUIDs, Item.getLinks, Item.linkChannel & Item.unlinkChannel => API documentation
  • Improved error logs for catched java exceptions in python.
  • Fix simple rule decorator (rule instead of rule()). Both variants works now.
  • Preview for type hinting (autocompletion)
  • BREAKING CHANGE: Changed parameter of Registry.addItem
  • BREAKING CHANGE: Replace NotInitialisedException with NotFoundException for getItem, removeItem, getThing, getChannel

Version 02.08.2025 14:05

Add-on changes

  • Implement State data type mapping
  • Removed Item conversion, as the Add-on works now with “real” items on python side
  • Fix dependency watcher in case of using compiled pyc files
  • Fix ScriptEngine reinitialisation (in Transformation Services) after Add-on updates
    • Hopefully no “Context execution was cancelled” Exceptions after Add-on updates anymore
    • An Add-on update should work now without any exception (the old one can still raise an exception on shutdown) or openhab restart
  • Additional simplification of PythonScriptEngine & GraalPythonScriptEngine (~20% less code) => easier to understand for other people
  • Refactored VFS
  • Update helper lib to version 1.0.5

Helper lib 1.0.5 changes

  • Removed “Python => Java” type conversion for sendCommand and postUpdate. Is now handled inside the Add-on in a more generic way.
  • Replace error message TypeError: invalid instantiation of foreign object with a more helpful description like One of your function parameters does not match the required value type.
  • Initial integration tests started

Version 27.07.2025 16:15

Add-on changes

  • Rename generic feature name for marketplace deployments
    • This fixes the auto uninstall issues for marketplace installations
  • Helper lib update to version 1.0.4

Helper lib 1.0.4 changes

  • Renamed rule profile option to profiler_enabled
  • New rule runtime_measurement option

Version 24.07.2025 15:29

Add-on changes

  • improved logging & debugging
  • fixed handling of config changes
  • Update helper lib to version 1.0.3

Helper lib 1.0.3 changes

  • Improved error messages for Java Foreign Objects
    • Old like “foreign object has no attribute ‘test’”
    • New like “Java instance of ‘org.openhab.core.types.UnDefType’ has no attribute ‘test’”
  • Improved java <=> python type conversion
    • Proxy classes for Item, State, Thing, Channel, HistoricItem are now real ChildClasses of Java Foreign Objects
    • As a result, much more object function results are transparently converted value, like datetime <=> ZonedDateTime
  • Refactored and cleaned Metadata handling
    • Registry.getItemMetadata => Registry.getItem().getMetadata().get
    • Registry.setItemMetadata => Registry.getItem().getMetadata().set
    • Registry.removeItemMetadata => Registry.getItem().getMetadata().remove & Registry.getItem().getMetadata().removeAll
  • BREAKING CHANGE
    • State ‘DateTimeType’ is not converted to a datetime anymore. Instead it stays as a ‘DateTimeType’, but the method getZonedDateTime returns a datetime. This leads to a much more consistent behavior.
    • Metadata API changed
    • Registry.safeItemName move to Item.buildSafeName

Version 21.07.2025 15:06

Fix missing feature warning against latest openhab release

Version 19.07.2025 09:10

Addon changes

  • refactor, cleanup and simplify GraalPythonScriptEngine
  • check timezone settings and print a warning on discrepancies
  • improved datetime to Java ZonedDateTime mapping
  • fix missing i18n translations for binding config
  • update helper lib to version 1.0.2

Helper lib 1.0.2 changes

  • refactor and simplify object type mapping.
    This results in a generic solution, wich covers all functions, including upcoming, not yet existing ones.
    Means functions in newer openhab versions are without any update correctly handled.
  • fixed internal bundle version parsing for beta, milestone or rc versions

Version 15.07.2025 22:02

  • Update helper lib to version v1.0.1
  • Fix datetime (with and without timezone) usage as function parameter
  • Fix and generalize type mapping between java and python

Version 14.07.2025 20:44

  • Update helper lib module to v1.0.0
  • Support for updating of helper libs
  • Support for venv setups
  • Support for ‘pip’ and preinstalled “modules”
  • Support for native modules
  • OSGI Console support
    • You can show python scripting state values
    • You can open an interactive console (not supported for openhab 4.x)
    • You can install, check, list and uninstall additional modules
    • You can install, check, list and uninstall helper lib module

Version 20.06.2025 10:02

  • fix list and set type mappings
  • fixed GenericEventTrigger
  • fixed ItemNotFound behavior
  • added addItem and safeItemName functions to Registry
  • cleanup usage of Dummy Set class => depends on latest openhab main branch

Version 25.03.2025 18:14

  • move helper libs from private repo to openhab repo
  • fix script unload/cleanup
  • update to graalpy 24.2.0 (version for openhab5 is using osgiified graalvm)
  • simplified createTimer implementation
  • helperlib fix to support upcomming graalpy 24.2.0
  • code cleanups and refactorings based on feedback and code reviews

Version 24.02.2025 18:06

  • script context cleanup/close fix for compiled scripts (e.g. transformation scripts)
  • log prefix for UI based and transformation scripts fixed
  • logging cleanup and simplification

Version 23.02.2025 20:57

  • add scope, Registry and logger auto injected for UI based rules

Version 23.02.2025 12:02

  • added scope object and import wrapper
    • for details check here
  • added IntervalCondition to triggers
  • cleanup and minor helper lib api changes
  • cleanup and simplification of helper lib deployment (no hardcoded filenames anymore)
  • use OSGI-ified version of polyglot in openhab 5 (this fixes openhab/openhab-addons#18054 in openhab >= 5)
  • migrate openhab helper lib into his own repository
    • This makes it easier to decouple release cycles between openhab and helper lib

Version 06.02.2025 07:30

  • fixed memory leak on rule reloading (old script engine is properly closed)
  • fixed tranformation service ‘PY3’
  • fixed log prefix
  • fixed lifecycleTracker
  • cleanups

Version 03.02.2025 17:34

  • fixed postUpdate, postUpdateIfDifferent, sendCommand and sendCommandIfDifferent for openhab value types like UP/DOWN etc)

Version 03.02.2025 08:30

  • code cleanup of internal trigger validation
  • various helper lib code cleanups
  • added Registry.setItemMetadata and Registry.removeItemMetadata
  • improved README.md

Version 02.02.2025 20:26

  • Fixed “Run Now” - UI in 4.3+

Version 27.01.2025 08:58

  • rule decorator for functions in addition to classes to allow much simpler rules
  • allow import of script modules in addition to lib modules
  • fixes for WebUI based rules (currently still not working because of another major bug)
  • internal graal binding cleanups and simplifications
  • cleanups in triggers helper module

Version 23.01.2025 12:08

  • added “when” and “onlyif” decorator support
  • Item.getPersistance renamed to Item.getPersistence
  • fixed TimeOfDayTrigger and DateTimeTrigger

Version 22.01.2025 10:58

  • initial release
7 Likes
2

This thread is only for marketplace updates. For discussion use our Python3 Binding Thread

1 Like