Improve annotations.

Make annotations style and language consistent across different modules.

custom_components/plum_ecomax/__init__.py

@@ -59,7 +59,7 @@
 
 
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
-    """Set up Plum ecoMAX from a config entry."""
+    """Set up the Plum ecoMAX from a config entry."""
     connection_type = entry.data.get(CONF_CONNECTION_TYPE, DEFAULT_CONNECTION_TYPE)
     connection = EcomaxConnection(
         hass,
@@ -68,7 +68,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     )
 
     async def async_close_connection(event=None):
-        """Close ecoMAX connection on HA Stop."""
+        """Close the ecoMAX connection on HA Stop."""
         await connection.close()
 
     entry.async_on_unload(
@@ -91,7 +91,7 @@ async def async_close_connection(event=None):
 
 @callback
 def async_setup_events(hass: HomeAssistant, connection: EcomaxConnection) -> bool:
-    """Setup ecoMAX events."""
+    """Set up the ecoMAX events."""
 
     dr = device_registry.async_get(hass)
 

custom_components/plum_ecomax/binary_sensor.py

@@ -27,7 +27,7 @@
 
 @dataclass(kw_only=True, slots=True)
 class EcomaxBinarySensorEntityDescription(BinarySensorEntityDescription):
-    """Describes ecoMAX binary sensor entity."""
+    """Describes an ecoMAX binary sensor."""
 
     value_fn: Callable[[Any], Any]
     product_types: set[ProductType] | Literal["all"] = ALL
@@ -134,13 +134,14 @@ class EcomaxBinarySensorEntityDescription(BinarySensorEntityDescription):
 
 
 class EcomaxBinarySensor(EcomaxEntity, BinarySensorEntity):
-    """Representation of ecoMAX binary sensor."""
+    """Represents an ecoMAX binary sensor."""
 
     def __init__(
         self,
         connection: EcomaxConnection,
         description: EcomaxBinarySensorEntityDescription,
     ):
+        """Initialize a new ecoMAX binary sensor."""
         self._connection = connection
         self.entity_description = description
         self._attr_available = False
@@ -163,7 +164,7 @@ def icon(self) -> str | None:
 
 @dataclass(slots=True)
 class MixerBinarySensorEntityDescription(EcomaxBinarySensorEntityDescription):
-    """Describes ecoMAX mixer binary sensor entity."""
+    """Describes a mixer binary sensor."""
 
 
 MIXER_BINARY_SENSOR_TYPES: tuple[MixerBinarySensorEntityDescription, ...] = (
@@ -189,15 +190,15 @@ class MixerBinarySensorEntityDescription(EcomaxBinarySensorEntityDescription):
 
 
 class MixerBinarySensor(MixerEntity, EcomaxBinarySensor):
-    """Represents mixer binary sensor platform."""
+    """Represents a mixer binary sensor."""
 
     def __init__(
         self,
         connection: EcomaxConnection,
         description: MixerBinarySensorEntityDescription,
         index: int,
     ):
-        """Initialize mixer binary sensor object."""
+        """Initialize a new mixer binary sensor."""
         self.index = index
         super().__init__(connection, description)
 
@@ -206,7 +207,7 @@ def get_by_product_type(
     product_type: ProductType,
     descriptions: Iterable[EcomaxBinarySensorEntityDescription],
 ) -> Generator[EcomaxBinarySensorEntityDescription, None, None]:
-    """Filter descriptions by product type."""
+    """Filter descriptions by the product type."""
     for description in descriptions:
         if (
             description.product_types == ALL
@@ -218,7 +219,7 @@ def get_by_product_type(
 def get_by_modules(
     connected_modules, descriptions: Iterable[EcomaxBinarySensorEntityDescription]
 ) -> Generator[EcomaxBinarySensorEntityDescription, None, None]:
-    """Filter descriptions by modules."""
+    """Filter descriptions by connected modules."""
     for description in descriptions:
         if getattr(connected_modules, description.module, None) is not None:
             yield description
@@ -227,7 +228,7 @@ def get_by_modules(
 def async_setup_ecomax_binary_sensors(
     connection: EcomaxConnection,
 ) -> list[EcomaxBinarySensor]:
-    """Setup ecoMAX binary sensors."""
+    """Set up the ecoMAX binary sensors."""
     return [
         EcomaxBinarySensor(connection, description)
         for description in get_by_modules(
@@ -240,7 +241,7 @@ def async_setup_ecomax_binary_sensors(
 def async_setup_mixer_binary_sensors(
     connection: EcomaxConnection,
 ) -> list[MixerBinarySensor]:
-    """Setup mixer binary sensors."""
+    """Set up the mixer binary sensors."""
     entities: list[MixerBinarySensor] = []
 
     for index in connection.device.mixers.keys():

custom_components/plum_ecomax/button.py

@@ -20,7 +20,7 @@
 
 @dataclass(kw_only=True, slots=True)
 class EcomaxButtonEntityDescription(ButtonEntityDescription):
-    """Describes ecoMAX button entity."""
+    """Describes an ecoMAX button."""
 
     press_fn: str
 
@@ -38,15 +38,15 @@ class EcomaxButtonEntityDescription(ButtonEntityDescription):
 
 
 class EcomaxButton(EcomaxEntity, ButtonEntity):
-    """Represents ecoMAX sensor platform."""
+    """Represents an ecoMAX button."""
 
     _connection: EcomaxConnection
     entity_description: EntityDescription
 
     def __init__(
         self, connection: EcomaxConnection, description: EcomaxButtonEntityDescription
     ):
-        """Initialize ecoMAX sensor object."""
+        """Initialize a new ecoMAX button."""
         self._connection = connection
         self.entity_description = description
 
@@ -57,11 +57,14 @@ async def async_press(self) -> None:
 
     @property
     def entity_registry_enabled_default(self) -> bool:
-        """Indicate if the entity should be enabled when first added."""
+        """Return if the entity should be enabled when first added.
+
+        This only applies when fist added to the entity registry.
+        """
         return self.entity_description.entity_registry_enabled_default
 
-    async def async_update(self, value) -> None:
-        """Retrieve latest state."""
+    async def async_update(self, _) -> None:
+        """Update entity state."""
 
     async def async_added_to_hass(self):
         """Called when an entity has their entity_id assigned."""
@@ -75,7 +78,7 @@ async def async_setup_entry(
     config_entry: ConfigType,
     async_add_entities: AddEntitiesCallback,
 ) -> bool:
-    """Set up the sensor platform."""
+    """Set up the button platform."""
     connection = hass.data[DOMAIN][config_entry.entry_id]
     return async_add_entities(
         EcomaxButton(connection, description) for description in BUTTON_TYPES

custom_components/plum_ecomax/climate.py

@@ -81,13 +81,13 @@
 
 @dataclass(kw_only=True, slots=True)
 class EcomaxClimateEntityDescription(ClimateEntityDescription):
-    """Describes ecoMAX climate entity."""
+    """Describes an ecoMAX climate entity."""
 
     index: int
 
 
 class EcomaxClimate(EcomaxEntity, ClimateEntity):
-    """Represents ecoMAX climate platform."""
+    """Represents an ecoMAX climate entity."""
 
     _attr_current_temperature: float | None = None
     _attr_entity_registry_enabled_default: bool
@@ -108,6 +108,7 @@ class EcomaxClimate(EcomaxEntity, ClimateEntity):
     entity_description: EntityDescription
 
     def __init__(self, connection: EcomaxConnection, thermostat: Thermostat):
+        """Initialize a new ecoMAX climate entity."""
         self._attr_current_temperature = None
         self._attr_entity_registry_enabled_default = True
         self._attr_hvac_action = None
@@ -160,11 +161,11 @@ async def async_update_target_temperature(self, value: float) -> None:
 
     @overload
     async def async_update_preset_mode(self, mode: int) -> None:
-        """Update preset mode from the state."""
+        """Update preset mode from the state sensor."""
 
     @overload
     async def async_update_preset_mode(self, mode: ThermostatParameter) -> None:
-        """Update preset mode from the parameter."""
+        """Update preset mode from the mode parameter."""
 
     async def async_update_preset_mode(self, mode) -> None:
         """Update preset mode."""
@@ -215,21 +216,20 @@ async def async_will_remove_from_hass(self):
     async def _async_update_target_temperature_attributes(
         self, target_temp: float | None = None
     ) -> None:
-        """Update target temperature parameter name and bounds."""
+        """Update target temperature parameter name and boundaries."""
         preset_mode = self.preset_mode
 
         if preset_mode == PRESET_SCHEDULE:
             preset_mode = await self._async_get_current_schedule_preset(target_temp)
 
         if preset_mode in (PRESET_AIRING, PRESET_UNKNOWN):
-            # Don't update temperature target name if we couldn't
-            # identify preset in schedule mode or if preset is airing.
+            # Couldn't identify preset in schedule mode or
+            # preset is airing.
             return
 
         target_temperature_name = HA_PRESET_TO_EM_TEMP[preset_mode]
         if self.target_temperature_name == target_temperature_name:
-            # Don't update bounds if target temperature parameter name
-            # is unchanged.
+            # Target temperature parameter name is unchanged.
             return
 
         self._attr_target_temperature_name = target_temperature_name
@@ -242,7 +242,7 @@ async def _async_update_target_temperature_attributes(
     async def _async_get_current_schedule_preset(
         self, target_temp: float | None = None
     ) -> Literal["comfort", "eco", "unknown"]:
-        """Get current preset for schedule mode."""
+        """Get current preset for the schedule mode."""
         if target_temp is None:
             target_temp = await self.device.get("target_temp")
 
@@ -263,14 +263,14 @@ async def _async_get_current_schedule_preset(
 
     @property
     def device(self) -> Thermostat:
-        """Return thermostat object."""
+        """Return the thermostat object."""
         return self.connection.device.data[ATTR_THERMOSTATS][
             self.entity_description.index
         ]
 
     @property
     def target_temperature_name(self) -> str | None:
-        """Return target temperature name."""
+        """Return the target temperature name."""
         return self._attr_target_temperature_name
 
 

custom_components/plum_ecomax/config_flow.py

@@ -99,7 +99,7 @@ def __init__(self) -> None:
         self.init_info: MutableMapping[str, Any] = {}
 
     async def async_step_user(self, user_input=None) -> FlowResult:
-        """Handle the initial step."""
+        """Handle initial step."""
         return self.async_show_menu(
             step_id="user",
             menu_options=["tcp", "serial"],
@@ -108,7 +108,7 @@ async def async_step_user(self, user_input=None) -> FlowResult:
     async def async_step_tcp(
         self, user_input: MutableMapping[str, Any] | None = None
     ) -> FlowResult:
-        """Handle the TCP connection setup."""
+        """Handle TCP connection setup."""
         if user_input is None:
             return self.async_show_form(step_id="tcp", data_schema=STEP_TCP_DATA_SCHEMA)
 
@@ -137,7 +137,7 @@ async def async_step_tcp(
     async def async_step_serial(
         self, user_input: MutableMapping[str, Any] | None = None
     ) -> FlowResult:
-        """Handle the serial connection setup."""
+        """Handle serial connection setup."""
         if user_input is None:
             return self.async_show_form(
                 step_id="serial", data_schema=STEP_SERIAL_DATA_SCHEMA
@@ -241,7 +241,7 @@ async def _identify_device() -> None:
         return self.async_show_progress_done(next_step_id="discover")
 
     async def async_step_discover(self, user_input=None) -> FlowResult:
-        """Detect modules connected to the device."""
+        """Discover connected modules."""
 
         async def _discover_modules() -> None:
             try:

custom_components/plum_ecomax/connection.py

@@ -1,4 +1,4 @@
-"""Contains the Plum ecoMAX connection."""
+"""Connection handler for Plum ecoMAX."""
 from __future__ import annotations
 
 from collections.abc import Mapping
@@ -55,7 +55,7 @@
 async def async_get_connection_handler(
     connection_type: str, hass: HomeAssistant, data: Mapping[str, Any]
 ) -> pyplumio.Connection:
-    """Return connection handler object."""
+    """Return the connection handler."""
     _LOGGER.debug("Getting connection handler for type: %s...", connection_type)
 
     public_ip = await async_get_source_ip(hass, target_ip=IPV4_BROADCAST_ADDR)
@@ -76,7 +76,7 @@ async def async_get_connection_handler(
 
 
 async def async_get_sub_devices(device: AddressableDevice) -> list[str]:
-    """Return device subdevices."""
+    """Return the sub-devices."""
     _LOGGER.debug("Checking connected sub-devices...")
 
     sub_devices: list[str] = []
@@ -110,7 +110,7 @@ async def async_get_sub_devices(device: AddressableDevice) -> list[str]:
 
 
 class EcomaxConnection:
-    """Represents the ecoMAX connection."""
+    """Represents an ecoMAX connection."""
 
     _connection: pyplumio.Connection
     _device: AddressableDevice | None
@@ -120,7 +120,7 @@ class EcomaxConnection:
     def __init__(
         self, hass: HomeAssistant, entry: ConfigEntry, connection: pyplumio.Connection
     ):
-        """Initialize new ecoMAX connection object."""
+        """Initialize a new ecoMAX connection."""
         self._connection = connection
         self._device = None
         self._hass = hass
@@ -143,7 +143,7 @@ async def async_setup(self) -> None:
         self._device = device
 
     async def async_setup_thermostats(self) -> bool:
-        """Setup thermostats."""
+        """Set up the thermostats."""
         try:
             return await self.device.request(
                 ATTR_THERMOSTAT_PARAMETERS,
@@ -156,7 +156,7 @@ async def async_setup_thermostats(self) -> bool:
             return False
 
     async def async_setup_mixers(self) -> bool:
-        """Setup mixers."""
+        """Set up the mixers."""
         try:
             return await self.device.request(
                 ATTR_MIXER_PARAMETERS,
@@ -169,7 +169,7 @@ async def async_setup_mixers(self) -> bool:
             return False
 
     async def async_setup_regdata(self) -> bool:
-        """Setup regdata."""
+        """Setup regulator data."""
         try:
             return await self.device.request(
                 ATTR_REGDATA,
@@ -191,22 +191,22 @@ async def async_update_sub_devices(self) -> None:
 
     @property
     def has_water_heater(self) -> bool:
-        """Does device has attached water heater."""
+        """Return if device has attached water heater."""
         return ATTR_WATER_HEATER in self.entry.data.get(CONF_SUB_DEVICES, [])
 
     @property
     def has_thermostats(self) -> bool:
-        """Does device has attached thermostats."""
+        """Return if device has attached thermostats."""
         return ATTR_THERMOSTATS in self.entry.data.get(CONF_SUB_DEVICES, [])
 
     @property
     def has_mixers(self) -> bool:
-        """Does device has attached mixers."""
+        """Return if device has attached mixers."""
         return ATTR_MIXERS in self.entry.data.get(CONF_SUB_DEVICES, [])
 
     @property
     def device(self) -> AddressableDevice:
-        """Return connection state."""
+        """Return the device handler."""
         if self._device is None:
             raise ConfigEntryNotReady("Device not ready")
 
@@ -244,7 +244,7 @@ def name(self) -> str:
 
     @property
     def connection(self) -> pyplumio.Connection:
-        """Return the connection handler instance."""
+        """Return the connection handler."""
         return self._connection
 
     @property