API 7.0

telegram/_bot.py

@@ -79,6 +79,7 @@
 from telegram._forumtopic import ForumTopic
 from telegram._games.gamehighscore import GameHighScore
 from telegram._inline.inlinequeryresultsbutton import InlineQueryResultsButton
+from telegram._linkpreviewoptions import LinkPreviewOptions
 from telegram._menubutton import MenuButton
 from telegram._message import Message
 from telegram._messageid import MessageId
@@ -670,7 +671,7 @@ async def _send_message(
         caption: Optional[str] = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Optional[Sequence["MessageEntity"]] = None,
-        disable_web_page_preview: ODVInput[bool] = DEFAULT_NONE,
+        link_preview_options: ODVInput["LinkPreviewOptions"] = DEFAULT_NONE,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -688,12 +689,12 @@ async def _send_message(
         using `Any` instead saves us a lot of `type: ignore` comments
         """
         # We don't check if (DEFAULT_)None here, so that _post is able to insert the defaults
-        # correctly, if necessary
+        # correctly, if necessary:
         data["disable_notification"] = disable_notification
         data["allow_sending_without_reply"] = allow_sending_without_reply
         data["protect_content"] = protect_content
         data["parse_mode"] = parse_mode
-        data["disable_web_page_preview"] = disable_web_page_preview
+        data["link_preview_options"] = link_preview_options
 
         if reply_to_message_id is not None:
             data["reply_to_message_id"] = reply_to_message_id
@@ -800,13 +801,17 @@ async def send_message(
         text: str,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         entities: Optional[Sequence["MessageEntity"]] = None,
+        # Deprecated since Bot API 7.0 (to be made keyword arg):
+        # ---
         disable_web_page_preview: ODVInput[bool] = DEFAULT_NONE,
+        # ---
         disable_notification: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         reply_markup: Optional[ReplyMarkup] = None,
         message_thread_id: Optional[int] = None,
+        link_preview_options: ODVInput["LinkPreviewOptions"] = DEFAULT_NONE,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -828,8 +833,23 @@ async def send_message(
 
                 .. versionchanged:: 20.0
                     |sequenceargs|
+            link_preview_options (:obj:`LinkPreviewOptions`, optional): Link preview generation
+                options for the message. Mutually exclusive with
+                :paramref:`disable_web_page_preview`.
+
+                .. versionadded:: NEXT.VERSION
+
             disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in
-                this message.
+                this message. Mutually exclusive with :paramref:`link_preview_options`.
+
+                .. versionchanged:: NEXT.VERSION
+                    Bot API 7.0 introduced :paramref:`link_preview_options` replacing this
+                    argument. PTB will automatically convert this argument to that one, but
+                    you should update your code to use the new argument.
+
+                .. deprecated:: NEXT.VERSION
+                    In future versions, this argument will become keyword only.
+
             disable_notification (:obj:`bool`, optional): |disable_notification|
             protect_content (:obj:`bool`, optional): |protect_content|
 
@@ -848,11 +868,21 @@ async def send_message(
             :class:`telegram.Message`: On success, the sent message is returned.
 
         Raises:
-            :class:`telegram.error.TelegramError`
+            :exc:`ValueError`: If both :paramref:`disable_web_page_preview` and
+                :paramref:`link_preview_options` are passed.
+            :class:`telegram.error.TelegramError`: For other errors.
 
         """
         data: JSONDict = {"chat_id": chat_id, "text": text, "entities": entities}
 
+        if disable_web_page_preview and link_preview_options:
+            raise ValueError(
+                "`disable_web_page_preview` and `link_preview_options` are mutually  exclusive."
+            )
+        # Convert to LinkPreviewOptions:
+        if not isinstance(disable_web_page_preview, DefaultValue):
+            link_preview_options = LinkPreviewOptions(is_disabled=disable_web_page_preview)
+
         return await self._send_message(
             "sendMessage",
             data,
@@ -863,7 +893,7 @@ async def send_message(
             protect_content=protect_content,
             message_thread_id=message_thread_id,
             parse_mode=parse_mode,
-            disable_web_page_preview=disable_web_page_preview,
+            link_preview_options=link_preview_options,
             read_timeout=read_timeout,
             write_timeout=write_timeout,
             connect_timeout=connect_timeout,
@@ -3339,9 +3369,13 @@ async def edit_message_text(
         message_id: Optional[int] = None,
         inline_message_id: Optional[str] = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
+        # Deprecated since Bot API 7.0 (to be keyword only):
+        # ---
         disable_web_page_preview: ODVInput[bool] = DEFAULT_NONE,
+        # ---
         reply_markup: Optional["InlineKeyboardMarkup"] = None,
         entities: Optional[Sequence["MessageEntity"]] = None,
+        link_preview_options: ODVInput["LinkPreviewOptions"] = DEFAULT_NONE,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -3375,8 +3409,24 @@ async def edit_message_text(
 
                 .. versionchanged:: 20.0
                     |sequenceargs|
+
+            link_preview_options (:obj:`LinkPreviewOptions`, optional): Link preview generation
+                options for the message. Mutually exclusive with
+                :paramref:`disable_web_page_preview`.
+
+                .. versionadded:: NEXT.VERSION
+
             disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in
-                this message.
+                this message. Mutually exclusive with :paramref:`link_preview_options`.
+
+                .. versionchanged:: NEXT.VERSION
+                    Bot API 7.0 introduced :paramref:`link_preview_options` replacing this
+                    argument. PTB will automatically convert this argument to that one, but
+                    you should update your code to use the new argument.
+
+                .. deprecated:: NEXT.VERSION
+                    In future versions, this argument will become keyword only.
+
             reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for an
                 inline keyboard.
 
@@ -3385,7 +3435,9 @@ async def edit_message_text(
             edited message is returned, otherwise :obj:`True` is returned.
 
         Raises:
-            :class:`telegram.error.TelegramError`
+            :exc:`ValueError`: If both :paramref:`disable_web_page_preview` and
+                :paramref:`link_preview_options` are passed.
+            :class:`telegram.error.TelegramError`: For other errors.
 
         """
         data: JSONDict = {
@@ -3396,12 +3448,20 @@ async def edit_message_text(
             "entities": entities,
         }
 
+        if disable_web_page_preview and link_preview_options:
+            raise ValueError(
+                "`disable_web_page_preview` and `link_preview_options` are mutually  exclusive."
+            )
+        # Convert to LinkPreviewOptions:
+        if not isinstance(disable_web_page_preview, DefaultValue):
+            link_preview_options = LinkPreviewOptions(is_disabled=disable_web_page_preview)
+
         return await self._send_message(
             "editMessageText",
             data,
             reply_markup=reply_markup,
             parse_mode=parse_mode,
-            disable_web_page_preview=disable_web_page_preview,
+            link_preview_options=link_preview_options,
             read_timeout=read_timeout,
             write_timeout=write_timeout,
             connect_timeout=connect_timeout,

telegram/ext/_defaults.py

@@ -20,7 +20,11 @@
 import datetime
 from typing import Any, Dict, NoReturn, Optional, final
 
+from telegram import LinkPreviewOptions
 from telegram._utils.datetime import UTC
+from telegram._utils.types import ODVInput
+from telegram._utils.warnings import warn
+from telegram.warnings import PTBDeprecationWarning
 
 
 @final
@@ -38,7 +42,12 @@ class Defaults:
         parse_mode (:obj:`str`, optional): |parse_mode|
         disable_notification (:obj:`bool`, optional): |disable_notification|
         disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in this
-            message.
+            message. Mutually exclusive with :paramref:`link_preview_options`.
+
+            .. deprecated:: NEXT.VERSION
+                Use :paramref:`link_preview_options` instead. This parameter will be removed in
+                future versions.
+
         allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply|
         quote (:obj:`bool`, optional): If set to :obj:`True`, the reply is sent as an actual reply
             to the message. If ``reply_to_message_id`` is passed, this parameter will
@@ -56,18 +65,23 @@ class Defaults:
         protect_content (:obj:`bool`, optional): |protect_content|
 
             .. versionadded:: 20.0
+        link_preview_options (:class:`telegram.LinkPreviewOptions`, optional):
+            Link preview generation options for all outgoing messages. Mutually exclusive with
+            :paramref:`disable_web_page_preview`.
+
+            .. versionadded:: NEXT.VERSION
     """
 
     __slots__ = (
         "_tzinfo",
-        "_disable_web_page_preview",
         "_block",
         "_quote",
         "_disable_notification",
         "_allow_sending_without_reply",
         "_parse_mode",
         "_api_defaults",
         "_protect_content",
+        "_link_preview_options",
     )
 
     def __init__(
@@ -80,25 +94,42 @@ def __init__(
         block: bool = True,
         allow_sending_without_reply: Optional[bool] = None,
         protect_content: Optional[bool] = None,
+        link_preview_options: Optional["LinkPreviewOptions"] = None,
     ):
         self._parse_mode: Optional[str] = parse_mode
         self._disable_notification: Optional[bool] = disable_notification
-        self._disable_web_page_preview: Optional[bool] = disable_web_page_preview
         self._allow_sending_without_reply: Optional[bool] = allow_sending_without_reply
         self._quote: Optional[bool] = quote
         self._tzinfo: datetime.tzinfo = tzinfo
         self._block: bool = block
         self._protect_content: Optional[bool] = protect_content
 
+        if disable_web_page_preview is not None and link_preview_options is not None:
+            raise ValueError(
+                "`disable_web_page_preview` and `link_preview_options` are mutually exclusive."
+            )
+
+        if disable_web_page_preview is not None:
+            warn(
+                "`Defaults.disable_web_page_preview` is deprecated. Use "
+                "`Defaults.link_preview_options` instead.",
+                category=PTBDeprecationWarning,
+                stacklevel=2,
+            )
+            self._link_preview_options: Optional[LinkPreviewOptions] = LinkPreviewOptions(
+                is_disabled=disable_web_page_preview
+            )
+        else:
+            self._link_preview_options = link_preview_options
         # Gather all defaults that actually have a default value
         self._api_defaults = {}
         for kwarg in (
             "parse_mode",
             "explanation_parse_mode",
             "disable_notification",
-            "disable_web_page_preview",
             "allow_sending_without_reply",
             "protect_content",
+            "link_preview_options",
         ):
             value = getattr(self, kwarg)
             if value is not None:
@@ -115,7 +146,7 @@ def __hash__(self) -> int:
             (
                 self._parse_mode,
                 self._disable_notification,
-                self._disable_web_page_preview,
+                self.disable_web_page_preview,
                 self._allow_sending_without_reply,
                 self._quote,
                 self._tzinfo,
@@ -178,11 +209,11 @@ def disable_notification(self, value: object) -> NoReturn:
         )
 
     @property
-    def disable_web_page_preview(self) -> Optional[bool]:
-        """:obj:`bool`: Optional. Disables link previews for links in this
-        message.
+    def disable_web_page_preview(self) -> ODVInput[bool]:
+        """:obj:`bool`: Optional. Disables link previews for links in all outgoing
+        messages.
         """
-        return self._disable_web_page_preview
+        return self._link_preview_options.is_disabled if self._link_preview_options else None
 
     @disable_web_page_preview.setter
     def disable_web_page_preview(self, value: object) -> NoReturn:
@@ -252,3 +283,12 @@ def protect_content(self, value: object) -> NoReturn:
         raise AttributeError(
             "You can't assign a new value to protect_content after initialization."
         )
+
+    @property
+    def link_preview_options(self) -> Optional["LinkPreviewOptions"]:
+        """:class:`telegram.LinkPreviewOptions`: Optional. Link preview generation options for all
+        outgoing messages.
+
+        .. versionadded:: NEXT.VERSION
+        """
+        return self._link_preview_options