Improve holidays config form and naming

The holidays library is improving over time, let's make use of their
data for a more user-friendly experience.

Author: bors-ltd

homeassistant/components/holiday/config_flow.py

@@ -19,6 +19,7 @@
 from homeassistant.helpers.selector import (
     CountrySelector,
     CountrySelectorConfig,
+    SelectOptionDict,
     SelectSelector,
     SelectSelectorConfig,
     SelectSelectorMode,
@@ -30,6 +31,29 @@
 SUPPORTED_COUNTRIES = list_supported_countries(include_aliases=False)
 
 
+def get_optional_provinces(country: str) -> list[Any]:
+    """Return the country provinces (territories).
+
+    Some territories have extra or different holidays
+    from another within the same country.
+    """
+    province_options: list[Any] = []
+
+    if provinces := SUPPORTED_COUNTRIES[country]:
+        country_data = country_holidays(country, years=dt_util.utcnow().year)
+        if country_data.subdivisions_aliases and (
+            subdiv_aliases := country_data.get_subdivision_aliases()
+        ):
+            province_options = [
+                SelectOptionDict(value=k, label=", ".join(v))
+                for k, v in subdiv_aliases.items()
+            ]
+        else:
+            province_options = provinces
+
+    return province_options
+
+
 def get_optional_categories(country: str) -> list[str]:
     """Return the country categories.
 
@@ -45,7 +69,7 @@ def get_optional_categories(country: str) -> list[str]:
 def get_options_schema(country: str) -> vol.Schema:
     """Return the options schema."""
     schema = {}
-    if provinces := SUPPORTED_COUNTRIES[country]:
+    if provinces := get_optional_provinces(country):
         schema[vol.Optional(CONF_PROVINCE)] = SelectSelector(
             SelectSelectorConfig(
                 options=provinces,
@@ -64,6 +88,15 @@ def get_options_schema(country: str) -> vol.Schema:
     return vol.Schema(schema)
 
 
+def get_province_alias(country: str, province: str) -> str:
+    """Return the friendly alias for a given province (territory) code, if any."""
+    country_data = country_holidays(country, province, years=dt_util.utcnow().year)
+    # holidays API doesn't make it straightforward
+    # revisit this after their API is enriched
+    code_to_alias = {v: k for k, v in country_data.subdivisions_aliases.items()}
+    return code_to_alias.get(province, province)
+
+
 class HolidayConfigFlow(ConfigFlow, domain=DOMAIN):
     """Handle a config flow for Holiday."""
 
@@ -140,8 +173,11 @@ async def async_step_options(
                 # Default to (US) English if language not recognized by babel
                 # Mainly an issue with English flavors such as "en-GB"
                 locale = Locale("en")
-            province_str = f", {province}" if province else ""
-            name = f"{locale.territories[country]}{province_str}"
+            name = locale.territories[country]
+
+            if province:
+                alias = get_province_alias(country, province)
+                name = f"{name}, {alias}"
 
             return self.async_create_entry(title=name, data=data, options=options)
 
@@ -177,8 +213,11 @@ async def async_step_reconfigure(
                 # Default to (US) English if language not recognized by babel
                 # Mainly an issue with English flavors such as "en-GB"
                 locale = Locale("en")
-            province_str = f", {province}" if province else ""
-            name = f"{locale.territories[country]}{province_str}"
+            name = locale.territories[country]
+
+            if province:
+                alias = get_province_alias(country, province)
+                name = f"{name}, {alias}"
 
             if options:
                 return self.async_update_reload_and_abort(

tests/components/holiday/test_config_flow.py

@@ -47,7 +47,7 @@ async def test_form(hass: HomeAssistant, mock_setup_entry: AsyncMock) -> None:
     await hass.async_block_till_done()
 
     assert result3["type"] is FlowResultType.CREATE_ENTRY
-    assert result3["title"] == "Germany, BW"
+    assert result3["title"] == "Germany, Baden-Württemberg"
     assert result3["data"] == {
         "country": "DE",
         "province": "BW",
@@ -178,7 +178,7 @@ async def test_form_babel_unresolved_language(hass: HomeAssistant) -> None:
     await hass.async_block_till_done()
 
     assert result["type"] is FlowResultType.CREATE_ENTRY
-    assert result["title"] == "Germany, BW"
+    assert result["title"] == "Germany, Baden-Württemberg"
     assert result["data"] == {
         "country": "DE",
         "province": "BW",
@@ -225,7 +225,7 @@ async def test_form_babel_replace_dash_with_underscore(hass: HomeAssistant) -> N
     await hass.async_block_till_done()
 
     assert result["type"] is FlowResultType.CREATE_ENTRY
-    assert result["title"] == "Germany, BW"
+    assert result["title"] == "Germany, Baden-Württemberg"
     assert result["data"] == {
         "country": "DE",
         "province": "BW",
@@ -237,7 +237,7 @@ async def test_reconfigure(hass: HomeAssistant) -> None:
     """Test reconfigure flow."""
     entry = MockConfigEntry(
         domain=DOMAIN,
-        title="Germany, BW",
+        title="Germany, Baden-Württemberg",
         data={"country": "DE", "province": "BW"},
     )
     entry.add_to_hass(hass)
@@ -256,7 +256,7 @@ async def test_reconfigure(hass: HomeAssistant) -> None:
     assert result["type"] is FlowResultType.ABORT
     assert result["reason"] == "reconfigure_successful"
     entry = hass.config_entries.async_get_entry(entry.entry_id)
-    assert entry.title == "Germany, NW"
+    assert entry.title == "Germany, Nordrhein-Westfalen"
     assert entry.data == {"country": "DE", "province": "NW"}
 
 
@@ -297,7 +297,7 @@ async def test_reconfigure_incorrect_language(hass: HomeAssistant) -> None:
 
     entry = MockConfigEntry(
         domain=DOMAIN,
-        title="Germany, BW",
+        title="Germany, Baden-Württemberg",
         data={"country": "DE", "province": "BW"},
     )
     entry.add_to_hass(hass)
@@ -316,7 +316,7 @@ async def test_reconfigure_incorrect_language(hass: HomeAssistant) -> None:
     assert result["type"] is FlowResultType.ABORT
     assert result["reason"] == "reconfigure_successful"
     entry = hass.config_entries.async_get_entry(entry.entry_id)
-    assert entry.title == "Germany, NW"
+    assert entry.title == "Germany, Nordrhein-Westfalen"
     assert entry.data == {"country": "DE", "province": "NW"}
 
 
@@ -325,13 +325,13 @@ async def test_reconfigure_entry_exists(hass: HomeAssistant) -> None:
     """Test reconfigure flow stops if other entry already exist."""
     entry = MockConfigEntry(
         domain=DOMAIN,
-        title="Germany, BW",
+        title="Germany, Baden-Württemberg",
         data={"country": "DE", "province": "BW"},
     )
     entry.add_to_hass(hass)
     entry2 = MockConfigEntry(
         domain=DOMAIN,
-        title="Germany, NW",
+        title="Germany, Nordrhein-Westfalen",
         data={"country": "DE", "province": "NW"},
     )
     entry2.add_to_hass(hass)
@@ -350,7 +350,7 @@ async def test_reconfigure_entry_exists(hass: HomeAssistant) -> None:
     assert result["type"] is FlowResultType.ABORT
     assert result["reason"] == "already_configured"
     entry = hass.config_entries.async_get_entry(entry.entry_id)
-    assert entry.title == "Germany, BW"
+    assert entry.title == "Germany, Baden-Württemberg"
     assert entry.data == {"country": "DE", "province": "BW"}
 
 
@@ -425,6 +425,47 @@ async def test_form_with_options(
     assert state.state == STATE_OFF
 
 
+async def test_form_with_subdivision_aliases(hass: HomeAssistant) -> None:
+    """Test the flow with a country using subdivision aliases (friendly names)."""
+    await hass.config.async_set_time_zone("Europe/Paris")
+
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+    assert result["type"] is FlowResultType.FORM
+
+    result = await hass.config_entries.flow.async_configure(
+        result["flow_id"],
+        {
+            CONF_COUNTRY: "FR",
+        },
+    )
+    await hass.async_block_till_done()
+
+    assert result["type"] is FlowResultType.FORM
+    # Find friendly name exposed to the user
+    options = {
+        option["value"]: option["label"]
+        for option in result["data_schema"].schema["province"].config["options"]
+    }
+    assert options["RE"] == "La Réunion"
+
+    result = await hass.config_entries.flow.async_configure(
+        result["flow_id"],
+        {
+            CONF_PROVINCE: "RE",
+        },
+    )
+    await hass.async_block_till_done(wait_background_tasks=True)
+
+    assert result["type"] is FlowResultType.CREATE_ENTRY
+    assert result["title"] == "France, La Réunion"
+    assert result["data"] == {
+        CONF_COUNTRY: "FR",
+        CONF_PROVINCE: "RE",
+    }
+
+
 @pytest.mark.usefixtures("mock_setup_entry")
 async def test_options_abort_no_categories(hass: HomeAssistant) -> None:
     """Test the options flow abort if no categories to select."""