- Updated documentation

- Added NumberItem to openhab.items

HABApp/core/items/item.py

@@ -5,6 +5,13 @@
 
 
 class Item:
+    """Simple item
+
+    :ivar str ~.name: Name of the item
+    :ivar ~.value: Value of the item, can be anything
+    :ivar ~.datetime.datetime last_change: Timestamp of the last time when the item has changed the value
+    :ivar ~.datetime.datetime last_update: Timestamp of the last time when the item has updated the value
+    """
 
     @classmethod
     def get_item(cls, name: str):
@@ -64,26 +71,27 @@ def set_value(self, new_value) -> bool:
         return state_changed
 
     def post_value(self, new_value):
-        """Set a new value and post appropriate events on the event bus (``ValueUpdateEvent``, ``ValueChangeEvent``)
+        """Set a new value and post appropriate events on the HABApp event bus
+        (``ValueUpdateEvent``, ``ValueChangeEvent``)
 
         :param new_value: new value of the item
         """
         old_value = self.value
         self.set_value(new_value)
 
         # create events
-        HABApp.core.EventBus.post_event(self.name, HABApp.core.events.ValueUpdateEvent(self.name, new_value))
-        if old_value != new_value:
+        HABApp.core.EventBus.post_event(self.name, HABApp.core.events.ValueUpdateEvent(self.name, self.value))
+        if old_value != self.value:
             HABApp.core.EventBus.post_event(
-                self.name, HABApp.core.events.ValueChangeEvent(self.name, value=new_value, old_value=old_value)
+                self.name, HABApp.core.events.ValueChangeEvent(self.name, value=self.value, old_value=old_value)
             )
         return None
 
     def get_value(self, default_value=None) -> typing.Any:
-        """Return the state of the item.
+        """Return the value of the item.
 
-        :param default_value: Return this value if the item state is None
-        :return: State of the item
+        :param default_value: Return this value if the item value is None
+        :return: value of the item
         """
         if self.value is None:
             return default_value

HABApp/core/items/item_color.py

@@ -17,11 +17,10 @@ def __init__(self, name: str, h=0.0, s=0.0, b=0.0):
 
     def set_value(self, hue=0.0, saturation=0.0, brightness=0.0):
         """Set the color value
-        
+
         :param hue: hue (in °)
         :param saturation: saturation (in %)
         :param brightness: brightness (in %)
-        :return:
         """
 
         # map tuples to variables
@@ -47,7 +46,7 @@ def post_value(self, hue=0.0, saturation=0.0, brightness=0.0):
 
     def get_rgb(self, max_rgb_value=255) -> typing.Tuple[int, int, int]:
         """Return a rgb equivalent of the color
-        
+
         :param max_rgb_value: the max value for rgb, typically 255 (default) or 65.536
         :return: rgb tuple
         """
@@ -60,7 +59,7 @@ def get_rgb(self, max_rgb_value=255) -> typing.Tuple[int, int, int]:
 
     def set_rgb(self, r, g, b, max_rgb_value=255) -> 'ColorItem':
         """Set a rgb value
-        
+
         :param r: red value
         :param g: green value
         :param b: blue value

HABApp/mqtt/items/mqtt_item.py

@@ -4,12 +4,12 @@
 
 class MqttItem(Item):
 
-    def publish(self, payload, qos=None, retain=None):
+    def publish(self, payload, qos: int = None, retain: bool = None):
         """
         Publish the payload under the topic from the item.
 
         :param payload: MQTT Payload
-        :param qos: QoS, can be 0, 1 or 2. If not specified value from configuration file will be used.
+        :param qos: QoS, can be ``0``, ``1`` or ``2``. If not specified value from configuration file will be used.
         :param retain: retain message. If not specified value from configuration file will be used.
         :return: 0 if successful
         """

HABApp/openhab/definitions/__init__.py

@@ -4,4 +4,4 @@
 
 GROUP_FUNCTIONS = ['AND', 'OR', 'NAND', 'NOR', 'AVG', 'MAX', 'MIN', 'SUM']
 
-from .values import OnOffValue, PercentValue, UpDownValue, HSBValue
+from .values import OnOffValue, PercentValue, UpDownValue, HSBValue, QuantityValue

HABApp/openhab/definitions/values.py

@@ -43,3 +43,18 @@ def __init__(self, value: str):
 
     def __str__(self):
         return f'{self.value[0]}°,{self.value[1]}%,{self.value[2]}%'
+
+
+class QuantityValue(ComplexEventValue):
+    def __init__(self, value: str):
+        val, unit = value.split(' ')
+        try:
+            val = int(val)
+        except ValueError:
+            val = float(val)
+
+        super().__init__(val)
+        self.unit = unit
+
+    def __str__(self):
+        return f'{self.value} {self.unit}'

HABApp/openhab/items/__init__.py

@@ -2,4 +2,5 @@
 from .dimmer_item import DimmerItem
 from .rollershutter_item import RollershutterItem
 from .switch_item import SwitchItem
-from .color_item import ColorItem
+from .color_item import ColorItem
+from .number_item import NumberItem

HABApp/openhab/items/map_items.py

@@ -1,7 +1,7 @@
 import datetime
 
 from HABApp.core.items import Item
-from . import SwitchItem, ContactItem, RollershutterItem, DimmerItem, ColorItem
+from . import SwitchItem, ContactItem, RollershutterItem, DimmerItem, ColorItem, NumberItem
 
 
 def map_items(name, openhab_type : str, openhab_value : str):
@@ -29,13 +29,13 @@ def map_items(name, openhab_type : str, openhab_value : str):
 
     if openhab_type == "Number":
         if value is None:
-            return Item(name, value)
+            return NumberItem(name, value)
 
         # Number items can be int or float
         try:
-            return Item(name, int(value))
+            return NumberItem(name, int(value))
         except ValueError:
-            return Item(name, float(value))
+            return NumberItem(name, float(value))
 
     if openhab_type == "DateTime":
         if value is None:

HABApp/openhab/items/number_item.py

@@ -0,0 +1,12 @@
+from HABApp.core.items import Item
+from ..definitions import QuantityValue
+
+
+class NumberItem(Item):
+
+    def set_value(self, new_value) -> bool:
+
+        if isinstance(new_value, QuantityValue):
+            return super().set_value(new_value.value)
+
+        return super().set_value(new_value)

HABApp/util/statistics.py

@@ -4,19 +4,20 @@
 
 
 class Statistics:
+    """Calculate mathematical statistics of numerical values.
+
+    :ivar sum: sum of all values
+    :ivar min: minimum of all values
+    :ivar max: maximum of all values
+    :ivar mean: mean of all values
+    :ivar median: median of all values
+    :ivar last_value: last added value
+    :ivar last_change: timestamp the last time a value was added
+    """
     def __init__(self, max_age=None, max_samples=None):
-        """Calculate mathematical statistics of numerical values.
-
+        """
         :param max_age:     Maximum age of values in seconds
         :param max_samples: Maximum amount of samples which will be kept
-
-        :ivar sum: sum of all values
-        :ivar min: minimum of all values
-        :ivar max: maximum of all values
-        :ivar mean: mean of all values
-        :ivar median: median of all values
-        :ivar last_value: last added value
-        :ivar last_change: timestamp the last time a value was added
         """
 
         if max_age is None and max_samples is None:

_doc/conf.py

@@ -220,6 +220,7 @@
     'ColorItem',
 )
 
+
 def skip_member(app, what, name, obj, skip, options):
 
     # Debug print
@@ -228,7 +229,7 @@ def skip_member(app, what, name, obj, skip, options):
     # don't change if we skip anyway
     if skip:
         return skip
-    
+
     for regex in RE_SKIP:
         m = regex.search(str(obj))
         if m:

_doc/interface_mqtt.rst

@@ -3,15 +3,17 @@
 MQTT
 ==================================
 
-Interaction with a MQTT broker
-------------------------------
-Interaction with the MQTT broker is done through the ``self.mqtt`` object in the rule.
+Interaction with the MQTT broker
+---------------------------------
+Interaction with the MQTT broker is done through the ``self.mqtt`` object in the rule or through
+the :class:`~HABApp.mqtt.items.MqttItem`. When receiving a topic for the first time a new :class:`~HABApp.mqtt.items.MqttItem`
+will automatically be created.
 
 ..  image:: /gifs/mqtt.gif
 
 
 
-Function parameters
+Rule Interface
 ------------------------------
 .. py:class:: mqtt
       
@@ -42,27 +44,38 @@ Function parameters
       :return: 0 if successful
 
 
-MQTT item types
+MqttItem
 ------------------------------
 
-Mqtt items have a publish method which make interaction with the mqtt broker easier.
+Mqtt items have an additional publish method which make interaction with the mqtt broker easier.
+
+.. execute_code::
+    :hide_output:
+
+    # hide
+    import HABApp
+    from unittest.mock import MagicMock
+    HABApp.mqtt.mqtt_interface.MQTT_INTERFACE = MagicMock()
+    # hide
 
-Example::
+    from HABApp.mqtt.items import MqttItem
 
-    # items can be created manually or will be automatically created when the first mqtt message is received
-    my_mqtt_item = self.create_item('test/topic', HABApp.mqtt.items.MqttItem)
-    assert isinstance(my_mqtt_item, HABApp.mqtt.items.MqttItem)
+    # items can be created manually or will be automatically
+    # created when the first mqtt message is received
+    my_mqtt_item = MqttItem.get_create_item('test/topic')
 
-    # easy publish
+    # easy to publish values
     my_mqtt_item.publish('new_value')
 
     # comparing the item to get the state works, too
     if my_mqtt_item == 'test':
-        # do something
+        pass # do something
+
 
 .. autoclass:: HABApp.mqtt.items.MqttItem
    :members:
-
+   :inherited-members:
+   :member-order: groupwise
 
 
 Example MQTT rule

_doc/interface_openhab.rst

@@ -21,34 +21,69 @@ Function parameters
 Openhab item types
 ------------------------------
 
-Openhab items are mapped to special classes and provide convenience functions
+Openhab items are mapped to special classes and provide convenience functions.
 
-Examples::
+Example:
 
-    my_contact = self.get_item('MyContact')
+.. execute_code::
+
+    # hide
+    import HABApp
+    from HABApp.openhab.items import ContactItem, SwitchItem
+    ContactItem.get_create_item('MyContact', initial_value='OPEN')
+    SwitchItem.get_create_item('MySwitch', initial_value='OFF')
+    # hide
+
+    my_contact = ContactItem.get_item('MyContact')
     if my_contact.is_open():
-        pass
+        print('Contact is open!')
 
-    my_switch = self.get_item('MySwitch')
+    my_switch = SwitchItem.get_item('MySwitch')
     if my_switch.is_on():
         my_switch.off()
 
-
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * - Openhab type
+     - HABApp class
+   * - ``Contact``
+     - :class:`~HABApp.openhab.items.ContactItem`
+   * - ``Switch``
+     - :class:`~HABApp.openhab.items.SwitchItem`
+   * - ``Dimmer``
+     - :class:`~HABApp.openhab.items.DimmerItem`
+   * - ``Rollershutter``
+     - :class:`~HABApp.openhab.items.RollershutterItem`
+   * - ``Color``
+     - :class:`~HABApp.openhab.items.ColorItem`
 
 .. autoclass:: HABApp.openhab.items.ContactItem
    :members:
+   :inherited-members:
+   :member-order: groupwise
+
 
 .. autoclass:: HABApp.openhab.items.SwitchItem
-   :members: is_on, is_off, on, off
+   :members:
+   :inherited-members:
+   :member-order: groupwise
 
 .. autoclass:: HABApp.openhab.items.DimmerItem
-   :members: is_on, is_off, on, off, percent
+   :members:
+   :inherited-members:
+   :member-order: groupwise
 
 .. autoclass:: HABApp.openhab.items.RollershutterItem
-   :members: up, down, percent
+   :members:
+   :inherited-members:
+   :member-order: groupwise
 
 .. autoclass:: HABApp.openhab.items.ColorItem
-   :members: is_on, is_off, on, off, percent, post_value, get_rgb, set_rgb, set_value
+   :members:
+   :inherited-members:
+   :member-order: groupwise