From 970d2ab085a062f46cc1bd1aab70771eb4345ba5 Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Sun, 1 Sep 2024 14:12:41 +0200 Subject: [PATCH] Documentation Improvements (#4400, #4448) Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Palaptin <100526200+Palaptin@users.noreply.github.com> --- .github/workflows/docs-linkcheck.yml | 2 +- README.rst | 2 +- docs/source/telegram.games-tree.rst | 2 +- docs/substitutions/global.rst | 4 ++- telegram/_bot.py | 33 ++++++----------- telegram/_chatbackground.py | 20 +++++------ telegram/_chatfullinfo.py | 12 +++---- telegram/_files/inputsticker.py | 4 +-- telegram/_giveaway.py | 6 ++-- telegram/_inline/inlinekeyboardbutton.py | 36 +++++++++---------- telegram/_inline/inlinequeryresultgif.py | 16 +++------ telegram/_inline/inlinequeryresultmpeg4gif.py | 15 +++----- telegram/_inline/inlinequeryresultphoto.py | 16 +++------ telegram/_inline/inlinequeryresultvideo.py | 21 +++-------- .../_inline/inputinvoicemessagecontent.py | 4 +-- telegram/_message.py | 20 +++++------ telegram/_passport/credentials.py | 2 +- .../_passport/encryptedpassportelement.py | 2 +- telegram/_passport/passportfile.py | 2 +- telegram/_payment/stars.py | 20 +++++++++-- telegram/_reply.py | 18 +++++----- telegram/_telegramobject.py | 2 +- telegram/ext/filters.py | 2 +- 23 files changed, 118 insertions(+), 143 deletions(-) diff --git a/.github/workflows/docs-linkcheck.yml b/.github/workflows/docs-linkcheck.yml index 82fafe3e5..f34fcc17d 100644 --- a/.github/workflows/docs-linkcheck.yml +++ b/.github/workflows/docs-linkcheck.yml @@ -10,7 +10,7 @@ jobs: runs-on: ${{matrix.os}} strategy: matrix: - python-version: [3.9] + python-version: [3.10] os: [ubuntu-latest] fail-fast: False steps: diff --git a/README.rst b/README.rst index d96b4d47a..605942c06 100644 --- a/README.rst +++ b/README.rst @@ -119,7 +119,7 @@ Verifying Releases To enable you to verify that a release file that you downloaded was indeed provided by the ``python-telegram-bot`` team, we have taken the following measures. -Starting with v21.4, all releases are signed via `sigstore `_. +Starting with v21.4, all releases are signed via `sigstore `_. The corresponding signature files are uploaded to the `GitHub releases page`_. To verify the signature, please install the `sigstore Python client `_ and follow the instructions for `verifying signatures from GitHub Actions `_. As input for the ``--repository`` parameter, please use the value ``python-telegram-bot/python-telegram-bot``. diff --git a/docs/source/telegram.games-tree.rst b/docs/source/telegram.games-tree.rst index 010c3c6d1..97b961a9e 100644 --- a/docs/source/telegram.games-tree.rst +++ b/docs/source/telegram.games-tree.rst @@ -10,7 +10,7 @@ Your bot can offer users **HTML5 games** to play solo or to compete against each * If you send the game message without any buttons, it will automatically have a 'Play ``GameName``' button. When this button is pressed, your bot gets a :class:`telegram.CallbackQuery` with the ``game_short_name`` of the requested game. You provide the correct URL for this particular user and the app opens the game in the in-app browser. * You can manually add multiple buttons to your game message. Please note that the first button in the first row **must always** launch the game, using the field ``callback_game`` in :class:`telegram.InlineKeyboardButton`. You can add extra buttons according to taste: e.g., for a description of the rules, or to open the game's official community. * To make your game more attractive, you can upload a GIF animation that demonstrates the game to the users via `BotFather `_ (see `Lumberjack `_ for example). -* A game message will also display high scores for the current chat. Use :meth:`~telegram.Bot.setGameScore` to post high scores to the chat with the game, optionally add the :paramref:`~telegram.Bot.set_game_score.disable_edit_message` parameter if you don't want to automatically update the message with the current scoreboard. +* A game message will also display high scores for the current chat. Use :meth:`~telegram.Bot.setGameScore` to post high scores to the chat with the game, add the :paramref:`~telegram.Bot.set_game_score.disable_edit_message` parameter to disable automatic update of the message with the current scoreboard. * Use :meth:`~telegram.Bot.getGameHighScores` to get data for in-game high score tables. * You can also add an extra sharing button for users to share their best score to different chats. * For examples of what can be done using this new stuff, check the `@gamebot `_ and `@gamee `_ bots. diff --git a/docs/substitutions/global.rst b/docs/substitutions/global.rst index c4e9e493b..88a604cd1 100644 --- a/docs/substitutions/global.rst +++ b/docs/substitutions/global.rst @@ -60,10 +60,12 @@ .. |removed_thumb_note| replace:: Removed the deprecated argument and attribute ``thumb``. -.. |removed_thumb_url_note| replace:: Removed the deprecated argument and attribute ``thumb_url``. +.. |removed_thumb_url_note| replace:: Removed the deprecated argument and attribute ``thumb_url`` which made thumbnail_url mandatory. .. |removed_thumb_wildcard_note| replace:: Removed the deprecated arguments and attributes ``thumb_*``. +.. |thumbnail_url_mandatory| replace:: Removal of the deprecated argument ``thumb_url`` made ``thumbnail_url`` mandatory. + .. |async_context_manager| replace:: Asynchronous context manager which .. |reply_parameters| replace:: Description of the message to reply to. diff --git a/telegram/_bot.py b/telegram/_bot.py index 7172344cb..1e21206f4 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -4428,18 +4428,6 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]): If you're having any trouble setting up webhooks, please check out this `guide to Webhooks`_. - Note: - 1. You will not be able to receive updates using :meth:`get_updates` for long as an - outgoing webhook is set up. - 2. To use a self-signed certificate, you need to upload your public key certificate - using certificate parameter. Please upload as InputFile, sending a String will not - work. - 3. Ports currently supported for Webhooks: - :attr:`telegram.constants.SUPPORTED_WEBHOOK_PORTS`. - - If you're having any trouble setting up webhooks, please check out this `guide to - Webhooks`_. - .. seealso:: :meth:`telegram.ext.Application.run_webhook`, :meth:`telegram.ext.Updater.start_webhook` @@ -5020,7 +5008,7 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]): payload (:obj:`str`): Bot-defined invoice payload. :tg-const:`telegram.Invoice.MIN_PAYLOAD_LENGTH`- :tg-const:`telegram.Invoice.MAX_PAYLOAD_LENGTH` bytes. This will not be - displayed to the user, use for your internal processes. + displayed to the user, use it for your internal processes. provider_token (:obj:`str`): Payments provider token, obtained via `@BotFather `_. Pass an empty string for payments in |tg_stars|. @@ -5786,10 +5774,10 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]): Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| - invite_link (:obj:`str` | :obj:`telegram.ChatInviteLink`): The invite link to edit. + invite_link (:obj:`str` | :class:`telegram.ChatInviteLink`): The invite link to edit. .. versionchanged:: 20.0 - Now also accepts :obj:`telegram.ChatInviteLink` instances. + Now also accepts :class:`telegram.ChatInviteLink` instances. expire_date (:obj:`int` | :obj:`datetime.datetime`, optional): Date when the link will expire. For timezone naive :obj:`datetime.datetime` objects, the default timezone of the @@ -5858,10 +5846,10 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]): Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| - invite_link (:obj:`str` | :obj:`telegram.ChatInviteLink`): The invite link to revoke. + invite_link (:obj:`str` | :class:`telegram.ChatInviteLink`): The invite link to revoke. .. versionchanged:: 20.0 - Now also accepts :obj:`telegram.ChatInviteLink` instances. + Now also accepts :class:`telegram.ChatInviteLink` instances. Returns: :class:`telegram.ChatInviteLink` @@ -7403,8 +7391,9 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. versionadded:: 20.0 Args: - rights (:obj:`telegram.ChatAdministratorRights`, optional): A - :obj:`telegram.ChatAdministratorRights` object describing new default administrator + rights (:class:`telegram.ChatAdministratorRights`, optional): A + :class:`telegram.ChatAdministratorRights` object describing new default + administrator rights. If not specified, the default administrator rights will be cleared. for_channels (:obj:`bool`, optional): Pass :obj:`True` to change the default administrator rights of the bot in channels. Otherwise, the default administrator @@ -7414,7 +7403,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. :obj:`bool`: Returns :obj:`True` on success. Raises: - :obj:`telegram.error.TelegramError` + :exc:`telegram.error.TelegramError` """ data: JSONDict = {"rights": rights, "for_channels": for_channels} @@ -7980,7 +7969,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. payload (:obj:`str`): Bot-defined invoice payload. :tg-const:`telegram.Invoice.MIN_PAYLOAD_LENGTH`- :tg-const:`telegram.Invoice.MAX_PAYLOAD_LENGTH` bytes. This will not be - displayed to the user, use for your internal processes. + displayed to the user, use it for your internal processes. provider_token (:obj:`str`): Payments provider token, obtained via `@BotFather `_. Pass an empty string for payments in |tg_stars|. @@ -9078,7 +9067,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. user_id (:obj:`int`): User identifier of the sticker set owner. name (:obj:`str`): Sticker set name. old_sticker (:obj:`str`): File identifier of the replaced sticker. - sticker (:obj:`telegram.InputSticker`): An object with information about the added + sticker (:class:`telegram.InputSticker`): An object with information about the added sticker. If exactly the same sticker had already been added to the set, then the set remains unchanged. diff --git a/telegram/_chatbackground.py b/telegram/_chatbackground.py index f9c77619f..b33fd4d91 100644 --- a/telegram/_chatbackground.py +++ b/telegram/_chatbackground.py @@ -307,7 +307,7 @@ class BackgroundTypeFill(BackgroundType): .. versionadded:: 21.2 Args: - fill (:obj:`telegram.BackgroundFill`): The background fill. + fill (:class:`telegram.BackgroundFill`): The background fill. dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a percentage; 0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`. @@ -315,7 +315,7 @@ class BackgroundTypeFill(BackgroundType): Attributes: type (:obj:`str`): Type of the background. Always :attr:`~telegram.BackgroundType.FILL`. - fill (:obj:`telegram.BackgroundFill`): The background fill. + fill (:class:`telegram.BackgroundFill`): The background fill. dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a percentage; 0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`. @@ -349,7 +349,7 @@ class BackgroundTypeWallpaper(BackgroundType): .. versionadded:: 21.2 Args: - document (:obj:`telegram.Document`): Document with the wallpaper + document (:class:`telegram.Document`): Document with the wallpaper dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a percentage; 0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`. @@ -361,7 +361,7 @@ class BackgroundTypeWallpaper(BackgroundType): Attributes: type (:obj:`str`): Type of the background. Always :attr:`~telegram.BackgroundType.WALLPAPER`. - document (:obj:`telegram.Document`): Document with the wallpaper + document (:class:`telegram.Document`): Document with the wallpaper dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a percentage; 0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`. @@ -407,8 +407,8 @@ class BackgroundTypePattern(BackgroundType): .. versionadded:: 21.2 Args: - document (:obj:`telegram.Document`): Document with the pattern. - fill (:obj:`telegram.BackgroundFill`): The background fill that is combined with + document (:class:`telegram.Document`): Document with the pattern. + fill (:class:`telegram.BackgroundFill`): The background fill that is combined with the pattern. intensity (:obj:`int`): Intensity of the pattern when it is shown above the filled background; @@ -422,8 +422,8 @@ class BackgroundTypePattern(BackgroundType): Attributes: type (:obj:`str`): Type of the background. Always :attr:`~telegram.BackgroundType.PATTERN`. - document (:obj:`telegram.Document`): Document with the pattern. - fill (:obj:`telegram.BackgroundFill`): The background fill that is combined with + document (:class:`telegram.Document`): Document with the pattern. + fill (:class:`telegram.BackgroundFill`): The background fill that is combined with the pattern. intensity (:obj:`int`): Intensity of the pattern when it is shown above the filled background; @@ -511,10 +511,10 @@ class ChatBackground(TelegramObject): .. versionadded:: 21.2 Args: - type (:obj:`telegram.BackgroundType`): Type of the background. + type (:class:`telegram.BackgroundType`): Type of the background. Attributes: - type (:obj:`telegram.BackgroundType`): Type of the background. + type (:class:`telegram.BackgroundType`): Type of the background. """ __slots__ = ("type",) diff --git a/telegram/_chatfullinfo.py b/telegram/_chatfullinfo.py index 04898659c..de26101f3 100644 --- a/telegram/_chatfullinfo.py +++ b/telegram/_chatfullinfo.py @@ -78,7 +78,7 @@ class ChatFullInfo(_ChatBase): #collectible-usernames>`_; for private chats, supergroups and channels. .. versionadded:: 20.0 - birthdate (:obj:`telegram.Birthdate`, optional): For private chats, + birthdate (:class:`telegram.Birthdate`, optional): For private chats, the date of birth of the user. .. versionadded:: 21.1 @@ -94,8 +94,8 @@ class ChatFullInfo(_ChatBase): chats with business accounts, the opening hours of the business. .. versionadded:: 21.1 - personal_chat (:obj:`telegram.Chat`, optional): For private chats, the personal channel of - the user. + personal_chat (:class:`telegram.Chat`, optional): For private chats, the personal channel + of the user. .. versionadded:: 21.1 available_reactions (Sequence[:class:`telegram.ReactionType`], optional): List of available @@ -232,7 +232,7 @@ class ChatFullInfo(_ChatBase): obtained via :meth:`~telegram.Bot.get_chat`. .. versionadded:: 20.0 - birthdate (:obj:`telegram.Birthdate`): Optional. For private chats, + birthdate (:class:`telegram.Birthdate`): Optional. For private chats, the date of birth of the user. .. versionadded:: 21.1 @@ -248,8 +248,8 @@ class ChatFullInfo(_ChatBase): chats with business accounts, the opening hours of the business. .. versionadded:: 21.1 - personal_chat (:obj:`telegram.Chat`): Optional. For private chats, the personal channel of - the user. + personal_chat (:class:`telegram.Chat`): Optional. For private chats, the personal channel + of the user. .. versionadded:: 21.1 available_reactions (Tuple[:class:`telegram.ReactionType`]): Optional. List of available diff --git a/telegram/_files/inputsticker.py b/telegram/_files/inputsticker.py index 89f1db81d..8fc8b8461 100644 --- a/telegram/_files/inputsticker.py +++ b/telegram/_files/inputsticker.py @@ -49,7 +49,7 @@ class InputSticker(TelegramObject): :tg-const:`telegram.constants.StickerLimit.MIN_STICKER_EMOJI` - :tg-const:`telegram.constants.StickerLimit.MAX_STICKER_EMOJI` emoji associated with the sticker. - mask_position (:obj:`telegram.MaskPosition`, optional): Position where the mask should be + mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask should be placed on faces. For ":tg-const:`telegram.constants.StickerType.MASK`" stickers only. keywords (Sequence[:obj:`str`], optional): Sequence of 0-:tg-const:`telegram.constants.StickerLimit.MAX_SEARCH_KEYWORDS` search keywords @@ -71,7 +71,7 @@ class InputSticker(TelegramObject): :tg-const:`telegram.constants.StickerLimit.MIN_STICKER_EMOJI` - :tg-const:`telegram.constants.StickerLimit.MAX_STICKER_EMOJI` emoji associated with the sticker. - mask_position (:obj:`telegram.MaskPosition`): Optional. Position where the mask should be + mask_position (:class:`telegram.MaskPosition`): Optional. Position where the mask should be placed on faces. For ":tg-const:`telegram.constants.StickerType.MASK`" stickers only. keywords (Tuple[:obj:`str`]): Optional. Tuple of 0-:tg-const:`telegram.constants.StickerLimit.MAX_SEARCH_KEYWORDS` search keywords diff --git a/telegram/_giveaway.py b/telegram/_giveaway.py index 0008dc9dd..b287433fe 100644 --- a/telegram/_giveaway.py +++ b/telegram/_giveaway.py @@ -126,7 +126,7 @@ class Giveaway(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["Giveaway"]: - """See :obj:`telegram.TelegramObject.de_json`.""" + """See :meth:`telegram.TelegramObject.de_json`.""" data = cls._parse_data(data) if data is None: @@ -262,7 +262,7 @@ class GiveawayWinners(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["GiveawayWinners"]: - """See :obj:`telegram.TelegramObject.de_json`.""" + """See :meth:`telegram.TelegramObject.de_json`.""" data = cls._parse_data(data) if data is None: @@ -330,7 +330,7 @@ class GiveawayCompleted(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["GiveawayCompleted"]: - """See :obj:`telegram.TelegramObject.de_json`.""" + """See :meth:`telegram.TelegramObject.de_json`.""" data = cls._parse_data(data) if data is None: diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index 6ceca1a31..cff4df66a 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -99,7 +99,7 @@ class InlineKeyboardButton(TelegramObject): .. seealso:: :wiki:`Arbitrary callback_data ` - web_app (:obj:`telegram.WebAppInfo`, optional): Description of the `Web App + web_app (:class:`telegram.WebAppInfo`, optional): Description of the `Web App `_ that will be launched when the user presses the button. The Web App will be able to send an arbitrary message on behalf of the user using the method :meth:`~telegram.Bot.answer_web_app_query`. Available only in @@ -107,16 +107,14 @@ class InlineKeyboardButton(TelegramObject): a Telegram Business account. .. versionadded:: 20.0 - switch_inline_query (:obj:`str`, optional): If set, pressing the button will insert the - bot's username and the specified inline query in the current chat's input field. May be - empty, in which case only the bot's username will be inserted. - - This offers a quick way for the user to open your bot in inline mode in the same chat - - good for selecting something from multiple options. Not supported in channels and for - messages sent on behalf of a Telegram Business account. + switch_inline_query (:obj:`str`, optional): If set, pressing the button will prompt the + user to select one of their chats, open that chat and insert the bot's username and the + specified inline query in the input field. May be empty, in which case just the bot's + username will be inserted. Not supported for messages sent on behalf of a Telegram + Business account. Tip: - This is similar to the new parameter :paramref:`switch_inline_query_chosen_chat`, + This is similar to the parameter :paramref:`switch_inline_query_chosen_chat`, but gives no control over which chats can be selected. switch_inline_query_current_chat (:obj:`str`, optional): If set, pressing the button will insert the bot's username and the specified inline query in the current chat's input @@ -137,7 +135,7 @@ class InlineKeyboardButton(TelegramObject): Note: This type of button **must** always be the first button in the first row and can only be used in invoice messages. - switch_inline_query_chosen_chat (:obj:`telegram.SwitchInlineQueryChosenChat`, optional): + switch_inline_query_chosen_chat (:class:`telegram.SwitchInlineQueryChosenChat`, optional): If set, pressing the button will prompt the user to select one of their chats of the specified type, open that chat and insert the bot's username and the specified inline query in the input field. Not supported for messages sent on behalf of a Telegram @@ -170,7 +168,7 @@ class InlineKeyboardButton(TelegramObject): to the bot when the button is pressed, UTF-8 :tg-const:`telegram.InlineKeyboardButton.MIN_CALLBACK_DATA`- :tg-const:`telegram.InlineKeyboardButton.MAX_CALLBACK_DATA` bytes. - web_app (:obj:`telegram.WebAppInfo`): Optional. Description of the `Web App + web_app (:class:`telegram.WebAppInfo`): Optional. Description of the `Web App `_ that will be launched when the user presses the button. The Web App will be able to send an arbitrary message on behalf of the user using the method :meth:`~telegram.Bot.answer_web_app_query`. Available only in @@ -178,16 +176,14 @@ class InlineKeyboardButton(TelegramObject): a Telegram Business account. .. versionadded:: 20.0 - switch_inline_query (:obj:`str`): Optional. If set, pressing the button will insert the - bot's username and the specified inline query in the current chat's input field. May be - empty, in which case only the bot's username will be inserted. - - This offers a quick way for the user to open your bot in inline mode in the same chat - - good for selecting something from multiple options. Not supported in channels and for - messages sent on behalf of a Telegram Business account. + switch_inline_query (:obj:`str`): Optional. If set, pressing the button will prompt the + user to select one of their chats, open that chat and insert the bot's username and the + specified inline query in the input field. May be empty, in which case just the bot's + username will be inserted. Not supported for messages sent on behalf of a Telegram + Business account. Tip: - This is similar to the new parameter :paramref:`switch_inline_query_chosen_chat`, + This is similar to the parameter :paramref:`switch_inline_query_chosen_chat`, but gives no control over which chats can be selected. switch_inline_query_current_chat (:obj:`str`): Optional. If set, pressing the button will insert the bot's username and the specified inline query in the current chat's input @@ -208,7 +204,7 @@ class InlineKeyboardButton(TelegramObject): Note: This type of button **must** always be the first button in the first row and can only be used in invoice messages. - switch_inline_query_chosen_chat (:obj:`telegram.SwitchInlineQueryChosenChat`): Optional. + switch_inline_query_chosen_chat (:class:`telegram.SwitchInlineQueryChosenChat`): Optional. If set, pressing the button will prompt the user to select one of their chats of the specified type, open that chat and insert the bot's username and the specified inline query in the input field. Not supported for messages sent on behalf of a Telegram diff --git a/telegram/_inline/inlinequeryresultgif.py b/telegram/_inline/inlinequeryresultgif.py index 13e1f253b..e5694e4f8 100644 --- a/telegram/_inline/inlinequeryresultgif.py +++ b/telegram/_inline/inlinequeryresultgif.py @@ -50,16 +50,14 @@ class InlineQueryResultGif(InlineQueryResult): gif_width (:obj:`int`, optional): Width of the GIF. gif_height (:obj:`int`, optional): Height of the GIF. gif_duration (:obj:`int`, optional): Duration of the GIF in seconds. - thumbnail_url (:obj:`str`, optional): URL of the static (JPEG or GIF) or animated (MPEG4) + thumbnail_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. - Warning: - The Bot API does **not** define this as an optional argument. It is formally - optional for backwards compatibility with the deprecated :paramref:`thumb_url`. - If you pass neither :paramref:`thumbnail_url` nor :paramref:`thumb_url`, - :class:`ValueError` will be raised. - .. versionadded:: 20.2 + + ..versionchanged:: 20.5 + |thumbnail_url_mandatory| + thumbnail_mime_type (:obj:`str`, optional): MIME type of the thumbnail, must be one of ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. @@ -82,10 +80,6 @@ class InlineQueryResultGif(InlineQueryResult): .. versionadded:: 21.3 - Raises: - :class:`ValueError`: If neither :paramref:`thumbnail_url` nor :paramref:`thumb_url` is - supplied or if both are supplied and are not equal. - Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.GIF`. id (:obj:`str`): Unique identifier for this result, diff --git a/telegram/_inline/inlinequeryresultmpeg4gif.py b/telegram/_inline/inlinequeryresultmpeg4gif.py index 1fff84841..9e27ab949 100644 --- a/telegram/_inline/inlinequeryresultmpeg4gif.py +++ b/telegram/_inline/inlinequeryresultmpeg4gif.py @@ -51,16 +51,14 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): mpeg4_width (:obj:`int`, optional): Video width. mpeg4_height (:obj:`int`, optional): Video height. mpeg4_duration (:obj:`int`, optional): Video duration in seconds. - thumbnail_url (:obj:`str`, optional): URL of the static (JPEG or GIF) or animated (MPEG4) + thumbnail_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. - Warning: - The Bot API does **not** define this as an optional argument. It is formally - optional for backwards compatibility with the deprecated :paramref:`thumb_url`. - If you pass neither :paramref:`thumbnail_url` nor :paramref:`thumb_url`, - :class:`ValueError` will be raised. - .. versionadded:: 20.2 + + ..versionchanged:: 20.5 + |thumbnail_url_mandatory| + thumbnail_mime_type (:obj:`str`, optional): MIME type of the thumbnail, must be one of ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. @@ -83,9 +81,6 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): show_caption_above_media (:obj:`bool`, optional): Pass |show_cap_above_med| .. versionadded:: 21.3 - Raises: - :class:`ValueError`: If neither :paramref:`thumbnail_url` nor :paramref:`thumb_url` is - supplied or if both are supplied and are not equal. Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.MPEG4GIF`. diff --git a/telegram/_inline/inlinequeryresultphoto.py b/telegram/_inline/inlinequeryresultphoto.py index 637e952d4..b74adf218 100644 --- a/telegram/_inline/inlinequeryresultphoto.py +++ b/telegram/_inline/inlinequeryresultphoto.py @@ -48,15 +48,13 @@ class InlineQueryResultPhoto(InlineQueryResult): :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes. photo_url (:obj:`str`): A valid URL of the photo. Photo must be in JPEG format. Photo size must not exceed 5MB. - thumbnail_url (:obj:`str`, optional): URL of the thumbnail for the photo. - - Warning: - The Bot API does **not** define this as an optional argument. It is formally - optional for backwards compatibility with the deprecated :paramref:`thumb_url`. - If you pass neither :paramref:`thumbnail_url` nor :paramref:`thumb_url`, - :class:`ValueError` will be raised. + thumbnail_url (:obj:`str`): URL of the thumbnail for the photo. .. versionadded:: 20.2 + + ..versionchanged:: 20.5 + |thumbnail_url_mandatory| + photo_width (:obj:`int`, optional): Width of the photo. photo_height (:obj:`int`, optional): Height of the photo. title (:obj:`str`, optional): Title for the result. @@ -78,10 +76,6 @@ class InlineQueryResultPhoto(InlineQueryResult): .. versionadded:: 21.3 - Raises: - :class:`ValueError`: If neither :paramref:`thumbnail_url` nor :paramref:`thumb_url` is - supplied or if both are supplied and are not equal. - Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.PHOTO`. id (:obj:`str`): Unique identifier for this result, diff --git a/telegram/_inline/inlinequeryresultvideo.py b/telegram/_inline/inlinequeryresultvideo.py index 90bf4c86d..bb01c1ac1 100644 --- a/telegram/_inline/inlinequeryresultvideo.py +++ b/telegram/_inline/inlinequeryresultvideo.py @@ -55,20 +55,12 @@ class InlineQueryResultVideo(InlineQueryResult): mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4". thumbnail_url (:obj:`str`, optional): URL of the thumbnail (JPEG only) for the video. - Warning: - The Bot API does **not** define this as an optional argument. It is formally - optional for backwards compatibility with the deprecated :paramref:`thumb_url`. - If you pass neither :paramref:`thumbnail_url` nor :paramref:`thumb_url`, - :class:`ValueError` will be raised. - .. versionadded:: 20.2 - title (:obj:`str`, optional): Title for the result. - Warning: - The Bot API does **not** define this as an optional argument. It is formally - optional to ensure backwards compatibility of :paramref:`thumbnail_url` with the - deprecated :paramref:`thumb_url`, which required that :paramref:`thumbnail_url` - become optional. :class:`TypeError` will be raised if no ``title`` is passed. + ..versionchanged:: 20.5 + |thumbnail_url_mandatory| + + title (:obj:`str`): Title for the result. caption (:obj:`str`, optional): Caption of the video to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. @@ -92,11 +84,6 @@ class InlineQueryResultVideo(InlineQueryResult): .. versionadded:: 21.3 - Raises: - :class:`ValueError`: If neither :paramref:`thumbnail_url` nor :paramref:`thumb_url` is - supplied or if both are supplied and are not equal. - :class:`TypeError`: If no :paramref:`title` is passed. - Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.VIDEO`. id (:obj:`str`): Unique identifier for this result, diff --git a/telegram/_inline/inputinvoicemessagecontent.py b/telegram/_inline/inputinvoicemessagecontent.py index e13642da5..101e0184b 100644 --- a/telegram/_inline/inputinvoicemessagecontent.py +++ b/telegram/_inline/inputinvoicemessagecontent.py @@ -47,7 +47,7 @@ class InputInvoiceMessageContent(InputMessageContent): payload (:obj:`str`): Bot-defined invoice payload. :tg-const:`telegram.Invoice.MIN_PAYLOAD_LENGTH`- :tg-const:`telegram.Invoice.MAX_PAYLOAD_LENGTH` bytes. This will not be displayed - to the user, use for your internal processes. + to the user, use it for your internal processes. provider_token (:obj:`str`): Payment provider token, obtained via `@Botfather `_. Pass an empty string for payments in |tg_stars|. @@ -115,7 +115,7 @@ class InputInvoiceMessageContent(InputMessageContent): payload (:obj:`str`): Bot-defined invoice payload. :tg-const:`telegram.Invoice.MIN_PAYLOAD_LENGTH`- :tg-const:`telegram.Invoice.MAX_PAYLOAD_LENGTH` bytes. This will not be displayed - to the user, use for your internal processes. + to the user, use it for your internal processes. provider_token (:obj:`str`): Payment provider token, obtained via `@Botfather `_. Pass an empty string for payments in `Telegram Stars `_. diff --git a/telegram/_message.py b/telegram/_message.py index 5e416ab7a..48e34583e 100644 --- a/telegram/_message.py +++ b/telegram/_message.py @@ -569,22 +569,22 @@ class Message(MaybeInaccessibleMessage): .. versionadded:: 21.1 - sender_business_bot (:obj:`telegram.User`, optional): The bot that actually sent the + sender_business_bot (:class:`telegram.User`, optional): The bot that actually sent the message on behalf of the business account. Available only for outgoing messages sent on behalf of the connected business account. .. versionadded:: 21.1 - chat_background_set (:obj:`telegram.ChatBackground`, optional): Service message: chat + chat_background_set (:class:`telegram.ChatBackground`, optional): Service message: chat background set. .. versionadded:: 21.2 - paid_media (:obj:`telegram.PaidMediaInfo`, optional): Message contains paid media; + paid_media (:class:`telegram.PaidMediaInfo`, optional): Message contains paid media; information about the paid media. .. versionadded:: 21.4 - refunded_payment (:obj:`telegram.RefundedPayment`, optional): Message is a service message - about a refunded payment, information about the payment. + refunded_payment (:class:`telegram.RefundedPayment`, optional): Message is a service + message about a refunded payment, information about the payment. .. versionadded:: 21.4 @@ -895,22 +895,22 @@ class Message(MaybeInaccessibleMessage): .. versionadded:: 21.1 - sender_business_bot (:obj:`telegram.User`): Optional. The bot that actually sent the + sender_business_bot (:class:`telegram.User`): Optional. The bot that actually sent the message on behalf of the business account. Available only for outgoing messages sent on behalf of the connected business account. .. versionadded:: 21.1 - chat_background_set (:obj:`telegram.ChatBackground`): Optional. Service message: chat + chat_background_set (:class:`telegram.ChatBackground`): Optional. Service message: chat background set .. versionadded:: 21.2 - paid_media (:obj:`telegram.PaidMediaInfo`): Optional. Message contains paid media; + paid_media (:class:`telegram.PaidMediaInfo`): Optional. Message contains paid media; information about the paid media. .. versionadded:: 21.4 - refunded_payment (:obj:`telegram.RefundedPayment`): Optional. Message is a service message - about a refunded payment, information about the payment. + refunded_payment (:class:`telegram.RefundedPayment`): Optional. Message is a service + message about a refunded payment, information about the payment. .. versionadded:: 21.4 diff --git a/telegram/_passport/credentials.py b/telegram/_passport/credentials.py index fab0b6eb2..7345991a5 100644 --- a/telegram/_passport/credentials.py +++ b/telegram/_passport/credentials.py @@ -112,7 +112,7 @@ class EncryptedCredentials(TelegramObject): Note: This object is decrypted only when originating from - :obj:`telegram.PassportData.decrypted_credentials`. + :attr:`telegram.PassportData.decrypted_credentials`. Args: data (:class:`telegram.Credentials` | :obj:`str`): Decrypted data with unique user's diff --git a/telegram/_passport/encryptedpassportelement.py b/telegram/_passport/encryptedpassportelement.py index b05003f2c..9f16d81e0 100644 --- a/telegram/_passport/encryptedpassportelement.py +++ b/telegram/_passport/encryptedpassportelement.py @@ -42,7 +42,7 @@ class EncryptedPassportElement(TelegramObject): Note: This object is decrypted only when originating from - :obj:`telegram.PassportData.decrypted_data`. + :attr:`telegram.PassportData.decrypted_data`. Args: type (:obj:`str`): Element type. One of "personal_details", "passport", "driver_license", diff --git a/telegram/_passport/passportfile.py b/telegram/_passport/passportfile.py index 61b704862..84a1ce201 100644 --- a/telegram/_passport/passportfile.py +++ b/telegram/_passport/passportfile.py @@ -203,7 +203,7 @@ class PassportFile(TelegramObject): """ Wrapper over :meth:`telegram.Bot.get_file`. Will automatically assign the correct credentials to the returned :class:`telegram.File` if originating from - :obj:`telegram.PassportData.decrypted_data`. + :attr:`telegram.PassportData.decrypted_data`. For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`. diff --git a/telegram/_payment/stars.py b/telegram/_payment/stars.py index 0baebd39d..ed83aabc2 100644 --- a/telegram/_payment/stars.py +++ b/telegram/_payment/stars.py @@ -75,6 +75,17 @@ class RevenueWithdrawalState(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["RevenueWithdrawalState"]: + """Converts JSON data to the appropriate :class:`RevenueWithdrawalState` object, i.e. takes + care of selecting the correct subclass. + + Args: + data (Dict[:obj:`str`, ...]): The JSON data. + bot (:class:`telegram.Bot`): The bot associated with this object. + + Returns: + The Telegram object. + + """ data = cls._parse_data(data) if not data: @@ -151,6 +162,7 @@ class RevenueWithdrawalStateSucceeded(RevenueWithdrawalState): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["RevenueWithdrawalStateSucceeded"]: + """See :meth:`telegram.RevenueWithdrawalState.de_json`.""" data = cls._parse_data(data) if not data: @@ -261,13 +273,13 @@ class TransactionPartnerFragment(TransactionPartner): .. versionadded:: 21.4 Args: - withdrawal_state (:obj:`telegram.RevenueWithdrawalState`, optional): State of the + withdrawal_state (:class:`telegram.RevenueWithdrawalState`, optional): State of the transaction if the transaction is outgoing. Attributes: type (:obj:`str`): The type of the transaction partner, always :tg-const:`telegram.TransactionPartner.FRAGMENT`. - withdrawal_state (:obj:`telegram.RevenueWithdrawalState`): Optional. State of the + withdrawal_state (:class:`telegram.RevenueWithdrawalState`): Optional. State of the transaction if the transaction is outgoing. """ @@ -288,6 +300,7 @@ class TransactionPartnerFragment(TransactionPartner): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["TransactionPartnerFragment"]: + """See :meth:`telegram.TransactionPartner.de_json`.""" data = cls._parse_data(data) if not data: @@ -356,6 +369,7 @@ class TransactionPartnerUser(TransactionPartner): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["TransactionPartnerUser"]: + """See :meth:`telegram.TransactionPartner.de_json`.""" data = cls._parse_data(data) if not data: @@ -468,6 +482,7 @@ class StarTransaction(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["StarTransaction"]: + """See :meth:`telegram.TelegramObject.de_json`.""" data = cls._parse_data(data) if not data: @@ -514,6 +529,7 @@ class StarTransactions(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["StarTransactions"]: + """See :meth:`telegram.TelegramObject.de_json`.""" data = cls._parse_data(data) if data is None: diff --git a/telegram/_reply.py b/telegram/_reply.py index 222e522a6..65e426657 100644 --- a/telegram/_reply.py +++ b/telegram/_reply.py @@ -250,7 +250,7 @@ class ExternalReplyInfo(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["ExternalReplyInfo"]: - """See :obj:`telegram.TelegramObject.de_json`.""" + """See :meth:`telegram.TelegramObject.de_json`.""" data = cls._parse_data(data) if data is None: @@ -299,7 +299,8 @@ class TextQuote(TelegramObject): message. position (:obj:`int`): Approximate quote position in the original message in UTF-16 code units as specified by the sender. - entities (Sequence[:obj:`telegram.MessageEntity`], optional): Special entities that appear + entities (Sequence[:class:`telegram.MessageEntity`], optional): Special entities that + appear in the quote. Currently, only bold, italic, underline, strikethrough, spoiler, and custom_emoji entities are kept in quotes. is_manual (:obj:`bool`, optional): :obj:`True`, if the quote was chosen manually by the @@ -310,7 +311,7 @@ class TextQuote(TelegramObject): message. position (:obj:`int`): Approximate quote position in the original message in UTF-16 code units as specified by the sender. - entities (Tuple[:obj:`telegram.MessageEntity`]): Optional. Special entities that appear + entities (Tuple[:class:`telegram.MessageEntity`]): Optional. Special entities that appear in the quote. Currently, only bold, italic, underline, strikethrough, spoiler, and custom_emoji entities are kept in quotes. is_manual (:obj:`bool`): Optional. :obj:`True`, if the quote was chosen manually by the @@ -351,7 +352,7 @@ class TextQuote(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["TextQuote"]: - """See :obj:`telegram.TelegramObject.de_json`.""" + """See :meth:`telegram.TelegramObject.de_json`.""" data = cls._parse_data(data) if data is None: @@ -387,7 +388,8 @@ class ReplyParameters(TelegramObject): quote_parse_mode (:obj:`str`, optional): Mode for parsing entities in the quote. See :wiki:`formatting options ` for more details. - quote_entities (Sequence[:obj:`telegram.MessageEntity`], optional): A JSON-serialized list + quote_entities (Sequence[:class:`telegram.MessageEntity`], optional): A JSON-serialized + list of special entities that appear in the quote. It can be specified instead of :paramref:`quote_parse_mode`. quote_position (:obj:`int`, optional): Position of the quote in the original message in @@ -409,8 +411,8 @@ class ReplyParameters(TelegramObject): quote_parse_mode (:obj:`str`): Optional. Mode for parsing entities in the quote. See :wiki:`formatting options ` for more details. - quote_entities (Tuple[:obj:`telegram.MessageEntity`]): Optional. A JSON-serialized list of - special entities that appear in the quote. It can be specified instead of + quote_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. A JSON-serialized list + of special entities that appear in the quote. It can be specified instead of :paramref:`quote_parse_mode`. quote_position (:obj:`int`): Optional. Position of the quote in the original message in UTF-16 code units. @@ -458,7 +460,7 @@ class ReplyParameters(TelegramObject): def de_json( cls, data: Optional[JSONDict], bot: Optional["Bot"] = None ) -> Optional["ReplyParameters"]: - """See :obj:`telegram.TelegramObject.de_json`.""" + """See :meth:`telegram.TelegramObject.de_json`.""" data = cls._parse_data(data) if data is None: diff --git a/telegram/_telegramobject.py b/telegram/_telegramobject.py index 6666b49b2..504075532 100644 --- a/telegram/_telegramobject.py +++ b/telegram/_telegramobject.py @@ -354,7 +354,7 @@ class TelegramObject: memodict (:obj:`dict`): A dictionary that maps objects to their copies. Returns: - :obj:`telegram.TelegramObject`: The copied object. + :class:`telegram.TelegramObject`: The copied object. """ bot = self._bot # Save bot so we can set it after copying self.set_bot(None) # set to None so it is not deepcopied diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py index de105e28b..fe5b8a79d 100644 --- a/telegram/ext/filters.py +++ b/telegram/ext/filters.py @@ -302,7 +302,7 @@ class BaseFilter: class MessageFilter(BaseFilter): """Base class for all Message Filters. In contrast to :class:`UpdateFilter`, the object passed - to :meth:`filter` is :obj:`telegram.Update.effective_message`. + to :meth:`filter` is :attr:`telegram.Update.effective_message`. Please see :class:`BaseFilter` for details on how to create custom filters.