From f58ec82111ad61490dd7cccf9dd1a334ee8d324d Mon Sep 17 00:00:00 2001 From: Harshil <37377066+harshil21@users.noreply.github.com> Date: Wed, 20 May 2026 06:45:22 -0400 Subject: [PATCH 1/3] Autogen Raises: block, fix kwargs and admonition insertion bug --- .../{kwargs_insertion.py => bot_insertion.py} | 14 + docs/auxil/sphinx_hooks.py | 22 +- src/telegram/_bot.py | 569 +----------------- 3 files changed, 33 insertions(+), 572 deletions(-) rename docs/auxil/{kwargs_insertion.py => bot_insertion.py} (90%) diff --git a/docs/auxil/kwargs_insertion.py b/docs/auxil/bot_insertion.py similarity index 90% rename from docs/auxil/kwargs_insertion.py rename to docs/auxil/bot_insertion.py index b2f05f8741b..008f5413856 100644 --- a/docs/auxil/kwargs_insertion.py +++ b/docs/auxil/bot_insertion.py @@ -83,6 +83,13 @@ " ``2``.", ] +RAISES_BLOCK = [ + "Raises:", + "", + " :class:`telegram.error.TelegramError`", + "", +] + def find_insert_pos_for_kwargs(lines: list[str]) -> int: """Finds the correct position to insert the keyword arguments and returns the index.""" @@ -92,6 +99,13 @@ def find_insert_pos_for_kwargs(lines: list[str]) -> int: return False +def find_insert_pos_for_raises(lines: list[str]) -> int: + """Finds the correct position to insert the Raises block and returns the index.""" + if "Raises:" in lines: + return -1 # Don't insert if there's already a Raises block + return len(lines) # Insert at the end if there's no Raises block + + def check_timeout_and_api_kwargs_presence(obj: object) -> int: """Checks if the method has timeout and api_kwargs keyword only parameters.""" sig = inspect.signature(obj) diff --git a/docs/auxil/sphinx_hooks.py b/docs/auxil/sphinx_hooks.py index 7183a0dbaf7..1f0082369ad 100644 --- a/docs/auxil/sphinx_hooks.py +++ b/docs/auxil/sphinx_hooks.py @@ -27,9 +27,11 @@ import telegram import telegram.ext from docs.auxil.admonition_inserter import AdmonitionInserter -from docs.auxil.kwargs_insertion import ( +from docs.auxil.bot_insertion import ( + RAISES_BLOCK, check_timeout_and_api_kwargs_presence, find_insert_pos_for_kwargs, + find_insert_pos_for_raises, get_updates_read_timeout_addition, keyword_args, media_write_timeout_change, @@ -84,8 +86,8 @@ def autodoc_process_docstring( app: Sphinx, what, name: str, obj: object, options, lines: list[str] ): """We do the following things: - 1) Use this method to automatically insert the Keyword Args and "Shortcuts" admonitions - for the Bot methods. + 1) Use this method to automatically insert the Keyword Args, "Shortcuts" admonitions, + and the Raises block, wherever applicable, for the Bot methods. 2) Use this method to automatically insert "Returned in" admonition into classes that are returned from the Bot methods @@ -101,13 +103,15 @@ def autodoc_process_docstring( """ # 1) Insert the Keyword Args and "Shortcuts" admonitions for the Bot methods - method_name = name.rsplit(".", maxsplit=1)[0] + method_name = name.rsplit(".", maxsplit=1)[-1] if ( name.startswith("telegram.Bot.") and what == "method" and method_name.islower() and check_timeout_and_api_kwargs_presence(obj) ): + # Logic for inserting keyword args into docstrings: + # ------------------------------------------------- insert_index = find_insert_pos_for_kwargs(lines) if not insert_index: raise ValueError( @@ -133,6 +137,16 @@ def autodoc_process_docstring( lines[insert_idx:insert_idx] = effective_insert insert_idx += len(effective_insert) + # Logic for inserting Raises: + # ------------------------------------------------- + # We will only insert the Raises block if there isn't already one. + + insert_index = find_insert_pos_for_raises(lines) + if insert_index != -1: + lines[insert_index:insert_index] = RAISES_BLOCK + + # Logic for inserting "Shortcuts" admonition: + # ------------------------------------------- ADMONITION_INSERTER.insert_admonitions( obj=typing.cast("collections.abc.Callable", obj), docstring_lines=lines, diff --git a/src/telegram/_bot.py b/src/telegram/_bot.py index d9d1f83b069..bebe9a80b3a 100644 --- a/src/telegram/_bot.py +++ b/src/telegram/_bot.py @@ -925,9 +925,6 @@ async def do_api_request( The result of the API call. If :paramref:`return_type` is not specified, this is a :obj:`dict` or :obj:`bool`, otherwise an instance of :paramref:`return_type` or a tuple of :paramref:`return_type`. - - Raises: - :class:`telegram.error.TelegramError` """ if hasattr(self, endpoint): self._warn( @@ -985,10 +982,6 @@ async def get_me( Returns: :class:`telegram.User`: A :class:`telegram.User` instance representing that bot if the credentials are valid, :obj:`None` otherwise. - - Raises: - :class:`telegram.error.TelegramError` - """ result = await self._post( "getMe", @@ -1189,10 +1182,6 @@ async def delete_message( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "message_id": message_id} return await self._post( @@ -1249,10 +1238,6 @@ async def send_message_draft( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -1299,9 +1284,6 @@ async def delete_messages( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"chat_id": chat_id, "message_ids": message_ids} return await self._post( @@ -1378,9 +1360,6 @@ async def forward_message( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -1449,9 +1428,6 @@ async def forward_messages( Returns: tuple[:class:`telegram.Message`]: On success, a tuple of ``MessageId`` of sent messages is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -1601,9 +1577,6 @@ async def send_photo( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -1776,9 +1749,6 @@ async def send_audio( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -1944,9 +1914,6 @@ async def send_document( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -2082,10 +2049,6 @@ async def send_sticker( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -2275,10 +2238,6 @@ async def send_video( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -2447,10 +2406,6 @@ async def send_video_note( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -2627,10 +2582,6 @@ async def send_animation( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -2799,10 +2750,6 @@ async def send_voice( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -2952,9 +2899,6 @@ async def send_media_group( Returns: tuple[:class:`telegram.Message`]: An array of the sent Messages. - - Raises: - :class:`telegram.error.TelegramError` """ if caption and any( [ @@ -3137,10 +3081,6 @@ async def send_location( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ if not ((latitude is not None and longitude is not None) or location): raise ValueError( @@ -3464,10 +3404,6 @@ async def send_venue( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ # The venue parameter is a convenience functionality added by us, so enforcing the # mutual exclusivity here is nothing that Telegram would handle anyway @@ -3622,10 +3558,6 @@ async def send_contact( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ # The contact parameter is a convenience functionality added by us, so enforcing the # mutual exclusivity here is nothing that Telegram would handle anyway @@ -3748,10 +3680,6 @@ async def send_game( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "game_short_name": game_short_name} @@ -3808,10 +3736,6 @@ async def send_chat_action( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -3988,10 +3912,6 @@ async def answer_inline_query( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ effective_results, next_offset = self._effective_inline_results( results=results, next_offset=next_offset, current_offset=current_offset @@ -4055,9 +3975,6 @@ async def save_prepared_inline_message( Returns: :class:`telegram.PreparedInlineMessage`: On success, the prepared message is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -4105,10 +4022,6 @@ async def get_user_profile_photos( Returns: :class:`telegram.UserProfilePhotos` - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"user_id": user_id, "offset": offset, "limit": limit} @@ -4171,10 +4084,6 @@ async def get_file( Returns: :class:`telegram.File` - - Raises: - :class:`telegram.error.TelegramError` - """ # Try to get the file_id from the object, if it fails, assume it's a string with contextlib.suppress(AttributeError): @@ -4237,10 +4146,6 @@ async def ban_chat_member( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -4285,10 +4190,6 @@ async def ban_chat_sender_chat( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "sender_chat_id": sender_chat_id} @@ -4329,10 +4230,6 @@ async def unban_chat_member( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "user_id": user_id, "only_if_banned": only_if_banned} @@ -4369,10 +4266,6 @@ async def unban_chat_sender_chat( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "sender_chat_id": sender_chat_id} @@ -4432,10 +4325,6 @@ async def answer_callback_query( Returns: :obj:`bool` On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "callback_query_id": callback_query_id, @@ -4615,10 +4504,6 @@ async def edit_message_caption( Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the edited message is returned, otherwise :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -4689,9 +4574,6 @@ async def edit_message_media( Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the edited Message is returned, otherwise :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "media": media, @@ -4750,10 +4632,6 @@ async def edit_message_reply_markup( Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the edited message is returned, otherwise :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -4834,10 +4712,6 @@ async def get_updates( Returns: tuple[:class:`telegram.Update`] - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "timeout": timeout, @@ -4984,8 +4858,7 @@ async def set_webhook( Returns: :obj:`bool` On success, :obj:`True` is returned. - Raises: - :class:`telegram.error.TelegramError` + .. _`guide to Webhooks`: https://core.telegram.org/bots/webhooks @@ -5030,10 +4903,6 @@ async def delete_webhook( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data = {"drop_pending_updates": drop_pending_updates} @@ -5064,10 +4933,6 @@ async def leave_chat( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} @@ -5103,10 +4968,6 @@ async def get_chat( Returns: :class:`telegram.ChatFullInfo` - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} @@ -5146,10 +5007,6 @@ async def get_chat_administrators( objects that contains information about all chat administrators except other bots. If the chat is a group or a supergroup and no administrators were appointed, only the creator will be returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} result = await self._post( @@ -5182,10 +5039,6 @@ async def get_chat_member_count( Returns: :obj:`int`: Number of members in the chat. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} return await self._post( @@ -5218,10 +5071,6 @@ async def get_chat_member( Returns: :class:`telegram.ChatMember` - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "user_id": user_id} result = await self._post( @@ -5430,10 +5279,6 @@ async def get_game_high_scores( Returns: tuple[:class:`telegram.GameHighScore`] - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "user_id": user_id, @@ -5637,10 +5482,6 @@ async def send_invoice( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -5724,10 +5565,6 @@ async def answer_shipping_query( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "shipping_query_id": shipping_query_id, @@ -5781,10 +5618,6 @@ async def answer_pre_checkout_query( Returns: :obj:`bool`: On success, :obj:`True` is returned - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "pre_checkout_query_id": pre_checkout_query_id, @@ -5826,10 +5659,6 @@ async def answer_web_app_query( Returns: :class:`telegram.SentWebAppMessage`: On success, a sent :class:`telegram.SentWebAppMessage` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "web_app_query_id": web_app_query_id, @@ -5897,9 +5726,6 @@ async def restrict_chat_member( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -6021,10 +5847,6 @@ async def promote_chat_member( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -6096,10 +5918,6 @@ async def set_chat_permissions( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -6141,10 +5959,6 @@ async def set_chat_administrator_custom_title( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "user_id": user_id, "custom_title": custom_title} @@ -6185,10 +5999,6 @@ async def export_chat_invite_link( Returns: :obj:`str`: New invite link on success. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} return await self._post( @@ -6251,10 +6061,6 @@ async def create_chat_invite_link( Returns: :class:`telegram.ChatInviteLink` - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -6328,10 +6134,6 @@ async def edit_chat_invite_link( Returns: :class:`telegram.ChatInviteLink` - - Raises: - :class:`telegram.error.TelegramError` - """ link = invite_link.invite_link if isinstance(invite_link, ChatInviteLink) else invite_link data: JSONDict = { @@ -6382,10 +6184,6 @@ async def revoke_chat_invite_link( Returns: :class:`telegram.ChatInviteLink` - - Raises: - :class:`telegram.error.TelegramError` - """ link = invite_link.invite_link if isinstance(invite_link, ChatInviteLink) else invite_link data: JSONDict = {"chat_id": chat_id, "invite_link": link} @@ -6426,9 +6224,6 @@ async def approve_chat_join_request( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"chat_id": chat_id, "user_id": user_id} @@ -6466,9 +6261,6 @@ async def decline_chat_join_request( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"chat_id": chat_id, "user_id": user_id} @@ -6512,10 +6304,6 @@ async def set_chat_photo( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "photo": self._parse_file_input(photo)} return await self._post( @@ -6548,10 +6336,6 @@ async def delete_chat_photo( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} return await self._post( @@ -6588,10 +6372,6 @@ async def set_chat_title( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "title": title} return await self._post( @@ -6628,10 +6408,6 @@ async def set_chat_description( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "description": description} @@ -6675,10 +6451,6 @@ async def set_user_emoji_status( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "user_id": user_id, @@ -6728,10 +6500,6 @@ async def pin_chat_message( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -6781,10 +6549,6 @@ async def unpin_chat_message( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -6824,10 +6588,6 @@ async def unpin_all_chat_messages( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} return await self._post( @@ -6857,10 +6617,6 @@ async def get_sticker_set( Returns: :class:`telegram.StickerSet` - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"name": name} result = await self._post( @@ -6900,10 +6656,6 @@ async def get_custom_emoji_stickers( Returns: tuple[:class:`telegram.Sticker`] - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"custom_emoji_ids": custom_emoji_ids} result = await self._post( @@ -6956,10 +6708,6 @@ async def upload_sticker_file( Returns: :class:`telegram.File`: On success, the uploaded File is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "user_id": user_id, @@ -7015,10 +6763,6 @@ async def add_sticker_to_set( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "user_id": user_id, @@ -7059,10 +6803,6 @@ async def set_sticker_position_in_set( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "sticker": sticker if isinstance(sticker, str) else sticker.file_id, @@ -7147,9 +6887,6 @@ async def create_new_sticker_set( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -7191,10 +6928,6 @@ async def delete_sticker_from_set( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"sticker": sticker if isinstance(sticker, str) else sticker.file_id} return await self._post( @@ -7227,10 +6960,6 @@ async def delete_sticker_set( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"name": name} return await self._post( @@ -7300,10 +7029,6 @@ async def set_sticker_set_thumbnail( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "name": name, @@ -7346,10 +7071,6 @@ async def set_sticker_set_title( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"name": name, "title": title} return await self._post( @@ -7392,9 +7113,6 @@ async def set_sticker_emoji_list( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "sticker": sticker if isinstance(sticker, str) else sticker.file_id, @@ -7440,9 +7158,6 @@ async def set_sticker_keywords( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "sticker": sticker if isinstance(sticker, str) else sticker.file_id, @@ -7487,9 +7202,6 @@ async def set_sticker_mask_position( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "sticker": sticker if isinstance(sticker, str) else sticker.file_id, @@ -7529,10 +7241,6 @@ async def set_custom_emoji_sticker_set_thumbnail( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"name": name, "custom_emoji_id": custom_emoji_id} @@ -7576,10 +7284,6 @@ async def set_passport_data_errors( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"user_id": user_id, "errors": errors} return await self._post( @@ -7793,10 +7497,6 @@ async def send_poll( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ if correct_option_id is not None: @@ -7886,10 +7586,6 @@ async def stop_poll( Returns: :class:`telegram.Poll`: On success, the stopped Poll is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -7961,10 +7657,6 @@ async def send_checklist( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -8022,10 +7714,6 @@ async def edit_message_checklist( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -8142,10 +7830,6 @@ async def send_dice( Returns: :class:`telegram.Message`: On success, the sent Message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "emoji": emoji} @@ -8194,9 +7878,6 @@ async def get_my_default_administrator_rights( Returns: :class:`telegram.ChatAdministratorRights`: On success. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"for_channels": for_channels} @@ -8292,10 +7973,6 @@ async def get_my_commands( Returns: tuple[:class:`telegram.BotCommand`]: On success, the commands set for the bot. An empty tuple is returned if commands are not set. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"scope": scope, "language_code": language_code} @@ -8357,10 +8034,6 @@ async def set_my_commands( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ cmds = [c if isinstance(c, BotCommand) else BotCommand(c[0], c[1]) for c in commands] data: JSONDict = {"commands": cmds, "scope": scope, "language_code": language_code} @@ -8406,9 +8079,6 @@ async def delete_my_commands( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"scope": scope, "language_code": language_code} @@ -8440,10 +8110,6 @@ async def log_out( Returns: :obj:`True`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ return await self._post( "logOut", @@ -8471,10 +8137,6 @@ async def close( Returns: :obj:`True`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ return await self._post( "close", @@ -8593,10 +8255,6 @@ async def copy_message( Returns: :class:`telegram.MessageId`: On success, the :class:`telegram.MessageId` of the sent message is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ if allow_sending_without_reply is not DEFAULT_NONE and reply_parameters is not None: raise ValueError( @@ -8697,10 +8355,6 @@ async def copy_messages( Returns: tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId` of the sent messages is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -8977,10 +8631,6 @@ async def get_forum_topic_icon_stickers( Returns: tuple[:class:`telegram.Sticker`] - - Raises: - :class:`telegram.error.TelegramError` - """ result = await self._post( "getForumTopicIconStickers", @@ -9030,9 +8680,6 @@ async def create_forum_topic( Returns: :class:`telegram.ForumTopic` - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -9087,10 +8734,6 @@ async def edit_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -9133,10 +8776,6 @@ async def close_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -9177,10 +8816,6 @@ async def reopen_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -9221,10 +8856,6 @@ async def delete_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -9266,10 +8897,6 @@ async def unpin_all_forum_topic_messages( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -9308,9 +8935,6 @@ async def unpin_all_general_forum_topic_messages( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"chat_id": chat_id} @@ -9350,10 +8974,6 @@ async def edit_general_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id, "name": name} @@ -9389,10 +9009,6 @@ async def close_general_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} @@ -9429,10 +9045,6 @@ async def reopen_general_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} @@ -9469,10 +9081,6 @@ async def hide_general_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} @@ -9508,10 +9116,6 @@ async def unhide_general_forum_topic( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"chat_id": chat_id} @@ -9553,10 +9157,6 @@ async def set_my_description( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"description": description, "language_code": language_code} @@ -9598,10 +9198,6 @@ async def set_my_short_description( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"short_description": short_description, "language_code": language_code} @@ -9634,10 +9230,6 @@ async def get_my_description( Returns: :class:`telegram.BotDescription`: On success, the bot description is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data = {"language_code": language_code} return BotDescription.de_json( @@ -9673,10 +9265,6 @@ async def get_my_short_description( Returns: :class:`telegram.BotShortDescription`: On success, the bot short description is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data = {"language_code": language_code} return BotShortDescription.de_json( @@ -9723,10 +9311,6 @@ async def set_my_name( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = {"name": name, "language_code": language_code} @@ -9759,10 +9343,6 @@ async def get_my_name( Returns: :class:`telegram.BotName`: On success, the bot name is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data = {"language_code": language_code} return BotName.de_json( @@ -9802,9 +9382,6 @@ async def get_user_chat_boosts( Returns: :class:`telegram.UserChatBoosts`: On success, the object containing the list of boosts is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"chat_id": chat_id, "user_id": user_id} return UserChatBoosts.de_json( @@ -9865,9 +9442,6 @@ async def set_message_reaction( Returns: :obj:`bool` On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ allowed_reactions: set[str] = set(ReactionEmoji) parsed_reaction = ( @@ -9961,9 +9535,6 @@ async def gift_premium_subscription( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -10004,9 +9575,6 @@ async def get_business_connection( Returns: :class:`telegram.BusinessConnection`: On success, the object containing the business connection information is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"business_connection_id": business_connection_id} return BusinessConnection.de_json( @@ -10087,9 +9655,6 @@ async def get_business_account_gifts( Returns: :class:`telegram.OwnedGifts` - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10138,9 +9703,6 @@ async def get_business_account_star_balance( Returns: :class:`telegram.StarAmount` - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"business_connection_id": business_connection_id} return StarAmount.de_json( @@ -10185,9 +9747,6 @@ async def read_business_message( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10235,9 +9794,6 @@ async def delete_business_messages( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10317,9 +9873,6 @@ async def post_story( Returns: :class:`Story` - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10397,9 +9950,6 @@ async def edit_story( Returns: :class:`Story` - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10445,9 +9995,6 @@ async def delete_story( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10492,9 +10039,6 @@ async def set_business_account_name( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10535,9 +10079,6 @@ async def set_business_account_username( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10577,9 +10118,6 @@ async def set_business_account_bio( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10624,9 +10162,6 @@ async def set_business_account_gift_settings( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10671,10 +10206,6 @@ async def set_business_account_profile_photo( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10718,9 +10249,6 @@ async def remove_business_account_profile_photo( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10761,9 +10289,6 @@ async def convert_gift_to_stars( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10816,9 +10341,6 @@ async def upgrade_gift( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10873,9 +10395,6 @@ async def transfer_gift( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10919,9 +10438,6 @@ async def transfer_business_account_stars( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -10970,9 +10486,6 @@ async def replace_sticker_in_set( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -11012,10 +10525,6 @@ async def refund_star_payment( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "user_id": user_id, @@ -11056,9 +10565,6 @@ async def get_star_transactions( Returns: :class:`telegram.StarTransactions`: On success. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = {"offset": offset, "limit": limit} @@ -11104,9 +10610,6 @@ async def edit_user_star_subscription( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -11210,9 +10713,6 @@ async def send_paid_media( Returns: :class:`telegram.Message`: On success, the sent message is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { @@ -11287,10 +10787,6 @@ async def create_chat_subscription_invite_link( Returns: :class:`telegram.ChatInviteLink` - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "chat_id": chat_id, @@ -11340,10 +10836,6 @@ async def edit_chat_subscription_invite_link( Returns: :class:`telegram.ChatInviteLink` - - Raises: - :class:`telegram.error.TelegramError` - """ link = invite_link.invite_link if isinstance(invite_link, ChatInviteLink) else invite_link data: JSONDict = { @@ -11380,9 +10872,6 @@ async def get_available_gifts( Returns: :class:`telegram.Gifts` - - Raises: - :class:`telegram.error.TelegramError` """ return Gifts.de_json( await self._post( @@ -11455,9 +10944,6 @@ async def send_gift( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -11502,9 +10988,6 @@ async def verify_chat( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -11544,9 +11027,6 @@ async def verify_user( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -11582,9 +11062,6 @@ async def remove_chat_verification( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -11619,9 +11096,6 @@ async def remove_user_verification( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -11651,9 +11125,6 @@ async def get_my_star_balance( Returns: :class:`telegram.StarAmount` - - Raises: - :class:`telegram.error.TelegramError` """ return StarAmount.de_json( await self._post( @@ -11698,9 +11169,6 @@ async def approve_suggested_post( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -11745,9 +11213,6 @@ async def decline_suggested_post( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -11807,9 +11272,6 @@ async def repost_story( Returns: :class:`telegram.Story` - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "business_connection_id": business_connection_id, @@ -11878,9 +11340,6 @@ async def get_user_gifts( Returns: :class:`telegram.OwnedGifts`: The owned gifts for the user. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -11961,9 +11420,6 @@ async def get_chat_gifts( Returns: :class:`telegram.OwnedGifts`: The owned gifts for the chat. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { @@ -12011,10 +11467,6 @@ async def set_my_profile_photo( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ data: JSONDict = { "photo": photo, @@ -12045,10 +11497,6 @@ async def remove_my_profile_photo( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` - """ return await self._post( @@ -12088,9 +11536,6 @@ async def get_user_profile_audios( Returns: :class:`telegram.UserProfileAudios` - - Raises: - :class:`telegram.error.TelegramError` """ data = { @@ -12139,9 +11584,6 @@ async def set_chat_member_tag( Returns: :obj:`bool`: On success, :obj:`True` is returned. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "chat_id": chat_id, @@ -12179,9 +11621,6 @@ async def get_managed_bot_token( Returns: :obj:`str`: The token of the managed bot. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -12217,9 +11656,6 @@ async def replace_managed_bot_token( Returns: :obj:`str`: The new token of the managed bot. - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, @@ -12261,9 +11697,6 @@ async def save_prepared_keyboard_button( Returns: :class:`telegram.PreparedKeyboardButton` - - Raises: - :class:`telegram.error.TelegramError` """ data: JSONDict = { "user_id": user_id, From a171534db1c16e5dc2f0ab9e81c91b61d5f94772 Mon Sep 17 00:00:00 2001 From: Harshil <37377066+harshil21@users.noreply.github.com> Date: Tue, 26 May 2026 07:42:25 -0400 Subject: [PATCH 2/3] Review: keyword args doc for do_api_request --- src/telegram/_bot.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/telegram/_bot.py b/src/telegram/_bot.py index bebe9a80b3a..571c7390041 100644 --- a/src/telegram/_bot.py +++ b/src/telegram/_bot.py @@ -921,6 +921,20 @@ async def do_api_request( instances of this class. If not specified, the raw result of the API call will be returned. + Keyword Args: + read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to + :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to + :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. + write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to + :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to + :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. + connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to + :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to + :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. + pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to + :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to + :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. + Returns: The result of the API call. If :paramref:`return_type` is not specified, this is a :obj:`dict` or :obj:`bool`, otherwise an instance of :paramref:`return_type` or a From 70d074e0b7e484cc83c5501dbcf924116d2fadb1 Mon Sep 17 00:00:00 2001 From: Harshil <37377066+harshil21@users.noreply.github.com> Date: Tue, 26 May 2026 07:45:27 -0400 Subject: [PATCH 3/3] Review: Update changelog --- changes/unreleased/5240.iJXyH8RNWNNQpC47SfNHzw.toml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/changes/unreleased/5240.iJXyH8RNWNNQpC47SfNHzw.toml b/changes/unreleased/5240.iJXyH8RNWNNQpC47SfNHzw.toml index 3de543f6010..24424c4695a 100644 --- a/changes/unreleased/5240.iJXyH8RNWNNQpC47SfNHzw.toml +++ b/changes/unreleased/5240.iJXyH8RNWNNQpC47SfNHzw.toml @@ -1,5 +1,6 @@ documentation = "Documentation Improvements" -[[pull_requests]] -uid = "5240" -author_uids = ["harshil21"] -closes_threads = [] + +pull_requests = [ + { uid = "5240", author_uids = ["harshil21", "Poolitzer"] }, + { uid = "5241", author_uids = ["harshil21"] }, +] \ No newline at end of file