homeassistant 2025.6.2__py3-none-any.whl → 2025.7.0b0__py3-none-any.whl

homeassistant/components/telegram_bot/const.py

@@ -0,0 +1,110 @@
+"""Constants for the Telegram Bot integration."""
+
+from ipaddress import ip_network
+
+DOMAIN = "telegram_bot"
+
+PLATFORM_BROADCAST = "broadcast"
+PLATFORM_POLLING = "polling"
+PLATFORM_WEBHOOKS = "webhooks"
+
+SUBENTRY_TYPE_ALLOWED_CHAT_IDS = "allowed_chat_ids"
+
+CONF_BOT_COUNT = "bot_count"
+CONF_ALLOWED_CHAT_IDS = "allowed_chat_ids"
+CONF_CONFIG_ENTRY_ID = "config_entry_id"
+
+CONF_PROXY_URL = "proxy_url"
+CONF_TRUSTED_NETWORKS = "trusted_networks"
+
+# subentry
+CONF_CHAT_ID = "chat_id"
+
+BOT_NAME = "telegram_bot"
+ERROR_FIELD = "error_field"
+ERROR_MESSAGE = "error_message"
+
+ISSUE_DEPRECATED_YAML = "deprecated_yaml"
+ISSUE_DEPRECATED_YAML_HAS_MORE_PLATFORMS = (
+    "deprecated_yaml_import_issue_has_more_platforms"
+)
+ISSUE_DEPRECATED_YAML_IMPORT_ISSUE_ERROR = "deprecated_yaml_import_issue_error"
+
+DEFAULT_TRUSTED_NETWORKS = [ip_network("149.154.160.0/20"), ip_network("91.108.4.0/22")]
+
+SERVICE_SEND_MESSAGE = "send_message"
+SERVICE_SEND_PHOTO = "send_photo"
+SERVICE_SEND_STICKER = "send_sticker"
+SERVICE_SEND_ANIMATION = "send_animation"
+SERVICE_SEND_VIDEO = "send_video"
+SERVICE_SEND_VOICE = "send_voice"
+SERVICE_SEND_DOCUMENT = "send_document"
+SERVICE_SEND_LOCATION = "send_location"
+SERVICE_SEND_POLL = "send_poll"
+SERVICE_SET_MESSAGE_REACTION = "set_message_reaction"
+SERVICE_EDIT_MESSAGE = "edit_message"
+SERVICE_EDIT_CAPTION = "edit_caption"
+SERVICE_EDIT_REPLYMARKUP = "edit_replymarkup"
+SERVICE_ANSWER_CALLBACK_QUERY = "answer_callback_query"
+SERVICE_DELETE_MESSAGE = "delete_message"
+SERVICE_LEAVE_CHAT = "leave_chat"
+
+EVENT_TELEGRAM_CALLBACK = "telegram_callback"
+EVENT_TELEGRAM_COMMAND = "telegram_command"
+EVENT_TELEGRAM_TEXT = "telegram_text"
+EVENT_TELEGRAM_SENT = "telegram_sent"
+
+PARSER_HTML = "html"
+PARSER_MD = "markdown"
+PARSER_MD2 = "markdownv2"
+PARSER_PLAIN_TEXT = "plain_text"
+
+ATTR_DATA = "data"
+ATTR_MESSAGE = "message"
+ATTR_TITLE = "title"
+
+ATTR_ARGS = "args"
+ATTR_AUTHENTICATION = "authentication"
+ATTR_CALLBACK_QUERY = "callback_query"
+ATTR_CALLBACK_QUERY_ID = "callback_query_id"
+ATTR_CAPTION = "caption"
+ATTR_CHAT_ID = "chat_id"
+ATTR_CHAT_INSTANCE = "chat_instance"
+ATTR_DATE = "date"
+ATTR_DISABLE_NOTIF = "disable_notification"
+ATTR_DISABLE_WEB_PREV = "disable_web_page_preview"
+ATTR_EDITED_MSG = "edited_message"
+ATTR_FILE = "file"
+ATTR_FROM_FIRST = "from_first"
+ATTR_FROM_LAST = "from_last"
+ATTR_KEYBOARD = "keyboard"
+ATTR_RESIZE_KEYBOARD = "resize_keyboard"
+ATTR_ONE_TIME_KEYBOARD = "one_time_keyboard"
+ATTR_KEYBOARD_INLINE = "inline_keyboard"
+ATTR_MESSAGEID = "message_id"
+ATTR_MSG = "message"
+ATTR_MSGID = "id"
+ATTR_PARSER = "parse_mode"
+ATTR_PASSWORD = "password"
+ATTR_REACTION = "reaction"
+ATTR_IS_BIG = "is_big"
+ATTR_REPLY_TO_MSGID = "reply_to_message_id"
+ATTR_REPLYMARKUP = "reply_markup"
+ATTR_SHOW_ALERT = "show_alert"
+ATTR_STICKER_ID = "sticker_id"
+ATTR_TARGET = "target"
+ATTR_TEXT = "text"
+ATTR_URL = "url"
+ATTR_USER_ID = "user_id"
+ATTR_USERNAME = "username"
+ATTR_VERIFY_SSL = "verify_ssl"
+ATTR_TIMEOUT = "timeout"
+ATTR_MESSAGE_TAG = "message_tag"
+ATTR_CHANNEL_POST = "channel_post"
+ATTR_QUESTION = "question"
+ATTR_OPTIONS = "options"
+ATTR_ANSWERS = "answers"
+ATTR_OPEN_PERIOD = "open_period"
+ATTR_IS_ANONYMOUS = "is_anonymous"
+ATTR_ALLOWS_MULTIPLE_ANSWERS = "allows_multiple_answers"
+ATTR_MESSAGE_THREAD_ID = "message_thread_id"

homeassistant/components/telegram_bot/icons.json

@@ -41,6 +41,12 @@
     },
     "delete_message": {
       "service": "mdi:delete"
+    },
+    "leave_chat": {
+      "service": "mdi:exit-run"
+    },
+    "set_message_reaction": {
+      "service": "mdi:emoticon-happy"
     }
   }
 }

homeassistant/components/telegram_bot/manifest.json

@@ -2,10 +2,11 @@
   "domain": "telegram_bot",
   "name": "Telegram bot",
   "codeowners": [],
+  "config_flow": true,
   "dependencies": ["http"],
   "documentation": "https://www.home-assistant.io/integrations/telegram_bot",
   "iot_class": "cloud_push",
   "loggers": ["telegram"],
-  "quality_scale": "legacy",
+  "quality_scale": "bronze",
   "requirements": ["python-telegram-bot[socks]==21.5"]
 }

homeassistant/components/telegram_bot/polling.py

@@ -2,34 +2,35 @@
 
 import logging
 
-from telegram import Update
+from telegram import Bot, Update
 from telegram.error import NetworkError, RetryAfter, TelegramError, TimedOut
 from telegram.ext import ApplicationBuilder, CallbackContext, TypeHandler
 
-from homeassistant.const import EVENT_HOMEASSISTANT_START, EVENT_HOMEASSISTANT_STOP
+from homeassistant.core import HomeAssistant
 
-from . import BaseTelegramBotEntity
+from .bot import BaseTelegramBot, TelegramBotConfigEntry
 
 _LOGGER = logging.getLogger(__name__)
 
 
-async def async_setup_platform(hass, bot, config):
+async def async_setup_platform(
+    hass: HomeAssistant, bot: Bot, config: TelegramBotConfigEntry
+) -> BaseTelegramBot | None:
     """Set up the Telegram polling platform."""
     pollbot = PollBot(hass, bot, config)
 
-    hass.bus.async_listen_once(EVENT_HOMEASSISTANT_START, pollbot.start_polling)
-    hass.bus.async_listen_once(EVENT_HOMEASSISTANT_STOP, pollbot.stop_polling)
+    await pollbot.start_polling()
 
-    return True
+    return pollbot
 
 
-async def process_error(update: Update, context: CallbackContext) -> None:
+async def process_error(update: object, context: CallbackContext) -> None:
     """Telegram bot error handler."""
     if context.error:
         error_callback(context.error, update)
 
 
-def error_callback(error: Exception, update: Update | None = None) -> None:
+def error_callback(error: Exception, update: object | None = None) -> None:
     """Log the error."""
     try:
         raise error
@@ -43,13 +44,15 @@ def error_callback(error: Exception, update: Update | None = None) -> None:
             _LOGGER.error("%s: %s", error.__class__.__name__, error)
 
 
-class PollBot(BaseTelegramBotEntity):
+class PollBot(BaseTelegramBot):
     """Controls the Application object that holds the bot and an updater.
 
     The application is set up to pass telegram updates to `self.handle_update`
     """
 
-    def __init__(self, hass, bot, config):
+    def __init__(
+        self, hass: HomeAssistant, bot: Bot, config: TelegramBotConfigEntry
+    ) -> None:
         """Create Application to poll for updates."""
         super().__init__(hass, config)
         self.bot = bot
@@ -57,16 +60,22 @@ class PollBot(BaseTelegramBotEntity):
         self.application.add_handler(TypeHandler(Update, self.handle_update))
         self.application.add_error_handler(process_error)
 
-    async def start_polling(self, event=None):
+    async def shutdown(self) -> None:
+        """Shutdown the app."""
+        await self.stop_polling()
+
+    async def start_polling(self) -> None:
         """Start the polling task."""
         _LOGGER.debug("Starting polling")
         await self.application.initialize()
-        await self.application.updater.start_polling(error_callback=error_callback)
+        if self.application.updater:
+            await self.application.updater.start_polling(error_callback=error_callback)
         await self.application.start()
 
-    async def stop_polling(self, event=None):
+    async def stop_polling(self) -> None:
         """Stop the polling task."""
         _LOGGER.debug("Stopping polling")
-        await self.application.updater.stop()
+        if self.application.updater:
+            await self.application.updater.stop()
         await self.application.stop()
         await self.application.shutdown()

homeassistant/components/telegram_bot/quality_scale.yaml

@@ -0,0 +1,72 @@
+rules:
+  # Bronze
+  action-setup: done
+  appropriate-polling:
+    status: exempt
+    comment: |
+      The integration provides webhooks (push based), polling (long polling) and broadcast (no data fetching) platforms which do not have interval polling.
+  brands: done
+  common-modules: done
+  config-flow-test-coverage: done
+  config-flow: done
+  dependency-transparency: done
+  docs-actions: done
+  docs-high-level-description: done
+  docs-installation-instructions: done
+  docs-removal-instructions: done
+  entity-event-setup:
+    status: exempt
+    comment: |
+      The integration does not provide any entities.
+  entity-unique-id:
+    status: exempt
+    comment: |
+      The integration does not provide any entities.
+  has-entity-name:
+    status: exempt
+    comment: |
+      The integration does not provide any entities.
+  runtime-data: done
+  test-before-configure: done
+  test-before-setup: done
+  unique-config-entry: done
+
+  # Silver
+  action-exceptions: todo
+  config-entry-unloading: done
+  docs-configuration-parameters: todo
+  docs-installation-parameters: todo
+  entity-unavailable: todo
+  integration-owner: todo
+  log-when-unavailable: todo
+  parallel-updates: todo
+  reauthentication-flow: done
+  test-coverage: todo
+
+  # Gold
+  devices: todo
+  diagnostics: todo
+  discovery-update-info: todo
+  discovery: todo
+  docs-data-update: todo
+  docs-examples: todo
+  docs-known-limitations: todo
+  docs-supported-devices: todo
+  docs-supported-functions: todo
+  docs-troubleshooting: todo
+  docs-use-cases: todo
+  dynamic-devices: todo
+  entity-category: todo
+  entity-device-class: todo
+  entity-disabled-by-default: todo
+  entity-translations: todo
+  exception-translations: todo
+  icon-translations: todo
+  reconfiguration-flow: todo
+  repair-issues: todo
+  stale-devices: todo
+
+  # Platinum
+  async-dependency: todo
+  inject-websession: todo
+  strict-typing: todo

homeassistant/components/telegram_bot/services.yaml

@@ -2,6 +2,10 @@
 
 send_message:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     message:
       required: true
       example: The garage door has been open for 10 minutes.
@@ -23,6 +27,7 @@ send_message:
             - "markdown"
             - "markdownv2"
             - "plain_text"
+          translation_key: "parse_mode"
     disable_notification:
       selector:
         boolean:
@@ -61,6 +66,10 @@ send_message:
 
 send_photo:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     url:
       example: "http://example.org/path/to/the/image.png"
       selector:
@@ -137,6 +146,10 @@ send_photo:
 
 send_sticker:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     url:
       example: "http://example.org/path/to/the/sticker.webp"
       selector:
@@ -205,6 +218,10 @@ send_sticker:
 
 send_animation:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     url:
       example: "http://example.org/path/to/the/animation.gif"
       selector:
@@ -281,6 +298,10 @@ send_animation:
 
 send_video:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     url:
       example: "http://example.org/path/to/the/video.mp4"
       selector:
@@ -357,6 +378,10 @@ send_video:
 
 send_voice:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     url:
       example: "http://example.org/path/to/the/voice.opus"
       selector:
@@ -425,6 +450,10 @@ send_voice:
 
 send_document:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     url:
       example: "http://example.org/path/to/the/document.odf"
       selector:
@@ -501,6 +530,10 @@ send_document:
 
 send_location:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     latitude:
       required: true
       selector:
@@ -555,6 +588,10 @@ send_location:
 
 send_poll:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     target:
       example: "[12345, 67890] or 12345"
       selector:
@@ -603,6 +640,10 @@ send_poll:
 
 edit_message:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     message_id:
       required: true
       example: "{{ trigger.event.data.message.message_id }}"
@@ -641,6 +682,10 @@ edit_message:
 
 edit_caption:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     message_id:
       required: true
       example: "{{ trigger.event.data.message.message_id }}"
@@ -665,6 +710,10 @@ edit_caption:
 
 edit_replymarkup:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     message_id:
       required: true
       example: "{{ trigger.event.data.message.message_id }}"
@@ -685,6 +734,10 @@ edit_replymarkup:
 
 answer_callback_query:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     message:
       required: true
       example: "OK, I'm listening"
@@ -708,6 +761,10 @@ answer_callback_query:
 
 delete_message:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
     message_id:
       required: true
       example: "{{ trigger.event.data.message.message_id }}"
@@ -718,3 +775,41 @@ delete_message:
       example: 12345
       selector:
         text:
+
+leave_chat:
+  fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
+    chat_id:
+      required: true
+      example: 12345
+      selector:
+        text:
+
+set_message_reaction:
+  fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: telegram_bot
+    message_id:
+      required: true
+      example: 54321
+      selector:
+        text:
+    chat_id:
+      required: true
+      example: 12345
+      selector:
+        text:
+    reaction:
+      required: true
+      example: 👍
+      selector:
+        text:
+    is_big:
+      required: false
+      selector:
+        boolean: