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 (#3139, #3153, #3135)

Browse source 
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
Co-authored-by: Poolitzer <github@poolitzer.eu>
Co-authored-by: Pawan <pawanrai9999@gmail.com>
Co-authored-by: Aditya Yadav <69784758+aditya-yadav-27@users.noreply.github.com>
This commit is contained in:
Bibo-Joshi 2022-08-27 11:46:51 +02:00 committed by GitHub
parent 741a50ab97
commit a983a89964
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
42 changed files with 420 additions and 186 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
AUTHORS.rst
View file

@ -86,6 +86,7 @@ The following wonderful people contributed directly or indirectly to this projec
- `Paradox <https://github.com/paradox70>`_
- `Patrick Hofmann <https://github.com/PH89>`_
- `Paul Larsen <https://github.com/PaulSonOfLars>`_
- `Pawan <https://github.com/pawanrai9999>`_
- `Pieter Schutz <https://github.com/eldinnie>`_
- `Piraty <https://github.com/piraty>`_
- `Poolitzer <https://github.com/Poolitzer>`_

2
docs/source/examples.rst
View file

@ -49,7 +49,7 @@ this library, we introduced the
:class:`telegram.ext.ConversationHandler`
for that exact purpose. This example uses it to retrieve
user-information in a conversation-like style. To get a better
understanding, take a look at the :ref:`state diagrem <conversationbot-diagram>`.
understanding, take a look at the :ref:`state diagram <conversationbot-diagram>`.
:any:`examples.conversationbot2`
--------------------------------

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

@ -0,0 +1,7 @@
Arbitrary Callback Data
-----------------------
.. toctree::
telegram.ext.callbackdatacache
telegram.ext.invalidcallbackdata

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

@ -0,0 +1,23 @@
Handlers
--------
.. toctree::
telegram.ext.basehandler
telegram.ext.callbackqueryhandler
telegram.ext.chatjoinrequesthandler
telegram.ext.chatmemberhandler
telegram.ext.choseninlineresulthandler
telegram.ext.commandhandler
telegram.ext.conversationhandler
telegram.ext.filters
telegram.ext.inlinequeryhandler
telegram.ext.messagehandler
telegram.ext.pollanswerhandler
telegram.ext.pollhandler
telegram.ext.precheckoutqueryhandler
telegram.ext.prefixhandler
telegram.ext.shippingqueryhandler
telegram.ext.stringcommandhandler
telegram.ext.stringregexhandler
telegram.ext.typehandler

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

@ -0,0 +1,9 @@
Persistence
-----------
.. toctree::
telegram.ext.basepersistence
telegram.ext.dictpersistence
telegram.ext.persistenceinput
telegram.ext.picklepersistence

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

@ -0,0 +1,7 @@
Rate Limiting
-------------
.. toctree::
telegram.ext.baseratelimiter
telegram.ext.aioratelimiter

54
docs/source/telegram.ext.rst
View file

@ -13,53 +13,7 @@ telegram.ext package
telegram.ext.job
telegram.ext.jobqueue
telegram.ext.updater
Handlers
--------
.. toctree::
telegram.ext.basehandler
telegram.ext.callbackqueryhandler
telegram.ext.chatjoinrequesthandler
telegram.ext.chatmemberhandler
telegram.ext.choseninlineresulthandler
telegram.ext.commandhandler
telegram.ext.conversationhandler
telegram.ext.filters
telegram.ext.inlinequeryhandler
telegram.ext.messagehandler
telegram.ext.pollanswerhandler
telegram.ext.pollhandler
telegram.ext.precheckoutqueryhandler
telegram.ext.prefixhandler
telegram.ext.shippingqueryhandler
telegram.ext.stringcommandhandler
telegram.ext.stringregexhandler
telegram.ext.typehandler
Persistence
-----------
.. toctree::
telegram.ext.basepersistence
telegram.ext.dictpersistence
telegram.ext.persistenceinput
telegram.ext.picklepersistence
Arbitrary Callback Data
-----------------------
.. toctree::
telegram.ext.callbackdatacache
telegram.ext.invalidcallbackdata
Rate Limiting
-------------
.. toctree::
telegram.ext.baseratelimiter
telegram.ext.aioratelimiter
telegram.ext.handlers-tree.rst
telegram.ext.persistence-tree.rst
telegram.ext.acd-tree.rst
telegram.ext.rate-limiting-tree.rst

8
docs/source/telegram.games-tree.rst Normal file
View file

@ -0,0 +1,8 @@
Games
-----
.. toctree::
telegram.callbackgame
telegram.game
telegram.gamehighscore

34
docs/source/telegram.inline-tree.rst Normal file
View file

@ -0,0 +1,34 @@
Inline Mode
-----------
.. toctree::
telegram.choseninlineresult
telegram.inlinequery
telegram.inlinequeryresult
telegram.inlinequeryresultarticle
telegram.inlinequeryresultaudio
telegram.inlinequeryresultcachedaudio
telegram.inlinequeryresultcacheddocument
telegram.inlinequeryresultcachedgif
telegram.inlinequeryresultcachedmpeg4gif
telegram.inlinequeryresultcachedphoto
telegram.inlinequeryresultcachedsticker
telegram.inlinequeryresultcachedvideo
telegram.inlinequeryresultcachedvoice
telegram.inlinequeryresultcontact
telegram.inlinequeryresultdocument
telegram.inlinequeryresultgame
telegram.inlinequeryresultgif
telegram.inlinequeryresultlocation
telegram.inlinequeryresultmpeg4gif
telegram.inlinequeryresultphoto
telegram.inlinequeryresultvenue
telegram.inlinequeryresultvideo
telegram.inlinequeryresultvoice
telegram.inputmessagecontent
telegram.inputtextmessagecontent
telegram.inputlocationmessagecontent
telegram.inputvenuemessagecontent
telegram.inputcontactmessagecontent
telegram.inputinvoicemessagecontent

27
docs/source/telegram.passport-tree.rst Normal file
View file

@ -0,0 +1,27 @@
Passport
--------
.. toctree::
telegram.credentials
telegram.datacredentials
telegram.encryptedcredentials
telegram.encryptedpassportelement
telegram.filecredentials
telegram.iddocumentdata
telegram.passportdata
telegram.passportelementerror
telegram.passportelementerrordatafield
telegram.passportelementerrorfile
telegram.passportelementerrorfiles
telegram.passportelementerrorfrontside
telegram.passportelementerrorreverseside
telegram.passportelementerrorselfie
telegram.passportelementerrortranslationfile
telegram.passportelementerrortranslationfiles
telegram.passportelementerrorunspecified
telegram.passportfile
telegram.personaldetails
telegram.residentialaddress
telegram.securedata
telegram.securevalue

13
docs/source/telegram.payments-tree.rst Normal file
View file

@ -0,0 +1,13 @@
Payments
--------
.. toctree::
telegram.invoice
telegram.labeledprice
telegram.orderinfo
telegram.precheckoutquery
telegram.shippingaddress
telegram.shippingoption
telegram.shippingquery
telegram.successfulpayment

99
docs/source/telegram.rst
View file

@ -89,98 +89,9 @@ Available Types
telegram.webappdata
telegram.webappinfo
telegram.webhookinfo
telegram.stickers-tree.rst
telegram.inline-tree.rst
telegram.payments-tree.rst
telegram.games-tree.rst
telegram.passport-tree.rst
Stickers
--------
.. toctree::
telegram.maskposition
telegram.sticker
telegram.stickerset
Inline Mode
-----------
.. toctree::
telegram.choseninlineresult
telegram.inlinequery
telegram.inlinequeryresult
telegram.inlinequeryresultarticle
telegram.inlinequeryresultaudio
telegram.inlinequeryresultcachedaudio
telegram.inlinequeryresultcacheddocument
telegram.inlinequeryresultcachedgif
telegram.inlinequeryresultcachedmpeg4gif
telegram.inlinequeryresultcachedphoto
telegram.inlinequeryresultcachedsticker
telegram.inlinequeryresultcachedvideo
telegram.inlinequeryresultcachedvoice
telegram.inlinequeryresultcontact
telegram.inlinequeryresultdocument
telegram.inlinequeryresultgame
telegram.inlinequeryresultgif
telegram.inlinequeryresultlocation
telegram.inlinequeryresultmpeg4gif
telegram.inlinequeryresultphoto
telegram.inlinequeryresultvenue
telegram.inlinequeryresultvideo
telegram.inlinequeryresultvoice
telegram.inputmessagecontent
telegram.inputtextmessagecontent
telegram.inputlocationmessagecontent
telegram.inputvenuemessagecontent
telegram.inputcontactmessagecontent
telegram.inputinvoicemessagecontent
Payments
--------
.. toctree::
telegram.invoice
telegram.labeledprice
telegram.orderinfo
telegram.precheckoutquery
telegram.shippingaddress
telegram.shippingoption
telegram.shippingquery
telegram.successfulpayment
Games
-----
.. toctree::
telegram.callbackgame
telegram.game
telegram.gamehighscore
Passport
--------
.. toctree::
telegram.credentials
telegram.datacredentials
telegram.encryptedcredentials
telegram.encryptedpassportelement
telegram.filecredentials
telegram.iddocumentdata
telegram.passportdata
telegram.passportelementerror
telegram.passportelementerrordatafield
telegram.passportelementerrorfile
telegram.passportelementerrorfiles
telegram.passportelementerrorfrontside
telegram.passportelementerrorreverseside
telegram.passportelementerrorselfie
telegram.passportelementerrortranslationfile
telegram.passportelementerrortranslationfiles
telegram.passportelementerrorunspecified
telegram.passportfile
telegram.personaldetails
telegram.residentialaddress
telegram.securedata
telegram.securevalue

8
docs/source/telegram.stickers-tree.rst Normal file
View file

@ -0,0 +1,8 @@
Stickers
--------
.. toctree::
telegram.maskposition
telegram.sticker
telegram.stickerset

211
telegram/_bot.py
View file

@ -139,6 +139,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
serialized instance will not reflect that change. Trying to pickle a bot instance will
raise :exc:`pickle.PicklingError`.
.. seealso:: :attr:`telegram.ext.Application.bot`,
:attr:`telegram.ext.CallbackContext.bot`,
:attr:`telegram.ext.Updater.bot`
.. versionadded:: 13.2
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`bot` is equal.
@ -590,6 +594,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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -683,16 +690,19 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Use this method to delete a message, including service messages, with the following
limitations:
- A message can only be deleted if it was sent less than 48 hours ago.
- A dice message in a private chat can only be deleted if it was sent more than 24
hours ago.
- Bots can delete outgoing messages in private chats, groups, and supergroups.
- Bots can delete incoming messages in private chats.
- Bots granted :attr:`~telegram.ChatMemberAdministrator.can_post_messages` permissions
can delete outgoing messages in channels.
- If the bot is an administrator of a group, it can delete any message there.
- If the bot has :attr:`~telegram.ChatMemberAdministrator.can_delete_messages`
permission in a supergroup or a channel, it can delete any message there.
- A message can only be deleted if it was sent less than 48 hours ago.
- A dice message in a private chat can only be deleted if it was sent more than 24
hours ago.
- Bots can delete outgoing messages in private chats, groups, and supergroups.
- Bots can delete incoming messages in private chats.
- Bots granted :attr:`~telegram.ChatMemberAdministrator.can_post_messages` permissions
can delete outgoing messages in channels.
- If the bot is an administrator of a group, it can delete any message there.
- If the bot has :attr:`~telegram.ChatMemberAdministrator.can_delete_messages`
permission in a supergroup or a channel, it can delete any message there.
.. seealso:: :meth:`telegram.Message.delete`,
:meth:`telegram.CallbackQuery.delete_message`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -760,6 +770,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -842,6 +855,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
The photo argument can be either a file_id, an URL or a file from disk
``open(filename, 'rb')``
.. seealso:: :attr:`telegram.Message.reply_photo`, :attr:`telegram.Chat.send_photo`,
:attr:`telegram.User.send_photo`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -972,6 +988,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
The audio argument can be either a file_id, an URL or a file from disk
``open(filename, 'rb')``
.. seealso:: :attr:`telegram.Message.reply_audio`, :attr:`telegram.Chat.send_audio`,
:attr:`telegram.User.send_audio`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -1119,6 +1138,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
* Sending by URL will currently only work ``GIF``, ``PDF`` & ``ZIP`` files.
.. seealso:: :attr:`telegram.Message.reply_document`, :attr:`telegram.Chat.send_document`,
:attr:`telegram.User.send_document`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -1247,6 +1269,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
The :paramref:`sticker` argument can be either a file_id, an URL or a file from disk
``open(filename, 'rb')``
.. seealso:: :attr:`telegram.Message.reply_sticker`, :attr:`telegram.Chat.send_sticker`,
:attr:`telegram.User.send_sticker`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -1354,6 +1379,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`, :attr:`telegram.Chat.send_video`,
:attr:`telegram.User.send_video`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -1500,6 +1528,10 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -1630,6 +1662,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
generate thumb nails. 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -1777,6 +1813,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
* To use this method, the file must have the type :mimetype:`audio/ogg` and be no more
than ``1MB`` in size. ``1-20MB`` voice notes will be sent as files.
.. seealso:: :attr:`telegram.Message.reply_voice`, :attr:`telegram.Chat.send_voice`,
:attr:`telegram.User.send_voice`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -1891,6 +1930,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> List[Message]:
"""Use this method to send a group of photos or videos as an album.
.. seealso:: :attr:`telegram.Message.reply_media_group`,
:attr:`telegram.Chat.send_media_group`,
:attr:`telegram.User.send_media_group`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -1982,6 +2025,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -2106,6 +2152,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
specified. Unique identifier for the target chat or username of the target channel
@ -2206,6 +2255,9 @@ 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 live_period expires.
.. seealso:: :attr:`telegram.Message.stop_live_location`
:attr:`telegram.CallbackQuery.stop_message_live_location`
Args:
chat_id (:obj:`int` | :obj:`str`): Required if inline_message_id is not specified.
Unique identifier for the target chat or username of the target channel
@ -2292,6 +2344,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -2430,6 +2485,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -2541,6 +2599,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat.
game_short_name (:obj:`str`): Short name of the game, serves as the unique identifier
@ -2618,6 +2679,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -2767,6 +2831,8 @@ 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`
Args:
inline_query_id (:obj:`str`): Unique identifier for the answered query.
results (List[:class:`telegram.InlineQueryResult`] | Callable): A list of results for
@ -2874,6 +2940,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> UserProfilePhotos:
"""Use this method to get a list of profile pictures for a user.
.. seealso:: :meth:`telegram.User.get_profile_photos`
Args:
user_id (:obj:`int`): Unique identifier of the target user.
offset (:obj:`int`, optional): Sequential number of the first photo to be returned.
@ -3028,6 +3096,8 @@ 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`
.. versionadded:: 13.7
Args:
@ -3109,6 +3179,8 @@ 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`
.. versionadded:: 13.9
Args:
@ -3174,6 +3246,8 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target supergroup or channel (in the format ``@channelusername``).
@ -3236,6 +3310,8 @@ 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`
.. versionadded:: 13.9
Args:
@ -3304,6 +3380,8 @@ 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`
Args:
callback_query_id (:obj:`str`): Unique identifier for the query to be answered.
text (:obj:`str`, optional): Text of the notification. If not specified, nothing will
@ -3392,6 +3470,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
It is currently only possible to edit messages without
:attr:`telegram.Message.reply_markup` or with inline keyboards.
.. seealso:: :attr:`telegram.Message.edit_text`,
:attr:`telegram.CallbackQuery.edit_message_text`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
specified. Unique identifier for the target chat or username of the target channel
@ -3488,6 +3569,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
It is currently only possible to edit messages without
:attr:`telegram.Message.reply_markup` or with inline keyboards
.. seealso:: :attr:`telegram.Message.edit_caption`,
:attr:`telegram.CallbackQuery.edit_message_caption`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
specified. Unique identifier for the target chat or username of the target channel
@ -3582,6 +3666,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
It is currently only possible to edit messages without
:attr:`telegram.Message.reply_markup` or with inline keyboards
.. seealso:: :attr:`telegram.Message.edit_media`,
:attr:`telegram.CallbackQuery.edit_message_media`
Args:
media (:class:`telegram.InputMedia`): An object for a new media content
of the message.
@ -3660,6 +3747,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
It is currently only possible to edit messages without
:attr:`telegram.Message.reply_markup` or with inline keyboards
.. seealso:: :attr:`telegram.Message.edit_reply_markup`,
:attr:`telegram.CallbackQuery.edit_message_reply_markup`
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
specified. Unique identifier for the target chat or username of the target channel
@ -4016,6 +4106,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> bool:
"""Use this method for your bot to leave a group, supergroup or channel.
.. seealso:: :attr:`telegram.Chat.leave`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target supergroup or channel (in the format ``@channelusername``).
@ -4127,6 +4219,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
"""
Use this method to get a list of administrators in a chat.
.. seealso:: :attr:`telegram.Chat.get_administrators`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target supergroup or channel (in the format ``@channelusername``).
@ -4182,6 +4276,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> int:
"""Use this method to get the number of members in a chat.
.. seealso:: :attr:`telegram.Chat.get_member_count`
.. versionadded:: 13.7
Args:
@ -4237,6 +4333,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> ChatMember:
"""Use this method to get information about a member of a chat.
.. seealso:: :attr:`telegram.Chat.get_member`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target supergroup or channel (in the format ``@channelusername``).
@ -4447,6 +4545,8 @@ 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`
Args:
user_id (:obj:`int`): User identifier.
score (:obj:`int`): New score, must be non-negative.
@ -4532,6 +4632,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`
Args:
user_id (:obj:`int`): Target user id.
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
@ -4629,6 +4731,9 @@ 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`
.. versionchanged:: 13.5
As of Bot API 5.2, the parameter :paramref:`start_parameter` is optional.
@ -4812,6 +4917,8 @@ 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`
Args:
shipping_query_id (:obj:`str`): Unique identifier for the query to be answered.
ok (:obj:`bool`): Specify :obj:`True` if delivery to the specified address is possible
@ -4889,6 +4996,8 @@ 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`
Args:
pre_checkout_query_id (:obj:`str`): Unique identifier for the query to be answered.
ok (:obj:`bool`): Specify :obj:`True` if everything is alright
@ -5019,7 +5128,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
the supergroup for this to work and must have the appropriate admin rights. Pass
:obj:`True` for all boolean parameters to lift restrictions from a user.
.. seealso:: :meth:`telegram.ChatPermissions.all_permissions`
.. seealso:: :meth:`telegram.ChatPermissions.all_permissions`,
:attr:`telegram.Chat.restrict_member`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -5106,6 +5216,8 @@ 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`
.. versionchanged:: 20.0
The argument ``can_manage_voice_chats`` was renamed to
:paramref:`can_manage_video_chats` in accordance to Bot API 6.0.
@ -5224,6 +5336,8 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of
the target supergroup (in the format `@supergroupusername`).
@ -5281,6 +5395,8 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of
the target supergroup (in the format `@supergroupusername`).
@ -5341,6 +5457,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
link is revoked. The bot must be an administrator in the chat for this to work and must
have the appropriate admin rights.
.. seealso:: :attr:`telegram.Chat.export_invite_link`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -5407,6 +5525,8 @@ 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`
.. versionadded:: 13.4
Args:
@ -5505,6 +5625,8 @@ 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`
.. versionadded:: 13.4
Args:
@ -5599,6 +5721,8 @@ 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`
.. versionadded:: 13.4
Args:
@ -5664,6 +5788,9 @@ 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`
.. versionadded:: 13.8
Args:
@ -5724,6 +5851,9 @@ 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`
.. versionadded:: 13.8
Args:
@ -5784,6 +5914,8 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -5843,6 +5975,8 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -5899,6 +6033,8 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -5956,6 +6092,8 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -6019,6 +6157,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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -6085,6 +6225,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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -6147,6 +6289,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -6870,6 +7015,9 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -7002,6 +7150,8 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -7068,9 +7218,20 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
receive a notification with no sound.
reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
original message.
reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \
:class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional):
Additional interface options. An object for an inline keyboard, custom reply
keyboard, instructions to remove reply keyboard or to force a reply from the user
emoji (:obj:`str`, optional): Emoji on which the dice throw animation is based.
Currently, must be one of :class:`telegram.constants.DiceEmoji`. Dice can have
values 1-6 for :tg-const:`telegram.constants.DiceEmoji.DICE`,
@ -7082,23 +7243,14 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
:tg-const:`telegram.constants.DiceEmoji.DICE`.
.. versionchanged:: 13.4
Added the :tg-const:`telegram.constants.DiceEmoji.BOWLING` emoji.
disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
receive a notification with no sound.
Added the :tg-const:`telegram.constants.DiceEmoji.BOWLING` emoji..
allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message
should be sent even if the specified replied-to message is not found.
protect_content (:obj:`bool`, optional): Protects the contents of the sent message from
forwarding and saving.
.. versionadded:: 13.10
reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
original message.
allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message
should be sent even if the specified replied-to message is not found.
reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \
:class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional):
Additional interface options. An object for an inline keyboard, custom reply
keyboard, instructions to remove reply keyboard or to force a reply from the user.
Keyword Args:
read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to
:paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to
@ -7616,6 +7768,10 @@ 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`
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
@ -7667,6 +7823,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
Raises:
:class:`telegram.error.TelegramError`
"""
data: JSONDict = {
"chat_id": chat_id,
@ -7713,7 +7870,8 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
button.
.. seealso:: :meth:`get_chat_menu_button`, :meth:`telegram.Chat.set_menu_button`,
:meth:`telegram.User.set_menu_button`
:meth:`telegram.Chat.get_menu_button`, meth:`telegram.User.set_menu_button`,
:meth:`telegram.User.get_menu_button`
.. versionadded:: 20.0
@ -7741,6 +7899,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
Returns:
:obj:`bool`: On success, :obj:`True` is returned.
"""
data: JSONDict = {}
if chat_id is not None:
@ -7773,7 +7932,8 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
the default menu button.
.. seealso:: :meth:`set_chat_menu_button`, :meth:`telegram.Chat.get_menu_button`,
:meth:`telegram.User.get_menu_button`
:meth:`telegram.Chat.set_menu_button`, :meth:`telegram.User.get_menu_button`,
:meth:`telegram.User.set_menu_button`
.. versionadded:: 20.0
@ -7799,6 +7959,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
Returns:
:class:`telegram.MenuButton`: On success, the current menu button is returned.
"""
data = {}
if chat_id is not None:

4
telegram/_chat.py
View file

@ -2389,7 +2389,7 @@ class Chat(TelegramObject):
Caution:
Can only work, if the chat is a private chat.
..seealso:: :meth:`get_menu_button`
.. seealso:: :meth:`get_menu_button`
.. versionadded:: 20.0
@ -2425,7 +2425,7 @@ class Chat(TelegramObject):
Caution:
Can only work, if the chat is a private chat.
..seealso:: :meth:`set_menu_button`
.. seealso:: :meth:`set_menu_button`
.. versionadded:: 20.0

2
telegram/_chatmember.py
View file

@ -44,6 +44,8 @@ class ChatMember(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`user` and :attr:`status` are equal.
.. seealso:: `Chat Member Example <examples.chatmemberbot.html>`_
.. versionchanged:: 20.0
* As of Bot API 5.3, :class:`ChatMember` is nothing but the base class for the subclasses

10
telegram/_files/file.py
View file

@ -44,7 +44,7 @@ class File(TelegramObject):
Note:
* Maximum file size to download is
:tg-const:`telegram.constants.FileSizeLimit.FILESIZE_DOWNLOAD`.
:tg-const:`telegram.constants.FileSizeLimit.FILESIZE_DOWNLOAD`.
* If you obtain an instance of this class from :attr:`telegram.PassportFile.get_file`,
then it will automatically be decrypted as it downloads when you call :meth:`download()`.
@ -111,7 +111,7 @@ class File(TelegramObject):
original filename as reported by Telegram. If the file has no filename, it the file ID will
be used as filename. If a :paramref:`custom_path` is supplied, it will be saved to that
path instead. If :paramref:`out` is defined, the file contents will be saved to that object
using the ``out.write`` method.
using the :obj:`out.write<io.BufferedWriter.write>` method.
Note:
* :paramref:`custom_path` and :paramref:`out` are mutually exclusive.
@ -144,8 +144,8 @@ class File(TelegramObject):
Returns:
:class:`pathlib.Path` | :obj:`io.BufferedWriter`: The same object as :paramref:`out` if
specified. Otherwise, returns the filename downloaded to or the file path of the
local file.
specified. Otherwise, returns the filename downloaded to or the file path of the
local file.
Raises:
ValueError: If both :paramref:`custom_path` and :paramref:`out` are passed.
@ -214,7 +214,7 @@ class File(TelegramObject):
Returns:
:obj:`bytearray`: The same object as :paramref:`buf` if it was specified. Otherwise a
newly allocated :obj:`bytearray`.
newly allocated :obj:`bytearray`.
"""
if buf is None:

4
telegram/_inline/inlinekeyboardbutton.py
View file

@ -62,6 +62,10 @@ class InlineKeyboardButton(TelegramObject):
* After Bot API 6.1, only ``HTTPS`` links will be allowed in :paramref:`login_url`.
.. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
`Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_,
:class:`telegram.InlineKeyboardMarkup`
.. versionchanged:: 20.0
:attr:`web_app` is considered as well when comparing objects of this type in terms of
equality.

3
telegram/_inline/inlinekeyboardmarkup.py
View file

@ -36,6 +36,9 @@ class InlineKeyboardMarkup(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their size of :attr:`inline_keyboard` and all the buttons are equal.
.. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
`Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_
Args:
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
each represented by a list of InlineKeyboardButton objects.

2
telegram/_inline/inlinequeryresultarticle.py
View file

@ -31,6 +31,8 @@ if TYPE_CHECKING:
class InlineQueryResultArticle(InlineQueryResult):
"""This object represents a Telegram InlineQueryResultArticle.
.. seealso:: `Inline Example <examples.inlinebot.html>`_
Args:
id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
title (:obj:`str`): Title of the result.

2
telegram/_inline/inputtextmessagecontent.py
View file

@ -33,6 +33,8 @@ class InputTextMessageContent(InputMessageContent):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`message_text` is equal.
.. seealso:: `Inline Example <examples.inlinebot.html>`_
Args:
message_text (:obj:`str`): Text of the message to be sent,
1-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters after entities

2
telegram/_keyboardbuttonpolltype.py
View file

@ -29,6 +29,8 @@ class KeyboardButtonPollType(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`type` is equal.
.. seealso:: `Pollbot Example <examples.pollbot.html>`_
Attributes:
type (:obj:`str`): Optional. If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be
allowed to create only polls in the quiz mode. If :tg-const:`telegram.Poll.REGULAR` is

2
telegram/_payment/labeledprice.py
View file

@ -29,6 +29,8 @@ class LabeledPrice(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`label` and :attr:`amount` are equal.
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
Args:
label (:obj:`str`): Portion label.
amount (:obj:`int`): Price of the product in the smallest units of the currency (integer,

2
telegram/_payment/shippingoption.py
View file

@ -33,6 +33,8 @@ class ShippingOption(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`id` is equal.
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
Args:
id (:obj:`str`): Shipping option identifier.
title (:obj:`str`): Option title.

2
telegram/_poll.py
View file

@ -112,6 +112,8 @@ class Poll(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`id` is equal.
.. seealso:: `Pollbot Example <examples.pollbot.html>`_
Args:
id (:obj:`str`): Unique poll identifier.
question (:obj:`str`): Poll question, 1-300 characters.

4
telegram/_user.py
View file

@ -1463,7 +1463,7 @@ class User(TelegramObject):
For the documentation of the arguments, please see
:meth:`telegram.Bot.set_chat_menu_button`.
..seealso:: :meth:`get_menu_button`
.. seealso:: :meth:`get_menu_button`
.. versionadded:: 20.0
@ -1496,7 +1496,7 @@ class User(TelegramObject):
For the documentation of the arguments, please see
:meth:`telegram.Bot.get_chat_menu_button`.
..seealso:: :meth:`set_menu_button`
.. seealso:: :meth:`set_menu_button`
.. versionadded:: 20.0

2
telegram/_webappdata.py
View file

@ -29,6 +29,8 @@ class WebAppData(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`data` and :attr:`button_text` are equal.
.. seealso:: `Webappbot Example <examples.webappbot.html>`_
.. versionadded:: 20.0
Args:

2
telegram/_webappinfo.py
View file

@ -30,6 +30,8 @@ class WebAppInfo(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`url` are equal.
.. seealso:: `Webappbot Example <examples.webappbot.html>`_
.. versionadded:: 20.0
Args:

5
telegram/ext/_application.py
View file

@ -708,7 +708,8 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
listen (:obj:`str`, optional): IP-Address to listen on. Defaults to
`127.0.0.1 <https://en.wikipedia.org/wiki/Localhost>`_.
port (:obj:`int`, optional): Port the bot should be listening on. Must be one of
:attr:`telegram.constants.SUPPORTED_WEBHOOK_PORTS`. Defaults to ``80``.
:attr:`telegram.constants.SUPPORTED_WEBHOOK_PORTS` unless the bot is running
behind a proxy. Defaults to ``80``.
url_path (:obj:`str`, optional): Path inside url. Defaults to `` '' ``
cert (:class:`pathlib.Path` | :obj:`str`, optional): Path to the SSL certificate file.
key (:class:`pathlib.Path` | :obj:`str`, optional): Path to the SSL key file.
@ -1417,6 +1418,8 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
Note:
Attempts to add the same callback multiple times will be ignored.
.. seealso:: `Errorhandler Example <examples.errorhandlerbot.py>`_
Args:
callback (:term:`coroutine function`): The callback function for this error handler.
Will be called when an error is raised. Callback signature::

5
telegram/ext/_callbackdatacache.py
View file

@ -94,6 +94,11 @@ class CallbackDataCache:
sent via inline mode.
If necessary, will drop the least recently used items.
.. seealso:: :attr:`telegram.ext.ExtBot.callback_data_cache`,
`Arbitrary callback_data <https://github.com/python-telegram-bot/
python-telegram-bot/wiki/Arbitrary-callback_data>`_,
Arbitrary Callback Data Example <examples.arbitrarycallbackdatabot.html>
.. versionadded:: 13.6
Args:

6
telegram/ext/_chatmemberhandler.py
View file

@ -31,12 +31,14 @@ RT = TypeVar("RT")
class ChatMemberHandler(BaseHandler[Update, CCT]):
"""BaseHandler class to handle Telegram updates that contain a chat member update.
.. versionadded:: 13.4
Warning:
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
.. seealso:: `Chat Member Example <examples.chatmemberbot.html>`_
.. versionadded:: 13.4
Args:
callback (:term:`coroutine function`): The callback function for this handler. Will be
called when :meth:`check_update` has determined that an update should be processed by

2
telegram/ext/_contexttypes.py
View file

@ -33,6 +33,8 @@ class ContextTypes(Generic[CCT, UD, CD, BD]):
Convenience class to gather customizable types of the :class:`telegram.ext.CallbackContext`
interface.
.. seealso:: `ContextTypes Example <examples.contexttypesbot.html>`_
.. versionadded:: 13.6
Args:

7
telegram/ext/_conversationhandler.py
View file

@ -184,7 +184,12 @@ class ConversationHandler(BaseHandler[Update, CCT]):
states to continue the parent conversation after the child conversation has ended or even
map a state to :attr:`END` to end the *parent* conversation from within the child
conversation. For an example on nested :class:`ConversationHandler` s, see
:any:`examples.conversationbot`.
:any:`examples.nestedconversationbot`.
.. seealso:: `Conversation Example <examples.conversationbot.html>`_,
`Conversation Example 2 <examples.conversationbot2.html>`_,
`Nested Conversation Example <examples.nestedconversationbot.html>`_,
`Persistent Conversation Example <examples.persistentconversationbot.html>`_
Args:
entry_points (List[:class:`telegram.ext.BaseHandler`]): A list of :obj:`BaseHandler`

4
telegram/ext/_extbot.py
View file

@ -118,6 +118,10 @@ class ExtBot(Bot, Generic[RLARGS]):
* The method :meth:`~telegram.Bot.get_updates` is the only method that does not have the
additional argument, as this method will never be rate limited.
.. seealso:: `Arbitrary Callback Example <examples.arbitrarycallbackdatabot.html>`_,
`Arbitrary callback_data <https://github.com/python-telegram-bot/
python-telegram-bot/wiki/Arbitrary-callback_data>`_
.. versionadded:: 13.6
Args:

2
telegram/ext/_inlinequeryhandler.py
View file

@ -46,6 +46,8 @@ class InlineQueryHandler(BaseHandler[Update, CCT]):
chats and may not be set for inline queries coming from third-party clients. These
updates won't be handled, if :attr:`chat_types` is passed.
.. seealso:: `Inlinebot Example <examples.inlinebot.html>`_
Args:
callback (:term:`coroutine function`): The callback function for this handler. Will be
called when :meth:`check_update` has determined that an update should be processed by

16
telegram/ext/_jobqueue.py
View file

@ -40,6 +40,12 @@ class JobQueue:
"""This class allows you to periodically perform tasks with the bot. It is a convenience
wrapper for the APScheduler library.
.. seealso:: :attr:`telegram.ext.Application.job_queue`,
:attr:`telegram.ext.CallbackContext.job_queue`,
`Timerbot Example <examples.timerbot.html>`_,
`Job Queue <https://github.com/python-telegram-bot/
python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`_
Attributes:
scheduler (:class:`apscheduler.schedulers.asyncio.AsyncIOScheduler`): The scheduler.
@ -47,7 +53,6 @@ class JobQueue:
Uses :class:`~apscheduler.schedulers.asyncio.AsyncIOScheduler` instead of
:class:`~apscheduler.schedulers.background.BackgroundScheduler`
"""
__slots__ = ("_application", "scheduler", "_executor")
@ -567,7 +572,11 @@ class JobQueue:
await asyncio.sleep(0.01)
def jobs(self) -> Tuple["Job", ...]:
"""Returns a tuple of all *scheduled* jobs that are currently in the :class:`JobQueue`."""
"""Returns a tuple of all *scheduled* jobs that are currently in the :class:`JobQueue`.
Returns:
Tuple[:class:`Job`]: Tuple of all *scheduled* jobs.
"""
return tuple(
Job._from_aps_job(job) # pylint: disable=protected-access
for job in self.scheduler.get_jobs()
@ -576,6 +585,9 @@ class JobQueue:
def get_jobs_by_name(self, name: str) -> Tuple["Job", ...]:
"""Returns a tuple of all *pending/scheduled* jobs with the given name that are currently
in the :class:`JobQueue`.
Returns:
Tuple[:class:`Job`]: Tuple of all *pending* or *scheduled* jobs matching the name.
"""
return tuple(job for job in self.jobs() if job.name == name)

2
telegram/ext/_pollanswerhandler.py
View file

@ -32,6 +32,8 @@ class PollAnswerHandler(BaseHandler[Update, CCT]):
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
.. seealso:: `Pollbot EXample <examples.pollbot.html>`_
Args:
callback (:term:`coroutine function`): The callback function for this handler. Will be
called when :meth:`check_update` has determined that an update should be processed by

2
telegram/ext/_pollhandler.py
View file

@ -32,6 +32,8 @@ class PollHandler(BaseHandler[Update, CCT]):
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
.. seealso:: `Pollbot Example <examples.pollbot.html>`_
Args:
callback (:term:`coroutine function`): The callback function for this handler. Will be
called when :meth:`check_update` has determined that an update should be processed by

2
telegram/ext/_precheckoutqueryhandler.py
View file

@ -31,6 +31,8 @@ class PreCheckoutQueryHandler(BaseHandler[Update, CCT]):
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
Args:
callback (:term:`coroutine function`): The callback function for this handler. Will be
called when :meth:`check_update` has determined that an update should be processed by

2
telegram/ext/_shippingqueryhandler.py
View file

@ -31,6 +31,8 @@ class ShippingQueryHandler(BaseHandler[Update, CCT]):
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
Args:
callback (:term:`coroutine function`): The callback function for this handler. Will be
called when :meth:`check_update` has determined that an update should be processed by

3
telegram/ext/_updater.py
View file

@ -389,7 +389,8 @@ class Updater(AbstractAsyncContextManager):
listen (:obj:`str`, optional): IP-Address to listen on. Defaults to
`127.0.0.1 <https://en.wikipedia.org/wiki/Localhost>`_.
port (:obj:`int`, optional): Port the bot should be listening on. Must be one of
:attr:`telegram.constants.SUPPORTED_WEBHOOK_PORTS`. Defaults to ``80``.
:attr:`telegram.constants.SUPPORTED_WEBHOOK_PORTS` unless the bot is running
behind a proxy. Defaults to ``80``.
url_path (:obj:`str`, optional): Path inside url (http(s)://listen:port/<url_path>).
Defaults to ``''``.
cert (:class:`pathlib.Path` | :obj:`str`, optional): Path to the SSL certificate file.

2
telegram/helpers.py
View file

@ -146,6 +146,8 @@ def create_deep_linked_url(bot_username: str, payload: str = None, group: bool =
Examples:
``create_deep_linked_url(bot.get_me().username, "some-params")``
.. seealso:: `Deeplinking Example <examples.deeplinking.html>`_
Args:
bot_username (:obj:`str`): The username to link to
payload (:obj:`str`, optional): Parameters to encode in the created URL