OpenSource/python-telegram-bot
OpenSource/python-telegram-bot
1
0
Fork 0
mirror of https://github.com/python-telegram-bot/python-telegram-bot.git synced 2024-12-22 06:25:12 +01:00
Code Issues Projects Releases Packages Wiki Activity

Documentation Improvements (#4109, #4116)

Browse source 
Co-authored-by: Aditya <adityayadav11082@gmail.com>
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
Co-authored-by: Maurice Banerjee Palmer <31225563+mbanerjeepalmer@users.noreply.github.com>
This commit is contained in:
Bibo-Joshi 2024-03-06 14:45:50 +01:00 committed by GitHub
parent 2c227d5977
commit ae2858783a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 94 additions and 89 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
README.rst
View file

@ -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

4
README_RAW.rst
View file

@ -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

2
docs/requirements-docs.txt
View file

@ -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

4
docs/source/telegram.constants.rst
View file

@ -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__

12
examples/deeplinking.py
View file

@ -20,7 +20,13 @@ bot.
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: <a href="{url}">▶️ CLICK HERE</a>.'
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:

53
telegram/_bot.py
View file

@ -1110,10 +1110,11 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
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 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
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 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
"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 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
"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 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
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 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
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 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
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.

2
telegram/_chat.py
View file

@ -2583,7 +2583,7 @@ class Chat(TelegramObject):
.. 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(

18
telegram/_chatadministratorrights.py
View file

@ -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
"""

18
telegram/_chatmember.py
View file

@ -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.

64
telegram/_passport/encryptedpassportelement.py
View file

@ -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

2
telegram/_user.py
View file

@ -1588,7 +1588,7 @@ class User(TelegramObject):
|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(