From 0a673e8f7e32f1e50dab6565323f93182a2d4d0b Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Fri, 12 Jul 2024 16:33:42 +0200 Subject: [PATCH] Documentation Improvements (#4303) Co-authored-by: poolitzer --- .github/CONTRIBUTING.rst | 2 +- telegram/_bot.py | 29 ++++++++++--------- telegram/_callbackquery.py | 2 +- telegram/_inline/inlinekeyboardbutton.py | 20 ++++++++----- telegram/_inline/inlinekeyboardmarkup.py | 2 +- .../_inline/inputinvoicemessagecontent.py | 15 +++++----- telegram/_keyboardbuttonrequest.py | 14 +++------ telegram/_message.py | 16 ++++++++-- telegram/_payment/invoice.py | 12 ++++---- telegram/_payment/labeledprice.py | 4 +-- telegram/_payment/precheckoutquery.py | 8 ++--- telegram/_payment/successfulpayment.py | 8 ++--- telegram/_reply.py | 18 ++++++++---- telegram/_replykeyboardmarkup.py | 2 +- telegram/ext/_application.py | 15 ++++++---- telegram/ext/_basepersistence.py | 12 ++++++++ telegram/request/_requestparameter.py | 2 +- 17 files changed, 107 insertions(+), 74 deletions(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 635cdb23e..63906fabd 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -194,7 +194,7 @@ Feel free to copy (parts of) the checklist to the PR description to remind you o - Added or updated documentation for the changed class(es) and/or method(s) - Added the new method(s) to ``_extbot.py`` - Added or updated ``bot_methods.rst`` - - Updated the Bot API version number in all places: ``README.rst`` and ``README_RAW.rst`` (including the badge), as well as ``telegram.constants.BOT_API_VERSION_INFO`` + - Updated the Bot API version number in all places: ``README.rst`` (including the badge) and ``telegram.constants.BOT_API_VERSION_INFO`` - Added logic for arbitrary callback data in :class:`telegram.ext.ExtBot` for new methods that either accept a ``reply_markup`` in some form or have a return type that is/contains :class:`~telegram.Message` Documenting diff --git a/telegram/_bot.py b/telegram/_bot.py index 6a1cbfd07..ff1ccbb37 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -3972,7 +3972,7 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]): Use this method to edit text and game messages. Note: - * |editreplymarkup|. + * |editreplymarkup| * |bcid_edit_time| .. seealso:: :attr:`telegram.Game.text` @@ -5037,15 +5037,16 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]): .. versionchanged:: 20.0 |sequenceargs| 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 pass ``max_tip_amount = 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``. Not supported for payment in |tg_stars| + *smallest units* of the currency (integer, **not** float/double). For example, for + a maximum tip of ``US$ 1.45`` pass ``max_tip_amount = 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``. Not supported for payment in |tg_stars|. .. versionadded:: 13.5 suggested_tip_amounts (Sequence[:obj:`int`], optional): An array of - suggested amounts of tips in the *smallest* units of the currency (integer, **not** + suggested amounts of tips in the *smallest units* of the currency (integer, **not** float/double). At most :tg-const:`telegram.Invoice.MAX_TIP_AMOUNTS` suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed :paramref:`max_tip_amount`. @@ -7978,14 +7979,14 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. versionchanged:: 20.0 |sequenceargs| 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 pass ``max_tip_amount = 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``. Not supported for payments in - |tg_stars|. + *smallest units* of the currency (integer, **not** float/double). For example, for + a maximum tip of ``US$ 1.45`` pass ``max_tip_amount = 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``. Not supported for payments in |tg_stars|. suggested_tip_amounts (Sequence[:obj:`int`], optional): An array of - suggested amounts of tips in the *smallest* units of the currency (integer, **not** + suggested amounts of tips in the *smallest units* of the currency (integer, **not** float/double). At most :tg-const:`telegram.Invoice.MAX_TIP_AMOUNTS` suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed :paramref:`max_tip_amount`. diff --git a/telegram/_callbackquery.py b/telegram/_callbackquery.py index 94661a10f..bdfa569db 100644 --- a/telegram/_callbackquery.py +++ b/telegram/_callbackquery.py @@ -93,7 +93,7 @@ class CallbackQuery(TelegramObject): with the callback button that originated the query. .. versionchanged:: 20.8 - Objects maybe be of type :class:`telegram.MaybeInaccessibleMessage` since Bot API + Objects may be of type :class:`telegram.MaybeInaccessibleMessage` since Bot API 7.0. 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 diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index bbd53ec06..6ceca1a31 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -46,7 +46,7 @@ class InlineKeyboardButton(TelegramObject): working as expected. Putting a game short name in it might, but is not guaranteed to work. * If your bot allows for arbitrary callback data, in keyboards returned in a response - from telegram, :attr:`callback_data` maybe be an instance of + from telegram, :attr:`callback_data` may be an instance of :class:`telegram.ext.InvalidCallbackData`. This will be the case, if the data associated with the button was already deleted. @@ -119,9 +119,12 @@ class InlineKeyboardButton(TelegramObject): This is similar to the new parameter :paramref:`switch_inline_query_chosen_chat`, but gives no control over which chats can be selected. switch_inline_query_current_chat (:obj:`str`, optional): If set, pressing the button will - prompt the user to select one of their chats of the specified type, open that chat and - insert the bot's username and the specified inline query in the input field. Not - supported for messages sent on behalf of a Telegram Business account. + insert the bot's username and the specified inline query in the current chat's input + field. May be empty, in which case only the bot's username will be inserted. + + This offers a quick way for the user to open your bot in inline mode in the same chat + - good for selecting something from multiple options. Not supported in channels and for + messages sent on behalf of a Telegram Business account. callback_game (:class:`telegram.CallbackGame`, optional): Description of the game that will be launched when the user presses the button @@ -187,9 +190,12 @@ class InlineKeyboardButton(TelegramObject): This is similar to the new parameter :paramref:`switch_inline_query_chosen_chat`, but gives no control over which chats can be selected. switch_inline_query_current_chat (:obj:`str`): Optional. If set, pressing the button will - prompt the user to select one of their chats of the specified type, open that chat and - insert the bot's username and the specified inline query in the input field. Not - supported for messages sent on behalf of a Telegram Business account. + insert the bot's username and the specified inline query in the current chat's input + field. May be empty, in which case only the bot's username will be inserted. + + This offers a quick way for the user to open your bot in inline mode in the same chat + - good for selecting something from multiple options. Not supported in channels and for + messages sent on behalf of a Telegram Business account. callback_game (:class:`telegram.CallbackGame`): Optional. Description of the game that will be launched when the user presses the button. diff --git a/telegram/_inline/inlinekeyboardmarkup.py b/telegram/_inline/inlinekeyboardmarkup.py index efb181e8a..6857e4d8e 100644 --- a/telegram/_inline/inlinekeyboardmarkup.py +++ b/telegram/_inline/inlinekeyboardmarkup.py @@ -42,7 +42,7 @@ class InlineKeyboardMarkup(TelegramObject): An inline keyboard on a message .. seealso:: - An another kind of keyboard would be the :class:`telegram.ReplyKeyboardMarkup`. + Another kind of keyboard would be the :class:`telegram.ReplyKeyboardMarkup`. Examples: * :any:`Inline Keyboard 1 ` diff --git a/telegram/_inline/inputinvoicemessagecontent.py b/telegram/_inline/inputinvoicemessagecontent.py index be539bcb3..e13642da5 100644 --- a/telegram/_inline/inputinvoicemessagecontent.py +++ b/telegram/_inline/inputinvoicemessagecontent.py @@ -66,14 +66,13 @@ class InputInvoiceMessageContent(InputMessageContent): |sequenceclassargs| 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 pass ``max_tip_amount = 145``. See the ``exp`` parameter in + *smallest units* of the currency (integer, **not** float/double). For example, for a + maximum tip of ``US$ 1.45`` pass ``max_tip_amount = 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``. Defaults to ``0``. Not supported for payments in - |tg_stars|. + of currencies). Defaults to ``0``. Not supported for payments in |tg_stars|. suggested_tip_amounts (Sequence[: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`. @@ -131,13 +130,13 @@ class InputInvoiceMessageContent(InputMessageContent): |tupleclassattrs| 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 + *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``. Not supported for payments in |tg_stars|. suggested_tip_amounts (Tuple[: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`. diff --git a/telegram/_keyboardbuttonrequest.py b/telegram/_keyboardbuttonrequest.py index 07f2c3a99..441695211 100644 --- a/telegram/_keyboardbuttonrequest.py +++ b/telegram/_keyboardbuttonrequest.py @@ -30,15 +30,12 @@ if TYPE_CHECKING: class KeyboardButtonRequestUsers(TelegramObject): """This object defines the criteria used to request a suitable user. The identifier of the - selected user will be shared with the bot when the corresponding button is pressed. + selected user will be shared with the bot when the corresponding button is pressed. `More + about requesting users » `_. Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`request_id` is equal. - .. seealso:: - `Telegram Docs on requesting users \ - `_ - .. versionadded:: 20.8 This class was previously named ``KeyboardButtonRequestUser``. @@ -136,15 +133,12 @@ class KeyboardButtonRequestUsers(TelegramObject): class KeyboardButtonRequestChat(TelegramObject): """This object defines the criteria used to request a suitable chat. The identifier of the - selected user will be shared with the bot when the corresponding button is pressed. + selected user will be shared with the bot when the corresponding button is pressed. `More + about requesting users » `_. Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`request_id` is equal. - .. seealso:: - `Telegram Docs on requesting chats \ - `_ - .. versionadded:: 20.1 Args: diff --git a/telegram/_message.py b/telegram/_message.py index 3cd654abb..edf9fb401 100644 --- a/telegram/_message.py +++ b/telegram/_message.py @@ -336,7 +336,7 @@ class Message(MaybeInaccessibleMessage): effect_id (:obj:`str`, optional): Unique identifier of the message effect added to the message. - ..versionadded:: 21.3 + .. versionadded:: 21.3 caption_entities (Sequence[:class:`telegram.MessageEntity`], optional): For messages with a Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the @@ -358,6 +358,7 @@ class Message(MaybeInaccessibleMessage): about the animation. For backward compatibility, when this field is set, the document field will also be set. game (:class:`telegram.Game`, optional): Message is a game, information about the game. + `More about games >> `_. photo (Sequence[:class:`telegram.PhotoSize`], optional): Message is a photo, available sizes of the photo. This list is empty if the message does not contain a photo. @@ -373,7 +374,8 @@ class Message(MaybeInaccessibleMessage): video. voice (:class:`telegram.Voice`, optional): Message is a voice message, information about the file. - video_note (:class:`telegram.VideoNote`, optional): Message is a video note, information + video_note (:class:`telegram.VideoNote`, optional): Message is a + `video note `_, information about the video message. new_chat_members (Sequence[:class:`telegram.User`], optional): New members that were added to the group or supergroup and information about them (the bot itself may be one of @@ -429,10 +431,13 @@ class Message(MaybeInaccessibleMessage): :class:`telegram.InaccessibleMessage`. invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment, information about the invoice. + `More about payments >> `_. successful_payment (:class:`telegram.SuccessfulPayment`, optional): Message is a service message about a successful payment, information about the payment. + `More about payments >> `_. connected_website (:obj:`str`, optional): The domain name of the website on which the user has logged in. + `More about Telegram Login >> `_. author_signature (:obj:`str`, optional): Signature of the post author for messages in channels, or the custom title of an anonymous group administrator. passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data. @@ -670,6 +675,7 @@ class Message(MaybeInaccessibleMessage): .. seealso:: :wiki:`Working with Files and Media ` game (:class:`telegram.Game`): Optional. Message is a game, information about the game. + `More about games >> `_. photo (Tuple[:class:`telegram.PhotoSize`]): Optional. Message is a photo, available sizes of the photo. This list is empty if the message does not contain a photo. @@ -693,7 +699,8 @@ class Message(MaybeInaccessibleMessage): the file. .. seealso:: :wiki:`Working with Files and Media ` - video_note (:class:`telegram.VideoNote`): Optional. Message is a video note, information + video_note (:class:`telegram.VideoNote`): Optional. Message is a + `video note `_, information about the video message. .. seealso:: :wiki:`Working with Files and Media ` @@ -750,10 +757,13 @@ class Message(MaybeInaccessibleMessage): :class:`telegram.InaccessibleMessage`. invoice (:class:`telegram.Invoice`): Optional. Message is an invoice for a payment, information about the invoice. + `More about payments >> `_. successful_payment (:class:`telegram.SuccessfulPayment`): Optional. Message is a service message about a successful payment, information about the payment. + `More about payments >> `_. connected_website (:obj:`str`): Optional. The domain name of the website on which the user has logged in. + `More about Telegram Login >> `_. author_signature (:obj:`str`): Optional. Signature of the post author for messages in channels, or the custom title of an anonymous group administrator. passport_data (:class:`telegram.PassportData`): Optional. Telegram Passport data. diff --git a/telegram/_payment/invoice.py b/telegram/_payment/invoice.py index 141f0c8fd..804ac0403 100644 --- a/telegram/_payment/invoice.py +++ b/telegram/_payment/invoice.py @@ -39,9 +39,9 @@ class Invoice(TelegramObject): generate this invoice. currency (:obj:`str`): Three-letter ISO 4217 currency code, or ``XTR`` for payments in |tg_stars|. - 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 pass ``amount = 145``. See the - ``exp`` parameter in + 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`` pass ``amount = 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). @@ -53,9 +53,9 @@ class Invoice(TelegramObject): generate this invoice. currency (:obj:`str`): Three-letter ISO 4217 currency code, or ``XTR`` for payments in |tg_stars|. - 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 + 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`` pass ``amount = 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). diff --git a/telegram/_payment/labeledprice.py b/telegram/_payment/labeledprice.py index b668931b9..ec02f1f70 100644 --- a/telegram/_payment/labeledprice.py +++ b/telegram/_payment/labeledprice.py @@ -36,7 +36,7 @@ class LabeledPrice(TelegramObject): Args: label (:obj:`str`): Portion label. 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 pass ``amount = 145``. + **not** float/double). For example, for a price of ``US$ 1.45`` pass ``amount = 145``. See the ``exp`` parameter in `currencies.json `_, it shows the number of digits past the decimal point for each currency @@ -45,7 +45,7 @@ class LabeledPrice(TelegramObject): Attributes: label (:obj:`str`): Portion label. 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``. + **not** float/double). For example, for a price of ``US$ 1.45`` pass ``amount = 145``. See the ``exp`` parameter in `currencies.json `_, it shows the number of digits past the decimal point for each currency diff --git a/telegram/_payment/precheckoutquery.py b/telegram/_payment/precheckoutquery.py index 30ae30be7..60e1d6078 100644 --- a/telegram/_payment/precheckoutquery.py +++ b/telegram/_payment/precheckoutquery.py @@ -44,8 +44,8 @@ class PreCheckoutQuery(TelegramObject): from_user (:class:`telegram.User`): User who sent the query. currency (:obj:`str`): Three-letter ISO 4217 currency code, or ``XTR`` for payments in |tg_stars|. - 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 pass ``amount = 145``. + 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`` pass ``amount = 145``. See the ``exp`` parameter in `currencies.json `_, it shows the number of digits past the decimal point for each currency @@ -60,8 +60,8 @@ class PreCheckoutQuery(TelegramObject): from_user (:class:`telegram.User`): User who sent the query. currency (:obj:`str`): Three-letter ISO 4217 currency code, or ``XTR`` for payments in |tg_stars|. - 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``. + 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`` pass ``amount = 145``. See the ``exp`` parameter in `currencies.json `_, it shows the number of digits past the decimal point for each currency diff --git a/telegram/_payment/successfulpayment.py b/telegram/_payment/successfulpayment.py index 90b1545b2..34bce2914 100644 --- a/telegram/_payment/successfulpayment.py +++ b/telegram/_payment/successfulpayment.py @@ -38,8 +38,8 @@ class SuccessfulPayment(TelegramObject): Args: currency (:obj:`str`): Three-letter ISO 4217 currency code, or ``XTR`` for payments in |tg_stars|. - 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 pass ``amount = 145``. + 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`` pass ``amount = 145``. See the ``exp`` parameter in `currencies.json `_, it shows the number of digits past the decimal point for each currency @@ -54,8 +54,8 @@ class SuccessfulPayment(TelegramObject): Attributes: currency (:obj:`str`): Three-letter ISO 4217 currency code, or ``XTR`` for payments in |tg_stars|. - 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``. + 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`` pass ``amount = 145``. See the ``exp`` parameter in `currencies.json `_, it shows the number of digits past the decimal point for each currency diff --git a/telegram/_reply.py b/telegram/_reply.py index 6c04847de..2aefa1508 100644 --- a/telegram/_reply.py +++ b/telegram/_reply.py @@ -81,8 +81,9 @@ class ExternalReplyInfo(TelegramObject): sticker. story (:class:`telegram.Story`, optional): Message is a forwarded story. video (:class:`telegram.Video`, optional): Message is a video, information about the video. - video_note (:class:`telegram.VideoNote`, optional): Message is a video note, information - about the video message. + video_note (:class:`telegram.VideoNote`, optional): Message is a `video note + `_, information about the video + message. voice (:class:`telegram.Voice`, optional): Message is a voice message, information about the file. has_media_spoiler (:obj:`bool`, optional): :obj:`True`, if the message media is covered by @@ -91,12 +92,14 @@ class ExternalReplyInfo(TelegramObject): about the contact. dice (:class:`telegram.Dice`, optional): Message is a dice with random value. game (:Class:`telegram.Game`. optional): Message is a game, information about the game. + `More about games >> `_. giveaway (:class:`telegram.Giveaway`, optional): Message is a scheduled giveaway, information about the giveaway. giveaway_winners (:class:`telegram.GiveawayWinners`, optional): A giveaway with public winners was completed. invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment, - information about the invoice. + information about the invoice. `More about payments >> + `_. location (:class:`telegram.Location`, optional): Message is a shared location, information about the location. poll (:class:`telegram.Poll`, optional): Message is a native poll, information about the @@ -128,8 +131,9 @@ class ExternalReplyInfo(TelegramObject): sticker. story (:class:`telegram.Story`): Optional. Message is a forwarded story. video (:class:`telegram.Video`): Optional. Message is a video, information about the video. - video_note (:class:`telegram.VideoNote`): Optional. Message is a video note, information - about the video message. + video_note (:class:`telegram.VideoNote`): Optional. Message is a `video note + `_, information about the video + message. voice (:class:`telegram.Voice`): Optional. Message is a voice message, information about the file. has_media_spoiler (:obj:`bool`): Optional. :obj:`True`, if the message media is covered by @@ -138,12 +142,14 @@ class ExternalReplyInfo(TelegramObject): about the contact. dice (:class:`telegram.Dice`): Optional. Message is a dice with random value. game (:Class:`telegram.Game`): Optional. Message is a game, information about the game. + `More about games >> `_. giveaway (:class:`telegram.Giveaway`): Optional. Message is a scheduled giveaway, information about the giveaway. giveaway_winners (:class:`telegram.GiveawayWinners`): Optional. A giveaway with public winners was completed. invoice (:class:`telegram.Invoice`): Optional. Message is an invoice for a payment, - information about the invoice. + information about the invoice. `More about payments >> + `_. location (:class:`telegram.Location`): Optional. Message is a shared location, information about the location. poll (:class:`telegram.Poll`): Optional. Message is a native poll, information about the diff --git a/telegram/_replykeyboardmarkup.py b/telegram/_replykeyboardmarkup.py index cfca12cc3..1b410ebc7 100644 --- a/telegram/_replykeyboardmarkup.py +++ b/telegram/_replykeyboardmarkup.py @@ -41,7 +41,7 @@ class ReplyKeyboardMarkup(TelegramObject): A reply keyboard with reply options. .. seealso:: - An another kind of keyboard would be the :class:`telegram.InlineKeyboardMarkup`. + Another kind of keyboard would be the :class:`telegram.InlineKeyboardMarkup`. Examples: * Example usage: A user requests to change the bot's language, bot replies to the request diff --git a/telegram/ext/_application.py b/telegram/ext/_application.py index 4f623ed36..670793c99 100644 --- a/telegram/ext/_application.py +++ b/telegram/ext/_application.py @@ -786,6 +786,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AsyncContextManager["Applica - :meth:`shutdown` - :meth:`post_shutdown` + A small wrapper is passed to :paramref:`telegram.ext.Updater.start_polling.error_callback` + which forwards errors occurring during polling to + :meth:`registered error handlers `. The update parameter of the callback + will be set to :obj:`None`. + .. include:: inclusions/application_run_tip.rst Args: @@ -1362,11 +1367,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AsyncContextManager["Applica The priority/order of handlers is determined as follows: - * Priority of the group (lower group number == higher priority) - * The first handler in a group which can handle an update (see - :attr:`telegram.ext.BaseHandler.check_update`) will be used. Other handlers from the - group will not be used. The order in which handlers were added to the group defines the - priority. + * Priority of the group (lower group number == higher priority) + * The first handler in a group which can handle an update (see + :attr:`telegram.ext.BaseHandler.check_update`) will be used. Other handlers from the + group will not be used. The order in which handlers were added to the group defines the + priority. Warning: Adding persistent :class:`telegram.ext.ConversationHandler` after the application has diff --git a/telegram/ext/_basepersistence.py b/telegram/ext/_basepersistence.py index 5199a165b..126437a0a 100644 --- a/telegram/ext/_basepersistence.py +++ b/telegram/ext/_basepersistence.py @@ -357,6 +357,10 @@ class BasePersistence(Generic[UD, CD, BD], ABC): :attr:`~telegram.ext.Application.user_data` to a callback. Can be used to update data stored in :attr:`~telegram.ext.Application.user_data` from an external source. + Tip: + This method is expected to edit the object :paramref:`user_data` in-place instead of + returning a new object. + Warning: When using :meth:`~telegram.ext.ApplicationBuilder.concurrent_updates`, this method may be called while a handler callback is still running. This might lead to race @@ -380,6 +384,10 @@ class BasePersistence(Generic[UD, CD, BD], ABC): :attr:`~telegram.ext.Application.chat_data` to a callback. Can be used to update data stored in :attr:`~telegram.ext.Application.chat_data` from an external source. + Tip: + This method is expected to edit the object :paramref:`chat_data` in-place instead of + returning a new object. + Warning: When using :meth:`~telegram.ext.ApplicationBuilder.concurrent_updates`, this method may be called while a handler callback is still running. This might lead to race @@ -403,6 +411,10 @@ class BasePersistence(Generic[UD, CD, BD], ABC): :attr:`~telegram.ext.Application.bot_data` to a callback. Can be used to update data stored in :attr:`~telegram.ext.Application.bot_data` from an external source. + Tip: + This method is expected to edit the object :paramref:`bot_data` in-place instead of + returning a new object. + Warning: When using :meth:`~telegram.ext.ApplicationBuilder.concurrent_updates`, this method may be called while a handler callback is still running. This might lead to race diff --git a/telegram/request/_requestparameter.py b/telegram/request/_requestparameter.py index 2e14a8be6..ab11cbce7 100644 --- a/telegram/request/_requestparameter.py +++ b/telegram/request/_requestparameter.py @@ -90,7 +90,7 @@ class RequestParameter: value: object, ) -> Tuple[object, List[InputFile]]: """Converts `value` into something that we can json-dump. Returns two values: - 1. the JSON-dumpable value. Maybe be `None` in case the value is an InputFile which must + 1. the JSON-dumpable value. May be `None` in case the value is an InputFile which must not be uploaded via an attach:// URI 2. A list of InputFiles that should be uploaded for this value