refactor: extract get_dock_state function and deprecate StatusV2.dock_state

Author: Lash-L

roborock/data/v1/v1_containers.py

@@ -1,5 +1,6 @@
 import datetime
 import logging
+import warnings
 from dataclasses import dataclass, field
 from enum import StrEnum
 from typing import Any
@@ -73,6 +74,39 @@ class StatusField(FieldNameBase):
     RDT = "rdt"
 
 
+def get_dock_state(
+    state: RoborockStateCode | int | None,
+    battery: int | None,
+    charge_status: RoborockChargeStatus | int | None = None,
+    *,
+    is_supported_valley_electricity: bool = False,
+) -> RoborockDockState:
+    """Return the dock state, accounting for off-peak charging support."""
+    if state is None or state == RoborockStateCode.unknown:
+        return RoborockDockState.unknown
+
+    # 6. DUSTING
+    if state == RoborockStateCode.emptying_the_bin:
+        return RoborockDockState.dusting
+
+    # 5. FULL
+    if state == RoborockStateCode.charging_complete or (state == RoborockStateCode.charging and battery == 100):
+        return RoborockDockState.full
+
+    # 3 & 4. CHARGING and CHARGE_WAITING
+    if state == RoborockStateCode.charging:
+        if is_supported_valley_electricity and charge_status == RoborockChargeStatus.charge_waiting:
+            return RoborockDockState.off_peak_waiting
+        return RoborockDockState.charging
+
+    # 2. RECHARGING
+    if state in (RoborockStateCode.returning_home, RoborockStateCode.docking):
+        return RoborockDockState.returning
+
+    # 1. IDLE (Not on dock, or doing something else)
+    return RoborockDockState.idle
+
+
 @dataclass
 class StatusV2(RoborockBase):
     """The result of a GET_STATUS API request."""
@@ -219,40 +253,21 @@ def dock_cool_fan_status(self) -> int | None:
     def dock_state(self) -> RoborockDockState:
         """A synthesized, high-level dock state reflecting the UI's display.
 
-        This property simplifies integration by handling the complex logic
-        of checking state, charge_status, and battery level simultaneously. It handles
-        newer off-peak charging logic seamlessly while maintaining backwards compatibility
-        with older devices.
+        .. deprecated::
+            Use StatusTrait.dock_state or get_dock_state instead.
         """
-        return self.get_dock_state()
-
-    def get_dock_state(self, *, is_supported_valley_electricity: bool = True) -> RoborockDockState:
-        """Return the dock state, accounting for off-peak charging support."""
-        if self.state is None or self.state == RoborockStateCode.unknown:
-            return RoborockDockState.unknown
-
-        # 6. DUSTING
-        if self.state == RoborockStateCode.emptying_the_bin:
-            return RoborockDockState.dusting
-
-        # 5. FULL
-        if self.state == RoborockStateCode.charging_complete or (
-            self.state == RoborockStateCode.charging and self.battery == 100
-        ):
-            return RoborockDockState.full
-
-        # 3 & 4. CHARGING and CHARGE_WAITING
-        if self.state == RoborockStateCode.charging:
-            if is_supported_valley_electricity and self.charge_status == RoborockChargeStatus.charge_waiting:
-                return RoborockDockState.off_peak_waiting
-            return RoborockDockState.charging
-
-        # 2. RECHARGING
-        if self.state in (RoborockStateCode.returning_home, RoborockStateCode.docking):
-            return RoborockDockState.returning
-
-        # 1. IDLE (Not on dock, or doing something else)
-        return RoborockDockState.idle
+        warnings.warn(
+            "StatusV2.dock_state is deprecated and will be removed in a future release. "
+            "Use StatusTrait.dock_state or get_dock_state instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return get_dock_state(
+            state=self.state,
+            battery=self.battery,
+            charge_status=self.charge_status,
+            is_supported_valley_electricity=True,
+        )
 
     @property
     def is_battery_charging(self) -> bool:

roborock/devices/traits/v1/status.py

@@ -14,6 +14,7 @@
     get_cleaning_mode_options,
     get_cleaning_mode_parameters,
     get_current_cleaning_mode,
+    get_dock_state,
     get_water_mode_mapping,
     get_water_modes,
     get_water_slide_mode_name,
@@ -70,10 +71,18 @@ def __init__(self, device_feature_trait: DeviceFeaturesTrait, region: str | None
     @property
     def dock_state(self) -> RoborockDockState:
         """Return the feature-aware dock state used by the Roborock app."""
-        return self.get_dock_state(
-            is_supported_valley_electricity=self._device_features_trait.is_supported_valley_electricity
+        return get_dock_state(
+            state=self.state,
+            battery=self.battery,
+            charge_status=self.charge_status,
+            is_supported_valley_electricity=self._device_features_trait.is_supported_valley_electricity,
         )
 
+    @property
+    def is_battery_charging(self) -> bool:
+        """Return whether the battery is actively charging."""
+        return self.dock_state == RoborockDockState.charging
+
     @cached_property
     def fan_speed_options(self) -> list[VacuumModes]:
         return get_clean_modes(self._device_features_trait)

tests/data/v1/test_v1_containers.py

@@ -23,6 +23,7 @@
     Consumable,
     DnDTimer,
     StatusV2,
+    get_dock_state,
 )
 from tests.mock_data import (
     CLEAN_RECORD,
@@ -141,36 +142,54 @@ def test_current_map() -> None:
 
 
 @pytest.mark.parametrize(
-    "state, charge_status, battery, expected_dock_state",
+    "state, charge_status, battery, is_supported_valley_electricity, expected_dock_state",
     [
-        (RoborockStateCode.emptying_the_bin, None, 50, RoborockDockState.dusting),
-        (RoborockStateCode.charging_complete, None, 100, RoborockDockState.full),
-        (RoborockStateCode.charging, None, 100, RoborockDockState.full),
-        (RoborockStateCode.charging, RoborockChargeStatus.charging.value, 90, RoborockDockState.charging),
-        (RoborockStateCode.charging, RoborockChargeStatus.charge_waiting.value, 50, RoborockDockState.off_peak_waiting),
-        (RoborockStateCode.charging, None, 50, RoborockDockState.charging),
-        (RoborockStateCode.returning_home, None, 20, RoborockDockState.returning),
-        (RoborockStateCode.docking, None, 15, RoborockDockState.returning),
-        (RoborockStateCode.cleaning, None, 80, RoborockDockState.idle),
-        (RoborockStateCode.paused, None, 80, RoborockDockState.idle),
-        (RoborockStateCode.unknown, None, 100, RoborockDockState.unknown),
-        (None, None, 100, RoborockDockState.unknown),
+        (RoborockStateCode.emptying_the_bin, None, 50, False, RoborockDockState.dusting),
+        (RoborockStateCode.charging_complete, None, 100, False, RoborockDockState.full),
+        (RoborockStateCode.charging, None, 100, False, RoborockDockState.full),
+        (RoborockStateCode.charging, RoborockChargeStatus.charging.value, 90, False, RoborockDockState.charging),
+        (
+            RoborockStateCode.charging,
+            RoborockChargeStatus.charge_waiting.value,
+            50,
+            True,
+            RoborockDockState.off_peak_waiting,
+        ),
+        (RoborockStateCode.charging, RoborockChargeStatus.charge_waiting.value, 50, False, RoborockDockState.charging),
+        (RoborockStateCode.charging, None, 50, False, RoborockDockState.charging),
+        (RoborockStateCode.returning_home, None, 20, False, RoborockDockState.returning),
+        (RoborockStateCode.docking, None, 15, False, RoborockDockState.returning),
+        (RoborockStateCode.cleaning, None, 80, False, RoborockDockState.idle),
+        (RoborockStateCode.paused, None, 80, False, RoborockDockState.idle),
+        (RoborockStateCode.unknown, None, 100, False, RoborockDockState.unknown),
+        (None, None, 100, False, RoborockDockState.unknown),
     ],
 )
-def test_dock_state(
+def test_get_dock_state(
     state: RoborockStateCode | None,
     charge_status: int | None,
     battery: int,
+    is_supported_valley_electricity: bool,
     expected_dock_state: RoborockDockState,
 ) -> None:
-    """Test that dock_state correctly synthesizes UI state."""
-    status = copy.deepcopy(STATUS)
-    status["state"] = state
-    status["charge_status"] = charge_status
-    status["battery"] = battery
+    """Test that get_dock_state correctly synthesizes UI state."""
+    assert (
+        get_dock_state(
+            state=state,
+            battery=battery,
+            charge_status=charge_status,
+            is_supported_valley_electricity=is_supported_valley_electricity,
+        )
+        == expected_dock_state
+    )
 
+
+def test_status_v2_dock_state_deprecated() -> None:
+    """Test that accessing StatusV2.dock_state issues a DeprecationWarning."""
+    status = copy.deepcopy(STATUS)
     s = StatusV2.from_dict(status)
-    assert s.dock_state == expected_dock_state
+    with pytest.deprecated_call():
+        assert s.dock_state == RoborockDockState.full
 
 
 def test_status_v2() -> None:

tests/devices/traits/v1/test_status.py

@@ -1,6 +1,7 @@
 """Tests for the StatusTrait class."""
 
 import asyncio
+import warnings
 from typing import cast
 from unittest.mock import AsyncMock, call
 
@@ -208,8 +209,10 @@ def test_feature_aware_dock_and_charging_state(
     status_trait.charge_status = charge_status
     status_trait.battery = battery
 
-    assert status_trait.dock_state == expected_dock_state
-    assert status_trait.is_battery_charging is expected_is_battery_charging
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+        assert status_trait.dock_state == expected_dock_state
+        assert status_trait.is_battery_charging is expected_is_battery_charging
 
 
 def test_options(status_trait: StatusTrait) -> None: