From ad42308ce2ae6441887ebf90483673df68fb8dcf Mon Sep 17 00:00:00 2001 From: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Date: Tue, 27 Dec 2022 12:54:22 +0300 Subject: [PATCH] Unified args and attrs in classes (#3404) Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com> Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> --- telegram/_botcommand.py | 8 ++- telegram/_callbackquery.py | 14 +++-- telegram/_chatinvitelink.py | 1 + telegram/_chatlocation.py | 7 ++- telegram/_chatmember.py | 5 +- telegram/_chatmemberupdated.py | 2 +- telegram/_choseninlineresult.py | 7 ++- telegram/_dice.py | 8 +++ telegram/_files/animation.py | 3 +- telegram/_files/audio.py | 10 ++-- telegram/_files/chatphoto.py | 4 +- telegram/_files/document.py | 15 +++-- telegram/_files/file.py | 13 +++-- telegram/_files/inputmedia.py | 55 +++++++++++-------- telegram/_files/location.py | 5 +- telegram/_files/photosize.py | 3 +- telegram/_files/sticker.py | 24 ++++---- telegram/_files/venue.py | 7 ++- telegram/_files/video.py | 4 +- telegram/_files/videonote.py | 6 +- telegram/_files/voice.py | 5 +- telegram/_forcereply.py | 14 ++++- telegram/_games/game.py | 1 + telegram/_inline/inlinekeyboardbutton.py | 35 +++++++----- telegram/_inline/inlinequery.py | 9 ++- .../_inline/inlinequeryresultcachedgif.py | 2 +- telegram/_inline/inlinequeryresultgif.py | 3 +- telegram/_inline/inlinequeryresultlocation.py | 20 +++++-- telegram/_inline/inlinequeryresultmpeg4gif.py | 6 +- telegram/_inline/inlinequeryresultvenue.py | 8 ++- telegram/_inline/inlinequeryresultvideo.py | 14 ++--- .../_inline/inputinvoicemessagecontent.py | 23 ++++++-- .../_inline/inputlocationmessagecontent.py | 20 +++++-- telegram/_inline/inputtextmessagecontent.py | 3 +- telegram/_inline/inputvenuemessagecontent.py | 6 +- telegram/_keyboardbutton.py | 19 +++++-- telegram/_keyboardbuttonpolltype.py | 9 ++- telegram/_loginurl.py | 18 +++++- telegram/_menubutton.py | 6 +- telegram/_messageentity.py | 7 ++- telegram/_passport/credentials.py | 42 ++++++++++++++ telegram/_passport/data.py | 28 ++++++++++ telegram/_passport/passportelementerrors.py | 1 + telegram/_passport/passportfile.py | 3 +- telegram/_payment/invoice.py | 10 +++- telegram/_payment/labeledprice.py | 7 ++- telegram/_payment/precheckoutquery.py | 7 ++- telegram/_payment/successfulpayment.py | 7 ++- telegram/_replykeyboardmarkup.py | 29 ++++++++-- telegram/_replykeyboardremove.py | 12 ++-- telegram/_update.py | 28 +++++++--- telegram/_user.py | 6 +- telegram/_userprofilephotos.py | 4 +- 53 files changed, 438 insertions(+), 175 deletions(-) diff --git a/telegram/_botcommand.py b/telegram/_botcommand.py index 362d95fbcf7..8bba7c29f52 100644 --- a/telegram/_botcommand.py +++ b/telegram/_botcommand.py @@ -41,8 +41,12 @@ class BotCommand(TelegramObject): :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters. Attributes: - command (:obj:`str`): Text of the command. - description (:obj:`str`): Description of the command. + command (:obj:`str`): Text of the command; :tg-const:`telegram.BotCommand.MIN_COMMAND`- + :tg-const:`telegram.BotCommand.MAX_COMMAND` characters. Can contain only lowercase + English letters, digits and underscores. + description (:obj:`str`): Description of the command; + :tg-const:`telegram.BotCommand.MIN_DESCRIPTION`- + :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters. """ diff --git a/telegram/_callbackquery.py b/telegram/_callbackquery.py index a6963f46146..9b39692cd65 100644 --- a/telegram/_callbackquery.py +++ b/telegram/_callbackquery.py @@ -78,23 +78,27 @@ class CallbackQuery(TelegramObject): inline_message_id (:obj:`str`, optional): Identifier of the message sent via the bot in inline mode, that originated the query. game_short_name (:obj:`str`, optional): Short name of a Game to be returned, serves as - the unique identifier for the game + the unique identifier for the game. Attributes: id (:obj:`str`): Unique identifier for this query. from_user (:class:`telegram.User`): Sender. chat_instance (:obj:`str`): Global identifier, uniquely corresponding to the chat to which - the message with the callback button was sent. + the message with the callback button was sent. Useful for high scores in games. message (:class:`telegram.Message`): Optional. Message with the callback button that - originated the query. + originated the query. Note that message content and message date will not be available + if the message is too old. data (:obj:`str` | :obj:`object`): Optional. Data associated with the callback button. + Be aware that the message, which originated the query, can contain no callback buttons + with this data. Tip: The value here is the same as the value passed in :paramref:`telegram.InlineKeyboardButton.callback_data`. inline_message_id (:obj:`str`): Optional. Identifier of the message sent via the bot in - inline mode, that originated the query. - game_short_name (:obj:`str`): Optional. Short name of a Game to be returned. + inline mode, that originated the query. + game_short_name (:obj:`str`): Optional. Short name of a Game to be returned, serves as + the unique identifier for the game. """ diff --git a/telegram/_chatinvitelink.py b/telegram/_chatinvitelink.py index a281b37cb67..5022f759de4 100644 --- a/telegram/_chatinvitelink.py +++ b/telegram/_chatinvitelink.py @@ -83,6 +83,7 @@ class ChatInviteLink(TelegramObject): :tg-const:`telegram.constants.ChatInviteLinkLimit.MIN_MEMBER_LIMIT`- :tg-const:`telegram.constants.ChatInviteLinkLimit.MAX_MEMBER_LIMIT`. name (:obj:`str`): Optional. Invite link name. + 0-:tg-const:`telegram.constants.ChatInviteLinkLimit.NAME_LENGTH` characters. .. versionadded:: 13.8 pending_join_request_count (:obj:`int`): Optional. Number of pending join requests diff --git a/telegram/_chatlocation.py b/telegram/_chatlocation.py index 0b885d436bb..209873e4532 100644 --- a/telegram/_chatlocation.py +++ b/telegram/_chatlocation.py @@ -40,10 +40,13 @@ class ChatLocation(TelegramObject): Can't be a live location. address (:obj:`str`): Location address; :tg-const:`telegram.ChatLocation.MIN_ADDRESS`- - :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner + :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner. Attributes: location (:class:`telegram.Location`): The location to which the supergroup is connected. - address (:obj:`str`): Location address, as defined by the chat owner + Can't be a live location. + address (:obj:`str`): Location address; + :tg-const:`telegram.ChatLocation.MIN_ADDRESS`- + :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner. """ diff --git a/telegram/_chatmember.py b/telegram/_chatmember.py index 8e80ecc8cc4..aff4750925a 100644 --- a/telegram/_chatmember.py +++ b/telegram/_chatmember.py @@ -65,7 +65,10 @@ class ChatMember(TelegramObject): Attributes: user (:class:`telegram.User`): Information about the user. - status (:obj:`str`): The member's status in the chat. + status (:obj:`str`): The member's status in the chat. Can be + :attr:`~telegram.ChatMember.ADMINISTRATOR`, :attr:`~telegram.ChatMember.OWNER`, + :attr:`~telegram.ChatMember.BANNED`, :attr:`~telegram.ChatMember.LEFT`, + :attr:`~telegram.ChatMember.MEMBER` or :attr:`~telegram.ChatMember.RESTRICTED`. """ diff --git a/telegram/_chatmemberupdated.py b/telegram/_chatmemberupdated.py index f7f8833f991..b730a3a404e 100644 --- a/telegram/_chatmemberupdated.py +++ b/telegram/_chatmemberupdated.py @@ -65,7 +65,7 @@ class ChatMemberUpdated(TelegramObject): old_chat_member (:class:`telegram.ChatMember`): Previous information about the chat member. new_chat_member (:class:`telegram.ChatMember`): New information about the chat member. invite_link (:class:`telegram.ChatInviteLink`): Optional. Chat invite link, which was used - by the user to join the chat. + by the user to join the chat. For joining by invite link events only. """ diff --git a/telegram/_choseninlineresult.py b/telegram/_choseninlineresult.py index 37ed70eb313..a74a070017b 100644 --- a/telegram/_choseninlineresult.py +++ b/telegram/_choseninlineresult.py @@ -56,8 +56,11 @@ class ChosenInlineResult(TelegramObject): Attributes: result_id (:obj:`str`): The unique identifier for the result that was chosen. from_user (:class:`telegram.User`): The user that chose the result. - location (:class:`telegram.Location`): Optional. Sender location. - inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message. + location (:class:`telegram.Location`): Optional. Sender location, only for bots that + require user location. + inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message. Available + only if there is an inline keyboard attached to the message. Will be also received in + callback queries and can be used to edit the message. query (:obj:`str`): The query that was used to obtain the result. """ diff --git a/telegram/_dice.py b/telegram/_dice.py index 40381f2e837..8a5b268994f 100644 --- a/telegram/_dice.py +++ b/telegram/_dice.py @@ -75,6 +75,14 @@ class Dice(TelegramObject): Attributes: value (:obj:`int`): Value of the dice. + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BOWLING` + for :tg-const:`telegram.Dice.DICE`, :tg-const:`telegram.Dice.DARTS` and + :tg-const:`telegram.Dice.BOWLING` base emoji, + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BASKETBALL` + for :tg-const:`telegram.Dice.BASKETBALL` and :tg-const:`telegram.Dice.FOOTBALL` + base emoji, + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_SLOT_MACHINE` + for :tg-const:`telegram.Dice.SLOT_MACHINE` base emoji. emoji (:obj:`str`): Emoji on which the dice throw animation is based. """ diff --git a/telegram/_files/animation.py b/telegram/_files/animation.py index eb6f795414a..59ad2c526db 100644 --- a/telegram/_files/animation.py +++ b/telegram/_files/animation.py @@ -44,7 +44,8 @@ class Animation(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): File identifier. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. diff --git a/telegram/_files/audio.py b/telegram/_files/audio.py index 1b67748b34d..0d05519f92e 100644 --- a/telegram/_files/audio.py +++ b/telegram/_files/audio.py @@ -46,11 +46,11 @@ class Audio(_BaseThumbedMedium): which the music file belongs. Attributes: - file_id (:obj:`str`): Identifier for this file. - file_unique_id (:obj:`str`): Unique identifier for this file, which - is supposed to be the same over time and for different bots. - Can't be used to download or reuse the file. - duration (:obj:`int`): Duration of the audio in seconds. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. + file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be + the same over time and for different bots. Can't be used to download or reuse the file. + duration (:obj:`int`): Duration of the audio in seconds as defined by sender. performer (:obj:`str`): Optional. Performer of the audio as defined by sender or by audio tags. title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags. diff --git a/telegram/_files/chatphoto.py b/telegram/_files/chatphoto.py index fabfa06d4db..f30b3a352eb 100644 --- a/telegram/_files/chatphoto.py +++ b/telegram/_files/chatphoto.py @@ -36,7 +36,7 @@ class ChatPhoto(TelegramObject): equal. Args: - small_file_id (:obj:`str`): Unique file identifier of small + small_file_id (:obj:`str`): File identifier of small (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed. @@ -44,7 +44,7 @@ class ChatPhoto(TelegramObject): (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`) chat photo, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - big_file_id (:obj:`str`): Unique file identifier of big + big_file_id (:obj:`str`): File identifier of big (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed. diff --git a/telegram/_files/document.py b/telegram/_files/document.py index 621154914f2..023ab7be9f2 100644 --- a/telegram/_files/document.py +++ b/telegram/_files/document.py @@ -41,16 +41,15 @@ class Document(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): File identifier. - file_unique_id (:obj:`str`): Unique identifier for this file, which - is supposed to be the same over time and for different bots. - Can't be used to download or reuse the file. - thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail. - file_name (:obj:`str`): Original filename. - mime_type (:obj:`str`): Optional. MIME type of the file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. + file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be + the same over time and for different bots. Can't be used to download or reuse the file. + thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail as defined by sender. + file_name (:obj:`str`): Optional. Original filename as defined by sender. + mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender. file_size (:obj:`int`): Optional. File size in bytes. - """ __slots__ = ("file_name", "mime_type") diff --git a/telegram/_files/file.py b/telegram/_files/file.py index 251b1f73975..796f8c73d98 100644 --- a/telegram/_files/file.py +++ b/telegram/_files/file.py @@ -42,7 +42,7 @@ class File(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`file_unique_id` is equal. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 ``download`` was split into :meth:`download_to_drive` and :meth:`download_to_memory`. Note: @@ -58,18 +58,19 @@ class File(TelegramObject): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`int`, optional): Optional. File size in bytes, if known. + file_size (:obj:`int`, optional): File size in bytes, if known. file_path (:obj:`str`, optional): File path. Use e.g. :meth:`download_to_drive` to get the file. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`str`): Optional. File size in bytes. - file_path (:obj:`str`): Optional. File path. Use e.g. :meth:`download_to_drive` to get - the file. + file_size (:obj:`int`): Optional. File size in bytes, if known. + file_path (:obj:`str`): Optional. File path. Use e.g. :meth:`download_to_drive` to get the + file. """ __slots__ = ( diff --git a/telegram/_files/inputmedia.py b/telegram/_files/inputmedia.py index ed7bbaf6305..e49d9b6e906 100644 --- a/telegram/_files/inputmedia.py +++ b/telegram/_files/inputmedia.py @@ -40,7 +40,7 @@ class InputMedia(TelegramObject): """ Base class for Telegram InputMedia Objects. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 Added arguments and attributes :attr:`type`, :attr:`media`, :attr:`caption`, :attr:`caption_entities`, :paramref:`parse_mode`. @@ -68,8 +68,10 @@ class InputMedia(TelegramObject): Attributes: type (:obj:`str`): Type of the input media. media (:obj:`str` | :class:`telegram.InputFile`): Media to send. - caption (:obj:`str`): Optional. Caption of the media to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the media to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities + parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities| .. versionchanged:: 20.0 @@ -152,7 +154,10 @@ class InputMediaAnimation(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.ANIMATION`. media (:obj:`str` | :class:`telegram.InputFile`): Animation to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| + caption (:obj:`str`): Optional. Caption of the animation to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities| @@ -160,8 +165,6 @@ class InputMediaAnimation(InputMedia): * |tupleclassattrs| * |alwaystuple| - - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. width (:obj:`int`): Optional. Animation width. height (:obj:`int`): Optional. Animation height. duration (:obj:`int`): Optional. Animation duration in seconds. @@ -238,8 +241,10 @@ class InputMediaPhoto(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.PHOTO`. media (:obj:`str` | :class:`telegram.InputFile`): Photo to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the photo to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities| .. versionchanged:: 20.0 @@ -324,8 +329,10 @@ class InputMediaVideo(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.VIDEO`. media (:obj:`str` | :class:`telegram.InputFile`): Video file to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the video to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities| .. versionchanged:: 20.0 @@ -335,9 +342,9 @@ class InputMediaVideo(InputMedia): width (:obj:`int`): Optional. Video width. height (:obj:`int`): Optional. Video height. duration (:obj:`int`): Optional. Video duration in seconds. - supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is + supports_streaming (:obj:`bool`): Optional. :obj:`True`, if the uploaded video is suitable for streaming. - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| """ @@ -416,7 +423,7 @@ class InputMediaAudio(InputMedia): .. versionchanged:: 20.0 |sequenceclassargs| - duration (:obj:`int`): Duration of the audio in seconds as defined by sender. + duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender. performer (:obj:`str`, optional): Performer of the audio as defined by sender or by audio tags. title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags. @@ -429,19 +436,21 @@ class InputMediaAudio(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.AUDIO`. media (:obj:`str` | :class:`telegram.InputFile`): Audio file to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the audio to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities| .. versionchanged:: 20.0 * |tupleclassattrs| * |alwaystuple| - duration (:obj:`int`): Duration of the audio in seconds. + duration (:obj:`int`): Optional. Duration of the audio in seconds. performer (:obj:`str`): Optional. Performer of the audio as defined by sender or by audio tags. title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags. - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| """ @@ -524,18 +533,20 @@ class InputMediaDocument(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.DOCUMENT`. media (:obj:`str` | :class:`telegram.InputFile`): File to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the document to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities| .. versionchanged:: 20.0 * |tupleclassattrs| * |alwaystuple| - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| disable_content_type_detection (:obj:`bool`): Optional. Disables automatic server-side - content type detection for files uploaded using multipart/form-data. Always true, if - the document is sent as part of an album. + content type detection for files uploaded using multipart/form-data. Always + :obj:`True`, if the document is sent as part of an album. """ diff --git a/telegram/_files/location.py b/telegram/_files/location.py index 59edda4e497..0a95058769d 100644 --- a/telegram/_files/location.py +++ b/telegram/_files/location.py @@ -48,10 +48,11 @@ class Location(TelegramObject): longitude (:obj:`float`): Longitude as defined by sender. latitude (:obj:`float`): Latitude as defined by sender. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. + measured in meters; 0-:tg-const:`telegram.Location.HORIZONTAL_ACCURACY`. live_period (:obj:`int`): Optional. Time relative to the message sending date, during which the location can be updated, in seconds. For active live locations only. - heading (:obj:`int`): Optional. The direction in which user is moving, in degrees. + heading (:obj:`int`): Optional. The direction in which user is moving, in degrees; + :tg-const:`telegram.Location.MIN_HEADING`-:tg-const:`telegram.Location.MAX_HEADING`. For active live locations only. proximity_alert_radius (:obj:`int`): Optional. Maximum distance for proximity alerts about approaching another chat member, in meters. For sent live locations only. diff --git a/telegram/_files/photosize.py b/telegram/_files/photosize.py index 0628529578e..dba1fd6ff09 100644 --- a/telegram/_files/photosize.py +++ b/telegram/_files/photosize.py @@ -39,7 +39,8 @@ class PhotoSize(_BaseMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. diff --git a/telegram/_files/sticker.py b/telegram/_files/sticker.py index f024652944b..df9b6a597da 100644 --- a/telegram/_files/sticker.py +++ b/telegram/_files/sticker.py @@ -62,10 +62,9 @@ class Sticker(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`, optional): Sticker thumbnail in the ``.WEBP`` or ``.JPG`` format. emoji (:obj:`str`, optional): Emoji associated with the sticker - set_name (:obj:`str`, optional): Name of the sticker set to which the sticker - belongs. - mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the - position where the mask should be placed. + set_name (:obj:`str`, optional): Name of the sticker set to which the sticker belongs. + mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the position + where the mask should be placed. file_size (:obj:`int`, optional): File size in bytes. premium_animation (:class:`telegram.File`, optional): For premium regular stickers, @@ -78,7 +77,8 @@ class Sticker(_BaseThumbedMedium): .. versionadded:: 20.0 Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. @@ -197,7 +197,7 @@ class StickerSet(TelegramObject): arguments had to be changed. Use keyword arguments to make sure that the arguments are passed correctly. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 The parameter ``contains_masks`` has been removed. Use :paramref:`sticker_type` instead. Args: @@ -232,11 +232,13 @@ class StickerSet(TelegramObject): .. versionchanged:: 20.0 |tupleclassattrs| - sticker_type (:obj:`str`): Type of stickers in the set. + sticker_type (:obj:`str`): Type of stickers in the set, currently one of + :attr:`telegram.Sticker.REGULAR`, :attr:`telegram.Sticker.MASK`, + :attr:`telegram.Sticker.CUSTOM_EMOJI`. .. versionadded:: 20.0 thumb (:class:`telegram.PhotoSize`): Optional. Sticker set thumbnail in the ``.WEBP``, - ``.TGS`` or ``.WEBM`` format. + ``.TGS``, or ``.WEBM`` format. """ @@ -316,9 +318,11 @@ class MaskPosition(TelegramObject): point (:obj:`str`): The part of the face relative to which the mask should be placed. One of :attr:`FOREHEAD`, :attr:`EYES`, :attr:`MOUTH`, or :attr:`CHIN`. x_shift (:obj:`float`): Shift by X-axis measured in widths of the mask scaled to the face - size, from left to right. + size, from left to right. For example, choosing ``-1.0`` will place mask just to the + left of the default mask position. y_shift (:obj:`float`): Shift by Y-axis measured in heights of the mask scaled to the face - size, from top to bottom. + size, from top to bottom. For example, ``1.0`` will place the mask just below the + default mask position. scale (:obj:`float`): Mask scaling coefficient. For example, ``2.0`` means double size. """ diff --git a/telegram/_files/venue.py b/telegram/_files/venue.py index 8106c275e5e..ef6f54d0fe3 100644 --- a/telegram/_files/venue.py +++ b/telegram/_files/venue.py @@ -55,9 +55,12 @@ class Venue(TelegramObject): title (:obj:`str`): Name of the venue. address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue. - foursquare_type (:obj:`str`): Optional. Foursquare type of the venue. + foursquare_type (:obj:`str`): Optional. Foursquare type of the venue. (For example, + "arts_entertainment/default", "arts_entertainment/aquarium" or "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) """ diff --git a/telegram/_files/video.py b/telegram/_files/video.py index b305bf32530..2944c7e65ed 100644 --- a/telegram/_files/video.py +++ b/telegram/_files/video.py @@ -44,7 +44,8 @@ class Video(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. @@ -56,7 +57,6 @@ class Video(_BaseThumbedMedium): mime_type (:obj:`str`): Optional. MIME type of a file as defined by sender. file_size (:obj:`int`): Optional. File size in bytes. - """ __slots__ = ("duration", "file_name", "height", "mime_type", "width") diff --git a/telegram/_files/videonote.py b/telegram/_files/videonote.py index 31ec471f2c4..8b48440f306 100644 --- a/telegram/_files/videonote.py +++ b/telegram/_files/videonote.py @@ -42,11 +42,13 @@ class VideoNote(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - length (:obj:`int`): Video width and height as defined by sender. + length (:obj:`int`): Video width and height (diameter of the video message) as defined + by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender. thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail. file_size (:obj:`int`): Optional. File size in bytes. diff --git a/telegram/_files/voice.py b/telegram/_files/voice.py index 47d6f7b6799..e922644e670 100644 --- a/telegram/_files/voice.py +++ b/telegram/_files/voice.py @@ -34,12 +34,13 @@ class Voice(_BaseMedium): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender. + duration (:obj:`int`): Duration of the audio in seconds as defined by sender. mime_type (:obj:`str`, optional): MIME type of the file as defined by sender. file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. diff --git a/telegram/_forcereply.py b/telegram/_forcereply.py index 1123bb60017..a17c14507d7 100644 --- a/telegram/_forcereply.py +++ b/telegram/_forcereply.py @@ -59,9 +59,17 @@ class ForceReply(TelegramObject): Attributes: force_reply (:obj:`True`): Shows reply interface to the user, as if they manually selected the bots message and tapped 'Reply'. - selective (:obj:`bool`): Optional. Force reply from specific users only. - input_field_placeholder (:obj:`str`): Optional. The placeholder shown in the input - field when the reply is active. + selective (:obj:`bool`): Optional. Force reply from specific users only. Targets: + + 1) Users that are @mentioned in the :attr:`~telegram.Message.text` of the + :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of the + original message. + input_field_placeholder (:obj:`str`): Optional. The placeholder to be shown in the input + field when the reply is active; + :tg-const:`telegram.ForceReply.MIN_INPUT_FIELD_PLACEHOLDER`- + :tg-const:`telegram.ForceReply.MAX_INPUT_FIELD_PLACEHOLDER` + characters. .. versionadded:: 13.7 diff --git a/telegram/_games/game.py b/telegram/_games/game.py index 3691d3b1208..da39296a7b8 100644 --- a/telegram/_games/game.py +++ b/telegram/_games/game.py @@ -75,6 +75,7 @@ class Game(TelegramObject): game message. Can be automatically edited to include current high scores for the game when the bot calls :meth:`telegram.Bot.set_game_score`, or manually edited using :meth:`telegram.Bot.edit_message_text`. + 0-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters. text_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. Special entities that appear in text, such as usernames, URLs, bot commands, etc. This list is empty if the message does not contain text entities. diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index d18b99a218c..e234058369e 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -109,7 +109,7 @@ class InlineKeyboardButton(TelegramObject): specified inline query in the input field. Can be empty, in which case just the bot's username will be inserted. This offers an easy way for users to start using your bot in inline mode when they are currently in a private chat with it. Especially useful - when combined with switch_pm* actions - in this case the user will be automatically + when combined with ``switch_pm*`` actions - in this case the user will be automatically returned to the chat they switched from, skipping the chat selection screen. switch_inline_query_current_chat (:obj:`str`, optional): If set, pressing the button will insert the bot's username and the specified inline query in the current chat's input @@ -117,11 +117,11 @@ class InlineKeyboardButton(TelegramObject): offers a quick way for the user to open your bot in inline mode in the same chat - good for selecting something from multiple options. callback_game (:class:`telegram.CallbackGame`, optional): Description of the game that will - be launched when the user presses the button. This type of button must always be - the ``first`` button in the first row. + be launched when the user presses the button. This type of button **must** always be + the **first** button in the first row. pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button. This type of button - must always be the `first` button in the first row and can only be used in invoice - messages. + **must** always be the **first** button in the first row and can only be used in + invoice messages. Attributes: text (:obj:`str`): Label text on the button. @@ -147,15 +147,24 @@ class InlineKeyboardButton(TelegramObject): private chats between a user and the bot. .. versionadded:: 20.0 - switch_inline_query (:obj:`str`): Optional. Will prompt the user to select one of their - chats, open that chat and insert the bot's username and the specified inline query in - the input field. Can be empty, in which case just the bot's username will be inserted. - switch_inline_query_current_chat (:obj:`str`): Optional. Will insert the bot's username and - the specified inline query in the current chat's input field. Can be empty, in which - case just the bot's username will be inserted. + switch_inline_query (:obj:`str`): Optional. If set, pressing the button will prompt the + user to select one of their chats, open that chat and insert the bot's username and the + specified inline query in the input field. Can be empty, in which case just the bot's + username will be inserted. This offers an easy way for users to start using your bot + in inline mode when they are currently in a private chat with it. Especially useful + when combined with ``switch_pm*`` actions - in this case the user will be automatically + returned to the chat they switched from, skipping the chat selection screen. + switch_inline_query_current_chat (:obj:`str`): Optional. If set, pressing the button will + insert the bot's username and the specified inline query in the current chat's input + field. Can be empty, in which case only the bot's username will be inserted. This + offers a quick way for the user to open your bot in inline mode in the same chat - good + for selecting something from multiple options. callback_game (:class:`telegram.CallbackGame`): Optional. Description of the game that will - be launched when the user presses the button. - pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button. + be launched when the user presses the button. This type of button **must** always be + the **first** button in the first row. + pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button. This type of button + **must** always be the **first** button in the first row and can only be used in + invoice messages. """ diff --git a/telegram/_inline/inlinequery.py b/telegram/_inline/inlinequery.py index abd2a40b205..ff478438443 100644 --- a/telegram/_inline/inlinequery.py +++ b/telegram/_inline/inlinequery.py @@ -72,11 +72,16 @@ class InlineQuery(TelegramObject): query (:obj:`str`): Text of the query (up to :tg-const:`telegram.InlineQuery.MAX_QUERY_LENGTH` characters). offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot. - location (:class:`telegram.Location`): Optional. Sender location, only for bots that - request user location. chat_type (:obj:`str`): Optional. Type of the chat, from which the inline query was sent. + Can be either :tg-const:`telegram.Chat.SENDER` for a private chat with the inline query + sender, :tg-const:`telegram.Chat.PRIVATE`, :tg-const:`telegram.Chat.GROUP`, + :tg-const:`telegram.Chat.SUPERGROUP` or :tg-const:`telegram.Chat.CHANNEL`. The chat + type should be always known for requests sent from official clients and most + third-party clients, unless the request was sent from a secret chat. .. versionadded:: 13.5 + location (:class:`telegram.Location`): Optional. Sender location, only for bots that + request user location. """ diff --git a/telegram/_inline/inlinequeryresultcachedgif.py b/telegram/_inline/inlinequeryresultcachedgif.py index ac9427b2986..de24eb2191d 100644 --- a/telegram/_inline/inlinequeryresultcachedgif.py +++ b/telegram/_inline/inlinequeryresultcachedgif.py @@ -45,7 +45,7 @@ class InlineQueryResultCachedGif(InlineQueryResult): :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes. gif_file_id (:obj:`str`): A valid file identifier for the GIF file. - title (:obj:`str`, optional): Title for the result.caption (:obj:`str`, optional): + title (:obj:`str`, optional): Title for the result. caption (:obj:`str`, optional): Caption of the GIF file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. diff --git a/telegram/_inline/inlinequeryresultgif.py b/telegram/_inline/inlinequeryresultgif.py index 31fe7603d6f..2f6aa526eae 100644 --- a/telegram/_inline/inlinequeryresultgif.py +++ b/telegram/_inline/inlinequeryresultgif.py @@ -77,7 +77,8 @@ class InlineQueryResultGif(InlineQueryResult): gif_duration (:obj:`int`): Optional. Duration of the GIF in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. - thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail. + thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of + ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. title (:obj:`str`): Optional. Title for the result. caption (:obj:`str`): Optional. Caption of the GIF file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters diff --git a/telegram/_inline/inlinequeryresultlocation.py b/telegram/_inline/inlinequeryresultlocation.py index 145d5138134..b6293d82fc7 100644 --- a/telegram/_inline/inlinequeryresultlocation.py +++ b/telegram/_inline/inlinequeryresultlocation.py @@ -75,13 +75,21 @@ class InlineQueryResultLocation(InlineQueryResult): longitude (:obj:`float`): Location longitude in degrees. title (:obj:`str`): Location title. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. - live_period (:obj:`int`): Optional. Period in seconds for which the location can be - updated, should be between 60 and 86400. + measured in meters; 0- + :tg-const:`telegram.InlineQueryResultLocation.HORIZONTAL_ACCURACY`. + live_period (:obj:`int`): Optional. Period in seconds for which the location will be + updated, should be between + :tg-const:`telegram.InlineQueryResultLocation.MIN_LIVE_PERIOD` and + :tg-const:`telegram.InlineQueryResultLocation.MAX_LIVE_PERIOD`. heading (:obj:`int`): Optional. For live locations, a direction in which the user is - moving, in degrees. - proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance for - proximity alerts about approaching another chat member, in meters. + moving, in degrees. Must be between + :tg-const:`telegram.InlineQueryResultLocation.MIN_HEADING` and + :tg-const:`telegram.InlineQueryResultLocation.MAX_HEADING` if specified. + proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance + for proximity alerts about approaching another chat member, in meters. Must be + between :tg-const:`telegram.InlineQueryResultLocation.MIN_PROXIMITY_ALERT_RADIUS` + and :tg-const:`telegram.InlineQueryResultLocation.MAX_PROXIMITY_ALERT_RADIUS` + if specified. reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the diff --git a/telegram/_inline/inlinequeryresultmpeg4gif.py b/telegram/_inline/inlinequeryresultmpeg4gif.py index 06d71ec3096..8b977847e01 100644 --- a/telegram/_inline/inlinequeryresultmpeg4gif.py +++ b/telegram/_inline/inlinequeryresultmpeg4gif.py @@ -48,7 +48,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): mpeg4_width (:obj:`int`, optional): Video width. mpeg4_height (:obj:`int`, optional): Video height. mpeg4_duration (:obj:`int`, optional): Video duration in seconds. - thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result. + thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for + the result. thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. title (:obj:`str`, optional): Title for the result. @@ -77,7 +78,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): mpeg4_duration (:obj:`int`): Optional. Video duration in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. - thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail. + thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of + ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. title (:obj:`str`): Optional. Title for the result. caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters diff --git a/telegram/_inline/inlinequeryresultvenue.py b/telegram/_inline/inlinequeryresultvenue.py index 9b6359b456c..b3494fbc33b 100644 --- a/telegram/_inline/inlinequeryresultvenue.py +++ b/telegram/_inline/inlinequeryresultvenue.py @@ -58,7 +58,7 @@ class InlineQueryResultVenue(InlineQueryResult): reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the - message to be sent instead of the location. + message to be sent instead of the venue. thumb_url (:obj:`str`, optional): Url of the thumbnail for the result. thumb_width (:obj:`int`, optional): Thumbnail width. thumb_height (:obj:`int`, optional): Thumbnail height. @@ -74,8 +74,12 @@ class InlineQueryResultVenue(InlineQueryResult): address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue if known. foursquare_type (:obj:`str`): Optional. Foursquare type of the venue, if known. + (For example, "arts_entertainment/default", "arts_entertainment/aquarium" or + "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the diff --git a/telegram/_inline/inlinequeryresultvideo.py b/telegram/_inline/inlinequeryresultvideo.py index 0fb7c6fd4ef..960eb315c19 100644 --- a/telegram/_inline/inlinequeryresultvideo.py +++ b/telegram/_inline/inlinequeryresultvideo.py @@ -52,7 +52,7 @@ class InlineQueryResultVideo(InlineQueryResult): mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4". thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video. title (:obj:`str`): Title for the result. - caption (:obj:`str`, optional): Caption, + caption (:obj:`str`, optional): Caption of the video to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. parse_mode (:obj:`str`, optional): |parse_mode| @@ -69,7 +69,7 @@ class InlineQueryResultVideo(InlineQueryResult): to the message. input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the message to be sent instead of the video. This field is required if - InlineQueryResultVideo is used to send an HTML-page as a result + ``InlineQueryResultVideo`` is used to send an HTML-page as a result (e.g., a YouTube video). Attributes: @@ -82,10 +82,10 @@ class InlineQueryResultVideo(InlineQueryResult): thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video. title (:obj:`str`): Title for the result. caption (:obj:`str`): Optional. Caption of the video to be sent, - 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after - entities parsing. + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities + parsing. parse_mode (:obj:`str`): Optional. |parse_mode| - caption_entities (Sequence[:class:`telegram.MessageEntity`]): Optional. |caption_entities| + caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities| .. versionchanged:: 20.0 @@ -96,11 +96,11 @@ class InlineQueryResultVideo(InlineQueryResult): video_height (:obj:`int`): Optional. Video height. video_duration (:obj:`int`): Optional. Video duration in seconds. description (:obj:`str`): Optional. Short description of the result. - reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached + reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the message to be sent instead of the video. This field is required if - InlineQueryResultVideo is used to send an HTML-page as a result + ``InlineQueryResultVideo`` is used to send an HTML-page as a result (e.g., a YouTube video). """ diff --git a/telegram/_inline/inputinvoicemessagecontent.py b/telegram/_inline/inputinvoicemessagecontent.py index cfdf0db980a..1a79935e31b 100644 --- a/telegram/_inline/inputinvoicemessagecontent.py +++ b/telegram/_inline/inputinvoicemessagecontent.py @@ -115,22 +115,33 @@ class InputInvoiceMessageContent(InputMessageContent): currency (:obj:`str`): Three-letter ISO 4217 currency code, see more on `currencies `_ prices (Tuple[:class:`telegram.LabeledPrice`]): Price breakdown, a list of - components. + components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, + etc.) .. versionchanged:: 20.0 |tupleclassattrs| - max_tip_amount (:obj:`int`): Optional. The maximum accepted amount for tips in the smallest - units of the currency (integer, not float/double). + max_tip_amount (:obj:`int`): Optional. The maximum accepted amount for tips in the + *smallest* units of the currency (integer, **not** float/double). For example, for a + maximum tip of US$ 1.45 ``max_tip_amount`` is ``145``. See the ``exp`` parameter in + `currencies.json `_, it + shows the number of digits past the decimal point for each currency (2 for the majority + of currencies). Defaults to ``0``. suggested_tip_amounts (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`. .. versionchanged:: 20.0 |tupleclassattrs| provider_data (:obj:`str`): Optional. An object for data about the invoice, - which will be shared with the payment provider. - photo_url (:obj:`str`): Optional. URL of the product photo for the invoice. + which will be shared with the payment provider. A detailed description of the required + fields should be provided by the payment provider. + photo_url (:obj:`str`): Optional. URL of the product photo for the invoice. Can be a photo + of the goods or a marketing image for a service. People like it better when they see + what they are paying for. photo_size (:obj:`int`): Optional. Photo size. photo_width (:obj:`int`): Optional. Photo width. photo_height (:obj:`int`): Optional. Photo height. diff --git a/telegram/_inline/inputlocationmessagecontent.py b/telegram/_inline/inputlocationmessagecontent.py index f3806dfae6b..ba1ff7b84b6 100644 --- a/telegram/_inline/inputlocationmessagecontent.py +++ b/telegram/_inline/inputlocationmessagecontent.py @@ -57,13 +57,21 @@ class InputLocationMessageContent(InputMessageContent): latitude (:obj:`float`): Latitude of the location in degrees. longitude (:obj:`float`): Longitude of the location in degrees. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. - live_period (:obj:`int`): Optional. Period in seconds for which the location can be - updated. + measured in meters; 0- + :tg-const:`telegram.InputLocationMessageContent.HORIZONTAL_ACCURACY`. + live_period (:obj:`int`): Optional. Period in seconds for which the location can be + updated, should be between + :tg-const:`telegram.InputLocationMessageContent.MIN_LIVE_PERIOD` and + :tg-const:`telegram.InputLocationMessageContent.MAX_LIVE_PERIOD`. heading (:obj:`int`): Optional. For live locations, a direction in which the user is - moving, in degrees. - proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance for - proximity alerts about approaching another chat member, in meters. + moving, in degrees. Must be between + :tg-const:`telegram.InputLocationMessageContent.MIN_HEADING` and + :tg-const:`telegram.InputLocationMessageContent.MAX_HEADING` if specified. + proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance + for proximity alerts about approaching another chat member, in meters. Must be + between :tg-const:`telegram.InputLocationMessageContent.MIN_PROXIMITY_ALERT_RADIUS` + and :tg-const:`telegram.InputLocationMessageContent.MAX_PROXIMITY_ALERT_RADIUS` + if specified. """ diff --git a/telegram/_inline/inputtextmessagecontent.py b/telegram/_inline/inputtextmessagecontent.py index e2a7825595a..098bcb9b0bb 100644 --- a/telegram/_inline/inputtextmessagecontent.py +++ b/telegram/_inline/inputtextmessagecontent.py @@ -52,7 +52,8 @@ class InputTextMessageContent(InputMessageContent): Attributes: message_text (:obj:`str`): Text of the message to be sent, - 1-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters after entities + :tg-const:`telegram.constants.MessageLimit.MIN_TEXT_LENGTH`- + :tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters after entities parsing. parse_mode (:obj:`str`): Optional. |parse_mode| entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities| diff --git a/telegram/_inline/inputvenuemessagecontent.py b/telegram/_inline/inputvenuemessagecontent.py index b44679bc589..a36eb1e2ccd 100644 --- a/telegram/_inline/inputvenuemessagecontent.py +++ b/telegram/_inline/inputvenuemessagecontent.py @@ -54,8 +54,12 @@ class InputVenueMessageContent(InputMessageContent): address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue, if known. foursquare_type (:obj:`str`): Optional. Foursquare type of the venue, if known. + (For example, "arts_entertainment/default", "arts_entertainment/aquarium" or + "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) """ diff --git a/telegram/_keyboardbutton.py b/telegram/_keyboardbutton.py index 0368496b92f..68f0f86b16f 100644 --- a/telegram/_keyboardbutton.py +++ b/telegram/_keyboardbutton.py @@ -68,12 +68,19 @@ class KeyboardButton(TelegramObject): .. versionadded:: 20.0 Attributes: - text (:obj:`str`): Text of the button. - request_contact (:obj:`bool`): Optional. The user's phone number will be sent. - request_location (:obj:`bool`): Optional. The user's current location will be sent. - request_poll (:class:`KeyboardButtonPollType`): Optional. If the user should create a poll. - web_app (:class:`WebAppInfo`): Optional. If the described Web App will be launched when the - button is pressed. + text (:obj:`str`): Text of the button. If none of the optional fields are used, it will be + sent to the bot as a message when the button is pressed. + request_contact (:obj:`bool`): Optional. If :obj:`True`, the user's phone number will be + sent as a contact when the button is pressed. Available in private chats only. + request_location (:obj:`bool`): Optional. If :obj:`True`, the user's current location will + be sent when the button is pressed. Available in private chats only. + request_poll (:class:`KeyboardButtonPollType`): Optional. If specified, the user will be + asked to create a poll and send it to the bot when the button is pressed. Available in + private chats only. + web_app (:class:`WebAppInfo`): Optional. If specified, the described `Web App + `_ will be launched when the button is pressed. + The Web App will be able to send a :attr:`Message.web_app_data` service message. + Available in private chats only. .. versionadded:: 20.0 """ diff --git a/telegram/_keyboardbuttonpolltype.py b/telegram/_keyboardbuttonpolltype.py index 9a26930d5aa..cb171edbc33 100644 --- a/telegram/_keyboardbuttonpolltype.py +++ b/telegram/_keyboardbuttonpolltype.py @@ -32,11 +32,16 @@ class KeyboardButtonPollType(TelegramObject): Examples: :any:`Poll Bot ` - Attributes: - type (:obj:`str`): Optional. If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be + Args: + type (:obj:`str`, optional): If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be allowed to create only polls in the quiz mode. If :tg-const:`telegram.Poll.REGULAR` is passed, only regular polls will be allowed. Otherwise, the user will be allowed to create a poll of any type. + Attributes: + type (:obj:`str`): Optional. If equals :tg-const:`telegram.Poll.QUIZ`, the user will + be allowed to create only polls in the quiz mode. If equals + :tg-const:`telegram.Poll.REGULAR`, only regular polls will be allowed. + Otherwise, the user will be allowed to create a poll of any type. """ __slots__ = ("type",) diff --git a/telegram/_loginurl.py b/telegram/_loginurl.py index ec2654ee42a..f46bfe27e6c 100644 --- a/telegram/_loginurl.py +++ b/telegram/_loginurl.py @@ -44,7 +44,7 @@ class LoginUrl(TelegramObject): the original URL without information about the user will be opened. The data added is the same as described in `Receiving authorization data - `_ + `_. forward_text (:obj:`str`, optional): New text of the button in forwarded messages. bot_username (:obj:`str`, optional): Username of a bot, which will be used for user authorization. See @@ -59,10 +59,22 @@ class LoginUrl(TelegramObject): for your bot to send messages to the user. Attributes: - url (:obj:`str`): An HTTPS URL to be opened with user authorization data. + url (:obj:`str`): An HTTPS URL to be opened with user authorization data added to the query + string when the button is pressed. If the user refuses to provide authorization data, + the original URL without information about the user will be opened. The data added is + the same as described in + `Receiving authorization data + `_. forward_text (:obj:`str`): Optional. New text of the button in forwarded messages. bot_username (:obj:`str`): Optional. Username of a bot, which will be used for user - authorization. + authorization. See + `Setting up a bot `_ + for more details. If not specified, the current + bot's username will be assumed. The url's domain must be the same as the domain linked + with the bot. See + `Linking your domain to the bot + `_ + for more details. request_write_access (:obj:`bool`): Optional. Pass :obj:`True` to request the permission for your bot to send messages to the user. diff --git a/telegram/_menubutton.py b/telegram/_menubutton.py index ea10434e658..192c6d37a1b 100644 --- a/telegram/_menubutton.py +++ b/telegram/_menubutton.py @@ -133,14 +133,16 @@ class MenuButtonWebApp(MenuButton): text (:obj:`str`): Text of the button. web_app (:class:`telegram.WebAppInfo`): Description of the Web App that will be launched when the user presses the button. The Web App will be able to send an arbitrary - message on behalf of the user using the method :meth:`~telegram.Bot.answerWebAppQuery`. + message on behalf of the user using the method :meth:`~telegram.Bot.answerWebAppQuery` + of :class:`~telegram.Bot`. Attributes: type (:obj:`str`): :tg-const:`telegram.constants.MenuButtonType.WEB_APP`. text (:obj:`str`): Text of the button. web_app (:class:`telegram.WebAppInfo`): Description of the Web App that will be launched when the user presses the button. The Web App will be able to send an arbitrary - message on behalf of the user using the method :meth:`~telegram.Bot.answerWebAppQuery`. + message on behalf of the user using the method :meth:`~telegram.Bot.answerWebAppQuery` + of :class:`~telegram.Bot`. """ __slots__ = ("text", "web_app") diff --git a/telegram/_messageentity.py b/telegram/_messageentity.py index d2d83b25901..f04d69f94f3 100644 --- a/telegram/_messageentity.py +++ b/telegram/_messageentity.py @@ -48,7 +48,7 @@ class MessageEntity(TelegramObject): :attr:`CUSTOM_EMOJI` (for inline custom emoji stickers). .. versionadded:: 20.0 - added inline custom emoji + Added inline custom emoji offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity. length (:obj:`int`): Length of the entity in UTF-16 code units. url (:obj:`str`, optional): For :attr:`TEXT_LINK` only, url that will be opened after @@ -77,8 +77,9 @@ class MessageEntity(TelegramObject): length (:obj:`int`): Length of the entity in UTF-16 code units. url (:obj:`str`): Optional. For :attr:`TEXT_LINK` only, url that will be opened after user taps on the text. - user (:class:`telegram.User`): Optional. The mentioned user. - language (:obj:`str`): Optional. For :attr:`PRE` only, The programming language of + user (:class:`telegram.User`): Optional. For :attr:`TEXT_MENTION` only, the mentioned + user. + language (:obj:`str`): Optional. For :attr:`PRE` only, the programming language of the entity text. custom_emoji_id (:obj:`str`): Optional. For :attr:`CUSTOM_EMOJI` only, unique identifier of the custom emoji. Use :meth:`telegram.Bot.get_custom_emoji_stickers` to get full diff --git a/telegram/_passport/credentials.py b/telegram/_passport/credentials.py index d2d86c24604..9bfeaa23892 100644 --- a/telegram/_passport/credentials.py +++ b/telegram/_passport/credentials.py @@ -249,6 +249,28 @@ class SecureData(TelegramObject): This object represents the credentials that were used to decrypt the encrypted data. All fields are optional and depend on fields that were requested. + Args: + personal_details (:class:`telegram.SecureValue`, optional): Credentials for encrypted + personal details. + passport (:class:`telegram.SecureValue`, optional): Credentials for encrypted passport. + internal_passport (:class:`telegram.SecureValue`, optional): Credentials for encrypted + internal passport. + driver_license (:class:`telegram.SecureValue`, optional): Credentials for encrypted + driver license. + identity_card (:class:`telegram.SecureValue`, optional): Credentials for encrypted ID card + address (:class:`telegram.SecureValue`, optional): Credentials for encrypted + residential address. + utility_bill (:class:`telegram.SecureValue`, optional): Credentials for encrypted + utility bill. + bank_statement (:class:`telegram.SecureValue`, optional): Credentials for encrypted + bank statement. + rental_agreement (:class:`telegram.SecureValue`, optional): Credentials for encrypted + rental agreement. + passport_registration (:class:`telegram.SecureValue`, optional): Credentials for encrypted + registration from internal passport. + temporary_registration (:class:`telegram.SecureValue`, optional): Credentials for encrypted + temporary registration. + Attributes: personal_details (:class:`telegram.SecureValue`): Optional. Credentials for encrypted personal details. @@ -351,6 +373,26 @@ class SecureValue(TelegramObject): This object represents the credentials that were used to decrypt the encrypted value. All fields are optional and depend on the type of field. + Args: + data (:class:`telegram.DataCredentials`, optional): Credentials for encrypted Telegram + Passport data. Available for "personal_details", "passport", "driver_license", + "identity_card", "identity_passport" and "address" types. + front_side (:class:`telegram.FileCredentials`, optional): Credentials for encrypted + document's front side. Available for "passport", "driver_license", "identity_card" + and "internal_passport". + reverse_side (:class:`telegram.FileCredentials`, optional): Credentials for encrypted + document's reverse side. Available for "driver_license" and "identity_card". + selfie (:class:`telegram.FileCredentials`, optional): Credentials for encrypted selfie + of the user with a document. Can be available for "passport", "driver_license", + "identity_card" and "internal_passport". + translation (List[:class:`telegram.FileCredentials`], optional): Credentials for an + encrypted translation of the document. Available for "passport", "driver_license", + "identity_card", "internal_passport", "utility_bill", "bank_statement", + "rental_agreement", "passport_registration" and "temporary_registration". + files (List[:class:`telegram.FileCredentials`], optional): Credentials for encrypted + files. Available for "utility_bill", "bank_statement", "rental_agreement", + "passport_registration" and "temporary_registration" types. + Attributes: data (:class:`telegram.DataCredentials`): Optional. Credentials for encrypted Telegram Passport data. Available for "personal_details", "passport", "driver_license", diff --git a/telegram/_passport/data.py b/telegram/_passport/data.py index ff015214644..282b9420309 100644 --- a/telegram/_passport/data.py +++ b/telegram/_passport/data.py @@ -26,6 +26,22 @@ class PersonalDetails(TelegramObject): """ This object represents personal details. + Args: + first_name (:obj:`str`): First Name. + middle_name (:obj:`str`): Optional. First Name. + last_name (:obj:`str`): Last Name. + birth_date (:obj:`str`): Date of birth in DD.MM.YYYY format. + gender (:obj:`str`): Gender, male or female. + country_code (:obj:`str`): Citizenship (ISO 3166-1 alpha-2 country code). + residence_country_code (:obj:`str`): Country of residence (ISO 3166-1 alpha-2 country + code). + first_name_native (:obj:`str`): First Name in the language of the user's country of + residence. + middle_name_native (:obj:`str`): Optional. Middle Name in the language of the user's + country of residence. + last_name_native (:obj:`str`): Last Name in the language of the user's country of + residence. + Attributes: first_name (:obj:`str`): First Name. middle_name (:obj:`str`): Optional. First Name. @@ -91,6 +107,14 @@ class ResidentialAddress(TelegramObject): """ This object represents a residential address. + Args: + street_line1 (:obj:`str`): First line for the address. + street_line2 (:obj:`str`): Optional. Second line for the address. + city (:obj:`str`): City. + state (:obj:`str`): Optional. State. + country_code (:obj:`str`): ISO 3166-1 alpha-2 country code. + post_code (:obj:`str`): Address post code. + Attributes: street_line1 (:obj:`str`): First line for the address. street_line2 (:obj:`str`): Optional. Second line for the address. @@ -136,6 +160,10 @@ class IdDocumentData(TelegramObject): """ This object represents the data of an identity document. + Args: + document_no (:obj:`str`): Document number. + expiry_date (:obj:`str`): Optional. Date of expiry, in DD.MM.YYYY format. + Attributes: document_no (:obj:`str`): Document number. expiry_date (:obj:`str`): Optional. Date of expiry, in DD.MM.YYYY format. diff --git a/telegram/_passport/passportelementerrors.py b/telegram/_passport/passportelementerrors.py index 58ce566a7c8..6aa5398177f 100644 --- a/telegram/_passport/passportelementerrors.py +++ b/telegram/_passport/passportelementerrors.py @@ -35,6 +35,7 @@ class PassportElementError(TelegramObject): Args: source (:obj:`str`): Error source. type (:obj:`str`): The section of the user's Telegram Passport which has the error. + message (:obj:`str`): Error message. Attributes: source (:obj:`str`): Error source. diff --git a/telegram/_passport/passportfile.py b/telegram/_passport/passportfile.py index a1fd67234c0..4a4f05eb5ab 100644 --- a/telegram/_passport/passportfile.py +++ b/telegram/_passport/passportfile.py @@ -46,7 +46,8 @@ class PassportFile(TelegramObject): file_date (:obj:`int`): Unix time when the file was uploaded. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. diff --git a/telegram/_payment/invoice.py b/telegram/_payment/invoice.py index 22bc17e7abe..de22c5545aa 100644 --- a/telegram/_payment/invoice.py +++ b/telegram/_payment/invoice.py @@ -48,9 +48,15 @@ class Invoice(TelegramObject): Attributes: title (:obj:`str`): Product name. description (:obj:`str`): Product description. - start_parameter (:obj:`str`): Unique bot deep-linking parameter. + start_parameter (:obj:`str`): Unique bot deep-linking parameter that can be used to + generate this invoice. currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. See the + ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). """ diff --git a/telegram/_payment/labeledprice.py b/telegram/_payment/labeledprice.py index ca3e295d08f..ec0daa2046f 100644 --- a/telegram/_payment/labeledprice.py +++ b/telegram/_payment/labeledprice.py @@ -42,7 +42,12 @@ class LabeledPrice(TelegramObject): Attributes: label (:obj:`str`): Portion label. - amount (:obj:`int`): Price of the product in the smallest units of the currency. + amount (:obj:`int`): Price of the product in the smallest units of the currency (integer, + not float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). """ diff --git a/telegram/_payment/precheckoutquery.py b/telegram/_payment/precheckoutquery.py index fbea2ebcda5..5c1f2d431a8 100644 --- a/telegram/_payment/precheckoutquery.py +++ b/telegram/_payment/precheckoutquery.py @@ -58,7 +58,12 @@ class PreCheckoutQuery(TelegramObject): id (:obj:`str`): Unique query identifier. from_user (:class:`telegram.User`): User who sent the query. currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). invoice_payload (:obj:`str`): Bot specified invoice payload. shipping_option_id (:obj:`str`): Optional. Identifier of the shipping option chosen by the user. diff --git a/telegram/_payment/successfulpayment.py b/telegram/_payment/successfulpayment.py index 3cc30af7fd3..7e83bf2e4ed 100644 --- a/telegram/_payment/successfulpayment.py +++ b/telegram/_payment/successfulpayment.py @@ -52,7 +52,12 @@ class SuccessfulPayment(TelegramObject): Attributes: currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). invoice_payload (:obj:`str`): Bot specified invoice payload. shipping_option_id (:obj:`str`): Optional. Identifier of the shipping option chosen by the user. diff --git a/telegram/_replykeyboardmarkup.py b/telegram/_replykeyboardmarkup.py index 2a481c8e6a8..bc38ac6ee99 100644 --- a/telegram/_replykeyboardmarkup.py +++ b/telegram/_replykeyboardmarkup.py @@ -70,14 +70,31 @@ class ReplyKeyboardMarkup(TelegramObject): .. versionadded:: 13.7 Attributes: - keyboard (Tuple[Tuple[:class:`telegram.KeyboardButton` | :obj:`str`]]): Array of button - rows. - resize_keyboard (:obj:`bool`): Optional. Requests clients to resize the keyboard. + keyboard (Tuple[Tuple[:class:`telegram.KeyboardButton`]]): Array of button rows, + each represented by an Array of :class:`telegram.KeyboardButton` objects. + resize_keyboard (:obj:`bool`): Optional. Requests clients to resize the keyboard vertically + for optimal fit (e.g., make the keyboard smaller if there are just two rows of + buttons). Defaults to :obj:`False`, in which case the custom keyboard is always of the + same height as the app's standard keyboard. one_time_keyboard (:obj:`bool`): Optional. Requests clients to hide the keyboard as soon as - it's been used. + it's been used. The keyboard will still be available, but clients will automatically + display the usual letter-keyboard in the chat - the user can press a special button in + the input field to see the custom keyboard again. Defaults to :obj:`False`. selective (:obj:`bool`): Optional. Show the keyboard to specific users only. - input_field_placeholder (:obj:`str`): Optional. The placeholder shown in the input - field when the reply is active. + Targets: + + 1) Users that are @mentioned in the :attr:`~telegram.Message.text` of the + :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of the + original message. + + Defaults to :obj:`False`. + + input_field_placeholder (:obj:`str`): Optional. The placeholder to be shown in the input + field when the keyboard is active; + :tg-const:`telegram.ReplyKeyboardMarkup.MIN_INPUT_FIELD_PLACEHOLDER`- + :tg-const:`telegram.ReplyKeyboardMarkup.MAX_INPUT_FIELD_PLACEHOLDER` + characters. .. versionadded:: 13.7 diff --git a/telegram/_replykeyboardremove.py b/telegram/_replykeyboardremove.py index 7464830f65c..2989704ba1d 100644 --- a/telegram/_replykeyboardremove.py +++ b/telegram/_replykeyboardremove.py @@ -45,13 +45,17 @@ class ReplyKeyboardRemove(TelegramObject): for specific users only. Targets: 1) Users that are @mentioned in the text of the :class:`telegram.Message` object. - 2) If the bot's message is a reply (has `reply_to_message_id`), sender of the original - message. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of + the original message. Attributes: remove_keyboard (:obj:`True`): Requests clients to remove the custom keyboard. - selective (:obj:`bool`): Optional. Use this parameter if you want to remove the keyboard - for specific users only. + selective (:obj:`bool`): Optional. Remove the keyboard for specific users only. + Targets: + + 1) Users that are @mentioned in the text of the :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of + the original message. """ diff --git a/telegram/_update.py b/telegram/_update.py index b1160696737..32daa2d80a8 100644 --- a/telegram/_update.py +++ b/telegram/_update.py @@ -97,23 +97,33 @@ class Update(TelegramObject): .. versionadded:: 13.8 Attributes: - update_id (:obj:`int`): The update's unique identifier. - message (:class:`telegram.Message`): Optional. New incoming message. - edited_message (:class:`telegram.Message`): Optional. New version of a message. - channel_post (:class:`telegram.Message`): Optional. New incoming channel post. - edited_channel_post (:class:`telegram.Message`): Optional. New version of a channel post. + update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a + certain positive number and increase sequentially. This ID becomes especially handy if + you're using Webhooks, since it allows you to ignore repeated updates or to restore the + correct update sequence, should they get out of order. If there are no new updates for + at least a week, then identifier of the next update will be chosen randomly instead of + sequentially. + message (:class:`telegram.Message`): Optional. New incoming message of any kind - text, + photo, sticker, etc. + edited_message (:class:`telegram.Message`): Optional. New version of a message that is + known to the bot and was edited. + channel_post (:class:`telegram.Message`): Optional. New incoming channel post of any kind + - text, photo, sticker, etc. + edited_channel_post (:class:`telegram.Message`): Optional. New version of a channel post + that is known to the bot and was edited. inline_query (:class:`telegram.InlineQuery`): Optional. New incoming inline query. chosen_inline_result (:class:`telegram.ChosenInlineResult`): Optional. The result of an - inline query that was chosen by a user. + inline query that was chosen by a user and sent to their chat partner. callback_query (:class:`telegram.CallbackQuery`): Optional. New incoming callback query. Examples: :any:`Arbitrary Callback Data Bot ` shipping_query (:class:`telegram.ShippingQuery`): Optional. New incoming shipping query. + Only for invoices with flexible price. pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming - pre-checkout query. - poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates - about stopped polls and polls, which are sent by the bot. + pre-checkout query. Contains full information about checkout. + poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates about + stopped polls and polls, which are sent by the bot. poll_answer (:class:`telegram.PollAnswer`): Optional. A user changed their answer in a non-anonymous poll. Bots receive new votes only in polls that were sent by the bot itself. diff --git a/telegram/_user.py b/telegram/_user.py index ba0e2364757..af062ec33b2 100644 --- a/telegram/_user.py +++ b/telegram/_user.py @@ -70,9 +70,9 @@ class User(TelegramObject): Args: id (:obj:`int`): Unique identifier for this user or bot. is_bot (:obj:`bool`): :obj:`True`, if this user is a bot. - first_name (:obj:`str`): User's or bots first name. - last_name (:obj:`str`, optional): User's or bots last name. - username (:obj:`str`, optional): User's or bots username. + first_name (:obj:`str`): User's or bot's first name. + last_name (:obj:`str`, optional): User's or bot's last name. + username (:obj:`str`, optional): User's or bot's username. language_code (:obj:`str`, optional): IETF language tag of the user's language. can_join_groups (:obj:`str`, optional): :obj:`True`, if the bot can be invited to groups. Returned only in :attr:`telegram.Bot.get_me` requests. diff --git a/telegram/_userprofilephotos.py b/telegram/_userprofilephotos.py index f6cf3dd5a06..7e25c9f489f 100644 --- a/telegram/_userprofilephotos.py +++ b/telegram/_userprofilephotos.py @@ -43,8 +43,8 @@ class UserProfilePhotos(TelegramObject): Attributes: total_count (:obj:`int`): Total number of profile pictures. - photos (Tuple[Tuple[:class:`telegram.PhotoSize`]]): Requested profile pictures (in up - to 4 sizes each). + photos (Tuple[Tuple[:class:`telegram.PhotoSize`]]): Requested profile pictures (in up to 4 + sizes each). .. versionchanged:: 20.0 |tupleclassattrs|