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 14:35:00 +01:00
Code Issues Projects Releases Packages Wiki Activity

Documentation Improvements (#3386)

Browse source 
Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com>
Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com>
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
This commit is contained in:
Bibo-Joshi 2022-12-15 15:20:04 +01:00 committed by GitHub
parent b11a0c7778
commit 9467847d74
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
21 changed files with 152 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/requirements-docs.txt
View file

@ -1,6 +1,6 @@
sphinx==5.3.0
sphinx-pypi-upload
furo==2022.9.29
furo==2022.12.7
git+https://github.com/harshil21/furo-sphinx-search@be5cfa221a01f6e259bb2bb1f76d6ede7ffc1f11#egg=furo-sphinx-search
sphinx-paramlinks==0.5.4
sphinxcontrib-mermaid==0.7.1

1
docs/source/telegram.at-tree.rst
View file

@ -2,6 +2,7 @@ Available Types
---------------
.. toctree::
:titlesonly:
telegram.animation
telegram.audio

1
docs/source/telegram.ext.acd-tree.rst
View file

@ -2,6 +2,7 @@ Arbitrary Callback Data
-----------------------
.. toctree::
:titlesonly:
telegram.ext.callbackdatacache
telegram.ext.invalidcallbackdata

1
docs/source/telegram.ext.handlers-tree.rst
View file

@ -2,6 +2,7 @@ Handlers
--------
.. toctree::
:titlesonly:
telegram.ext.basehandler
telegram.ext.callbackqueryhandler

1
docs/source/telegram.ext.persistence-tree.rst
View file

@ -2,6 +2,7 @@ Persistence
-----------
.. toctree::
:titlesonly:
telegram.ext.basepersistence
telegram.ext.dictpersistence

1
docs/source/telegram.ext.rate-limiting-tree.rst
View file

@ -2,6 +2,7 @@ Rate Limiting
-------------
.. toctree::
:titlesonly:
telegram.ext.baseratelimiter
telegram.ext.aioratelimiter

1
docs/source/telegram.games-tree.rst
View file

@ -2,6 +2,7 @@ Games
-----
.. toctree::
:titlesonly:
telegram.callbackgame
telegram.game

1
docs/source/telegram.inline-tree.rst
View file

@ -2,6 +2,7 @@ Inline Mode
-----------
.. toctree::
:titlesonly:
telegram.choseninlineresult
telegram.inlinequery

1
docs/source/telegram.passport-tree.rst
View file

@ -2,6 +2,7 @@ Passport
--------
.. toctree::
:titlesonly:
telegram.credentials
telegram.datacredentials

1
docs/source/telegram.payments-tree.rst
View file

@ -2,6 +2,7 @@ Payments
--------
.. toctree::
:titlesonly:
telegram.invoice
telegram.labeledprice

2
docs/source/telegram.request.rst
View file

@ -4,6 +4,8 @@ telegram.request Module
.. versionadded:: 20.0
.. toctree::
:titlesonly:
telegram.request.baserequest
telegram.request.requestdata
telegram.request.httpxrequest

1
docs/source/telegram.stickers-tree.rst
View file

@ -2,6 +2,7 @@ Stickers
--------
.. toctree::
:titlesonly:
telegram.maskposition
telegram.sticker

1
docs/source/telegram_auxil.rst
View file

@ -2,6 +2,7 @@ Auxiliary modules
=================
.. toctree::
:titlesonly:
telegram.constants
telegram.error

207
telegram/_bot.py
View file

@ -705,8 +705,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> Message:
"""Use this method to send text messages.
.. seealso:: :attr:`telegram.Message.reply_text`, :attr:`telegram.Chat.send_message`,
:attr:`telegram.User.send_message`
.. seealso:: :meth:`telegram.Chat.send_message`, :meth:`telegram.User.send_message`,
:meth:`telegram.Message.reply_text`, :meth:`telegram.Message.reply_html`,
:meth:`telegram.Message.reply_markdown`, :meth:`telegram.Message.reply_markdown_v2`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -841,8 +842,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
As a workaround, it is still possible to use :meth:`copy_message`. However, this
behaviour is undocumented and might be changed by Telegram.
.. seealso:: :attr:`telegram.Message.forward`, :attr:`telegram.Chat.forward_to`,
:attr:`telegram.Chat.forward_from`
.. seealso:: :meth:`telegram.Message.forward`, :meth:`telegram.Chat.forward_to`,
:meth:`telegram.Chat.forward_from`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -907,8 +908,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> Message:
"""Use this method to send photos.
.. seealso:: :attr:`telegram.Message.reply_photo`, :attr:`telegram.Chat.send_photo`,
:attr:`telegram.User.send_photo`
.. seealso:: :meth:`telegram.Message.reply_photo`, :meth:`telegram.Chat.send_photo`,
:meth:`telegram.User.send_photo`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1016,8 +1017,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
For sending voice messages, use the :meth:`send_voice` method instead.
.. seealso:: :attr:`telegram.Message.reply_audio`, :attr:`telegram.Chat.send_audio`,
:attr:`telegram.User.send_audio`
.. seealso:: :meth:`telegram.Message.reply_audio`, :meth:`telegram.Chat.send_audio`,
:meth:`telegram.User.send_audio`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1137,8 +1138,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
:tg-const:`telegram.constants.FileSizeLimit.FILESIZE_UPLOAD` in size, this limit may be
changed in the future.
.. seealso:: :attr:`telegram.Message.reply_document`, :attr:`telegram.Chat.send_document`,
:attr:`telegram.User.send_document`
.. seealso:: :meth:`telegram.Message.reply_document`, :meth:`telegram.Chat.send_document`,
:meth:`telegram.User.send_document`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1246,8 +1247,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
"""
Use this method to send static ``.WEBP``, animated ``.TGS``, or video ``.WEBM`` stickers.
.. seealso:: :attr:`telegram.Message.reply_sticker`, :attr:`telegram.Chat.send_sticker`,
:attr:`telegram.User.send_sticker`
.. seealso:: :meth:`telegram.Message.reply_sticker`, :meth:`telegram.Chat.send_sticker`,
:meth:`telegram.User.send_sticker`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1341,8 +1342,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
easily generate thumbnails. However, this behaviour is undocumented and might be
changed by Telegram.
.. seealso:: :attr:`telegram.Message.reply_video`, :attr:`telegram.Chat.send_video`,
:attr:`telegram.User.send_video`
.. seealso:: :meth:`telegram.Message.reply_video`, :meth:`telegram.Chat.send_video`,
:meth:`telegram.User.send_video`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1465,9 +1466,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
easily generate thumbnails. However, this behaviour is undocumented and might be
changed by Telegram.
.. seealso:: :attr:`telegram.Message.reply_video_note`,
:attr:`telegram.Chat.send_video_note`,
:attr:`telegram.User.send_video_note`
.. seealso:: :meth:`telegram.Message.reply_video_note`,
:meth:`telegram.Chat.send_video_note`,
:meth:`telegram.User.send_video_note`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1587,9 +1588,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
generate thumbnails. However, this behaviour is undocumented and might be changed
by Telegram.
.. seealso:: :attr:`telegram.Message.reply_animation`,
:attr:`telegram.Chat.send_animation`,
:attr:`telegram.User.send_animation`
.. seealso:: :meth:`telegram.Message.reply_animation`,
:meth:`telegram.Chat.send_animation`,
:meth:`telegram.User.send_animation`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1713,8 +1714,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
:tg-const:`telegram.constants.FileSizeLimit.FILESIZE_DOWNLOAD` voice notes will be
sent as files.
.. seealso:: :attr:`telegram.Message.reply_voice`, :attr:`telegram.Chat.send_voice`,
:attr:`telegram.User.send_voice`
.. seealso:: :meth:`telegram.Message.reply_voice`, :meth:`telegram.Chat.send_voice`,
:meth:`telegram.User.send_voice`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1821,9 +1822,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
:paramref:`caption_entities`), then items in :paramref:`media` must have no captions,
and vice versa.
.. seealso:: :attr:`telegram.Message.reply_media_group`,
:attr:`telegram.Chat.send_media_group`,
:attr:`telegram.User.send_media_group`
.. seealso:: :meth:`telegram.Message.reply_media_group`,
:meth:`telegram.Chat.send_media_group`,
:meth:`telegram.User.send_media_group`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -1943,8 +1944,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
You can either supply a :paramref:`latitude` and :paramref:`longitude` or a
:paramref:`location`.
.. seealso:: :attr:`telegram.Message.reply_location`, :attr:`telegram.Chat.send_location`,
:attr:`telegram.User.send_location`
.. seealso:: :meth:`telegram.Message.reply_location`, :meth:`telegram.Chat.send_location`,
:meth:`telegram.User.send_location`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -2059,8 +2060,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
You can either supply a :paramref:`latitude` and :paramref:`longitude` or a
:paramref:`location`.
.. seealso:: :attr:`telegram.Message.edit_live_location`,
:attr:`telegram.CallbackQuery.edit_message_live_location`
.. seealso:: :meth:`telegram.Message.edit_live_location`,
:meth:`telegram.CallbackQuery.edit_message_live_location`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id`
@ -2146,8 +2147,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
"""Use this method to stop updating a live location message sent by the bot or via the bot
(for inline bots) before :paramref:`~telegram.Location.live_period` expires.
.. seealso:: :attr:`telegram.Message.stop_live_location`,
:attr:`telegram.CallbackQuery.stop_message_live_location`
.. seealso:: :meth:`telegram.Message.stop_live_location`,
:meth:`telegram.CallbackQuery.stop_message_live_location`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id`
@ -2216,8 +2217,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
* Foursquare details and Google Place details are mutually exclusive. However, this
behaviour is undocumented and might be changed by Telegram.
.. seealso:: :attr:`telegram.Message.reply_venue`, :attr:`telegram.Chat.send_venue`,
:attr:`telegram.User.send_venue`
.. seealso:: :meth:`telegram.Message.reply_venue`, :meth:`telegram.Chat.send_venue`,
:meth:`telegram.User.send_venue`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -2338,8 +2339,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
:paramref:`first_name` with optionally :paramref:`last_name` and optionally
:paramref:`vcard`.
.. seealso:: :attr:`telegram.Message.reply_contact`, :attr:`telegram.Chat.send_contact`,
:attr:`telegram.User.send_contact`
.. seealso:: :meth:`telegram.Message.reply_contact`, :meth:`telegram.Chat.send_contact`,
:meth:`telegram.User.send_contact`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -2435,8 +2436,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> Message:
"""Use this method to send a game.
.. seealso:: :attr:`telegram.Message.reply_game`, :attr:`telegram.Chat.send_game`,
:attr:`telegram.User.send_game`
.. seealso:: :meth:`telegram.Message.reply_game`, :meth:`telegram.Chat.send_game`,
:meth:`telegram.User.send_game`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat.
@ -2499,8 +2500,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Telegram clients clear its typing status). Telegram only recommends using this method when
a response from the bot will take a noticeable amount of time to arrive.
.. seealso:: :attr:`telegram.Message.reply_chat_action`, :attr:`telegram.Chat.send_action`,
:attr:`telegram.User.send_chat_action`
.. seealso:: :meth:`telegram.Message.reply_chat_action`, :meth:`telegram.Chat.send_action`,
:meth:`telegram.User.send_chat_action`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -2663,7 +2664,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
:paramref:`telegram.InlineQuery.answer.auto_pagination` set to :obj:`True`, which will
take care of passing the correct value.
.. seealso:: :attr:`telegram.InlineQuery.answer`
.. seealso:: :meth:`telegram.InlineQuery.answer`
Args:
inline_query_id (:obj:`str`): Unique identifier for the answered query.
@ -2806,6 +2807,13 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
You should save the file's MIME type and name (if available) when the File object
is received.
.. seealso:: :meth:`telegram.Animation.get_file`, :meth:`telegram.Audio.get_file`,
:meth:`telegram.ChatPhoto.get_big_file`, :meth:`telegram.ChatPhoto.get_small_file`,
:meth:`telegram.Document.get_file`, :meth:`telegram.PassportFile.get_file`,
:meth:`telegram.PhotoSize.get_file`, :meth:`telegram.Sticker.get_file`,
:meth:`telegram.Video.get_file`, :meth:`telegram.VideoNote.get_file`,
:meth:`telegram.Voice.get_file`
Args:
file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` | \
:class:`telegram.ChatPhoto` | :class:`telegram.Document` | \
@ -2865,7 +2873,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
using invite links, etc., unless unbanned first. The bot must be an administrator in the
chat for this to work and must have the appropriate admin rights.
.. seealso:: :attr:`telegram.Chat.ban_member`
.. seealso:: :meth:`telegram.Chat.ban_member`
.. versionadded:: 13.7
@ -2931,7 +2939,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
their channels**. The bot must be an administrator in the supergroup or channel for this
to work and must have the appropriate administrator rights.
.. seealso:: :attr:`telegram.Chat.ban_chat`, :attr:`telegram.Chat.ban_sender_chat`
.. seealso:: :meth:`telegram.Chat.ban_chat`, :meth:`telegram.Chat.ban_sender_chat`
.. versionadded:: 13.9
@ -2982,7 +2990,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
join it. So if the user is a member of the chat they will also be *removed* from the chat.
If you don't want this, use the parameter :paramref:`only_if_banned`.
.. seealso:: :attr:`telegram.Chat.unban_member`
.. seealso:: :meth:`telegram.Chat.unban_member`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -3026,7 +3034,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
The bot must be an administrator for this to work and must have the
appropriate administrator rights.
.. seealso:: :attr:`telegram.Chat.unban_chat`
.. seealso:: :meth:`telegram.Chat.unban_chat`
.. versionadded:: 13.9
@ -3079,7 +3087,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
and accept the terms. Otherwise, you may use links like t.me/your_bot?start=XXXX that open
your bot with a parameter.
.. seealso:: :attr:`telegram.CallbackQuery.answer`
.. seealso:: :meth:`telegram.CallbackQuery.answer`
Args:
callback_query_id (:obj:`str`): Unique identifier for the query to be answered.
@ -3149,8 +3157,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Note:
|editreplymarkup|.
.. seealso:: :attr:`telegram.Message.edit_text`,
:attr:`telegram.CallbackQuery.edit_message_text`
.. seealso:: :meth:`telegram.Message.edit_text`,
:meth:`telegram.CallbackQuery.edit_message_text`, :attr:`telegram.Game.text`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id`
@ -3224,8 +3232,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Note:
|editreplymarkup|
.. seealso:: :attr:`telegram.Message.edit_caption`,
:attr:`telegram.CallbackQuery.edit_message_caption`
.. seealso:: :meth:`telegram.Message.edit_caption`,
:meth:`telegram.CallbackQuery.edit_message_caption`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
@ -3295,8 +3303,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Note:
|editreplymarkup|
.. seealso:: :attr:`telegram.Message.edit_media`,
:attr:`telegram.CallbackQuery.edit_message_media`
.. seealso:: :meth:`telegram.Message.edit_media`,
:meth:`telegram.CallbackQuery.edit_message_media`
Args:
media (:class:`telegram.InputMedia`): An object for a new media content
@ -3356,8 +3364,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Note:
|editreplymarkup|
.. seealso:: :attr:`telegram.Message.edit_reply_markup`,
:attr:`telegram.CallbackQuery.edit_message_reply_markup`
.. seealso:: :meth:`telegram.Message.edit_reply_markup`,
:meth:`telegram.CallbackQuery.edit_message_reply_markup`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
@ -3419,6 +3427,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
server response.
3. To take full advantage of this library take a look at :class:`telegram.ext.Updater`
.. seealso:: :meth:`telegram.ext.Application.run_polling`,
:meth:`telegram.ext.Updater.start_polling`
Args:
offset (:obj:`int`, optional): Identifier of the first update to be returned. Must be
greater by one than the highest among the identifiers of previously received
@ -3534,6 +3545,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
If you're having any trouble setting up webhooks, please check out this `guide to
Webhooks`_.
.. seealso:: :meth:`telegram.ext.Application.run_webhook`,
:meth:`telegram.ext.Updater.start_webhook`
Examples:
:any:`Custom Webhook Bot <examples.customwebhookbot>`
@ -3657,7 +3671,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> bool:
"""Use this method for your bot to leave a group, supergroup or channel.
.. seealso:: :attr:`telegram.Chat.leave`
.. seealso:: :meth:`telegram.Chat.leave`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -3736,7 +3750,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
"""
Use this method to get a list of administrators in a chat.
.. seealso:: :attr:`telegram.Chat.get_administrators`
.. seealso:: :meth:`telegram.Chat.get_administrators`
.. versionchanged:: 20.0
Returns a tuple instead of a list.
@ -3779,7 +3793,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> int:
"""Use this method to get the number of members in a chat.
.. seealso:: :attr:`telegram.Chat.get_member_count`
.. seealso:: :meth:`telegram.Chat.get_member_count`
.. versionadded:: 13.7
@ -3819,7 +3833,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> ChatMember:
"""Use this method to get information about a member of a chat.
.. seealso:: :attr:`telegram.Chat.get_member`
.. seealso:: :meth:`telegram.Chat.get_member`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -3963,7 +3977,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
"""
Use this method to set the score of the specified user in a game message.
.. seealso::`telegram.CallbackQuery.set_game_score`
.. seealso:: :meth:`telegram.CallbackQuery.set_game_score`, :attr:`telegram.Game.text`
Args:
user_id (:obj:`int`): User identifier.
@ -4034,7 +4048,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
closest neighbors on each side. Will also return the top three users if the user and
his neighbors are not among them. Please note that this behavior is subject to change.
.. seealso:: :attr:`telegram.CallbackQuery.get_game_high_scores`
.. seealso:: :meth:`telegram.CallbackQuery.get_game_high_scores`,
:meth:`telegram.Message.get_game_high_scores`
Args:
user_id (:obj:`int`): Target user id.
@ -4116,8 +4131,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
order of the arguments had to be changed. Use keyword arguments to make sure that the
arguments are passed correctly.
.. seealso:: :attr:`telegram.Message.reply_invoice`, :attr:`telegram.Chat.send_invoice`,
:attr:`telegram.User.send_invoice`
.. seealso:: :meth:`telegram.Message.reply_invoice`, :meth:`telegram.Chat.send_invoice`,
:meth:`telegram.User.send_invoice`
.. versionchanged:: 13.5
As of Bot API 5.2, the parameter :paramref:`start_parameter` is optional.
@ -4270,7 +4285,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
:class:`telegram.Update` with a :attr:`telegram.Update.shipping_query` field to the bot.
Use this method to reply to shipping queries.
.. seealso:: :attr:`telegram.ShippingQuery.answer`
.. seealso:: :meth:`telegram.ShippingQuery.answer`
Args:
shipping_query_id (:obj:`str`): Unique identifier for the query to be answered.
@ -4333,7 +4348,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
The Bot API must receive an answer within 10 seconds after the pre-checkout
query was sent.
.. seealso:: :attr:`telegram.PreCheckoutQuery.answer`
.. seealso:: :meth:`telegram.PreCheckoutQuery.answer`
Args:
pre_checkout_query_id (:obj:`str`): Unique identifier for the query to be answered.
@ -4438,7 +4453,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
:obj:`True` for all boolean parameters to lift restrictions from a user.
.. seealso:: :meth:`telegram.ChatPermissions.all_permissions`,
:attr:`telegram.Chat.restrict_member`
:meth:`telegram.Chat.restrict_member`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_group|
@ -4507,7 +4522,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
an administrator in the chat for this to work and must have the appropriate admin rights.
Pass :obj:`False` for all boolean parameters to demote a user.
.. seealso:: :attr:`telegram.Chat.promote_member`
.. seealso:: :meth:`telegram.Chat.promote_member`
.. versionchanged:: 20.0
The argument ``can_manage_voice_chats`` was renamed to
@ -4606,7 +4621,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
administrator in the group or a supergroup for this to work and must have the
:attr:`telegram.ChatMemberAdministrator.can_restrict_members` admin rights.
.. seealso:: :attr:`telegram.Chat.set_permissions`
.. seealso:: :meth:`telegram.Chat.set_permissions`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_group|
@ -4648,7 +4663,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Use this method to set a custom title for administrators promoted by the bot in a
supergroup. The bot must be an administrator for this to work.
.. seealso:: :attr:`telegram.Chat.set_administrator_custom_title`
.. seealso:: :meth:`telegram.Chat.set_administrator_custom_title`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_group|
@ -4699,9 +4714,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
links generated by other administrators. If you want your bot to work with invite
links, it will need to generate its own link using :meth:`export_chat_invite_link` or
by calling the :meth:`get_chat` method. If your bot needs to generate a new primary
invite link replacing its previous one, use :attr:`export_chat_invite_link` again.
invite link replacing its previous one, use :meth:`export_chat_invite_link` again.
.. seealso:: :attr:`telegram.Chat.export_invite_link`
.. seealso:: :meth:`telegram.Chat.export_invite_link`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -4745,7 +4760,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
administrator in the chat for this to work and must have the appropriate admin rights.
The link can be revoked using the method :meth:`revoke_chat_invite_link`.
.. seealso:: :attr:`telegram.Chat.create_invite_link`
.. seealso:: :meth:`telegram.Chat.create_invite_link`
.. versionadded:: 13.4
@ -4823,7 +4838,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
parameters to the default values. However, since not documented, this behaviour may
change unbeknown to PTB.
.. seealso:: :attr:`telegram.Chat.edit_invite_link`
.. seealso:: :meth:`telegram.Chat.edit_invite_link`
.. versionadded:: 13.4
@ -4898,7 +4913,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
revoked, a new link is automatically generated. The bot must be an administrator in the
chat for this to work and must have the appropriate admin rights.
.. seealso:: :attr:`telegram.Chat.revoke_invite_link`
.. seealso:: :meth:`telegram.Chat.revoke_invite_link`
.. versionadded:: 13.4
@ -4948,8 +4963,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
The bot must be an administrator in the chat for this to work and must have the
:attr:`telegram.ChatPermissions.can_invite_users` administrator right.
.. seealso:: :attr:`telegram.Chat.approve_join_request`,
:attr:`telegram.ChatJoinRequest.approve`, :attr:`telegram.User.approve_join_request`
.. seealso:: :meth:`telegram.Chat.approve_join_request`,
:meth:`telegram.ChatJoinRequest.approve`, :meth:`telegram.User.approve_join_request`
.. versionadded:: 13.8
@ -4994,8 +5009,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
The bot must be an administrator in the chat for this to work and must have the
:attr:`telegram.ChatPermissions.can_invite_users` administrator right.
.. seealso:: :attr:`telegram.Chat.decline_join_request`,
:attr:`telegram.ChatJoinRequest.decline`, :attr:`telegram.User.decline_join_request`
.. seealso:: :meth:`telegram.Chat.decline_join_request`,
:meth:`telegram.ChatJoinRequest.decline`, :meth:`telegram.User.decline_join_request`
.. versionadded:: 13.8
@ -5040,7 +5055,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Photos can't be changed for private chats. The bot must be an administrator in the chat
for this to work and must have the appropriate admin rights.
.. seealso:: :attr:`telegram.Chat.set_photo`
.. seealso:: :meth:`telegram.Chat.set_photo`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -5089,7 +5104,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
must be an administrator in the chat for this to work and must have the appropriate admin
rights.
.. seealso:: :attr:`telegram.Chat.delete_photo`
.. seealso:: :meth:`telegram.Chat.delete_photo`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -5130,7 +5145,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
The bot must be an administrator in the chat for this to work and must have the appropriate
admin rights.
.. seealso:: :attr:`telegram.Chat.set_title`
.. seealso:: :meth:`telegram.Chat.set_title`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -5174,7 +5189,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
must be an administrator in the chat for this to work and must have the appropriate admin
rights.
.. seealso:: :attr:`telegram.Chat.set_description`
.. seealso:: :meth:`telegram.Chat.set_description`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -5222,7 +5237,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin
right in a channel.
.. seealso:: :attr:`telegram.Chat.pin_message`, :attr:`telegram.User.pin_message`
.. seealso:: :meth:`telegram.Chat.pin_message`, :meth:`telegram.Message.pin`,
:meth:`telegram.User.pin_message`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -5273,7 +5289,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin
right in a channel.
.. seealso:: :attr:`telegram.Chat.unpin_message`, :attr:`telegram.User.unpin_message`
.. seealso:: :meth:`telegram.Chat.unpin_message`, :meth:`telegram.Message.unpin`,
:meth:`telegram.User.unpin_message`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -5317,8 +5334,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
admin right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages`
admin right in a channel.
.. seealso:: :attr:`telegram.Chat.unpin_all_messages`,
:attr:`telegram.User.unpin_all_messages`
.. seealso:: :meth:`telegram.Chat.unpin_all_messages`,
:meth:`telegram.User.unpin_all_messages`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -5895,8 +5912,8 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
"""
Use this method to send a native poll.
.. seealso:: :attr:`telegram.Message.reply_poll`, :attr:`telegram.Chat.send_poll`,
:attr:`telegram.User.send_poll`
.. seealso:: :meth:`telegram.Message.reply_poll`, :meth:`telegram.Chat.send_poll`,
:meth:`telegram.User.send_poll`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -6010,7 +6027,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
"""
Use this method to stop a poll which was sent by the bot.
.. seealso:: :attr:`telegram.Message.stop_poll`
.. seealso:: :meth:`telegram.Message.stop_poll`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -6063,8 +6080,8 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
"""
Use this method to send an animated emoji that will display a random value.
.. seealso:: :attr:`telegram.Message.reply_dice`, :attr:`telegram.Chat.send_dice`,
:attr:`telegram.User.send_dice`
.. seealso:: :meth:`telegram.Message.reply_dice`, :meth:`telegram.Chat.send_dice`,
:meth:`telegram.User.send_dice`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@ -6228,6 +6245,8 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
Use this method to get the current list of the bot's commands for the given scope and user
language.
.. seealso:: :meth:`set_my_commands`, :meth:`delete_my_commands`
.. versionchanged:: 20.0
Returns a tuple instead of a list.
@ -6282,6 +6301,8 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
`Telegram docs <https://core.telegram.org/bots/features#commands>`_ for more details about
bot commands.
.. seealso:: :meth:`get_my_commands`, :meth:`delete_my_commands`
Args:
commands (List[:class:`BotCommand` | (:obj:`str`, :obj:`str`)]): A list
of bot commands to be set as the list of the bot's commands. At most
@ -6341,6 +6362,8 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
.. versionadded:: 13.7
.. seealso:: :meth:`get_my_commands`, :meth:`set_my_commands`
Args:
scope (:class:`telegram.BotCommandScope`, optional): An object,
describing scope of users for which the commands are relevant. Defaults to
@ -6461,9 +6484,9 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
be copied. The method is analogous to the method :meth:`forward_message`, but the copied
message doesn't have a link to the original message.
.. seealso:: :attr:`telegram.Message.copy`, :attr:`telegram.Chat.send_copy`,
:attr:`telegram.Chat.copy_message`, :attr:`telegram.User.send_copy`,
:attr:`telegram.User.copy_message`
.. seealso:: :meth:`telegram.Message.copy`, :meth:`telegram.Chat.send_copy`,
:meth:`telegram.Chat.copy_message`, :meth:`telegram.User.send_copy`,
:meth:`telegram.User.copy_message`
Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|

2
telegram/_chat.py
View file

@ -2839,7 +2839,7 @@ class Chat(TelegramObject):
await bot.get_chat_menu_button(chat_id=update.effective_chat.id, *args, **kwargs)
For the documentation of the arguments, please see
:meth:`telegram.Bot.set_chat_menu_button`.
:meth:`telegram.Bot.get_chat_menu_button`.
Caution:
Can only work, if the chat is a private chat.

2
telegram/_files/_basemedium.py
View file

@ -79,7 +79,7 @@ class _BaseMedium(TelegramObject):
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict = None,
) -> "File":
"""Convenience wrapper over :attr:`telegram.Bot.get_file`
"""Convenience wrapper over :meth:`telegram.Bot.get_file`
For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.

4
telegram/_files/chatphoto.py
View file

@ -111,7 +111,7 @@ class ChatPhoto(TelegramObject):
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict = None,
) -> "File":
"""Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the small
"""Convenience wrapper over :meth:`telegram.Bot.get_file` for getting the small
(:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`)
chat photo
@ -142,7 +142,7 @@ class ChatPhoto(TelegramObject):
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict = None,
) -> "File":
"""Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the
"""Convenience wrapper over :meth:`telegram.Bot.get_file` for getting the
big (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`)
chat photo

2
telegram/_passport/passportfile.py
View file

@ -157,7 +157,7 @@ class PassportFile(TelegramObject):
api_kwargs: JSONDict = None,
) -> "File":
"""
Wrapper over :attr:`telegram.Bot.get_file`. Will automatically assign the correct
Wrapper over :meth:`telegram.Bot.get_file`. Will automatically assign the correct
credentials to the returned :class:`telegram.File` if originating from
:obj:`telegram.PassportData.decrypted_data`.

17
telegram/ext/_application.py
View file

@ -162,7 +162,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
(and encouraged), but editing the mapping ``application.chat_data`` itself is not.
.. tip::
Manually modifying :attr:`chat_data` is almost never needed and unadvisable.
* Manually modifying :attr:`chat_data` is almost never needed and unadvisable.
* Entries are never deleted automatically from this mapping. If you want to delete
the data associated with a specific chat, e.g. if the bot got removed from that
chat, please use :meth:`drop_chat_data`.
user_data (:obj:`types.MappingProxyType`): A dictionary handlers can use to store data for
the user. For each integer user id, the corresponding value of this mapping is
@ -175,7 +179,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
(and encouraged), but editing the mapping ``application.user_data`` itself is not.
.. tip::
Manually modifying :attr:`user_data` is almost never needed and unadvisable.
* Manually modifying :attr:`user_data` is almost never needed and unadvisable.
* Entries are never deleted automatically from this mapping. If you want to delete
the data associated with a specific user, e.g. if that user blocked the bot,
please use :meth:`drop_user_data`.
bot_data (:obj:`dict`): A dictionary handlers can use to store data for the bot.
persistence (:class:`telegram.ext.BasePersistence`): The persistence class to
@ -504,6 +512,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
either start :attr:`updater` manually or use one of :meth:`run_polling` or
:meth:`run_webhook`.
Tip:
When using a custom logic for startup and shutdown of the application, eventual
cancellation of pending tasks should happen only `after` :meth:`stop` has been called
in order to ensure that the tasks mentioned above are not cancelled prematurely.
.. seealso::
:meth:`stop`

1
telegram/ext/_conversationhandler.py
View file

@ -208,6 +208,7 @@ class ConversationHandler(BaseHandler[Update, CCT]):
handled.
allow_reentry (:obj:`bool`, optional): If set to :obj:`True`, a user that is currently in a
conversation can restart the conversation by triggering one of the entry points.
Default is :obj:`False`.
per_chat (:obj:`bool`, optional): If the conversation key should contain the Chat's ID.
Default is :obj:`True`.
per_user (:obj:`bool`, optional): If the conversation key should contain the User's ID.

7
telegram/ext/_messagehandler.py
View file

@ -44,11 +44,8 @@ class MessageHandler(BaseHandler[Update, CCT]):
filters (:class:`telegram.ext.filters.BaseFilter`): A filter inheriting from
:class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
:mod:`telegram.ext.filters`. Filters can be combined using bitwise
operators (& for and, | for or, ~ for not). This defaults to all message updates
being: :attr:`telegram.Update.message`, :attr:`telegram.Update.edited_message`,
:attr:`telegram.Update.channel_post` and :attr:`telegram.Update.edited_channel_post`.
If you don't want or need any of those pass ``~filters.UpdateType.*`` in the filter
argument.
operators (& for and, | for or, ~ for not). Passing :obj:`None` is a shortcut
to passing :class:`telegram.ext.filters.ALL`.
.. seealso:: `Advanced Filters <https://github.com/\
python-telegram-bot/python-telegram-bot/wiki/Extensions-–-Advanced-Filters>`_