From ae2858783a95e0bcd2839162116b7df36c15efcf Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Wed, 6 Mar 2024 14:45:50 +0100 Subject: [PATCH] Documentation Improvements (#4109, #4116) Co-authored-by: Aditya Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Maurice Banerjee Palmer <31225563+mbanerjeepalmer@users.noreply.github.com> --- README.rst | 4 -- README_RAW.rst | 4 -- docs/requirements-docs.txt | 2 +- docs/source/telegram.constants.rst | 4 +- examples/deeplinking.py | 12 +++- telegram/_bot.py | 53 ++++++++------- telegram/_chat.py | 2 +- telegram/_chatadministratorrights.py | 18 +++--- telegram/_chatmember.py | 18 +++--- .../_passport/encryptedpassportelement.py | 64 +++++++++---------- telegram/_user.py | 2 +- 11 files changed, 94 insertions(+), 89 deletions(-) diff --git a/README.rst b/README.rst index c71b3eb4ea4..8366a1ff6f0 100644 --- a/README.rst +++ b/README.rst @@ -46,10 +46,6 @@ :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard :alt: Code quality: Codacy -.. image:: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues - :target: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge - :alt: Code quality: DeepSource - .. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg :target: https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master :alt: pre-commit.ci status diff --git a/README_RAW.rst b/README_RAW.rst index 0f5810f59ec..fae3d516e38 100644 --- a/README_RAW.rst +++ b/README_RAW.rst @@ -46,10 +46,6 @@ :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard :alt: Code quality: Codacy -.. image:: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues - :target: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge - :alt: Code quality: DeepSource - .. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg :target: https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master :alt: pre-commit.ci status diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 4b4db586ba7..3aa5506bdbf 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,6 +1,6 @@ sphinx==7.2.6 furo==2024.1.29 -git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1 +furo-sphinx-search @ git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1 sphinx-paramlinks==0.6.0 sphinxcontrib-mermaid==0.9.2 sphinx-copybutton==0.5.2 diff --git a/docs/source/telegram.constants.rst b/docs/source/telegram.constants.rst index 78d5af89944..4b5edf51094 100644 --- a/docs/source/telegram.constants.rst +++ b/docs/source/telegram.constants.rst @@ -4,4 +4,6 @@ telegram.constants Module .. automodule:: telegram.constants :members: :show-inheritance: - :inherited-members: Enum, EnumMeta + :no-undoc-members: + :inherited-members: Enum, EnumMeta, str, int + :exclude-members: __format__, __new__, __repr__, __str__ diff --git a/examples/deeplinking.py b/examples/deeplinking.py index bea7098026b..3ac7f9bd0e5 100644 --- a/examples/deeplinking.py +++ b/examples/deeplinking.py @@ -20,7 +20,13 @@ import logging -from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update, helpers +from telegram import ( + InlineKeyboardButton, + InlineKeyboardMarkup, + LinkPreviewOptions, + Update, + helpers, +) from telegram.constants import ParseMode from telegram.ext import Application, CallbackQueryHandler, CommandHandler, ContextTypes, filters @@ -70,7 +76,9 @@ async def deep_linked_level_2(update: Update, context: ContextTypes.DEFAULT_TYPE bot = context.bot url = helpers.create_deep_linked_url(bot.username, USING_ENTITIES) text = f'You can also mask the deep-linked URLs as links: ▶️ CLICK HERE.' - await update.message.reply_text(text, parse_mode=ParseMode.HTML, disable_web_page_preview=True) + await update.message.reply_text( + text, parse_mode=ParseMode.HTML, link_preview_options=LinkPreviewOptions(is_disabled=True) + ) async def deep_linked_level_3(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: diff --git a/telegram/_bot.py b/telegram/_bot.py index dc6c66aab7c..be9c971af39 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -1110,10 +1110,11 @@ async def delete_messages( Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| - message_ids (Sequence[:obj:`int`]): Identifiers of + message_ids (Sequence[:obj:`int`]): A list of :tg-const:`telegram.constants.BulkRequestLimit.MIN_LIMIT`- - :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` messages to delete. - See :meth:`delete_message` for limitations on which messages can be deleted. + :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` identifiers of messages + to delete. See :meth:`delete_message` for limitations on which messages can be + deleted. Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -1225,11 +1226,11 @@ async def forward_messages( chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| from_chat_id (:obj:`int` | :obj:`str`): Unique identifier for the chat where the original message was sent (or channel username in the format ``@channelusername``). - message_ids (Sequence[:obj:`int`]): Identifiers of + message_ids (Sequence[:obj:`int`]): A list of :tg-const:`telegram.constants.BulkRequestLimit.MIN_LIMIT`- - :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` messages in the chat - :paramref:`from_chat_id` to forward. The identifiers must be specified in a - strictly increasing order. + :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` identifiers of messages + in the chat :paramref:`from_chat_id` to forward. The identifiers must be specified + in a strictly increasing order. disable_notification (:obj:`bool`, optional): |disable_notification| protect_content (:obj:`bool`, optional): |protect_content| message_thread_id (:obj:`int`, optional): |message_thread_id_arg| @@ -4127,10 +4128,11 @@ async def get_updates( "edited_channel_post", "callback_query"] to only receive updates of these types. See :class:`telegram.Update` for a complete list of available update types. Specify an empty sequence to receive all updates except - :attr:`telegram.Update.chat_member` (default). If not specified, the previous - setting will be used. Please note that this parameter doesn't affect updates - created before the call to the get_updates, so unwanted updates may be received for - a short period of time. + :attr:`telegram.Update.chat_member`, :attr:`telegram.Update.message_reaction` and + :attr:`telegram.Update.message_reaction_count` (default). If not specified, the + previous setting will be used. Please note that this parameter doesn't affect + updates created before the call to the get_updates, so unwanted updates may be + received for a short period of time. .. versionchanged:: 20.0 |sequenceargs| @@ -4268,10 +4270,13 @@ async def set_webhook( "edited_channel_post", "callback_query"] to only receive updates of these types. See :class:`telegram.Update` for a complete list of available update types. Specify an empty sequence to receive all updates except - :attr:`telegram.Update.chat_member` (default). If not specified, the previous - setting will be used. Please note that this parameter doesn't affect updates - created before the call to the set_webhook, so unwanted updates may be received for - a short period of time. + :attr:`telegram.Update.chat_member`, + :attr:`telegram.Update.message_reaction` + and :attr:`telegram.Update.message_reaction_count` (default). If not + specified, the previous setting will be used. Please note that this + parameter doesn't affect + updates created before the call to the set_webhook, so unwanted update + may be received for a short period of time. .. versionchanged:: 20.0 |sequenceargs| @@ -5265,9 +5270,9 @@ async def promote_chat_member( can_change_info (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can change chat title, photo and other settings. can_post_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can - post messages in the channel, or access channel statistics; channels only. + post messages in the channel, or access channel statistics; for channels only. can_edit_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can - edit messages of other users and can pin messages, channels only. + edit messages of other users and can pin messages, for channels only. can_delete_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can delete messages of other users. can_invite_users (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can @@ -5275,13 +5280,13 @@ async def promote_chat_member( can_restrict_members (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can restrict, ban or unban chat members, or access supergroup statistics. can_pin_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can - pin messages, supergroups only. + pin messages, for supergroups only. can_promote_members (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can add new administrators with a subset of their own privileges or demote administrators that they have promoted, directly or indirectly (promoted by administrators that were appointed by the user). can_manage_topics (:obj:`bool`, optional): Pass :obj:`True`, if the user is - allowed to create, rename, close, and reopen forum topics; supergroups only. + allowed to create, rename, close, and reopen forum topics; for supergroups only. .. versionadded:: 20.0 can_post_stories (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can @@ -7577,11 +7582,11 @@ async def copy_messages( chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| from_chat_id (:obj:`int` | :obj:`str`): Unique identifier for the chat where the original message was sent (or channel username in the format ``@channelusername``). - message_ids (Sequence[:obj:`int`]): Identifiers of + message_ids (Sequence[:obj:`int`]): A list of :tg-const:`telegram.constants.BulkRequestLimit.MIN_LIMIT` - - :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` messages in the chat. - :paramref:`from_chat_id` to copy. The identifiers must be specified in a strictly - increasing order. + :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` identifiers of messages + in the chat :paramref:`from_chat_id` to copy. The identifiers must be + specified in a strictly increasing order. disable_notification (:obj:`bool`, optional): |disable_notification| protect_content (:obj:`bool`, optional): |protect_content| message_thread_id (:obj:`int`, optional): |message_thread_id_arg| @@ -8731,7 +8736,7 @@ async def set_message_reaction( media group, the reaction is set to the first non-deleted message in the group instead. reaction (Sequence[:class:`telegram.ReactionType` | :obj:`str`] | \ - :class:`telegram.ReactionType` | :obj:`str`, optional): New list of reaction + :class:`telegram.ReactionType` | :obj:`str`, optional): A list of reaction types to set on the message. Currently, as non-premium users, bots can set up to one reaction per message. A custom emoji reaction can be used if it is either already present on the message or explicitly allowed by chat administrators. diff --git a/telegram/_chat.py b/telegram/_chat.py index d308cc0f265..8115c60566e 100644 --- a/telegram/_chat.py +++ b/telegram/_chat.py @@ -2583,7 +2583,7 @@ async def copy_message( .. seealso:: :meth:`send_copy`, :meth:`send_copies`, :meth:`copy_messages`. Returns: - :class:`telegram.Message`: On success, instance representing the message posted. + :class:`telegram.MessageId`: On success, returns the MessageId of the sent message. """ return await self.get_bot().copy_message( diff --git a/telegram/_chatadministratorrights.py b/telegram/_chatadministratorrights.py index 35e1adaac0d..f5bbb7e568a 100644 --- a/telegram/_chatadministratorrights.py +++ b/telegram/_chatadministratorrights.py @@ -60,15 +60,15 @@ class ChatAdministratorRights(TelegramObject): that they have promoted, directly or indirectly (promoted by administrators that were appointed by the user). can_change_info (:obj:`bool`): :obj:`True`, if the user is allowed to change the chat title - ,photo and other settings. + , photo and other settings. can_invite_users (:obj:`bool`): :obj:`True`, if the user is allowed to invite new users to the chat. can_post_messages (:obj:`bool`, optional): :obj:`True`, if the administrator can post - messages in the channel, or access channel statistics; channels only. + messages in the channel, or access channel statistics; for channels only. can_edit_messages (:obj:`bool`, optional): :obj:`True`, if the administrator can edit - messages of other users. + messages of other users and can pin messages; for channels only. can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin - messages; groups and supergroups only. + messages; for groups and supergroups only. can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post stories to the chat. @@ -88,7 +88,7 @@ class ChatAdministratorRights(TelegramObject): .. versionchanged:: NEXT.VERSION |non_optional_story_argument| can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed - to create, rename, close, and reopen forum topics; supergroups only. + to create, rename, close, and reopen forum topics; for supergroups only. .. versionadded:: 20.0 @@ -112,11 +112,11 @@ class ChatAdministratorRights(TelegramObject): can_invite_users (:obj:`bool`): :obj:`True`, if the user is allowed to invite new users to the chat. can_post_messages (:obj:`bool`): Optional. :obj:`True`, if the administrator can post - messages in the channel, or access channel statistics; channels only. + messages in the channel, or access channel statistics; for channels only. can_edit_messages (:obj:`bool`): Optional. :obj:`True`, if the administrator can edit - messages of other users. + messages of other users and can pin messages; for channels only. can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to pin - messages; groups and supergroups only. + messages; for groups and supergroups only. can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post stories to the chat. @@ -136,7 +136,7 @@ class ChatAdministratorRights(TelegramObject): .. versionchanged:: NEXT.VERSION |non_optional_story_argument| can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed - to create, rename, close, and reopen forum topics; supergroups only. + to create, rename, close, and reopen forum topics; for supergroups only. .. versionadded:: 20.0 """ diff --git a/telegram/_chatmember.py b/telegram/_chatmember.py index 6d2d35ce3f4..c251e23c620 100644 --- a/telegram/_chatmember.py +++ b/telegram/_chatmember.py @@ -217,13 +217,13 @@ class ChatMemberAdministrator(ChatMember): can_invite_users (:obj:`bool`): :obj:`True`, if the user can invite new users to the chat. can_post_messages (:obj:`bool`, optional): :obj:`True`, if the - administrator can post messages in the channel, or access channel statistics; channels - only. + administrator can post messages in the channel, or access channel statistics; + for channels only. can_edit_messages (:obj:`bool`, optional): :obj:`True`, if the administrator can edit messages of other users and can pin - messages; channels only. + messages; for channels only. can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed - to pin messages; groups and supergroups only. + to pin messages; for groups and supergroups only. can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post stories to the chat. @@ -243,7 +243,7 @@ class ChatMemberAdministrator(ChatMember): .. versionchanged:: NEXT.VERSION |non_optional_story_argument| can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed - to create, rename, close, and reopen forum topics; supergroups only. + to create, rename, close, and reopen forum topics; for supergroups only. .. versionadded:: 20.0 custom_title (:obj:`str`, optional): Custom title for this user. @@ -277,12 +277,12 @@ class ChatMemberAdministrator(ChatMember): new users to the chat. can_post_messages (:obj:`bool`): Optional. :obj:`True`, if the administrator can post messages in the channel or access channel statistics; - channels only. + for channels only. can_edit_messages (:obj:`bool`): Optional. :obj:`True`, if the administrator can edit messages of other users and can pin - messages; channels only. + messages; for channels only. can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed - to pin messages; groups and supergroups only. + to pin messages; for groups and supergroups only. can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post stories to the chat. @@ -302,7 +302,7 @@ class ChatMemberAdministrator(ChatMember): .. versionchanged:: NEXT.VERSION |non_optional_story_argument| can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed - to create, rename, close, and reopen forum topics; supergroups only + to create, rename, close, and reopen forum topics; for supergroups only .. versionadded:: 20.0 custom_title (:obj:`str`): Optional. Custom title for this user. diff --git a/telegram/_passport/encryptedpassportelement.py b/telegram/_passport/encryptedpassportelement.py index 46b7ac15fb2..14d8b63dcf5 100644 --- a/telegram/_passport/encryptedpassportelement.py +++ b/telegram/_passport/encryptedpassportelement.py @@ -53,35 +53,34 @@ class EncryptedPassportElement(TelegramObject): :class:`telegram.PassportElementErrorUnspecified`. data (:class:`telegram.PersonalDetails` | :class:`telegram.IdDocumentData` | \ :class:`telegram.ResidentialAddress` | :obj:`str`, optional): - Decrypted or encrypted data, available for "personal_details", "passport", + Decrypted or encrypted data; available only for "personal_details", "passport", "driver_license", "identity_card", "internal_passport" and "address" types. - phone_number (:obj:`str`, optional): User's verified phone number, available only for + phone_number (:obj:`str`, optional): User's verified phone number; available only for "phone_number" type. - email (:obj:`str`, optional): User's verified email address, available only for "email" + email (:obj:`str`, optional): User's verified email address; available only for "email" type. files (Sequence[:class:`telegram.PassportFile`], optional): Array of encrypted/decrypted - files - with documents provided by the user, available for "utility_bill", "bank_statement", - "rental_agreement", "passport_registration" and "temporary_registration" types. + files with documents provided by the user; available only for "utility_bill", + "bank_statement", "rental_agreement", "passport_registration" and + "temporary_registration" types. .. versionchanged:: 20.0 |sequenceclassargs| front_side (:class:`telegram.PassportFile`, optional): Encrypted/decrypted file with the - front side of the document, provided by the user. Available for "passport", + front side of the document, provided by the user; Available only for "passport", "driver_license", "identity_card" and "internal_passport". reverse_side (:class:`telegram.PassportFile`, optional): Encrypted/decrypted file with the - reverse side of the document, provided by the user. Available for "driver_license" and - "identity_card". + reverse side of the document, provided by the user; Available only for + "driver_license" and "identity_card". selfie (:class:`telegram.PassportFile`, optional): Encrypted/decrypted file with the - selfie of the user holding a document, provided by the user; available for "passport", - "driver_license", "identity_card" and "internal_passport". + selfie of the user holding a document, provided by the user; available if requested for + "passport", "driver_license", "identity_card" and "internal_passport". translation (Sequence[:class:`telegram.PassportFile`], optional): Array of - encrypted/decrypted - files with translated versions of documents provided by the user. Available if - requested for "passport", "driver_license", "identity_card", "internal_passport", - "utility_bill", "bank_statement", "rental_agreement", "passport_registration" and - "temporary_registration" types. + encrypted/decrypted files with translated versions of documents provided by the user; + available if requested requested for "passport", "driver_license", "identity_card", + "internal_passport", "utility_bill", "bank_statement", "rental_agreement", + "passport_registration" and "temporary_registration" types. .. versionchanged:: 20.0 |sequenceclassargs| @@ -95,16 +94,16 @@ class EncryptedPassportElement(TelegramObject): :class:`telegram.PassportElementErrorUnspecified`. data (:class:`telegram.PersonalDetails` | :class:`telegram.IdDocumentData` | \ :class:`telegram.ResidentialAddress` | :obj:`str`): - Optional. Decrypted or encrypted data, available for "personal_details", "passport", - "driver_license", "identity_card", "internal_passport" and "address" types. - phone_number (:obj:`str`): Optional. User's verified phone number, available only for + Optional. Decrypted or encrypted data; available only for "personal_details", + "passport", "driver_license", "identity_card", "internal_passport" and "address" types. + phone_number (:obj:`str`): Optional. User's verified phone number; available only for "phone_number" type. - email (:obj:`str`): Optional. User's verified email address, available only for "email" + email (:obj:`str`): Optional. User's verified email address; available only for "email" type. files (Tuple[:class:`telegram.PassportFile`]): Optional. Array of encrypted/decrypted - files - with documents provided by the user, available for "utility_bill", "bank_statement", - "rental_agreement", "passport_registration" and "temporary_registration" types. + files with documents provided by the user; available only for "utility_bill", + "bank_statement", "rental_agreement", "passport_registration" and + "temporary_registration" types. .. versionchanged:: 20.0 @@ -112,20 +111,19 @@ class EncryptedPassportElement(TelegramObject): * |alwaystuple| front_side (:class:`telegram.PassportFile`): Optional. Encrypted/decrypted file with the - front side of the document, provided by the user. Available for "passport", + front side of the document, provided by the user; available only for "passport", "driver_license", "identity_card" and "internal_passport". reverse_side (:class:`telegram.PassportFile`): Optional. Encrypted/decrypted file with the - reverse side of the document, provided by the user. Available for "driver_license" and - "identity_card". + reverse side of the document, provided by the user; available only for "driver_license" + and "identity_card". selfie (:class:`telegram.PassportFile`): Optional. Encrypted/decrypted file with the - selfie of the user holding a document, provided by the user; available for "passport", - "driver_license", "identity_card" and "internal_passport". + selfie of the user holding a document, provided by the user; available if requested for + "passport", "driver_license", "identity_card" and "internal_passport". translation (Tuple[:class:`telegram.PassportFile`]): Optional. Array of - encrypted/decrypted - files with translated versions of documents provided by the user. Available if - requested for "passport", "driver_license", "identity_card", "internal_passport", - "utility_bill", "bank_statement", "rental_agreement", "passport_registration" and - "temporary_registration" types. + encrypted/decrypted files with translated versions of documents provided by the user; + available if requested for "passport", "driver_license", "identity_card", + "internal_passport", "utility_bill", "bank_statement", "rental_agreement", + "passport_registration" and "temporary_registration" types. .. versionchanged:: 20.0 diff --git a/telegram/_user.py b/telegram/_user.py index 914d7024f5c..eb4227e18ce 100644 --- a/telegram/_user.py +++ b/telegram/_user.py @@ -1588,7 +1588,7 @@ async def copy_message( |user_chat_id_note| Returns: - :class:`telegram.Message`: On success, instance representing the message posted. + :class:`telegram.MessageId`: On success, returns the MessageId of the sent message. """ return await self.get_bot().copy_message(