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>
python-telegram-bot · Dec 27, 2022 · ad42308 · ad42308
1 parent fa0642e
commit ad42308
Show file tree

Hide file tree

Showing 53 changed files with 438 additions and 175 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -36,15 +36,15 @@ 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.
         small_file_unique_id (:obj:`str`): Unique file identifier of small
             (: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
@@ -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
@@ -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
@@ -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,16 +154,17 @@ 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|
 
             .. versionchanged:: 20.0
 
                 * |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.
 
     """