Rename ButtonDescriptor to ActionDescriptor (#1567)

The actions may in future allow passing arguments to perform other
actions besides just triggering them.

Cleanup obsolete documentation related to switch decorator.

docs/contributing.rst

@@ -194,7 +194,7 @@ Development checklist
    listing the known models (as reported by :meth:`~miio.device.Device.info()`).
 4. Status containers is derived from :class:`~miio.devicestatus.DeviceStatus` class and all properties should
    have type annotations for their return values. The information that should be exposed directly
-   to end users should be decorated using appropriate decorators (e.g., `@sensor` or `@switch`) to make
+   to end users should be decorated using appropriate decorators (e.g., `@sensor` or `@setting`) to make
    them discoverable (:ref:`status_containers`).
 5. Add tests at least for the status container handling (:ref:`adding_tests`).
 6. Updating documentation is generally not needed as the API documentation
@@ -293,36 +293,19 @@ This will make all decorated sensors accessible through :meth:`~miio.device.Devi
     device class information to Home Assistant.
 
 
-Switches
-""""""""
-
-Use :meth:`@switch <miio.devicestatus.switch>` to create :class:`~miio.descriptors.SwitchDescriptor` objects.
-This will make all decorated switches accessible through :meth:`~miio.device.Device.switches` for downstream users.
-
-.. code-block::
-
-    @property
-    @switch(name="Power", setter_name="set_power")
-    def power(self) -> bool:
-        """Return if device is turned on."""
-
-You can either use *setter* to define a callable that can be used to adjust the value of the property,
-or alternatively define *setter_name* which will be used to bind the method during the initialization
-to the the :meth:`~miio.descriptors.SwitchDescriptor.setter` callable.
-
-
 Settings
 """"""""
 
-Use :meth:`@switch <miio.devicestatus.setting>` to create :meth:`~miio.descriptors.SettingDescriptor` objects.
+Use :meth:`@setting <miio.devicestatus.setting>` to create :meth:`~miio.descriptors.SettingDescriptor` objects.
 This will make all decorated settings accessible through :meth:`~miio.device.Device.settings` for downstream users.
 
 The type of the descriptor depends on the input parameters:
 
     * Passing *min_value* or *max_value* will create a :class:`~miio.descriptors.NumberSettingDescriptor`,
       which is useful for presenting ranges of values.
-    * Passing an Enum object using *choices* will create a :class:`~miio.descriptors.EnumSettingDescriptor`,
-      which is useful for presenting a fixed set of options.
+    * Passing an :class:`enum.Enum` object using *choices* will create a
+      :class:`~miio.descriptors.EnumSettingDescriptor`, which is useful for presenting a fixed set of options.
+    * Otherwise, the setting is considered to be boolean switch.
 
 
 You can either use *setter* to define a callable that can be used to adjust the value of the property,
@@ -338,7 +321,7 @@ The *max_value* is the only mandatory parameter. If not given, *min_value* defau
 .. code-block::
 
     @property
-    @switch(name="Fan Speed", min_value=0, max_value=100, steps=5, setter_name="set_fan_speed")
+    @setting(name="Fan Speed", min_value=0, max_value=100, steps=5, setter_name="set_fan_speed")
     def fan_speed(self) -> int:
         """Return the current fan speed."""
 
@@ -356,7 +339,7 @@ If the device has a setting with some pre-defined values, you want to use this.
         Off = 2
 
     @property
-    @switch(name="LED Brightness", choices=SomeEnum, setter_name="set_led_brightness")
+    @setting(name="LED Brightness", choices=SomeEnum, setter_name="set_led_brightness")
     def led_brightness(self) -> LedBrightness:
         """Return the LED brightness."""
 

miio/descriptors.py

@@ -3,11 +3,11 @@
 The descriptors contain information that can be used to provide generic, dynamic user-interfaces.
 
 If you are a downstream developer, use :func:`~miio.device.Device.sensors()`,
-:func:`~miio.device.Device.settings()`, :func:`~miio.device.Device.switches()`, and
-:func:`~miio.device.Device.buttons()` to access the functionality exposed by the integration developer.
+:func:`~miio.device.Device.settings()`, and
+:func:`~miio.device.Device.actions()` to access the functionality exposed by the integration developer.
 
-If you are developing an integration, prefer :func:`~miio.devicestatus.sensor`, :func:`~miio.devicestatus.sensor`, and
-:func:`~miio.devicestatus.sensor` decorators over creating the descriptors manually.
+If you are developing an integration, prefer :func:`~miio.devicestatus.sensor`, :func:`~miio.devicestatus.setting`, and
+:func:`~miio.devicestatus.action` decorators over creating the descriptors manually.
 If needed, you can override the methods listed to add more descriptors to your integration.
 """
 from enum import Enum, auto
@@ -17,7 +17,7 @@
 
 
 @attr.s(auto_attribs=True)
-class ButtonDescriptor:
+class ActionDescriptor:
     """Describes a button exposed by the device."""
 
     id: str

miio/device.py

@@ -5,7 +5,7 @@
 import click
 
 from .click_common import DeviceGroupMeta, LiteralParamType, command, format_output
-from .descriptors import ButtonDescriptor, SensorDescriptor, SettingDescriptor
+from .descriptors import ActionDescriptor, SensorDescriptor, SettingDescriptor
 from .deviceinfo import DeviceInfo
 from .devicestatus import DeviceStatus
 from .exceptions import DeviceInfoUnavailableException, PayloadDecodeException
@@ -241,12 +241,12 @@ def status(self) -> DeviceStatus:
         """Return device status."""
         raise NotImplementedError()
 
-    def buttons(self) -> List[ButtonDescriptor]:
-        """Return a list of button-like, clickable actions of the device."""
-        return []
+    def actions(self) -> Dict[str, ActionDescriptor]:
+        """Return device actions."""
+        return {}
 
     def settings(self) -> Dict[str, SettingDescriptor]:
-        """Return list of settings."""
+        """Return device settings."""
         settings = self.status().settings()
         for setting in settings.values():
             # TODO: Bind setter methods, this should probably done only once during init.
@@ -262,7 +262,7 @@ def settings(self) -> Dict[str, SettingDescriptor]:
         return settings
 
     def sensors(self) -> Dict[str, SensorDescriptor]:
-        """Return sensors."""
+        """Return device sensors."""
         # TODO: the latest status should be cached and re-used by all meta information getters
         sensors = self.status().sensors()
         return sensors

miio/devicestatus.py

@@ -59,7 +59,7 @@ class DeviceStatus(metaclass=_StatusMeta):
     All status container classes should inherit from this class:
 
     * This class allows downstream users to access the available information in an
-      introspectable way. See :func:`@property`, :func:`switch`, and :func:`@setting`.
+      introspectable way. See :func:`@sensor` and :func:`@setting`.
     * :func:`embed` allows embedding other status containers.
     * The __repr__ implementation returns all defined properties and their values.
     """