From 940a4927d135bff78ee7c07112b2636d78f0d688 Mon Sep 17 00:00:00 2001 From: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com> Date: Thu, 24 Nov 2022 13:01:41 +0100 Subject: [PATCH 01/68] titles-only toctrees --- docs/source/telegram.at-tree.rst | 1 + docs/source/telegram.ext.acd-tree.rst | 1 + docs/source/telegram.ext.handlers-tree.rst | 1 + docs/source/telegram.ext.persistence-tree.rst | 1 + docs/source/telegram.ext.rate-limiting-tree.rst | 1 + docs/source/telegram.games-tree.rst | 1 + docs/source/telegram.inline-tree.rst | 1 + docs/source/telegram.passport-tree.rst | 1 + docs/source/telegram.payments-tree.rst | 1 + docs/source/telegram.request.rst | 2 ++ docs/source/telegram.stickers-tree.rst | 1 + docs/source/telegram_auxil.rst | 1 + 12 files changed, 13 insertions(+) diff --git a/docs/source/telegram.at-tree.rst b/docs/source/telegram.at-tree.rst index 41fd5e6385a..122df9befcc 100644 --- a/docs/source/telegram.at-tree.rst +++ b/docs/source/telegram.at-tree.rst @@ -2,6 +2,7 @@ Available Types --------------- .. toctree:: + :titlesonly: telegram.animation telegram.audio diff --git a/docs/source/telegram.ext.acd-tree.rst b/docs/source/telegram.ext.acd-tree.rst index 6517c3f0ffb..0ce4efda72c 100644 --- a/docs/source/telegram.ext.acd-tree.rst +++ b/docs/source/telegram.ext.acd-tree.rst @@ -2,6 +2,7 @@ Arbitrary Callback Data ----------------------- .. toctree:: + :titlesonly: telegram.ext.callbackdatacache telegram.ext.invalidcallbackdata diff --git a/docs/source/telegram.ext.handlers-tree.rst b/docs/source/telegram.ext.handlers-tree.rst index 5c3acf41867..b918d6a92dd 100644 --- a/docs/source/telegram.ext.handlers-tree.rst +++ b/docs/source/telegram.ext.handlers-tree.rst @@ -2,6 +2,7 @@ Handlers -------- .. toctree:: + :titlesonly: telegram.ext.basehandler telegram.ext.callbackqueryhandler diff --git a/docs/source/telegram.ext.persistence-tree.rst b/docs/source/telegram.ext.persistence-tree.rst index 6fd5c7ebf2c..c17d7bd5555 100644 --- a/docs/source/telegram.ext.persistence-tree.rst +++ b/docs/source/telegram.ext.persistence-tree.rst @@ -2,6 +2,7 @@ Persistence ----------- .. toctree:: + :titlesonly: telegram.ext.basepersistence telegram.ext.dictpersistence diff --git a/docs/source/telegram.ext.rate-limiting-tree.rst b/docs/source/telegram.ext.rate-limiting-tree.rst index 97818ac7362..023a3a633c5 100644 --- a/docs/source/telegram.ext.rate-limiting-tree.rst +++ b/docs/source/telegram.ext.rate-limiting-tree.rst @@ -2,6 +2,7 @@ Rate Limiting ------------- .. toctree:: + :titlesonly: telegram.ext.baseratelimiter telegram.ext.aioratelimiter \ No newline at end of file diff --git a/docs/source/telegram.games-tree.rst b/docs/source/telegram.games-tree.rst index dc8ba52d032..64f399d86a9 100644 --- a/docs/source/telegram.games-tree.rst +++ b/docs/source/telegram.games-tree.rst @@ -2,6 +2,7 @@ Games ----- .. toctree:: + :titlesonly: telegram.callbackgame telegram.game diff --git a/docs/source/telegram.inline-tree.rst b/docs/source/telegram.inline-tree.rst index 10a697cc487..cda06bc0c93 100644 --- a/docs/source/telegram.inline-tree.rst +++ b/docs/source/telegram.inline-tree.rst @@ -2,6 +2,7 @@ Inline Mode ----------- .. toctree:: + :titlesonly: telegram.choseninlineresult telegram.inlinequery diff --git a/docs/source/telegram.passport-tree.rst b/docs/source/telegram.passport-tree.rst index 48960ddbdd3..fb4e3b4ffde 100644 --- a/docs/source/telegram.passport-tree.rst +++ b/docs/source/telegram.passport-tree.rst @@ -2,6 +2,7 @@ Passport -------- .. toctree:: + :titlesonly: telegram.credentials telegram.datacredentials diff --git a/docs/source/telegram.payments-tree.rst b/docs/source/telegram.payments-tree.rst index b50b7390dcc..67f686ecc4b 100644 --- a/docs/source/telegram.payments-tree.rst +++ b/docs/source/telegram.payments-tree.rst @@ -2,6 +2,7 @@ Payments -------- .. toctree:: + :titlesonly: telegram.invoice telegram.labeledprice diff --git a/docs/source/telegram.request.rst b/docs/source/telegram.request.rst index 0b9528ec5c5..22292c70d72 100644 --- a/docs/source/telegram.request.rst +++ b/docs/source/telegram.request.rst @@ -4,6 +4,8 @@ telegram.request Module .. versionadded:: 20.0 .. toctree:: + :titlesonly: + telegram.request.baserequest telegram.request.requestdata telegram.request.httpxrequest diff --git a/docs/source/telegram.stickers-tree.rst b/docs/source/telegram.stickers-tree.rst index b52f6b567f0..783b90ec0c7 100644 --- a/docs/source/telegram.stickers-tree.rst +++ b/docs/source/telegram.stickers-tree.rst @@ -2,6 +2,7 @@ Stickers -------- .. toctree:: + :titlesonly: telegram.maskposition telegram.sticker diff --git a/docs/source/telegram_auxil.rst b/docs/source/telegram_auxil.rst index 0a7d951e2c9..19b26d609fa 100644 --- a/docs/source/telegram_auxil.rst +++ b/docs/source/telegram_auxil.rst @@ -2,6 +2,7 @@ Auxiliary modules ================= .. toctree:: + :titlesonly: telegram.constants telegram.error From cf9b22880d3e2d35508513b62d6b968549c73e86 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Sun, 27 Nov 2022 15:22:24 +0300 Subject: [PATCH 02/68] Conversationhandler docfix (#3395) --- telegram/ext/_conversationhandler.py | 1 + 1 file changed, 1 insertion(+) diff --git a/telegram/ext/_conversationhandler.py b/telegram/ext/_conversationhandler.py index 0402f740a7c..4c8e7a31e95 100644 --- a/telegram/ext/_conversationhandler.py +++ b/telegram/ext/_conversationhandler.py @@ -208,6 +208,7 @@ class ConversationHandler(BaseHandler[Update, CCT]): handled. allow_reentry (:obj:`bool`, optional): If set to :obj:`True`, a user that is currently in a conversation can restart the conversation by triggering one of the entry points. + Default is :obj:`False`. per_chat (:obj:`bool`, optional): If the conversation key should contain the Chat's ID. Default is :obj:`True`. per_user (:obj:`bool`, optional): If the conversation key should contain the User's ID. From c53c721d672699a76402560b169e10bebe18f77f Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 28 Nov 2022 20:17:01 +0300 Subject: [PATCH 03/68] fix(`Bot`): `:attr:`->`:meth:` in `seealso` where applicable --- telegram/_bot.py | 180 +++++++++++++++++++++++------------------------ 1 file changed, 90 insertions(+), 90 deletions(-) diff --git a/telegram/_bot.py b/telegram/_bot.py index dbfd6d7dffa..a8ca3d4ccf6 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -694,8 +694,8 @@ async def send_message( ) -> Message: """Use this method to send text messages. - .. seealso:: :attr:`telegram.Message.reply_text`, :attr:`telegram.Chat.send_message`, - :attr:`telegram.User.send_message` + .. seealso:: :meth:`telegram.Message.reply_text`, :meth:`telegram.Chat.send_message`, + :meth:`telegram.User.send_message` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -836,8 +836,8 @@ async def forward_message( As a workaround, it is still possible to use :meth:`copy_message`. However, this behaviour is undocumented and might be changed by Telegram. - .. seealso:: :attr:`telegram.Message.forward`, :attr:`telegram.Chat.forward_to`, - :attr:`telegram.Chat.forward_from` + .. seealso:: :meth:`telegram.Message.forward`, :meth:`telegram.Chat.forward_to`, + :meth:`telegram.Chat.forward_from` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -904,8 +904,8 @@ async def send_photo( ) -> Message: """Use this method to send photos. - .. seealso:: :attr:`telegram.Message.reply_photo`, :attr:`telegram.Chat.send_photo`, - :attr:`telegram.User.send_photo` + .. seealso:: :meth:`telegram.Message.reply_photo`, :meth:`telegram.Chat.send_photo`, + :meth:`telegram.User.send_photo` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1013,8 +1013,8 @@ async def send_audio( For sending voice messages, use the :meth:`send_voice` method instead. - .. seealso:: :attr:`telegram.Message.reply_audio`, :attr:`telegram.Chat.send_audio`, - :attr:`telegram.User.send_audio` + .. seealso:: :meth:`telegram.Message.reply_audio`, :meth:`telegram.Chat.send_audio`, + :meth:`telegram.User.send_audio` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1140,8 +1140,8 @@ async def send_document( :tg-const:`telegram.constants.FileSizeLimit.FILESIZE_UPLOAD` in size, this limit may be changed in the future. - .. seealso:: :attr:`telegram.Message.reply_document`, :attr:`telegram.Chat.send_document`, - :attr:`telegram.User.send_document` + .. seealso:: :meth:`telegram.Message.reply_document`, :meth:`telegram.Chat.send_document`, + :meth:`telegram.User.send_document` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1252,8 +1252,8 @@ async def send_sticker( """ Use this method to send static ``.WEBP``, animated ``.TGS``, or video ``.WEBM`` stickers. - .. seealso:: :attr:`telegram.Message.reply_sticker`, :attr:`telegram.Chat.send_sticker`, - :attr:`telegram.User.send_sticker` + .. seealso:: :meth:`telegram.Message.reply_sticker`, :meth:`telegram.Chat.send_sticker`, + :meth:`telegram.User.send_sticker` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1347,8 +1347,8 @@ async def send_video( easily generate thumbnails. However, this behaviour is undocumented and might be changed by Telegram. - .. seealso:: :attr:`telegram.Message.reply_video`, :attr:`telegram.Chat.send_video`, - :attr:`telegram.User.send_video` + .. seealso:: :meth:`telegram.Message.reply_video`, :meth:`telegram.Chat.send_video`, + :meth:`telegram.User.send_video` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1477,9 +1477,9 @@ async def send_video_note( easily generate thumbnails. However, this behaviour is undocumented and might be changed by Telegram. - .. seealso:: :attr:`telegram.Message.reply_video_note`, - :attr:`telegram.Chat.send_video_note`, - :attr:`telegram.User.send_video_note` + .. seealso:: :meth:`telegram.Message.reply_video_note`, + :meth:`telegram.Chat.send_video_note`, + :meth:`telegram.User.send_video_note` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1603,9 +1603,9 @@ async def send_animation( generate thumbnails. However, this behaviour is undocumented and might be changed by Telegram. - .. seealso:: :attr:`telegram.Message.reply_animation`, - :attr:`telegram.Chat.send_animation`, - :attr:`telegram.User.send_animation` + .. seealso:: :meth:`telegram.Message.reply_animation`, + :meth:`telegram.Chat.send_animation`, + :meth:`telegram.User.send_animation` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1734,8 +1734,8 @@ async def send_voice( :tg-const:`telegram.constants.FileSizeLimit.FILESIZE_DOWNLOAD` voice notes will be sent as files. - .. seealso:: :attr:`telegram.Message.reply_voice`, :attr:`telegram.Chat.send_voice`, - :attr:`telegram.User.send_voice` + .. seealso:: :meth:`telegram.Message.reply_voice`, :meth:`telegram.Chat.send_voice`, + :meth:`telegram.User.send_voice` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1841,9 +1841,9 @@ async def send_media_group( :paramref:`caption_entities`), then items in :paramref:`media` must have no captions, and vice versa. - .. seealso:: :attr:`telegram.Message.reply_media_group`, - :attr:`telegram.Chat.send_media_group`, - :attr:`telegram.User.send_media_group` + .. seealso:: :meth:`telegram.Message.reply_media_group`, + :meth:`telegram.Chat.send_media_group`, + :meth:`telegram.User.send_media_group` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1966,8 +1966,8 @@ async def send_location( You can either supply a :paramref:`latitude` and :paramref:`longitude` or a :paramref:`location`. - .. seealso:: :attr:`telegram.Message.reply_location`, :attr:`telegram.Chat.send_location`, - :attr:`telegram.User.send_location` + .. seealso:: :meth:`telegram.Message.reply_location`, :meth:`telegram.Chat.send_location`, + :meth:`telegram.User.send_location` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -2083,8 +2083,8 @@ async def edit_message_live_location( You can either supply a :paramref:`latitude` and :paramref:`longitude` or a :paramref:`location`. - .. seealso:: :attr:`telegram.Message.edit_live_location`, - :attr:`telegram.CallbackQuery.edit_message_live_location` + .. seealso:: :meth:`telegram.Message.edit_live_location`, + :meth:`telegram.CallbackQuery.edit_message_live_location` Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not @@ -2174,8 +2174,8 @@ async def stop_message_live_location( """Use this method to stop updating a live location message sent by the bot or via the bot (for inline bots) before :paramref:`~telegram.Location.live_period` expires. - .. seealso:: :attr:`telegram.Message.stop_live_location`, - :attr:`telegram.CallbackQuery.stop_message_live_location` + .. seealso:: :meth:`telegram.Message.stop_live_location`, + :meth:`telegram.CallbackQuery.stop_message_live_location` Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id` @@ -2247,8 +2247,8 @@ async def send_venue( * Foursquare details and Google Place details are mutually exclusive. However, this behaviour is undocumented and might be changed by Telegram. - .. seealso:: :attr:`telegram.Message.reply_venue`, :attr:`telegram.Chat.send_venue`, - :attr:`telegram.User.send_venue` + .. seealso:: :meth:`telegram.Message.reply_venue`, :meth:`telegram.Chat.send_venue`, + :meth:`telegram.User.send_venue` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -2374,8 +2374,8 @@ async def send_contact( :paramref:`first_name` with optionally :paramref:`last_name` and optionally :paramref:`vcard`. - .. seealso:: :attr:`telegram.Message.reply_contact`, :attr:`telegram.Chat.send_contact`, - :attr:`telegram.User.send_contact` + .. seealso:: :meth:`telegram.Message.reply_contact`, :meth:`telegram.Chat.send_contact`, + :meth:`telegram.User.send_contact` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -2474,8 +2474,8 @@ async def send_game( ) -> Message: """Use this method to send a game. - .. seealso:: :attr:`telegram.Message.reply_game`, :attr:`telegram.Chat.send_game`, - :attr:`telegram.User.send_game` + .. seealso:: :meth:`telegram.Message.reply_game`, :meth:`telegram.Chat.send_game`, + :meth:`telegram.User.send_game` Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat. @@ -2538,8 +2538,8 @@ async def send_chat_action( Telegram clients clear its typing status). Telegram only recommends using this method when a response from the bot will take a noticeable amount of time to arrive. - .. seealso:: :attr:`telegram.Message.reply_chat_action`, :attr:`telegram.Chat.send_action`, - :attr:`telegram.User.send_chat_action` + .. seealso:: :meth:`telegram.Message.reply_chat_action`, :meth:`telegram.Chat.send_action`, + :meth:`telegram.User.send_chat_action` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -2695,7 +2695,7 @@ async def answer_inline_query( :paramref:`telegram.InlineQuery.answer.auto_pagination` set to :obj:`True`, which will take care of passing the correct value. - .. seealso:: :attr:`telegram.InlineQuery.answer` + .. seealso:: :meth:`telegram.InlineQuery.answer` Args: inline_query_id (:obj:`str`): Unique identifier for the answered query. @@ -2908,7 +2908,7 @@ async def ban_chat_member( using invite links, etc., unless unbanned first. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. - .. seealso:: :attr:`telegram.Chat.ban_member` + .. seealso:: :meth:`telegram.Chat.ban_member` .. versionadded:: 13.7 @@ -2975,7 +2975,7 @@ async def ban_chat_sender_chat( their channels**. The bot must be an administrator in the supergroup or channel for this to work and must have the appropriate administrator rights. - .. seealso:: :attr:`telegram.Chat.ban_chat`, :attr:`telegram.Chat.ban_sender_chat` + .. seealso:: :meth:`telegram.Chat.ban_chat`, :meth:`telegram.Chat.ban_sender_chat` .. versionadded:: 13.9 @@ -3026,7 +3026,7 @@ async def unban_chat_member( join it. So if the user is a member of the chat they will also be *removed* from the chat. If you don't want this, use the parameter :paramref:`only_if_banned`. - .. seealso:: :attr:`telegram.Chat.unban_member` + .. seealso:: :meth:`telegram.Chat.unban_member` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -3073,7 +3073,7 @@ async def unban_chat_sender_chat( The bot must be an administrator for this to work and must have the appropriate administrator rights. - .. seealso:: :attr:`telegram.Chat.unban_chat` + .. seealso:: :meth:`telegram.Chat.unban_chat` .. versionadded:: 13.9 @@ -3126,7 +3126,7 @@ async def answer_callback_query( and accept the terms. Otherwise, you may use links like t.me/your_bot?start=XXXX that open your bot with a parameter. - .. seealso:: :attr:`telegram.CallbackQuery.answer` + .. seealso:: :meth:`telegram.CallbackQuery.answer` Args: callback_query_id (:obj:`str`): Unique identifier for the query to be answered. @@ -3199,8 +3199,8 @@ async def edit_message_text( Note: |editreplymarkup|. - .. seealso:: :attr:`telegram.Message.edit_text`, - :attr:`telegram.CallbackQuery.edit_message_text` + .. seealso:: :meth:`telegram.Message.edit_text`, + :meth:`telegram.CallbackQuery.edit_message_text` Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id` @@ -3277,8 +3277,8 @@ async def edit_message_caption( Note: |editreplymarkup| - .. seealso:: :attr:`telegram.Message.edit_caption`, - :attr:`telegram.CallbackQuery.edit_message_caption` + .. seealso:: :meth:`telegram.Message.edit_caption`, + :meth:`telegram.CallbackQuery.edit_message_caption` Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not @@ -3351,8 +3351,8 @@ async def edit_message_media( Note: |editreplymarkup| - .. seealso:: :attr:`telegram.Message.edit_media`, - :attr:`telegram.CallbackQuery.edit_message_media` + .. seealso:: :meth:`telegram.Message.edit_media`, + :meth:`telegram.CallbackQuery.edit_message_media` Args: media (:class:`telegram.InputMedia`): An object for a new media content @@ -3414,8 +3414,8 @@ async def edit_message_reply_markup( Note: |editreplymarkup| - .. seealso:: :attr:`telegram.Message.edit_reply_markup`, - :attr:`telegram.CallbackQuery.edit_message_reply_markup` + .. seealso:: :meth:`telegram.Message.edit_reply_markup`, + :meth:`telegram.CallbackQuery.edit_message_reply_markup` Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not @@ -3725,7 +3725,7 @@ async def leave_chat( ) -> bool: """Use this method for your bot to leave a group, supergroup or channel. - .. seealso:: :attr:`telegram.Chat.leave` + .. seealso:: :meth:`telegram.Chat.leave` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -3804,7 +3804,7 @@ async def get_chat_administrators( """ Use this method to get a list of administrators in a chat. - .. seealso:: :attr:`telegram.Chat.get_administrators` + .. seealso:: :meth:`telegram.Chat.get_administrators` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -3844,7 +3844,7 @@ async def get_chat_member_count( ) -> int: """Use this method to get the number of members in a chat. - .. seealso:: :attr:`telegram.Chat.get_member_count` + .. seealso:: :meth:`telegram.Chat.get_member_count` .. versionadded:: 13.7 @@ -3884,7 +3884,7 @@ async def get_chat_member( ) -> ChatMember: """Use this method to get information about a member of a chat. - .. seealso:: :attr:`telegram.Chat.get_member` + .. seealso:: :meth:`telegram.Chat.get_member` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -4100,7 +4100,7 @@ async def get_game_high_scores( closest neighbors on each side. Will also return the top three users if the user and his neighbors are not among them. Please note that this behavior is subject to change. - .. seealso:: :attr:`telegram.CallbackQuery.get_game_high_scores` + .. seealso:: :meth:`telegram.CallbackQuery.get_game_high_scores` Args: user_id (:obj:`int`): Target user id. @@ -4184,8 +4184,8 @@ async def send_invoice( order of the arguments had to be changed. Use keyword arguments to make sure that the arguments are passed correctly. - .. seealso:: :attr:`telegram.Message.reply_invoice`, :attr:`telegram.Chat.send_invoice`, - :attr:`telegram.User.send_invoice` + .. seealso:: :meth:`telegram.Message.reply_invoice`, :meth:`telegram.Chat.send_invoice`, + :meth:`telegram.User.send_invoice` .. versionchanged:: 13.5 As of Bot API 5.2, the parameter :paramref:`start_parameter` is optional. @@ -4416,7 +4416,7 @@ async def answer_pre_checkout_query( # pylint: disable=invalid-name The Bot API must receive an answer within 10 seconds after the pre-checkout query was sent. - .. seealso:: :attr:`telegram.PreCheckoutQuery.answer` + .. seealso:: :meth:`telegram.PreCheckoutQuery.answer` Args: pre_checkout_query_id (:obj:`str`): Unique identifier for the query to be answered. @@ -4520,7 +4520,7 @@ async def restrict_chat_member( :obj:`True` for all boolean parameters to lift restrictions from a user. .. seealso:: :meth:`telegram.ChatPermissions.all_permissions`, - :attr:`telegram.Chat.restrict_member` + :meth:`telegram.Chat.restrict_member` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_group| @@ -4591,7 +4591,7 @@ async def promote_chat_member( an administrator in the chat for this to work and must have the appropriate admin rights. Pass :obj:`False` for all boolean parameters to demote a user. - .. seealso:: :attr:`telegram.Chat.promote_member` + .. seealso:: :meth:`telegram.Chat.promote_member` .. versionchanged:: 20.0 The argument ``can_manage_voice_chats`` was renamed to @@ -4700,7 +4700,7 @@ async def set_chat_permissions( administrator in the group or a supergroup for this to work and must have the :attr:`telegram.ChatMemberAdministrator.can_restrict_members` admin rights. - .. seealso:: :attr:`telegram.Chat.set_permissions` + .. seealso:: :meth:`telegram.Chat.set_permissions` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_group| @@ -4742,7 +4742,7 @@ async def set_chat_administrator_custom_title( Use this method to set a custom title for administrators promoted by the bot in a supergroup. The bot must be an administrator for this to work. - .. seealso:: :attr:`telegram.Chat.set_administrator_custom_title` + .. seealso:: :meth:`telegram.Chat.set_administrator_custom_title` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_group| @@ -4793,9 +4793,9 @@ async def export_chat_invite_link( links generated by other administrators. If you want your bot to work with invite links, it will need to generate its own link using :meth:`export_chat_invite_link` or by calling the :meth:`get_chat` method. If your bot needs to generate a new primary - invite link replacing its previous one, use :attr:`export_chat_invite_link` again. + invite link replacing its previous one, use :meth:`export_chat_invite_link` again. - .. seealso:: :attr:`telegram.Chat.export_invite_link` + .. seealso:: :meth:`telegram.Chat.export_invite_link` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -4839,7 +4839,7 @@ async def create_chat_invite_link( administrator in the chat for this to work and must have the appropriate admin rights. The link can be revoked using the method :meth:`revoke_chat_invite_link`. - .. seealso:: :attr:`telegram.Chat.create_invite_link` + .. seealso:: :meth:`telegram.Chat.create_invite_link` .. versionadded:: 13.4 @@ -4923,7 +4923,7 @@ async def edit_chat_invite_link( parameters to the default values. However, since not documented, this behaviour may change unbeknown to PTB. - .. seealso:: :attr:`telegram.Chat.edit_invite_link` + .. seealso:: :meth:`telegram.Chat.edit_invite_link` .. versionadded:: 13.4 @@ -5003,7 +5003,7 @@ async def revoke_chat_invite_link( revoked, a new link is automatically generated. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. - .. seealso:: :attr:`telegram.Chat.revoke_invite_link` + .. seealso:: :meth:`telegram.Chat.revoke_invite_link` .. versionadded:: 13.4 @@ -5053,8 +5053,8 @@ async def approve_chat_join_request( The bot must be an administrator in the chat for this to work and must have the :attr:`telegram.ChatPermissions.can_invite_users` administrator right. - .. seealso:: :attr:`telegram.Chat.approve_join_request`, - :attr:`telegram.ChatJoinRequest.approve`, :attr:`telegram.User.approve_join_request` + .. seealso:: :meth:`telegram.Chat.approve_join_request`, + :meth:`telegram.ChatJoinRequest.approve`, :meth:`telegram.User.approve_join_request` .. versionadded:: 13.8 @@ -5099,8 +5099,8 @@ async def decline_chat_join_request( The bot must be an administrator in the chat for this to work and must have the :attr:`telegram.ChatPermissions.can_invite_users` administrator right. - .. seealso:: :attr:`telegram.Chat.decline_join_request`, - :attr:`telegram.ChatJoinRequest.decline`, :attr:`telegram.User.decline_join_request` + .. seealso:: :meth:`telegram.Chat.decline_join_request`, + :meth:`telegram.ChatJoinRequest.decline`, :meth:`telegram.User.decline_join_request` .. versionadded:: 13.8 @@ -5145,7 +5145,7 @@ async def set_chat_photo( Photos can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. - .. seealso:: :attr:`telegram.Chat.set_photo` + .. seealso:: :meth:`telegram.Chat.set_photo` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5194,7 +5194,7 @@ async def delete_chat_photo( must be an administrator in the chat for this to work and must have the appropriate admin rights. - .. seealso:: :attr:`telegram.Chat.delete_photo` + .. seealso:: :meth:`telegram.Chat.delete_photo` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5235,7 +5235,7 @@ async def set_chat_title( The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. - .. seealso:: :attr:`telegram.Chat.set_title` + .. seealso:: :meth:`telegram.Chat.set_title` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5279,7 +5279,7 @@ async def set_chat_description( must be an administrator in the chat for this to work and must have the appropriate admin rights. - .. seealso:: :attr:`telegram.Chat.set_description` + .. seealso:: :meth:`telegram.Chat.set_description` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5329,7 +5329,7 @@ async def pin_chat_message( right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin right in a channel. - .. seealso:: :attr:`telegram.Chat.pin_message`, :attr:`telegram.User.pin_message` + .. seealso:: :meth:`telegram.Chat.pin_message`, :meth:`telegram.User.pin_message` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5380,7 +5380,7 @@ async def unpin_chat_message( right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin right in a channel. - .. seealso:: :attr:`telegram.Chat.unpin_message`, :attr:`telegram.User.unpin_message` + .. seealso:: :meth:`telegram.Chat.unpin_message`, :meth:`telegram.User.unpin_message` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5427,8 +5427,8 @@ async def unpin_all_chat_messages( admin right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin right in a channel. - .. seealso:: :attr:`telegram.Chat.unpin_all_messages`, - :attr:`telegram.User.unpin_all_messages` + .. seealso:: :meth:`telegram.Chat.unpin_all_messages`, + :meth:`telegram.User.unpin_all_messages` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -6002,8 +6002,8 @@ async def send_poll( """ Use this method to send a native poll. - .. seealso:: :attr:`telegram.Message.reply_poll`, :attr:`telegram.Chat.send_poll`, - :attr:`telegram.User.send_poll` + .. seealso:: :meth:`telegram.Message.reply_poll`, :meth:`telegram.Chat.send_poll`, + :meth:`telegram.User.send_poll` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -6127,7 +6127,7 @@ async def stop_poll( """ Use this method to stop a poll which was sent by the bot. - .. seealso:: :attr:`telegram.Message.stop_poll` + .. seealso:: :meth:`telegram.Message.stop_poll` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -6179,8 +6179,8 @@ async def send_dice( """ Use this method to send an animated emoji that will display a random value. - .. seealso:: :attr:`telegram.Message.reply_dice`, :attr:`telegram.Chat.send_dice`, - :attr:`telegram.User.send_dice` + .. seealso:: :meth:`telegram.Message.reply_dice`, :meth:`telegram.Chat.send_dice`, + :meth:`telegram.User.send_dice` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -6603,9 +6603,9 @@ async def copy_message( be copied. The method is analogous to the method :meth:`forward_message`, but the copied message doesn't have a link to the original message. - .. seealso:: :attr:`telegram.Message.copy`, :attr:`telegram.Chat.send_copy`, - :attr:`telegram.Chat.copy_message`, :attr:`telegram.User.send_copy`, - :attr:`telegram.User.copy_message` + .. seealso:: :meth:`telegram.Message.copy`, :meth:`telegram.Chat.send_copy`, + :meth:`telegram.Chat.copy_message`, :meth:`telegram.User.send_copy`, + :meth:`telegram.User.copy_message` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| From eb07a2ba92d2420a9d3ee616dae8721a80155dd8 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Wed, 30 Nov 2022 17:46:36 +0300 Subject: [PATCH 04/68] Add more crossrefs to docstrings (#3398) --- telegram/_bot.py | 39 ++++++++++++++++++++++++------ telegram/_chat.py | 2 +- telegram/_files/_basemedium.py | 2 +- telegram/_files/chatphoto.py | 4 +-- telegram/_passport/passportfile.py | 2 +- 5 files changed, 36 insertions(+), 13 deletions(-) diff --git a/telegram/_bot.py b/telegram/_bot.py index a8ca3d4ccf6..877fd11e3db 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -694,8 +694,9 @@ async def send_message( ) -> Message: """Use this method to send text messages. - .. seealso:: :meth:`telegram.Message.reply_text`, :meth:`telegram.Chat.send_message`, - :meth:`telegram.User.send_message` + .. seealso:: :meth:`telegram.Chat.send_message`, :meth:`telegram.User.send_message`, + :meth:`telegram.Message.reply_text`, :meth:`telegram.Message.reply_html`, + :meth:`telegram.Message.reply_markdown`, :meth:`telegram.Message.reply_markdown_v2` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -2846,6 +2847,13 @@ async def get_file( You should save the file's MIME type and name (if available) when the File object is received. + .. seealso:: :meth:`telegram.Animation.get_file`, :meth:`telegram.Audio.get_file`, + :meth:`telegram.ChatPhoto.get_big_file`, :meth:`telegram.ChatPhoto.get_small_file`, + :meth:`telegram.Document.get_file`, :meth:`telegram.PassportFile.get_file`, + :meth:`telegram.PhotoSize.get_file`, :meth:`telegram.Sticker.get_file`, + :meth:`telegram.Video.get_file`, :meth:`telegram.VideoNote.get_file`, + :meth:`telegram.Voice.get_file` + Args: file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` | \ :class:`telegram.ChatPhoto` | :class:`telegram.Document` | \ @@ -3200,7 +3208,7 @@ async def edit_message_text( |editreplymarkup|. .. seealso:: :meth:`telegram.Message.edit_text`, - :meth:`telegram.CallbackQuery.edit_message_text` + :meth:`telegram.CallbackQuery.edit_message_text`, :attr:`telegram.Game.text` Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id` @@ -3477,6 +3485,9 @@ async def get_updates( server response. 3. To take full advantage of this library take a look at :class:`telegram.ext.Updater` + .. seealso:: :meth:`telegram.ext.Application.run_polling`, + :meth:`telegram.ext.Updater.start_polling` + Args: offset (:obj:`int`, optional): Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of previously received @@ -3594,6 +3605,9 @@ async def set_webhook( 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` + Examples: :any:`Custom Webhook Bot ` @@ -4029,7 +4043,7 @@ async def set_game_score( """ Use this method to set the score of the specified user in a game message. - .. seealso::`telegram.CallbackQuery.set_game_score` + .. seealso:: :meth:`telegram.CallbackQuery.set_game_score`, :attr:`telegram.Game.text` Args: user_id (:obj:`int`): User identifier. @@ -4100,7 +4114,8 @@ async def get_game_high_scores( closest neighbors on each side. Will also return the top three users if the user and his neighbors are not among them. Please note that this behavior is subject to change. - .. seealso:: :meth:`telegram.CallbackQuery.get_game_high_scores` + .. seealso:: :meth:`telegram.CallbackQuery.get_game_high_scores`, + :meth:`telegram.Message.get_game_high_scores` Args: user_id (:obj:`int`): Target user id. @@ -4353,7 +4368,7 @@ async def answer_shipping_query( # pylint: disable=invalid-name :class:`telegram.Update` with a :attr:`telegram.Update.shipping_query` field to the bot. Use this method to reply to shipping queries. - .. seealso:: :attr:`telegram.ShippingQuery.answer` + .. seealso:: :meth:`telegram.ShippingQuery.answer` Args: shipping_query_id (:obj:`str`): Unique identifier for the query to be answered. @@ -5329,7 +5344,8 @@ async def pin_chat_message( right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin right in a channel. - .. seealso:: :meth:`telegram.Chat.pin_message`, :meth:`telegram.User.pin_message` + .. seealso:: :meth:`telegram.Chat.pin_message`, :meth:`telegram.Message.pin`, + :meth:`telegram.User.pin_message` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5380,7 +5396,8 @@ async def unpin_chat_message( right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin right in a channel. - .. seealso:: :meth:`telegram.Chat.unpin_message`, :meth:`telegram.User.unpin_message` + .. seealso:: :meth:`telegram.Chat.unpin_message`, :meth:`telegram.Message.unpin`, + :meth:`telegram.User.unpin_message` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -6355,6 +6372,8 @@ async def get_my_commands( Use this method to get the current list of the bot's commands for the given scope and user language. + .. seealso:: :meth:`set_my_commands`, :meth:`delete_my_commands` + Args: scope (:class:`telegram.BotCommandScope`, optional): An object, describing scope of users. Defaults to :class:`telegram.BotCommandScopeDefault`. @@ -6412,6 +6431,8 @@ async def set_my_commands( `Telegram docs `_ for more details about bot commands. + .. seealso:: :meth:`get_my_commands`, :meth:`delete_my_commands` + Args: commands (List[:class:`BotCommand` | (:obj:`str`, :obj:`str`)]): A list of bot commands to be set as the list of the bot's commands. At most @@ -6477,6 +6498,8 @@ async def delete_my_commands( .. versionadded:: 13.7 + .. seealso:: :meth:`get_my_commands`, :meth:`set_my_commands` + Args: scope (:class:`telegram.BotCommandScope`, optional): An object, describing scope of users for which the commands are relevant. Defaults to diff --git a/telegram/_chat.py b/telegram/_chat.py index 33fba0cf0d1..d3929596619 100644 --- a/telegram/_chat.py +++ b/telegram/_chat.py @@ -2833,7 +2833,7 @@ async def get_menu_button( await bot.get_chat_menu_button(chat_id=update.effective_chat.id, *args, **kwargs) For the documentation of the arguments, please see - :meth:`telegram.Bot.set_chat_menu_button`. + :meth:`telegram.Bot.get_chat_menu_button`. Caution: Can only work, if the chat is a private chat. diff --git a/telegram/_files/_basemedium.py b/telegram/_files/_basemedium.py index a574064befb..a0ad5998d9f 100644 --- a/telegram/_files/_basemedium.py +++ b/telegram/_files/_basemedium.py @@ -79,7 +79,7 @@ async def get_file( pool_timeout: ODVInput[float] = DEFAULT_NONE, api_kwargs: JSONDict = None, ) -> "File": - """Convenience wrapper over :attr:`telegram.Bot.get_file` + """Convenience wrapper over :meth:`telegram.Bot.get_file` For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`. diff --git a/telegram/_files/chatphoto.py b/telegram/_files/chatphoto.py index fb1b005eda5..9e55efa2dfc 100644 --- a/telegram/_files/chatphoto.py +++ b/telegram/_files/chatphoto.py @@ -109,7 +109,7 @@ async def get_small_file( pool_timeout: ODVInput[float] = DEFAULT_NONE, api_kwargs: JSONDict = None, ) -> "File": - """Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the small + """Convenience wrapper over :meth:`telegram.Bot.get_file` for getting the small (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`) chat photo @@ -140,7 +140,7 @@ async def get_big_file( pool_timeout: ODVInput[float] = DEFAULT_NONE, api_kwargs: JSONDict = None, ) -> "File": - """Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the + """Convenience wrapper over :meth:`telegram.Bot.get_file` for getting the big (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`) chat photo diff --git a/telegram/_passport/passportfile.py b/telegram/_passport/passportfile.py index 41586483670..f2434807935 100644 --- a/telegram/_passport/passportfile.py +++ b/telegram/_passport/passportfile.py @@ -146,7 +146,7 @@ async def get_file( api_kwargs: JSONDict = None, ) -> "File": """ - Wrapper over :attr:`telegram.Bot.get_file`. Will automatically assign the correct + 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`. From 421518b2ae82cb5c6eb98de20fbd2e7de4c09390 Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Thu, 1 Dec 2022 23:36:31 +0100 Subject: [PATCH 05/68] Clarify docs of the `filter` argument in `MessageHandler` (#3403) --- telegram/ext/_messagehandler.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/telegram/ext/_messagehandler.py b/telegram/ext/_messagehandler.py index addf72c33b7..0a0f365d3dd 100644 --- a/telegram/ext/_messagehandler.py +++ b/telegram/ext/_messagehandler.py @@ -44,11 +44,8 @@ class MessageHandler(BaseHandler[Update, CCT]): filters (:class:`telegram.ext.filters.BaseFilter`): A filter inheriting from :class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in :mod:`telegram.ext.filters`. Filters can be combined using bitwise - operators (& for and, | for or, ~ for not). This defaults to all message updates - being: :attr:`telegram.Update.message`, :attr:`telegram.Update.edited_message`, - :attr:`telegram.Update.channel_post` and :attr:`telegram.Update.edited_channel_post`. - If you don't want or need any of those pass ``~filters.UpdateType.*`` in the filter - argument. + operators (& for and, | for or, ~ for not). Passing :obj:`None` is a shortcut + to passing :class:`telegram.ext.filters.ALL`. .. seealso:: `Advanced Filters `_ From d8d3d3158349f96aaf7f2d5b0857f24c4b994fc3 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 11:16:06 +0300 Subject: [PATCH 06/68] unify attrs and args in `Dice` --- telegram/_dice.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/telegram/_dice.py b/telegram/_dice.py index a25bdc992da..2fc50754313 100644 --- a/telegram/_dice.py +++ b/telegram/_dice.py @@ -75,6 +75,14 @@ class Dice(TelegramObject): Attributes: value (:obj:`int`): Value of the dice. + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BOWLING` + for :tg-const:`telegram.Dice.DICE`, :tg-const:`telegram.Dice.DARTS` and + :tg-const:`telegram.Dice.BOWLING` base emoji, + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BASKETBALL` + for :tg-const:`telegram.Dice.BASKETBALL` and :tg-const:`telegram.Dice.FOOTBALL` + base emoji, + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_SLOT_MACHINE` + for :tg-const:`telegram.Dice.SLOT_MACHINE` base emoji. emoji (:obj:`str`): Emoji on which the dice throw animation is based. """ From c627e86a85a21a8df5204b6ca87b8f940fd60ef6 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 11:24:51 +0300 Subject: [PATCH 07/68] unify attrs and args in `LoginURL` --- telegram/_loginurl.py | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/telegram/_loginurl.py b/telegram/_loginurl.py index d71d8dfbdb5..7b3c3bfd3a2 100644 --- a/telegram/_loginurl.py +++ b/telegram/_loginurl.py @@ -44,7 +44,7 @@ class LoginUrl(TelegramObject): the original URL without information about the user will be opened. The data added is the same as described in `Receiving authorization data - `_ + `_. forward_text (:obj:`str`, optional): New text of the button in forwarded messages. bot_username (:obj:`str`, optional): Username of a bot, which will be used for user authorization. See @@ -59,10 +59,22 @@ class LoginUrl(TelegramObject): for your bot to send messages to the user. Attributes: - url (:obj:`str`): An HTTPS URL to be opened with user authorization data. + url (:obj:`str`): An HTTPS URL to be opened with user authorization data added to the query + string when the button is pressed. If the user refuses to provide authorization data, + the original URL without information about the user will be opened. The data added is + the same as described in + `Receiving authorization data + `_. forward_text (:obj:`str`): Optional. New text of the button in forwarded messages. bot_username (:obj:`str`): Optional. Username of a bot, which will be used for user - authorization. + authorization. See + `Setting up a bot `_ + for more details. If not specified, the current + bot's username will be assumed. The url's domain must be the same as the domain linked + with the bot. See + `Linking your domain to the bot + `_ + for more details. request_write_access (:obj:`bool`): Optional. Pass :obj:`True` to request the permission for your bot to send messages to the user. From c599963e7e7d0966925d300d4af21d0b4b061e0e Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 11:33:51 +0300 Subject: [PATCH 08/68] fix(`User`): "bots"->"bot's" in args --- telegram/_user.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/telegram/_user.py b/telegram/_user.py index 015ec93234e..7658abe907e 100644 --- a/telegram/_user.py +++ b/telegram/_user.py @@ -70,9 +70,9 @@ class User(TelegramObject): Args: id (:obj:`int`): Unique identifier for this user or bot. is_bot (:obj:`bool`): :obj:`True`, if this user is a bot. - first_name (:obj:`str`): User's or bots first name. - last_name (:obj:`str`, optional): User's or bots last name. - username (:obj:`str`, optional): User's or bots username. + first_name (:obj:`str`): User's or bot's first name. + last_name (:obj:`str`, optional): User's or bot's last name. + username (:obj:`str`, optional): User's or bot's username. language_code (:obj:`str`, optional): IETF language tag of the user's language. can_join_groups (:obj:`str`, optional): :obj:`True`, if the bot can be invited to groups. Returned only in :attr:`telegram.Bot.get_me` requests. From 88f0c656275ae820e03af5a301a40d9a32d533b6 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 11:40:32 +0300 Subject: [PATCH 09/68] `Update`: unify args and attrs --- telegram/_update.py | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/telegram/_update.py b/telegram/_update.py index e29597b3029..266d9321174 100644 --- a/telegram/_update.py +++ b/telegram/_update.py @@ -98,23 +98,33 @@ class Update(TelegramObject): .. versionadded:: 13.8 Attributes: - update_id (:obj:`int`): The update's unique identifier. - message (:class:`telegram.Message`): Optional. New incoming message. - edited_message (:class:`telegram.Message`): Optional. New version of a message. - channel_post (:class:`telegram.Message`): Optional. New incoming channel post. - edited_channel_post (:class:`telegram.Message`): Optional. New version of a channel post. + update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a + certain positive number and increase sequentially. This ID becomes especially handy if + you're using Webhooks, since it allows you to ignore repeated updates or to restore the + correct update sequence, should they get out of order. If there are no new updates for + at least a week, then identifier of the next update will be chosen randomly instead of + sequentially. + message (:class:`telegram.Message`): Optional. New incoming message of any kind - text, + photo, sticker, etc. + edited_message (:class:`telegram.Message`): Optional. New version of a message that is + known to the bot and was edited. + channel_post (:class:`telegram.Message`): Optional. New incoming channel post of any kind + - text, photo, sticker, etc. + edited_channel_post (:class:`telegram.Message`): Optional. New version of a channel post + that is known to the bot and was edited. inline_query (:class:`telegram.InlineQuery`): Optional. New incoming inline query. chosen_inline_result (:class:`telegram.ChosenInlineResult`): Optional. The result of an - inline query that was chosen by a user. + inline query that was chosen by a user and sent to their chat partner. callback_query (:class:`telegram.CallbackQuery`): Optional. New incoming callback query. Examples: :any:`Arbitrary Callback Data Bot ` shipping_query (:class:`telegram.ShippingQuery`): Optional. New incoming shipping query. + Only for invoices with flexible price. pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming - pre-checkout query. - poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates - about stopped polls and polls, which are sent by the bot. + pre-checkout query. Contains full information about checkout. + poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates about + stopped polls and polls, which are sent by the bot. poll_answer (:class:`telegram.PollAnswer`): Optional. A user changed their answer in a non-anonymous poll. Bots receive new votes only in polls that were sent by the bot itself. From e61968dbc66c7b7ca2ff0f87b803de763c3ca3b1 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 11:44:06 +0300 Subject: [PATCH 10/68] `PollAnswer`: unify args and attrs --- telegram/_poll.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/telegram/_poll.py b/telegram/_poll.py index 87feee5a3e8..a9c123bf0a7 100644 --- a/telegram/_poll.py +++ b/telegram/_poll.py @@ -92,7 +92,8 @@ class PollAnswer(TelegramObject): Attributes: poll_id (:obj:`str`): Unique poll identifier. user (:class:`telegram.User`): The user, who changed the answer to the poll. - option_ids (List[:obj:`int`]): Identifiers of answer options, chosen by the user. + option_ids (List[:obj:`int`]): 0-based identifiers of answer options, chosen by the user. + May be empty if the user retracted their vote. """ From 2980497fd31a630dda5847ad864d3a597241c029 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 11:49:14 +0300 Subject: [PATCH 11/68] `MessageEntity`: unify args and attrs it was not done completely in #3314 (`user` attr needed addition) --- telegram/_messageentity.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/telegram/_messageentity.py b/telegram/_messageentity.py index 72438b1aa1a..f343899708a 100644 --- a/telegram/_messageentity.py +++ b/telegram/_messageentity.py @@ -48,7 +48,7 @@ class MessageEntity(TelegramObject): :attr:`CUSTOM_EMOJI` (for inline custom emoji stickers). .. versionadded:: 20.0 - added inline custom emoji + Added inline custom emoji offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity. length (:obj:`int`): Length of the entity in UTF-16 code units. url (:obj:`str`, optional): For :attr:`TEXT_LINK` only, url that will be opened after @@ -77,8 +77,9 @@ class MessageEntity(TelegramObject): length (:obj:`int`): Length of the entity in UTF-16 code units. url (:obj:`str`): Optional. For :attr:`TEXT_LINK` only, url that will be opened after user taps on the text. - user (:class:`telegram.User`): Optional. The mentioned user. - language (:obj:`str`): Optional. For :attr:`PRE` only, The programming language of + user (:class:`telegram.User`): Optional. For :attr:`TEXT_MENTION` only, the mentioned + user. + language (:obj:`str`): Optional. For :attr:`PRE` only, the programming language of the entity text. custom_emoji_id (:obj:`str`): Optional. For :attr:`CUSTOM_EMOJI` only, unique identifier of the custom emoji. Use :meth:`telegram.Bot.get_custom_emoji_stickers` to get full From b0ce3a4be4a2d657426dac2203b961b75f708a60 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 11:51:48 +0300 Subject: [PATCH 12/68] `Location`: unify args and attrs --- telegram/_files/location.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/telegram/_files/location.py b/telegram/_files/location.py index 967eefdea76..fe088088709 100644 --- a/telegram/_files/location.py +++ b/telegram/_files/location.py @@ -48,10 +48,11 @@ class Location(TelegramObject): longitude (:obj:`float`): Longitude as defined by sender. latitude (:obj:`float`): Latitude as defined by sender. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. + measured in meters; 0-:tg-const:`telegram.Location.HORIZONTAL_ACCURACY`. live_period (:obj:`int`): Optional. Time relative to the message sending date, during which the location can be updated, in seconds. For active live locations only. - heading (:obj:`int`): Optional. The direction in which user is moving, in degrees. + heading (:obj:`int`): Optional. The direction in which user is moving, in degrees; + :tg-const:`telegram.Location.MIN_HEADING`-:tg-const:`telegram.Location.MAX_HEADING`. For active live locations only. proximity_alert_radius (:obj:`int`): Optional. Maximum distance for proximity alerts about approaching another chat member, in meters. For sent live locations only. From 2d55ed883bdcb23cc522bc3d1de65977e6219d8d Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 17:57:29 +0300 Subject: [PATCH 13/68] `CallbackQuery`: unify args and attrs not sure this is correct in the attrs, but I'm not changing it: data (:obj:`str` | :obj:`object`) (it's only `str` in args) --- telegram/_callbackquery.py | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/telegram/_callbackquery.py b/telegram/_callbackquery.py index 2a6fd1ba682..584796b5ec4 100644 --- a/telegram/_callbackquery.py +++ b/telegram/_callbackquery.py @@ -78,23 +78,27 @@ class CallbackQuery(TelegramObject): inline_message_id (:obj:`str`, optional): Identifier of the message sent via the bot in inline mode, that originated the query. game_short_name (:obj:`str`, optional): Short name of a Game to be returned, serves as - the unique identifier for the game + the unique identifier for the game. Attributes: id (:obj:`str`): Unique identifier for this query. from_user (:class:`telegram.User`): Sender. chat_instance (:obj:`str`): Global identifier, uniquely corresponding to the chat to which - the message with the callback button was sent. + the message with the callback button was sent. Useful for high scores in games. message (:class:`telegram.Message`): Optional. Message with the callback button that - originated the query. + originated the query. Note that message content and message date will not be available + if the message is too old. data (:obj:`str` | :obj:`object`): Optional. Data associated with the callback button. + Be aware that the message, which originated the query, can contain no callback buttons + with this data. Tip: The value here is the same as the value passed in :paramref:`telegram.InlineKeyboardButton.callback_data`. inline_message_id (:obj:`str`): Optional. Identifier of the message sent via the bot in - inline mode, that originated the query. - game_short_name (:obj:`str`): Optional. Short name of a Game to be returned. + inline mode, that originated the query. + game_short_name (:obj:`str`): Optional. Short name of a Game to be returned, serves as + the unique identifier for the game. """ From 717f64344a4d3ba2dfd0f16226adeb65a0390606 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 18:09:59 +0300 Subject: [PATCH 14/68] `ChatInviteLink`: unify args and attrs * not sure I had to add the note for `invite_link` to args, but it is there in Telegram API * Telegram API contains no explicit limit for `name` arg/attr --- telegram/_chatinvitelink.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/telegram/_chatinvitelink.py b/telegram/_chatinvitelink.py index 0f8f6d2600a..f2c2fc8b79a 100644 --- a/telegram/_chatinvitelink.py +++ b/telegram/_chatinvitelink.py @@ -44,7 +44,8 @@ class ChatInviteLink(TelegramObject): * Comparing objects of this class now also takes :attr:`creates_join_request` into account. Args: - invite_link (:obj:`str`): The invite link. + invite_link (:obj:`str`): The invite link. If the link was created by another chat + administrator, then the second part of the link will be replaced with ``'…'``. creator (:class:`telegram.User`): Creator of the link. creates_join_request (:obj:`bool`): :obj:`True`, if users joining the chat via the link need to be approved by chat administrators. @@ -83,6 +84,7 @@ class ChatInviteLink(TelegramObject): :tg-const:`telegram.constants.ChatInviteLinkLimit.MIN_MEMBER_LIMIT`- :tg-const:`telegram.constants.ChatInviteLinkLimit.MAX_MEMBER_LIMIT`. name (:obj:`str`): Optional. Invite link name. + 0-:tg-const:`telegram.constants.ChatInviteLinkLimit.NAME_LENGTH` characters. .. versionadded:: 13.8 pending_join_request_count (:obj:`int`): Optional. Number of pending join requests From 0bc70f66f3ea5deb6ea4e385c0da51874178f592 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 18:17:57 +0300 Subject: [PATCH 15/68] `ChatLocation`: unify args and attrs maybe "Can't be a live location" and limit constants are not needed in attrs, but it matches Telegram API --- telegram/_chatlocation.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/telegram/_chatlocation.py b/telegram/_chatlocation.py index bbac4524ef2..a826ded0724 100644 --- a/telegram/_chatlocation.py +++ b/telegram/_chatlocation.py @@ -40,10 +40,13 @@ class ChatLocation(TelegramObject): Can't be a live location. address (:obj:`str`): Location address; :tg-const:`telegram.ChatLocation.MIN_ADDRESS`- - :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner + :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner. Attributes: location (:class:`telegram.Location`): The location to which the supergroup is connected. - address (:obj:`str`): Location address, as defined by the chat owner + Can't be a live location. + address (:obj:`str`): Location address; + :tg-const:`telegram.ChatLocation.MIN_ADDRESS`- + :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner. """ From 268a853e012b204daec97a512f5d7f6b6d62eb54 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 2 Dec 2022 18:21:22 +0300 Subject: [PATCH 16/68] `ChatMember`: unify args and attrs --- telegram/_chatmember.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/telegram/_chatmember.py b/telegram/_chatmember.py index a1db9db3666..1e91a891e1d 100644 --- a/telegram/_chatmember.py +++ b/telegram/_chatmember.py @@ -65,7 +65,10 @@ class ChatMember(TelegramObject): Attributes: user (:class:`telegram.User`): Information about the user. - status (:obj:`str`): The member's status in the chat. + status (:obj:`str`): The member's status in the chat. Can be + :attr:`~telegram.ChatMember.ADMINISTRATOR`, :attr:`~telegram.ChatMember.OWNER`, + :attr:`~telegram.ChatMember.BANNED`, :attr:`~telegram.ChatMember.LEFT`, + :attr:`~telegram.ChatMember.MEMBER` or :attr:`~telegram.ChatMember.RESTRICTED`. """ From 9fd18c7314af0938654bfc0ffacb5a7835f4f9df Mon Sep 17 00:00:00 2001 From: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com> Date: Sat, 3 Dec 2022 13:20:24 +0100 Subject: [PATCH 17/68] Add a note in the line of #3401 --- telegram/ext/_application.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/telegram/ext/_application.py b/telegram/ext/_application.py index 5543fafc5c7..59f72eb355b 100644 --- a/telegram/ext/_application.py +++ b/telegram/ext/_application.py @@ -489,6 +489,11 @@ async def start(self) -> None: either start :attr:`updater` manually or use one of :meth:`run_polling` or :meth:`run_webhook`. + Tip: + When using a custom logic for startup and shutdown of the application, eventual + cancellation of pending tasks should happen only `after` :meth:`stop` has been called + in order to ensure that the tasks mentioned above are not cancelled prematurely. + .. seealso:: :meth:`stop` From fddaf7f32905db94102b8d6211fd62ef55af751c Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Sat, 3 Dec 2022 21:02:01 +0300 Subject: [PATCH 18/68] `ChatMemberUpdated`: add to `invite_link` attr --- telegram/_chatmemberupdated.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/telegram/_chatmemberupdated.py b/telegram/_chatmemberupdated.py index c497318a93f..80bbc49b963 100644 --- a/telegram/_chatmemberupdated.py +++ b/telegram/_chatmemberupdated.py @@ -65,7 +65,7 @@ class ChatMemberUpdated(TelegramObject): old_chat_member (:class:`telegram.ChatMember`): Previous information about the chat member. new_chat_member (:class:`telegram.ChatMember`): New information about the chat member. invite_link (:class:`telegram.ChatInviteLink`): Optional. Chat invite link, which was used - by the user to join the chat. + by the user to join the chat. For joining by invite link events only. """ From 58679f7e0088919b0be11d1a94c149a9a6d48989 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Sat, 3 Dec 2022 21:10:08 +0300 Subject: [PATCH 19/68] `File`: unify args and attrs `file_size` in attrs had wrong type too --- telegram/_files/file.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/telegram/_files/file.py b/telegram/_files/file.py index 4f917679289..61583199480 100644 --- a/telegram/_files/file.py +++ b/telegram/_files/file.py @@ -58,18 +58,19 @@ class File(TelegramObject): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`int`, optional): Optional. File size in bytes, if known. + file_size (:obj:`int`, optional): File size in bytes, if known. file_path (:obj:`str`, optional): File path. Use e.g. :meth:`download_to_drive` to get the file. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`str`): Optional. File size in bytes. - file_path (:obj:`str`): Optional. File path. Use e.g. :meth:`download_to_drive` to get - the file. + file_size (:obj:`int`): Optional. File size in bytes, if known. + file_path (:obj:`str`): Optional. File path. Use e.g. :meth:`download_to_drive` to get the + file. """ __slots__ = ( From 0e24a4b9c6890abf8c2b92098e0b135147910782 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Sat, 3 Dec 2022 21:25:56 +0300 Subject: [PATCH 20/68] `InlineKeyboardButton`: unify args and attrs, fix bold text I didn't include Tip and ..seealso from `callback_data` argument as I assume it is not put into attrs on purpose --- telegram/_inline/inlinekeyboardbutton.py | 35 +++++++++++++++--------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index 35f87ae9deb..348283953c6 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -110,7 +110,7 @@ class InlineKeyboardButton(TelegramObject): specified inline query in the input field. Can be empty, in which case just the bot's username will be inserted. This offers an easy way for users to start using your bot in inline mode when they are currently in a private chat with it. Especially useful - when combined with switch_pm* actions - in this case the user will be automatically + when combined with ``switch_pm*`` actions - in this case the user will be automatically returned to the chat they switched from, skipping the chat selection screen. 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 @@ -118,11 +118,11 @@ class InlineKeyboardButton(TelegramObject): 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. callback_game (:class:`telegram.CallbackGame`, optional): Description of the game that will - be launched when the user presses the button. This type of button must always be - the ``first`` button in the first row. + be launched when the user presses the button. This type of button **must** always be + the **first** button in the first row. pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button. This type of button - must always be the `first` button in the first row and can only be used in invoice - messages. + **must** always be the **first** button in the first row and can only be used in + invoice messages. Attributes: text (:obj:`str`): Label text on the button. @@ -148,15 +148,24 @@ class InlineKeyboardButton(TelegramObject): private chats between a user and the bot. .. versionadded:: 20.0 - switch_inline_query (:obj:`str`): Optional. 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. Can be empty, in which case just the bot's username will be inserted. - switch_inline_query_current_chat (:obj:`str`): Optional. Will insert the bot's username and - the specified inline query in the current chat's input field. Can be empty, in which - case just the bot's username will be inserted. + 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. Can be empty, in which case just the bot's + username will be inserted. This offers an easy way for users to start using your bot + in inline mode when they are currently in a private chat with it. Especially useful + when combined with ``switch_pm*`` actions - in this case the user will be automatically + returned to the chat they switched from, skipping the chat selection screen. + 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 + field. Can 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. callback_game (:class:`telegram.CallbackGame`): Optional. Description of the game that will - be launched when the user presses the button. - pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button. + be launched when the user presses the button. This type of button must always be + the ``first`` button in the first row. + pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button. This type of button + **must** always be the **first** button in the first row and can only be used in + invoice messages. """ From f4575af9d3f0b1d99116d5e41412f18a2ff0c940 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 5 Dec 2022 19:00:40 +0300 Subject: [PATCH 21/68] minor(`InlineKeyboardButton`) add ref to class it's not really needed, but at least monospace font was in place, I think, so why not put a reference --- telegram/_inline/inlinekeyboardmarkup.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/telegram/_inline/inlinekeyboardmarkup.py b/telegram/_inline/inlinekeyboardmarkup.py index 9fb6d4ee134..005fe06f3a6 100644 --- a/telegram/_inline/inlinekeyboardmarkup.py +++ b/telegram/_inline/inlinekeyboardmarkup.py @@ -42,11 +42,11 @@ class InlineKeyboardMarkup(TelegramObject): Args: inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows, - each represented by a list of InlineKeyboardButton objects. + each represented by a list of :class:`~telegram.InlineKeyboardButton` objects. Attributes: inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows, - each represented by a list of InlineKeyboardButton objects. + each represented by a list of :class:`~telegram.InlineKeyboardButton` objects. """ From 83c0a4cfe2579b7eef0c431213aaaca5c1093681 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 5 Dec 2022 19:08:16 +0300 Subject: [PATCH 22/68] minor(`MenuButtonWebApp`) add ref to class `Bot` from reading the docstr it isn't clear that it's a method of Bot --- telegram/_menubutton.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/telegram/_menubutton.py b/telegram/_menubutton.py index 4a7a84c0552..50ae87c4ff3 100644 --- a/telegram/_menubutton.py +++ b/telegram/_menubutton.py @@ -130,14 +130,16 @@ class MenuButtonWebApp(MenuButton): text (:obj:`str`): Text of the button. web_app (:class:`telegram.WebAppInfo`): 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.answerWebAppQuery`. + message on behalf of the user using the method :meth:`~telegram.Bot.answerWebAppQuery` + of :class:`~telegram.Bot`. Attributes: type (:obj:`str`): :tg-const:`telegram.constants.MenuButtonType.WEB_APP`. text (:obj:`str`): Text of the button. web_app (:class:`telegram.WebAppInfo`): 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.answerWebAppQuery`. + message on behalf of the user using the method :meth:`~telegram.Bot.answerWebAppQuery` + of :class:`~telegram.Bot`. """ __slots__ = ("text", "web_app") From df3e98415c484d45b2b7603debd8e4022e4846b1 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 5 Dec 2022 19:14:49 +0300 Subject: [PATCH 23/68] unify args and attrs in `UserProfilePhotos` --- telegram/_userprofilephotos.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/telegram/_userprofilephotos.py b/telegram/_userprofilephotos.py index 244c89fa2f2..87ae14f55cf 100644 --- a/telegram/_userprofilephotos.py +++ b/telegram/_userprofilephotos.py @@ -41,7 +41,8 @@ class UserProfilePhotos(TelegramObject): Attributes: total_count (:obj:`int`): Total number of profile pictures. - photos (List[List[:class:`telegram.PhotoSize`]]): Requested profile pictures. + photos (List[List[:class:`telegram.PhotoSize`]]): Requested profile pictures (in up to 4 + sizes each). """ From d93ac700d306c90804df647e6d24023c462eb982 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 5 Dec 2022 19:48:38 +0300 Subject: [PATCH 24/68] unify args and attrs in `StickerSet` --- telegram/_files/sticker.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/telegram/_files/sticker.py b/telegram/_files/sticker.py index 5c3e81d11af..98d0ac11c1c 100644 --- a/telegram/_files/sticker.py +++ b/telegram/_files/sticker.py @@ -223,11 +223,13 @@ class StickerSet(TelegramObject): .. versionadded:: 13.11 stickers (List[:class:`telegram.Sticker`]): List of all set stickers. - sticker_type (:obj:`str`): Type of stickers in the set. + sticker_type (:obj:`str`): Type of stickers in the set, currently one of + :attr:`telegram.Sticker.REGULAR`, :attr:`telegram.Sticker.MASK`, + :attr:`telegram.Sticker.CUSTOM_EMOJI`. .. versionadded:: 20.0 thumb (:class:`telegram.PhotoSize`): Optional. Sticker set thumbnail in the ``.WEBP``, - ``.TGS`` or ``.WEBM`` format. + ``.TGS``, or ``.WEBM`` format. """ From cce57ae81d4519981fe2b5fb48ec5ba48d173037 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 5 Dec 2022 19:49:35 +0300 Subject: [PATCH 25/68] unify args and attrs in `MaskPosition` --- telegram/_files/sticker.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/telegram/_files/sticker.py b/telegram/_files/sticker.py index 98d0ac11c1c..90dc25dedff 100644 --- a/telegram/_files/sticker.py +++ b/telegram/_files/sticker.py @@ -307,9 +307,11 @@ class MaskPosition(TelegramObject): point (:obj:`str`): The part of the face relative to which the mask should be placed. One of :attr:`FOREHEAD`, :attr:`EYES`, :attr:`MOUTH`, or :attr:`CHIN`. x_shift (:obj:`float`): Shift by X-axis measured in widths of the mask scaled to the face - size, from left to right. + size, from left to right. For example, choosing ``-1.0`` will place mask just to the + left of the default mask position. y_shift (:obj:`float`): Shift by Y-axis measured in heights of the mask scaled to the face - size, from top to bottom. + size, from top to bottom. For example, ``1.0`` will place the mask just below the + default mask position. scale (:obj:`float`): Mask scaling coefficient. For example, ``2.0`` means double size. """ From d796bf46db192b6014dc8ece07c3cd50e590b921 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 5 Dec 2022 19:51:52 +0300 Subject: [PATCH 26/68] unify args and attrs in `Sticker` --- telegram/_files/sticker.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/telegram/_files/sticker.py b/telegram/_files/sticker.py index 90dc25dedff..eb24f8d2719 100644 --- a/telegram/_files/sticker.py +++ b/telegram/_files/sticker.py @@ -62,10 +62,9 @@ class Sticker(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`, optional): Sticker thumbnail in the ``.WEBP`` or ``.JPG`` format. emoji (:obj:`str`, optional): Emoji associated with the sticker - set_name (:obj:`str`, optional): Name of the sticker set to which the sticker - belongs. - mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the - position where the mask should be placed. + set_name (:obj:`str`, optional): Name of the sticker set to which the sticker belongs. + mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the position + where the mask should be placed. file_size (:obj:`int`, optional): File size in bytes. premium_animation (:class:`telegram.File`, optional): For premium regular stickers, @@ -78,7 +77,8 @@ class Sticker(_BaseThumbedMedium): .. versionadded:: 20.0 Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. From 94bd384deef4cda17752e3b53a9e9ee6fd989025 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 5 Dec 2022 19:54:44 +0300 Subject: [PATCH 27/68] unify args and attrs in `BotCommand` --- telegram/_botcommand.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/telegram/_botcommand.py b/telegram/_botcommand.py index 650a2b59a7d..795845dac8a 100644 --- a/telegram/_botcommand.py +++ b/telegram/_botcommand.py @@ -41,8 +41,12 @@ class BotCommand(TelegramObject): :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters. Attributes: - command (:obj:`str`): Text of the command. - description (:obj:`str`): Description of the command. + command (:obj:`str`): Text of the command; :tg-const:`telegram.BotCommand.MIN_COMMAND`- + :tg-const:`telegram.BotCommand.MAX_COMMAND` characters. Can contain only lowercase + English letters, digits and underscores. + description (:obj:`str`): Description of the command; + :tg-const:`telegram.BotCommand.MIN_DESCRIPTION`- + :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters. """ From d4d360094faf25ed112c3e444c28d8ca22a70f83 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Mon, 5 Dec 2022 20:04:55 +0300 Subject: [PATCH 28/68] unify args and attrs in `Game` text_entities was not marked with 'Optional.' in attrs. Leaving the phrase that is not there in Telegram API: "This list is empty if the message does not contain text entities." --- telegram/_games/game.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/telegram/_games/game.py b/telegram/_games/game.py index e7228d3957c..a52f86d5e4a 100644 --- a/telegram/_games/game.py +++ b/telegram/_games/game.py @@ -63,7 +63,8 @@ class Game(TelegramObject): game message. Can be automatically edited to include current high scores for the game when the bot calls :meth:`telegram.Bot.set_game_score`, or manually edited using :meth:`telegram.Bot.edit_message_text`. - text_entities (List[:class:`telegram.MessageEntity`]): Special entities that + 0-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters. + text_entities (List[:class:`telegram.MessageEntity`]): Optional. Special entities that appear in text, such as usernames, URLs, bot commands, etc. This list is empty if the message does not contain text entities. animation (:class:`telegram.Animation`): Optional. Animation that will be displayed in the From 8b81e1f4b908ced6dd1ee42032c9d3ade3b5a109 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Tue, 6 Dec 2022 20:14:37 +0300 Subject: [PATCH 29/68] `Animation`: unify args and attrs --- telegram/_files/animation.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/telegram/_files/animation.py b/telegram/_files/animation.py index 13ada07e15b..4202f218b6f 100644 --- a/telegram/_files/animation.py +++ b/telegram/_files/animation.py @@ -44,7 +44,8 @@ class Animation(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): File identifier. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. From 9828dab12c572396d43ace5017f3459929ae1e3a Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Tue, 6 Dec 2022 20:16:40 +0300 Subject: [PATCH 30/68] `Audio`: unify args and attrs --- telegram/_files/audio.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/telegram/_files/audio.py b/telegram/_files/audio.py index a4a0cc06440..be776714456 100644 --- a/telegram/_files/audio.py +++ b/telegram/_files/audio.py @@ -46,11 +46,11 @@ class Audio(_BaseThumbedMedium): which the music file belongs. Attributes: - file_id (:obj:`str`): Identifier for this file. - file_unique_id (:obj:`str`): Unique identifier for this file, which - is supposed to be the same over time and for different bots. - Can't be used to download or reuse the file. - duration (:obj:`int`): Duration of the audio in seconds. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. + file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be + the same over time and for different bots. Can't be used to download or reuse the file. + duration (:obj:`int`): Duration of the audio in seconds as defined by sender. performer (:obj:`str`): Optional. Performer of the audio as defined by sender or by audio tags. title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags. From b2c36067c27d196b5ca9775479b46814db25f55e Mon Sep 17 00:00:00 2001 From: Harshil <37377066+harshil21@users.noreply.github.com> Date: Wed, 7 Dec 2022 20:39:49 +0530 Subject: [PATCH 31/68] update furo --- docs/requirements-docs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 51e35d83dbd..2f8cd82483f 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,6 +1,6 @@ sphinx==5.3.0 sphinx-pypi-upload -furo==2022.9.29 +furo==2022.12.7 git+https://github.com/harshil21/furo-sphinx-search@be5cfa221a01f6e259bb2bb1f76d6ede7ffc1f11#egg=furo-sphinx-search sphinx-paramlinks==0.5.4 sphinxcontrib-mermaid==0.7.1 \ No newline at end of file From c11ba1e5ff1b2084de1cfcfca9e607144f31e8a9 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Wed, 7 Dec 2022 19:14:18 +0300 Subject: [PATCH 32/68] fix(`ChatPhoto`) rm "unique" from docstring of `big/small_file_id` attrs --- telegram/_files/chatphoto.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/telegram/_files/chatphoto.py b/telegram/_files/chatphoto.py index 9e55efa2dfc..6f2640886d1 100644 --- a/telegram/_files/chatphoto.py +++ b/telegram/_files/chatphoto.py @@ -36,7 +36,7 @@ class ChatPhoto(TelegramObject): equal. Args: - small_file_id (:obj:`str`): Unique file identifier of small + small_file_id (:obj:`str`): File identifier of small (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed. @@ -44,7 +44,7 @@ class ChatPhoto(TelegramObject): (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`) chat photo, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - big_file_id (:obj:`str`): Unique file identifier of big + big_file_id (:obj:`str`): File identifier of big (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed. From c893aa56c0b2d36ceead5c3e135dccfd9028705d Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Wed, 7 Dec 2022 19:17:47 +0300 Subject: [PATCH 33/68] 'Document': unify args and attrs including fix of lacking "Optional" in `.file_name` --- telegram/_files/document.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/telegram/_files/document.py b/telegram/_files/document.py index e650ebde466..e09bdc4fb7e 100644 --- a/telegram/_files/document.py +++ b/telegram/_files/document.py @@ -41,16 +41,15 @@ class Document(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): File identifier. - file_unique_id (:obj:`str`): Unique identifier for this file, which - is supposed to be the same over time and for different bots. - Can't be used to download or reuse the file. - thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail. - file_name (:obj:`str`): Original filename. - mime_type (:obj:`str`): Optional. MIME type of the file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. + file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be + the same over time and for different bots. Can't be used to download or reuse the file. + thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail as defined by sender. + file_name (:obj:`str`): Optional. Original filename as defined by sender. + mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender. file_size (:obj:`int`): Optional. File size in bytes. - """ __slots__ = ("file_name", "mime_type") From d8f9f28920f1ff1150f0a3a4dcf9d91c94aadb80 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Wed, 7 Dec 2022 19:29:44 +0300 Subject: [PATCH 34/68] 'Force Reply': unify args and attrs I decided to include the explanation for `selective` as well, but removed the phrase "Use this parameter" as it makes no sense in attrs --- telegram/_forcereply.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/telegram/_forcereply.py b/telegram/_forcereply.py index 459d2a9eb40..b11ffc0bd5d 100644 --- a/telegram/_forcereply.py +++ b/telegram/_forcereply.py @@ -59,9 +59,17 @@ class ForceReply(TelegramObject): Attributes: force_reply (:obj:`True`): Shows reply interface to the user, as if they manually selected the bots message and tapped 'Reply'. - selective (:obj:`bool`): Optional. Force reply from specific users only. - input_field_placeholder (:obj:`str`): Optional. The placeholder shown in the input - field when the reply is active. + selective (:obj:`bool`): Optional. Force reply from specific users only. Targets: + + 1) Users that are @mentioned in the :attr:`~telegram.Message.text` of the + :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of the + original message. + input_field_placeholder (:obj:`str`): Optional. The placeholder to be shown in the input + field when the reply is active; + :tg-const:`telegram.ForceReply.MIN_INPUT_FIELD_PLACEHOLDER`- + :tg-const:`telegram.ForceReply.MAX_INPUT_FIELD_PLACEHOLDER` + characters. .. versionadded:: 13.7 From 00c4087f01fadeacffc63fc3754cb420e2991528 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Wed, 7 Dec 2022 19:38:23 +0300 Subject: [PATCH 35/68] 'InputMedia': unify args and attrs I decided to add substitution strings to `parse_mode` and `caption_entities`, but did not duplicate `media` arg in attrs --- telegram/_files/inputmedia.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/telegram/_files/inputmedia.py b/telegram/_files/inputmedia.py index 75cd519629d..f7751da0077 100644 --- a/telegram/_files/inputmedia.py +++ b/telegram/_files/inputmedia.py @@ -61,10 +61,11 @@ class InputMedia(TelegramObject): Attributes: type (:obj:`str`): Type of the input media. media (:obj:`str` | :class:`telegram.InputFile`): Media to send. - caption (:obj:`str`): Optional. Caption of the media to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. - caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special - entities that appear in the caption. + caption (:obj:`str`): Optional. Caption of the media to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities + parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| """ __slots__ = ("caption", "caption_entities", "media", "parse_mode", "type") From 75119387bf7a433ff1532e03df85649192400c31 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Wed, 7 Dec 2022 19:52:09 +0300 Subject: [PATCH 36/68] minor: remove trailing colon in `versionchanged` Sphinx adds a colon automatically --- telegram/_files/file.py | 2 +- telegram/_files/inputmedia.py | 2 +- telegram/_files/sticker.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/telegram/_files/file.py b/telegram/_files/file.py index 61583199480..659e2912597 100644 --- a/telegram/_files/file.py +++ b/telegram/_files/file.py @@ -42,7 +42,7 @@ class File(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`file_unique_id` is equal. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 ``download`` was split into :meth:`download_to_drive` and :meth:`download_to_memory`. Note: diff --git a/telegram/_files/inputmedia.py b/telegram/_files/inputmedia.py index f7751da0077..d424c970bca 100644 --- a/telegram/_files/inputmedia.py +++ b/telegram/_files/inputmedia.py @@ -39,7 +39,7 @@ class InputMedia(TelegramObject): """ Base class for Telegram InputMedia Objects. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 Added arguments and attributes :attr:`type`, :attr:`media`, :attr:`caption`, :attr:`caption_entities`, :paramref:`parse_mode`. diff --git a/telegram/_files/sticker.py b/telegram/_files/sticker.py index eb24f8d2719..42f7e0e3735 100644 --- a/telegram/_files/sticker.py +++ b/telegram/_files/sticker.py @@ -196,7 +196,7 @@ class StickerSet(TelegramObject): arguments had to be changed. Use keyword arguments to make sure that the arguments are passed correctly. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 The parameter ``contains_masks`` has been removed. Use :paramref:`sticker_type` instead. Args: From c92d81858a6b9a862b1ea603cd89928945742d3a Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Wed, 7 Dec 2022 20:47:26 +0300 Subject: [PATCH 37/68] `PhotoSize`: unify args and attrs --- telegram/_files/photosize.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/telegram/_files/photosize.py b/telegram/_files/photosize.py index 86fc391426b..9862abea303 100644 --- a/telegram/_files/photosize.py +++ b/telegram/_files/photosize.py @@ -39,7 +39,8 @@ class PhotoSize(_BaseMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. From 7b153117c02cb9b003b9ae4cb3e4d9fcaa4272b5 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Wed, 7 Dec 2022 20:57:09 +0300 Subject: [PATCH 38/68] `ReplyKeyboardMarkup`: unify args and attrs, fix type of `.keyboard` attr --- telegram/_replykeyboardmarkup.py | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/telegram/_replykeyboardmarkup.py b/telegram/_replykeyboardmarkup.py index ca391f4bf66..87e2a8c07f7 100644 --- a/telegram/_replykeyboardmarkup.py +++ b/telegram/_replykeyboardmarkup.py @@ -70,13 +70,31 @@ class ReplyKeyboardMarkup(TelegramObject): .. versionadded:: 13.7 Attributes: - keyboard (List[List[:class:`telegram.KeyboardButton` | :obj:`str`]]): Array of button rows. - resize_keyboard (:obj:`bool`): Optional. Requests clients to resize the keyboard. + keyboard (List[List[:class:`telegram.KeyboardButton`]]): Array of button rows, + each represented by an Array of :class:`telegram.KeyboardButton` objects. + resize_keyboard (:obj:`bool`): Optional. Requests clients to resize the keyboard vertically + for optimal fit (e.g., make the keyboard smaller if there are just two rows of + buttons). Defaults to :obj:`False`, in which case the custom keyboard is always of the + same height as the app's standard keyboard. one_time_keyboard (:obj:`bool`): Optional. Requests clients to hide the keyboard as soon as - it's been used. + it's been used. The keyboard will still be available, but clients will automatically + display the usual letter-keyboard in the chat - the user can press a special button in + the input field to see the custom keyboard again. Defaults to :obj:`False`. selective (:obj:`bool`): Optional. Show the keyboard to specific users only. - input_field_placeholder (:obj:`str`): Optional. The placeholder shown in the input - field when the reply is active. + Targets: + + 1) Users that are @mentioned in the :attr:`~telegram.Message.text` of the + :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of the + original message. + + Defaults to :obj:`False`. + + input_field_placeholder (:obj:`str`): Optional. The placeholder to be shown in the input + field when the keyboard is active; + :tg-const:`telegram.ReplyKeyboardMarkup.MIN_INPUT_FIELD_PLACEHOLDER`- + :tg-const:`telegram.ReplyKeyboardMarkup.MAX_INPUT_FIELD_PLACEHOLDER` + characters. .. versionadded:: 13.7 From cc93abf16c1f2fe9c6eab255c3ef58bd349c9f0e Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 13:01:01 +0300 Subject: [PATCH 39/68] `ReplyKeyboardRemove`: unify args and attrs --- telegram/_replykeyboardremove.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/telegram/_replykeyboardremove.py b/telegram/_replykeyboardremove.py index 7765c37f774..42dacc03dae 100644 --- a/telegram/_replykeyboardremove.py +++ b/telegram/_replykeyboardremove.py @@ -45,13 +45,17 @@ class ReplyKeyboardRemove(TelegramObject): for specific users only. Targets: 1) Users that are @mentioned in the text of the :class:`telegram.Message` object. - 2) If the bot's message is a reply (has `reply_to_message_id`), sender of the original - message. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of + the original message. Attributes: remove_keyboard (:obj:`True`): Requests clients to remove the custom keyboard. - selective (:obj:`bool`): Optional. Use this parameter if you want to remove the keyboard - for specific users only. + selective (:obj:`bool`): Optional. Remove the keyboard for specific users only. + Targets: + + 1) Users that are @mentioned in the text of the :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of + the original message. """ From 3e0f7910ea869e26f12999829d8144279bb5553e Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 13:25:51 +0300 Subject: [PATCH 40/68] `InputMedia...`: unify args and attrs + fix `InputMediaAudio.duration` * not changing docstr of `media` attr * move `thumb` up in attrs where applicable and apply |thumbdocstringbase| substitution (only the base should suffice as no directions are needed on how to send the file) * add "optional" to `duration` arg and attr of InputMediaAudio --- telegram/_files/inputmedia.py | 63 +++++++++++++++++++---------------- 1 file changed, 34 insertions(+), 29 deletions(-) diff --git a/telegram/_files/inputmedia.py b/telegram/_files/inputmedia.py index d424c970bca..0e39771818a 100644 --- a/telegram/_files/inputmedia.py +++ b/telegram/_files/inputmedia.py @@ -133,11 +133,12 @@ class InputMediaAnimation(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.ANIMATION`. media (:obj:`str` | :class:`telegram.InputFile`): Animation to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. - caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special - entities that appear in the caption. - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| + caption (:obj:`str`): Optional. Caption of the animation to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| width (:obj:`int`): Optional. Animation width. height (:obj:`int`): Optional. Animation height. duration (:obj:`int`): Optional. Animation duration in seconds. @@ -208,10 +209,11 @@ class InputMediaPhoto(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.PHOTO`. media (:obj:`str` | :class:`telegram.InputFile`): Photo to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. - caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special - entities that appear in the caption. + caption (:obj:`str`): Optional. Caption of the photo to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| """ @@ -282,16 +284,17 @@ class InputMediaVideo(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.VIDEO`. media (:obj:`str` | :class:`telegram.InputFile`): Video file to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. - caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special - entities that appear in the caption. + caption (:obj:`str`): Optional. Caption of the video to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| width (:obj:`int`): Optional. Video width. height (:obj:`int`): Optional. Video height. duration (:obj:`int`): Optional. Video duration in seconds. - supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is + supports_streaming (:obj:`bool`): Optional. :obj:`True`, if the uploaded video is suitable for streaming. - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| """ @@ -363,7 +366,7 @@ class InputMediaAudio(InputMedia): entities parsing. parse_mode (:obj:`str`, optional): |parse_mode| caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| - duration (:obj:`int`): Duration of the audio in seconds as defined by sender. + duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender. performer (:obj:`str`, optional): Performer of the audio as defined by sender or by audio tags. title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags. @@ -376,15 +379,16 @@ class InputMediaAudio(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.AUDIO`. media (:obj:`str` | :class:`telegram.InputFile`): Audio file to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. - caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special - entities that appear in the caption. - duration (:obj:`int`): Duration of the audio in seconds. + caption (:obj:`str`): Optional. Caption of the audio to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| + duration (:obj:`int`): Optional. Duration of the audio in seconds. performer (:obj:`str`): Optional. Performer of the audio as defined by sender or by audio tags. title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags. - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| """ @@ -460,14 +464,15 @@ class InputMediaDocument(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.DOCUMENT`. media (:obj:`str` | :class:`telegram.InputFile`): File to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. - caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special - entities that appear in the caption. - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + caption (:obj:`str`): Optional. Caption of the document to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| disable_content_type_detection (:obj:`bool`): Optional. Disables automatic server-side - content type detection for files uploaded using multipart/form-data. Always true, if - the document is sent as part of an album. + content type detection for files uploaded using multipart/form-data. Always + :obj:`True`, if the document is sent as part of an album. """ From eabf48010ed7e7e332b71479ec8dee4443c4f155 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 13:31:19 +0300 Subject: [PATCH 41/68] minor(`InlineKeyboardButton`): add bold in `callback_game` attr --- telegram/_inline/inlinekeyboardbutton.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index 348283953c6..037db1e6f79 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -161,8 +161,8 @@ class InlineKeyboardButton(TelegramObject): 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. callback_game (:class:`telegram.CallbackGame`): Optional. Description of the game that will - be launched when the user presses the button. This type of button must always be - the ``first`` button in the first row. + be launched when the user presses the button. This type of button **must** always be + the **first** button in the first row. pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button. This type of button **must** always be the **first** button in the first row and can only be used in invoice messages. From 821b33da96b5b9940cc94f58284c5097335b8432 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 13:34:46 +0300 Subject: [PATCH 42/68] `KeyboardButton`: unify args and attrs --- telegram/_keyboardbutton.py | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/telegram/_keyboardbutton.py b/telegram/_keyboardbutton.py index a0511e17e67..84058f5951d 100644 --- a/telegram/_keyboardbutton.py +++ b/telegram/_keyboardbutton.py @@ -68,12 +68,19 @@ class KeyboardButton(TelegramObject): .. versionadded:: 20.0 Attributes: - text (:obj:`str`): Text of the button. - request_contact (:obj:`bool`): Optional. The user's phone number will be sent. - request_location (:obj:`bool`): Optional. The user's current location will be sent. - request_poll (:class:`KeyboardButtonPollType`): Optional. If the user should create a poll. - web_app (:class:`WebAppInfo`): Optional. If the described Web App will be launched when the - button is pressed. + text (:obj:`str`): Text of the button. If none of the optional fields are used, it will be + sent to the bot as a message when the button is pressed. + request_contact (:obj:`bool`): Optional. If :obj:`True`, the user's phone number will be + sent as a contact when the button is pressed. Available in private chats only. + request_location (:obj:`bool`): Optional. If :obj:`True`, the user's current location will + be sent when the button is pressed. Available in private chats only. + request_poll (:class:`KeyboardButtonPollType`): Optional. If specified, the user will be + asked to create a poll and send it to the bot when the button is pressed. Available in + private chats only. + web_app (:class:`WebAppInfo`): Optional. If specified, the described `Web App + `_ will be launched when the button is pressed. + The Web App will be able to send a :attr:`Message.web_app_data` service message. + Available in private chats only. .. versionadded:: 20.0 """ From 110c0302002845b76ec79060d71405234e6a266f Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 13:41:47 +0300 Subject: [PATCH 43/68] fix(`KeyboardButtonPollType`): add `Args:` section re-formulate attrs section without "is passed" phrases --- telegram/_keyboardbuttonpolltype.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/telegram/_keyboardbuttonpolltype.py b/telegram/_keyboardbuttonpolltype.py index ae78389804a..1c8f0d97ebb 100644 --- a/telegram/_keyboardbuttonpolltype.py +++ b/telegram/_keyboardbuttonpolltype.py @@ -32,11 +32,16 @@ class KeyboardButtonPollType(TelegramObject): Examples: :any:`Poll Bot ` - Attributes: - type (:obj:`str`): Optional. If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be + Args: + type (:obj:`str`, optional): If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be allowed to create only polls in the quiz mode. If :tg-const:`telegram.Poll.REGULAR` is passed, only regular polls will be allowed. Otherwise, the user will be allowed to create a poll of any type. + Attributes: + type (:obj:`str`): Optional. If equals :tg-const:`telegram.Poll.QUIZ`, the user will + be allowed to create only polls in the quiz mode. If equals + :tg-const:`telegram.Poll.REGULAR`, only regular polls will be allowed. + Otherwise, the user will be allowed to create a poll of any type. """ __slots__ = ("type",) From 8789beaafa1f92b06e05af36d490e17c537daded Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 14:07:54 +0300 Subject: [PATCH 44/68] `Venue`: unify args and attrs I see no harm in adding links/examples for types --- telegram/_files/venue.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/telegram/_files/venue.py b/telegram/_files/venue.py index a87cfb57342..abdcb8f99fe 100644 --- a/telegram/_files/venue.py +++ b/telegram/_files/venue.py @@ -55,9 +55,12 @@ class Venue(TelegramObject): title (:obj:`str`): Name of the venue. address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue. - foursquare_type (:obj:`str`): Optional. Foursquare type of the venue. + foursquare_type (:obj:`str`): Optional. Foursquare type of the venue. (For example, + "arts_entertainment/default", "arts_entertainment/aquarium" or "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) """ From de1e9e61ba0f4d0135d08b9ffce8dc20c50de420 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 14:09:27 +0300 Subject: [PATCH 45/68] `Video`: unify args and attrs --- telegram/_files/video.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/telegram/_files/video.py b/telegram/_files/video.py index c3c632f68b8..2abc4213549 100644 --- a/telegram/_files/video.py +++ b/telegram/_files/video.py @@ -44,7 +44,8 @@ class Video(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. @@ -56,7 +57,6 @@ class Video(_BaseThumbedMedium): mime_type (:obj:`str`): Optional. MIME type of a file as defined by sender. file_size (:obj:`int`): Optional. File size in bytes. - """ __slots__ = ("duration", "file_name", "height", "mime_type", "width") From 864d9da286cd60554b58c637928d0100afefab04 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 14:11:49 +0300 Subject: [PATCH 46/68] `VideoNote`: unify args and attrs --- telegram/_files/videonote.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/telegram/_files/videonote.py b/telegram/_files/videonote.py index 5dd7941a169..8c945ecfdd0 100644 --- a/telegram/_files/videonote.py +++ b/telegram/_files/videonote.py @@ -42,11 +42,13 @@ class VideoNote(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - length (:obj:`int`): Video width and height as defined by sender. + length (:obj:`int`): Video width and height (diameter of the video message) as defined + by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender. thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail. file_size (:obj:`int`): Optional. File size in bytes. From 2890c0bd8f08bb9098ff3334132805822bf76ae0 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Thu, 8 Dec 2022 14:24:01 +0300 Subject: [PATCH 47/68] `Voice`: unify args and attrs + fix `duration` duration arg is not optional in `Voice` --- telegram/_files/voice.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/telegram/_files/voice.py b/telegram/_files/voice.py index 22346d3c095..7568a3ea41f 100644 --- a/telegram/_files/voice.py +++ b/telegram/_files/voice.py @@ -34,12 +34,13 @@ class Voice(_BaseMedium): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender. + duration (:obj:`int`): Duration of the audio in seconds as defined by sender. mime_type (:obj:`str`, optional): MIME type of the file as defined by sender. file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. From 2fe6d368cc261ab73c3fa2e2e85c58ce5f00ce71 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 00:13:05 +0300 Subject: [PATCH 48/68] `ChosenInlineResult`: unify args and attrs --- telegram/_choseninlineresult.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/telegram/_choseninlineresult.py b/telegram/_choseninlineresult.py index 67d29d501f2..233e651c1cd 100644 --- a/telegram/_choseninlineresult.py +++ b/telegram/_choseninlineresult.py @@ -56,8 +56,11 @@ class ChosenInlineResult(TelegramObject): Attributes: result_id (:obj:`str`): The unique identifier for the result that was chosen. from_user (:class:`telegram.User`): The user that chose the result. - location (:class:`telegram.Location`): Optional. Sender location. - inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message. + location (:class:`telegram.Location`): Optional. Sender location, only for bots that + require user location. + inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message. Available + only if there is an inline keyboard attached to the message. Will be also received in + callback queries and can be used to edit the message. query (:obj:`str`): The query that was used to obtain the result. """ From b2941669335b05d13bf16dd4c9ebefe6c0cb6b1a Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 00:14:57 +0300 Subject: [PATCH 49/68] `InlineQuery`: unify args and attrs --- telegram/_inline/inlinequery.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/telegram/_inline/inlinequery.py b/telegram/_inline/inlinequery.py index 963e6dfe1c6..9a7fa6acfe1 100644 --- a/telegram/_inline/inlinequery.py +++ b/telegram/_inline/inlinequery.py @@ -72,11 +72,16 @@ class InlineQuery(TelegramObject): query (:obj:`str`): Text of the query (up to :tg-const:`telegram.InlineQuery.MAX_QUERY_LENGTH` characters). offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot. - location (:class:`telegram.Location`): Optional. Sender location, only for bots that - request user location. chat_type (:obj:`str`): Optional. Type of the chat, from which the inline query was sent. + Can be either :tg-const:`telegram.Chat.SENDER` for a private chat with the inline query + sender, :tg-const:`telegram.Chat.PRIVATE`, :tg-const:`telegram.Chat.GROUP`, + :tg-const:`telegram.Chat.SUPERGROUP` or :tg-const:`telegram.Chat.CHANNEL`. The chat + type should be always known for requests sent from official clients and most + third-party clients, unless the request was sent from a secret chat. .. versionadded:: 13.5 + location (:class:`telegram.Location`): Optional. Sender location, only for bots that + request user location. """ From be96d7a567ca03dc9905cd768022b25144e1cdbd Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 00:25:45 +0300 Subject: [PATCH 50/68] `InlineQueryResultCachedAudio`: fix typo in attrs --- telegram/_inline/inlinequeryresultcachedaudio.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/telegram/_inline/inlinequeryresultcachedaudio.py b/telegram/_inline/inlinequeryresultcachedaudio.py index db2afa6ddaa..d1b403e3ead 100644 --- a/telegram/_inline/inlinequeryresultcachedaudio.py +++ b/telegram/_inline/inlinequeryresultcachedaudio.py @@ -61,7 +61,7 @@ class InlineQueryResultCachedAudio(InlineQueryResult): caption (:obj:`str`): Optional. Caption, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`, optionals): |parse_mode| + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. From 5a8468bc298fb83247dc6a5b5a2e9a10bb671a2a Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 00:30:04 +0300 Subject: [PATCH 51/68] `InlineQueryResultCachedGif`: fix typo in args `caption` was doubled in `title` arg --- telegram/_inline/inlinequeryresultcachedgif.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/telegram/_inline/inlinequeryresultcachedgif.py b/telegram/_inline/inlinequeryresultcachedgif.py index 9f463192ab4..05eaa07021d 100644 --- a/telegram/_inline/inlinequeryresultcachedgif.py +++ b/telegram/_inline/inlinequeryresultcachedgif.py @@ -43,7 +43,7 @@ class InlineQueryResultCachedGif(InlineQueryResult): :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes. gif_file_id (:obj:`str`): A valid file identifier for the GIF file. - title (:obj:`str`, optional): Title for the result.caption (:obj:`str`, optional): + title (:obj:`str`, optional): Title for the result. caption (:obj:`str`, optional): Caption of the GIF file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. From 5456f22d2821d50ffcfee94f24014101a2b8d233 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 13:39:16 +0300 Subject: [PATCH 52/68] `InlineQueryResult...[...Gif/...Mpeg4Gif]`: unify args and attrs --- telegram/_inline/inlinequeryresultgif.py | 3 ++- telegram/_inline/inlinequeryresultmpeg4gif.py | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/telegram/_inline/inlinequeryresultgif.py b/telegram/_inline/inlinequeryresultgif.py index 39eab95ed47..c23fa1dc6fd 100644 --- a/telegram/_inline/inlinequeryresultgif.py +++ b/telegram/_inline/inlinequeryresultgif.py @@ -71,7 +71,8 @@ class InlineQueryResultGif(InlineQueryResult): gif_duration (:obj:`int`): Optional. Duration of the GIF in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. - thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail. + thumb_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'``. title (:obj:`str`): Optional. Title for the result. caption (:obj:`str`): Optional. Caption of the GIF file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters diff --git a/telegram/_inline/inlinequeryresultmpeg4gif.py b/telegram/_inline/inlinequeryresultmpeg4gif.py index 448a9c91b87..f5a514ca9ed 100644 --- a/telegram/_inline/inlinequeryresultmpeg4gif.py +++ b/telegram/_inline/inlinequeryresultmpeg4gif.py @@ -46,7 +46,8 @@ 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. - thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result. + thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for + the result. thumb_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'``. title (:obj:`str`, optional): Title for the result. @@ -71,7 +72,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): mpeg4_duration (:obj:`int`): Optional. Video duration in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. - thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail. + thumb_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'``. title (:obj:`str`): Optional. Title for the result. caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters From 66a4d68029dd44e0e7de5ec9d58ab07ec299e87d Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 13:48:46 +0300 Subject: [PATCH 53/68] `InlineQueryResultLocation`: unify args and attrs --- telegram/_inline/inlinequeryresultlocation.py | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/telegram/_inline/inlinequeryresultlocation.py b/telegram/_inline/inlinequeryresultlocation.py index 02a27d0c99a..d0b33d6842b 100644 --- a/telegram/_inline/inlinequeryresultlocation.py +++ b/telegram/_inline/inlinequeryresultlocation.py @@ -75,13 +75,21 @@ class InlineQueryResultLocation(InlineQueryResult): longitude (:obj:`float`): Location longitude in degrees. title (:obj:`str`): Location title. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. - live_period (:obj:`int`): Optional. Period in seconds for which the location can be - updated, should be between 60 and 86400. + measured in meters; 0- + :tg-const:`telegram.InlineQueryResultLocation.HORIZONTAL_ACCURACY`. + live_period (:obj:`int`): Optional. Period in seconds for which the location will be + updated, should be between + :tg-const:`telegram.InlineQueryResultLocation.MIN_LIVE_PERIOD` and + :tg-const:`telegram.InlineQueryResultLocation.MAX_LIVE_PERIOD`. heading (:obj:`int`): Optional. For live locations, a direction in which the user is - moving, in degrees. - proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance for - proximity alerts about approaching another chat member, in meters. + moving, in degrees. Must be between + :tg-const:`telegram.InlineQueryResultLocation.MIN_HEADING` and + :tg-const:`telegram.InlineQueryResultLocation.MAX_HEADING` if specified. + proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance + for proximity alerts about approaching another chat member, in meters. Must be + between :tg-const:`telegram.InlineQueryResultLocation.MIN_PROXIMITY_ALERT_RADIUS` + and :tg-const:`telegram.InlineQueryResultLocation.MAX_PROXIMITY_ALERT_RADIUS` + if specified. reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the From 756994f650b2452ee4305cc9b888167c18f9e6a8 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 13:51:03 +0300 Subject: [PATCH 54/68] `InlineQueryResultVenue`: unify args and attrs --- telegram/_inline/inlinequeryresultvenue.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/telegram/_inline/inlinequeryresultvenue.py b/telegram/_inline/inlinequeryresultvenue.py index 6c16808406d..ef319924a88 100644 --- a/telegram/_inline/inlinequeryresultvenue.py +++ b/telegram/_inline/inlinequeryresultvenue.py @@ -58,7 +58,7 @@ class InlineQueryResultVenue(InlineQueryResult): reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the - message to be sent instead of the location. + message to be sent instead of the venue. thumb_url (:obj:`str`, optional): Url of the thumbnail for the result. thumb_width (:obj:`int`, optional): Thumbnail width. thumb_height (:obj:`int`, optional): Thumbnail height. @@ -74,8 +74,12 @@ class InlineQueryResultVenue(InlineQueryResult): address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue if known. foursquare_type (:obj:`str`): Optional. Foursquare type of the venue, if known. + (For example, "arts_entertainment/default", "arts_entertainment/aquarium" or + "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the From 0c0f200533bad7cd25357e35fe7fc91233a0bed6 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 13:55:54 +0300 Subject: [PATCH 55/68] `InlineQueryResultVideo`: unify args and attrs in attrs, all "optional" marks were done as in args, fix that --- telegram/_inline/inlinequeryresultvideo.py | 28 +++++++++++----------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/telegram/_inline/inlinequeryresultvideo.py b/telegram/_inline/inlinequeryresultvideo.py index 903865e2e3e..3b4c237f0ec 100644 --- a/telegram/_inline/inlinequeryresultvideo.py +++ b/telegram/_inline/inlinequeryresultvideo.py @@ -50,7 +50,7 @@ class InlineQueryResultVideo(InlineQueryResult): mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4". thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video. title (:obj:`str`): Title for the result. - caption (:obj:`str`, optional): Caption, + caption (:obj:`str`, optional): Caption of the video to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. parse_mode (:obj:`str`, optional): |parse_mode| @@ -63,7 +63,7 @@ class InlineQueryResultVideo(InlineQueryResult): to the message. input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the message to be sent instead of the video. This field is required if - InlineQueryResultVideo is used to send an HTML-page as a result + ``InlineQueryResultVideo`` is used to send an HTML-page as a result (e.g., a YouTube video). Attributes: @@ -75,20 +75,20 @@ class InlineQueryResultVideo(InlineQueryResult): mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4". thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video. 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. - parse_mode (:obj:`str`, optional): |parse_mode| - caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| - video_width (:obj:`int`, optional): Video width. - video_height (:obj:`int`, optional): Video height. - video_duration (:obj:`int`, optional): Video duration in seconds. - description (:obj:`str`, optional): Short description of the result. - reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached + caption (:obj:`str`): Optional. Caption of the video to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities + parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| + video_width (:obj:`int`): Optional. Video width. + video_height (:obj:`int`): Optional. Video height. + video_duration (:obj:`int`): Optional. Video duration in seconds. + description (:obj:`str`): Optional. Short description of the result. + reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. - input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the + input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the message to be sent instead of the video. This field is required if - InlineQueryResultVideo is used to send an HTML-page as a result + ``InlineQueryResultVideo`` is used to send an HTML-page as a result (e.g., a YouTube video). """ From 2bb01040a3a7fdc0a33cd32cd3853141f5ff78ae Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 13:58:42 +0300 Subject: [PATCH 56/68] `InputTextMessageContent`: unify args and attrs --- telegram/_inline/inputtextmessagecontent.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/telegram/_inline/inputtextmessagecontent.py b/telegram/_inline/inputtextmessagecontent.py index cbde72169ba..d22e5b44a49 100644 --- a/telegram/_inline/inputtextmessagecontent.py +++ b/telegram/_inline/inputtextmessagecontent.py @@ -48,7 +48,8 @@ class InputTextMessageContent(InputMessageContent): Attributes: message_text (:obj:`str`): Text of the message to be sent, - 1-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters after entities + :tg-const:`telegram.constants.MessageLimit.MIN_TEXT_LENGTH`- + :tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters after entities parsing. parse_mode (:obj:`str`): Optional. |parse_mode| entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities| From f56313cdad8aec7f6a2f000ce891970db1813e96 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 14:01:32 +0300 Subject: [PATCH 57/68] `InputLocationMessageContent`: unify args and attrs --- .../_inline/inputlocationmessagecontent.py | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/telegram/_inline/inputlocationmessagecontent.py b/telegram/_inline/inputlocationmessagecontent.py index 717749db208..5a42e5f4ced 100644 --- a/telegram/_inline/inputlocationmessagecontent.py +++ b/telegram/_inline/inputlocationmessagecontent.py @@ -57,13 +57,21 @@ class InputLocationMessageContent(InputMessageContent): latitude (:obj:`float`): Latitude of the location in degrees. longitude (:obj:`float`): Longitude of the location in degrees. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. - live_period (:obj:`int`): Optional. Period in seconds for which the location can be - updated. + measured in meters; 0- + :tg-const:`telegram.InputLocationMessageContent.HORIZONTAL_ACCURACY`. + live_period (:obj:`int`): Optional. Period in seconds for which the location can be + updated, should be between + :tg-const:`telegram.InputLocationMessageContent.MIN_LIVE_PERIOD` and + :tg-const:`telegram.InputLocationMessageContent.MAX_LIVE_PERIOD`. heading (:obj:`int`): Optional. For live locations, a direction in which the user is - moving, in degrees. - proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance for - proximity alerts about approaching another chat member, in meters. + moving, in degrees. Must be between + :tg-const:`telegram.InputLocationMessageContent.MIN_HEADING` and + :tg-const:`telegram.InputLocationMessageContent.MAX_HEADING` if specified. + proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance + for proximity alerts about approaching another chat member, in meters. Must be + between :tg-const:`telegram.InputLocationMessageContent.MIN_PROXIMITY_ALERT_RADIUS` + and :tg-const:`telegram.InputLocationMessageContent.MAX_PROXIMITY_ALERT_RADIUS` + if specified. """ From 0a7642fe185ce5ab9b77baaf4220fb232ad9660c Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 14:02:21 +0300 Subject: [PATCH 58/68] `InputVenueMessageContent`: unify args and attrs --- telegram/_inline/inputvenuemessagecontent.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/telegram/_inline/inputvenuemessagecontent.py b/telegram/_inline/inputvenuemessagecontent.py index b6adeece5f5..17f59bce904 100644 --- a/telegram/_inline/inputvenuemessagecontent.py +++ b/telegram/_inline/inputvenuemessagecontent.py @@ -54,8 +54,12 @@ class InputVenueMessageContent(InputMessageContent): address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue, if known. foursquare_type (:obj:`str`): Optional. Foursquare type of the venue, if known. + (For example, "arts_entertainment/default", "arts_entertainment/aquarium" or + "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) """ From fb08193ae533e7698af582d01a01d858d53a5c39 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 14:05:01 +0300 Subject: [PATCH 59/68] `InputInvoiceMessageContent`: unify args and attrs --- .../_inline/inputinvoicemessagecontent.py | 23 ++++++++++++++----- 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/telegram/_inline/inputinvoicemessagecontent.py b/telegram/_inline/inputinvoicemessagecontent.py index ce65c717162..5429f55486b 100644 --- a/telegram/_inline/inputinvoicemessagecontent.py +++ b/telegram/_inline/inputinvoicemessagecontent.py @@ -105,14 +105,25 @@ class InputInvoiceMessageContent(InputMessageContent): currency (:obj:`str`): Three-letter ISO 4217 currency code, see more on `currencies `_ prices (List[:class:`telegram.LabeledPrice`]): Price breakdown, a list of - components. - max_tip_amount (:obj:`int`): Optional. The maximum accepted amount for tips in the smallest - units of the currency (integer, not float/double). + components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, + etc.) + max_tip_amount (:obj:`int`): Optional. The maximum accepted amount for tips in the + *smallest* units of the currency (integer, **not** float/double). For example, for a + maximum tip of US$ 1.45 ``max_tip_amount`` is ``145``. See the ``exp`` parameter in + `currencies.json `_, it + shows the number of digits past the decimal point for each currency (2 for the majority + of currencies). Defaults to ``0``. suggested_tip_amounts (List[:obj:`int`]): Optional. An array of suggested - amounts of tip in the smallest units of the currency (integer, not float/double). + amounts of tip in the *smallest* units of the currency (integer, **not** float/double). + At most 4 suggested tip amounts can be specified. The suggested tip amounts must be + positive, passed in a strictly increased order and must not exceed + :attr:`max_tip_amount`. provider_data (:obj:`str`): Optional. An object for data about the invoice, - which will be shared with the payment provider. - photo_url (:obj:`str`): Optional. URL of the product photo for the invoice. + which will be shared with the payment provider. A detailed description of the required + fields should be provided by the payment provider. + photo_url (:obj:`str`): Optional. URL of the product photo for the invoice. Can be a photo + of the goods or a marketing image for a service. People like it better when they see + what they are paying for. photo_size (:obj:`int`): Optional. Photo size. photo_width (:obj:`int`): Optional. Photo width. photo_height (:obj:`int`): Optional. Photo height. From d08fb9ae8b6de63d698c743c9ed28f1c516e630b Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 19:13:29 +0300 Subject: [PATCH 60/68] `Invoice`: unify args and attrs I think the 2nd part of docstring for `start_parameter` can be useful to understand this attr, despite the phrase addressing the generation of the Invoice --- telegram/_payment/invoice.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/telegram/_payment/invoice.py b/telegram/_payment/invoice.py index bdc325d1e66..9bae65b4bec 100644 --- a/telegram/_payment/invoice.py +++ b/telegram/_payment/invoice.py @@ -48,9 +48,15 @@ class Invoice(TelegramObject): Attributes: title (:obj:`str`): Product name. description (:obj:`str`): Product description. - start_parameter (:obj:`str`): Unique bot deep-linking parameter. + start_parameter (:obj:`str`): Unique bot deep-linking parameter that can be used to + generate this invoice. currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. See the + ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). """ From 0775af588ba82cce6f05c1e18a1d2668e49cd206 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 19:15:07 +0300 Subject: [PATCH 61/68] `LabeledPrice`: unify args and attrs --- telegram/_payment/labeledprice.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/telegram/_payment/labeledprice.py b/telegram/_payment/labeledprice.py index 91811ca103c..80c34db5f4c 100644 --- a/telegram/_payment/labeledprice.py +++ b/telegram/_payment/labeledprice.py @@ -42,7 +42,12 @@ class LabeledPrice(TelegramObject): Attributes: label (:obj:`str`): Portion label. - amount (:obj:`int`): Price of the product in the smallest units of the currency. + amount (:obj:`int`): Price of the product in the smallest units of the currency (integer, + not float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). """ From c5d3756cbcec53f5434a82e286393d5664afae18 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 19:16:52 +0300 Subject: [PATCH 62/68] `PreCheckoutQuery`: unify args and attrs --- telegram/_payment/precheckoutquery.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/telegram/_payment/precheckoutquery.py b/telegram/_payment/precheckoutquery.py index af009beeb6e..dec5ed8d32f 100644 --- a/telegram/_payment/precheckoutquery.py +++ b/telegram/_payment/precheckoutquery.py @@ -58,7 +58,12 @@ class PreCheckoutQuery(TelegramObject): id (:obj:`str`): Unique query identifier. from_user (:class:`telegram.User`): User who sent the query. currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). invoice_payload (:obj:`str`): Bot specified invoice payload. shipping_option_id (:obj:`str`): Optional. Identifier of the shipping option chosen by the user. From 0287c354c6dce7db1ce8fc08efd35a5e42dd2f60 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 19:18:47 +0300 Subject: [PATCH 63/68] `SuccessfulPayment`: unify args and attrs --- telegram/_payment/successfulpayment.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/telegram/_payment/successfulpayment.py b/telegram/_payment/successfulpayment.py index cfbd7fd01fd..152484366f3 100644 --- a/telegram/_payment/successfulpayment.py +++ b/telegram/_payment/successfulpayment.py @@ -52,7 +52,12 @@ class SuccessfulPayment(TelegramObject): Attributes: currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). invoice_payload (:obj:`str`): Bot specified invoice payload. shipping_option_id (:obj:`str`): Optional. Identifier of the shipping option chosen by the user. From 423ee44556702652febe6e1d9d695bc2edf5cf52 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 19:27:50 +0300 Subject: [PATCH 64/68] `PassportFile`: unify args and attrs --- telegram/_passport/passportfile.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/telegram/_passport/passportfile.py b/telegram/_passport/passportfile.py index f2434807935..b66b0f1bd04 100644 --- a/telegram/_passport/passportfile.py +++ b/telegram/_passport/passportfile.py @@ -46,7 +46,8 @@ class PassportFile(TelegramObject): file_date (:obj:`int`): Unix time when the file was uploaded. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. From 16bbb30a769f2c3eae070de3b92dc8c1ffc1b028 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 19:31:38 +0300 Subject: [PATCH 65/68] add `Args` sections to `PersonalDetails`, `ResidentialAddress`, `IdDocumentData` --- telegram/_passport/data.py | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/telegram/_passport/data.py b/telegram/_passport/data.py index f256f273dac..d8f0061e39e 100644 --- a/telegram/_passport/data.py +++ b/telegram/_passport/data.py @@ -26,6 +26,22 @@ class PersonalDetails(TelegramObject): """ This object represents personal details. + Args: + first_name (:obj:`str`): First Name. + middle_name (:obj:`str`): Optional. First Name. + last_name (:obj:`str`): Last Name. + birth_date (:obj:`str`): Date of birth in DD.MM.YYYY format. + gender (:obj:`str`): Gender, male or female. + country_code (:obj:`str`): Citizenship (ISO 3166-1 alpha-2 country code). + residence_country_code (:obj:`str`): Country of residence (ISO 3166-1 alpha-2 country + code). + first_name_native (:obj:`str`): First Name in the language of the user's country of + residence. + middle_name_native (:obj:`str`): Optional. Middle Name in the language of the user's + country of residence. + last_name_native (:obj:`str`): Last Name in the language of the user's country of + residence. + Attributes: first_name (:obj:`str`): First Name. middle_name (:obj:`str`): Optional. First Name. @@ -89,6 +105,14 @@ class ResidentialAddress(TelegramObject): """ This object represents a residential address. + Args: + street_line1 (:obj:`str`): First line for the address. + street_line2 (:obj:`str`): Optional. Second line for the address. + city (:obj:`str`): City. + state (:obj:`str`): Optional. State. + country_code (:obj:`str`): ISO 3166-1 alpha-2 country code. + post_code (:obj:`str`): Address post code. + Attributes: street_line1 (:obj:`str`): First line for the address. street_line2 (:obj:`str`): Optional. Second line for the address. @@ -132,6 +156,10 @@ class IdDocumentData(TelegramObject): """ This object represents the data of an identity document. + Args: + document_no (:obj:`str`): Document number. + expiry_date (:obj:`str`): Optional. Date of expiry, in DD.MM.YYYY format. + Attributes: document_no (:obj:`str`): Document number. expiry_date (:obj:`str`): Optional. Date of expiry, in DD.MM.YYYY format. From a881c483b51d5c35bd4386dc3105c8282506b834 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 19:35:42 +0300 Subject: [PATCH 66/68] add `Args` sections to `SecureData`, `SecureValue` --- telegram/_passport/credentials.py | 42 +++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/telegram/_passport/credentials.py b/telegram/_passport/credentials.py index 8f8c2b85986..46d791f0c1f 100644 --- a/telegram/_passport/credentials.py +++ b/telegram/_passport/credentials.py @@ -244,6 +244,28 @@ class SecureData(TelegramObject): This object represents the credentials that were used to decrypt the encrypted data. All fields are optional and depend on fields that were requested. + Args: + personal_details (:class:`telegram.SecureValue`, optional): Credentials for encrypted + personal details. + passport (:class:`telegram.SecureValue`, optional): Credentials for encrypted passport. + internal_passport (:class:`telegram.SecureValue`, optional): Credentials for encrypted + internal passport. + driver_license (:class:`telegram.SecureValue`, optional): Credentials for encrypted + driver license. + identity_card (:class:`telegram.SecureValue`, optional): Credentials for encrypted ID card + address (:class:`telegram.SecureValue`, optional): Credentials for encrypted + residential address. + utility_bill (:class:`telegram.SecureValue`, optional): Credentials for encrypted + utility bill. + bank_statement (:class:`telegram.SecureValue`, optional): Credentials for encrypted + bank statement. + rental_agreement (:class:`telegram.SecureValue`, optional): Credentials for encrypted + rental agreement. + passport_registration (:class:`telegram.SecureValue`, optional): Credentials for encrypted + registration from internal passport. + temporary_registration (:class:`telegram.SecureValue`, optional): Credentials for encrypted + temporary registration. + Attributes: personal_details (:class:`telegram.SecureValue`): Optional. Credentials for encrypted personal details. @@ -344,6 +366,26 @@ class SecureValue(TelegramObject): This object represents the credentials that were used to decrypt the encrypted value. All fields are optional and depend on the type of field. + Args: + data (:class:`telegram.DataCredentials`, optional): Credentials for encrypted Telegram + Passport data. Available for "personal_details", "passport", "driver_license", + "identity_card", "identity_passport" and "address" types. + front_side (:class:`telegram.FileCredentials`, optional): Credentials for encrypted + document's front side. Available for "passport", "driver_license", "identity_card" + and "internal_passport". + reverse_side (:class:`telegram.FileCredentials`, optional): Credentials for encrypted + document's reverse side. Available for "driver_license" and "identity_card". + selfie (:class:`telegram.FileCredentials`, optional): Credentials for encrypted selfie + of the user with a document. Can be available for "passport", "driver_license", + "identity_card" and "internal_passport". + translation (List[:class:`telegram.FileCredentials`], optional): Credentials for an + encrypted translation of the document. Available for "passport", "driver_license", + "identity_card", "internal_passport", "utility_bill", "bank_statement", + "rental_agreement", "passport_registration" and "temporary_registration". + files (List[:class:`telegram.FileCredentials`], optional): Credentials for encrypted + files. Available for "utility_bill", "bank_statement", "rental_agreement", + "passport_registration" and "temporary_registration" types. + Attributes: data (:class:`telegram.DataCredentials`): Optional. Credentials for encrypted Telegram Passport data. Available for "personal_details", "passport", "driver_license", From dee43f08be97c8e23f384e34b55f0b45f571a438 Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 9 Dec 2022 19:36:56 +0300 Subject: [PATCH 67/68] add `message` arg to `PassportElementError` --- telegram/_passport/passportelementerrors.py | 1 + 1 file changed, 1 insertion(+) diff --git a/telegram/_passport/passportelementerrors.py b/telegram/_passport/passportelementerrors.py index d61fc62f545..732d2878d64 100644 --- a/telegram/_passport/passportelementerrors.py +++ b/telegram/_passport/passportelementerrors.py @@ -35,6 +35,7 @@ class PassportElementError(TelegramObject): Args: source (:obj:`str`): Error source. type (:obj:`str`): The section of the user's Telegram Passport which has the error. + message (:obj:`str`): Error message. Attributes: source (:obj:`str`): Error source. From 57eb9061d6abd395f39be0b4a93f506fb23e437f Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Fri, 23 Dec 2022 18:44:23 +0300 Subject: [PATCH 68/68] `ChatInviteLink`: remove explanatory phrase for `invite_link` arg It makes sense in attrs but not in args --- telegram/_chatinvitelink.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/telegram/_chatinvitelink.py b/telegram/_chatinvitelink.py index b36feba57a5..5022f759de4 100644 --- a/telegram/_chatinvitelink.py +++ b/telegram/_chatinvitelink.py @@ -44,8 +44,7 @@ class ChatInviteLink(TelegramObject): * Comparing objects of this class now also takes :attr:`creates_join_request` into account. Args: - invite_link (:obj:`str`): The invite link. If the link was created by another chat - administrator, then the second part of the link will be replaced with ``'…'``. + invite_link (:obj:`str`): The invite link. creator (:class:`telegram.User`): Creator of the link. creates_join_request (:obj:`bool`): :obj:`True`, if users joining the chat via the link need to be approved by chat administrators.