python-roborock 7.12.2__tar.gz → 7.12.3__tar.gz

{python_roborock-7.12.2 → python_roborock-7.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-roborock
-Version: 7.12.2
+Version: 7.12.3
 Summary: A package to control Roborock vacuums.
 Project-URL: Repository, https://github.com/python-roborock/python-roborock
 Project-URL: Documentation, https://python-roborock.readthedocs.io/

{python_roborock-7.12.2 → python_roborock-7.12.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "7.12.2"
+version = "7.12.3"
 description = "A package to control Roborock vacuums."
 authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
 requires-python = ">=3.11, <4"

{python_roborock-7.12.2 → python_roborock-7.12.3}/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,36 +253,26 @@ class StatusV2(RoborockBase):
     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.
         """
-        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 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:
+        """Return whether the battery is actively charging."""
+        return self.dock_state == RoborockDockState.charging
 
     def __repr__(self) -> str:
         return _attr_repr(self)

{python_roborock-7.12.2 → python_roborock-7.12.3}/roborock/devices/traits/v1/status.py

@@ -5,6 +5,7 @@ from typing import Any
 from roborock import (
     CleaningMode,
     CleanRoutes,
+    RoborockDockState,
     StatusV2,
     VacuumModes,
     WaterModes,
@@ -13,6 +14,7 @@ from roborock import (
     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,
@@ -66,6 +68,21 @@ class StatusTrait(StatusV2, common.V1TraitMixin, TraitUpdateListener):
         self._device_features_trait = device_feature_trait
         self._region = region
 
+    @property
+    def dock_state(self) -> RoborockDockState:
+        """Return the feature-aware dock state used by the Roborock app."""
+        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)