miio.descriptors module

This module contains descriptors.

The descriptors contain information that can be used to provide generic, dynamic user-interfaces.

If you are a downstream developer, use properties(), actions() to access the functionality exposed by the integration developer.

If you are developing an integration, prefer sensor(), setting(), and action() decorators over creating the descriptors manually.

class miio.descriptors.AccessFlags(value)[source]

Bases: Flag

Defines the access rights for the property behind the descriptor.

Execute = 4

Read = 1

Write = 2

class miio.descriptors.ActionDescriptor(id: str, name: str, type: None = None, unit: str | None = None, status_attribute: str | None = None, extras: Dict = _Nothing.NOTHING, method: Callable | None = None, method_name: str | None = None, inputs: List[Any] | None = None, access: AccessFlags = AccessFlags.Execute)[source]

Bases: Descriptor

Describes a button exposed by the device.

access: AccessFlags: Access flags (read, write, execute) for the described item.

extras: Dict: Additional data related to this descriptor.

id: str: Unique identifier.

inputs: List[Any] | None

method: Callable | None

method_name: str | None: Name of the method in the device class that can be used to execute the action.

name: str: Human readable name.

status_attribute: str | None: Name of the attribute in the status container that contains the value, if applicable.

type: type | None: Type of the property, if applicable.

unit: str | None: Unit of the property, if applicable.

class miio.descriptors.Descriptor(id: str, name: str, type: None = None, unit: str | None = None, status_attribute: str | None = None, extras: ~typing.Dict = _Nothing.NOTHING, access: ~miio.descriptors.AccessFlags = AccessFlags.None)[source]

Bases: object

Base class for all descriptors.

access: AccessFlags: Access flags (read, write, execute) for the described item.

extras: Dict: Additional data related to this descriptor.

id: str: Unique identifier.

name: str: Human readable name.

status_attribute: str | None: Name of the attribute in the status container that contains the value, if applicable.

type: None: Type of the property, if applicable.

unit: str | None: Unit of the property, if applicable.

class miio.descriptors.EnumDescriptor(*, id: str, name: str, type: None = None, unit: str | None = None, extras: Dict = _Nothing.NOTHING, status_attribute: str, access: AccessFlags = AccessFlags.Read, setter: Callable | None = None, setter_name: str | None = None, constraint: PropertyConstraint = PropertyConstraint.Choice, choices_attribute: str | None = None, choices: Type[Enum] | None = None)[source]

Bases: PropertyDescriptor

Presents a settable, enum-based value.

access: AccessFlags: Sensors are read-only and settings are (usually) read-write.

choices: Type[Enum] | None: Enum class containing the available choices.

choices_attribute: str | None: Name of the attribute in the device class that returns the choices.

constraint: PropertyConstraint: Constraint type defining the allowed values for an integer property.

extras: Dict: Additional data related to this descriptor.

id: str: Unique identifier.

name: str: Human readable name.

setter: Callable | None: Callable to set the value of the property.

setter_name: str | None: Name of the method in the device class that can be used to set the value. If set, the callable with this name will override the setter attribute.

status_attribute: str: Name of the attribute in the status container that contains the value.

type: type | None: Type of the property, if applicable.

unit: str | None: Unit of the property, if applicable.

class miio.descriptors.PropertyConstraint(value)[source]

Bases: Enum

Defines constraints for integer based properties.

Choice = 3

Range = 2

Unset = 1

class miio.descriptors.PropertyDescriptor(*, id: str, name: str, type: None = None, unit: str | None = None, extras: Dict = _Nothing.NOTHING, status_attribute: str, access: AccessFlags = AccessFlags.Read, constraint: PropertyConstraint = PropertyConstraint.Unset, setter: Callable | None = None, setter_name: str | None = None)[source]

Bases: Descriptor

Describes a property exposed by the device.

This information can be used by library users to programmatically access information what types of data is available to display to users.

Prefer @sensor or: @setting for constructing these.

access: AccessFlags: Sensors are read-only and settings are (usually) read-write.

constraint: PropertyConstraint: Constraint type defining the allowed values for an integer property.

extras: Dict: Additional data related to this descriptor.

id: str: Unique identifier.

name: str: Human readable name.

setter: Callable | None: Callable to set the value of the property.

setter_name: str | None: Name of the method in the device class that can be used to set the value. If set, the callable with this name will override the setter attribute.

status_attribute: str: Name of the attribute in the status container that contains the value.

type: type | None: Type of the property, if applicable.

unit: str | None: Unit of the property, if applicable.

class miio.descriptors.RangeDescriptor(*, id: str, name: str, unit: str | None = None, extras: ~typing.Dict = _Nothing.NOTHING, status_attribute: str, access: ~miio.descriptors.AccessFlags = AccessFlags.Read, setter: ~typing.Callable | None = None, setter_name: str | None = None, min_value: int, max_value: int, step: int, range_attribute: str | None = None, type: int = <class 'int'>, constraint: ~miio.descriptors.PropertyConstraint = PropertyConstraint.Range)[source]

Bases: PropertyDescriptor

Presents a settable, numerical value constrained by min, max, and step.

If range_attribute is set, the named property that should return a ValidSettingRange object to override the {min,max}_value and step values.

access: AccessFlags: Sensors are read-only and settings are (usually) read-write.

constraint: PropertyConstraint: Constraint type defining the allowed values for an integer property.

extras: Dict: Additional data related to this descriptor.

id: str: Unique identifier.

max_value: int: Maximum value for the property.

min_value: int: Minimum value for the property.

name: str: Human readable name.

range_attribute: str | None: Name of the attribute in the device class that returns the range. If set, this will override the individual min/max/step values.

setter: Callable | None: Callable to set the value of the property.

setter_name: str | None: Name of the method in the device class that can be used to set the value. If set, the callable with this name will override the setter attribute.

status_attribute: str: Name of the attribute in the status container that contains the value.

step: int: Step size for the property.

type: int: Type of the property, if applicable.

unit: str | None: Unit of the property, if applicable.

class miio.descriptors.ValidSettingRange(min_value: int, max_value: int, step: int = 1)[source]

Bases: object

Describes a valid input range for a property.

max_value: int

min_value: int

step: int