Deprecate topic_template and payload_template for mqtt publish action (#122098)

Co-authored-by: Franck Nijhof <git@frenck.dev>

homeassistant/components/mqtt/__init__.py

@@ -155,7 +155,10 @@ CONFIG_SCHEMA = vol.Schema(
 )
 
 
-# Service call validation schema
+# The use of a topic_template and payload_template in an mqtt publish action call
+# have been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
+
+# Publish action call validation schema
 MQTT_PUBLISH_SCHEMA = vol.All(
     vol.Schema(
         {
@@ -296,10 +299,26 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         qos: int = call.data[ATTR_QOS]
         retain: bool = call.data[ATTR_RETAIN]
         if msg_topic_template is not None:
+            # The use of a topic_template in an mqtt publish action call
+            # has been deprecated with HA Core 2024.8.0
+            # and will be removed with HA Core 2025.2.0
             rendered_topic: Any = MqttCommandTemplate(
                 template.Template(msg_topic_template),
                 hass=hass,
             ).async_render()
+            ir.async_create_issue(
+                hass,
+                DOMAIN,
+                f"topic_template_deprecation_{rendered_topic}",
+                breaks_in_ha_version="2025.2.0",
+                is_fixable=False,
+                severity=ir.IssueSeverity.WARNING,
+                translation_key="topic_template_deprecation",
+                translation_placeholders={
+                    "topic_template": msg_topic_template,
+                    "topic": rendered_topic,
+                },
+            )
             try:
                 msg_topic = valid_publish_topic(rendered_topic)
             except vol.Invalid as err:
@@ -315,6 +334,24 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
                 ) from err
 
         if payload_template is not None:
+            # The use of a payload_template in an mqtt publish action call
+            # has been deprecated with HA Core 2024.8.0
+            # and will be removed with HA Core 2025.2.0
+            if TYPE_CHECKING:
+                assert msg_topic is not None
+            ir.async_create_issue(
+                hass,
+                DOMAIN,
+                f"payload_template_deprecation_{msg_topic}",
+                breaks_in_ha_version="2025.2.0",
+                is_fixable=False,
+                severity=ir.IssueSeverity.WARNING,
+                translation_key="payload_template_deprecation",
+                translation_placeholders={
+                    "topic": msg_topic,
+                    "payload_template": payload_template,
+                },
+            )
             payload = MqttCommandTemplate(
                 template.Template(payload_template), hass=hass
             ).async_render()

homeassistant/components/mqtt/services.yaml

@@ -8,12 +8,8 @@ publish:
       selector:
         text:
     payload:
-      example: This is great
-      selector:
-        text:
-    payload_template:
-      advanced: true
-      example: "{{ states('sensor.temperature') }}"
+      required: true
+      example: "The temperature is {{ states('sensor.temperature') }}"
       selector:
         template:
     qos:

homeassistant/components/mqtt/strings.json

@@ -11,6 +11,14 @@
     "invalid_platform_config": {
       "title": "Invalid config found for mqtt {domain} item",
       "description": "Home Assistant detected an invalid config for a manually configured item.\n\nPlatform domain: **{domain}**\nConfiguration file: **{config_file}**\nNear line: **{line}**\nConfiguration found:\n```yaml\n{config}\n```\nError: **{error}**.\n\nMake sure the configuration is valid and [reload](/developer-tools/yaml) the manually configured MQTT items or restart Home Assistant to fix this issue."
+    },
+    "payload_template_deprecation": {
+      "title": "Deprecated option used in mqtt publish action call",
+      "description": "Deprecated `payload_template` option used in MQTT publish action call to topic `{topic}` from payload template `{payload_template}`. Use the `payload` option instead. In automations templates are supported natively. Update the automation or script to use the `payload` option instead and restart Home Assistant to fix this issue."
+    },
+    "topic_template_deprecation": {
+      "title": "Deprecated option used in mqtt publish action call",
+      "description": "Deprecated `topic_template` option used in MQTT publish action call to topic `{topic}` from topic template `{topic_template}`. Use the `topic` option instead. In automations templates are supported natively. Update the automation or script to use the `topic` option instead and restart Home Assistant to fix this issue."
     }
   },
   "config": {

tests/components/mqtt/test_init.py

@@ -260,10 +260,12 @@ async def test_service_call_without_topic_does_not_publish(
     assert not mqtt_mock.async_publish.called
 
 
-async def test_service_call_with_topic_and_topic_template_does_not_publish(
+# The use of a topic_template in an mqtt publish action call
+# has been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
+async def test_mqtt_publish_action_call_with_topic_and_topic_template_does_not_publish(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the service call with topic/topic template.
+    """Test the mqtt publish action call with topic/topic template.
 
     If both 'topic' and 'topic_template' are provided then fail.
     """
@@ -284,10 +286,12 @@ async def test_service_call_with_topic_and_topic_template_does_not_publish(
     assert not mqtt_mock.async_publish.called
 
 
-async def test_service_call_with_invalid_topic_template_does_not_publish(
+# The use of a topic_template in an mqtt publish action call
+# has been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
+async def test_mqtt_action_call_with_invalid_topic_template_does_not_publish(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the service call with a problematic topic template."""
+    """Test the mqtt publish action call with a problematic topic template."""
     mqtt_mock = await mqtt_mock_entry()
     with pytest.raises(MqttCommandTemplateException) as exc:
         await hass.services.async_call(
@@ -307,10 +311,12 @@ async def test_service_call_with_invalid_topic_template_does_not_publish(
     assert not mqtt_mock.async_publish.called
 
 
-async def test_service_call_with_template_topic_renders_template(
+# The use of a topic_template in an mqtt publish action call
+# has been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
+async def test_mqtt_publish_action_call_with_template_topic_renders_template(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the service call with rendered topic template.
+    """Test the mqtt publish action call with rendered topic template.
 
     If 'topic_template' is provided and 'topic' is not, then render it.
     """
@@ -331,7 +337,7 @@ async def test_service_call_with_template_topic_renders_template(
 async def test_service_call_with_template_topic_renders_invalid_topic(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the service call with rendered, invalid topic template.
+    """Test the action call with rendered, invalid topic template.
 
     If a wildcard topic is rendered, then fail.
     """
@@ -354,10 +360,12 @@ async def test_service_call_with_template_topic_renders_invalid_topic(
     assert not mqtt_mock.async_publish.called
 
 
-async def test_service_call_with_invalid_rendered_template_topic_doesnt_render_template(
+# The use of a payload_template in an mqtt publish action call
+# has been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
+async def test_action_call_with_invalid_rendered_payload_template_doesnt_render_template(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the service call with unrendered template.
+    """Test the action call with unrendered payload template.
 
     If both 'payload' and 'payload_template' are provided then fail.
     """
@@ -378,10 +386,12 @@ async def test_service_call_with_invalid_rendered_template_topic_doesnt_render_t
     assert not mqtt_mock.async_publish.called
 
 
-async def test_service_call_with_template_payload_renders_template(
+# The use of a payload_template in an mqtt publish action call
+# has been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
+async def test_mqtt_publish_action_call_with_template_payload_renders_template(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the service call with rendered template.
+    """Test the mqtt publish action call with rendered template.
 
     If 'payload_template' is provided and 'payload' is not, then render it.
     """
@@ -410,10 +420,12 @@ async def test_service_call_with_template_payload_renders_template(
     mqtt_mock.reset_mock()
 
 
-async def test_service_call_with_bad_template(
+# The use of a payload_template in an mqtt publish action call
+# has been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
+async def test_publish_action_call_with_bad_payload_template(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the service call with a bad template does not publish."""
+    """Test the mqtt publish action call with a bad template does not publish."""
     mqtt_mock = await mqtt_mock_entry()
     with pytest.raises(MqttCommandTemplateException) as exc:
         await hass.services.async_call(
@@ -432,10 +444,12 @@ async def test_service_call_with_bad_template(
     )
 
 
-async def test_service_call_with_payload_doesnt_render_template(
+# The use of a payload_template in an mqtt publish action call
+# has been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
+async def test_action_call_with_payload_doesnt_render_template(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the service call with unrendered template.
+    """Test the mqtt publish action call with an unrendered template.
 
     If both 'payload' and 'payload_template' are provided then fail.
     """
@@ -1626,10 +1640,12 @@ async def test_debug_info_qos_retain(
     } in messages
 
 
+# The use of a payload_template in an mqtt publish action call
+# has been deprecated with HA Core 2024.8.0 and will be removed with HA Core 2025.2.0
 async def test_publish_json_from_template(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
-    """Test the publishing of call to services."""
+    """Test the publishing of call to mqtt publish action."""
     mqtt_mock = await mqtt_mock_entry()
 
     test_str = "{'valid': 'python', 'invalid': 'json'}"