Add label support

homeassistant/bootstrap.py

@@ -32,6 +32,7 @@
     entity,
     entity_registry,
     issue_registry,
+    label_registry,
     recorder,
     restore_state,
     template,
@@ -298,6 +299,7 @@ def _cache_uname_processor() -> None:
         device_registry.async_load(hass),
         entity_registry.async_load(hass),
         issue_registry.async_load(hass),
+        label_registry.async_load(hass),
         hass.async_add_executor_job(_cache_uname_processor),
         template.async_load_custom_templates(hass),
         restore_state.async_load(hass),

homeassistant/components/config/__init__.py

@@ -35,6 +35,7 @@
     "core",
     "device_registry",
     "entity_registry",
+    "label_registry",
     "script",
     "scene",
 )

homeassistant/components/config/label_registry.py

@@ -0,0 +1,128 @@
+"""Websocket API to interact with the label registry."""
+from typing import Any
+
+import voluptuous as vol
+
+from homeassistant.components import websocket_api
+from homeassistant.components.websocket_api.connection import ActiveConnection
+from homeassistant.core import HomeAssistant, callback
+from homeassistant.helpers.label_registry import LabelEntry, async_get
+
+
+async def async_setup(hass: HomeAssistant) -> bool:
+    """Register the Label Registry WS commands."""
+    websocket_api.async_register_command(hass, websocket_list_labels)
+    websocket_api.async_register_command(hass, websocket_create_label)
+    websocket_api.async_register_command(hass, websocket_delete_label)
+    websocket_api.async_register_command(hass, websocket_update_label)
+    return True
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "config/label_registry/list",
+    }
+)
+@callback
+def websocket_list_labels(
+    hass: HomeAssistant, connection: ActiveConnection, msg: dict[str, Any]
+) -> None:
+    """Handle list labels command."""
+    registry = async_get(hass)
+    connection.send_result(
+        msg["id"],
+        [_entry_dict(entry) for entry in registry.async_list_labels()],
+    )
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "config/label_registry/create",
+        vol.Required("name"): str,
+        vol.Optional("color"): vol.Any(str, None),
+        vol.Optional("description"): vol.Any(str, None),
+        vol.Optional("icon"): vol.Any(str, None),
+    }
+)
+@websocket_api.require_admin
+@callback
+def websocket_create_label(
+    hass: HomeAssistant, connection: ActiveConnection, msg: dict[str, Any]
+) -> None:
+    """Create label command."""
+    registry = async_get(hass)
+
+    data = dict(msg)
+    data.pop("type")
+    data.pop("id")
+
+    try:
+        entry = registry.async_create(**data)
+    except ValueError as err:
+        connection.send_error(msg["id"], "invalid_info", str(err))
+    else:
+        connection.send_result(msg["id"], _entry_dict(entry))
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "config/label_registry/delete",
+        vol.Required("label_id"): str,
+    }
+)
+@websocket_api.require_admin
+@callback
+def websocket_delete_label(
+    hass: HomeAssistant, connection: ActiveConnection, msg: dict[str, Any]
+) -> None:
+    """Delete label command."""
+    registry = async_get(hass)
+
+    try:
+        registry.async_delete(msg["label_id"])
+    except KeyError:
+        connection.send_error(msg["id"], "invalid_info", "Label ID doesn't exist")
+    else:
+        connection.send_message(websocket_api.result_message(msg["id"], "success"))
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "config/label_registry/update",
+        vol.Required("label_id"): str,
+        vol.Optional("color"): vol.Any(str, None),
+        vol.Optional("description"): vol.Any(str, None),
+        vol.Optional("icon"): vol.Any(str, None),
+        vol.Optional("name"): str,
+    }
+)
+@websocket_api.require_admin
+@callback
+def websocket_update_label(
+    hass: HomeAssistant, connection: ActiveConnection, msg: dict[str, Any]
+) -> None:
+    """Handle update label websocket command."""
+    registry = async_get(hass)
+
+    data = dict(msg)
+    data.pop("type")
+    data.pop("id")
+
+    try:
+        entry = registry.async_update(**data)
+    except ValueError as err:
+        connection.send_error(msg["id"], "invalid_info", str(err))
+    else:
+        connection.send_result(msg["id"], _entry_dict(entry))
+
+
+@callback
+def _entry_dict(entry: LabelEntry) -> dict[str, Any]:
+    """Convert entry to API format."""
+    return {
+        "color": entry.color,
+        "description": entry.description,
+        "icon": entry.icon,
+        "label_id": entry.label_id,
+        "name": entry.name,
+    }

homeassistant/const.py

@@ -509,6 +509,10 @@ class Platform(StrEnum):
 # Contains one string, the device ID
 ATTR_DEVICE_ID: Final = "device_id"
 
+# Label identifier. Also used as service calls target parameter in which case
+# it contains one string or a list of strings, each being an label id.
+ATTR_LABEL_ID: Final = "label_id"
+
 # String with a friendly name for the entity
 ATTR_FRIENDLY_NAME: Final = "friendly_name"
 

homeassistant/helpers/config_validation.py

@@ -29,6 +29,7 @@
     ATTR_AREA_ID,
     ATTR_DEVICE_ID,
     ATTR_ENTITY_ID,
+    ATTR_LABEL_ID,
     CONF_ABOVE,
     CONF_ALIAS,
     CONF_ATTRIBUTE,
@@ -1229,6 +1230,9 @@ def platform_only_config_schema(domain: str) -> Callable[[dict], dict]:
     vol.Optional(ATTR_AREA_ID): vol.Any(
         ENTITY_MATCH_NONE, vol.All(ensure_list, [vol.Any(dynamic_template, str)])
     ),
+    vol.Optional(ATTR_LABEL_ID): vol.Any(
+        ENTITY_MATCH_NONE, vol.All(ensure_list, [vol.Any(dynamic_template, str)])
+    ),
 }
 
 TARGET_SERVICE_FIELDS = {
@@ -1246,6 +1250,9 @@ def platform_only_config_schema(domain: str) -> Callable[[dict], dict]:
     vol.Optional(ATTR_AREA_ID): vol.Any(
         ENTITY_MATCH_NONE, vol.All(ensure_list, [vol.Any(dynamic_template, str)])
     ),
+    vol.Optional(ATTR_LABEL_ID): vol.Any(
+        ENTITY_MATCH_NONE, vol.All(ensure_list, [vol.Any(dynamic_template, str)])
+    ),
 }
 
 

homeassistant/helpers/device_registry.py

@@ -43,7 +43,7 @@
 EVENT_DEVICE_REGISTRY_UPDATED = "device_registry_updated"
 STORAGE_KEY = "core.device_registry"
 STORAGE_VERSION_MAJOR = 1
-STORAGE_VERSION_MINOR = 4
+STORAGE_VERSION_MINOR = 5
 SAVE_DELAY = 10
 CLEANUP_DELAY = 10
 
@@ -238,6 +238,7 @@ class DeviceEntry:
     hw_version: str | None = attr.ib(default=None)
     id: str = attr.ib(factory=uuid_util.random_uuid_hex)
     identifiers: set[tuple[str, str]] = attr.ib(converter=set, factory=set)
+    labels: set[str] = attr.ib(converter=set, factory=set)
     manufacturer: str | None = attr.ib(default=None)
     model: str | None = attr.ib(default=None)
     name_by_user: str | None = attr.ib(default=None)
@@ -378,6 +379,10 @@ async def _async_migrate_func(
                 # Introduced in 2023.11
                 for device in old_data["devices"]:
                     device["serial_number"] = None
+            if old_minor_version < 5:
+                # Introduced in 2024.3
+                for device in old_data["devices"]:
+                    device["labels"] = device.get("labels", [])
 
         if old_major_version > 1:
             raise NotImplementedError
@@ -634,6 +639,7 @@ def async_update_device(
         disabled_by: DeviceEntryDisabler | None | UndefinedType = UNDEFINED,
         entry_type: DeviceEntryType | None | UndefinedType = UNDEFINED,
         hw_version: str | None | UndefinedType = UNDEFINED,
+        labels: set[str] | UndefinedType = UNDEFINED,
         manufacturer: str | None | UndefinedType = UNDEFINED,
         merge_connections: set[tuple[str, str]] | UndefinedType = UNDEFINED,
         merge_identifiers: set[tuple[str, str]] | UndefinedType = UNDEFINED,
@@ -728,11 +734,12 @@ def async_update_device(
             ("disabled_by", disabled_by),
             ("entry_type", entry_type),
             ("hw_version", hw_version),
+            ("labels", labels),
             ("manufacturer", manufacturer),
             ("model", model),
-            ("name", name),
             ("name_by_user", name_by_user),
             ("serial_number", serial_number),
+            ("name", name),
             ("suggested_area", suggested_area),
             ("sw_version", sw_version),
             ("via_device_id", via_device_id),
@@ -822,6 +829,7 @@ async def async_load(self) -> None:
                         tuple(iden)  # type: ignore[misc]
                         for iden in device["identifiers"]
                     },
+                    labels=set(device["labels"]),
                     manufacturer=device["manufacturer"],
                     model=device["model"],
                     name_by_user=device["name_by_user"],
@@ -865,6 +873,7 @@ def _data_to_save(self) -> dict[str, list[dict[str, Any]]]:
                 "hw_version": entry.hw_version,
                 "id": entry.id,
                 "identifiers": list(entry.identifiers),
+                "labels": list(entry.labels),
                 "manufacturer": entry.manufacturer,
                 "model": entry.model,
                 "name_by_user": entry.name_by_user,
@@ -937,6 +946,15 @@ def async_clear_area_id(self, area_id: str) -> None:
             if area_id == device.area_id:
                 self.async_update_device(dev_id, area_id=None)
 
+    @callback
+    def async_clear_label_id(self, label_id: str) -> None:
+        """Clear label from registry entries."""
+        for device_id, entry in self.devices.items():
+            if label_id in entry.labels:
+                labels = entry.labels.copy()
+                labels.remove(label_id)
+                self.async_update_device(device_id, labels=labels)
+
 
 @callback
 def async_get(hass: HomeAssistant) -> DeviceRegistry:
@@ -957,6 +975,14 @@ def async_entries_for_area(registry: DeviceRegistry, area_id: str) -> list[Devic
     return [device for device in registry.devices.values() if device.area_id == area_id]
 
 
+@callback
+def async_entries_for_label(
+    registry: DeviceRegistry, label_id: str
+) -> list[DeviceEntry]:
+    """Return entries that match an label."""
+    return [device for device in registry.devices.values() if label_id in device.labels]
+
+
 @callback
 def async_entries_for_config_entry(
     registry: DeviceRegistry, config_entry_id: str