Merge pull request #687 from plugwise/more-improvin-II

More improvements

Author: bouwew

plugwise/__init__.py

@@ -38,7 +38,7 @@
 
 
 class Smile(SmileComm):
-    """The Plugwise SmileConnect class."""
+    """The main Plugwise Smile API class."""
 
     # pylint: disable=too-many-instance-attributes, too-many-public-methods
 
@@ -91,7 +91,7 @@ def __init__(
         self.smile_zigbee_mac_address: str | None = None
 
     async def connect(self) -> Version | None:
-        """Connect to Plugwise device and determine its name, type and version."""
+        """Connect to the Plugwise Gateway and determine its name, type, version, and other data."""
         result = await self._request(DOMAIN_OBJECTS)
         # Work-around for Stretch fw 2.7.18
         if not (vendor_names := result.findall("./module/vendor_name")):
@@ -186,7 +186,7 @@ async def connect(self) -> Version | None:
     async def _smile_detect(self, result: etree, dsmrmain: etree) -> None:
         """Helper-function for connect().
 
-        Detect which type of Smile is connected.
+        Detect which type of Plugwise Gateway is being connected.
         """
         model: str = "Unknown"
         if (gateway := result.find("./gateway")) is not None:
@@ -260,7 +260,10 @@ async def _smile_detect(self, result: etree, dsmrmain: etree) -> None:
     async def _smile_detect_legacy(
         self, result: etree, dsmrmain: etree, model: str
     ) -> str:
-        """Helper-function for _smile_detect()."""
+        """Helper-function for _smile_detect().
+
+        Detect which type of legacy Plugwise Gateway is being connected.
+        """
         return_model = model
         # Stretch: find the MAC of the zigbee master_controller (= Stick)
         if (network := result.find("./module/protocols/master_controller")) is not None:
@@ -305,15 +308,15 @@ async def _smile_detect_legacy(
         return return_model
 
     async def full_xml_update(self) -> None:
-        """Helper-function used for testing."""
+        """Perform a first fetch of the Plugwise server XML data."""
         await self._smile_api.full_xml_update()
 
     def get_all_gateway_entities(self) -> None:
-        """Helper-function used for testing."""
+        """Collect the Plugwise Gateway entities and their data and states from the received raw XML-data."""
         self._smile_api.get_all_gateway_entities()
 
     async def async_update(self) -> PlugwiseData:
-        """Update the various entities and their states."""
+        """Update the Plughwise Gateway entities and their data and states."""
         data = PlugwiseData(devices={}, gateway={})
         try:
             data = await self._smile_api.async_update()

plugwise/helper.py

@@ -275,7 +275,6 @@ def __init__(self) -> None:
         self.smile_type: str
         self.smile_version: version.Version | None
         self.smile_zigbee_mac_address: str | None
-        self.therms_with_offset_func: list[str] = []
         self._zones: dict[str, GwEntityData] = {}
         SmileCommon.__init__(self)
 

plugwise/legacy/smile.py

@@ -34,7 +34,7 @@
 
 
 class SmileLegacyAPI(SmileLegacyData):
-    """The Plugwise SmileLegacyAPI class."""
+    """The Plugwise SmileLegacyAPI helper class for actual Plugwise legacy devices."""
 
     # pylint: disable=too-many-instance-attributes, too-many-public-methods
 
@@ -83,7 +83,7 @@ def __init__(
         self._previous_day_number: str = "0"
 
     async def full_xml_update(self) -> None:
-        """Perform a first fetch of all XML data, needed for initialization."""
+        """Perform a first fetch of the Plugwise server XML data."""
         self._domain_objects = await self.request(DOMAIN_OBJECTS)
         self._locations = await self.request(LOCATIONS)
         self._modules = await self.request(MODULES)
@@ -92,24 +92,23 @@ async def full_xml_update(self) -> None:
             self._appliances = await self.request(APPLIANCES)
 
     def get_all_gateway_entities(self) -> None:
-        """Collect the gateway entities from the received raw XML-data.
+        """Collect the Plugwise gateway entities and their data and states from the received raw XML-data.
 
-        Run this functions once to gather the initial device configuration,
-        then regularly run async_update() to refresh the device data.
+        First, collect all the connected entities and their initial data.
+        Collect and add switching- and/or pump-group entities.
+        Finally, collect the data and states for each entity.
         """
-        # Gather all the devices and their initial data
         self._all_appliances()
-
-        # Collect and add switching- and/or pump-group devices
         if group_data := self._get_group_switches():
             self.gw_entities.update(group_data)
 
-        # Collect the remaining data for all entities
         self._all_entity_data()
 
     async def async_update(self) -> PlugwiseData:
-        """Perform an incremental update for updating the various device states."""
-        # Perform a full update at day-change
+        """Perform an full update update at day-change: re-collect all gateway entities and their data and states.
+
+        Otherwise perform an incremental update: only collect the entities updated data and states.
+        """
         day_number = dt.datetime.now().strftime("%w")
         if (
             day_number  # pylint: disable=consider-using-assignment-expr
@@ -129,7 +128,6 @@ async def async_update(self) -> PlugwiseData:
                 raise DataMissingError(
                     "No (full) Plugwise legacy data received"
                 ) from err
-        # Otherwise perform an incremental update
         else:
             try:
                 self._domain_objects = await self.request(DOMAIN_OBJECTS)

plugwise/smile.py

@@ -93,45 +93,47 @@ def __init__(
         self.smile_name = smile_name
         self.smile_type = smile_type
         self.smile_version = smile_version
+        self.therms_with_offset_func: list[str] = []
         SmileData.__init__(self)
 
     async def full_xml_update(self) -> None:
-        """Perform a first fetch of all XML data, needed for initialization."""
+        """Perform a first fetch of the Plugwise server XML data."""
         self._domain_objects = await self.request(DOMAIN_OBJECTS)
         self._get_plugwise_notifications()
 
     def get_all_gateway_entities(self) -> None:
-        """Collect the gateway entities from the received raw XML-data.
+        """Collect the Plugwise gateway entities and their data and states from the received raw XML-data.
 
-        Run this functions once to gather the initial configuration,
-        then regularly run async_update() to refresh the entity data.
+        First, collect all the connected entities and their initial data.
+        If a thermostat-gateway, collect a list of thermostats with offset-capability.
+        Collect and add switching- and/or pump-group entities.
+        Finally, collect the data and states for each entity.
         """
-        # Gather all the entities and their initial data
         self._all_appliances()
         if self._is_thermostat:
-            if self.smile(ADAM):
-                self._scan_thermostats()
-            # Collect a list of thermostats with offset-capability
             self.therms_with_offset_func = (
                 self._get_appliances_with_offset_functionality()
             )
+            if self.smile(ADAM):
+                self._scan_thermostats()
 
-        # Collect and add switching- and/or pump-group devices
         if group_data := self._get_group_switches():
             self.gw_entities.update(group_data)
 
-        # Collect the remaining data for all entities
         self._all_entity_data()
 
     async def async_update(self) -> PlugwiseData:
-        """Perform an incremental update for updating the various device states."""
+        """Perform an full update: re-collect all gateway entities and their data and states.
+
+        Any change in the connected entities will be detected immediately.
+        """
         self.gw_data: GatewayData = {}
         self.gw_entities: dict[str, GwEntityData] = {}
         self._zones: dict[str, GwEntityData] = {}
         try:
             await self.full_xml_update()
             self.get_all_gateway_entities()
-            # Set self._cooling_enabled - required for set_temperature,
+            # Set self._cooling_enabled - required for set_temperature(),
             # also, check for a failed data-retrieval
             if "heater_id" in self.gw_data:
                 heat_cooler = self.gw_entities[self.gw_data["heater_id"]]