python-telegram-bot · Bibo-Joshi · Nov 15, 2022 · Aug 29, 2022 · Aug 29, 2022 · Aug 29, 2022
diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst
@@ -13,7 +13,7 @@ Setting things up
 
    .. code-block:: bash
 
-      $ git clone https://github.com/<your username>/python-telegram-bot --recursive
+      $ git clone https://github.com/<your username>/python-telegram-bot
       $ cd python-telegram-bot
 
 3. Add a track to the original repository:

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -21,6 +21,31 @@ python:
      - requirements: docs/requirements-docs.txt
 
 build:
-   os: ubuntu-20.04
+   os: ubuntu-22.04
    tools:
       python: "3"  # latest stable cpython version
+
+search:
+   ranking:  # bump up rank of commonly searched pages: (default: 0, values range from -10 to 10)
+      telegram.bot.html: 7
+      telegram.message.html: 3
+      telegram.update.html: 3
+      telegram.user.html: 2
+      telegram.chat.html: 2
+      telegram.ext.application.html: 3
+      telegram.ext.filters.html: 3
+      telegram.ext.callbackcontext.html: 2
+      telegram.ext.inlinekeyboardbutton.html: 1
+
+      telegram.passport*.html: -7
+
+   ignore:
+      - changelog.html
+      - coc.html
+      - bot_methods.html#
+      - bot_methods.html
+      # Defaults
+      - search.html
+      - search/index.html
+      - 404.html
+      - 404/index.html'
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
@@ -1,5 +1,6 @@
 sphinx==5.3.0
 sphinx-pypi-upload
 furo==2022.9.29
+git+https://github.com/harshil21/furo-sphinx-search@be5cfa221a01f6e259bb2bb1f76d6ede7ffc1f11#egg=furo-sphinx-search
 sphinx-paramlinks==0.5.4
 sphinxcontrib-mermaid==0.7.1
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -5,7 +5,7 @@
 import sys
 from enum import Enum
 from pathlib import Path
-from typing import Tuple
+from typing import List, Tuple
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -34,7 +34,7 @@
 release = "20.0a4"  # telegram.__version__
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = "4.5.0"
+needs_sphinx = "5.1.1"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -46,6 +46,7 @@
     "sphinx.ext.linkcode",
     "sphinx_paramlinks",
     "sphinxcontrib.mermaid",
+    "sphinx_search.extension",
 ]
 
 # Use intersphinx to reference the python builtin library docs
@@ -215,11 +216,9 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-html_css_files = [
-    "style_external_link.css",
-    "style_mermaid_diagrams.css",
-]
-html_permalinks_icon = "¶"  # Furo's default permalink icon is `#`` which doesn't look great imo.
+html_css_files = ["style_external_link.css", "style_mermaid_diagrams.css"]
+
+html_permalinks_icon = "¶"  # Furo's default permalink icon is `#` which doesn't look great imo.
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = "python-telegram-bot-doc"
@@ -260,6 +259,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentation", [author], 1)]
 
+# rtd_sphinx_search_file_type = "un-minified"  # Configuration for furo-sphinx-search
 
 # -- Options for Texinfo output -------------------------------------------
 
@@ -378,12 +378,98 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
 file_root = Path(inspect.getsourcefile(telegram)).parent.parent.resolve()
 import telegram.ext  # Needed for checking if an object is a BaseFilter
 
+keyword_args = [
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to {read_timeout}.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: {read_timeout_type}, optional",
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to {write_timeout}.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: :obj:`float` | :obj:`None`, optional",
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: :obj:`float` | :obj:`None`, optional",
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: :obj:`float` | :obj:`None`, optional",
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: Arbitrary keyword arguments to be passed to the Telegram API.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: :obj:`dict`, optional",
+    "",
+]
 
-def autodoc_process_docstring(app: Sphinx, what, name: str, obj: object, options, lines):
-    """We misuse this autodoc hook to get the file names & line numbers because we have access
-    to the actual object here.
+write_timeout_sub = [":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`", "``20``"]
+read_timeout_sub = [
+    ":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
+    "``2``. :paramref:`timeout` will be added to this value",
+]
+read_timeout_type = [":obj:`float` | :obj:`None`", ":obj:`float`"]
+
+
+def find_insert_pos(lines: List[str]) -> int:
+    """Finds the correct position to insert the keyword arguments and returns the index."""
+    for idx, value in reversed(list(enumerate(lines))):  # reversed since :returns: is at the end
+        if value.startswith(":returns:"):
+            return idx
+    else:
+        return False
+
+
+def is_write_timeout_20(obj: object) -> int:
+    """inspects the default value of write_timeout parameter of the bot method."""
+    sig = inspect.signature(obj)
+    return 1 if (sig.parameters["write_timeout"].default == 20) else 0
+
+
+def check_timeout_and_api_kwargs_presence(obj: object) -> int:
+    """Checks if the method has timeout and api_kwargs keyword only parameters."""
+    sig = inspect.signature(obj)
+    params_to_check = (
+        "read_timeout",
+        "write_timeout",
+        "connect_timeout",
+        "pool_timeout",
+        "api_kwargs",
+    )
+    return all(
+        param in sig.parameters and sig.parameters[param].kind == inspect.Parameter.KEYWORD_ONLY
+        for param in params_to_check
+    )
+
+
+def autodoc_process_docstring(
+    app: Sphinx, what, name: str, obj: object, options, lines: List[str]
+):
+    """We do two things:
+    1) Use this method to automatically insert the Keyword Args for the Bot methods.
+
+    2) Misuse this autodoc hook to get the file names & line numbers because we have access
+       to the actual object here.
     """
-    # Ce can't properly handle ordinary attributes.
+    # 1) Insert the Keyword Args for the Bot methods
+    method_name = name.split(".")[-1]
+    if (
+        name.startswith("telegram.Bot.")
+        and what == "method"
+        and method_name.islower()
+        and check_timeout_and_api_kwargs_presence(obj)
+    ):
+        insert_index = find_insert_pos(lines)
+        if not insert_index:
+            raise ValueError(
+                f"Couldn't find the correct position to insert the keyword args for {obj}."
+            )
+
+        long_write_timeout = is_write_timeout_20(obj)
+        get_updates_sub = 1 if (method_name == "get_updates") else 0
+        # The below can be done in 1 line with itertools.chain, but this must be modified in-place
+        for i in range(insert_index, insert_index + len(keyword_args)):
+            lines.insert(
+                i,
+                keyword_args[i - insert_index].format(
+                    method=method_name,
+                    write_timeout=write_timeout_sub[long_write_timeout],
+                    read_timeout=read_timeout_sub[get_updates_sub],
+                    read_timeout_type=read_timeout_type[get_updates_sub],
+                ),
+            )
+
+    # 2) Get the file names & line numbers
+    # We can't properly handle ordinary attributes.
     # In linkcode_resolve we'll resolve to the `__init__` or module instead
     if what == "attribute":
         return

diff --git a/docs/source/inclusions/application_run_tip.rst b/docs/source/inclusions/application_run_tip.rst
@@ -0,0 +1,7 @@
+.. tip::
+    When combining ``python-telegram-bot`` with other :mod:`asyncio` based frameworks, using this
+    method is likely not the best choice, as it blocks the event loop until it receives a stop
+    signal as described above.
+    Instead, you can manually call the methods listed below to start and shut down the application
+    and the :attr:`~telegram.ext.Application.updater`.
+    Keeping the event loop running and listening for a stop signal is then up to you.
diff --git a/docs/source/inclusions/bot_methods.rst b/docs/source/inclusions/bot_methods.rst
@@ -290,6 +290,10 @@
     :align: left
     :widths: 1 4
 
+    * - :attr:`~telegram.Bot.base_file_url`
+      - Telegram Bot API file URL
+    * - :attr:`~telegram.Bot.base_url`
+      - Telegram Bot API service URL
     * - :attr:`~telegram.Bot.bot`
       - The user instance of the bot as returned by :meth:`~telegram.Bot.get_me`
     * - :attr:`~telegram.Bot.can_join_groups`
@@ -310,8 +314,12 @@
       - The username of the bot, without leading ``@``
     * - :attr:`~telegram.Bot.link`
       - The t.me link of the bot
+    * - :attr:`~telegram.Bot.private_key`
+      - Deserialized private key for decryption of telegram passport data
     * - :attr:`~telegram.Bot.supports_inline_queries`
       - Whether the bot supports inline queries
+    * - :attr:`~telegram.Bot.token`
+      - Bot's unique authentication token
 
 .. raw:: html
 

diff --git a/docs/source/telegram.at-tree.rst b/docs/source/telegram.at-tree.rst
@@ -0,0 +1,82 @@
+Available Types
+---------------
+
+.. toctree::
+
+    telegram.animation
+    telegram.audio
+    telegram.botcommand
+    telegram.botcommandscope
+    telegram.botcommandscopeallchatadministrators
+    telegram.botcommandscopeallgroupchats
+    telegram.botcommandscopeallprivatechats
+    telegram.botcommandscopechat
+    telegram.botcommandscopechatadministrators
+    telegram.botcommandscopechatmember
+    telegram.botcommandscopedefault
+    telegram.callbackquery
+    telegram.chat
+    telegram.chatadministratorrights
+    telegram.chatinvitelink
+    telegram.chatjoinrequest
+    telegram.chatlocation
+    telegram.chatmember
+    telegram.chatmemberadministrator
+    telegram.chatmemberbanned
+    telegram.chatmemberleft
+    telegram.chatmembermember
+    telegram.chatmemberowner
+    telegram.chatmemberrestricted
+    telegram.chatmemberupdated
+    telegram.chatpermissions
+    telegram.chatphoto
+    telegram.contact
+    telegram.dice
+    telegram.document
+    telegram.file
+    telegram.forcereply
+    telegram.inlinekeyboardbutton
+    telegram.inlinekeyboardmarkup
+    telegram.inputfile
+    telegram.inputmedia
+    telegram.inputmediaanimation
+    telegram.inputmediaaudio
+    telegram.inputmediadocument
+    telegram.inputmediaphoto
+    telegram.inputmediavideo
+    telegram.keyboardbutton
+    telegram.keyboardbuttonpolltype
+    telegram.location
+    telegram.loginurl
+    telegram.menubutton
+    telegram.menubuttoncommands
+    telegram.menubuttondefault
+    telegram.menubuttonwebapp
+    telegram.message
+    telegram.messageautodeletetimerchanged
+    telegram.messageentity
+    telegram.messageid
+    telegram.photosize
+    telegram.poll
+    telegram.pollanswer
+    telegram.polloption
+    telegram.proximityalerttriggered
+    telegram.replykeyboardmarkup
+    telegram.replykeyboardremove
+    telegram.sentwebappmessage
+    telegram.telegramobject
+    telegram.update
+    telegram.user
+    telegram.userprofilephotos
+    telegram.venue
+    telegram.video
+    telegram.videochatended
+    telegram.videochatparticipantsinvited
+    telegram.videochatscheduled
+    telegram.videochatstarted
+    telegram.videonote
+    telegram.voice
+    telegram.webappdata
+    telegram.webappinfo
+    telegram.webhookinfo
+
diff --git a/docs/source/telegram.ext.rst b/docs/source/telegram.ext.rst
@@ -2,6 +2,7 @@ telegram.ext package
 ====================
 
 .. toctree::
+    :titlesonly:
 
     telegram.ext.application
     telegram.ext.applicationbuilder