Add description placeholders to service translation strings (home-assistant#154984)

Co-authored-by: Erik Montnemery <[email protected]>

Author: jbouwh

homeassistant/components/kitchen_sink/__init__.py

@@ -31,7 +31,7 @@
     UnitOfTemperature,
     UnitOfVolume,
 )
-from homeassistant.core import HomeAssistant, ServiceCall, callback
+from homeassistant.core import HomeAssistant, ServiceCall, ServiceResponse, callback
 from homeassistant.helpers import config_validation as cv
 from homeassistant.helpers.device_registry import DeviceEntry
 from homeassistant.helpers.issue_registry import (
@@ -81,11 +81,22 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     )
 
     @callback
-    def service_handler(call: ServiceCall | None = None) -> None:
+    def service_handler(call: ServiceCall | None = None) -> ServiceResponse:
         """Do nothing."""
+        return None
 
     hass.services.async_register(
-        DOMAIN, "test_service_1", service_handler, SCHEMA_SERVICE_TEST_SERVICE_1
+        DOMAIN,
+        "test_service_1",
+        service_handler,
+        SCHEMA_SERVICE_TEST_SERVICE_1,
+        description_placeholders={
+            "meep_1": "foo",
+            "meep_2": "bar",
+            "meep_3": "beer",
+            "meep_4": "milk",
+            "meep_5": "https://example.com",
+        },
     )
 
     return True

homeassistant/components/kitchen_sink/strings.json

@@ -117,14 +117,16 @@
   },
   "services": {
     "test_service_1": {
-      "description": "Fake action for testing",
+      "description": "Fake action for testing {meep_2}",
       "fields": {
         "field_1": {
-          "description": "Number of seconds",
-          "name": "Field 1"
+          "description": "Number of seconds {meep_4}",
+          "example": "Example: {meep_5}",
+          "name": "Field 1 {meep_3}"
         },
         "field_2": {
           "description": "Mode",
+          "example": "Field 2 example",
           "name": "Field 2"
         },
         "field_3": {
@@ -136,7 +138,7 @@
           "name": "Field 4"
         }
       },
-      "name": "Test action 1",
+      "name": "Test action {meep_1}",
       "sections": {
         "advanced_fields": {
           "description": "Some very advanced things",

homeassistant/core.py

@@ -2426,7 +2426,14 @@ class SupportsResponse(enum.StrEnum):
 class Service:
     """Representation of a callable service."""
 
-    __slots__ = ["domain", "job", "schema", "service", "supports_response"]
+    __slots__ = [
+        "description_placeholders",
+        "domain",
+        "job",
+        "schema",
+        "service",
+        "supports_response",
+    ]
 
     def __init__(
         self,
@@ -2443,11 +2450,13 @@ def __init__(
         context: Context | None = None,
         supports_response: SupportsResponse = SupportsResponse.NONE,
         job_type: HassJobType | None = None,
+        description_placeholders: Mapping[str, str] | None = None,
     ) -> None:
         """Initialize a service."""
         self.job = HassJob(func, f"service {domain}.{service}", job_type=job_type)
         self.schema = schema
         self.supports_response = supports_response
+        self.description_placeholders = description_placeholders
 
 
 class ServiceCall:
@@ -2590,6 +2599,8 @@ def async_register(
         schema: VolSchemaType | None = None,
         supports_response: SupportsResponse = SupportsResponse.NONE,
         job_type: HassJobType | None = None,
+        *,
+        description_placeholders: Mapping[str, str] | None = None,
     ) -> None:
         """Register a service.
 
@@ -2599,7 +2610,13 @@ def async_register(
         """
         self._hass.verify_event_loop_thread("hass.services.async_register")
         self._async_register(
-            domain, service, service_func, schema, supports_response, job_type
+            domain,
+            service,
+            service_func,
+            schema,
+            supports_response,
+            job_type,
+            description_placeholders,
         )
 
     @callback
@@ -2617,6 +2634,7 @@ def _async_register(
         schema: VolSchemaType | None = None,
         supports_response: SupportsResponse = SupportsResponse.NONE,
         job_type: HassJobType | None = None,
+        description_placeholders: Mapping[str, str] | None = None,
     ) -> None:
         """Register a service.
 
@@ -2633,6 +2651,7 @@ def _async_register(
             service,
             supports_response=supports_response,
             job_type=job_type,
+            description_placeholders=description_placeholders,
         )
 
         if domain in self._services:

homeassistant/helpers/entity_component.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Mapping
 from datetime import timedelta
 import logging
 from types import ModuleType
@@ -251,6 +251,8 @@ def async_register_entity_service(
         func: str | Callable[..., Any],
         required_features: list[int] | None = None,
         supports_response: SupportsResponse = SupportsResponse.NONE,
+        *,
+        description_placeholders: Mapping[str, str] | None = None,
     ) -> None:
         """Register an entity service."""
         service.async_register_entity_service(
@@ -263,6 +265,7 @@ def async_register_entity_service(
             required_features=required_features,
             schema=schema,
             supports_response=supports_response,
+            description_placeholders=description_placeholders,
         )
 
     async def async_setup_platform(

homeassistant/helpers/entity_platform.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Callable, Coroutine, Iterable
+from collections.abc import Awaitable, Callable, Coroutine, Iterable, Mapping
 from contextvars import ContextVar
 from datetime import timedelta
 from logging import Logger, getLogger
@@ -1081,6 +1081,7 @@ def async_register_entity_service(
         supports_response: SupportsResponse = SupportsResponse.NONE,
         *,
         entity_device_classes: Iterable[str | None] | None = None,
+        description_placeholders: Mapping[str, str] | None = None,
     ) -> None:
         """Register an entity service.
 
@@ -1100,6 +1101,7 @@ def async_register_entity_service(
             required_features=required_features,
             schema=schema,
             supports_response=supports_response,
+            description_placeholders=description_placeholders,
         )
 
     async def _async_update_entity_states(self) -> None:

homeassistant/helpers/service.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable, Coroutine, Iterable
+from collections.abc import Callable, Coroutine, Iterable, Mapping
 import dataclasses
 from enum import Enum
 from functools import cache, partial
@@ -612,6 +612,8 @@ async def async_get_all_descriptions(
             # Don't warn for missing services, because it triggers false
             # positives for things like scripts, that register as a service
             description = {"fields": yaml_description.get("fields", {})}
+            if description_placeholders := service.description_placeholders:
+                description["description_placeholders"] = description_placeholders
 
             for item in ("description", "name", "target"):
                 if item in yaml_description:
@@ -955,6 +957,8 @@ def async_register_admin_service(
     ],
     schema: VolSchemaType = vol.Schema({}, extra=vol.PREVENT_EXTRA),
     supports_response: SupportsResponse = SupportsResponse.NONE,
+    *,
+    description_placeholders: Mapping[str, str] | None = None,
 ) -> None:
     """Register a service that requires admin access."""
     hass.services.async_register(
@@ -967,6 +971,7 @@ def async_register_admin_service(
         ),
         schema,
         supports_response,
+        description_placeholders=description_placeholders,
     )
 
 
@@ -1112,6 +1117,7 @@ def async_register_entity_service(
     domain: str,
     name: str,
     *,
+    description_placeholders: Mapping[str, str] | None = None,
     entity_device_classes: Iterable[str | None] | None = None,
     entities: dict[str, Entity],
     func: str | Callable[..., Any],
@@ -1145,6 +1151,7 @@ def async_register_entity_service(
         schema,
         supports_response,
         job_type=job_type,
+        description_placeholders=description_placeholders,
     )
 
 
@@ -1154,6 +1161,7 @@ def async_register_platform_entity_service(
     service_domain: str,
     service_name: str,
     *,
+    description_placeholders: Mapping[str, str] | None = None,
     entity_device_classes: Iterable[str | None] | None = None,
     entity_domain: str,
     func: str | Callable[..., Any],
@@ -1191,4 +1199,5 @@ def get_entities() -> dict[str, Entity]:
         schema,
         supports_response,
         job_type=HassJobType.Coroutinefunction,
+        description_placeholders=description_placeholders,
     )

tests/helpers/test_entity_component.py

@@ -26,6 +26,7 @@
 from homeassistant.helpers import config_validation as cv, discovery
 from homeassistant.helpers.entity_component import EntityComponent, async_update_entity
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.helpers.service import async_get_all_descriptions
 from homeassistant.helpers.typing import ConfigType, DiscoveryInfoType
 from homeassistant.setup import async_setup_component
 from homeassistant.util import dt as dt_util
@@ -511,7 +512,7 @@ async def test_register_entity_service(
     schema: dict | None,
     service_data: dict,
 ) -> None:
-    """Test registering an enttiy service and calling it."""
+    """Test registering an entity service and calling it."""
     entity = MockEntity(entity_id=f"{DOMAIN}.entity")
     calls = []
 
@@ -525,7 +526,16 @@ def appender(**kwargs):
     await component.async_setup({})
     await component.async_add_entities([entity])
 
-    component.async_register_entity_service("hello", schema, "async_called_by_service")
+    component.async_register_entity_service(
+        "hello",
+        schema,
+        "async_called_by_service",
+        description_placeholders={"test_placeholder": "beer"},
+    )
+    descriptions = await async_get_all_descriptions(hass)
+    assert descriptions["test_domain"]["hello"]["description_placeholders"] == {
+        "test_placeholder": "beer"
+    }
 
     with pytest.raises(vol.Invalid):
         await hass.services.async_call(

tests/helpers/test_entity_platform.py

@@ -40,6 +40,7 @@
     AddConfigEntryEntitiesCallback,
     AddEntitiesCallback,
 )
+from homeassistant.helpers.service import async_get_all_descriptions
 from homeassistant.helpers.typing import ConfigType, DiscoveryInfoType
 from homeassistant.util import dt as dt_util
 
@@ -1639,11 +1640,21 @@ async def test_platforms_sharing_services(hass: HomeAssistant) -> None:
     def handle_service(entity, data):
         entities.append(entity)
 
-    entity_platform1.async_register_entity_service("hello", {}, handle_service)
+    entity_platform1.async_register_entity_service(
+        "hello", {}, handle_service, description_placeholders={"drink": "beer"}
+    )
     entity_platform2.async_register_entity_service(
-        "hello", {}, Mock(side_effect=AssertionError("Should not be called"))
+        "hello",
+        {},
+        Mock(side_effect=AssertionError("Should not be called")),
+        description_placeholders={"drink": "milk"},
     )
 
+    descriptions = await async_get_all_descriptions(hass)
+    assert descriptions["mock_platform"]["hello"]["description_placeholders"] == {
+        "drink": "beer"
+    }
+
     await hass.services.async_call(
         "mock_platform", "hello", {"entity_id": "all"}, blocking=True
     )