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 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 diff --git a/telegram/_bot.py b/telegram/_bot.py index a6042b1f3b8..95a9b23a022 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -705,8 +705,9 @@ 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.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| @@ -841,8 +842,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| @@ -907,8 +908,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| @@ -1016,8 +1017,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| @@ -1137,8 +1138,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| @@ -1246,8 +1247,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| @@ -1341,8 +1342,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| @@ -1465,9 +1466,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| @@ -1587,9 +1588,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| @@ -1713,8 +1714,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| @@ -1821,9 +1822,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| @@ -1943,8 +1944,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| @@ -2059,8 +2060,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 :paramref:`inline_message_id` @@ -2146,8 +2147,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` @@ -2216,8 +2217,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| @@ -2338,8 +2339,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| @@ -2435,8 +2436,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. @@ -2499,8 +2500,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| @@ -2663,7 +2664,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. @@ -2806,6 +2807,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` | \ @@ -2865,7 +2873,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 @@ -2931,7 +2939,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 @@ -2982,7 +2990,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| @@ -3026,7 +3034,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 @@ -3079,7 +3087,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. @@ -3149,8 +3157,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`, :attr:`telegram.Game.text` Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id` @@ -3224,8 +3232,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 @@ -3295,8 +3303,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 @@ -3356,8 +3364,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 @@ -3419,6 +3427,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 @@ -3534,6 +3545,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 ` @@ -3657,7 +3671,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| @@ -3736,7 +3750,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` .. versionchanged:: 20.0 Returns a tuple instead of a list. @@ -3779,7 +3793,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 @@ -3819,7 +3833,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| @@ -3963,7 +3977,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. @@ -4034,7 +4048,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:: :attr:`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. @@ -4116,8 +4131,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. @@ -4270,7 +4285,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. @@ -4333,7 +4348,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. @@ -4438,7 +4453,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| @@ -4507,7 +4522,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 @@ -4606,7 +4621,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| @@ -4648,7 +4663,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| @@ -4699,9 +4714,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| @@ -4745,7 +4760,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 @@ -4823,7 +4838,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 @@ -4898,7 +4913,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 @@ -4948,8 +4963,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 @@ -4994,8 +5009,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 @@ -5040,7 +5055,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| @@ -5089,7 +5104,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| @@ -5130,7 +5145,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| @@ -5174,7 +5189,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| @@ -5222,7 +5237,8 @@ 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.Message.pin`, + :meth:`telegram.User.pin_message` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5273,7 +5289,8 @@ 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.Message.unpin`, + :meth:`telegram.User.unpin_message` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -5317,8 +5334,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| @@ -5895,8 +5912,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| @@ -6010,7 +6027,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| @@ -6063,8 +6080,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| @@ -6228,6 +6245,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` + .. versionchanged:: 20.0 Returns a tuple instead of a list. @@ -6282,6 +6301,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 @@ -6341,6 +6362,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 @@ -6461,9 +6484,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| diff --git a/telegram/_chat.py b/telegram/_chat.py index 77fa665921e..7cdd9c79386 100644 --- a/telegram/_chat.py +++ b/telegram/_chat.py @@ -2839,7 +2839,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 00d01438346..fabfa06d4db 100644 --- a/telegram/_files/chatphoto.py +++ b/telegram/_files/chatphoto.py @@ -111,7 +111,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 @@ -142,7 +142,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 376d4470596..a1fd67234c0 100644 --- a/telegram/_passport/passportfile.py +++ b/telegram/_passport/passportfile.py @@ -157,7 +157,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`. diff --git a/telegram/ext/_application.py b/telegram/ext/_application.py index 0311787b07b..f14c6af5d16 100644 --- a/telegram/ext/_application.py +++ b/telegram/ext/_application.py @@ -162,7 +162,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) (and encouraged), but editing the mapping ``application.chat_data`` itself is not. .. tip:: - Manually modifying :attr:`chat_data` is almost never needed and unadvisable. + + * Manually modifying :attr:`chat_data` is almost never needed and unadvisable. + * Entries are never deleted automatically from this mapping. If you want to delete + the data associated with a specific chat, e.g. if the bot got removed from that + chat, please use :meth:`drop_chat_data`. user_data (:obj:`types.MappingProxyType`): A dictionary handlers can use to store data for the user. For each integer user id, the corresponding value of this mapping is @@ -175,7 +179,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) (and encouraged), but editing the mapping ``application.user_data`` itself is not. .. tip:: - Manually modifying :attr:`user_data` is almost never needed and unadvisable. + + * Manually modifying :attr:`user_data` is almost never needed and unadvisable. + * Entries are never deleted automatically from this mapping. If you want to delete + the data associated with a specific user, e.g. if that user blocked the bot, + please use :meth:`drop_user_data`. bot_data (:obj:`dict`): A dictionary handlers can use to store data for the bot. persistence (:class:`telegram.ext.BasePersistence`): The persistence class to @@ -504,6 +512,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` diff --git a/telegram/ext/_conversationhandler.py b/telegram/ext/_conversationhandler.py index 277bbf8a254..c972551f356 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. 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 `_