Merge branch 'main' into dynamic_status_trait

Author: Lash-L

.github/workflows/ci.yml

@@ -47,8 +47,15 @@ jobs:
           activate-environment: true
       - run: uv pip install pip
       - name: Test with Pytest
-        run:  uv run pytest --log-cli-level=DEBUG -vv -s
+        run:  uv run pytest --log-cli-level=DEBUG -vv -s --cov --cov-branch --cov-report=xml
         shell: bash
+      - name: Upload results to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: Python-roborock/python-roborock
+
+
 
   build:
     name: Build Package
@@ -82,15 +89,15 @@ jobs:
           git config user.email "actions@github.com"
       - name: Test Semantic Release (No-op)
         id: test-release
-        uses: python-semantic-release/python-semantic-release@v10.5.2
+        uses: python-semantic-release/python-semantic-release@v10.5.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           changelog: true
           # Use noop mode to test without making changes
           no_operation_mode: true
       - name: Test Semantic Release (Dry Run)
         id: test-release-dry
-        uses: python-semantic-release/python-semantic-release@v10.5.2
+        uses: python-semantic-release/python-semantic-release@v10.5.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           changelog: true
@@ -122,7 +129,7 @@ jobs:
         persist-credentials: false
     - name: Python Semantic Release
       id: release
-      uses: python-semantic-release/python-semantic-release@v10.5.2
+      uses: python-semantic-release/python-semantic-release@v10.5.3
       with:
         github_token: ${{ secrets.GH_TOKEN }}
         changelog: true
@@ -138,7 +145,7 @@ jobs:
         verbose: true
 
     - name: Publish package distributions to GitHub Releases
-      uses: python-semantic-release/publish-action@v10.5.2
+      uses: python-semantic-release/publish-action@v10.5.3
       if: steps.release.outputs.released == 'true'
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -6,8 +6,12 @@
   </a>
   <img src="https://img.shields.io/pypi/pyversions/python-roborock.svg?style=flat-square&logo=python&amp;logoColor=fff" alt="Supported Python versions">
   <img src="https://img.shields.io/pypi/l/python-roborock.svg?style=flat-square" alt="License">
+    <a href="https://codecov.io/github/Python-roborock/python-roborock" >
+  <img src="https://codecov.io/github/Python-roborock/python-roborock/graph/badge.svg?token=KEK4S3FPSZ" alt="Code Coverage"/>
+ </a>
 </p>
 
+
 Roborock library for online and offline control of your vacuums.
 
 ## Installation
@@ -16,11 +20,13 @@ Install this via pip (or your favourite package manager):
 
 `pip install python-roborock`
 
-## Functionality
+## Example Usage
 
-You can see all of the commands supported [here](https://python-roborock.readthedocs.io/en/latest/api_commands.html)
+See [examples/example.py](examples/example.py) for a more full featured example,
+or the [API documentation](https://python-roborock.github.io/python-roborock/)
+for more details.
 
-## Example Usage
+Here is a basic example:
 
 ```python
 import asyncio
@@ -30,38 +36,45 @@ from roborock.devices.device_manager import create_device_manager, UserParams
 
 
 async def main():
-    web_api = RoborockApiClient(username="youremailhere")
-    # Login via your password
-    user_data = await web_api.pass_login(password="pass_here")
-    # Or login via a code
+    email_address = "youremailhere@example.com"
+    web_api = RoborockApiClient(username=email_address)
+    # Send a login code to the above email address
     await web_api.request_code()
+    # Prompt the user to enter the code
     code = input("What is the code?")
     user_data = await web_api.code_login(code)
 
     # Create a device manager that can discover devices.
-    user_params = UserParams(
-        username="youremailhere",
-        user_data=user_data,
-    )
+    user_params = UserParams(username=email_address, user_data=user_data)
     device_manager = await create_device_manager(user_params)
     devices = await device_manager.get_devices()
 
-    # Get all vacuum devices that support the v1 PropertiesApi
+    # Get all vacuum devices. Each device generation has different capabilities
+    # and APIs available so to find vacuums we filter by the v1 PropertiesApi.
     for device in devices:
         if not device.v1_properties:
             continue
 
-        # Refresh the current device status
+        # The PropertiesAPI has traits different device commands such as getting
+        # status, sending clean commands, etc. For this example we send a
+        # command to refresh the current device status.
         status_trait = device.v1_properties.status
         await status_trait.refresh()
         print(status_trait)
 
 asyncio.run(main())
 ```
 
-See [examples/example.py](examples/example.py) for a more full featured example
-that has performance improvements to cache cloud information to prefer
-connections over the local network.
+
+## Functionality
+
+The library interacts with devices through specific API properties based on the device protocol:
+
+*   **Standard Vacuums (V1 Protocol)**: Most robot vacuums use this. Interaction is done through `device.v1_properties`, which contains traits like `status`, `consumables`, and `maps`. Use the `command` trait for actions like starting or stopping cleaning.
+*   **Wet/Dry Vacuums & Washing Machines (A01 Protocol)**: Devices like the Dyad and Zeo use this. Interaction is done through `device.a01_properties` using `query_values()` and `set_value()`.
+
+You can find detailed documentation for [Devices](https://python-roborock.github.io/python-roborock/roborock/devices/device.html) and [Traits](https://python-roborock.github.io/python-roborock/roborock/devices/traits.html).
+
 
 ## Supported devices
 
@@ -70,6 +83,7 @@ You can find what devices are supported
 Please note this may not immediately contain the latest devices.
 
 
-## Credits
+## Acknowledgements
 
-Thanks @rovo89 for https://gist.github.com/rovo89/dff47ed19fca0dfdda77503e66c2b7c7 And thanks @PiotrMachowski for https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor
+* Thanks to [@rovo89](https://github.com/rovo89) for [Login APIs gist](https://gist.github.com/rovo89/dff47ed19fca0dfdda77503e66c2b7c7).
+* Thanks to [@PiotrMachowski](https://github.com/PiotrMachowski) for [Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor](https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor).

README.md

@@ -38,7 +38,7 @@
 | `is_carpet_shape_type_supported` |  |  |  |
 | `is_carpet_show_on_map` |  | X |  |
 | `is_carpet_supported` | X | X |  |
-| `is_ces2022_supported` |  |  |  |
+| `is_ces_2022_supported` |  |  |  |
 | `is_clean_count_setting_supported` |  | X |  |
 | `is_clean_direct_status_supported` |  |  |  |
 | `is_clean_efficiency_supported` |  |  |  |

SUPPORTED_FEATURES.md

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "3.8.5"
+version = "3.19.0"
 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"
@@ -44,16 +44,17 @@ dev = [
     "pytest",
     "pre-commit>=3.5,<5.0",
     "mypy",
-    "ruff==0.14.6",
+    "ruff==0.14.9",
     "codespell",
     "pyshark>=0.6,<0.7",
     "aioresponses>=0.7.7,<0.8",
     "freezegun>=1.5.1,<2",
     "pytest-timeout>=2.3.1,<3",
-    "syrupy>=4.9.1,<5",
-    "pdoc>=15.0.4,<16",
+    "syrupy>=4.9.1,<6",
+    "pdoc>=15.0.4,<17",
     "pyyaml>=6.0.3",
     "pyshark>=0.6",
+    "pytest-cov>=7.0.0",
 ]
 
 [tool.hatch.build.targets.sdist]

pyproject.toml

@@ -10,7 +10,9 @@
 V = TypeVar("V")
 
 
-def safe_callback(callback: Callable[[V], None], logger: logging.Logger | None = None) -> Callable[[V], None]:
+def safe_callback(
+    callback: Callable[[V], None], logger: logging.Logger | logging.LoggerAdapter | None = None
+) -> Callable[[V], None]:
     """Wrap a callback to catch and log exceptions.
 
     This is useful for ensuring that errors in callbacks do not propagate
@@ -36,7 +38,7 @@ class CallbackMap(Generic[K, V]):
     when a value is received for a specific key.
     """
 
-    def __init__(self, logger: logging.Logger | None = None) -> None:
+    def __init__(self, logger: logging.Logger | logging.LoggerAdapter | None = None) -> None:
         self._callbacks: dict[K, list[Callable[[V], None]]] = {}
         self._logger = logger or _LOGGER
 
@@ -79,7 +81,7 @@ class CallbackList(Generic[V]):
     additional callbacks to the list at any time.
     """
 
-    def __init__(self, logger: logging.Logger | None = None) -> None:
+    def __init__(self, logger: logging.Logger | logging.LoggerAdapter | None = None) -> None:
         self._callbacks: list[Callable[[V], None]] = []
         self._logger = logger or _LOGGER
 
@@ -101,7 +103,9 @@ def __call__(self, value: V) -> None:
 
 
 def decoder_callback(
-    decoder: Callable[[K], list[V]], callback: Callable[[V], None], logger: logging.Logger | None = None
+    decoder: Callable[[K], list[V]],
+    callback: Callable[[V], None],
+    logger: logging.Logger | logging.LoggerAdapter | None = None,
 ) -> Callable[[K], None]:
     """Create a callback that decodes messages using a decoder and invokes a callback.
 
@@ -120,7 +124,7 @@ def wrapper(data: K) -> None:
             logger.warning("Failed to decode message: %s", data)
             return
         for message in messages:
-            _LOGGER.debug("Decoded message: %s", message)
+            logger.debug("Decoded message: %s", message)
             safe_cb(message)
 
     return wrapper