Deprecate legacy and undocumented template entity configurations (home-assistant#155355)

Author: Petro31

homeassistant/components/template/__init__.py

@@ -18,7 +18,7 @@
 )
 from homeassistant.core import Event, HomeAssistant, ServiceCall
 from homeassistant.exceptions import ConfigEntryError, HomeAssistantError
-from homeassistant.helpers import discovery
+from homeassistant.helpers import discovery, issue_registry as ir
 from homeassistant.helpers.device import (
     async_remove_stale_devices_links_keep_current_device,
 )
@@ -30,12 +30,21 @@
 
 from .const import CONF_MAX, CONF_MIN, CONF_STEP, DOMAIN, PLATFORMS
 from .coordinator import TriggerUpdateCoordinator
-from .helpers import async_get_blueprints
+from .helpers import DATA_DEPRECATION, async_get_blueprints
 
 _LOGGER = logging.getLogger(__name__)
 DATA_COORDINATORS: HassKey[list[TriggerUpdateCoordinator]] = HassKey(DOMAIN)
 
 
+def _clean_up_legacy_template_deprecations(hass: HomeAssistant) -> None:
+    if (found_issues := hass.data.pop(DATA_DEPRECATION, None)) is not None:
+        issue_registry = ir.async_get(hass)
+        for domain, issue_id in set(issue_registry.issues):
+            if domain != DOMAIN or issue_id in found_issues:
+                continue
+            ir.async_delete_issue(hass, DOMAIN, issue_id)
+
+
 async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     """Set up the template integration."""
 
@@ -54,6 +63,8 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
 
     async def _reload_config(call: Event | ServiceCall) -> None:
         """Reload top-level + platforms."""
+        hass.data.pop(DATA_DEPRECATION, None)
+
         await async_get_blueprints(hass).async_reset_cache()
         try:
             unprocessed_conf = await conf_util.async_hass_config_yaml(hass)
@@ -74,6 +85,7 @@ async def _reload_config(call: Event | ServiceCall) -> None:
         if DOMAIN in conf:
             await _process_config(hass, conf)
 
+        _clean_up_legacy_template_deprecations(hass)
         hass.bus.async_fire(f"event_{DOMAIN}_reloaded", context=call.context)
 
     async_register_admin_service(hass, DOMAIN, SERVICE_RELOAD, _reload_config)

homeassistant/components/template/config.py

@@ -72,7 +72,11 @@
     weather as weather_platform,
 )
 from .const import CONF_DEFAULT_ENTITY_ID, DOMAIN, PLATFORMS, TemplateConfig
-from .helpers import async_get_blueprints, rewrite_legacy_to_modern_configs
+from .helpers import (
+    async_get_blueprints,
+    create_legacy_template_issue,
+    rewrite_legacy_to_modern_configs,
+)
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -386,11 +390,11 @@ async def async_validate_config(hass: HomeAssistant, config: ConfigType) -> Conf
             definitions = (
                 list(template_config[new_key]) if new_key in template_config else []
             )
-            definitions.extend(
-                rewrite_legacy_to_modern_configs(
-                    hass, new_key, template_config[old_key], legacy_fields
-                )
-            )
+            for definition in rewrite_legacy_to_modern_configs(
+                hass, new_key, template_config[old_key], legacy_fields
+            ):
+                create_legacy_template_issue(hass, definition, new_key)
+                definitions.append(definition)
             template_config = TemplateConfig({**template_config, new_key: definitions})
 
         config_sections.append(template_config)

homeassistant/components/template/helpers.py

@@ -1,6 +1,8 @@
 """Helpers for template integration."""
 
 from collections.abc import Callable
+from enum import Enum
+import hashlib
 import itertools
 import logging
 from typing import Any
@@ -22,15 +24,18 @@
 )
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.exceptions import PlatformNotReady
-from homeassistant.helpers import template
+from homeassistant.helpers import issue_registry as ir, template
 from homeassistant.helpers.entity import Entity
 from homeassistant.helpers.entity_platform import (
     AddConfigEntryEntitiesCallback,
     AddEntitiesCallback,
     async_get_platforms,
 )
+from homeassistant.helpers.issue_registry import IssueSeverity
 from homeassistant.helpers.singleton import singleton
 from homeassistant.helpers.typing import ConfigType, DiscoveryInfoType
+from homeassistant.util import yaml as yaml_util
+from homeassistant.util.hass_dict import HassKey
 
 from .const import (
     CONF_ADVANCED_OPTIONS,
@@ -46,7 +51,10 @@
 from .template_entity import TemplateEntity
 from .trigger_entity import TriggerEntity
 
+LEGACY_TEMPLATE_DEPRECATION_KEY = "deprecate_legacy_templates"
+
 DATA_BLUEPRINTS = "template_blueprints"
+DATA_DEPRECATION: HassKey[list[str]] = HassKey(LEGACY_TEMPLATE_DEPRECATION_KEY)
 
 LEGACY_FIELDS = {
     CONF_ICON_TEMPLATE: CONF_ICON,
@@ -180,6 +188,95 @@ def async_create_template_tracking_entities(
     async_add_entities(entities)
 
 
+def _format_template(value: Any) -> Any:
+    if isinstance(value, template.Template):
+        return value.template
+
+    if isinstance(value, Enum):
+        return value.name
+
+    if isinstance(value, (int, float, str, bool)):
+        return value
+
+    return str(value)
+
+
+def format_migration_config(
+    config: ConfigType | list[ConfigType], depth: int = 0
+) -> ConfigType | list[ConfigType]:
+    """Recursive method to format templates as strings from ConfigType."""
+    types = (dict, list)
+    if depth > 9:
+        raise RecursionError
+
+    if isinstance(config, list):
+        items = []
+        for item in config:
+            if isinstance(item, types):
+                if len(item) > 0:
+                    items.append(format_migration_config(item, depth + 1))
+            else:
+                items.append(_format_template(item))
+        return items  # type: ignore[return-value]
+
+    formatted_config = {}
+    for field, value in config.items():
+        if isinstance(value, types):
+            if len(value) > 0:
+                formatted_config[field] = format_migration_config(value, depth + 1)
+        else:
+            formatted_config[field] = _format_template(value)
+
+    return formatted_config
+
+
+def create_legacy_template_issue(
+    hass: HomeAssistant, config: ConfigType, domain: str
+) -> None:
+    """Create a repair for legacy template entities."""
+
+    breadcrumb = "Template Entity"
+    # Default entity id should be in most legacy configuration because
+    # it's created from the legacy slug. Vacuum and Lock do not have a
+    # slug, therefore we need to use the name or unique_id.
+    if (default_entity_id := config.get(CONF_DEFAULT_ENTITY_ID)) is not None:
+        breadcrumb = default_entity_id.split(".")[-1]
+    elif (unique_id := config.get(CONF_UNIQUE_ID)) is not None:
+        breadcrumb = f"unique_id: {unique_id}"
+    elif (name := config.get(CONF_NAME)) and isinstance(name, template.Template):
+        breadcrumb = name.template
+
+    issue_id = f"{LEGACY_TEMPLATE_DEPRECATION_KEY}_{domain}_{breadcrumb}_{hashlib.md5(','.join(config.keys()).encode()).hexdigest()}"
+
+    if (deprecation_list := hass.data.get(DATA_DEPRECATION)) is None:
+        hass.data[DATA_DEPRECATION] = deprecation_list = []
+
+    deprecation_list.append(issue_id)
+
+    try:
+        modified_yaml = format_migration_config(config)
+        yaml_config = yaml_util.dump({DOMAIN: [{domain: [modified_yaml]}]})
+        # Format to show up properly in a numbered bullet on the repair.
+        yaml_config = "    ```\n    " + yaml_config.replace("\n", "\n    ") + "```"
+    except RecursionError:
+        yaml_config = f"{DOMAIN}:\n  - {domain}:      - ..."
+
+    ir.async_create_issue(
+        hass,
+        DOMAIN,
+        issue_id,
+        breaks_in_ha_version="2026.6",
+        is_fixable=False,
+        severity=IssueSeverity.WARNING,
+        translation_key="deprecated_legacy_templates",
+        translation_placeholders={
+            "domain": domain,
+            "breadcrumb": breadcrumb,
+            "config": yaml_config,
+        },
+    )
+
+
 async def async_setup_template_platform(
     hass: HomeAssistant,
     domain: str,
@@ -201,6 +298,10 @@ async def async_setup_template_platform(
                 )
             else:
                 configs = [rewrite_legacy_to_modern_config(hass, config, legacy_fields)]
+
+            for definition in configs:
+                create_legacy_template_issue(hass, definition, domain)
+
             async_create_template_tracking_entities(
                 state_entity_cls,
                 async_add_entities,

homeassistant/components/template/strings.json

@@ -527,6 +527,10 @@
     "deprecated_battery_level": {
       "description": "The template vacuum options `battery_level` and `battery_level_template` are being removed in 2026.8.\n\nPlease remove the `battery_level` or `battery_level_template` option from the YAML configuration for {entity_id} ({entity_name}).",
       "title": "Deprecated battery level option in {entity_name}"
+    },
+    "deprecated_legacy_templates": {
+      "description": "The legacy `platform: template` syntax for `{domain}` is being removed. Please migrate `{breadcrumb}` to the modern template syntax.\n\n1. Remove existing template definition.\n2. Add new template definition:\n{config}\n3. Restart Home Assistant or reload template entities.",
+      "title": "Legacy {domain} template deprecation"
     }
   },
   "options": {

tests/components/template/fixtures/legacy_template_deprecation.yaml

@@ -0,0 +1,11 @@
+sensor:
+  - platform: template
+    sensors:
+      state:
+        value_template: "{{ states.sensor.test_sensor.state }}"
+template:
+  - sensor:
+      - default_entity_id: sensor.state2
+        state: "{{ states.sensor.test_sensor.state }}"
+      - default_entity_id: sensor.state3
+        state: "{{ states.sensor.test_sensor.state }}"