Documentation Improvements (#3428, #3423, #3429, #3441, #3404, #3443)

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>
Co-authored-by: Eisberge <22561095+Eisberge@users.noreply.github.com>
Co-authored-by: Joshua Tang <joshuaystang@gmail.com>

AUTHORS.rst

@@ -74,6 +74,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `LRezende <https://github.com/lrezende>`_
 - `macrojames <https://github.com/macrojames>`_
 - `Matheus Lemos <https://github.com/mlemosf>`_
+- `Michael Dix <https://github.com/Eisberge>`_
 - `Michael Elovskikh <https://github.com/wronglink>`_
 - `miles <https://github.com/miles170>`_
 - `Mischa Krüger <https://github.com/Makman2>`_

CHANGES.rst

@@ -1,6 +1,7 @@
 =========
 Changelog
 =========
+
 Version 20.0b0
 ==============
 *Released 2022-12-15*
@@ -10,7 +11,7 @@ This is the technical changelog for version 20.0b0. More elaborate release notes
 Major Changes
 -------------
 
-- Make `TelegramObject` Immutable (`#3249`_)
+- Make ``TelegramObject`` Immutable (`#3249`_)
 
 Minor Changes, Documentation Improvements and CI
 ------------------------------------------------

README.rst

@@ -148,9 +148,9 @@ Optional Dependencies
 PTB can be installed with optional dependencies:
 
 * ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install python-telegram-bot[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server.
-* ``pip install python-telegram-bot[rate-limiter]`` installs ``aiolimiter~=1.0.0``. Use this, if you want to use ``telegram.ext.AIORateLimiter``.
-* ``pip install python-telegram-bot[webhooks]`` installs the `tornado~=6.2 <https://www.tornadoweb.org/en/stable/>`_ library. Use this, if you want to use ``telegram.ext.Updater.start_webhook``/``telegram.ext.Application.start_webhook``.
+* ``pip install python-telegram-bot[socks]`` installs `httpx[socks] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
+* ``pip install python-telegram-bot[rate-limiter]`` installs `aiolimiter~=1.0.0 <https://aiolimiter.readthedocs.io/en/stable/>`_. Use this, if you want to use ``telegram.ext.AIORateLimiter``.
+* ``pip install python-telegram-bot[webhooks]`` installs the `tornado~=6.2 <https://www.tornadoweb.org/en/stable/>`_ library. Use this, if you want to use ``telegram.ext.Updater.start_webhook``/``telegram.ext.Application.run_webhook``.
 * ``pip install python-telegram-bot[callback-data]`` installs the `cachetools~=5.2.0 <https://cachetools.readthedocs.io/en/latest/>`_ library. Use this, if you want to use `arbitrary callback_data <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_.
 * ``pip install python-telegram-bot[job-queue]`` installs the `APScheduler~=3.9.1 <https://apscheduler.readthedocs.io/en/3.x/>`_ library and enforces `pytz>=2018.6 <https://pypi.org/project/pytz/>`_, where ``pytz`` is a dependency of ``APScheduler``. Use this, if you want to use the ``telegram.ext.JobQueue``.
 

README_RAW.rst

@@ -34,7 +34,7 @@
    :target: https://github.com/python-telegram-bot/python-telegram-bot/
    :alt: Github Actions workflow
 
-.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
+.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
    :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
    :alt: Code coverage
 
@@ -149,7 +149,7 @@ Optional Dependencies
 PTB can be installed with optional dependencies:
 
 * ``pip install python-telegram-bot-raw[passport]`` installs the `cryptography>=3.0 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install python-telegram-bot-raw[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server.
+* ``pip install python-telegram-bot-raw[socks]`` installs `httpx[socks] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
 
 To install multiple optional dependencies, separate them by commas, e.g. ``pip install python-telegram-bot-raw[passport,socks]``.
 

docs/source/conf.py

@@ -44,11 +44,15 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
+    "sphinx.ext.extlinks",
     "sphinx_paramlinks",
     "sphinxcontrib.mermaid",
     "sphinx_search.extension",
 ]
 
+# For shorter links to Wiki in docstrings
+extlinks = {"wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s")}
+
 # Use intersphinx to reference the python builtin library docs
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),

telegram/_bot.py

@@ -150,10 +150,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
     .. seealso:: :attr:`telegram.ext.Application.bot`,
         :attr:`telegram.ext.CallbackContext.bot`,
         :attr:`telegram.ext.Updater.bot`,
-        `Your First Bot <https://github.com/\
-        python-telegram-bot/python-telegram-bot/wiki/Extensions-–-Your-first-Bot>`_,
-        `Builder Pattern <https://github.com/\
-        python-telegram-bot/python-telegram-bot/wiki/Builder-Pattern>`_
+        :wiki:`Your First Bot <Extensions-–-Your-first-Bot>`,
+        :wiki:`Builder Pattern <Builder-Pattern>`
 
     .. versionadded:: 13.2
         Objects of this class are comparable in terms of equality. Two objects of this class are
@@ -932,7 +930,8 @@ async def send_photo(
         """Use this method to send photos.
 
         .. seealso:: :meth:`telegram.Message.reply_photo`, :meth:`telegram.Chat.send_photo`,
-            :meth:`telegram.User.send_photo`
+            :meth:`telegram.User.send_photo`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -941,6 +940,11 @@ async def send_photo(
                 |fileinput|
                 Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
 
+                Caution:
+                    * The photo must be at most 10MB in size.
+                    * The photo's width and height must not exceed 10000 in total.
+                    * Width and height ratio must be at most 20.
+
                 .. versionchanged:: 13.2
                    Accept :obj:`bytes` as input.
 
@@ -1045,7 +1049,8 @@ async def send_audio(
         For sending voice messages, use the :meth:`send_voice` method instead.
 
         .. seealso:: :meth:`telegram.Message.reply_audio`, :meth:`telegram.Chat.send_audio`,
-            :meth:`telegram.User.send_audio`
+            :meth:`telegram.User.send_audio`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1170,7 +1175,8 @@ async def send_document(
         changed in the future.
 
         .. seealso:: :meth:`telegram.Message.reply_document`, :meth:`telegram.Chat.send_document`,
-            :meth:`telegram.User.send_document`
+            :meth:`telegram.User.send_document`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1283,7 +1289,8 @@ async def send_sticker(
         Use this method to send static ``.WEBP``, animated ``.TGS``, or video ``.WEBM`` stickers.
 
         .. seealso:: :meth:`telegram.Message.reply_sticker`, :meth:`telegram.Chat.send_sticker`,
-            :meth:`telegram.User.send_sticker`
+            :meth:`telegram.User.send_sticker`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1378,7 +1385,8 @@ async def send_video(
             changed by Telegram.
 
         .. seealso:: :meth:`telegram.Message.reply_video`, :meth:`telegram.Chat.send_video`,
-            :meth:`telegram.User.send_video`
+            :meth:`telegram.User.send_video`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1507,7 +1515,8 @@ async def send_video_note(
 
         .. seealso:: :meth:`telegram.Message.reply_video_note`,
             :meth:`telegram.Chat.send_video_note`,
-            :meth:`telegram.User.send_video_note`
+            :meth:`telegram.User.send_video_note`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1629,7 +1638,8 @@ async def send_animation(
 
         .. seealso:: :meth:`telegram.Message.reply_animation`,
             :meth:`telegram.Chat.send_animation`,
-            :meth:`telegram.User.send_animation`
+            :meth:`telegram.User.send_animation`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1758,7 +1768,8 @@ async def send_voice(
             sent as files.
 
         .. seealso:: :meth:`telegram.Message.reply_voice`, :meth:`telegram.Chat.send_voice`,
-            :meth:`telegram.User.send_voice`
+            :meth:`telegram.User.send_voice`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1859,7 +1870,8 @@ async def send_media_group(
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Sequence["MessageEntity"] = None,
     ) -> Tuple[Message, ...]:
-        """Use this method to send a group of photos or videos as an album.
+        """Use this method to send a group of photos, videos, documents or audios as an album.
+        Documents and audio files can be only grouped in an album with messages of the same type.
 
         .. versionchanged:: 20.0
             Returns a tuple instead of a list.
@@ -1871,7 +1883,8 @@ async def send_media_group(
 
         .. seealso:: :meth:`telegram.Message.reply_media_group`,
             :meth:`telegram.Chat.send_media_group`,
-            :meth:`telegram.User.send_media_group`
+            :meth:`telegram.User.send_media_group`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -2717,7 +2730,8 @@ async def answer_inline_query(
             :paramref:`telegram.InlineQuery.answer.auto_pagination` set to :obj:`True`, which will
             take care of passing the correct value.
 
-        .. seealso:: :meth:`telegram.InlineQuery.answer`
+        .. seealso:: :meth:`telegram.InlineQuery.answer`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             inline_query_id (:obj:`str`): Unique identifier for the answered query.
@@ -2865,7 +2879,8 @@ async def get_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`
+            :meth:`telegram.Voice.get_file`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` |         \
@@ -3364,7 +3379,8 @@ async def edit_message_media(
             |editreplymarkup|
 
         .. seealso:: :meth:`telegram.Message.edit_media`,
-            :meth:`telegram.CallbackQuery.edit_message_media`
+            :meth:`telegram.CallbackQuery.edit_message_media`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             media (:class:`telegram.InputMedia`): An object for a new media content
@@ -3619,9 +3635,9 @@ async def set_webhook(
                 integration.
             certificate (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`):
                 Upload your public key certificate so that the root
-                certificate in use can be checked. See our `self-signed guide <https://github.com/\
-                python-telegram-bot/python-telegram-bot/wiki/Webhooks#creating-a-self-signed-\
-                certificate-using-openssl>`_ for details. |uploadinputnopath|
+                certificate in use can be checked. See our :wiki:`self-signed guide\
+                <Webhooks#creating-a-self-signed-certificate-using-openssl>` for details.
+                |uploadinputnopath|
             ip_address (:obj:`str`, optional): The fixed IP address which will be used to send
                 webhook requests instead of the IP address resolved through DNS.
             max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS

telegram/_botcommand.py

@@ -41,8 +41,12 @@ class BotCommand(TelegramObject):
             :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters.
 
     Attributes:
-        command (:obj:`str`): Text of the command.
-        description (:obj:`str`): Description of the command.
+        command (:obj:`str`): Text of the command; :tg-const:`telegram.BotCommand.MIN_COMMAND`-
+            :tg-const:`telegram.BotCommand.MAX_COMMAND` characters. Can contain only lowercase
+            English letters, digits and underscores.
+        description (:obj:`str`): Description of the command;
+            :tg-const:`telegram.BotCommand.MIN_DESCRIPTION`-
+            :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters.
 
     """
 

telegram/_callbackquery.py

@@ -78,23 +78,27 @@ class CallbackQuery(TelegramObject):
         inline_message_id (:obj:`str`, optional): Identifier of the message sent via the bot in
             inline mode, that originated the query.
         game_short_name (:obj:`str`, optional): Short name of a Game to be returned, serves as
-            the unique identifier for the game
+            the unique identifier for the game.
 
     Attributes:
         id (:obj:`str`): Unique identifier for this query.
         from_user (:class:`telegram.User`): Sender.
         chat_instance (:obj:`str`): Global identifier, uniquely corresponding to the chat to which
-            the message with the callback button was sent.
+            the message with the callback button was sent. Useful for high scores in games.
         message (:class:`telegram.Message`): Optional. Message with the callback button that
-            originated the query.
+            originated the query. Note that message content and message date will not be available
+            if the message is too old.
         data (:obj:`str` | :obj:`object`): Optional. Data associated with the callback button.
+            Be aware that the message, which originated the query, can contain no callback buttons
+            with this data.
 
             Tip:
                 The value here is the same as the value passed in
                 :paramref:`telegram.InlineKeyboardButton.callback_data`.
         inline_message_id (:obj:`str`): Optional. Identifier of the message sent via the bot in
-                inline mode, that originated the query.
-        game_short_name (:obj:`str`): Optional. Short name of a Game to be returned.
+            inline mode, that originated the query.
+        game_short_name (:obj:`str`): Optional. Short name of a Game to be returned, serves as
+            the unique identifier for the game.
 
 
     """

telegram/_chatinvitelink.py

@@ -83,6 +83,7 @@ class ChatInviteLink(TelegramObject):
             :tg-const:`telegram.constants.ChatInviteLinkLimit.MIN_MEMBER_LIMIT`-
             :tg-const:`telegram.constants.ChatInviteLinkLimit.MAX_MEMBER_LIMIT`.
         name (:obj:`str`): Optional. Invite link name.
+            0-:tg-const:`telegram.constants.ChatInviteLinkLimit.NAME_LENGTH` characters.
 
             .. versionadded:: 13.8
         pending_join_request_count (:obj:`int`): Optional. Number of pending join requests

telegram/_chatlocation.py

@@ -40,10 +40,13 @@ class ChatLocation(TelegramObject):
             Can't be a live location.
         address (:obj:`str`): Location address;
             :tg-const:`telegram.ChatLocation.MIN_ADDRESS`-
-            :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner
+            :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner.
     Attributes:
         location (:class:`telegram.Location`): The location to which the supergroup is connected.
-        address (:obj:`str`): Location address, as defined by the chat owner
+            Can't be a live location.
+        address (:obj:`str`): Location address;
+            :tg-const:`telegram.ChatLocation.MIN_ADDRESS`-
+            :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner.
 
     """
 

telegram/_chatmember.py

@@ -45,7 +45,7 @@ class ChatMember(TelegramObject):
     considered equal, if their :attr:`user` and :attr:`status` are equal.
 
     Examples:
-         :any:`Chat Member Bot <examples.chatmemberbot>`
+        :any:`Chat Member Bot <examples.chatmemberbot>`
 
     .. versionchanged:: 20.0
 
@@ -65,7 +65,10 @@ class ChatMember(TelegramObject):
 
     Attributes:
         user (:class:`telegram.User`): Information about the user.
-        status (:obj:`str`): The member's status in the chat.
+        status (:obj:`str`): The member's status in the chat. Can be
+            :attr:`~telegram.ChatMember.ADMINISTRATOR`, :attr:`~telegram.ChatMember.OWNER`,
+            :attr:`~telegram.ChatMember.BANNED`, :attr:`~telegram.ChatMember.LEFT`,
+            :attr:`~telegram.ChatMember.MEMBER` or :attr:`~telegram.ChatMember.RESTRICTED`.
 
     """
 

telegram/_chatmemberupdated.py

@@ -65,7 +65,7 @@ class ChatMemberUpdated(TelegramObject):
         old_chat_member (:class:`telegram.ChatMember`): Previous information about the chat member.
         new_chat_member (:class:`telegram.ChatMember`): New information about the chat member.
         invite_link (:class:`telegram.ChatInviteLink`): Optional. Chat invite link, which was used
-            by the user to join the chat.
+            by the user to join the chat. For joining by invite link events only.
 
     """
 

telegram/_choseninlineresult.py

@@ -56,8 +56,11 @@ class ChosenInlineResult(TelegramObject):
     Attributes:
         result_id (:obj:`str`): The unique identifier for the result that was chosen.
         from_user (:class:`telegram.User`): The user that chose the result.
-        location (:class:`telegram.Location`): Optional. Sender location.
-        inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message.
+        location (:class:`telegram.Location`): Optional. Sender location, only for bots that
+            require user location.
+        inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message. Available
+            only if there is an inline keyboard attached to the message. Will be also received in
+            callback queries and can be used to edit the message.
         query (:obj:`str`): The query that was used to obtain the result.
 
     """