Add label_description to template engine (#147138)

Co-authored-by: Abílio Costa <abmantis@users.noreply.github.com>

homeassistant/helpers/template.py

@@ -1734,6 +1734,14 @@ def label_name(hass: HomeAssistant, lookup_value: str) -> str | None:
     return None
 
 
+def label_description(hass: HomeAssistant, lookup_value: str) -> str | None:
+    """Get the label description from a label ID."""
+    label_reg = label_registry.async_get(hass)
+    if label := label_reg.async_get_label(lookup_value):
+        return label.description
+    return None
+
+
 def _label_id_or_name(hass: HomeAssistant, label_id_or_name: str) -> str | None:
     """Get the label ID from a label name or ID."""
     # If label_name returns a value, we know the input was an ID, otherwise we
@@ -3314,6 +3322,9 @@ class TemplateEnvironment(ImmutableSandboxedEnvironment):
         self.globals["label_name"] = hassfunction(label_name)
         self.filters["label_name"] = self.globals["label_name"]
 
+        self.globals["label_description"] = hassfunction(label_description)
+        self.filters["label_description"] = self.globals["label_description"]
+
         self.globals["label_areas"] = hassfunction(label_areas)
         self.filters["label_areas"] = self.globals["label_areas"]
 

tests/helpers/test_template.py

@@ -6295,6 +6295,40 @@ async def test_label_name(
     assert info.rate_limit is None
 
 
+async def test_label_description(
+    hass: HomeAssistant,
+    label_registry: lr.LabelRegistry,
+) -> None:
+    """Test label_description function."""
+    # Test non existing label ID
+    info = render_to_info(hass, "{{ label_description('1234567890') }}")
+    assert_result_info(info, None)
+    assert info.rate_limit is None
+
+    info = render_to_info(hass, "{{ '1234567890' | label_description }}")
+    assert_result_info(info, None)
+    assert info.rate_limit is None
+
+    # Test wrong value type
+    info = render_to_info(hass, "{{ label_description(42) }}")
+    assert_result_info(info, None)
+    assert info.rate_limit is None
+
+    info = render_to_info(hass, "{{ 42 | label_description }}")
+    assert_result_info(info, None)
+    assert info.rate_limit is None
+
+    # Test valid label ID
+    label = label_registry.async_create("choo choo", description="chugga chugga")
+    info = render_to_info(hass, f"{{{{ label_description('{label.label_id}') }}}}")
+    assert_result_info(info, label.description)
+    assert info.rate_limit is None
+
+    info = render_to_info(hass, f"{{{{ '{label.label_id}' | label_description }}}}")
+    assert_result_info(info, label.description)
+    assert info.rate_limit is None
+
+
 async def test_label_entities(
     hass: HomeAssistant,
     entity_registry: er.EntityRegistry,