Bump version to v21.1.1

Fix Bug With Parameter message_thread_id of Message.reply_* (#4207 )
Remove Deprecation Warning in JobQueue.run_daily (#4206 )
2026-06-19 15:45:13 +00:00 · 2024-04-15 17:00:17 +02:00 · 2024-04-15 16:49:36 +02:00 · 2024-04-14 14:14:45 +02:00 · 2024-04-13 20:27:29 +02:00 · 2024-04-12 12:39:38 +02:00
522 changed files with 33971 additions and 14309 deletions
@@ -1,19 +0,0 @@
-version = 1
-
-test_patterns = ["tests/**"]
-
-exclude_patterns = [
-    "tests/**",
-    "docs/**",
-    "setup.py",
-    "setup-raw.py"
-]
-
-[[analyzers]]
-name = "python"
-enabled = true
-
-  [analyzers.meta]
-  runtime_version = "3.x.x"
-  max_line_length = 99
-  skip_doc_coverage = ["module", "magic", "init", "nonpublic"]
@@ -67,6 +67,7 @@ Here's how to make a one-off code change.
      $ git checkout -b your-branch-name

 3. **Make a commit to your feature branch**. Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made.
+   We also have a check-list for PRs `below`_.

   - You can refer to relevant issues in the commit message by writing, e.g., "#105".

@@ -80,7 +81,7 @@ Here's how to make a one-off code change.

   - The following exceptions to the above (Google's) style guides applies:

-        - Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
+     - Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.

   -  In addition, PTB uses some formatting/styling and linting tools in the pre-commit setup. Some of those tools also have command line tools that can help to run these tools outside of the pre-commit step. If you'd like to leverage that, please have a look at the `pre-commit config file`_ for an overview of which tools (and which versions of them) are used. For example, we use `Black`_ for code formatting. Plugins for Black exist for some `popular editors`_. You can use those instead of manually formatting everything.

@@ -121,11 +122,11 @@ Here's how to make a one-off code change.

   - When your reviewer has reviewed the code, you'll get a notification. You'll need to respond in two ways:

-       - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
+     - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".

-       - In order to keep the commit history intact, please avoid squashing or amending history and then force-pushing to the PR. Reviewers often want to look at individual commits.
+     - In order to keep the commit history intact, please avoid squashing or amending history and then force-pushing to the PR. Reviewers often want to look at individual commits.

-       - In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
+     - In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.

   - Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run:

@@ -150,6 +151,52 @@ Here's how to make a one-off code change.

 7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!

+Check-list for PRs
+------------------
+
+This checklist is a non-exhaustive reminder of things that should be done before a PR is merged, both for you as contributor and for the maintainers.
+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.
+
+- Added ``.. versionadded:: NEXT.VERSION``, ``.. versionchanged:: NEXT.VERSION`` or ``.. deprecated:: NEXT.VERSION`` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
+- Created new or adapted existing unit tests
+- Documented code changes according to the `CSI standard <https://standards.mousepawmedia.com/en/stable/csi.html>`__
+- Added myself alphabetically to ``AUTHORS.rst`` (optional)
+- Added new classes & modules to the docs and all suitable ``__all__`` s
+- Checked the `Stability Policy <https://docs.python-telegram-bot.org/stability_policy.html>`_ in case of deprecations or changes to documented behavior
+
+**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:
+
+   - Added ``self._id_attrs`` and corresponding documentation
+   - ``__init__`` accepts ``api_kwargs`` as kw-only
+
+-  Added new shortcuts:
+
+   - In :class:`~telegram.Chat` & :class:`~telegram.User` for all methods that accept ``chat/user_id``
+   - In :class:`~telegram.Message` for all methods that accept ``chat_id`` and ``message_id``
+   - For new :class:`~telegram.Message` shortcuts: Added ``quote`` argument if methods accepts ``reply_to_message_id``
+   - In :class:`~telegram.CallbackQuery` for all methods that accept either ``chat_id`` and ``message_id`` or ``inline_message_id``
+
+-  If relevant:
+
+   - Added new constants at :mod:`telegram.constants` and shortcuts to them as class variables
+   - Link new and existing constants in docstrings instead of hard-coded numbers and strings
+   - Add new message types to :attr:`telegram.Message.effective_attachment`
+   - Added new handlers for new update types
+
+     - Add the handlers to the warning loop in the :class:`~telegram.ext.ConversationHandler`
+
+   - Added new filters for new message (sub)types
+   - Added or updated documentation for the changed class(es) and/or method(s)
+   - Added the new method(s) to ``_extbot.py``
+   - Added or updated ``bot_methods.rst``
+   - Updated the Bot API version number in all places: ``README.rst`` and ``README_RAW.rst`` (including the badge), as well as ``telegram.constants.BOT_API_VERSION_INFO``
+   - Added logic for arbitrary callback data in :class:`telegram.ext.ExtBot` for new methods that either accept a ``reply_markup`` in some form or have a return type that is/contains :class:`~telegram.Message`
+
 Documenting
 ===========

@@ -228,25 +275,6 @@ callable we prefer that the call also uses keyword arg syntax. For example:
 This gives us the flexibility to re-order arguments and more importantly
 to add new required arguments. It's also more explicit and easier to read.

-Properly defining optional arguments
------------------------------------
-
-It's always good to not initialize optional arguments at class creation,
-instead use ``**kwargs`` to get them. It's well known Telegram API can
-change without notice, in that case if a new argument is added it won't
-break the API classes. For example:
-
-.. code-block:: python
-
-    # GOOD
-    def __init__(self, id, name, last_name=None, **kwargs):
-        self.last_name = last_name
-
-
-    # BAD
-    def __init__(self, id, name, last_name=None):
-        self.last_name = last_name
-

 .. _`Code of Conduct`: https://www.python.org/psf/conduct/
 .. _`issue tracker`: https://github.com/python-telegram-bot/python-telegram-bot/issues
@@ -266,3 +294,4 @@ break the API classes. For example:
 .. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html
 .. _`section`: #documenting
 .. _`testing page`: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/tests/README.rst
+.. _`below`: #check-list-for-prs
@@ -0,0 +1,9 @@
+# Config file for workflows/labelling.yml
+
+version: 1
+
+labels:
+- label: "dependencies"
+  authors: ["dependabot[bot]", "pre-commit-ci[bot]"]
+- label: "code quality ✨"
+  authors: ["pre-commit-ci[bot]"]
@@ -1,38 +1,6 @@
 <!--
-Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to help both you and the maintainers to remember some aspects. Make sure to check out our contribution guide (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst).
+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#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.
 -->

-### Checklist for PRs
-
- [ ] Added `.. versionadded:: version`, `.. versionchanged:: version` or `.. deprecated:: version` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
- [ ] Created new or adapted existing unit tests
- [ ] Documented code changes according to the [CSI standard](https://standards.mousepawmedia.com/en/stable/csi.html)
- [ ] Added myself alphabetically to `AUTHORS.rst` (optional)
- [ ] Added new classes & modules to the docs and all suitable `__all__` s
-
-
-### If the PR contains API changes (otherwise, you can delete this passage)
-
-* New classes:
-    - [ ] Added `self._id_attrs` and corresponding documentation
-    - [ ] `__init__` accepts `api_kwargs` as kw-only
-
-* Added new shortcuts:
-    - [ ] In `Chat` & `User` for all methods that accept `chat/user_id`
-    - [ ] In `Message` for all methods that accept `chat_id` and `message_id`
-    - [ ] For new `Message` shortcuts: Added `quote` argument if methods accepts `reply_to_message_id`
-    - [ ] In `CallbackQuery` for all methods that accept either `chat_id` and `message_id` or `inline_message_id`
-
-* If relevant:
-
-    - [ ] Added new constants at `telegram.constants` and shortcuts to them as class variables
-    - [ ] Link new and existing constants in docstrings instead of hard coded number and strings
-    - [ ] Add new message types to `Message.effective_attachment`
-    - [ ] Added new handlers for new update types
-      - [ ] Add the handlers to the warning loop in the `ConversationHandler`
-    - [ ] Added new filters for new message (sub)types
-    - [ ] Added or updated documentation for the changed class(es) and/or method(s)
-    - [ ] Added the new method(s) to `_extbot.py`
-    - [ ] Added or updated `bot_methods.rst`
-    - [ ] Updated the Bot API version number in all places: `README.rst` and `README_RAW.rst` (including the badge), as well as `telegram.constants.BOT_API_VERSION_INFO`
-    - [ ] Added logic for arbitrary callback data in `tg.ext.Bot` for new methods that either accept a `reply_markup` in some form or have a return type that is/contains `telegram.Message`
@@ -0,0 +1,38 @@
+name: Process Dependabot PRs
+
+on:
+  pull_request:
+    types: [opened, reopened]
+
+jobs:
+  process-dependabot-prs:
+    permissions:
+      pull-requests: read
+      contents: write
+
+    runs-on: ubuntu-latest
+    if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }}
+    steps:
+
+    - name: Fetch Dependabot metadata
+      id: dependabot-metadata
+      uses: dependabot/fetch-metadata@v2.0.0
+
+    - uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event.pull_request.head.ref }}
+
+    - name: Update Version Number in Other Files
+      uses: jacobtomlinson/gha-find-replace@v3
+      with:
+        find: ${{ steps.dependabot-metadata.outputs.previous-version }}
+        replace: ${{ steps.dependabot-metadata.outputs.new-version }}
+        regex: false
+        exclude: CHANGES.rst
+
+    - name: Commit & Push Changes to PR
+      uses: EndBug/add-and-commit@v9.1.4
+      with:
+        message: 'Update version number in other files'
+        committer_name: GitHub Actions
+        committer_email: 41898282+github-actions[bot]@users.noreply.github.com
@@ -14,9 +14,9 @@ jobs:
        os: [ubuntu-latest]
      fail-fast: False
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install dependencies
@@ -1,13 +1,12 @@
 name: Test Documentation Build
 on:
  pull_request:
-    branches:
-      - master
-      - doc-fixes
+    paths:
+      - telegram/**
+      - docs/**
  push:
    branches:
      - master
-      - doc-fixes

 jobs:
  test-sphinx-build:
@@ -19,9 +18,9 @@ jobs:
        os: [ubuntu-latest]
      fail-fast: False
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'
@@ -35,7 +34,7 @@ jobs:
      - name: Build docs
        run: sphinx-build docs/source docs/build/html -W --keep-going -j auto
      - name: Upload docs
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
        with:
          name: HTML Docs
          retention-days: 7
@@ -0,0 +1,17 @@
+name: PR Labeler
+
+on:
+  pull_request:
+    types: [opened]
+
+jobs:
+  pre-commit-ci:
+    permissions:
+      contents: read # for srvaroa/labeler to read config file
+      pull-requests: write # for srvaroa/labeler to add labels in PR
+    runs-on: ubuntu-latest
+    steps:
+    - uses: srvaroa/labeler@v1.10.0
+      # Config file at .github/labeler.yml
+      env:
+        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
@@ -8,10 +8,12 @@ jobs:
  lock:
    runs-on: ubuntu-latest
    steps:
-      - uses: dessant/lock-threads@v4.0.0
+      - uses: dessant/lock-threads@v5.0.1
        with:
          github-token: ${{ github.token }}
          issue-inactive-days: '7'
          issue-lock-reason: ''
          pr-inactive-days: '7'
          pr-lock-reason: ''
+          # Don't lock Discussions
+          process-only: 'issues, prs'
@@ -7,7 +7,7 @@ jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/stale@v7
+      - uses: actions/stale@v9
        with:
          # PRs never get stale
          days-before-stale: 3
@@ -0,0 +1,48 @@
+name: Bot API Tests
+on:
+  pull_request:
+    paths:
+      - telegram/**
+      - tests/**
+  push:
+    branches:
+      - master
+  schedule:
+    # Run monday and friday morning at 03:07 - odd time to spread load on GitHub Actions
+    - cron: '7 3 * * 1,5'
+
+jobs:
+  check-conformity:
+    name: check-conformity
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        python-version: [3.11]
+        os: [ubuntu-latest]
+      fail-fast: False
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -W ignore -m pip install --upgrade pip
+          python -W ignore -m pip install -r requirements.txt
+          python -W ignore -m pip install -r requirements-opts.txt
+          python -W ignore -m pip install -r requirements-dev.txt
+      - name: Compare to official api
+        run: |
+          pytest -v tests/test_official/test_official.py --junit-xml=.test_report_official.xml
+          exit $?
+        env:
+          TEST_OFFICIAL: "true"
+        shell: bash --noprofile --norc {0}
+
+      - name: Test Summary
+        id: test_summary
+        uses: test-summary/action@v2.3
+        if: always()  # always run, even if tests fail
+        with:
+          paths: .test_report_official.xml
@@ -1,8 +1,10 @@
 name: Check Type Completeness
 on:
  pull_request:
-    branches:
-      - master
+    paths:
+      - telegram/**
+      - requirements.txt
+      - requirements-opts.txt
  push:
    branches:
      - master
@@ -12,17 +14,17 @@ jobs:
    name:   test-type-completeness
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - run: git fetch --depth=1  # https://github.com/actions/checkout/issues/329#issuecomment-674881489
      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
        with:
          python-version: 3.9
          cache: 'pip'
          cache-dependency-path: '**/requirements*.txt'
      - name: Install Pyright
        run: |
-          python -W ignore -m pip install pyright~=1.1.291
+          python -W ignore -m pip install pyright~=1.1.316
      - name: Get PR Completeness
        # Must run before base completeness, as base completeness will checkout the base branch
        # And we can't go back to the PR branch after that in case the PR is coming from a fork
@@ -49,21 +51,29 @@ jobs:
            pr = float(
              json.load(open("pr.json", "rb"))["typeCompleteness"]["completenessScore"]
            )
-            base_text = f"After this PR, type completeness will be {round(pr, 3)}."
-            if pr < (base - 0.1):
-                text = f"This PR decreases type completeness by {round(base - pr, 3)}. ❌"
+            base_text = f"This PR changes type completeness from {round(base, 3)} to {round(pr, 3)}."
+            
+            if base == 0:
+                text = f"Something is broken in the workflow. Reported type completeness is 0. 💥"
                set_summary(text)
                print(Path("pr.readable").read_text(encoding="utf-8"))
-                error(f"{text}\n{base_text}")
+                error(text)
                exit(1)
-            elif pr > (base + 0.1):
-                text = f"This PR increases type completeness by {round(pr - base, 3)}. ✨"
+            
+            if pr < (base - 0.001):
+                text = f"{base_text} ❌"
+                set_summary(text)
+                print(Path("pr.readable").read_text(encoding="utf-8"))
+                error(text)
+                exit(1)
+            elif pr > (base + 0.001):
+                text = f"{base_text} ✨"
                set_summary(text)
                if pr < 1:
                    print(Path("pr.readable").read_text(encoding="utf-8"))
-                print(f"{text}\n{base_text}")
+                print(text)
            else:
-                text = f"This PR does not change type completeness by more than 0.1. ✅"
+                text = f"{base_text} This is less than 0.1 percentage points. ✅"
                set_summary(text)
                print(Path("pr.readable").read_text(encoding="utf-8"))
-                print(f"{text}\n{base_text}")
+                print(text)
@@ -1,57 +1,59 @@
-# Make sure that the additional_dependencies here match requirements.txt
+# Make sure that the additional_dependencies here match requirements(-opts).txt

 ci:
    autofix_prs: false
    autoupdate_schedule: monthly
-    # We currently only need this behavior on the v13.x branch were we have the vendored urllib
-    # TODO: Remove once we discontinue v13
-    submodules: true

 repos:
-   repo: https://github.com/psf/black
-    rev: 23.1.0
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 'v0.3.5'
+    hooks:
+    -   id: ruff
+        name: ruff
+        additional_dependencies:
+          - httpx~=0.27
+          - tornado~=6.4
+          - APScheduler~=3.10.4
+          - cachetools~=5.3.3
+          - aiolimiter~=1.1.0
+-   repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 24.3.0
    hooks:
    -   id: black
        args:
        - --diff
        - --check
 -   repo: https://github.com/PyCQA/flake8
-    rev: 6.0.0
+    rev: 7.0.0
    hooks:
    -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v2.16.4
+    rev: v3.1.0
    hooks:
    -   id: pylint
-        files: ^(telegram|examples)/.*\.py$
-        args:
-          - --rcfile=setup.cfg
-          #  run pylint across multiple cpu cores to speed it up-
-          # https://pylint.pycqa.org/en/latest/user_guide/run.html?#parallel-execution to know more
-          - --jobs=0
-
+        files: ^(?!(tests|docs)).*\.py$
        additional_dependencies:
-          - httpx~=0.23.3
-          - tornado~=6.2
-          - APScheduler~=3.10.1
-          - cachetools~=5.3.0
-          - aiolimiter~=1.0.0
+          - httpx~=0.27
+          - tornado~=6.4
+          - APScheduler~=3.10.4
+          - cachetools~=5.3.3
+          - aiolimiter~=1.1.0
          - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.0.1
+    rev: v1.9.0
    hooks:
    -   id: mypy
        name: mypy-ptb
-        files: ^telegram/.*\.py$
+        files: ^(?!(tests|examples|docs)).*\.py$
        additional_dependencies:
          - types-pytz
          - types-cryptography
          - types-cachetools
-          - httpx~=0.23.3
-          - tornado~=6.2
-          - APScheduler~=3.10.1
-          - cachetools~=5.3.0
-          - aiolimiter~=1.0.0
+          - httpx~=0.27
+          - tornado~=6.4
+          - APScheduler~=3.10.4
+          - cachetools~=5.3.3
+          - aiolimiter~=1.1.0
          - . # this basically does `pip install -e .`
    - id: mypy
      name: mypy-examples
@@ -60,34 +62,21 @@ repos:
        - --no-strict-optional
        - --follow-imports=silent
      additional_dependencies:
-        - tornado~=6.2
-        - APScheduler~=3.10.1
-        - cachetools~=5.3.0
+        - tornado~=6.4
+        - APScheduler~=3.10.4
+        - cachetools~=5.3.3
        - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.3.1
+    rev: v3.15.2
    hooks:
    -   id: pyupgrade
-        files: ^(telegram|examples|tests|docs)/.*\.py$
        args:
-          - --py37-plus
+          - --py38-plus
 -   repo: https://github.com/pycqa/isort
-    rev: 5.12.0
+    rev: 5.13.2
    hooks:
    -   id: isort
        name: isort
        args:
        - --diff
        - --check
-   repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: 'v0.0.254'
-    hooks:
-    -   id: ruff
-        name: ruff
-        files: ^(telegram|examples)/.*\.py$
-        additional_dependencies:
-          - httpx~=0.23.3
-          - tornado~=6.2
-          - APScheduler~=3.10.1
-          - cachetools~=5.3.0
-          - aiolimiter~=1.0.0
@@ -7,45 +7,56 @@ version: 2

 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: docs/source/conf.py
+  configuration: docs/source/conf.py

 # Optionally build your docs in additional formats such as PDF
 formats:
-   - pdf
+  - pdf

 # Optionally set the version of Python and requirements required to build your docs
 python:
-   install:
-     - method: pip
-       path: .
-     - requirements: docs/requirements-docs.txt
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements-docs.txt

 build:
-   os: ubuntu-22.04
-   tools:
-      python: "3"  # latest stable cpython version
+  os: ubuntu-22.04
+  tools:
+    python: "3"  # latest stable cpython version
+  jobs:
+    post_build:
+      # Based on https://github.com/readthedocs/readthedocs.org/issues/3242#issuecomment-1410321534
+      # This provides a HTML zip file for download, with the same structure as the hosted website
+      - mkdir --parents $READTHEDOCS_OUTPUT/htmlzip
+      - cp --recursive $READTHEDOCS_OUTPUT/html $READTHEDOCS_OUTPUT/$READTHEDOCS_PROJECT
+      # Hide the "other versions" dropdown. This is a workaround for those versions being shown,
+      # but not being accessible, as they are not built. Also, they hide the actual sidebar menu
+      # that is relevant only on ReadTheDocs.
+      - echo "#furo-readthedocs-versions{display:none}" >> $READTHEDOCS_OUTPUT/$READTHEDOCS_PROJECT/_static/styles/furo-extensions.css
+      - cd $READTHEDOCS_OUTPUT ; zip --recurse-path --symlinks htmlzip/$READTHEDOCS_PROJECT.zip $READTHEDOCS_PROJECT

 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
+  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
+    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'
+  ignore:
+    - changelog.html
+    - coc.html
+    - bot_methods.html#
+    - bot_methods.html
+    # Defaults
+    - search.html
+    - search/index.html
+    - 404.html
+    - 404/index.html'
@@ -21,9 +21,12 @@ 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>`_
+- `Alexandre <https://github.com/xTudoS>`_
+- `Alizia <https://github.com/thefunkycat>`_
 - `Ambro17 <https://github.com/Ambro17>`_
 - `Andrej Zhilenkov <https://github.com/Andrej730>`_
 - `Anton Tagunov <https://github.com/anton-tagunov>`_
@@ -56,6 +59,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Harshil <https://github.com/harshil21>`_
 - `Hugo Damer <https://github.com/HakimusGIT>`_
 - `ihoru <https://github.com/ihoru>`_
+- `Iulian Onofrei <https://github.com/revolter>`_
 - `Jasmin Bom <https://github.com/jsmnbom>`_
 - `JASON0916 <https://github.com/JASON0916>`_
 - `jeffffc <https://github.com/jeffffc>`_
@@ -66,16 +70,20 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Joscha Götzer <https://github.com/Rostgnom>`_
 - `jossalgon <https://github.com/jossalgon>`_
 - `JRoot3D <https://github.com/JRoot3D>`_
+- `kenjitagawa <https://github.com/kenjitagawa>`_
 - `kennethcheo <https://github.com/kennethcheo>`_
 - `Kirill Vasin <https://github.com/vasinkd>`_
 - `Kjwon15 <https://github.com/kjwon15>`_
 - `Li-aung Yip <https://github.com/LiaungYip>`_
 - `Loo Zheng Yuan <https://github.com/loozhengyuan>`_
 - `LRezende <https://github.com/lrezende>`_
+- `Luca Bellanti <https://github.com/Trifase>`_
+- `Lucas Molinari <https://github.com/lucasmolinari>`_
 - `macrojames <https://github.com/macrojames>`_
 - `Matheus Lemos <https://github.com/mlemosf>`_
 - `Michael Dix <https://github.com/Eisberge>`_
 - `Michael Elovskikh <https://github.com/wronglink>`_
+- `Miguel C. R. <https://github.com/MiguelX413>`_
 - `miles <https://github.com/miles170>`_
 - `Mischa Krüger <https://github.com/Makman2>`_
 - `naveenvhegde <https://github.com/naveenvhegde>`_
@@ -115,7 +123,9 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Vorobjev Simon <https://github.com/simonvorobjev>`_
 - `Wagner Macedo <https://github.com/wagnerluis1982>`_
 - `wjt <https://github.com/wjt>`_
+- `Wonseok Oh <https://github.com/marinelay>`_
 - `Yaw Danso <https://github.com/dglitxh>`_
+- `Yao Kuan <https://github.com/thatguylah>`_
 - `zeroone2numeral2 <https://github.com/zeroone2numeral2>`_
 - `zeshuaro <https://github.com/zeshuaro>`_
 - `zpavloudis <https://github.com/zpavloudis>`_
@@ -14,7 +14,7 @@
   :target: https://pypi.org/project/python-telegram-bot/
   :alt: Supported Python versions

-.. image:: https://img.shields.io/badge/Bot%20API-6.6-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-7.2-blue?logo=telegram
   :target: https://core.telegram.org/bots/api-changelog
   :alt: Supported Bot API versions

@@ -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/actions/workflows/unit_tests.yml/badge.svg?branch=master
   :target: https://github.com/python-telegram-bot/python-telegram-bot/
   :alt: Github Actions workflow

@@ -46,10 +46,6 @@
   :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
   :alt: Code quality: Codacy

-.. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
-   :target: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
-   :alt: Code quality: DeepSource
-
 .. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg
   :target: https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master
   :alt: pre-commit.ci status
@@ -77,7 +73,7 @@ Introduction

 This library provides a pure Python, asynchronous interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
-It's compatible with Python versions **3.7+**.
+It's compatible with Python versions **3.8+**.

 In addition to the pure API implementation, this library features a number of high-level classes to
 make the development of bots easy and straightforward. These classes are contained in the
@@ -93,7 +89,7 @@ Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conju
 Telegram API support
 ====================

-All types and methods of the Telegram Bot API **6.6** are supported.
+All types and methods of the Telegram Bot API **7.2** are supported.

 Installing
 ==========
@@ -135,7 +131,7 @@ As these features are *optional*, the corresponding 3rd party dependencies are n
 Instead, they are listed as optional dependencies.
 This allows to avoid unnecessary dependency conflicts for users who don't need the optional features.

-The only required dependency is `httpx ~= 0.23.3 <https://www.python-httpx.org>`_ for
+The only required dependency is `httpx ~= 0.27 <https://www.python-httpx.org>`_ for
 ``telegram.request.HTTPXRequest``, the default networking backend.

 ``python-telegram-bot`` is most useful when used along with additional libraries.
@@ -148,26 +144,26 @@ Optional Dependencies

 PTB can be installed with optional dependencies:

-* ``pip install python-telegram-bot[passport]`` installs the `cryptography>=39.0.1 <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] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
-* ``pip install python-telegram-bot[http2]`` installs `httpx[http2] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to use HTTP/2.
-* ``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.3.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.10.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``.
+* ``pip install "python-telegram-bot[passport]"`` installs the `cryptography>=39.0.1 <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] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
+* ``pip install "python-telegram-bot[http2]"`` installs `httpx[http2] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to use HTTP/2.
+* ``pip install "python-telegram-bot[rate-limiter]"`` installs `aiolimiter~=1.1.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.4 <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.3.3 <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.10.4 <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``.

-To install multiple optional dependencies, separate them by commas, e.g. ``pip install python-telegram-bot[socks,webhooks]``.
+To install multiple optional dependencies, separate them by commas, e.g. ``pip install "python-telegram-bot[socks,webhooks]"``.

 Additionally, two shortcuts are provided:

-* ``pip install python-telegram-bot[all]`` installs all optional dependencies.
-* ``pip install python-telegram-bot[ext]`` installs all optional dependencies that are related to ``telegram.ext``, i.e. ``[rate-limiter, webhooks, callback-data, job-queue]``.
+* ``pip install "python-telegram-bot[all]"`` installs all optional dependencies.
+* ``pip install "python-telegram-bot[ext]"`` installs all optional dependencies that are related to ``telegram.ext``, i.e. ``[rate-limiter, webhooks, callback-data, job-queue]``.

 Quick Start
 ===========

 Our Wiki contains an `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_ explaining how the pure Bot API can be accessed via ``python-telegram-bot``.
-Moreover, the `Tutorial: Your first Bot <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-Your-first-Bot>`_ gives an introduction on how chatbots can be easily programmed with the help of the ``telegram.ext`` module.
+Moreover, the `Tutorial: Your first Bot <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions---Your-first-Bot>`_ gives an introduction on how chatbots can be easily programmed with the help of the ``telegram.ext`` module.

 Resources
 =========
@@ -209,7 +205,7 @@ Contributing

 Contributions of all sizes are welcome.
 Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ to get started.
-You can also help by `reporting bugs or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+You can also help by `reporting bugs or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.

 Donating
 ========
@@ -14,7 +14,7 @@
   :target: https://pypi.org/project/python-telegram-bot-raw/
   :alt: Supported Python versions

-.. image:: https://img.shields.io/badge/Bot%20API-6.6-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-7.2-blue?logo=telegram
   :target: https://core.telegram.org/bots/api-changelog
   :alt: Supported Bot API versions

@@ -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/actions/workflows/unit_tests.yml/badge.svg?branch=master
   :target: https://github.com/python-telegram-bot/python-telegram-bot/
   :alt: Github Actions workflow

@@ -46,10 +46,6 @@
   :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
   :alt: Code quality: Codacy

-.. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
-   :target: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
-   :alt: Code quality: DeepSource
-
 .. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg
   :target: https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master
   :alt: pre-commit.ci status
@@ -77,7 +73,7 @@ Introduction

 This library provides a pure Python, asynchronous interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
-It's compatible with Python versions **3.7+**.
+It's compatible with Python versions **3.8+**.

 ``python-telegram-bot-raw`` is part of the `python-telegram-bot <https://python-telegram-bot.org>`_ ecosystem and provides the pure API functionality extracted from PTB. It therefore does not have independent release schedules, changelogs or documentation.

@@ -89,7 +85,7 @@ Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conju
 Telegram API support
 ====================

-All types and methods of the Telegram Bot API **6.6** are supported.
+All types and methods of the Telegram Bot API **7.2** are supported.

 Installing
 ==========
@@ -108,12 +104,12 @@ You can also install ``python-telegram-bot-raw`` from source, though this is usu

    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
    $ cd python-telegram-bot
-    $ python setup-raw.py install
+    $ python setup_raw.py install

 Note
 ----

-Installing the ``.tar.gz`` archive available on PyPi directly via ``pip`` will *not* work as expected, as ``pip`` does not recognize that it should use ``setup-raw.py`` instead of ``setup.py``.
+Installing the ``.tar.gz`` archive available on PyPi directly via ``pip`` will *not* work as expected, as ``pip`` does not recognize that it should use ``setup_raw.py`` instead of ``setup.py``.

 Verifying Releases
 ------------------
@@ -136,7 +132,7 @@ As these features are *optional*, the corresponding 3rd party dependencies are n
 Instead, they are listed as optional dependencies.
 This allows to avoid unnecessary dependency conflicts for users who don't need the optional features.

-The only required dependency is `httpx ~= 0.23.3 <https://www.python-httpx.org>`_ for
+The only required dependency is `httpx ~= 0.27 <https://www.python-httpx.org>`_ for
 ``telegram.request.HTTPXRequest``, the default networking backend.

 ``python-telegram-bot`` is most useful when used along with additional libraries.
@@ -149,13 +145,13 @@ Optional Dependencies

 PTB can be installed with optional dependencies:

-* ``pip install python-telegram-bot-raw[passport]`` installs the `cryptography>=39.0.1 <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] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
-* ``pip install python-telegram-bot[http2]`` installs `httpx[http2] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to use HTTP/2.
+* ``pip install "python-telegram-bot-raw[passport]"`` installs the `cryptography>=39.0.1 <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] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
+* ``pip install "python-telegram-bot-raw[http2]"`` installs `httpx[http2] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to use HTTP/2.

-To install multiple optional dependencies, separate them by commas, e.g. ``pip install python-telegram-bot-raw[passport,socks]``.
+To install multiple optional dependencies, separate them by commas, e.g. ``pip install "python-telegram-bot-raw[passport,socks]"``.

-Additionally, the shortcut ``pip install python-telegram-bot-raw[all]`` installs all optional dependencies.
+Additionally, the shortcut ``pip install "python-telegram-bot-raw[all]"`` installs all optional dependencies.

 Quick Start
 ===========
@@ -195,7 +191,7 @@ Contributing

 Contributions of all sizes are welcome.
 Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ to get started.
-You can also help by `reporting bugs or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+You can also help by `reporting bugs or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.

 Donating
 ========
@@ -1,6 +1,6 @@
 #
 #  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2023
+#  Copyright (C) 2015-2024
 #  Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 #  This program is free software: you can redistribute it and/or modify
@@ -64,7 +64,7 @@ class AdmonitionInserter:
    ForwardRef('DefaultValue[DVValueType]')
    """

-    METHOD_NAMES_FOR_BOT_AND_APPBUILDER: dict[type, str] = {
+    METHOD_NAMES_FOR_BOT_AND_APPBUILDER: typing.ClassVar[dict[type, str]] = {
        cls: tuple(m[0] for m in _iter_own_public_methods(cls))  # m[0] means we take only names
        for cls in (telegram.Bot, telegram.ext.ApplicationBuilder)
    }
@@ -159,7 +159,7 @@ class AdmonitionInserter:
            telegram.ext, inspect.isclass
        )

-        for class_name, inspected_class in classes_to_inspect:
+        for _class_name, inspected_class in classes_to_inspect:
            # We need to make "<class 'telegram._files.sticker.StickerSet'>" into
            # "telegram.StickerSet" because that's the way the classes are mentioned in
            # docstrings.
@@ -174,8 +174,7 @@ class AdmonitionInserter:
                    break

            for line in lines_with_attrs:
-                line_match = attr_docstr_pattern.match(line)
-                if not line_match:
+                if not (line_match := attr_docstr_pattern.match(line)):
                    continue

                target_attr = line_match.group("attr_name")
@@ -195,11 +194,11 @@ class AdmonitionInserter:
                        )
                    except NotImplementedError as e:
                        raise NotImplementedError(
-                            f"Error generating Sphinx 'Available in' admonition "
+                            "Error generating Sphinx 'Available in' admonition "
                            f"(admonition_inserter.py). Class {name_of_class_in_attr} present in "
                            f"attribute {target_attr} of class {name_of_inspected_class_in_docstr}"
-                            f" could not be resolved. {str(e)}"
-                        )
+                            f" could not be resolved. {e!s}"
+                        ) from e

            # Properties need to be parsed separately because they act like attributes but not
            # listed as attributes.
@@ -238,11 +237,11 @@ class AdmonitionInserter:
                        )
                    except NotImplementedError as e:
                        raise NotImplementedError(
-                            f"Error generating Sphinx 'Available in' admonition "
+                            "Error generating Sphinx 'Available in' admonition "
                            f"(admonition_inserter.py). Class {name_of_class_in_prop} present in "
                            f"property {prop_name} of class {name_of_inspected_class_in_docstr}"
-                            f" could not be resolved. {str(e)}"
-                        )
+                            f" could not be resolved. {e!s}"
+                        ) from e

        return self._generate_admonitions(attrs_for_class, admonition_type="available_in")

@@ -270,10 +269,10 @@ class AdmonitionInserter:
                    )
                except NotImplementedError as e:
                    raise NotImplementedError(
-                        f"Error generating Sphinx 'Returned in' admonition "
+                        "Error generating Sphinx 'Returned in' admonition "
                        f"(admonition_inserter.py). {cls}, method {method_name}. "
-                        f"Couldn't resolve type hint in return annotation {ret_annot}. {str(e)}"
-                    )
+                        f"Couldn't resolve type hint in return annotation {ret_annot}. {e!s}"
+                    ) from e

        return self._generate_admonitions(methods_for_class, admonition_type="returned_in")

@@ -298,7 +297,7 @@ class AdmonitionInserter:

        # inspect methods of all telegram classes for return statements that indicate
        # that this given method is a shortcut for a Bot method
-        for class_name, cls in inspect.getmembers(telegram, predicate=inspect.isclass):
+        for _class_name, cls in inspect.getmembers(telegram, predicate=inspect.isclass):
            # no need to inspect Bot's own methods, as Bot can't have shortcuts in Bot
            if cls is telegram.Bot:
                continue
@@ -343,10 +342,10 @@ class AdmonitionInserter:
                        )
                    except NotImplementedError as e:
                        raise NotImplementedError(
-                            f"Error generating Sphinx 'Use in' admonition "
+                            "Error generating Sphinx 'Use in' admonition "
                            f"(admonition_inserter.py). {cls}, method {method_name}, parameter "
-                            f"{param}: Couldn't resolve type hint {param.annotation}. {str(e)}"
-                        )
+                            f"{param}: Couldn't resolve type hint {param.annotation}. {e!s}"
+                        ) from e

        return self._generate_admonitions(methods_for_class, admonition_type="use_in")

@@ -360,17 +359,19 @@ class AdmonitionInserter:
        If no key phrases are found, the admonition will be inserted at the very end.
        """
        for idx, value in list(enumerate(lines)):
-            if (
-                value.startswith(".. seealso:")
-                # The docstring contains heading "Examples:", but Sphinx will have it converted
-                # to ".. admonition: Examples":
-                or value.startswith(".. admonition:: Examples")
-                or value.startswith(".. version")
-                # The space after ":param" is important because docstring can contain ":paramref:"
-                # in its plain text in the beginning of a line (e.g. ExtBot):
-                or value.startswith(":param ")
-                # some classes (like "Credentials") have no params, so insert before attrs:
-                or value.startswith(".. attribute::")
+            if value.startswith(
+                (
+                    ".. seealso:",
+                    # The docstring contains heading "Examples:", but Sphinx will have it converted
+                    # to ".. admonition: Examples":
+                    ".. admonition:: Examples",
+                    ".. version",
+                    # The space after ":param" is important because docstring can contain
+                    # ":paramref:" in its plain text in the beginning of a line (e.g. ExtBot):
+                    ":param ",
+                    # some classes (like "Credentials") have no params, so insert before attrs:
+                    ".. attribute::",
+                )
            ):
                return idx
        return len(lines) - 1
@@ -412,7 +413,7 @@ class AdmonitionInserter:
                # so its page needs no admonitions.
                continue

-            attrs = sorted(attrs)
+            sorted_attrs = sorted(attrs)

            # e.g. for admonition type "use_in" the title will be "Use in" and CSS class "use-in".
            admonition = f"""
@@ -420,11 +421,11 @@ class AdmonitionInserter:
 .. admonition:: {admonition_type.title().replace("_", " ")}
    :class: {admonition_type.replace("_", "-")}
    """
-            if len(attrs) > 1:
-                for target_attr in attrs:
+            if len(sorted_attrs) > 1:
+                for target_attr in sorted_attrs:
                    admonition += "\n    * " + target_attr
            else:
-                admonition += f"\n    {attrs[0]}"
+                admonition += f"\n    {sorted_attrs[0]}"

            admonition += "\n    "  # otherwise an unexpected unindent warning will be issued
            admonition_for_class[cls] = admonition
@@ -517,19 +518,23 @@ class AdmonitionInserter:
            # If it isn't resolved, we'll have the program throw an exception to be sure.
            try:
                cls = self._resolve_class(m.group("class_name"))
-            except AttributeError:
+            except AttributeError as exc:
                # skip known ForwardRef's that need not be resolved to a Telegram class
                if self.FORWARD_REF_SKIP_PATTERN.match(str(arg)):
                    pass
                else:
-                    raise NotImplementedError(f"Could not process ForwardRef: {arg}")
+                    raise NotImplementedError(f"Could not process ForwardRef: {arg}") from exc
            else:
                yield cls

        # For custom generics like telegram.ext._application.Application[~BT, ~CCT, ~UD...].
        # This must come before the check for isinstance(type) because GenericAlias can also be
        # recognized as type if it belongs to <class 'types.GenericAlias'>.
-        elif str(type(arg)) in ("<class 'typing._GenericAlias'>", "<class 'types.GenericAlias'>"):
+        elif str(type(arg)) in (
+            "<class 'typing._GenericAlias'>",
+            "<class 'types.GenericAlias'>",
+            "<class 'typing._LiteralGenericAlias'>",
+        ):
            if "telegram" in str(arg):
                # get_origin() of telegram.ext._application.Application[~BT, ~CCT, ~UD...]
                # will produce <class 'telegram.ext._application.Application'>
@@ -584,6 +589,7 @@ class AdmonitionInserter:
            # If neither option works, this is not a PTB class.
            except (NameError, AttributeError):
                continue
+        return None


 if __name__ == "__main__":
@@ -1,6 +1,6 @@
 #
 #  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2023
+#  Copyright (C) 2015-2024
 #  Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 #  This program is free software: you can redistribute it and/or modify
@@ -16,51 +16,81 @@
 #  You should have received a copy of the GNU Lesser Public License
 #  along with this program.  If not, see [http://www.gnu.org/licenses/].
 import inspect
+from typing import List

 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",
+    "Keyword Arguments:",
+    (
+        "    read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
+        "        :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to "
+        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. "
+    ),
+    (
+        "    write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
+        "        :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to "
+        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
+    ),
+    (
+        "    connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
+        "        :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to "
+        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
+    ),
+    (
+        "    pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
+        "        :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to "
+        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
+    ),
+    (
+        "    api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments"
+        "        to be passed to the Telegram API. See :meth:`~telegram.Bot.do_api_request` for"
+        "        limitations."
+    ),
    "",
 ]
-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",
+
+media_write_timeout_deprecation_methods = [
+    "send_photo",
+    "send_audio",
+    "send_document",
+    "send_sticker",
+    "send_video",
+    "send_video_note",
+    "send_animation",
+    "send_voice",
+    "send_media_group",
+    "set_chat_photo",
+    "upload_sticker_file",
+    "add_sticker_to_set",
+    "create_new_sticker_set",
+]
+media_write_timeout_deprecation = [
+    "    write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
+    "        :paramref:`telegram.request.BaseRequest.post.write_timeout`. By default, ``20`` "
+    "        seconds are used as write timeout."
+    "",
+    "",
+    "       .. deprecated:: 20.7",
+    "           In future versions, the default value will be changed to "
+    "           :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
+    "",
+    "",
+]
+get_updates_read_timeout_addition = [
+    "        :paramref:`timeout` will be added to this value.",
+    "",
+    "",
+    "        .. versionchanged:: 20.7",
+    "           Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE` instead of ",
+    "           ``2``.",
 ]
-read_timeout_type = [":obj:`float` | :obj:`None`", ":obj:`float`"]


-def find_insert_pos_for_kwargs(lines: list[str]) -> int:
+def find_insert_pos_for_kwargs(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:"):
+        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
+    return False


 def check_timeout_and_api_kwargs_presence(obj: object) -> int:
@@ -1,6 +1,6 @@
 #
 #  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2023
+#  Copyright (C) 2015-2024
 #  Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 #  This program is free software: you can redistribute it and/or modify
@@ -20,6 +20,8 @@ to link to the correct files & lines on github. Can be simplified once
 https://github.com/sphinx-doc/sphinx/issues/1556 is closed
 """
 import subprocess
+from pathlib import Path
+from typing import Dict, Tuple

 from sphinx.util import logging

@@ -30,13 +32,13 @@ sphinx_logger = logging.getLogger(__name__)

 # must be a module-level variable so that it can be written to by the `autodoc-process-docstring`
 # event handler in `sphinx_hooks.py`
-LINE_NUMBERS = {}
+LINE_NUMBERS: Dict[str, Tuple[Path, int, int]] = {}


 def _git_branch() -> str:
    """Get's the current git sha if available or fall back to `master`"""
    try:
-        output = subprocess.check_output(  # skipcq: BAN-B607
+        output = subprocess.check_output(
            ["git", "describe", "--tags", "--always"], stderr=subprocess.STDOUT
        )
        return output.decode().strip()
@@ -52,7 +54,7 @@ git_branch = _git_branch()
 base_url = "https://github.com/python-telegram-bot/python-telegram-bot/blob/"


-def linkcode_resolve(_, info):
+def linkcode_resolve(_, info) -> str:
    """See www.sphinx-doc.org/en/master/usage/extensions/linkcode.html"""
    combined = ".".join((info["module"], info["fullname"]))
    # special casing for ExtBot which is due to the special structure of extbot.rst
@@ -71,7 +73,7 @@ def linkcode_resolve(_, info):
        line_info = LINE_NUMBERS.get(info["module"])

    if not line_info:
-        return
+        return None

    file, start_line, end_line = line_info
    return f"{base_url}{git_branch}/{file}#L{start_line}-L{end_line}"
@@ -1,6 +1,6 @@
 #
 #  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2023
+#  Copyright (C) 2015-2024
 #  Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 #  This program is free software: you can redistribute it and/or modify
@@ -29,11 +29,10 @@ from docs.auxil.admonition_inserter import AdmonitionInserter
 from docs.auxil.kwargs_insertion import (
    check_timeout_and_api_kwargs_presence,
    find_insert_pos_for_kwargs,
-    is_write_timeout_20,
+    get_updates_read_timeout_addition,
    keyword_args,
-    read_timeout_sub,
-    read_timeout_type,
-    write_timeout_sub,
+    media_write_timeout_deprecation,
+    media_write_timeout_deprecation_methods,
 )
 from docs.auxil.link_code import LINE_NUMBERS

@@ -68,9 +67,9 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
                    return True
                break

-    if name == "filter" and obj.__module__ == "telegram.ext.filters":
-        if not included_in_obj:
-            return True  # return True to exclude from docs.
+    if name == "filter" and obj.__module__ == "telegram.ext.filters" and not included_in_obj:
+        return True  # return True to exclude from docs.
+    return None


 def autodoc_process_docstring(
@@ -107,19 +106,24 @@ def autodoc_process_docstring(
                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
+        get_updates: bool = method_name == "get_updates"
        # The below can be done in 1 line with itertools.chain, but this must be modified in-place
+        insert_idx = insert_index
        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],
-                ),
-            )
+            to_insert = keyword_args[i - insert_index]
+
+            if (
+                "post.write_timeout`. Defaults to" in to_insert
+                and method_name in media_write_timeout_deprecation_methods
+            ):
+                effective_insert: list[str] = media_write_timeout_deprecation
+            elif get_updates and to_insert.lstrip().startswith("read_timeout"):
+                effective_insert = [to_insert, *get_updates_read_timeout_addition]
+            else:
+                effective_insert = [to_insert]
+
+            lines[insert_idx:insert_idx] = effective_insert
+            insert_idx += len(effective_insert)

        ADMONITION_INSERTER.insert_admonitions(
            obj=typing.cast(collections.abc.Callable, obj),
@@ -162,11 +166,11 @@ def autodoc_process_docstring(
        autodoc_process_docstring(app, "method", f"{name}.__init__", obj.__init__, options, lines)


-def autodoc_process_bases(app, name, obj, option, bases: list):
+def autodoc_process_bases(app, name, obj, option, bases: list) -> None:
    """Here we fine tune how the base class's classes are displayed."""
-    for idx, base in enumerate(bases):
+    for idx, raw_base in enumerate(bases):
        # let's use a string representation of the object
-        base = str(base)
+        base = str(raw_base)

        # Special case for abstract context managers which are wrongly resoled for some reason
        if base.startswith("typing.AbstractAsyncContextManager"):
@@ -189,8 +193,10 @@ def autodoc_process_bases(app, name, obj, option, bases: list):
            bases[idx] = f":class:`{base}`"

        # Now convert `telegram._message.Message` to `telegram.Message` etc
-        match = re.search(pattern=r"(telegram(\.ext|))\.[_\w\.]+", string=base)
-        if not match or "_utils" in base:
+        if (
+            not (match := re.search(pattern=r"(telegram(\.ext|))\.[_\w\.]+", string=base))
+            or "_utils" in base
+        ):
            continue

        parts = match.group(0).split(".")
@@ -1,6 +1,6 @@
 #
 #  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2023
+#  Copyright (C) 2015-2024
 #  Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 #  This program is free software: you can redistribute it and/or modify
@@ -15,6 +15,7 @@
 #
 #  You should have received a copy of the GNU Lesser Public License
 #  along with this program.  If not, see [http://www.gnu.org/licenses/].
+import datetime
 from enum import Enum

 from docutils.nodes import Element
@@ -71,14 +72,21 @@ class TGConstXRefRole(PyXRefRole):
            if isinstance(value, tuple) and target in (
                "telegram.constants.BOT_API_VERSION_INFO",
                "telegram.__version_info__",
+            ):
+                return str(value), target
+            if (
+                isinstance(value, datetime.datetime)
+                and value == telegram.constants.ZERO_DATE
+                and target in ("telegram.constants.ZERO_DATE",)
            ):
                return repr(value), target
            sphinx_logger.warning(
-                f"%s:%d: WARNING: Did not convert reference %s. :{CONSTANTS_ROLE}: is not supposed"
+                "%s:%d: WARNING: Did not convert reference %s. :%s: is not supposed"
                " to be used with this type of target.",
                refnode.source,
                refnode.line,
                refnode.rawsource,
+                CONSTANTS_ROLE,
            )
            return title, target
        except Exception as exc:
@@ -1,7 +1,7 @@
-sphinx==6.1.3
-sphinx-pypi-upload
-furo==2023.3.23
-git+https://github.com/harshil21/furo-sphinx-search@01efc7be422d7dc02390aab9be68d6f5ce1a5618#egg=furo-sphinx-search
-sphinx-paramlinks==0.5.4
-sphinxcontrib-mermaid==0.8.1
-sphinx-copybutton==0.5.1
+sphinx==7.2.6
+furo==2024.1.29
+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
+sphinx-inline-tabs==2023.4.21
@@ -1,4 +1,3 @@
-import os
 import re
 import sys
 from pathlib import Path
@@ -8,12 +7,12 @@ from pathlib import Path
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 from sphinx.application import Sphinx

-sys.path.insert(0, os.path.abspath("../.."))
+sys.path.insert(0, str(Path("../..").resolve().absolute()))

 # -- General configuration ------------------------------------------------
 # General information about the project.
 project = "python-telegram-bot"
-copyright = "2015-2023, Leandro Toledo"
+copyright = "2015-2024, Leandro Toledo"
 author = "Leandro Toledo"

 # The version info for the project you're documenting, acts as replacement for
@@ -21,9 +20,9 @@ author = "Leandro Toledo"
 # built documents.
 #
 # The short X.Y version.
-version = "20.2"  # telegram.__version__[:3]
+version = "21.1.1"  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = "20.2"  # telegram.__version__
+release = "21.1.1"  # telegram.__version__

 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = "6.1.3"
@@ -39,12 +38,17 @@ extensions = [
    "sphinx.ext.extlinks",
    "sphinx_paramlinks",
    "sphinx_copybutton",
+    "sphinx_inline_tabs",
    "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")}
+extlinks = {
+    "wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s"),
+    "pr": ("https://github.com/python-telegram-bot/python-telegram-bot/pull/%s", "#%s"),
+    "issue": ("https://github.com/python-telegram-bot/python-telegram-bot/issues/%s", "#%s"),
+}

 # Use intersphinx to reference the python builtin library docs
 intersphinx_mapping = {
@@ -72,6 +76,14 @@ napoleon_use_admonition_for_examples = True
 # and we document the types anyway
 autodoc_typehints = "none"

+# Show docstring for special members
+autodoc_default_options = {
+    "special-members": True,
+    # For some reason, __weakref__ can not be ignored by using "inherited-members" in all cases
+    # so we list it here.
+    "exclude-members": "__init__, __weakref__",
+}
+
 # Fail on warnings & unresolved references etc
 nitpicky = True

@@ -91,7 +103,9 @@ linkcheck_ignore = [
 ]
 linkcheck_allowed_redirects = {
    # Redirects to the default version are okay
-    r"https://docs\.python-telegram-bot\.org/.*": r"https://docs\.python-telegram-bot\.org/en/[\w\d\.]+/.*",
+    r"https://docs\.python-telegram-bot\.org/.*": (
+        r"https://docs\.python-telegram-bot\.org/en/[\w\d\.]+/.*"
+    ),
    # pre-commit.ci always redirects to the latest run
    re.escape(
        "https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master"
@@ -126,71 +140,73 @@ html_theme_options = {
        "admonition-title-font-size": "0.95rem",
        "admonition-font-size": "0.92rem",
    },
-    "announcement": "PTB has undergone significant changes in v20. Please read the documentation "
-    "carefully and also check out the transition guide in the "
-    '<a href="https://github.com/python-telegram-bot/python-telegram-bot/wiki/'
-    'Transition-guide-to-Version-20.0">wiki</a>.',
    "footer_icons": [
        {
            # Telegram channel logo
            "name": "Telegram Channel",
            "url": "https://t.me/pythontelegrambotchannel/",
            # Following svg is from https://react-icons.github.io/react-icons/search?q=telegram
-            "html": '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
-            'viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">'
-            '<path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zM8.287 5.906c-.778.324-2.334.994'
-            "-4.666 2.01-.378.15-.577.298-.595.442-.03.243.275.339.69.47l.175.055c.408.133."
-            "958.288 1.243.294.26.006.549-.1.868-.32 2.179-1.471 3.304-2.214 3.374-2.23.0"
-            "5-.012.12-.026.166.016.047.041.042.12.037.141-.03.129-1.227 1.241-1.846 1.81"
-            "7-.193.18-.33.307-.358.336a8.154 8.154 0 0 1-.188.186c-.38.366-.664.64.015 1.08"
-            "8.327.216.589.393.85.571.284.194.568.387.936.629.093.06.183.125.27.187.331.23"
-            "6.63.448.997.414.214-.02.435-.22.547-.82.265-1.417.786-4.486.906-5.751a1.426 "
-            "1.426 0 0 0-.013-.315.337.337 0 0 0-.114-.217.526.526 0 0 0-.31-.093c-.3.005-.7"
-            '63.166-2.984 1.09z"></path></svg>',
+            "html": (
+                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
+                'viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">'
+                '<path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zM8.287 5.906c-.778.324-2.334.994'
+                "-4.666 2.01-.378.15-.577.298-.595.442-.03.243.275.339.69.47l.175.055c.408.133."
+                "958.288 1.243.294.26.006.549-.1.868-.32 2.179-1.471 3.304-2.214 3.374-2.23.0"
+                "5-.012.12-.026.166.016.047.041.042.12.037.141-.03.129-1.227 1.241-1.846 1.81"
+                "7-.193.18-.33.307-.358.336a8.154 8.154 0 0 1-.188.186c-.38.366-.664.64.015 1.08"
+                "8.327.216.589.393.85.571.284.194.568.387.936.629.093.06.183.125.27.187.331.23"
+                "6.63.448.997.414.214-.02.435-.22.547-.82.265-1.417.786-4.486.906-5.751a1.426 "
+                "1.426 0 0 0-.013-.315.337.337 0 0 0-.114-.217.526.526 0 0 0-.31-.093c-.3.005-.7"
+                '63.166-2.984 1.09z"></path></svg>'
+            ),
            "class": "",
        },
        {  # Github logo
            "name": "GitHub",
            "url": "https://github.com/python-telegram-bot/python-telegram-bot/",
-            "html": '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
-            'viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 '
-            "2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.4"
-            "9-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23"
-            ".82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 "
-            "0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.2"
-            "7 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.5"
-            "1.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 "
-            '1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z">'
-            "</path></svg>",
+            "html": (
+                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
+                'viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 '
+                "2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.4"
+                "9-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23"
+                ".82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 "
+                "0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.2"
+                "7 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.5"
+                "1.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 "
+                '1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z">'
+                "</path></svg>"
+            ),
            "class": "",
        },
        {  # PTB website logo - globe
            "name": "python-telegram-bot website",
            "url": "https://python-telegram-bot.org/",
-            "html": '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
-            'viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">'
-            '<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8zm7.5-6.923c-.67.204-1.335.82-1.887 '
-            "1.855-.143.268-.276.56-.395.872.705.157 1.472.257 2.282.287V1.077zM4.249 3.53"
-            "9c.142-.384.304-.744.481-1.078a6.7 6.7 0 0 1 .597-.933A7.01 7.01 0 0 0 3.051 "
-            "3.05c.362.184.763.349 1.198.49zM3.509 7.5c.036-1.07.188-2.087.436-3.008a9.124 "
-            "9.124 0 0 1-1.565-.667A6.964 6.964 0 0 0 1.018 7.5h2.49zm1.4-2.741a12.344 "
-            "12.344 0 0 0-.4 2.741H7.5V5.091c-.91-.03-1.783-.145-2.591-.332zM8.5 5.09V7.5h"
-            "2.99a12.342 12.342 0 0 0-.399-2.741c-.808.187-1.681.301-2.591.332zM4.51 8.5c.03"
-            "5.987.176 1.914.399 2.741A13.612 13.612 0 0 1 7.5 10.91V8.5H4.51zm3.99 0v2.409"
-            "c.91.03 1.783.145 2.591.332.223-.827.364-1.754.4-2.741H8.5zm-3.282 3.696c.12.31"
-            "2.252.604.395.872.552 1.035 1.218 1.65 1.887 1.855V11.91c-.81.03-1.577.13-2.28"
-            "2.287zm.11 2.276a6.696 6.696 0 0 1-.598-.933 8.853 8.853 0 0 1-.481-1.079 8.38 "
-            "8.38 0 0 0-1.198.49 7.01 7.01 0 0 0 2.276 1.522zm-1.383-2.964A13.36 13.36 0 0 1"
-            " 3.508 8.5h-2.49a6.963 6.963 0 0 0 1.362 3.675c.47-.258.995-.482 1.565-.667zm"
-            "6.728 2.964a7.009 7.009 0 0 0 2.275-1.521 8.376 8.376 0 0 0-1.197-.49 8.853 "
-            "8.853 0 0 1-.481 1.078 6.688 6.688 0 0 1-.597.933zM8.5 11.909v3.014c.67-.204 "
-            "1.335-.82 1.887-1.855.143-.268.276-.56.395-.872A12.63 12.63 0 0 0 8.5 11.91zm"
-            "3.555-.401c.57.185 1.095.409 1.565.667A6.963 6.963 0 0 0 14.982 8.5h-2.49a1"
-            "3.36 13.36 0 0 1-.437 3.008zM14.982 7.5a6.963 6.963 0 0 0-1.362-3.675c-.47.25"
-            "8-.995.482-1.565.667.248.92.4 1.938.437 3.008h2.49zM11.27 2.461c.177.334.339.6"
-            "94.482 1.078a8.368 8.368 0 0 0 1.196-.49 7.01 7.01 0 0 0-2.275-1.52c.218.283.4"
-            "18.597.597.932zm-.488 1.343a7.765 7.765 0 0 0-.395-.872C9.835 1.897 9.17 1.282 "
-            '8.5 1.077V4.09c.81-.03 1.577-.13 2.282-.287z"></path></svg>',
+            "html": (
+                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
+                'viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">'
+                '<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8zm7.5-6.923c-.67.204-1.335.82-1.887 '
+                "1.855-.143.268-.276.56-.395.872.705.157 1.472.257 2.282.287V1.077zM4.249 3.53"
+                "9c.142-.384.304-.744.481-1.078a6.7 6.7 0 0 1 .597-.933A7.01 7.01 0 0 0 3.051 "
+                "3.05c.362.184.763.349 1.198.49zM3.509 7.5c.036-1.07.188-2.087.436-3.008a9.124 "
+                "9.124 0 0 1-1.565-.667A6.964 6.964 0 0 0 1.018 7.5h2.49zm1.4-2.741a12.344 "
+                "12.344 0 0 0-.4 2.741H7.5V5.091c-.91-.03-1.783-.145-2.591-.332zM8.5 5.09V7.5h"
+                "2.99a12.342 12.342 0 0 0-.399-2.741c-.808.187-1.681.301-2.591.332zM4.51 8.5c.03"
+                "5.987.176 1.914.399 2.741A13.612 13.612 0 0 1 7.5 10.91V8.5H4.51zm3.99 0v2.409"
+                "c.91.03 1.783.145 2.591.332.223-.827.364-1.754.4-2.741H8.5zm-3.282 3.696c.12.31"
+                "2.252.604.395.872.552 1.035 1.218 1.65 1.887 1.855V11.91c-.81.03-1.577.13-2.28"
+                "2.287zm.11 2.276a6.696 6.696 0 0 1-.598-.933 8.853 8.853 0 0 1-.481-1.079 8.38 "
+                "8.38 0 0 0-1.198.49 7.01 7.01 0 0 0 2.276 1.522zm-1.383-2.964A13.36 13.36 0 0 1"
+                " 3.508 8.5h-2.49a6.963 6.963 0 0 0 1.362 3.675c.47-.258.995-.482 1.565-.667zm"
+                "6.728 2.964a7.009 7.009 0 0 0 2.275-1.521 8.376 8.376 0 0 0-1.197-.49 8.853 "
+                "8.853 0 0 1-.481 1.078 6.688 6.688 0 0 1-.597.933zM8.5 11.909v3.014c.67-.204 "
+                "1.335-.82 1.887-1.855.143-.268.276-.56.395-.872A12.63 12.63 0 0 0 8.5 11.91zm"
+                "3.555-.401c.57.185 1.095.409 1.565.667A6.963 6.963 0 0 0 14.982 8.5h-2.49a1"
+                "3.36 13.36 0 0 1-.437 3.008zM14.982 7.5a6.963 6.963 0 0 0-1.362-3.675c-.47.25"
+                "8-.995.482-1.565.667.248.92.4 1.938.437 3.008h2.49zM11.27 2.461c.177.334.339.6"
+                "94.482 1.078a8.368 8.368 0 0 0 1.196-.49 7.01 7.01 0 0 0-2.275-1.52c.218.283.4"
+                "18.597.597.932zm-.488 1.343a7.765 7.765 0 0 0-.395-.872C9.835 1.897 9.17 1.282 "
+                '8.5 1.077V4.09c.81-.03 1.577-.13 2.282-.287z"></path></svg>'
+            ),
            "class": "",
        },
    ],
@@ -287,17 +303,20 @@ texinfo_documents = [
 # Due to Sphinx behaviour, these imports only work when imported here, not at top of module.

 # Not used but must be imported for the linkcode extension to find it
-from docs.auxil.link_code import linkcode_resolve
-from docs.auxil.sphinx_hooks import (
+from docs.auxil.link_code import linkcode_resolve  # noqa: E402, F401
+from docs.auxil.sphinx_hooks import (  # noqa: E402
    autodoc_process_bases,
    autodoc_process_docstring,
    autodoc_skip_member,
 )
-from docs.auxil.tg_const_role import CONSTANTS_ROLE, TGConstXRefRole
+from docs.auxil.tg_const_role import CONSTANTS_ROLE, TGConstXRefRole  # noqa: E402


 def setup(app: Sphinx):
    app.connect("autodoc-skip-member", autodoc_skip_member)
    app.connect("autodoc-process-bases", autodoc_process_bases)
-    app.connect("autodoc-process-docstring", autodoc_process_docstring)
+    # The default priority is 500. We want our function to run before napoleon doc-conversion
+    # and sphinx-paramlinks do, b/c otherwise the inserted kwargs in the bot methods won't show
+    # up in the objects.inv file that Sphinx generates (i.e. not in the search).
+    app.connect("autodoc-process-docstring", autodoc_process_docstring, priority=100)
    app.add_role_to_domain("py", CONSTANTS_ROLE, TGConstXRefRole())
@@ -1,7 +1,43 @@
 ``customwebhookbot.py``
 =======================

-.. literalinclude:: ../../examples/customwebhookbot.py
-   :language: python
-   :linenos:
+This example is available for different web frameworks.
+You can select your preferred framework by opening one of the tabs above the code example.
+
+.. hint::
+
+    The following examples show how different Python web frameworks can be used alongside PTB.
+    This can be useful for two use cases:
+
+    1. For extending the functionality of your existing bot to handling updates of external services
+    2. For extending the functionality of your exisiting web application to also include chat bot functionality
+
+    How the PTB and web framework components of the examples below are viewed surely depends on which use case one has in mind.
+    We are fully aware that a combination of PTB with web frameworks will always mean finding a tradeoff between usability and best practices for both PTB and the web framework and these examples are certainly far from optimal solutions.
+    Please understand them as starting points and use your expertise of the web framework of your choosing to build up on them.
+    You are of course also very welcome to help improve these examples!
+
+.. tab:: ``starlette``
+
+    .. literalinclude:: ../../examples/customwebhookbot/starlettebot.py
+       :language: python
+       :linenos:
+
+.. tab:: ``flask``
+
+    .. literalinclude:: ../../examples/customwebhookbot/flaskbot.py
+       :language: python
+       :linenos:
+
+.. tab:: ``quart``
+
+    .. literalinclude:: ../../examples/customwebhookbot/quartbot.py
+       :language: python
+       :linenos:
+
+.. tab:: ``Django``
+
+    .. literalinclude:: ../../examples/customwebhookbot/djangobot.py
+       :language: python
+       :linenos:
    
@@ -8,7 +8,7 @@ aspect of the Telegram Bot API while others focus on one of the
 mechanics of this library. Except for the
 :any:`examples.rawapibot` example, they all use the high-level
 framework this library provides with the
-:any:`telegram.ext <telegram.ext>` submodule.
+:mod:`telegram.ext` submodule.

 All examples are licensed under the `CC0
 License <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt>`__
@@ -38,9 +38,8 @@ class to send timed messages. The user sets a timer by using ``/set``
 command with a specific time, for example ``/set 30``. The bot then sets
 up a job to send a message to that user after 30 seconds. The user can
 also cancel the timer by sending ``/unset``. To learn more about the
-``JobQueue``, read `this wiki
-article <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`__.
-Note: To use ``JobQueue``, you must install PTB via ``pip install python-telegram-bot[job-queue]``
+``JobQueue``, read `this wiki article <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions---JobQueue>`__.
+Note: To use ``JobQueue``, you must install PTB via ``pip install "python-telegram-bot[job-queue]"``

 :any:`examples.conversationbot`
 -------------------------------
@@ -116,7 +115,7 @@ Don’t forget to enable and configure payments with
 `@BotFather <https://telegram.me/BotFather>`_. Check out this
 `guide <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport>`__
 on Telegram passports in PTB.
-Note: To use Telegram Passport, you must install PTB via ``pip install python-telegram-bot[passport]``
+Note: To use Telegram Passport, you must install PTB via ``pip install "python-telegram-bot[passport]"``

 :any:`examples.paymentbot`
 --------------------------
@@ -164,7 +163,7 @@ combination with ``telegram.ext.Application``.

 This example showcases how PTBs “arbitrary callback data” feature can be
 used.
-Note: To use arbitrary callback data, you must install PTB via ``pip install python-telegram-bot[callback-data]``
+Note: To use arbitrary callback data, you must install PTB via ``pip install "python-telegram-bot[callback-data]"``

 Pure API
 --------
@@ -1,7 +1,9 @@
 .. 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.
+    * 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.
+    * To gracefully stop the execution of this method from within a handler, job or error callback,
+      use :meth:`~telegram.ext.Application.stop_running`.
@@ -49,8 +49,12 @@
          - Used for sending voice messages
        * - :meth:`~telegram.Bot.copy_message`
          - Used for copying the contents of an arbitrary message
+        * - :meth:`~telegram.Bot.copy_messages`
+          - Used for copying the contents of an multiple arbitrary messages
        * - :meth:`~telegram.Bot.forward_message`
          - Used for forwarding messages
+        * - :meth:`~telegram.Bot.forward_messages`
+          - Used for forwarding multiple messages at once

 .. raw:: html

@@ -76,6 +80,10 @@
      - Used for answering a shipping query
    * - :meth:`~telegram.Bot.answer_web_app_query`
      - Used for answering a web app query
+    * - :meth:`~telegram.Bot.delete_message`
+      - Used for deleting messages.
+    * - :meth:`~telegram.Bot.delete_messages`
+      - Used for deleting multiple messages as once.
    * - :meth:`~telegram.Bot.edit_message_caption`
      - Used for editing captions
    * - :meth:`~telegram.Bot.edit_message_media`
@@ -88,8 +96,8 @@
      - Used for editing text messages
    * - :meth:`~telegram.Bot.stop_poll`
      - Used for stopping the running poll
-    * - :meth:`~telegram.Bot.delete_message`
-      - Used for deleting messages.
+    * - :meth:`~telegram.Bot.set_message_reaction`
+      - Used for setting reactions on messages

 .. raw:: html

@@ -105,6 +113,10 @@
    :align: left
    :widths: 1 4

+    * - :meth:`~telegram.Bot.approve_chat_join_request`
+      - Used for approving a chat join request
+    * - :meth:`~telegram.Bot.decline_chat_join_request`
+      - Used for declining a chat join request
    * - :meth:`~telegram.Bot.ban_chat_member`
      - Used for banning a member from the chat
    * - :meth:`~telegram.Bot.unban_chat_member`
@@ -129,10 +141,6 @@
      - Used for editing a non-primary invite link
    * - :meth:`~telegram.Bot.revoke_chat_invite_link`
      - Used for revoking an invite link created by the bot
-    * - :meth:`~telegram.Bot.approve_chat_join_request`
-      - Used for approving a chat join request
-    * - :meth:`~telegram.Bot.decline_chat_join_request`
-      - Used for declining a chat join request
    * - :meth:`~telegram.Bot.set_chat_photo`
      - Used for setting a photo to a chat
    * - :meth:`~telegram.Bot.delete_chat_photo`
@@ -147,6 +155,8 @@
      - Used for unpinning a message
    * - :meth:`~telegram.Bot.unpin_all_chat_messages`
      - Used for unpinning all pinned chat messages
+    * - :meth:`~telegram.Bot.get_business_connection`
+      - Used for getting information about the business account.
    * - :meth:`~telegram.Bot.get_user_profile_photos`
      - Used for obtaining user's profile pictures
    * - :meth:`~telegram.Bot.get_chat`
@@ -157,6 +167,8 @@
      - Used for getting the number of members in a chat
    * - :meth:`~telegram.Bot.get_chat_member`
      - Used for getting a member of a chat
+    * - :meth:`~telegram.Bot.get_user_chat_boosts`
+      - Used for getting the list of boosts added to a chat
    * - :meth:`~telegram.Bot.leave_chat`
      - Used for leaving a chat

@@ -196,6 +208,10 @@
      - Used for setting the short description of the bot
    * - :meth:`~telegram.Bot.get_my_short_description`
      - Used for obtaining the short description of the bot
+    * - :meth:`~telegram.Bot.set_my_name`
+      - Used for setting the name of the bot
+    * - :meth:`~telegram.Bot.get_my_name`
+      - Used for obtaining the name of the bot

 .. raw:: html

@@ -223,6 +239,8 @@
      - Used for setting a sticker set of a chat
    * - :meth:`~telegram.Bot.delete_chat_sticker_set`
      - Used for deleting the set sticker set of a chat
+    * - :meth:`~telegram.Bot.replace_sticker_in_set`
+      - Used for replacing a sticker in a set
    * - :meth:`~telegram.Bot.set_sticker_position_in_set`
      - Used for moving a sticker's position in the set
    * - :meth:`~telegram.Bot.set_sticker_set_title`
@@ -233,7 +251,7 @@
      - Used for setting the keywords of a sticker
    * - :meth:`~telegram.Bot.set_sticker_mask_position`
      - Used for setting the mask position of a mask sticker
-    * - :meth:`~telegram.Bot.set_sticker_set_thumb`
+    * - :meth:`~telegram.Bot.set_sticker_set_thumbnail`
      - Used for setting the thumbnail of a sticker set
    * - :meth:`~telegram.Bot.set_custom_emoji_sticker_set_thumbnail`
      - Used for setting the thumbnail of a custom emoji sticker set
@@ -324,6 +342,8 @@
      - Used to reopen the general topic
    * - :meth:`~telegram.Bot.unpin_all_forum_topic_messages`
      - Used to unpin all messages in a forum topic
+    * - :meth:`~telegram.Bot.unpin_all_general_forum_topic_messages`
+      - Used to unpin all messages in the general forum topic

 .. raw:: html

@@ -27,11 +27,12 @@
   :hidden:
   :caption: Project

+   stability_policy
   changelog
+   coc
+   contributing
+   testing
   Website <https://python-telegram-bot.org>
   GitHub Repository <https://github.com/python-telegram-bot/python-telegram-bot/>
   Telegram Channel <https://t.me/pythontelegrambotchannel/>
   Telegram User Group <https://t.me/pythontelegrambotgroup/>
-   coc
-   contributing
-   testing
@@ -0,0 +1,146 @@
+Stability Policy
+================
+
+.. important::
+
+    This stability policy is in place since version 20.3.
+    While earlier versions of ``python-telegram-bot`` also had stable interfaces, they had no explicit stability policy and hence did not follow the rules outlined below in all detail.
+    Please also refer to the :ref:`changelog <ptb-changelog>`.
+
+.. caution::
+
+    Large parts of the :mod:`telegram` package are the Python representations of the Telegram Bot API, whose stability policy PTB can not influence.
+    This policy hence includes some special cases for those parts.
+
+What does this policy cover?
+----------------------------
+
+This policy includes any API or behavior that is covered in this documentation.
+This covers both the :mod:`telegram` package and the :mod:`telegram.ext` package.
+
+What doesn't this policy cover?
+-------------------------------
+
+Introduction of new features or changes of flavors of comparable behavior (e.g. the default for the HTTP protocol version being used) are not covered by this policy.
+
+The internal structure of classes in PTB, i.e. things like the result of ``dir(obj))`` or the contents of ``obj.__dict__``, is not covered by this policy.
+
+Objects are in general not guaranteed to be pickleable (unless stated otherwise) and pickled objects from one version of PTB may not be loadable in future versions.
+We may provide a way to convert pickled objects from one version to another, but this is not guaranteed.
+
+Functionality that is part of PTBs API but is explicitly documented as not being intended to be used directly by users (e.g. :meth:`telegram.request.BaseRequest.do_request`) may change.
+This also applies to functions or attributes marked as final in the sense of `PEP 591 <https://peps.python.org/pep-0591/>`__.
+
+PTB has dependencies to third-party packages.
+The versions that PTB uses of these third-party packages may change if that does not affect PTBs public API.
+
+PTB does not give guarantees about which Python versions are supported.
+In general, we will try to support all Python versions that have not yet reached their end of life, but we reserve ourselves the option to drop support for Python versions earlier if that benefits the advancement of the library.
+
+PTB provides static type hints for all public attributes, parameters, return values and generic classes.
+These type hints are not covered by this policy and may change at any time under the condition that these changes have no impact on the runtime behavior of PTB.
+
+.. _bot-api-functionality-1:
+
+Bot API Functionality
+~~~~~~~~~~~~~~~~~~~~~
+
+Comparison of equality of instances of the classes in the :mod:`telegram` package is subject to change and the PTB team will update the behavior to best reflect updates in the Bot API.
+Changes in this regard will be documented in the affected classes.
+Note that equality comparison with objects that where serialized by an older version of PTB may hence give unexpected results.
+
+When the order of arguments of the Bot API methods changes or they become optional/mandatory due to changes in the Bot API, PTB will always try to reflect these changes.
+While we try to make such changes backward compatible, this is not always possible or only with significant effort.
+In such cases we will find a trade-off between backward compatibility and fully complying with the Bot API, which may result in breaking changes.
+We highly recommend using keyword arguments, which can help make such changes non-breaking on your end.
+
+..
+    We have documented a few common cases and possible backwards compatible solutions in the wiki as a reference for the dev team: https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Backward-Compatibility
+
+When the Bot API changes attributes of classes, the method :meth:`telegram.TelegramObject.to_dict` will change as necessary to reflect these changes.
+In particular, attributes deprecated by Telegram will be removed from the returned dictionary.
+Deprecated attributes that are still passed by Telegram will be available in the :attr:`~telegram.TelegramObject.api_kwargs` dictionary as long as PTB can support that with feasible effort.
+Since attributes of the classes in the :mod:`telegram` package are not writable, we may change them to properties where appropriate.
+
+Development Versions
+~~~~~~~~~~~~~~~~~~~~
+
+Pre-releases marked as alpha, beta or release candidate are not covered by this policy.
+Before a feature is in a stable release, i.e. the feature was merged into the ``master`` branch but not released yet (or only in a pre-release), it is not covered by this policy either and may change.
+
+Security
+~~~~~~~~
+
+We make exceptions from our stability policy for security.
+We will violate this policy as necessary in order to resolve a security issue or harden PTB against a possible attack.
+
+Versioning
+----------
+
+PTB uses a versioning scheme that roughly follows `https://semver.org/ <https://semver.org/>`_, although it may not be quite as strict.
+
+Given a version of PTB X.Y.Z,
+
+-  X indicates the major version number.
+   This is incremented when backward incompatible changes are introduced.
+-  Y indicates the minor version number.
+   This is incremented when new functionality or backward compatible changes are introduced by PTB.
+   *This is also incremented when PTB adds support for a new Bot API version, which may include backward incompatible changes in some cases as outlined* :ref:`below <bot-api-versioning>`.
+-  Z is the patch version.
+   This is incremented if backward compatible bug fixes or smaller changes are introduced.
+   If this number is 0, it can be omitted, i.e. we just write X.Y instead of X.Y.0.
+
+Deprecation
+~~~~~~~~~~~
+
+From time to time we will want to change the behavior of an API or remove it entirely, or we do so to comply with changes in the Telegram Bot API.
+In those cases, we follow a deprecation schedule as detailed below.
+
+Functionality is marked as deprecated by a corresponding note in the release notes and the documentation.
+Where possible, a :class:`~telegram.warnings.PTBDeprecationWarning` is issued when deprecated functionality is used, but this is not mandatory.
+
+From time to time, we may decide to deprecate an API that is particularly widely used.
+In these cases, we may decide to provide an extended deprecation period, at our discretion.
+
+With version 20.0.0, PTB introduced major structural breaking changes without the above deprecation period.
+Should a similarly big change ever be deemed necessary again by the development team and should a deprecation period prove too much additional effort, this violation of the stability policy will be announced well ahead of the release in our channel, `as was done for v20 <https://t.me/pythontelegrambotchannel/94>`_.
+
+Non-Bot API Functionality
+#########################
+
+Starting with version 20.3, deprecated functionality will stay available for the current and the next major version.
+For example:
+
+-  In PTB v20.1.1 the feature exists
+-  In PTB v20.1.2 or v20.2.0 the feature is marked as deprecated
+-  In PTB v21.*.* the feature is marked as deprecated
+-  In PTB v22.0 the feature is removed or changed
+
+.. _bot-api-versioning:
+
+Bot API Functionality
+#####################
+
+As PTB has no control over deprecations introduced by Telegram and the schedule of these deprecations rarely coincides with PTBs deprecation schedule, we have a special policy for Bot API functionality.
+
+Starting with 20.3, deprecated Bot API functionality will stay available for the current and the next major version of PTB *or* until the next version of the Bot API.
+More precisely, two cases are possible, for which we show examples below.
+
+Case 1
+^^^^^^
+
+-  In PTB v20.1 the feature exists
+-  Bot API version 6.6 is released and deprecates the feature
+-  PTB v20.2 adds support for Bot API 6.6 and the feature is
+   marked as deprecated
+-  In PTB v21.0 the feature is removed or changed
+
+Case 2
+^^^^^^
+
+-  In PTB v20.1 the feature exists
+-  Bot API version 6.6 is released and deprecates the feature
+-  PTB v20.2 adds support for Bot API version 6.6 and the feature is marked as deprecated
+-  In PTB v20.2.* and v20.3.* the feature is marked as deprecated
+-  Bot API version 6.7 is released
+-  PTB v20.4 adds support for Bot API version 6.7 and the feature is removed or changed
@@ -6,6 +6,7 @@ Available Types

    telegram.animation
    telegram.audio
+    telegram.birthdate
    telegram.botcommand
    telegram.botcommandscope
    telegram.botcommandscopeallchatadministrators
@@ -16,10 +17,25 @@ Available Types
    telegram.botcommandscopechatmember
    telegram.botcommandscopedefault
    telegram.botdescription
+    telegram.botname
    telegram.botshortdescription
+    telegram.businessconnection
+    telegram.businessintro
+    telegram.businesslocation
+    telegram.businessopeninghours
+    telegram.businessopeninghoursinterval
+    telegram.businessmessagesdeleted
    telegram.callbackquery
    telegram.chat
    telegram.chatadministratorrights
+    telegram.chatboost
+    telegram.chatboostadded
+    telegram.chatboostremoved
+    telegram.chatboostsource
+    telegram.chatboostsourcegiftcode
+    telegram.chatboostsourcegiveaway
+    telegram.chatboostsourcepremium
+    telegram.chatboostupdated
    telegram.chatinvitelink
    telegram.chatjoinrequest
    telegram.chatlocation
@@ -37,6 +53,7 @@ Available Types
    telegram.contact
    telegram.dice
    telegram.document
+    telegram.externalreplyinfo
    telegram.file
    telegram.forcereply
    telegram.forumtopic
@@ -46,6 +63,11 @@ Available Types
    telegram.forumtopicreopened
    telegram.generalforumtopichidden
    telegram.generalforumtopicunhidden
+    telegram.giveaway
+    telegram.giveawaycompleted
+    telegram.giveawaycreated
+    telegram.giveawaywinners
+    telegram.inaccessiblemessage
    telegram.inlinekeyboardbutton
    telegram.inlinekeyboardmarkup
    telegram.inputfile
@@ -59,9 +81,11 @@ Available Types
    telegram.keyboardbutton
    telegram.keyboardbuttonpolltype
    telegram.keyboardbuttonrequestchat
-    telegram.keyboardbuttonrequestuser
+    telegram.keyboardbuttonrequestusers
+    telegram.linkpreviewoptions
    telegram.location
    telegram.loginurl
+    telegram.maybeinaccessiblemessage
    telegram.menubutton
    telegram.menubuttoncommands
    telegram.menubuttondefault
@@ -70,19 +94,36 @@ Available Types
    telegram.messageautodeletetimerchanged
    telegram.messageentity
    telegram.messageid
+    telegram.messageorigin
+    telegram.messageoriginchannel
+    telegram.messageoriginchat
+    telegram.messageoriginhiddenuser
+    telegram.messageoriginuser
+    telegram.messagereactioncountupdated
+    telegram.messagereactionupdated
    telegram.photosize
    telegram.poll
    telegram.pollanswer
    telegram.polloption
    telegram.proximityalerttriggered
+    telegram.reactioncount
+    telegram.reactiontype
+    telegram.reactiontypecustomemoji
+    telegram.reactiontypeemoji
    telegram.replykeyboardmarkup
    telegram.replykeyboardremove
+    telegram.replyparameters
    telegram.sentwebappmessage
+    telegram.shareduser
+    telegram.story
+    telegram.switchinlinequerychosenchat
    telegram.telegramobject
+    telegram.textquote
    telegram.update
    telegram.user
+    telegram.userchatboosts
    telegram.userprofilephotos
-    telegram.usershared
+    telegram.usersshared
    telegram.venue
    telegram.video
    telegram.videochatended
@@ -0,0 +1,7 @@
+Birthdate
+=========
+
+.. autoclass:: telegram.Birthdate
+    :members:
+    :show-inheritance:
+
@@ -4,4 +4,3 @@ Bot
 .. autoclass:: telegram.Bot
    :members:
    :show-inheritance:
-    :special-members: __reduce__, __deepcopy__
@@ -0,0 +1,6 @@
+BotName
+=======
+
+.. autoclass:: telegram.BotName
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+BusinessConnection
+==================
+
+.. autoclass:: telegram.BusinessConnection
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+BusinessIntro
+==================
+
+.. autoclass:: telegram.BusinessIntro
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+BusinessLocation
+==================
+
+.. autoclass:: telegram.BusinessLocation
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+BusinessMessagesDeleted
+=======================
+
+.. autoclass:: telegram.BusinessMessagesDeleted
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+BusinessOpeningHours
+====================
+
+.. autoclass:: telegram.BusinessOpeningHours
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+BusinessOpeningHoursInterval
+============================
+
+.. autoclass:: telegram.BusinessOpeningHoursInterval
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatBoost
+=========
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.ChatBoost
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+ChatBoostAdded
+==============
+
+.. autoclass:: telegram.ChatBoostAdded
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatBoostRemoved
+================
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.ChatBoostRemoved
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatBoostSource
+===============
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.ChatBoostSource
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatBoostSourceGiftCode
+=======================
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.ChatBoostSourceGiftCode
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatBoostSourceGiveaway
+=======================
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.ChatBoostSourceGiveaway
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatBoostSourcePremium
+======================
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.ChatBoostSourcePremium
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatBoostUpdated
+================
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.ChatBoostUpdated
+    :members:
+    :show-inheritance:
@@ -4,3 +4,6 @@ telegram.constants Module
 .. automodule:: telegram.constants
    :members:
    :show-inheritance:
+    :no-undoc-members:
+    :inherited-members: Enum, EnumMeta, str, int
+    :exclude-members: __format__, __new__, __repr__, __str__
@@ -0,0 +1,6 @@
+BaseUpdateProcessor
+===================
+
+.. autoclass:: telegram.ext.BaseUpdateProcessor
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+BusinessConnectionHandler
+=========================
+
+.. autoclass:: telegram.ext.BusinessConnectionHandler
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+BusinessMessagesDeletedHandler
+==============================
+
+.. autoclass:: telegram.ext.BusinessMessagesDeletedHandler
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatBoostHandler
+================
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.ext.ChatBoostHandler
+    :members:
+    :show-inheritance:
@@ -5,7 +5,7 @@ filters Module
   The classes in `filters.py` are sorted alphabetically such that :bysource: still is readable

 .. automodule:: telegram.ext.filters
-    :inherited-members: BaseFilter, MessageFilter, UpdateFilter
+    :inherited-members: BaseFilter, MessageFilter, UpdateFilter, object
    :members:
    :show-inheritance:
    :member-order: bysource
@@ -5,7 +5,10 @@ Handlers
    :titlesonly:

    telegram.ext.basehandler
+    telegram.ext.businessconnectionhandler
+    telegram.ext.businessmessagesdeletedhandler
    telegram.ext.callbackqueryhandler
+    telegram.ext.chatboosthandler
    telegram.ext.chatjoinrequesthandler
    telegram.ext.chatmemberhandler
    telegram.ext.choseninlineresulthandler
@@ -14,6 +17,7 @@ Handlers
    telegram.ext.filters
    telegram.ext.inlinequeryhandler
    telegram.ext.messagehandler
+    telegram.ext.messagereactionhandler
    telegram.ext.pollanswerhandler
    telegram.ext.pollhandler
    telegram.ext.precheckoutqueryhandler
@@ -4,4 +4,3 @@ Job
 .. autoclass:: telegram.ext.Job
    :members:
    :show-inheritance:
-    :special-members: __call__
@@ -0,0 +1,6 @@
+MessageReactionHandler
+======================
+
+.. autoclass:: telegram.ext.MessageReactionHandler
+    :members:
+    :show-inheritance:
@@ -1,18 +1,22 @@
 telegram.ext package
 ====================

+.. automodule:: telegram.ext
+
 .. toctree::
    :titlesonly:

    telegram.ext.application
    telegram.ext.applicationbuilder
    telegram.ext.applicationhandlerstop
+    telegram.ext.baseupdateprocessor
    telegram.ext.callbackcontext
    telegram.ext.contexttypes
    telegram.ext.defaults
    telegram.ext.extbot
    telegram.ext.job
    telegram.ext.jobqueue
+    telegram.ext.simpleupdateprocessor
    telegram.ext.updater
    telegram.ext.handlers-tree.rst
    telegram.ext.persistence-tree.rst
@@ -0,0 +1,6 @@
+SimpleUpdateProcessor
+=====================
+
+.. autoclass:: telegram.ext.SimpleUpdateProcessor
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+ExternalReplyInfo
+=================
+
+.. autoclass:: telegram.ExternalReplyInfo
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+Giveaway
+========
+
+.. autoclass:: telegram.Giveaway
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+GiveawayCompleted
+=================
+
+.. autoclass:: telegram.GiveawayCompleted
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+GiveawayCreated
+===============
+
+.. autoclass:: telegram.GiveawayCreated
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+GiveawayWinners
+===============
+
+.. autoclass:: telegram.GiveawayWinners
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+InaccessibleMessage
+===================
+
+.. autoclass:: telegram.InaccessibleMessage
+    :members:
+    :show-inheritance:
@@ -24,6 +24,7 @@ Inline Mode
    telegram.inlinequeryresultlocation
    telegram.inlinequeryresultmpeg4gif
    telegram.inlinequeryresultphoto
+    telegram.inlinequeryresultsbutton
    telegram.inlinequeryresultvenue
    telegram.inlinequeryresultvideo
    telegram.inlinequeryresultvoice
@@ -0,0 +1,6 @@
+InlineQueryResultsButton
+========================
+
+.. autoclass:: telegram.InlineQueryResultsButton
+    :members:
+    :show-inheritance:
@@ -1,6 +0,0 @@
-KeyboardButtonRequestUser
-==================================
-
-.. autoclass:: telegram.KeyboardButtonRequestUser
-    :members:
-    :show-inheritance:
@@ -0,0 +1,6 @@
+KeyboardButtonRequestUsers
+==========================
+
+.. autoclass:: telegram.KeyboardButtonRequestUsers
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+LinkPreviewOptions
+==================
+
+.. autoclass:: telegram.LinkPreviewOptions
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+MaybeInaccessibleMessage
+========================
+
+.. autoclass:: telegram.MaybeInaccessibleMessage
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+MessageOrigin
+=============
+
+.. autoclass:: telegram.MessageOrigin
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+MessageOriginChannel
+====================
+
+.. autoclass:: telegram.MessageOriginChannel
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+MessageOriginChat
+=================
+
+.. autoclass:: telegram.MessageOriginChat
+    :members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+MessageOriginHiddenUser
+=======================
+
+.. autoclass:: telegram.MessageOriginHiddenUser
+    :members:
+    :show-inheritance:
+
@@ -0,0 +1,6 @@
+MessageOriginUser
+=================
+
+.. autoclass:: telegram.MessageOriginUser
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+MessageReactionCountUpdated
+===========================
+
+.. autoclass:: telegram.MessageReactionCountUpdated
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+MessageReactionUpdated
+======================
+
+.. autoclass:: telegram.MessageReactionUpdated
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+ReactionCount
+=============
+
+.. autoclass:: telegram.ReactionCount
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+ReactionType
+============
+
+.. autoclass:: telegram.ReactionType
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+ReactionTypeCustomEmoji
+=======================
+
+.. autoclass:: telegram.ReactionTypeCustomEmoji
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+ReactionTypeEmoji
+=================
+
+.. autoclass:: telegram.ReactionTypeEmoji
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+ReplyParameters
+===============
+
+.. autoclass:: telegram.ReplyParameters
+    :members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+SharedUser
+==========
+
+.. autoclass:: telegram.SharedUser
+    :members:
+    :show-inheritance:
+
@@ -0,0 +1,6 @@
+Story
+=====
+
+.. autoclass:: telegram.Story
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+SwitchInlineQueryChosenChat
+===========================
+
+.. autoclass:: telegram.SwitchInlineQueryChosenChat
+    :members:
+    :show-inheritance:
@@ -4,4 +4,3 @@ TelegramObject
 .. autoclass:: telegram.TelegramObject
    :members:
    :show-inheritance:
-    :special-members: __repr__, __getitem__, __eq__, __hash__, __setstate__, __getstate__, __deepcopy__, __setattr__, __delattr__
@@ -0,0 +1,6 @@
+TextQuote
+=========
+
+.. autoclass:: telegram.TextQuote
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+UserChatBoosts
+==============
+
+.. versionadded:: 20.8
+
+.. autoclass:: telegram.UserChatBoosts
+    :members:
+    :show-inheritance:
@@ -1,6 +0,0 @@
-UserShared
-===================
-
-.. autoclass:: telegram.UserShared
-    :members:
-    :show-inheritance:
@@ -0,0 +1,6 @@
+UsersShared
+===========
+
+.. autoclass:: telegram.UsersShared
+    :members:
+    :show-inheritance:
@@ -14,10 +14,6 @@

 .. |thumbdocstringnopath| replace:: |thumbdocstringbase| |uploadinputnopath|

-.. |thumbargumentdeprecation| replace:: As of Bot API 6.6 this argument is deprecated in favor of
-
-.. |thumbattributedeprecation| replace:: As of Bot API 6.6 this attribute is deprecated in favor of
-
 .. |editreplymarkup| replace:: It is currently only possible to edit messages without :attr:`telegram.Message.reply_markup` or with inline keyboards.

 .. |toapikwargsbase| replace:: These arguments are also considered by :meth:`~telegram.TelegramObject.to_dict` and :meth:`~telegram.TelegramObject.to_json`, i.e. when passing objects to Telegram. Passing them to Telegram is however not guaranteed to work for all kinds of objects, e.g. this will fail for objects that can not directly be JSON serialized.
@@ -55,3 +51,33 @@
 .. |sequenceargs| replace:: Accepts any :class:`collections.abc.Sequence` as input instead of just a list.

 .. |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).
+
+.. |removed_thumb_note| replace:: Removed the deprecated argument and attribute ``thumb``.
+
+.. |removed_thumb_url_note| replace:: Removed the deprecated argument and attribute ``thumb_url``.
+
+.. |removed_thumb_wildcard_note| replace:: Removed the deprecated arguments and attributes ``thumb_*``.
+
+.. |async_context_manager| replace:: Asynchronous context manager which
+
+.. |reply_parameters| replace:: Description of the message to reply to.
+
+.. |rtm_aswr_deprecated| replace:: replacing this argument. PTB will automatically convert this argument to that one, but you should update your code to use the new argument.
+
+.. |keyword_only_arg| replace:: This argument is now a keyword-only argument.
+
+.. |text_html| replace:: The return value of this property is a best-effort approach. Unfortunately, it can not be guaranteed that sending a message with the returned string will render in the same way as the original message produces the same :attr:`~telegram.Message.entities`/:attr:`~telegram.Message.caption_entities` as the original message. For example, Telegram recommends that entities of type :attr:`~telegram.MessageEntity.BLOCKQUOTE` and :attr:`~telegram.MessageEntity.PRE` *should* start and end on a new line, but does not enforce this and leaves rendering decisions up to the clients.
+
+.. |text_markdown| replace:: |text_html| Moreover, markdown formatting is inherently less expressive than HTML, so some edge cases may not be coverable at all. For example, markdown formatting can not specify two consecutive block quotes without a blank line in between, but HTML can.
+
+.. |reply_quote| replace:: If set to :obj:`True`, the reply is sent as an actual reply to this message. If ``reply_to_message_id`` is passed, this parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
+
+.. |do_quote| replace:: If set to :obj:`True`, the replied message is quoted. For a dict, it must be the output of :meth:`~telegram.Message.build_reply_arguments` to specify exact ``reply_parameters``. If ``reply_to_message_id`` or ``reply_parameters`` are passed, this parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
+
+.. |non_optional_story_argument| replace:: As of this version, this argument is now required. In accordance with our `stability policy <https://docs.python-telegram-bot.org/en/stable/stability_policy.html>`__, the signature will be kept as optional for now, though they are mandatory and an error will be raised if you don't pass it.
+
+.. |business_id_str| replace:: Unique identifier of the business connection on behalf of which the message will be sent.
@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument, wrong-import-position
+# pylint: disable=unused-argument
 # This program is dedicated to the public domain under the CC0 license.

 """This example showcases how PTBs "arbitrary callback data" feature can be used.
@@ -9,24 +9,11 @@ https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callba

 Note:
 To use arbitrary callback data, you must install PTB via
-`pip install python-telegram-bot[callback-data]`
+`pip install "python-telegram-bot[callback-data]"`
 """
 import logging
 from typing import List, Tuple, cast

-from telegram import __version__ as TG_VER
-
-try:
-    from telegram import __version_info__
-except ImportError:
-    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
-
-if __version_info__ < (20, 0, 0, "alpha", 1):
-    raise RuntimeError(
-        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
-        f"{TG_VER} version of this example, "
-        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
-    )
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import (
    Application,
@@ -41,6 +28,9 @@ from telegram.ext import (
 logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
 )
+# set higher logging level for httpx to avoid all GET and POST requests being logged
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
 logger = logging.getLogger(__name__)


@@ -122,7 +112,7 @@ def main() -> None:
    application.add_handler(CallbackQueryHandler(list_button))

    # Run the bot until the user presses Ctrl-C
-    application.run_polling()
+    application.run_polling(allowed_updates=Update.ALL_TYPES)


 if __name__ == "__main__":
@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument, wrong-import-position
+# pylint: disable=unused-argument
 # This program is dedicated to the public domain under the CC0 license.

 """
@@ -14,19 +14,6 @@ bot.
 import logging
 from typing import Optional, Tuple

-from telegram import __version__ as TG_VER
-
-try:
-    from telegram import __version_info__
-except ImportError:
-    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
-
-if __version_info__ < (20, 0, 0, "alpha", 1):
-    raise RuntimeError(
-        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
-        f"{TG_VER} version of this example, "
-        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
-    )
 from telegram import Chat, ChatMember, ChatMemberUpdated, Update
 from telegram.constants import ParseMode
 from telegram.ext import (
@@ -44,6 +31,9 @@ logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
 )

+# set higher logging level for httpx to avoid all GET and POST requests being logged
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
 logger = logging.getLogger(__name__)


@@ -103,13 +93,12 @@ async def track_chats(update: Update, context: ContextTypes.DEFAULT_TYPE) -> Non
        elif was_member and not is_member:
            logger.info("%s removed the bot from the group %s", cause_name, chat.title)
            context.bot_data.setdefault("group_ids", set()).discard(chat.id)
-    else:
-        if not was_member and is_member:
-            logger.info("%s added the bot to the channel %s", cause_name, chat.title)
-            context.bot_data.setdefault("channel_ids", set()).add(chat.id)
-        elif was_member and not is_member:
-            logger.info("%s removed the bot from the channel %s", cause_name, chat.title)
-            context.bot_data.setdefault("channel_ids", set()).discard(chat.id)
+    elif not was_member and is_member:
+        logger.info("%s added the bot to the channel %s", cause_name, chat.title)
+        context.bot_data.setdefault("channel_ids", set()).add(chat.id)
+    elif was_member and not is_member:
+        logger.info("%s removed the bot from the channel %s", cause_name, chat.title)
+        context.bot_data.setdefault("channel_ids", set()).discard(chat.id)


 async def show_chats(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument, wrong-import-position
+# pylint: disable=unused-argument
 # This program is dedicated to the public domain under the CC0 license.

 """
@@ -14,19 +14,6 @@ import logging
 from collections import defaultdict
 from typing import DefaultDict, Optional, Set

-from telegram import __version__ as TG_VER
-
-try:
-    from telegram import __version_info__
-except ImportError:
-    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
-
-if __version_info__ < (20, 0, 0, "alpha", 1):
-    raise RuntimeError(
-        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
-        f"{TG_VER} version of this example, "
-        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
-    )
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.constants import ParseMode
 from telegram.ext import (
@@ -43,6 +30,9 @@ from telegram.ext import (
 logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
 )
+# set higher logging level for httpx to avoid all GET and POST requests being logged
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
 logger = logging.getLogger(__name__)


@@ -57,7 +47,12 @@ class ChatData:
 class CustomContext(CallbackContext[ExtBot, dict, ChatData, dict]):
    """Custom class for context."""

-    def __init__(self, application: Application, chat_id: int = None, user_id: int = None):
+    def __init__(
+        self,
+        application: Application,
+        chat_id: Optional[int] = None,
+        user_id: Optional[int] = None,
+    ):
        super().__init__(application=application, chat_id=chat_id, user_id=user_id)
        self._message_id: Optional[int] = None

@@ -120,8 +115,7 @@ async def count_click(update: Update, context: CustomContext) -> None:
 async def print_users(update: Update, context: CustomContext) -> None:
    """Show which users have been using this bot."""
    await update.message.reply_text(
-        "The following user IDs have used this bot: "
-        f'{", ".join(map(str, context.bot_user_ids))}'
+        f"The following user IDs have used this bot: {', '.join(map(str, context.bot_user_ids))}"
    )


@@ -142,7 +136,7 @@ def main() -> None:
    application.add_handler(CallbackQueryHandler(count_click))
    application.add_handler(CommandHandler("print_users", print_users))

-    application.run_polling()
+    application.run_polling(allowed_updates=Update.ALL_TYPES)


 if __name__ == "__main__":
@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument, wrong-import-position
+# pylint: disable=unused-argument
 # This program is dedicated to the public domain under the CC0 license.

 """
@@ -16,19 +16,6 @@ bot.

 import logging

-from telegram import __version__ as TG_VER
-
-try:
-    from telegram import __version_info__
-except ImportError:
-    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
-
-if __version_info__ < (20, 0, 0, "alpha", 5):
-    raise RuntimeError(
-        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
-        f"{TG_VER} version of this example, "
-        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
-    )
 from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update
 from telegram.ext import (
    Application,
@@ -43,6 +30,9 @@ from telegram.ext import (
 logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
 )
+# set higher logging level for httpx to avoid all GET and POST requests being logged
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
 logger = logging.getLogger(__name__)

 GENDER, PHOTO, LOCATION, BIO = range(4)
@@ -169,7 +159,7 @@ def main() -> None:
    application.add_handler(conv_handler)

    # Run the bot until the user presses Ctrl-C
-    application.run_polling()
+    application.run_polling(allowed_updates=Update.ALL_TYPES)


 if __name__ == "__main__":
--- a/Show More
+++ b/Show More