Implement introspectable actions

miio/device.py

@@ -1,5 +1,6 @@
 import logging
 from enum import Enum
+from inspect import getmembers
 from typing import Any, Dict, List, Optional, Union  # noqa: F401
 
 import click
@@ -57,6 +58,7 @@ def __init__(
         self.token: Optional[str] = token
         self._model: Optional[str] = model
         self._info: Optional[DeviceInfo] = None
+        self._actions: Optional[List[ActionDescriptor]] = None
         timeout = timeout if timeout is not None else self.timeout
         self._protocol = MiIOProtocol(
             ip, token, start_id, debug, lazy_discover, timeout
@@ -243,7 +245,15 @@ def status(self) -> DeviceStatus:
 
     def actions(self) -> Dict[str, ActionDescriptor]:
         """Return device actions."""
-        return {}
+        if self._actions is None:
+            self._actions = []
+            for action_tuple in getmembers(self, lambda o: hasattr(o, "_action")):
+                method_name, method = action_tuple
+                action = method._action
+                action.method = method  # bind the method
+                self._actions.append(action)
+
+        return self._actions
 
     def settings(self) -> Dict[str, SettingDescriptor]:
         """Return device settings."""

miio/devicestatus.py

@@ -14,6 +14,7 @@
 )
 
 from .descriptors import (
+    ActionDescriptor,
     BooleanSettingDescriptor,
     EnumSettingDescriptor,
     NumberSettingDescriptor,
@@ -236,3 +237,32 @@ def decorator_setting(func):
         return func
 
     return decorator_setting
+
+
+def action(name: str, **kwargs):
+    """Syntactic sugar to create ActionDescriptor objects.
+
+    The information can be used by users of the library to programmatically find out what
+    types of actions are available for the device.
+
+    The interface is kept minimal, but you can pass any extra keyword arguments.
+    These extras are made accessible over :attr:`~miio.descriptors.ActionDescriptor.extras`,
+    and can be interpreted downstream users as they wish.
+    """
+
+    def decorator_action(func):
+        property_name = str(func.__name__)
+        qualified_name = str(func.__qualname__)
+
+        descriptor = ActionDescriptor(
+            id=qualified_name,
+            name=name,
+            method_name=property_name,
+            method=None,
+            extras=kwargs,
+        )
+        func._action = descriptor
+
+        return func
+
+    return decorator_action

miio/integrations/vacuum/roborock/vacuum.py

@@ -20,6 +20,7 @@
     LiteralParamType,
     command,
 )
+from miio.devicestatus import action
 from miio.device import Device, DeviceInfo
 from miio.exceptions import DeviceInfoUnavailableException, UnsupportedFeatureException
 from miio.interfaces import FanspeedPresets, VacuumInterface
@@ -866,12 +867,14 @@ def set_dust_collection_mode(self, mode: DustCollectionMode) -> bool:
         return self.send("set_dust_collection_mode", {"mode": mode.value})[0] == "ok"
 
     @command()
+    @action(name="Start dust collection", icon="mdi:turbine")
     def start_dust_collection(self):
         """Activate automatic dust collection."""
         self._verify_auto_empty_support()
         return self.send("app_start_collect_dust")
 
     @command()
+    @action(name="Stop dust collection", icon="mdi:turbine")
     def stop_dust_collection(self):
         """Abort in progress dust collection."""
         self._verify_auto_empty_support()