From 9467847d7410d7e91fb18a54be68a437b1fa44e5 Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Thu, 15 Dec 2022 15:20:04 +0100 Subject: [PATCH] Documentation Improvements (#3386) Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> --- docs/requirements-docs.txt | 2 +- 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 + .../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 + telegram/_bot.py | 207 ++++++++++-------- telegram/_chat.py | 2 +- telegram/_files/_basemedium.py | 2 +- telegram/_files/chatphoto.py | 4 +- telegram/_passport/passportfile.py | 2 +- telegram/ext/_application.py | 17 +- telegram/ext/_conversationhandler.py | 1 + telegram/ext/_messagehandler.py | 7 +- 21 files changed, 152 insertions(+), 105 deletions(-) diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 51e35d83d..2f8cd8248 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 41fd5e638..122df9bef 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 6517c3f0f..0ce4efda7 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 5c3acf418..b918d6a92 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 6fd5c7ebf..c17d7bd55 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 97818ac73..023a3a633 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 dc8ba52d0..64f399d86 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 10a697cc4..cda06bc0c 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 48960ddbd..fb4e3b4ff 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 b50b7390d..67f686ecc 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 0b9528ec5..22292c70d 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 b52f6b567..783b90ec0 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 0a7d951e2..19b26d609 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 a6042b1f3..95a9b23a0 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -705,8 +705,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """ 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): * 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """ 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """ 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. """ 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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. """ 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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. """ 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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. 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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. `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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. 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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. 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 77fa66592..7cdd9c793 100644 --- a/telegram/_chat.py +++ b/telegram/_chat.py @@ -2839,7 +2839,7 @@ class Chat(TelegramObject): 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 a574064be..a0ad5998d 100644 --- a/telegram/_files/_basemedium.py +++ b/telegram/_files/_basemedium.py @@ -79,7 +79,7 @@ class _BaseMedium(TelegramObject): 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 00d014383..fabfa06d4 100644 --- a/telegram/_files/chatphoto.py +++ b/telegram/_files/chatphoto.py @@ -111,7 +111,7 @@ class ChatPhoto(TelegramObject): 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 @@ class ChatPhoto(TelegramObject): 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 376d44705..a1fd67234 100644 --- a/telegram/_passport/passportfile.py +++ b/telegram/_passport/passportfile.py @@ -157,7 +157,7 @@ class PassportFile(TelegramObject): 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 0311787b0..f14c6af5d 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 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) 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 277bbf8a2..c972551f3 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 addf72c33..0a0f365d3 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 `_