From 5b4dd0718969f3f3ee4d6dd133d7050dcc1643f9 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Fri, 19 Jul 2024 10:10:38 +0200 Subject: [PATCH] Deprecate `topic_template` and `payload_template` for mqtt publish action (#122098) Co-authored-by: Franck Nijhof --- homeassistant/components/mqtt/__init__.py | 39 ++++++++++++++++- homeassistant/components/mqtt/services.yaml | 8 +--- homeassistant/components/mqtt/strings.json | 8 ++++ tests/components/mqtt/test_init.py | 48 ++++++++++++++------- 4 files changed, 80 insertions(+), 23 deletions(-) diff --git a/homeassistant/components/mqtt/__init__.py b/homeassistant/components/mqtt/__init__.py index f057dab8bc4..ed87a99386b 100644 --- a/homeassistant/components/mqtt/__init__.py +++ b/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() diff --git a/homeassistant/components/mqtt/services.yaml b/homeassistant/components/mqtt/services.yaml index 5102d481143..ee5e4ff56e8 100644 --- a/homeassistant/components/mqtt/services.yaml +++ b/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: diff --git a/homeassistant/components/mqtt/strings.json b/homeassistant/components/mqtt/strings.json index f1e740d7f35..93131376154 100644 --- a/homeassistant/components/mqtt/strings.json +++ b/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": { diff --git a/tests/components/mqtt/test_init.py b/tests/components/mqtt/test_init.py index 403f7974878..51379dc8508 100644 --- a/tests/components/mqtt/test_init.py +++ b/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'}"