README.md edited

.venv/lib/python3.10/site-packages/telegram/ext/_defaults.py

@@ -0,0 +1,413 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the class Defaults, which allows passing default values to Application."""
+import datetime
+from typing import Any, 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
+class Defaults:
+    """Convenience Class to gather all parameters with a (user defined) default value
+
+    .. seealso:: :wiki:`Architecture Overview <Architecture>`,
+        :wiki:`Adding Defaults to Your Bot <Adding-defaults-to-your-bot>`
+
+    .. versionchanged:: 20.0
+        Removed the argument and attribute ``timeout``. Specify default timeout behavior for the
+        networking backend directly via :class:`telegram.ext.ApplicationBuilder` instead.
+
+    Parameters:
+        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. Mutually exclusive with :paramref:`link_preview_options`.
+
+            .. deprecated:: 20.8
+                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|.
+            Will be used for :attr:`telegram.ReplyParameters.allow_sending_without_reply`.
+        quote (:obj:`bool`, optional): |reply_quote|
+
+            .. deprecated:: 20.8
+                Use :paramref:`do_quote` instead. This parameter will be removed in future
+                versions.
+        tzinfo (:class:`datetime.tzinfo`, optional): A timezone to be used for all date(time)
+            inputs appearing throughout PTB, i.e. if a timezone naive date(time) object is passed
+            somewhere, it will be assumed to be in :paramref:`tzinfo`. If the
+            :class:`telegram.ext.JobQueue` is used, this must be a timezone provided
+            by the ``pytz`` module. Defaults to ``pytz.utc``, if available, and
+            :attr:`datetime.timezone.utc` otherwise.
+        block (:obj:`bool`, optional): Default setting for the :paramref:`BaseHandler.block`
+            parameter
+            of handlers and error handlers registered through :meth:`Application.add_handler` and
+            :meth:`Application.add_error_handler`. Defaults to :obj:`True`.
+        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`.
+            This object is used for the corresponding parameter of
+            :meth:`telegram.Bot.send_message`, :meth:`telegram.Bot.edit_message_text`,
+            and :class:`telegram.InputTextMessageContent` if not specified. If a value is specified
+            for the corresponding parameter, only those parameters of
+            :class:`telegram.LinkPreviewOptions` will be overridden that are not
+            explicitly set.
+
+            Example:
+
+                .. code-block:: python
+
+                    from telegram import LinkPreviewOptions
+                    from telegram.ext import Defaults, ExtBot
+
+                    defaults = Defaults(
+                        link_preview_options=LinkPreviewOptions(show_above_text=True)
+                    )
+                    chat_id = 123
+
+                    async def main():
+                        async with ExtBot("Token", defaults=defaults) as bot:
+                            # The link preview will be shown above the text.
+                            await bot.send_message(chat_id, "https://python-telegram-bot.org")
+
+                            # The link preview will be shown below the text.
+                            await bot.send_message(
+                                chat_id,
+                                "https://python-telegram-bot.org",
+                                link_preview_options=LinkPreviewOptions(show_above_text=False)
+                            )
+
+                            # The link preview will be shown above the text, but the preview will
+                            # show Telegram.
+                            await bot.send_message(
+                                chat_id,
+                                "https://python-telegram-bot.org",
+                                link_preview_options=LinkPreviewOptions(url="https://telegram.org")
+                            )
+
+            .. versionadded:: 20.8
+        do_quote(:obj:`bool`, optional): |reply_quote|
+
+            .. versionadded:: 20.8
+    """
+
+    __slots__ = (
+        "_allow_sending_without_reply",
+        "_api_defaults",
+        "_block",
+        "_disable_notification",
+        "_do_quote",
+        "_link_preview_options",
+        "_parse_mode",
+        "_protect_content",
+        "_tzinfo",
+    )
+
+    def __init__(
+        self,
+        parse_mode: Optional[str] = None,
+        disable_notification: Optional[bool] = None,
+        disable_web_page_preview: Optional[bool] = None,
+        quote: Optional[bool] = None,
+        tzinfo: datetime.tzinfo = UTC,
+        block: bool = True,
+        allow_sending_without_reply: Optional[bool] = None,
+        protect_content: Optional[bool] = None,
+        link_preview_options: Optional["LinkPreviewOptions"] = None,
+        do_quote: Optional[bool] = None,
+    ):
+        self._parse_mode: Optional[str] = parse_mode
+        self._disable_notification: Optional[bool] = disable_notification
+        self._allow_sending_without_reply: Optional[bool] = allow_sending_without_reply
+        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 quote is not None and do_quote is not None:
+            raise ValueError("`quote` and `do_quote` are mutually exclusive")
+        if disable_web_page_preview is not None:
+            warn(
+                PTBDeprecationWarning(
+                    "20.8",
+                    "`Defaults.disable_web_page_preview` is deprecated. Use "
+                    "`Defaults.link_preview_options` instead.",
+                ),
+                stacklevel=2,
+            )
+            self._link_preview_options: Optional[LinkPreviewOptions] = LinkPreviewOptions(
+                is_disabled=disable_web_page_preview
+            )
+        else:
+            self._link_preview_options = link_preview_options
+
+        if quote is not None:
+            warn(
+                PTBDeprecationWarning(
+                    "20.8", "`Defaults.quote` is deprecated. Use `Defaults.do_quote` instead."
+                ),
+                stacklevel=2,
+            )
+            self._do_quote: Optional[bool] = quote
+        else:
+            self._do_quote = do_quote
+        # Gather all defaults that actually have a default value
+        self._api_defaults = {}
+        for kwarg in (
+            "allow_sending_without_reply",
+            "disable_notification",
+            "do_quote",
+            "explanation_parse_mode",
+            "link_preview_options",
+            "parse_mode",
+            "text_parse_mode",
+            "protect_content",
+            "question_parse_mode",
+        ):
+            value = getattr(self, kwarg)
+            if value is not None:
+                self._api_defaults[kwarg] = value
+
+    def __hash__(self) -> int:
+        """Builds a hash value for this object such that the hash of two objects is equal if and
+        only if the objects are equal in terms of :meth:`__eq__`.
+
+        Returns:
+            :obj:`int` The hash value of the object.
+        """
+        return hash(
+            (
+                self._parse_mode,
+                self._disable_notification,
+                self.disable_web_page_preview,
+                self._allow_sending_without_reply,
+                self.quote,
+                self._tzinfo,
+                self._block,
+                self._protect_content,
+            )
+        )
+
+    def __eq__(self, other: object) -> bool:
+        """Defines equality condition for the :class:`Defaults` object.
+        Two objects of this class are considered to be equal if all their parameters
+        are identical.
+
+        Returns:
+            :obj:`True` if both objects have all parameters identical. :obj:`False` otherwise.
+        """
+        if isinstance(other, Defaults):
+            return all(getattr(self, attr) == getattr(other, attr) for attr in self.__slots__)
+        return False
+
+    @property
+    def api_defaults(self) -> dict[str, Any]:  # skip-cq: PY-D0003
+        return self._api_defaults
+
+    @property
+    def parse_mode(self) -> Optional[str]:
+        """:obj:`str`: Optional. Send Markdown or HTML, if you want Telegram apps to show
+        bold, italic, fixed-width text or URLs in your bot's message.
+        """
+        return self._parse_mode
+
+    @parse_mode.setter
+    def parse_mode(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to parse_mode after initialization.")
+
+    @property
+    def explanation_parse_mode(self) -> Optional[str]:
+        """:obj:`str`: Optional. Alias for :attr:`parse_mode`, used for
+        the corresponding parameter of :meth:`telegram.Bot.send_poll`.
+        """
+        return self._parse_mode
+
+    @explanation_parse_mode.setter
+    def explanation_parse_mode(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to explanation_parse_mode after initialization."
+        )
+
+    @property
+    def quote_parse_mode(self) -> Optional[str]:
+        """:obj:`str`: Optional. Alias for :attr:`parse_mode`, used for
+        the corresponding parameter of :meth:`telegram.ReplyParameters`.
+        """
+        return self._parse_mode
+
+    @quote_parse_mode.setter
+    def quote_parse_mode(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to quote_parse_mode after initialization."
+        )
+
+    @property
+    def text_parse_mode(self) -> Optional[str]:
+        """:obj:`str`: Optional. Alias for :attr:`parse_mode`, used for
+        the corresponding parameter of :class:`telegram.InputPollOption` and
+        :meth:`telegram.Bot.send_gift`.
+
+        .. versionadded:: 21.2
+        """
+        return self._parse_mode
+
+    @text_parse_mode.setter
+    def text_parse_mode(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to text_parse_mode after initialization."
+        )
+
+    @property
+    def question_parse_mode(self) -> Optional[str]:
+        """:obj:`str`: Optional. Alias for :attr:`parse_mode`, used for
+        the corresponding parameter of :meth:`telegram.Bot.send_poll`.
+
+        .. versionadded:: 21.2
+        """
+        return self._parse_mode
+
+    @question_parse_mode.setter
+    def question_parse_mode(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to question_parse_mode after initialization."
+        )
+
+    @property
+    def disable_notification(self) -> Optional[bool]:
+        """:obj:`bool`: Optional. Sends the message silently. Users will
+        receive a notification with no sound.
+        """
+        return self._disable_notification
+
+    @disable_notification.setter
+    def disable_notification(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to disable_notification after initialization."
+        )
+
+    @property
+    def disable_web_page_preview(self) -> ODVInput[bool]:
+        """:obj:`bool`: Optional. Disables link previews for links in all outgoing
+        messages.
+
+        .. deprecated:: 20.8
+            Use :attr:`link_preview_options` instead. This attribute will be removed in future
+            versions.
+        """
+        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, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to disable_web_page_preview after initialization."
+        )
+
+    @property
+    def allow_sending_without_reply(self) -> Optional[bool]:
+        """:obj:`bool`: Optional. Pass :obj:`True`, if the message
+        should be sent even if the specified replied-to message is not found.
+        """
+        return self._allow_sending_without_reply
+
+    @allow_sending_without_reply.setter
+    def allow_sending_without_reply(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to allow_sending_without_reply after initialization."
+        )
+
+    @property
+    def quote(self) -> Optional[bool]:
+        """:obj:`bool`: Optional. |reply_quote|
+
+        .. deprecated:: 20.8
+            Use :attr:`do_quote` instead. This attribute will be removed in future
+            versions.
+        """
+        return self._do_quote if self._do_quote is not None else None
+
+    @quote.setter
+    def quote(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to quote after initialization.")
+
+    @property
+    def tzinfo(self) -> datetime.tzinfo:
+        """:obj:`tzinfo`: A timezone to be used for all date(time) objects appearing
+        throughout PTB.
+        """
+        return self._tzinfo
+
+    @tzinfo.setter
+    def tzinfo(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to tzinfo after initialization.")
+
+    @property
+    def block(self) -> bool:
+        """:obj:`bool`: Optional. Default setting for the :paramref:`BaseHandler.block` parameter
+        of handlers and error handlers registered through :meth:`Application.add_handler` and
+        :meth:`Application.add_error_handler`.
+        """
+        return self._block
+
+    @block.setter
+    def block(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to block after initialization.")
+
+    @property
+    def protect_content(self) -> Optional[bool]:
+        """:obj:`bool`: Optional. Protects the contents of the sent message from forwarding and
+        saving.
+
+        .. versionadded:: 20.0
+        """
+        return self._protect_content
+
+    @protect_content.setter
+    def protect_content(self, _: 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:: 20.8
+        """
+        return self._link_preview_options
+
+    @property
+    def do_quote(self) -> Optional[bool]:
+        """:obj:`bool`: Optional. |reply_quote|
+
+        .. versionadded:: 20.8
+        """
+        return self._do_quote