Documentation Improvements

.github/CONTRIBUTING.rst

@@ -167,6 +167,7 @@ Feel free to copy (parts of) the checklist to the PR description to remind you o
 **If the PR contains API changes (otherwise, you can ignore this passage)**
 
 - Checked the Bot API specific sections of the `Stability Policy <https://docs.python-telegram-bot.org/stability_policy.html>`_
+- Created a PR to remove functionality deprecated in the previous Bot API release (`see here <https://docs.python-telegram-bot.org/en/stable/stability_policy.html#case-2>`_)
 
 -  New classes:
 

.github/pull_request_template.md

@@ -1,6 +1,6 @@
 <!--
 Hey! You're PRing? Cool!
 Please be sure to check out our contribution guide (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst).
-Especially, please have a look at the check list for PRs (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst#checklist-for-prs). Feel free to copy (parts of) the checklist to the PR description to remind you or the maintainers of open points or if you have questions on anything.
+Especially, please have a look at the check list for PRs (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst#check-list-for-prs). Feel free to copy (parts of) the checklist to the PR description to remind you or the maintainers of open points or if you have questions on anything.
 -->
 

AUTHORS.rst

@@ -21,6 +21,7 @@ Contributors
 
 The following wonderful people contributed directly or indirectly to this project:
 
+- `Abdelrahman <https://github.com/aelkheir>`_
 - `Abshar <https://github.com/abxhr>`_
 - `Alateas <https://github.com/alateas>`_
 - `Ales Dokshanin <https://github.com/alesdokshanin>`_

README.rst

@@ -30,7 +30,7 @@
    :target: https://www.gnu.org/licenses/lgpl-3.0.html
    :alt: LGPLv3 License
 
-.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg
+.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/Unit%20Tests/badge.svg
    :target: https://github.com/python-telegram-bot/python-telegram-bot/
    :alt: Github Actions workflow
 

README_RAW.rst

@@ -30,7 +30,7 @@
    :target: https://www.gnu.org/licenses/lgpl-3.0.html
    :alt: LGPLv3 License
 
-.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg
+.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/Unit%20Tests/badge.svg
    :target: https://github.com/python-telegram-bot/python-telegram-bot/
    :alt: Github Actions workflow
 

docs/auxil/kwargs_insertion.py

@@ -42,7 +42,7 @@
 ]
 write_timeout_sub = [":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`", "``20``"]
 read_timeout_sub = [
-    ":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
+    ":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`",
     "``2``. :paramref:`timeout` will be added to this value",
 ]
 read_timeout_type = [":obj:`float` | :obj:`None`", ":obj:`float`"]

docs/requirements-docs.txt

@@ -1,7 +1,7 @@
 sphinx==7.2.5
 sphinx-pypi-upload
 furo==2023.8.19
-git+https://github.com/harshil21/furo-sphinx-search@01efc7be422d7dc02390aab9be68d6f5ce1a5618#egg=furo-sphinx-search
+git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1
 sphinx-paramlinks==0.6.0
 sphinxcontrib-mermaid==0.9.2
 sphinx-copybutton==0.5.2

docs/source/conf.py

@@ -23,7 +23,7 @@
 # The short X.Y version.
 version = "20.4"  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = "20.3"  # telegram.__version__
+release = "20.4"  # telegram.__version__
 
 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = "6.1.3"

docs/substitutions/global.rst

@@ -57,3 +57,5 @@
 .. |captionentitiesattr| replace:: Tuple of special entities that appear in the caption, which can be specified instead of ``parse_mode``.
 
 .. |datetime_localization| replace:: The default timezone of the bot is used for localization, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used.
+
+.. |post_methods_note| replace:: If you implement custom logic that implies that you will **not** be using :class:`~telegram.ext.Application`'s methods :meth:`~telegram.ext.Application.run_polling` or :meth:`~telegram.ext.Application.run_webhook` to run your application (like it's done in `Custom Webhook Bot Example <https://docs.python-telegram-bot.org/en/stable/examples.customwebhookbot.html>`__), the callback you set in this method **will not be called automatically**. So instead of setting a callback with this method, you have to explicitly ``await`` the function that you want to run at this stage of your application's life (in the `example mentioned above <https://docs.python-telegram-bot.org/en/stable/examples.customwebhookbot.html>`__, that would be in ``async with application`` context manager).

telegram/_messageentity.py

@@ -40,11 +40,13 @@ class MessageEntity(TelegramObject):
 
     Args:
         type (:obj:`str`): Type of the entity. Can be :attr:`MENTION` (@username),
-            :attr:`HASHTAG`, :attr:`BOT_COMMAND`,
-            :attr:`URL`, :attr:`EMAIL`, :attr:`PHONE_NUMBER`, :attr:`BOLD` (bold text),
-            :attr:`ITALIC` (italic text), :attr:`STRIKETHROUGH`, :attr:`SPOILER` (spoiler message),
-            :attr:`CODE` (monowidth string), :attr:`PRE` (monowidth block), :attr:`TEXT_LINK` (for
-            clickable text URLs), :attr:`TEXT_MENTION` (for users without usernames),
+            :attr:`HASHTAG` (#hashtag), :attr:`CASHTAG` ($USD), :attr:`BOT_COMMAND`
+            (/start@jobs_bot), :attr:`URL` (https://telegram.org),
+            :attr:`EMAIL` (do-not-reply@telegram.org), :attr:`PHONE_NUMBER` (+1-212-555-0123),
+            :attr:`BOLD` (**bold text**), :attr:`ITALIC` (*italic text*), :attr:`UNDERLINE`
+            (underlined text), :attr:`STRIKETHROUGH`, :attr:`SPOILER` (spoiler message),
+            :attr:`CODE` (monowidth string), :attr:`PRE` (monowidth block), :attr:`TEXT_LINK`
+            (for clickable text URLs), :attr:`TEXT_MENTION` (for users without usernames),
             :attr:`CUSTOM_EMOJI` (for inline custom emoji stickers).
 
             .. versionadded:: 20.0
@@ -64,11 +66,13 @@ class MessageEntity(TelegramObject):
             .. versionadded:: 20.0
     Attributes:
         type (:obj:`str`): Type of the entity. Can be :attr:`MENTION` (@username),
-            :attr:`HASHTAG`, :attr:`BOT_COMMAND`,
-            :attr:`URL`, :attr:`EMAIL`, :attr:`PHONE_NUMBER`, :attr:`BOLD` (bold text),
-            :attr:`ITALIC` (italic text), :attr:`STRIKETHROUGH`, :attr:`SPOILER` (spoiler message),
-            :attr:`CODE` (monowidth string), :attr:`PRE` (monowidth block), :attr:`TEXT_LINK` (for
-            clickable text URLs), :attr:`TEXT_MENTION` (for users without usernames),
+            :attr:`HASHTAG` (#hashtag), :attr:`CASHTAG` ($USD), :attr:`BOT_COMMAND`
+            (/start@jobs_bot), :attr:`URL` (https://telegram.org),
+            :attr:`EMAIL` (do-not-reply@telegram.org), :attr:`PHONE_NUMBER` (+1-212-555-0123),
+            :attr:`BOLD` (**bold text**), :attr:`ITALIC` (*italic text*), :attr:`UNDERLINE`
+            (underlined text), :attr:`STRIKETHROUGH`, :attr:`SPOILER` (spoiler message),
+            :attr:`CODE` (monowidth string), :attr:`PRE` (monowidth block), :attr:`TEXT_LINK`
+            (for clickable text URLs), :attr:`TEXT_MENTION` (for users without usernames),
             :attr:`CUSTOM_EMOJI` (for inline custom emoji stickers).
 
             .. versionadded:: 20.0

telegram/error.py

@@ -127,6 +127,9 @@ class NetworkError(TelegramError):
 
     Examples:
         :any:`Raw API Bot <examples.rawapibot>`
+
+    .. seealso::
+        :wiki:`Handling network errors <Handling-network-errors>`
     """
 
     __slots__ = ()
@@ -141,6 +144,9 @@ class BadRequest(NetworkError):
 class TimedOut(NetworkError):
     """Raised when a request took too long to finish.
 
+    .. seealso::
+        :wiki:`Handling network errors <Handling-network-errors>`
+
     Args:
         message (:obj:`str`, optional): Any additional information about the exception.
 

telegram/ext/_application.py

@@ -693,7 +693,7 @@ def run_polling(
         On unix, the app will also shut down on receiving the signals specified by
         :paramref:`stop_signals`.
 
-        The order of execution by `run_polling` is roughly as follows:
+        The order of execution by :meth:`run_polling` is roughly as follows:
 
         - :meth:`initialize`
         - :meth:`post_init`
@@ -708,11 +708,6 @@ def run_polling(
 
         .. include:: inclusions/application_run_tip.rst
 
-        .. seealso::
-            :meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown`
-            :meth:`telegram.ext.Updater.start_polling`, :meth:`telegram.ext.Updater.stop`,
-            :meth:`run_webhook`
-
         Args:
             poll_interval (:obj:`float`, optional): Time to wait between polling updates from
                 Telegram in seconds. Default is ``0.0``.
@@ -816,7 +811,7 @@ def run_webhook(
         ``https://listen:port/url_path``. Also calls :meth:`telegram.Bot.set_webhook` as
         required.
 
-        The order of execution by `run_webhook` is roughly as follows:
+        The order of execution by :meth:`run_webhook` is roughly as follows:
 
         - :meth:`initialize`
         - :meth:`post_init`
@@ -840,9 +835,7 @@ def run_webhook(
         .. include:: inclusions/application_run_tip.rst
 
         .. seealso::
-            :meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown`
-            :meth:`telegram.ext.Updater.start_webhook`, :meth:`telegram.ext.Updater.stop`,
-            :meth:`run_polling`, :wiki:`Webhooks`
+            :wiki:`Webhooks`
 
         Args:
             listen (:obj:`str`, optional): IP-Address to listen on. Defaults to

telegram/ext/_applicationbuilder.py

@@ -473,6 +473,8 @@ def connection_pool_size(self: BuilderType, connection_pool_size: int) -> Builde
 
         .. include:: inclusions/pool_size_tip.rst
 
+        .. seealso:: :meth:`get_updates_connection_pool_size`
+
         Args:
             connection_pool_size (:obj:`int`): The size of the connection pool.
 
@@ -487,6 +489,9 @@ def proxy_url(self: BuilderType, proxy_url: str) -> BuilderType:
         """Sets the proxy for the :paramref:`~telegram.request.HTTPXRequest.proxy_url`
         parameter of :attr:`telegram.Bot.request`. Defaults to :obj:`None`.
 
+
+        .. seealso:: :meth:`get_updates_proxy_url`
+
         Args:
             proxy_url (:obj:`str`): The URL to the proxy server. See
                 :paramref:`telegram.request.HTTPXRequest.proxy_url` for more information.
@@ -503,6 +508,8 @@ def connect_timeout(self: BuilderType, connect_timeout: Optional[float]) -> Buil
         :paramref:`~telegram.request.HTTPXRequest.connect_timeout` parameter of
         :attr:`telegram.Bot.request`. Defaults to ``5.0``.
 
+        .. seealso:: :meth:`get_updates_connect_timeout`
+
         Args:
             connect_timeout (:obj:`float`): See
                 :paramref:`telegram.request.HTTPXRequest.connect_timeout` for more information.
@@ -519,6 +526,8 @@ def read_timeout(self: BuilderType, read_timeout: Optional[float]) -> BuilderTyp
         :paramref:`~telegram.request.HTTPXRequest.read_timeout` parameter of
         :attr:`telegram.Bot.request`. Defaults to ``5.0``.
 
+        .. seealso:: :meth:`get_updates_read_timeout`
+
         Args:
             read_timeout (:obj:`float`): See
                 :paramref:`telegram.request.HTTPXRequest.read_timeout` for more information.
@@ -535,6 +544,8 @@ def write_timeout(self: BuilderType, write_timeout: Optional[float]) -> BuilderT
         :paramref:`~telegram.request.HTTPXRequest.write_timeout` parameter of
         :attr:`telegram.Bot.request`. Defaults to ``5.0``.
 
+        .. seealso:: :meth:`get_updates_write_timeout`
+
         Args:
             write_timeout (:obj:`float`): See
                 :paramref:`telegram.request.HTTPXRequest.write_timeout` for more information.
@@ -553,6 +564,8 @@ def pool_timeout(self: BuilderType, pool_timeout: Optional[float]) -> BuilderTyp
 
         .. include:: inclusions/pool_size_tip.rst
 
+        .. seealso:: :meth:`get_updates_pool_timeout`
+
         Args:
             pool_timeout (:obj:`float`): See
                 :paramref:`telegram.request.HTTPXRequest.pool_timeout` for more information.
@@ -629,6 +642,8 @@ def get_updates_connection_pool_size(
         :paramref:`telegram.request.HTTPXRequest.connection_pool_size` parameter which is used
         for the :meth:`telegram.Bot.get_updates` request. Defaults to ``1``.
 
+        .. seealso:: :meth:`connection_pool_size`
+
         Args:
             get_updates_connection_pool_size (:obj:`int`): The size of the connection pool.
 
@@ -643,6 +658,9 @@ def get_updates_proxy_url(self: BuilderType, get_updates_proxy_url: str) -> Buil
         """Sets the proxy for the :paramref:`telegram.request.HTTPXRequest.proxy_url`
         parameter which is used for :meth:`telegram.Bot.get_updates`. Defaults to :obj:`None`.
 
+
+        .. seealso:: :meth:`proxy_url`
+
         Args:
             get_updates_proxy_url (:obj:`str`): The URL to the proxy server. See
                 :paramref:`telegram.request.HTTPXRequest.proxy_url` for more information.
@@ -661,6 +679,8 @@ def get_updates_connect_timeout(
         :paramref:`telegram.request.HTTPXRequest.connect_timeout` parameter which is used for
         the :meth:`telegram.Bot.get_updates` request. Defaults to ``5.0``.
 
+        .. seealso:: :meth:`connect_timeout`
+
         Args:
             get_updates_connect_timeout (:obj:`float`): See
                 :paramref:`telegram.request.HTTPXRequest.connect_timeout` for more information.
@@ -679,6 +699,8 @@ def get_updates_read_timeout(
         :paramref:`telegram.request.HTTPXRequest.read_timeout` parameter which is used for the
         :meth:`telegram.Bot.get_updates` request. Defaults to ``5.0``.
 
+        .. seealso:: :meth:`read_timeout`
+
         Args:
             get_updates_read_timeout (:obj:`float`): See
                 :paramref:`telegram.request.HTTPXRequest.read_timeout` for more information.
@@ -697,6 +719,8 @@ def get_updates_write_timeout(
         :paramref:`telegram.request.HTTPXRequest.write_timeout` parameter which is used for
         the :meth:`telegram.Bot.get_updates` request. Defaults to ``5.0``.
 
+        .. seealso:: :meth:`write_timeout`
+
         Args:
             get_updates_write_timeout (:obj:`float`): See
                 :paramref:`telegram.request.HTTPXRequest.write_timeout` for more information.
@@ -715,6 +739,8 @@ def get_updates_pool_timeout(
         :paramref:`~telegram.request.HTTPXRequest.pool_timeout` parameter which is used for the
         :meth:`telegram.Bot.get_updates` request. Defaults to ``1.0``.
 
+        .. seealso:: :meth:`pool_timeout`
+
         Args:
             get_updates_pool_timeout (:obj:`float`): See
                 :paramref:`telegram.request.HTTPXRequest.pool_timeout` for more information.
@@ -1099,6 +1125,9 @@ async def post_init(application: Application) -> None:
 
                 application = Application.builder().token("TOKEN").post_init(post_init).build()
 
+        Note:
+            |post_methods_note|
+
         .. seealso:: :meth:`post_stop`, :meth:`post_shutdown`
 
         Args:
@@ -1137,6 +1166,9 @@ async def post_shutdown(application: Application) -> None:
                                         .post_shutdown(post_shutdown)
                                         .build()
 
+        Note:
+            |post_methods_note|
+
         .. seealso:: :meth:`post_init`, :meth:`post_stop`
 
         Args:
@@ -1177,6 +1209,9 @@ async def post_stop(application: Application) -> None:
                                         .post_stop(post_stop)
                                         .build()
 
+        Note:
+            |post_methods_note|
+
         .. seealso:: :meth:`post_init`, :meth:`post_shutdown`
 
         Args:

telegram/ext/_callbackqueryhandler.py

@@ -34,7 +34,7 @@
 
 
 class CallbackQueryHandler(BaseHandler[Update, CCT]):
-    """BaseHandler class to handle Telegram
+    """Handler class to handle Telegram
     :attr:`callback queries <telegram.Update.callback_query>`. Optionally based on a regex.
 
     Read the documentation of the :mod:`re` module for more information.

telegram/ext/_chatjoinrequesthandler.py

@@ -28,7 +28,7 @@
 
 
 class ChatJoinRequestHandler(BaseHandler[Update, CCT]):
-    """BaseHandler class to handle Telegram updates that contain
+    """Handler class to handle Telegram updates that contain
     :attr:`telegram.Update.chat_join_request`.
 
     Note:

telegram/ext/_chatmemberhandler.py

@@ -29,7 +29,7 @@
 
 
 class ChatMemberHandler(BaseHandler[Update, CCT]):
-    """BaseHandler class to handle Telegram updates that contain a chat member update.
+    """Handler class to handle Telegram updates that contain a chat member update.
 
     Warning:
         When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom

telegram/ext/_choseninlineresulthandler.py

@@ -33,7 +33,7 @@
 
 
 class ChosenInlineResultHandler(BaseHandler[Update, CCT]):
-    """BaseHandler class to handle Telegram updates that contain
+    """Handler class to handle Telegram updates that contain
     :attr:`telegram.Update.chosen_inline_result`.
 
     Warning:

telegram/ext/_commandhandler.py

@@ -34,7 +34,7 @@
 
 
 class CommandHandler(BaseHandler[Update, CCT]):
-    """BaseHandler class to handle Telegram commands.
+    """Handler class to handle Telegram commands.
 
     Commands are Telegram messages that start with ``/``, optionally followed by an ``@`` and the
     bot's name and/or some additional text. The handler will add a :obj:`list` to the
@@ -104,7 +104,7 @@ async def callback(update: Update, context: CallbackContext)
         commands (FrozenSet[:obj:`str`]): The set of commands this handler should listen for.
         callback (:term:`coroutine function`): The callback function for this handler.
         filters (:class:`telegram.ext.filters.BaseFilter`): Optional. Only allow updates with these
-            Filters.
+            filters.
         block (:obj:`bool`): Determines whether the return value of the callback should be
             awaited before processing the next handler in
             :meth:`telegram.ext.Application.process_update`.

telegram/ext/_messagehandler.py

@@ -33,7 +33,7 @@
 
 
 class MessageHandler(BaseHandler[Update, CCT]):
-    """BaseHandler class to handle Telegram messages. They might contain text, media or status
+    """Handler class to handle Telegram messages. They might contain text, media or status
     updates.
 
     Warning:

telegram/ext/_pollanswerhandler.py

@@ -25,7 +25,7 @@
 
 
 class PollAnswerHandler(BaseHandler[Update, CCT]):
-    """BaseHandler class to handle Telegram updates that contain a
+    """Handler class to handle Telegram updates that contain a
     :attr:`poll answer <telegram.Update.poll_answer>`.
 
     Warning:

telegram/ext/_pollhandler.py

@@ -25,7 +25,7 @@
 
 
 class PollHandler(BaseHandler[Update, CCT]):
-    """BaseHandler class to handle Telegram updates that contain a
+    """Handler class to handle Telegram updates that contain a
     :attr:`poll <telegram.Update.poll>`.
 
     Warning: