From e494f66c0275ed01b99dccebd4dfbb46237f7558 Mon Sep 17 00:00:00 2001
From: Petro31 <35082313+Petro31@users.noreply.github.com>
Date: Mon, 23 Jun 2025 14:21:29 -0400
Subject: [PATCH] Add label_description to template engine (#147138)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Abílio Costa <abmantis@users.noreply.github.com>
---
 homeassistant/helpers/template.py | 11 ++++++++++
 tests/helpers/test_template.py    | 34 +++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/homeassistant/helpers/template.py b/homeassistant/helpers/template.py
index acf78f70380..34b19c07f83 100644
--- a/homeassistant/helpers/template.py
+++ b/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"]
 
diff --git a/tests/helpers/test_template.py b/tests/helpers/test_template.py
index 8e6e7643df3..15c6a4b7251 100644
--- a/tests/helpers/test_template.py
+++ b/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,