Auto insert raises block, fix Bot kwargs insertion regression (#5241)

python-telegram-bot · harshil21 · Jun 16, 2026 · May 7, 2026 · May 20, 2026 · May 20, 2026
commit 0c7053c8bdbda056e4f8e196a776ee7b0bd58a24
diff --git a/changes/unreleased/5240.iJXyH8RNWNNQpC47SfNHzw.toml b/changes/unreleased/5240.iJXyH8RNWNNQpC47SfNHzw.toml
@@ -1,5 +1,6 @@
 documentation = "Documentation Improvements"
-[[pull_requests]]
-uid = "5240"
-author_uids = ["harshil21"]
-closes_threads = []
+
+pull_requests = [
+    { uid = "5240", author_uids = ["harshil21", "Poolitzer"] },
+    { uid = "5241", author_uids = ["harshil21"] },
+]
diff --git a/docs/auxil/kwargs_insertion.py → docs/auxil/bot_insertion.py b/docs/auxil/kwargs_insertion.py → docs/auxil/bot_insertion.py
@@ -83,6 +83,13 @@
     "           ``2``.",
 ]
 
+RAISES_BLOCK = [
+    "Raises:",
+    "",
+    "    :class:`telegram.error.TelegramError`",
+    "",
+]
+
 
 def find_insert_pos_for_kwargs(lines: list[str]) -> int:
     """Finds the correct position to insert the keyword arguments and returns the index."""
@@ -92,6 +99,13 @@ def find_insert_pos_for_kwargs(lines: list[str]) -> int:
     return False
 
 
+def find_insert_pos_for_raises(lines: list[str]) -> int:
+    """Finds the correct position to insert the Raises block and returns the index."""
+    if "Raises:" in lines:
+        return -1  # Don't insert if there's already a Raises block
+    return len(lines)  # Insert at the end if there's no Raises block
+
+
 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)

diff --git a/docs/auxil/sphinx_hooks.py b/docs/auxil/sphinx_hooks.py
@@ -27,9 +27,11 @@
 import telegram
 import telegram.ext
 from docs.auxil.admonition_inserter import AdmonitionInserter
-from docs.auxil.kwargs_insertion import (
+from docs.auxil.bot_insertion import (
+    RAISES_BLOCK,
     check_timeout_and_api_kwargs_presence,
     find_insert_pos_for_kwargs,
+    find_insert_pos_for_raises,
     get_updates_read_timeout_addition,
     keyword_args,
     media_write_timeout_change,
@@ -84,8 +86,8 @@ def autodoc_process_docstring(
     app: Sphinx, what, name: str, obj: object, options, lines: list[str]
 ):
     """We do the following things:
-    1) Use this method to automatically insert the Keyword Args and "Shortcuts" admonitions
-       for the Bot methods.
+    1) Use this method to automatically insert the Keyword Args, "Shortcuts" admonitions,
+       and the Raises block, wherever applicable, for the Bot methods.
 
     2) Use this method to automatically insert "Returned in" admonition into classes
        that are returned from the Bot methods
@@ -101,13 +103,15 @@ def autodoc_process_docstring(
     """
 
     # 1) Insert the Keyword Args and "Shortcuts" admonitions for the Bot methods
-    method_name = name.rsplit(".", maxsplit=1)[0]
+    method_name = name.rsplit(".", maxsplit=1)[-1]
     if (
         name.startswith("telegram.Bot.")
         and what == "method"
         and method_name.islower()
         and check_timeout_and_api_kwargs_presence(obj)
     ):
+        # Logic for inserting keyword args into docstrings:
+        # -------------------------------------------------
         insert_index = find_insert_pos_for_kwargs(lines)
         if not insert_index:
             raise ValueError(
@@ -133,6 +137,16 @@ def autodoc_process_docstring(
             lines[insert_idx:insert_idx] = effective_insert
             insert_idx += len(effective_insert)
 
+        # Logic for inserting Raises:
+        # -------------------------------------------------
+        # We will only insert the Raises block if there isn't already one.
+
+        insert_index = find_insert_pos_for_raises(lines)
+        if insert_index != -1:
+            lines[insert_index:insert_index] = RAISES_BLOCK
+
+        # Logic for inserting "Shortcuts" admonition:
+        # -------------------------------------------
         ADMONITION_INSERTER.insert_admonitions(
             obj=typing.cast("collections.abc.Callable", obj),
             docstring_lines=lines,