Class reference

Reference for returned classes from some functions. These are not intended to be created by the user.

ItemTimeWatch

class ItemTimeWatch(times, event_factory, context=None)

cancel()

Cancel the item watch

Return type:: None

listen_event(callback)

Listen to (only) the event that is emitted by this watcher

Return type:: EventBusListener

InstantView

class InstantView(instant)

classmethod now()

Create a new instance with the current time

Return type:: InstantView

add(*, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0, nanoseconds=0)

Add time delta

Return type:: Self
Returns:: New instance

delta_now(now=None)

Return the delta between now and the instant. The delta will be positive, e.g. if the InstantView is from 5 seconds ago this will return a timedelta with 5 seconds.

Parameters:: now (InstantView | Instant | None) – optional instant to compare to instead of now, must be newer than the instant of the instant view
Return type:: TimeDelta

newer_than(obj=None, **kwargs)

Check if the instant is newer than the given value

Overloads:

*, days (float) = 0, hours (float) = 0, minutes (float) = 0, seconds (float) = 0, milliseconds (float) = 0, microseconds (float) = 0, nanoseconds (int) = 0 → bool
obj (timedelta | TimeDelta | int | float | str | Instant | InstantView) → bool

older_than(obj=None, **kwargs)

Check if the instant is older than the given value

Overloads:

*, days (float) = 0, hours (float) = 0, minutes (float) = 0, seconds (float) = 0, milliseconds (float) = 0, microseconds (float) = 0, nanoseconds (int) = 0 → bool
obj (timedelta | TimeDelta | int | float | str | Instant | InstantView) → bool

py_datetime()

Return the datetime of the instant

Return type:: datetime

py_timedelta(now=None)

Return the timedelta between the instant and now

Parameters:: now (InstantView | Instant | None) – optional instant to compare to
Return type:: timedelta

subtract(*, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0, nanoseconds=0)

Subtract time delta from current instant

Return type:: Self
Returns:: New instance

Base Classes

Items

class BaseItem()

BaseItem, all items must inherit from this class

classmethod get_item(name)

Returns an already existing item. If it does not exist or has a different item type an exception will occur.

Parameters:: name (str) – Name of the item
Return type:: Self

listen_event(callback, event_filter=None)

Register an event listener which listens to all event that the item receives

Parameters:

callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event
event_filter (EventFilterBase | None) – Event filter. This is typically ValueUpdateEventFilter or ValueChangeEventFilter which will also trigger on changes/update from openhab or mqtt. Additionally, it can be an instance of EventFilter which additionally filters on the values of the event. It is also possible to group filters logically with, e.g. AndFilterGroup and OrFilterGroup

Return type:

EventBusListener

watch_change(secs)

Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur
Return type:: ItemTimeWatch
Returns:: The watch obj which can be used to cancel the watch

watch_update(secs)

Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur
Return type:: ItemTimeWatch
Returns:: The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:: Timestamp of the last time when the item has been changed (read only)

property last_update: InstantView

Returns:: Timestamp of the last time when the item has been updated (read only)

property name: str

Returns:: Name of the item (read only)

class BaseValueItem()

Simple item

Variables:

name (str) – Name of the item (read only)
value (Any) – Value of the item, can be anything (read only)
last_change (datetime) – Timestamp of the last time when the item has changed the value (read only)
last_update (datetime) – Timestamp of the last time when the item has updated the value (read only)

classmethod get_item(name)

Returns an already existing item. If it does not exist or has a different item type an exception will occur.

Parameters:: name (str) – Name of the item
Return type:: Self

command_value(value)

Send a ValueCommandEvent for the item to the HABApp event bus. A ValueCommandEvent is typically used to indicate that the item should change the value. E.g. a command “ON” to a dimmer might result in a brightness value of 100%.

Parameters:: value (Any) – the commanded value
Return type:: None

get_value(default_value=None)

Return the value of the item. This is a helper function that returns a default in case the item value is None.

Parameters:: default_value – Return this value if the item value is None
Return type:: Any
Returns:: value of the item

listen_event(callback, event_filter=None)

Register an event listener which listens to all event that the item receives

Parameters:

callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event
event_filter (EventFilterBase | None) – Event filter. This is typically ValueUpdateEventFilter or ValueChangeEventFilter which will also trigger on changes/update from openhab or mqtt. Additionally, it can be an instance of EventFilter which additionally filters on the values of the event. It is also possible to group filters logically with, e.g. AndFilterGroup and OrFilterGroup

Return type:

EventBusListener

post_value(new_value)

Set a new value and post appropriate events on the HABApp event bus (ValueUpdateEvent, ValueChangeEvent)

Parameters:: new_value (Any) – new value of the item
Return type:: bool
Returns:: True if state has changed

post_value_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>)

Post a value depending on the current state of the item. If one of the comparisons is true the new state will be posted.

Parameters:

new_value – new value to post
equal – item state has to be equal to the passed value
eq – item state has to be equal to the passed value
not_equal – item state has to be not equal to the passed value
ne – item state has to be not equal to the passed value
lower_than – item state has to be lower than the passed value
lt – item state has to be lower than the passed value
lower_equal – item state has to be lower equal the passed value
le – item state has to be lower equal the passed value
greater_than – item state has to be greater than the passed value
gt – item state has to be greater than the passed value
greater_equal – item state has to be greater equal the passed value
ge – item state has to be greater equal the passed value
is_ – item state has to be the same object as the passt value (e.g. None)
is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:: new_value (Any) – new value of the item
Return type:: bool
Returns:: True if state has changed

watch_change(secs)

Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur
Return type:: ItemTimeWatch
Returns:: The watch obj which can be used to cancel the watch

watch_update(secs)

Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur
Return type:: ItemTimeWatch
Returns:: The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:: Timestamp of the last time when the item has been changed (read only)

property last_update: InstantView

Returns:: Timestamp of the last time when the item has been updated (read only)

property name: str

Returns:: Name of the item (read only)

class OpenhabItem()

Base class for items which exists in OpenHAB.

Variables:

name (str)
value (Any)
last_value (Any)
label (str | None)
tags (frozenset[str])
groups (frozenset[str])
metadata (Mapping[str, MetaData])

classmethod get_item(name)

Returns an already existing item. If it does not exist or has a different item type an exception will occur.

Parameters:: name (str) – Name of the item
Return type:: Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:: value (Any) – value to be sent
Return type:: None
Overrides:: BaseValueItem.command_value

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

persistence (str | None) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used
start_time (datetime | None) – return only items which are newer than this
end_time (datetime | None) – return only items which are older than this

get_value(default_value=None)

Return the value of the item. This is a helper function that returns a default in case the item value is None.

Parameters:: default_value – Return this value if the item value is None
Return type:: Any
Returns:: value of the item

listen_event(callback, event_filter=None)

Register an event listener which listens to all event that the item receives

Parameters:

callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event
event_filter (EventFilterBase | None) – Event filter. This is typically ValueUpdateEventFilter or ValueChangeEventFilter which will also trigger on changes/update from openhab or mqtt. Additionally, it can be an instance of EventFilter which additionally filters on the values of the event. It is also possible to group filters logically with, e.g. AndFilterGroup and OrFilterGroup

Return type:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

Post an update to the openHAB item

Parameters:

value (Any) – (optional) value to be posted. If not specified the current item value will be used.
source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

Post a value depending on the current state of the item. If one of the comparisons is true the new state will be posted.

Parameters:

new_value – new value to post
equal – item state has to be equal to the passed value
eq – item state has to be equal to the passed value
not_equal – item state has to be not equal to the passed value
ne – item state has to be not equal to the passed value
lower_than – item state has to be lower than the passed value
lt – item state has to be lower than the passed value
lower_equal – item state has to be lower equal the passed value
le – item state has to be lower equal the passed value
greater_than – item state has to be greater than the passed value
gt – item state has to be greater than the passed value
greater_equal – item state has to be greater equal the passed value
ge – item state has to be greater equal the passed value
is_ – item state has to be the same object as the passt value (e.g. None)
is_not – item state has to be not the same object as the passt value (e.g. None)
source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

Send a command to the openHAB item

Parameters:

value (Any) – (optional) value to be sent. If not specified the current item value will be used.
source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

Set a new value and post appropriate events on the HABApp event bus (ValueUpdateEvent, ValueChangeEvent)

Parameters:: new_value (Any) – new value of the item
Return type:: bool
Returns:: True if state has changed

post_value_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>)

Post a value depending on the current state of the item. If one of the comparisons is true the new state will be posted.

Parameters:

new_value – new value to post
equal – item state has to be equal to the passed value
eq – item state has to be equal to the passed value
not_equal – item state has to be not equal to the passed value
ne – item state has to be not equal to the passed value
lower_than – item state has to be lower than the passed value
lt – item state has to be lower than the passed value
lower_equal – item state has to be lower equal the passed value
le – item state has to be lower equal the passed value
greater_than – item state has to be greater than the passed value
gt – item state has to be greater than the passed value
greater_equal – item state has to be greater equal the passed value
ge – item state has to be greater equal the passed value
is_ – item state has to be the same object as the passt value (e.g. None)
is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:: new_value (Any) – new value of the item
Return type:: bool
Returns:: True if state has changed

watch_change(secs)

Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur
Return type:: ItemTimeWatch
Returns:: The watch obj which can be used to cancel the watch

watch_update(secs)

Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur
Return type:: ItemTimeWatch
Returns:: The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:: Timestamp of the last time when the item has been changed (read only)

property last_update: InstantView

Returns:: Timestamp of the last time when the item has been updated (read only)

property name: str

Returns:: Name of the item (read only)

class ItemRegistryItem()

ItemRegistryItem, all items that will be stored in the Item Registry must inherit from this

property name: str

Returns:: Name of the item (read only)

class MqttBaseItem()

classmethod get_item(name)

Returns an already existing item. If it does not exist or has a different item type an exception will occur.

Parameters:: name (str) – Name of the item
Return type:: Self

command_value(value)

Send a ValueCommandEvent for the item to the HABApp event bus. A ValueCommandEvent is typically used to indicate that the item should change the value. E.g. a command “ON” to a dimmer might result in a brightness value of 100%.

Parameters:: value (Any) – the commanded value
Return type:: None

get_value(default_value=None)

Return the value of the item. This is a helper function that returns a default in case the item value is None.

Parameters:: default_value – Return this value if the item value is None
Return type:: Any
Returns:: value of the item

listen_event(callback, event_filter=None)

Register an event listener which listens to all event that the item receives

Parameters:

callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event
event_filter (EventFilterBase | None) – Event filter. This is typically ValueUpdateEventFilter or ValueChangeEventFilter which will also trigger on changes/update from openhab or mqtt. Additionally, it can be an instance of EventFilter which additionally filters on the values of the event. It is also possible to group filters logically with, e.g. AndFilterGroup and OrFilterGroup

Return type:

EventBusListener

post_value(new_value)

Set a new value and post appropriate events on the HABApp event bus (ValueUpdateEvent, ValueChangeEvent)

Parameters:: new_value (Any) – new value of the item
Return type:: bool
Returns:: True if state has changed

post_value_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>)

Post a value depending on the current state of the item. If one of the comparisons is true the new state will be posted.

Parameters:

new_value – new value to post
equal – item state has to be equal to the passed value
eq – item state has to be equal to the passed value
not_equal – item state has to be not equal to the passed value
ne – item state has to be not equal to the passed value
lower_than – item state has to be lower than the passed value
lt – item state has to be lower than the passed value
lower_equal – item state has to be lower equal the passed value
le – item state has to be lower equal the passed value
greater_than – item state has to be greater than the passed value
gt – item state has to be greater than the passed value
greater_equal – item state has to be greater equal the passed value
ge – item state has to be greater equal the passed value
is_ – item state has to be the same object as the passt value (e.g. None)
is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:: new_value (Any) – new value of the item
Return type:: bool
Returns:: True if state has changed

watch_change(secs)

Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur
Return type:: ItemTimeWatch
Returns:: The watch obj which can be used to cancel the watch

watch_update(secs)

Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur
Return type:: ItemTimeWatch
Returns:: The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:: Timestamp of the last time when the item has been changed (read only)

property last_update: InstantView

Returns:: Timestamp of the last time when the item has been updated (read only)

property name: str

Returns:: Name of the item (read only)

Events

class EventBusListener(topic, func, event_filter, **kwargs)

cancel()

Stop listening on the event bus

Return type:: None

class EventFilterBase

class OpenhabEvent

Types

class StringList(iterable)

A frozen list / tuple where all entries are of type str

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class RawType(type, data)

class MetaData(value, config=immutables.Map({}))

config: Mapping[str, Any]: Alias for field number 1

value: str: Alias for field number 0

OpenHAB Definitions

class ThingStatusEnum(*values)

class ThingStatusDetailEnum(*values)