Telegram bot proxy params deprecation (#112778)

* Add strings for issues to raise in telegram integration startup

* Allow proxy_params to be passed empty

Allows migration away from proxy_params whilst retaining a configured proxy.

* Raise issues for removing proxy_params config option

* Add types to initialize_bot function

* Add PR link for learn more URL

Update issue message to leave a comment on the PR instead

* Apply suggestions from code review

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* hass should always be first argument

* Update issues strings to give domain and better direction.

* Update breaks_in_ha_version to something saner

* Apply strings.json suggestions from code review

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

---------

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

homeassistant/components/telegram_bot/__init__.py

@@ -38,7 +38,7 @@ from homeassistant.const import (
 )
 from homeassistant.core import HomeAssistant, ServiceCall
 from homeassistant.exceptions import TemplateError
-import homeassistant.helpers.config_validation as cv
+from homeassistant.helpers import config_validation as cv, issue_registry as ir
 from homeassistant.helpers.typing import ConfigType
 from homeassistant.loader import async_get_loaded_integration
 
@@ -366,7 +366,7 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
 
     for p_config in domain_config:
         # Each platform config gets its own bot
-        bot = initialize_bot(p_config)
+        bot = initialize_bot(hass, p_config)
         p_type: str = p_config[CONF_PLATFORM]
 
         platform = platforms[p_type]
@@ -456,16 +456,55 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     return True
 
 
-def initialize_bot(p_config):
+def initialize_bot(hass: HomeAssistant, p_config: dict) -> Bot:
     """Initialize telegram bot with proxy support."""
-    api_key = p_config.get(CONF_API_KEY)
+    api_key: str = p_config[CONF_API_KEY]
-    proxy_url = p_config.get(CONF_PROXY_URL)
+    proxy_url: str | None = p_config.get(CONF_PROXY_URL)
-    proxy_params = p_config.get(CONF_PROXY_PARAMS)
+    proxy_params: dict | None = p_config.get(CONF_PROXY_PARAMS)
 
     if proxy_url is not None:
-        # These have been kept for backwards compatibility, they can actually be stuffed into the URL.
+        auth = None
-        # Side note: In the future we should deprecate these and raise a repair issue if we find them here.
+        if proxy_params is None:
-        auth = proxy_params.pop("username"), proxy_params.pop("password")
+            # CONF_PROXY_PARAMS has been kept for backwards compatibility.
+            proxy_params = {}
+        elif "username" in proxy_params and "password" in proxy_params:
+            # Auth can actually be stuffed into the URL, but the docs have previously
+            # indicated to put them here.
+            auth = proxy_params.pop("username"), proxy_params.pop("password")
+            ir.async_create_issue(
+                hass,
+                DOMAIN,
+                "proxy_params_auth_deprecation",
+                breaks_in_ha_version="2024.10.0",
+                is_persistent=False,
+                is_fixable=False,
+                severity=ir.IssueSeverity.WARNING,
+                translation_placeholders={
+                    "proxy_params": CONF_PROXY_PARAMS,
+                    "proxy_url": CONF_PROXY_URL,
+                    "telegram_bot": "Telegram bot",
+                },
+                translation_key="proxy_params_auth_deprecation",
+                learn_more_url="https://github.com/home-assistant/core/pull/112778",
+            )
+        else:
+            ir.async_create_issue(
+                hass,
+                DOMAIN,
+                "proxy_params_deprecation",
+                breaks_in_ha_version="2024.10.0",
+                is_persistent=False,
+                is_fixable=False,
+                severity=ir.IssueSeverity.WARNING,
+                translation_placeholders={
+                    "proxy_params": CONF_PROXY_PARAMS,
+                    "proxy_url": CONF_PROXY_URL,
+                    "httpx": "httpx",
+                    "telegram_bot": "Telegram bot",
+                },
+                translation_key="proxy_params_deprecation",
+                learn_more_url="https://github.com/home-assistant/core/pull/112778",
+            )
         proxy = httpx.Proxy(proxy_url, auth=auth, **proxy_params)
         request = HTTPXRequest(connection_pool_size=8, proxy=proxy)
     else:

homeassistant/components/telegram_bot/strings.json

@@ -636,5 +636,15 @@
         }
       }
     }
+  },
+  "issues": {
+    "proxy_params_auth_deprecation": {
+      "title": "{telegram_bot}: Proxy authentication should be moved to the URL",
+      "description": "Authentication details for the the proxy configured in the {telegram_bot} integration should be moved into the {proxy_url} instead. Please update your configuration and restart Home Assistant to fix this issue.\n\nThe {proxy_params} config key will be removed in a future release."
+    },
+    "proxy_params_deprecation": {
+      "title": "{telegram_bot}: Proxy params option will be removed",
+      "description": "The {proxy_params} config key for the {telegram_bot} integration will be removed in a future release.\n\nAuthentication can now be provided through the {proxy_url} key.\n\nThe underlying library has changed to {httpx} which is incompatible with previous parameters. If you still need this functionality for other options, please leave a comment on the learn more link.\n\nPlease update your configuration to remove the {proxy_params} key and restart Home Assistant to fix this issue."
+    }
   }
 }