Bump Version to v21.6 (#4486 )

API 7.10 (#4461 , #4460 , #4463 , #4464 )
Co-authored-by: aelkheir <90580077+aelkheir@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>
2026-06-19 15:45:13 +00:00 · 2024-09-19 20:17:08 +02:00 · 2024-09-17 18:09:19 +02:00 · 2024-09-14 08:17:31 +02:00 · 2024-09-14 08:16:39 +02:00 · 2024-09-13 19:32:22 +02:00
389 changed files with 13527 additions and 4866 deletions
@@ -26,7 +26,7 @@ Setting things up

   .. code-block:: bash

-      $ pip install -r requirements-all.txt
+      $ pip install -r requirements-dev-all.txt


 5. Install pre-commit hooks:
@@ -157,7 +157,7 @@ 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)
+- Added ``.. versionadded:: NEXT.VERSION``, ``.. versionchanged:: NEXT.VERSION``, ``.. deprecated:: NEXT.VERSION`` or ``.. versionremoved:: 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)
@@ -194,7 +194,7 @@ Feel free to copy (parts of) the checklist to the PR description to remind you o
   - 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``
+   - Updated the Bot API version number in all places: ``README.rst`` (including the badge) and ``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
@@ -210,13 +210,8 @@ doc strings don't have a separate documentation site they generate, instead, the

 User facing documentation
 -------------------------
-We use `sphinx`_ to generate static HTML docs. To build them, first make sure you're running Python 3.9 or above and have the required dependencies:
-
-.. code-block:: bash
-
-   $ pip install -r docs/requirements-docs.txt
-
-then run the following from the PTB root directory:
+We use `sphinx`_ to generate static HTML docs. To build them, first make sure you're running Python 3.10 or above and have the required dependencies installed as explained above.
+Then, run the following from the PTB root directory:

 .. code-block:: bash

@@ -276,7 +271,7 @@ 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.


-.. _`Code of Conduct`: https://www.python.org/psf/conduct/
+.. _`Code of Conduct`: https://policies.python.org/python.org/code-of-conduct/
 .. _`issue tracker`: https://github.com/python-telegram-bot/python-telegram-bot/issues
 .. _`Telegram group`: https://telegram.me/pythontelegrambotgroup
 .. _`PEP 8 Style Guide`: https://peps.python.org/pep-0008/
@@ -12,6 +12,8 @@ body:
        To make it easier for us to help you, please read this [article](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Ask-Right).

        Please mind that there is also a users' [Telegram group](https://t.me/pythontelegrambotgroup) for questions about the library. Questions asked there might be answered quicker than here. Moreover, [GitHub Discussions](https://github.com/python-telegram-bot/python-telegram-bot/discussions) offer a slightly better format to discuss usage questions.
+        
+        If you have asked the same question elsewhere (e.g. the [Telegram group](https://t.me/pythontelegrambotgroup) or [StackOverflow](https://stackoverflow.com/questions/tagged/python-telegram-bot)), provide a link to that thread.

  - type: textarea
    id: issue-faced
@@ -16,7 +16,7 @@ jobs:

    - name: Fetch Dependabot metadata
      id: dependabot-metadata
-      uses: dependabot/fetch-metadata@v2.0.0
+      uses: dependabot/fetch-metadata@v2.2.0

    - uses: actions/checkout@v4
      with:
@@ -10,7 +10,7 @@ jobs:
    runs-on: ${{matrix.os}}
    strategy:
      matrix:
-        python-version: [3.9]
+        python-version: [3.10]
        os: [ubuntu-latest]
      fail-fast: False
    steps:
@@ -22,6 +22,6 @@ jobs:
      - name: Install dependencies
        run: |
          python -W ignore -m pip install --upgrade pip
-          python -W ignore -m pip install -r requirements-all.txt
+          python -W ignore -m pip install -r requirements-dev-all.txt
      - name: Check Links
        run: sphinx-build docs/source docs/build/html -W --keep-going -j auto -b linkcheck
@@ -14,7 +14,7 @@ jobs:
    runs-on: ${{matrix.os}}
    strategy:
      matrix:
-        python-version: [3.9]
+        python-version: ['3.10']
        os: [ubuntu-latest]
      fail-fast: False
    steps:
@@ -28,7 +28,7 @@ jobs:
      - name: Install dependencies
        run: |
          python -W ignore -m pip install --upgrade pip
-          python -W ignore -m pip install -r requirements-all.txt
+          python -W ignore -m pip install -r requirements-dev-all.txt
      - name: Test autogeneration of admonitions
        run: pytest -v --tb=short tests/docs/admonition_inserter.py
      - name: Build docs
@@ -11,7 +11,7 @@ jobs:
      pull-requests: write # for srvaroa/labeler to add labels in PR
    runs-on: ubuntu-latest
    steps:
-    - uses: srvaroa/labeler@v1.10.0
+    - uses: srvaroa/labeler@v1.10.1
      # Config file at .github/labeler.yml
      env:
        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
@@ -1,19 +0,0 @@
-name: Warning maintainers
-on:
-  pull_request_target:
-    paths:
-      - requirements.txt
-      - requirements-opts.txt
-      - .pre-commit-config.yaml
-permissions:
- pull-requests: write
-jobs:
-  job:
-    runs-on: ubuntu-latest
-    name: about pre-commit and dependency change
-    steps:
-      - name: running the check
-        uses: Poolitzer/notifier-action@master
-        with:
-          notify-message: Hey! Looks like you edited the (optional) requirements or the pre-commit hooks. I'm just a friendly reminder to keep the additional dependencies for the hooks in sync with the requirements :)
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
@@ -1,18 +0,0 @@
-name: Warning maintainers
-on:
-  pull_request_target:
-    paths:
-      - README.rst
-      - README_RAW.rst
-permissions:
- pull-requests: write
-jobs:
-  job:
-    runs-on: ubuntu-latest
-    name: about readme change
-    steps:
-      - name: running the check
-        uses: Poolitzer/notifier-action@master
-        with:
-          notify-message: Hey! Looks like you edited README.rst or README_RAW.rst. I'm just a friendly reminder to apply relevant changes to both of those files :)
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
@@ -0,0 +1,129 @@
+name: Publish to PyPI
+
+on:
+  # manually trigger the workflow
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    outputs:
+      TAG: ${{ steps.get_tag.outputs.TAG }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install pypa/build
+        run: >-
+          python3 -m pip install build --user
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Get Tag Name
+        id: get_tag
+        run: |
+          pip install .
+          TAG=$(python -c "from telegram import __version__; print(f'v{__version__}')")
+          echo "TAG=$TAG" >> $GITHUB_OUTPUT
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: release_pypi
+      url: https://pypi.org/p/python-telegram-bot
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  compute-signatures:
+    name: Compute SHA1 Sums and Sign with Sigstore
+    runs-on: ubuntu-latest
+    needs:
+      - publish-to-pypi
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Compute SHA1 Sums
+        run: |
+          # Compute SHA1 sum of the distribution packages and save it to a file with the same name,
+          # but with .sha1 extension
+          for file in dist/*; do
+              sha1sum $file > $file.sha1
+          done
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Store the distribution packages and signatures
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions-and-signatures
+          path: dist/
+
+  github-release:
+    name: Upload to GitHub Release
+    needs:
+      - build
+      - compute-signatures
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions-and-signatures
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.build.outputs.TAG }}
+        # Create a tag and a GitHub Release. The description can be changed later, as for now
+        # we don't define it through this workflow.
+        run: >-
+          gh release create
+          '${{ env.TAG }}'
+          --repo '${{ github.repository }}'
+          --generate-notes
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.build.outputs.TAG }}
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built packages, and the
+        # sigstore-produced signatures and certificates.
+        run: >-
+          gh release upload
+          '${{ env.TAG }}' dist/**
+          --repo '${{ github.repository }}'
@@ -0,0 +1,132 @@
+name: Publish to Test PyPI
+
+on:
+  # manually trigger the workflow
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    outputs:
+      TAG: ${{ steps.get_tag.outputs.TAG }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install pypa/build
+        run: >-
+          python3 -m pip install build --user
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Get Tag Name
+        id: get_tag
+        run: |
+          pip install .
+          TAG=$(python -c "from telegram import __version__; print(f'v{__version__}')")
+          echo "TAG=$TAG" >> $GITHUB_OUTPUT
+
+  publish-to-test-pypi:
+    name: Publish to Test PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: release_test_pypi
+      url: https://test.pypi.org/p/python-telegram-bot
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  compute-signatures:
+    name: Compute SHA1 Sums and Sign with Sigstore
+    runs-on: ubuntu-latest
+    needs:
+      - publish-to-test-pypi
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Compute SHA1 Sums
+        run: |
+          # Compute SHA1 sum of the distribution packages and save it to a file with the same name,
+          # but with .sha1 extension
+          for file in dist/*; do
+              sha1sum $file > $file.sha1
+          done
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Store the distribution packages and signatures
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions-and-signatures
+          path: dist/
+
+  github-test-release:
+    name: Upload to GitHub Release Draft
+    needs:
+      - build
+      - compute-signatures
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions-and-signatures
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.build.outputs.TAG }}
+        # Create a GitHub Release *draft*. The description can be changed later, as for now
+        # we don't define it through this workflow.
+        run: >-
+          gh release create
+          '${{ env.TAG }}'
+          --repo '${{ github.repository }}'
+          --generate-notes
+          --draft
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.build.outputs.TAG }}
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built packages, and the
+        # sigstore-produced signatures and certificates.
+        run: >-
+          gh release upload
+          '${{ env.TAG }}' dist/**
+          --repo '${{ github.repository }}'
@@ -29,9 +29,8 @@ jobs:
      - 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
+          python -W ignore -m pip install .[all]
+          python -W ignore -m pip install -r requirements-unit-tests.txt
      - name: Compare to official api
        run: |
          pytest -v tests/test_official/test_official.py --junit-xml=.test_report_official.xml
@@ -42,7 +41,7 @@ jobs:

      - name: Test Summary
        id: test_summary
-        uses: test-summary/action@v2.3
+        uses: test-summary/action@v2.4
        if: always()  # always run, even if tests fail
        with:
          paths: .test_report_official.xml
@@ -3,8 +3,8 @@ on:
  pull_request:
    paths:
      - telegram/**
-      - requirements.txt
-      - requirements-opts.txt
+      - pyproject.toml
+      - .github/workflows/type_completeness.yml
  push:
    branches:
      - master
@@ -14,66 +14,8 @@ jobs:
    name:   test-type-completeness
    runs-on: ubuntu-latest
    steps:
-      - 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@v5
+      - uses: Bibo-Joshi/pyright-type-completeness@1.0.0
        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.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
-        run: |
-          pip install . -U
-          pyright --verifytypes telegram --ignoreexternal --outputjson > pr.json || true
-          pyright --verifytypes telegram --ignoreexternal > pr.readable || true
-      - name: Get Base Completeness
-        run: |
-          git checkout ${{ github.base_ref }}
-          pip install . -U
-          pyright --verifytypes telegram --ignoreexternal --outputjson > base.json || true
-      - name: Compare Completeness
-        uses: jannekem/run-python-script-action@v1
-        with:
-          script: |
-            import json
-            import os
-            from pathlib import Path
-
-            base = float(
-              json.load(open("base.json", "rb"))["typeCompleteness"]["completenessScore"]
-            )
-            pr = float(
-              json.load(open("pr.json", "rb"))["typeCompleteness"]["completenessScore"]
-            )
-            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(text)
-                exit(1)
-            
-            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(text)
-            else:
-                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(text)
+          package-name: telegram
+          python-version: 3.12
+          pyright-version: ~=1.1.367
@@ -0,0 +1,33 @@
+name: Check Type Completeness Monthly Run
+on:
+  schedule:
+    # Run first friday of the month at 03:17 - odd time to spread load on GitHub Actions
+    - cron: '17 3 1-7 * 5'
+
+jobs:
+  test-type-completeness:
+    name:   test-type-completeness
+    runs-on: ubuntu-latest
+    steps:
+      - uses: Bibo-Joshi/pyright-type-completeness@1.0.0
+        id: pyright-type-completeness
+        with:
+          package-name: telegram
+          python-version: 3.12
+          pyright-version: ~=1.1.367
+      - name: Check Output
+        uses: jannekem/run-python-script-action@v1
+        env:
+          TYPE_COMPLETENESS: ${{ steps.pyright-type-completeness.outputs.base-completeness-score }}
+        with:
+          script: |
+            import os
+            completeness = float(os.getenv("TYPE_COMPLETENESS"))
+            
+            if completeness >= 1:
+                exit(0)
+            
+            text = f"Type Completeness Decreased to {completeness}. ❌"
+            error(text)
+            set_summary(text)
+            exit(1)
@@ -4,8 +4,9 @@ on:
    paths:
      - telegram/**
      - tests/**
-      - requirements.txt
-      - requirements-opts.txt
+      - .github/workflows/unit_tests.yml
+      - pyproject.toml
+      - requirements-unit-tests.txt
  push:
    branches:
      - master
@@ -19,7 +20,7 @@ jobs:
    runs-on: ${{matrix.os}}
    strategy:
      matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13.0-rc.2']
        os: [ubuntu-latest, windows-latest, macos-latest]
      fail-fast: False
    steps:
@@ -34,8 +35,8 @@ jobs:
        run: |
          python -W ignore -m pip install --upgrade pip
          python -W ignore -m pip install -U pytest-cov
-          python -W ignore -m pip install -r requirements.txt
-          python -W ignore -m pip install -r requirements-dev.txt
+          python -W ignore -m pip install .
+          python -W ignore -m pip install -r requirements-unit-tests.txt
          python -W ignore -m pip install pytest-xdist[psutil]

      - name: Test with pytest
@@ -64,7 +65,7 @@ jobs:

          # Test the rest
          export TEST_WITH_OPT_DEPS='true'
-          pip install -r requirements-opts.txt
+          pip install .[all]
          # `-n auto --dist loadfile` uses pytest-xdist to run each test file on a different CPU
          # worker. Increasing number of workers has little effect on test duration, but it seems
          # to increase flakyness, specially on python 3.7 with --dist=loadgroup.
@@ -82,7 +83,7 @@ jobs:

      - name: Test Summary
        id: test_summary
-        uses: test-summary/action@v2.3
+        uses: test-summary/action@v2.4
        if: always()  # always run, even if tests fail
        with:
          paths: |
@@ -92,3 +92,6 @@ telegram.jpg

 # virtual env
 venv*
+
+# environment manager:
+.mise.toml
@@ -1,12 +1,13 @@
-# Make sure that the additional_dependencies here match requirements(-opts).txt
+# Make sure that the additional_dependencies here match pyproject.toml

 ci:
    autofix_prs: false
-    autoupdate_schedule: monthly
+    autoupdate_schedule: quarterly
+    autoupdate_commit_msg: 'Bump `pre-commit` Hooks to Latest Versions'

 repos:
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.3.5'
+    rev: 'v0.5.6'
    hooks:
    -   id: ruff
        name: ruff
@@ -14,21 +15,21 @@ repos:
          - httpx~=0.27
          - tornado~=6.4
          - APScheduler~=3.10.4
-          - cachetools~=5.3.3
+          - cachetools>=5.3.3,<5.5.0
          - aiolimiter~=1.1.0
 -   repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.3.0
+    rev: 24.4.2
    hooks:
    -   id: black
        args:
        - --diff
        - --check
 -   repo: https://github.com/PyCQA/flake8
-    rev: 7.0.0
+    rev: 7.1.0
    hooks:
    -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v3.1.0
+    rev: v3.2.4
    hooks:
    -   id: pylint
        files: ^(?!(tests|docs)).*\.py$
@@ -36,11 +37,11 @@ repos:
          - httpx~=0.27
          - tornado~=6.4
          - APScheduler~=3.10.4
-          - cachetools~=5.3.3
+          - cachetools>=5.3.3,<5.5.0
          - aiolimiter~=1.1.0
          - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.9.0
+    rev: v1.10.1
    hooks:
    -   id: mypy
        name: mypy-ptb
@@ -52,7 +53,7 @@ repos:
          - httpx~=0.27
          - tornado~=6.4
          - APScheduler~=3.10.4
-          - cachetools~=5.3.3
+          - cachetools>=5.3.3,<5.5.0
          - aiolimiter~=1.1.0
          - . # this basically does `pip install -e .`
    - id: mypy
@@ -64,10 +65,10 @@ repos:
      additional_dependencies:
        - tornado~=6.4
        - APScheduler~=3.10.4
-        - cachetools~=5.3.3
+        - cachetools>=5.3.3,<5.5.0
        - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.15.2
+    rev: v3.16.0
    hooks:
    -   id: pyupgrade
        args:
@@ -60,6 +60,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Hugo Damer <https://github.com/HakimusGIT>`_
 - `ihoru <https://github.com/ihoru>`_
 - `Iulian Onofrei <https://github.com/revolter>`_
+- `Jainam Oswal <https://github.com/jainamoswal>`_
 - `Jasmin Bom <https://github.com/jsmnbom>`_
 - `JASON0916 <https://github.com/JASON0916>`_
 - `jeffffc <https://github.com/jeffffc>`_
@@ -86,6 +87,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Miguel C. R. <https://github.com/MiguelX413>`_
 - `miles <https://github.com/miles170>`_
 - `Mischa Krüger <https://github.com/Makman2>`_
+- `Mohd Yusuf <https://github.com/mohdyusuf2312>`_
 - `naveenvhegde <https://github.com/naveenvhegde>`_
 - `neurrone <https://github.com/neurrone>`_
 - `NikitaPirate <https://github.com/NikitaPirate>`_
@@ -96,6 +98,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Oleg Sushchenko <https://github.com/feuillemorte>`_
 - `Or Bin <https://github.com/OrBin>`_
 - `overquota <https://github.com/overquota>`_
+- `Pablo Martinez <https://github.com/elpekenin>`_
 - `Paradox <https://github.com/paradox70>`_
 - `Patrick Hofmann <https://github.com/PH89>`_
 - `Paul Larsen <https://github.com/PaulSonOfLars>`_
@@ -4,6 +4,227 @@
 Changelog
 =========

+Version 21.6
+============
+
+*Released 2024-09-19*
+
+This is the technical changelog for version 21.6. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+New Features
+------------
+
+- Full Support for Bot API 7.10 (:pr:`4461` closes :issue:`4459`, :pr:`4460`, :pr:`4463` by `aelkheir <https://github.com/aelkheir>`_, :pr:`4464`)
+- Add Parameter ``httpx_kwargs`` to ``HTTPXRequest`` (:pr:`4451` closes :issue:`4424`)
+
+Minor Changes
+-------------
+
+- Improve Type Completeness (:pr:`4466`)
+
+Internal Changes
+----------------
+
+- Update Python 3.13 Test Suite to RC2 (:pr:`4471`)
+- Enforce the ``offline_bot`` Fixture in ``Test*WithoutRequest`` (:pr:`4465`)
+- Make Tests for ``telegram.ext`` Independent of Networking (:pr:`4454`)
+- Rename Testing Base Classes (:pr:`4453`)
+
+Dependency Updates
+------------------
+
+- Bump ``pytest`` from 8.3.2 to 8.3.3 (:pr:`4475`)
+
+Version 21.5
+============
+
+*Released 2024-09-01*
+
+This is the technical changelog for version 21.5. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.9 (:pr:`4429`)
+- Full Support for Bot API 7.8 (:pr:`4408`)
+
+New Features
+------------
+
+- Add ``MessageEntity.shift_entities`` and ``MessageEntity.concatenate`` (:pr:`4376` closes :issue:`4372`)
+- Add Parameter ``game_pattern`` to ``CallbackQueryHandler`` (:pr:`4353` by `jainamoswal <https://github.com/jainamoswal>`_ closes :issue:`4269`)
+- Add Parameter ``read_file_handle`` to ``InputFile`` (:pr:`4388` closes :issue:`4339`)
+
+Documentation Improvements
+--------------------------
+
+- Bugfix for "Available In" Admonitions (:pr:`4413`)
+- Documentation Improvements (:pr:`4400` closes :issue:`4446`, :pr:`4448` by `Palaptin <https://github.com/Palaptin>`_)
+- Document Return Types of ``RequestData`` Members (:pr:`4396`)
+- Add Introductory Paragraphs to Telegram Types Subsections (:pr:`4389` by `mohdyusuf2312 <https://github.com/mohdyusuf2312>`_ closes :issue:`4380`)
+- Start Adapting to RTD Addons (:pr:`4386`)
+
+Minor and Internal Changes
+---------------------------
+
+- Remove Surplus Logging from ``Updater`` Network Loop (:pr:`4432` by `MartinHjelmare <https://github.com/MartinHjelmare>`_)
+- Add Internal Constants for Encodings (:pr:`4378` by `elpekenin <https://github.com/elpekenin>`_)
+- Improve PyPI Automation (:pr:`4375` closes :issue:`4373`)
+- Update Test Suite to New Test Channel Setup (:pr:`4435`)
+- Improve Fixture Usage in ``test_message.py`` (:pr:`4431` by `Palaptin <https://github.com/Palaptin>`_)
+- Update Python 3.13 Test Suite to RC1 (:pr:`4415`)
+- Bump ``ruff`` and Add New Rules (:pr:`4416`)
+
+Dependency Updates
+------------------
+
+- Update ``cachetools`` requirement from <5.5.0,>=5.3.3 to >=5.3.3,<5.6.0 (:pr:`4437`)
+- Bump ``sphinx`` from 7.4.7 to 8.0.2 and ``furo`` from 2024.7.18 to 2024.8.6 (:pr:`4412`)
+- Bump ``test-summary/action`` from 2.3 to 2.4 (:pr:`4410`)
+- Bump ``pytest`` from 8.2.2 to 8.3.2 (:pr:`4403`)
+- Bump ``dependabot/fetch-metadata`` from 2.1.0 to 2.2.0 (:pr:`4411`)
+- Update ``cachetools`` requirement from ~=5.3.3 to >=5.3.3,<5.5.0 (:pr:`4390`)
+- Bump ``sphinx`` from 7.3.7 to 7.4.7 (:pr:`4395`)
+- Bump ``furo`` from 2024.5.6 to 2024.7.18 (:pr:`4392`)
+
+Version 21.4
+============
+
+*Released 2024-07-12*
+
+This is the technical changelog for version 21.4. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.5 (:pr:`4328`, :pr:`4316`, :pr:`4315`, :pr:`4312` closes :issue:`4310`, :pr:`4311`)
+- Full Support for Bot API 7.6 (:pr:`4333` closes :issue:`4331`, :pr:`4344`, :pr:`4341`, :pr:`4334`, :pr:`4335`, :pr:`4351`, :pr:`4342`, :pr:`4348`)
+- Full Support for Bot API 7.7 (:pr:`4356` closes :issue:`4355`)
+- Drop ``python-telegram-bot-raw`` And Switch to ``pyproject.toml`` Based Packaging (:pr:`4288` closes :issue:`4129` and :issue:`4296`)
+- Deprecate Inclusion of ``successful_payment`` in ``Message.effective_attachment`` (:pr:`4365` closes :issue:`4350`)
+
+New Features
+------------
+
+- Add Support for Python 3.13 Beta (:pr:`4253`)
+- Add ``filters.PAID_MEDIA`` (:pr:`4357`)
+- Log Received Data on Deserialization Errors (:pr:`4304`)
+- Add ``MessageEntity.adjust_message_entities_to_utf_16`` Utility Function (:pr:`4323` by `Antares0982 <https://github.com/Antares0982>`_ closes :issue:`4319`)
+- Make Argument ``bot`` of ``TelegramObject.de_json`` Optional (:pr:`4320`)
+
+Documentation Improvements
+--------------------------
+
+- Documentation Improvements (:pr:`4303` closes :issue:`4301`)
+- Restructure Readme (:pr:`4362`)
+- Fix Link-Check Workflow (:pr:`4332`)
+
+Internal Changes
+----------------
+
+- Automate PyPI Releases (:pr:`4364` closes :issue:`4318`)
+- Add ``mise-en-place`` to ``.gitignore`` (:pr:`4300`)
+- Use a Composite Action for Testing Type Completeness (:pr:`4367`)
+- Stabilize Some Concurrency Usages in Test Suite (:pr:`4360`)
+- Add a Test Case for ``MenuButton`` (:pr:`4363`)
+- Extend ``SuccessfulPayment`` Test (:pr:`4349`)
+- Small Fixes for ``test_stars.py`` (:pr:`4347`)
+- Use Python 3.13 Beta 3 in Test Suite (:pr:`4336`)
+
+Dependency Updates
+------------------
+
+- Bump ``ruff`` and Add New Rules (:pr:`4329`)
+- Bump ``pre-commit`` Hooks to Latest Versions (:pr:`4337`)
+- Add Lower Bound for ``flaky`` Dependency (:pr:`4322` by `Palaptin <https://github.com/Palaptin>`_)
+- Bump ``pytest`` from 8.2.1 to 8.2.2 (:pr:`4294`)
+
+Version 21.3
+============
+*Released 2024-06-07*
+
+This is the technical changelog for version 21.3. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.4 (:pr:`4286`, :pr:`4276` closes :issue:`4275`, :pr:`4285`, :pr:`4283`, :pr:`4280`, :pr:`4278`, :pr:`4279`)
+- Deprecate ``python-telegram-bot-raw`` (:pr:`4270`)
+- Remove Functionality Deprecated in Bot API 7.3 (:pr:`4266` closes :issue:`4244`)
+
+New Features
+------------
+
+- Add Parameter ``chat_id`` to ``ChatMemberHandler`` (:pr:`4290` by `uniquetrij <https://github.com/uniquetrij>`_ closes :issue:`4287`)
+
+Documentation Improvements
+--------------------------
+
+- Documentation Improvements (:pr:`4264` closes :issue:`4240`)
+
+Internal Changes
+----------------
+
+- Add ``setuptools`` to ``requirements-dev.txt`` (:pr:`4282`)
+- Update Settings for pre-commit.ci (:pr:`4265`)
+
+Dependency Updates
+------------------
+
+- Bump ``pytest`` from 8.2.0 to 8.2.1 (:pr:`4272`)
+
+Version 21.2
+============
+
+*Released 2024-05-20*
+
+This is the technical changelog for version 21.2. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.3 (:pr:`4246`, :pr:`4260`, :pr:`4243`, :pr:`4248`, :pr:`4242` closes :issue:`4236`, :pr:`4247` by `aelkheir <https://github.com/aelkheir>`_)
+- Remove Functionality Deprecated by Bot API 7.2 (:pr:`4245`)
+
+New Features
+------------
+
+- Add Version to ``PTBDeprecationWarning`` (:pr:`4262` closes :issue:`4261`)
+- Handle Exceptions in building ``CallbackContext`` (:pr:`4222`)
+
+Bug Fixes
+---------
+
+- Call ``Application.post_stop`` Only if ``Application.stop`` was called (:pr:`4211` closes :issue:`4210`)
+- Handle ``SystemExit`` raised in Handlers (:pr:`4157` closes :issue:`4155` and :issue:`4156`)
+- Make ``Birthdate.to_date`` Return a ``datetime.date`` Object (:pr:`4251`)
+
+Documentation Improvements
+--------------------------
+
+- Documentation Improvements (:pr:`4217`)
+
+Internal Changes
+----------------
+
+- Add New Rules to ``ruff`` Config (:pr:`4250`)
+- Adapt Test Suite to Changes in Error Messages (:pr:`4238`)
+
+Dependency Updates
+------------------
+
+- Bump ``furo`` from 2024.4.27 to 2024.5.6 (:pr:`4252`)
+- ``pre-commit`` autoupdate (:pr:`4239`)
+- Bump ``pytest`` from 8.1.1 to 8.2.0 (:pr:`4231`)
+- Bump ``dependabot/fetch-metadata`` from 2.0.0 to 2.1.0 (:pr:`4228`)
+- Bump ``pytest-asyncio`` from 0.21.1 to 0.21.2 (:pr:`4232`)
+- Bump ``pytest-xdist`` from 3.6.0 to 3.6.1 (:pr:`4233`)
+- Bump ``furo`` from 2024.1.29 to 2024.4.27 (:pr:`4230`)
+- Bump ``srvaroa/labeler`` from 1.10.0 to 1.10.1 (:pr:`4227`)
+- Bump ``pytest`` from 7.4.4 to 8.1.1 (:pr:`4218`)
+- Bump ``sphinx`` from 7.2.6 to 7.3.7 (:pr:`4215`)
+- Bump ``pytest-xdist`` from 3.5.0 to 3.6.0 (:pr:`4215`)
+
 Version 21.1.1
 ==============

@@ -1 +0,0 @@
-include LICENSE LICENSE.lesser requirements.txt requirements-opts.txt README_RAW.rst telegram/py.typed
@@ -1,6 +1,3 @@
-..
-    Make sure to apply any changes to this file to README_RAW.rst as well!
-
 .. image:: https://raw.githubusercontent.com/python-telegram-bot/logos/master/logo-text/png/ptb-logo-text_768.png
   :align: center
   :target: https://python-telegram-bot.org
@@ -14,9 +11,9 @@
   :target: https://pypi.org/project/python-telegram-bot/
   :alt: Supported Python versions

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

 .. image:: https://img.shields.io/pypi/dm/python-telegram-bot
   :target: https://pypistats.org/packages/python-telegram-bot
@@ -69,30 +66,36 @@ We have a vibrant community of developers helping each other in our `Telegram gr
 *Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.

 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.8+**.

-In addition to the pure API implementation, this library features a number of high-level classes to
+In addition to the pure API implementation, this library features several convenience methods and shortcuts as well as a number of high-level classes to
 make the development of bots easy and straightforward. These classes are contained in the
 ``telegram.ext`` submodule.

-A pure API implementation *without* ``telegram.ext`` is available as the standalone package ``python-telegram-bot-raw``.  `See here for details. <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/README_RAW.rst>`_
-
-Note
----
-
-Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conjunction will result in undesired side-effects, so only install *one* of both.
+After installing_ the library, be sure to check out the section on `working with PTB`_.

 Telegram API support
-====================
+~~~~~~~~~~~~~~~~~~~~

-All types and methods of the Telegram Bot API **7.2** are supported.
+All types and methods of the Telegram Bot API **7.10** are natively supported by this library.
+In addition, Bot API functionality not yet natively included can still be used as described `in our wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Forward-Compatibility>`_.
+
+Notable Features
+~~~~~~~~~~~~~~~~
+
+- `Fully asynchronous <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
+- Convenient shortcut methods, e.g. `Message.reply_text <https://docs.python-telegram-bot.org/en/stable/telegram.message.html#telegram.Message.reply_text>`_
+- `Fully annotated with static type hints <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Type-Checking>`_
+- `Customizable and extendable interface <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Architecture>`_
+- Seamless integration with `webhooks <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Webhooks>`_ and `polling <https://docs.python-telegram-bot.org/en/stable/telegram.ext.application.html#telegram.ext.Application.run_polling>`_
+- `Comprehensive documentation and examples <#working-with-ptb>`_

 Installing
-==========
+----------

 You can install or upgrade ``python-telegram-bot`` via

@@ -108,22 +111,27 @@ You can also install ``python-telegram-bot`` from source, though this is usually

    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
    $ cd python-telegram-bot
-    $ python setup.py install
+    $ pip install build
+    $ python -m build

 Verifying Releases
------------------
+~~~~~~~~~~~~~~~~~~

-We sign all the releases with a GPG key.
-The signatures are uploaded to both the `GitHub releases page <https://github.com/python-telegram-bot/python-telegram-bot/releases>`_ and the `PyPI project <https://pypi.org/project/python-telegram-bot/>`_ and end with a suffix ``.asc``.
+To enable you to verify that a release file that you downloaded was indeed provided by the ``python-telegram-bot`` team, we have taken the following measures.
+
+Starting with v21.4, all releases are signed via `sigstore <https://www.sigstore.dev>`_.
+The corresponding signature files are uploaded to the `GitHub releases page`_.
+To verify the signature, please install the `sigstore Python client <https://pypi.org/project/sigstore/>`_ and follow the instructions for `verifying signatures from GitHub Actions <https://github.com/sigstore/sigstore-python#signatures-from-github-actions>`_. As input for the ``--repository`` parameter, please use the value ``python-telegram-bot/python-telegram-bot``.
+
+Earlier releases are signed with a GPG key.
+The signatures are uploaded to both the `GitHub releases page`_ and the `PyPI project <https://pypi.org/project/python-telegram-bot/>`_ and end with a suffix ``.asc``.
 Please find the public keys `here <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/public_keys>`_.
-The keys are named in the format ``<first_version>-<last_version>.gpg`` or ``<first_version>-current.gpg`` if the key is currently being used for new releases.
+The keys are named in the format ``<first_version>-<last_version>.gpg``.

 In addition, the GitHub release page also contains the sha1 hashes of the release files in the files with the suffix ``.sha1``.

-This allows you to verify that a release file that you downloaded was indeed provided by the ``python-telegram-bot`` team.
-
 Dependencies & Their Versions
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 ``python-telegram-bot`` tries to use as few 3rd party dependencies as possible.
 However, for some features using a 3rd party library is more sane than implementing the functionality again.
@@ -149,7 +157,7 @@ PTB can be installed with optional dependencies:
 * ``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[callback-data]"`` installs the `cachetools>=5.3.3,<5.6.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.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]"``.
@@ -159,14 +167,19 @@ 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]``.

+Working with PTB
+----------------
+
+Once you have installed the library, you can begin working with it - so let's get started!
+
 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---Your-first-Bot>`_ gives an introduction on how chatbots can be easily programmed with the help of the ``telegram.ext`` module.

 Resources
-=========
+~~~~~~~~~

 - The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
  It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog <https://docs.python-telegram-bot.org/changelog.html>`_.
@@ -177,7 +190,7 @@ Resources
 - The `official Telegram Bot API documentation <https://core.telegram.org/bots/api>`_ is of course always worth a read.

 Getting help
-============
+~~~~~~~~~~~~

 If the resources mentioned above don't answer your questions or simply overwhelm you, there are several ways of getting help.

@@ -188,7 +201,7 @@ If the resources mentioned above don't answer your questions or simply overwhelm
 3. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.

 Concurrency
-===========
+~~~~~~~~~~~

 Since v20.0, ``python-telegram-bot`` is built on top of Pythons ``asyncio`` module.
 Because ``asyncio`` is in general single-threaded, ``python-telegram-bot`` does currently not aim to be thread-safe.
@@ -201,20 +214,22 @@ Noteworthy parts of ``python-telegram-bots`` API that are likely to cause issues
 * all classes in the ``telegram.ext.filters`` module that allow to add/remove allowed users/chats at runtime

 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/choose>`_.

 Donating
-========
+--------
 Occasionally we are asked if we accept donations to support the development.
 While we appreciate the thought, maintaining PTB is our hobby, and we have almost no running costs for it. We therefore have nothing set up to accept donations.
 If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.

 License
-=======
+-------

 You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_.
 Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don't have to be.
+
+.. _`GitHub releases page`: https://github.com/python-telegram-bot/python-telegram-bot/releases>
@@ -1,206 +0,0 @@
-..
-    Make sure to apply any changes to this file to README.rst as well!
-
-.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-raw-logo-text_768.png?raw=true
-   :align: center
-   :target: https://python-telegram-bot.org
-   :alt: python-telegram-bot-raw Logo
-
-.. image:: https://img.shields.io/pypi/v/python-telegram-bot-raw.svg
-   :target: https://pypi.org/project/python-telegram-bot-raw/
-   :alt: PyPi Package Version
-
-.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot-raw.svg
-   :target: https://pypi.org/project/python-telegram-bot-raw/
-   :alt: Supported Python versions
-
-.. 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
-
-.. image:: https://img.shields.io/pypi/dm/python-telegram-bot-raw
-   :target: https://pypistats.org/packages/python-telegram-bot-raw
-   :alt: PyPi Package Monthly Download
-
-.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
-   :target: https://docs.python-telegram-bot.org/
-   :alt: Documentation Status
-
-.. image:: https://img.shields.io/pypi/l/python-telegram-bot-raw.svg
-   :target: https://www.gnu.org/licenses/lgpl-3.0.html
-   :alt: LGPLv3 License
-
-.. 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
-
-.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
-   :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
-   :alt: Code coverage
-
-.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
-   :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
-   :alt: Median time to resolve an issue
-
-.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
-   :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
-   :alt: Code quality: Codacy
-
-.. 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
-
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-   :target: https://github.com/psf/black
-   :alt: Code Style: Black
-
-.. image:: https://img.shields.io/badge/Telegram-Channel-blue.svg?logo=telegram
-   :target: https://t.me/pythontelegrambotchannel
-   :alt: Telegram Channel
-
-.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram
-   :target: https://telegram.me/pythontelegrambotgroup
-   :alt: Telegram Group
-
-We have made you a wrapper you can't refuse
-
-We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
-
-*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.
-
-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.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.
-
-Note
----
-
-Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conjunction will result in undesired side-effects, so only install *one* of both.
-
-Telegram API support
-====================
-
-All types and methods of the Telegram Bot API **7.2** are supported.
-
-Installing
-==========
-
-You can install or upgrade ``python-telegram-bot`` via
-
-.. code:: shell
-
-    $ pip install python-telegram-bot-raw --upgrade
-
-To install a pre-release, use the ``--pre`` `flag <https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-pre>`_ in addition.
-
-You can also install ``python-telegram-bot-raw`` from source, though this is usually not necessary.
-
-.. code:: shell
-
-    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
-    $ cd python-telegram-bot
-    $ 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``.
-
-Verifying Releases
------------------
-
-We sign all the releases with a GPG key.
-The signatures are uploaded to both the `GitHub releases page <https://github.com/python-telegram-bot/python-telegram-bot/releases>`_ and the `PyPI project <https://pypi.org/project/python-telegram-bot/>`_ and end with a suffix ``.asc``.
-Please find the public keys `here <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/public_keys>`_.
-The keys are named in the format ``<first_version>-<last_version>.gpg`` or ``<first_version>-current.gpg`` if the key is currently being used for new releases.
-
-In addition, the GitHub release page also contains the sha1 hashes of the release files in the files with the suffix ``.sha1``.
-
-This allows you to verify that a release file that you downloaded was indeed provided by the ``python-telegram-bot`` team.
-
-Dependencies & Their Versions
-----------------------------
-
-``python-telegram-bot`` tries to use as few 3rd party dependencies as possible.
-However, for some features using a 3rd party library is more sane than implementing the functionality again.
-As these features are *optional*, the corresponding 3rd party dependencies are not installed by default.
-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.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.
-To minimize dependency conflicts, we try to be liberal in terms of version requirements on the (optional) dependencies.
-On the other hand, we have to ensure stability of ``python-telegram-bot``, which is why we do apply version bounds.
-If you encounter dependency conflicts due to these bounds, feel free to reach out.
-
-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-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]"``.
-
-Additionally, the shortcut ``pip install "python-telegram-bot-raw[all]"`` installs all optional dependencies.
-
-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``.
-
-Resources
-=========
-
- The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
-  It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog <https://docs.python-telegram-bot.org/changelog.html>`_.
- The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation.
- Our `examples section <https://docs.python-telegram-bot.org/examples.html>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.
-  Even if it is not your approach for learning, please take a look at ``echobot.py``. It is the de facto base for most of the bots out there.
-  The code for these examples is released to the public domain, so you can start by grabbing the code and building on top of it.
- The `official Telegram Bot API documentation <https://core.telegram.org/bots/api>`_ is of course always worth a read.
-
-Getting help
-============
-
-If the resources mentioned above don't answer your questions or simply overwhelm you, there are several ways of getting help.
-
-1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us! Asking a question here is often the quickest way to get a pointer in the right direction.
-
-2. Ask questions by opening `a discussion <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>`_.
-
-3. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
-
-Concurrency
-===========
-
-Since v20.0, ``python-telegram-bot`` is built on top of Pythons ``asyncio`` module.
-Because ``asyncio`` is in general single-threaded, ``python-telegram-bot`` does currently not aim to be thread-safe.
-
-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/choose>`_.
-
-Donating
-========
-Occasionally we are asked if we accept donations to support the development.
-While we appreciate the thought, maintaining PTB is our hobby, and we have almost no running costs for it. We therefore have nothing set up to accept donations.
-If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
-
-License
-=======
-
-You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_.
-Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don't have to be.
@@ -140,7 +140,7 @@ class AdmonitionInserter:
            r"^\s*(?P<attr_name>[a-z_]+)"  # Any number of spaces, named group for attribute
            r"\s?\("  # Optional whitespace, opening parenthesis
            r".*"  # Any number of characters (that could denote a built-in type)
-            r":class:`.+`"  # Marker of a classref, class name in backticks
+            r":(class|obj):`.+`"  # Marker of a classref, class name in backticks
            r".*\):"  # Any number of characters, closing parenthesis, colon.
            # The ^ colon above along with parenthesis is important because it makes sure that
            # the class is mentioned in the attribute description, not in free text.
@@ -149,11 +149,11 @@ class AdmonitionInserter:
        )

        # for properties: there is no attr name in docstring.  Just check if there's a class name.
-        prop_docstring_pattern = re.compile(r":class:`.+`.*:")
+        prop_docstring_pattern = re.compile(r":(class|obj):`.+`.*:")

        # pattern for iterating over potentially many class names in docstring for one attribute.
        # Tilde is optional (sometimes it is in the docstring, sometimes not).
-        single_class_name_pattern = re.compile(r":class:`~?(?P<class_name>[\w.]*)`")
+        single_class_name_pattern = re.compile(r":(class|obj):`~?(?P<class_name>[\w.]*)`")

        classes_to_inspect = inspect.getmembers(telegram, inspect.isclass) + inspect.getmembers(
            telegram.ext, inspect.isclass
@@ -366,6 +366,7 @@ class AdmonitionInserter:
                    # to ".. admonition: Examples":
                    ".. admonition:: Examples",
                    ".. version",
+                    "Args:",
                    # 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 ",
@@ -16,6 +16,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 collections.abc
+import contextlib
 import inspect
 import re
 import typing
@@ -46,6 +47,7 @@ PRIVATE_BASE_CLASSES = {
    "_BaseThumbedMedium": "TelegramObject",
    "_BaseMedium": "TelegramObject",
    "_CredentialsBase": "TelegramObject",
+    "_ChatBase": "TelegramObject",
 }


@@ -152,13 +154,11 @@ def autodoc_process_docstring(
    if isinstance(obj, telegram.ext.filters.BaseFilter):
        obj = obj.__class__

-    try:
+    with contextlib.suppress(Exception):
        source_lines, start_line = inspect.getsourcelines(obj)
        end_line = start_line + len(source_lines)
        file = Path(inspect.getsourcefile(obj)).relative_to(FILE_ROOT)
        LINE_NUMBERS[name] = (file, start_line, end_line)
-    except Exception:
-        pass

    # Since we don't document the `__init__`, we call this manually to have it available for
    # attributes -- see the note above
@@ -88,7 +88,6 @@ class TGConstXRefRole(PyXRefRole):
                refnode.rawsource,
                CONSTANTS_ROLE,
            )
-            return title, target
        except Exception as exc:
            sphinx_logger.exception(
                "%s:%d: WARNING: Did not convert reference %s due to an exception.",
@@ -98,3 +97,5 @@ class TGConstXRefRole(PyXRefRole):
                exc_info=exc,
            )
            return title, target
+        else:
+            return title, target
@@ -1,7 +1,7 @@
-sphinx==7.2.6
-furo==2024.1.29
+sphinx==8.0.2
+furo==2024.8.6
 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
+sphinx-inline-tabs==2023.4.21
@@ -1,3 +1,4 @@
+import os
 import re
 import sys
 from pathlib import Path
@@ -20,12 +21,16 @@ author = "Leandro Toledo"
 # built documents.
 #
 # The short X.Y version.
-version = "21.1.1"  # telegram.__version__[:3]
+
+# Import needs to be below the sys.path.insert above
+import telegram  # noqa: E402
+
+version = telegram.__version__
 # The full version, including alpha/beta/rc tags.
-release = "21.1.1"  # telegram.__version__
+release = telegram.__version__

 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = "6.1.3"
+needs_sphinx = "8.0.2"

 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -67,7 +72,9 @@ source_suffix = ".rst"
 master_doc = "index"

 # Global substitutions
-rst_prolog = (Path.cwd() / "../substitutions/global.rst").read_text(encoding="utf-8")
+rst_prolog = ""
+for file in Path.cwd().glob("../substitutions/*.rst"):
+    rst_prolog += "\n" + file.read_text(encoding="utf-8")

 # -- Extension settings ------------------------------------------------
 napoleon_use_admonition_for_examples = True
@@ -245,7 +252,14 @@ htmlhelp_basename = "python-telegram-bot-doc"

 # The base URL which points to the root of the HTML documentation. It is used to indicate the
 # location of document using The Canonical Link Relation. Default: ''.
-html_baseurl = "https://docs.python-telegram-bot.org"
+# Set canonical URL from the Read the Docs Domain
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+# Tell Jinja2 templates the build is running on Read the Docs
+html_context = {}
+if os.environ.get("READTHEDOCS", "") == "True":
+    html_context["READTHEDOCS"] = True
+

 # -- Options for LaTeX output ---------------------------------------------

@@ -33,6 +33,8 @@
          - Used for sending media grouped together
        * - :meth:`~telegram.Bot.send_message`
          - Used for sending text messages
+        * - :meth:`~telegram.Bot.send_paid_media`
+          - Used for sending paid media to channels
        * - :meth:`~telegram.Bot.send_photo`
          - Used for sending photos
        * - :meth:`~telegram.Bot.send_poll`
@@ -369,6 +371,10 @@
      - Used for getting basic info about a file
    * - :meth:`~telegram.Bot.get_me`
      - Used for getting basic information about the bot
+    * - :meth:`~telegram.Bot.get_star_transactions`
+      - Used for obtaining the bot's Telegram Stars transactions
+    * - :meth:`~telegram.Bot.refund_star_payment`
+      - Used for refunding a payment in Telegram Stars

 .. raw:: html

@@ -3,6 +3,18 @@
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

+.. raw:: html
+
+    <div style="display: none">
+
+Hidden Headline
+===============
+This is just here to get furo to display the right sidebar.
+
+.. raw:: html
+
+    </div>
+
 .. include:: ../../README.rst

 .. The toctrees are hidden such that they don't render on the start page but still include the contents into the documentation.
@@ -28,6 +28,16 @@ Available Types
    telegram.callbackquery
    telegram.chat
    telegram.chatadministratorrights
+    telegram.chatbackground
+    telegram.backgroundtype
+    telegram.backgroundtypefill
+    telegram.backgroundtypewallpaper
+    telegram.backgroundtypepattern
+    telegram.backgroundtypechattheme
+    telegram.backgroundfill
+    telegram.backgroundfillsolid
+    telegram.backgroundfillgradient
+    telegram.backgroundfillfreeformgradient
    telegram.chatboost
    telegram.chatboostadded
    telegram.chatboostremoved
@@ -36,6 +46,7 @@ Available Types
    telegram.chatboostsourcegiveaway
    telegram.chatboostsourcepremium
    telegram.chatboostupdated
+    telegram.chatfullinfo
    telegram.chatinvitelink
    telegram.chatjoinrequest
    telegram.chatlocation
@@ -77,6 +88,10 @@ Available Types
    telegram.inputmediadocument
    telegram.inputmediaphoto
    telegram.inputmediavideo
+    telegram.inputpaidmedia
+    telegram.inputpaidmediaphoto
+    telegram.inputpaidmediavideo
+    telegram.inputpolloption
    telegram.inputsticker
    telegram.keyboardbutton
    telegram.keyboardbuttonpolltype
@@ -101,6 +116,12 @@ Available Types
    telegram.messageoriginuser
    telegram.messagereactioncountupdated
    telegram.messagereactionupdated
+    telegram.paidmedia
+    telegram.paidmediainfo
+    telegram.paidmediaphoto
+    telegram.paidmediapreview
+    telegram.paidmediapurchased
+    telegram.paidmediavideo
    telegram.photosize
    telegram.poll
    telegram.pollanswer
@@ -110,6 +131,7 @@ Available Types
    telegram.reactiontype
    telegram.reactiontypecustomemoji
    telegram.reactiontypeemoji
+    telegram.reactiontypepaid
    telegram.replykeyboardmarkup
    telegram.replykeyboardremove
    telegram.replyparameters
@@ -0,0 +1,8 @@
+BackgroundFill
+==============
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundFill
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+BackgroundFillFreeformGradient
+==============================
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundFillFreeformGradient
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+BackgroundFillGradient
+======================
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundFillGradient
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+BackgroundFillSolid
+===================
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundFillSolid
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+BackgroundType
+==============
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundType
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+BackgroundTypeChatTheme
+=======================
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundTypeChatTheme
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+BackgroundTypeFill
+==================
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundTypeFill
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+BackgroundTypePattern
+=====================
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundTypePattern
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+BackgroundTypeWallpaper
+=======================
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.BackgroundTypeWallpaper
+    :members:
+    :show-inheritance:
@@ -1,6 +1,8 @@
 Chat
 ====

+.. Also lists methods of _ChatBase, but not the ones of TelegramObject
 .. autoclass:: telegram.Chat
    :members:
    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,8 @@
+ChatBackground
+==============
+
+.. versionadded:: 21.2
+
+.. autoclass:: telegram.ChatBackground
+    :members:
+    :show-inheritance:
@@ -0,0 +1,8 @@
+ChatFullInfo
+============
+
+.. Also lists methods of _ChatBase, but not the ones of TelegramObject
+.. autoclass:: telegram.ChatFullInfo
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -18,6 +18,7 @@ Handlers
    telegram.ext.inlinequeryhandler
    telegram.ext.messagehandler
    telegram.ext.messagereactionhandler
+    telegram.ext.paidmediapurchasedhandler
    telegram.ext.pollanswerhandler
    telegram.ext.pollhandler
    telegram.ext.precheckoutqueryhandler
@@ -0,0 +1,6 @@
+PaidMediaPurchasedHandler
+=========================
+
+.. autoclass:: telegram.ext.PaidMediaPurchasedHandler
+    :members:
+    :show-inheritance:
@@ -1,6 +1,21 @@
+.. _games-tree:
+
 Games
 -----

+Your bot can offer users **HTML5 games** to play solo or to compete against each other in groups and one-on-one chats. Create games via `@BotFather <https://telegram.me/BotFather>`_ using the ``/newgame`` command. Please note that this kind of power requires responsibility: you will need to accept the terms for each game that your bots will be offering.
+
+* Games are a new type of content on Telegram, represented by the :class:`telegram.Game` and :class:`telegram.InlineQueryResultGame` objects.
+* Once you've created a game via `BotFather <https://t.me/botfather>`_, you can send games to chats as regular messages using the :meth:`~telegram.Bot.sendGame` method, or use :ref:`inline mode <inline-tree>` with :class:`telegram.InlineQueryResultGame`.
+* If you send the game message without any buttons, it will automatically have a 'Play ``GameName``' button. When this button is pressed, your bot gets a :class:`telegram.CallbackQuery` with the ``game_short_name`` of the requested game. You provide the correct URL for this particular user and the app opens the game in the in-app browser.
+* You can manually add multiple buttons to your game message. Please note that the first button in the first row **must always** launch the game, using the field ``callback_game`` in :class:`telegram.InlineKeyboardButton`. You can add extra buttons according to taste: e.g., for a description of the rules, or to open the game's official community.
+* To make your game more attractive, you can upload a GIF animation that demonstrates the game to the users via `BotFather <https://t.me/botfather>`_ (see `Lumberjack <https://t.me/gamebot?game=lumberjack>`_ for example).
+* A game message will also display high scores for the current chat. Use :meth:`~telegram.Bot.setGameScore` to post high scores to the chat with the game, add the :paramref:`~telegram.Bot.set_game_score.disable_edit_message` parameter to disable automatic update of the message with the current scoreboard.
+* Use :meth:`~telegram.Bot.getGameHighScores` to get data for in-game high score tables.
+* You can also add an extra sharing button for users to share their best score to different chats.
+* For examples of what can be done using this new stuff, check the `@gamebot <https://t.me/gamebot>`_ and `@gamee <https://t.me/gamee>`_ bots.
+
+
 .. toctree::
    :titlesonly:

@@ -1,6 +1,14 @@
+.. _inline-tree:
+
 Inline Mode
 -----------

+The following methods and objects allow your bot to work in `inline mode <https://core.telegram.org/bots/inline>`_. 
+Please see Telegrams `Introduction to Inline bots <https://core.telegram.org/bots/inline>`_ for more details.
+
+To enable this option, send the ``/setinline`` command to `@BotFather <https://t.me/botfather>`_ and provide the placeholder text that the user will see in the input field after typing your bot's name.
+
+
 .. toctree::
    :titlesonly:

@@ -0,0 +1,6 @@
+InputPaidMedia
+==============
+
+.. autoclass:: telegram.InputPaidMedia
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+InputPaidMediaPhoto
+===================
+
+.. autoclass:: telegram.InputPaidMediaPhoto
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+InputPaidMediaVideo
+===================
+
+.. autoclass:: telegram.InputPaidMediaVideo
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+InputPollOption
+===============
+
+.. autoclass:: telegram.InputPollOption
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+PaidMedia
+=========
+
+.. autoclass:: telegram.PaidMedia
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+PaidMediaInfo
+=============
+
+.. autoclass:: telegram.PaidMediaInfo
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+PaidMediaPhoto
+==============
+
+.. autoclass:: telegram.PaidMediaPhoto
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+PaidMediaPreview
+================
+
+.. autoclass:: telegram.PaidMediaPreview
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+PaidMediaPurchased
+==================
+
+.. autoclass:: telegram.PaidMediaPurchased
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+PaidMediaVideo
+==============
+
+.. autoclass:: telegram.PaidMediaVideo
+    :members:
+    :show-inheritance:
@@ -1,6 +1,9 @@
 Passport
 --------

+Passport is a unified authorization method for services that require personal identification. Users can upload their documents once, then instantly share their data with services that require real-world ID (finance, ICOs, etc.). Please see the `manual <https://core.telegram.org/passport>`_ for details.
+
+
 .. toctree::
    :titlesonly:

@@ -1,6 +1,11 @@
+.. _payments-tree:
+
 Payments
 --------

+Your bot can accept payments from Telegram users. Please see the `introduction to payments <https://core.telegram.org/bots/payments>`_ for more details on the process and how to set up payments for your bot.
+
+
 .. toctree::
    :titlesonly:

@@ -8,7 +13,19 @@ Payments
    telegram.labeledprice
    telegram.orderinfo
    telegram.precheckoutquery
+    telegram.refundedpayment
+    telegram.revenuewithdrawalstate
+    telegram.revenuewithdrawalstatefailed
+    telegram.revenuewithdrawalstatepending
+    telegram.revenuewithdrawalstatesucceeded
    telegram.shippingaddress
    telegram.shippingoption
    telegram.shippingquery
+    telegram.startransaction
+    telegram.startransactions
    telegram.successfulpayment
+    telegram.transactionpartner
+    telegram.transactionpartnerfragment
+    telegram.transactionpartnerother
+    telegram.transactionpartnertelegramads
+    telegram.transactionpartneruser
@@ -1,6 +1,6 @@
 PhotoSize
 =========
-.. Also lists methods of _BaseThumbedMedium, but not the ones of TelegramObject
+.. Also lists methods of _BaseMedium, but not the ones of TelegramObject

 .. autoclass:: telegram.PhotoSize
    :members:
@@ -0,0 +1,6 @@
+ReactionTypePaid
+================
+
+.. autoclass:: telegram.ReactionTypePaid
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+RefundedPayment
+===============
+
+.. autoclass:: telegram.RefundedPayment
+    :members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+RevenueWithdrawalState
+======================
+
+.. autoclass:: telegram.RevenueWithdrawalState
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,7 @@
+RevenueWithdrawalStateFailed
+=============================
+
+.. autoclass:: telegram.RevenueWithdrawalStateFailed
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,7 @@
+RevenueWithdrawalStatePending
+=============================
+
+.. autoclass:: telegram.RevenueWithdrawalStatePending
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,7 @@
+RevenueWithdrawalStateSucceeded
+===============================
+
+.. autoclass:: telegram.RevenueWithdrawalStateSucceeded
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,7 @@
+StarTransaction
+===============
+
+.. autoclass:: telegram.StarTransaction
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,8 @@
+StarTransactions
+================
+
+.. autoclass:: telegram.StarTransactions
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
+
@@ -1,6 +1,8 @@
 Stickers
 --------

+The following methods and objects allow your bot to handle stickers and sticker sets.
+
 .. toctree::
    :titlesonly:

@@ -0,0 +1,7 @@
+TransactionPartner
+==================
+
+.. autoclass:: telegram.TransactionPartner
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,7 @@
+TransactionPartnerFragment
+==========================
+
+.. autoclass:: telegram.TransactionPartnerFragment
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,7 @@
+TransactionPartnerOther
+=======================
+
+.. autoclass:: telegram.TransactionPartnerOther
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,7 @@
+TransactionPartnerTelegramAds
+=============================
+
+.. autoclass:: telegram.TransactionPartnerTelegramAds
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1,7 @@
+TransactionPartnerUser
+======================
+
+.. autoclass:: telegram.TransactionPartnerUser
+    :members:
+    :show-inheritance:
+    :inherited-members: TelegramObject
@@ -0,0 +1 @@
+.. |app_run_shutdown| replace:: The app will shut down when :exc:`KeyboardInterrupt` or :exc:`SystemExit` is raised. This also works from within handlers, error handlers and jobs. However, using :meth:`~telegram.ext.Application.stop_running` will give a somewhat cleaner shutdown behavior than manually raising those exceptions. On unix, the app will also shut down on receiving the signals specified by
@@ -16,6 +16,8 @@

 .. |editreplymarkup| replace:: It is currently only possible to edit messages without :attr:`telegram.Message.reply_markup` or with inline keyboards.

+.. |bcid_edit_time| replace:: Note that business messages that were not sent by the bot and do not contain an inline keyboard can only be edited within *48 hours* from the time they were sent.
+
 .. |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.

 .. |toapikwargsarg| replace:: Arbitrary keyword arguments. Can be used to store data for which there are no dedicated attributes. |toapikwargsbase|
@@ -58,10 +60,12 @@

 .. |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_url_note| replace:: Removed the deprecated argument and attribute ``thumb_url`` which made thumbnail_url mandatory.

 .. |removed_thumb_wildcard_note| replace:: Removed the deprecated arguments and attributes ``thumb_*``.

+.. |thumbnail_url_mandatory| replace:: Removal of the deprecated argument ``thumb_url`` made ``thumbnail_url`` mandatory.
+
 .. |async_context_manager| replace:: Asynchronous context manager which

 .. |reply_parameters| replace:: Description of the message to reply to.
@@ -81,3 +85,11 @@
 .. |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.
+
+.. |business_id_str_edit| replace:: Unique identifier of the business connection on behalf of which the message to be edited was sent
+
+.. |message_effect_id| replace:: Unique identifier of the message effect to be added to the message; for private chats only.
+
+.. |show_cap_above_med| replace:: :obj:`True`, if the caption must be shown above the message media.
+
+.. |tg_stars| replace:: `Telegram Stars <https://t.me/BotNews/90>`__
@@ -371,8 +371,8 @@ def main() -> None:
        entry_points=[CommandHandler("start", start)],
        states={
            SHOWING: [CallbackQueryHandler(start, pattern="^" + str(END) + "$")],
-            SELECTING_ACTION: selection_handlers,
-            SELECTING_LEVEL: selection_handlers,
+            SELECTING_ACTION: selection_handlers,  # type: ignore[dict-item]
+            SELECTING_LEVEL: selection_handlers,  # type: ignore[dict-item]
            DESCRIBING_SELF: [description_conv],
            STOPPING: [CommandHandler("start", start)],
        },
@@ -47,9 +47,9 @@ async def msg(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    # Files will be downloaded to current directory
    for data in passport_data.decrypted_data:  # This is where the data gets decrypted
        if data.type == "phone_number":
-            print("Phone: ", data.phone_number)
+            logger.info("Phone: %s", data.phone_number)
        elif data.type == "email":
-            print("Email: ", data.email)
+            logger.info("Email: %s", data.email)
        if data.type in (
            "personal_details",
            "passport",
@@ -58,7 +58,7 @@ async def msg(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
            "internal_passport",
            "address",
        ):
-            print(data.type, data.data)
+            logger.info(data.type, data.data)
        if data.type in (
            "utility_bill",
            "bank_statement",
@@ -66,28 +66,28 @@ async def msg(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
            "passport_registration",
            "temporary_registration",
        ):
-            print(data.type, len(data.files), "files")
+            logger.info(data.type, len(data.files), "files")
            for file in data.files:
                actual_file = await file.get_file()
-                print(actual_file)
+                logger.info(actual_file)
                await actual_file.download_to_drive()
        if (
            data.type in ("passport", "driver_license", "identity_card", "internal_passport")
            and data.front_side
        ):
            front_file = await data.front_side.get_file()
-            print(data.type, front_file)
+            logger.info(data.type, front_file)
            await front_file.download_to_drive()
        if data.type in ("driver_license" and "identity_card") and data.reverse_side:
            reverse_file = await data.reverse_side.get_file()
-            print(data.type, reverse_file)
+            logger.info(data.type, reverse_file)
            await reverse_file.download_to_drive()
        if (
            data.type in ("passport", "driver_license", "identity_card", "internal_passport")
            and data.selfie
        ):
            selfie_file = await data.selfie.get_file()
-            print(data.type, selfie_file)
+            logger.info(data.type, selfie_file)
            await selfie_file.download_to_drive()
        if data.translation and data.type in (
            "passport",
@@ -100,10 +100,10 @@ async def msg(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
            "passport_registration",
            "temporary_registration",
        ):
-            print(data.type, len(data.translation), "translation")
+            logger.info(data.type, len(data.translation), "translation")
            for file in data.translation:
                actual_file = await file.get_file()
-                print(actual_file)
+                logger.info(actual_file)
                await actual_file.download_to_drive()


@@ -1,7 +1,116 @@
+# PACKAGING
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+dynamic = ["version"]
+name = "python-telegram-bot"
+description = "We have made you a wrapper you can't refuse"
+readme = "README.rst"
+requires-python = ">=3.8"
+license = "LGPL-3.0-only"
+license-files = { paths = ["LICENSE", "LICENSE.dual", "LICENSE.lesser"] }
+authors = [
+    { name = "Leandro Toledo", email = "devs@python-telegram-bot.org" }
+]
+keywords = [
+    "python",
+    "telegram",
+    "bot",
+    "api",
+    "wrapper",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Communications :: Chat",
+    "Topic :: Internet",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "httpx ~= 0.27",
+]
+
+[project.urls]
+"Homepage" = "https://python-telegram-bot.org"
+"Documentation" = "https://docs.python-telegram-bot.org"
+"Bug Tracker" = "https://github.com/python-telegram-bot/python-telegram-bot/issues"
+"Source Code" = "https://github.com/python-telegram-bot/python-telegram-bot"
+"News" = "https://t.me/pythontelegrambotchannel"
+"Changelog" = "https://docs.python-telegram-bot.org/en/stable/changelog.html"
+"Support" = "https://t.me/pythontelegrambotgroup"
+
+[project.optional-dependencies]
+# Make sure to install those as additional_dependencies in the
+# pre-commit hooks for pylint & mypy
+# Also update the readme accordingly
+#
+# When dependencies release new versions and tests succeed, we should try to expand the allowed
+# versions and only increase the lower bound if necessary
+#
+# When adding new groups, make sure to update `ext` and `all` accordingly
+
+# Optional dependencies for production
+all = [
+    "python-telegram-bot[ext,http2,passport,socks]",
+]
+callback-data = [
+    # Cachetools doesn't have a strict stability policy. Let's be cautious for now.
+    "cachetools>=5.3.3,<5.6.0",
+]
+ext = [
+    "python-telegram-bot[callback-data,job-queue,rate-limiter,webhooks]",
+]
+http2 = [
+    "httpx[http2]",
+]
+job-queue = [
+    # APS doesn't have a strict stability policy. Let's be cautious for now.
+    "APScheduler~=3.10.4",
+    # pytz is required by APS and just needs the lower bound due to #2120
+    "pytz>=2018.6",
+]
+passport = [
+    "cryptography!=3.4,!=3.4.1,!=3.4.2,!=3.4.3,>=39.0.1",
+    # cffi is a dependency of cryptography and added support for python 3.13 in 1.17.0rc1
+    "cffi >= 1.17.0rc1; python_version > '3.12'"
+]
+rate-limiter = [
+    "aiolimiter~=1.1.0",
+]
+socks = [
+    "httpx[socks]",
+]
+webhooks = [
+    # tornado is rather stable, but let's not allow the next major release without prior testing
+    "tornado~=6.4",
+]
+
+
+# HATCH
+[tool.hatch.version]
+# dynamically evaluates the `__version__` variable in that file
+source = "code"
+path = "telegram/_version.py"
+search-paths = ["telegram"]
+
+[tool.hatch.build]
+packages = ["telegram"]
+
 # BLACK:
 [tool.black]
 line-length = 99
-target-version = ['py38', 'py39', 'py310', 'py311']

 # ISORT:
 [tool.isort]  # black config
@@ -11,22 +120,29 @@ line_length = 99
 # RUFF:
 [tool.ruff]
 line-length = 99
-target-version = "py38"
 show-fixes = true

 [tool.ruff.lint]
 preview = true
-explicit-preview-rules = true
+explicit-preview-rules = true  # TODO: Drop this when RUF022 and RUF023 are out of preview
 ignore = ["PLR2004", "PLR0911", "PLR0912", "PLR0913", "PLR0915", "PERF203"]
 select = ["E", "F", "I", "PL", "UP", "RUF", "PTH", "C4", "B", "PIE", "SIM", "RET", "RSE",
          "G", "ISC", "PT", "ASYNC", "TCH", "SLOT", "PERF", "PYI", "FLY", "AIR", "RUF022",
-          "RUF023", "Q", "INP", "W"]
-# Add "FURB" after it's out of preview
+          "RUF023", "Q", "INP", "W", "YTT", "DTZ", "ARG", "T20", "FURB", "DOC", "TRY", 
+          "D100", "D101", "D102", "D103", "D300", "D418", "D419", "S"]
+# Add "A (flake8-builtins)" after we drop pylint

 [tool.ruff.lint.per-file-ignores]
 "tests/*.py" = ["B018"]
-"tests/**.py" = ["RUF012", "ASYNC101"]
-"docs/**.py" = ["INP001"]
+"tests/**.py" = ["RUF012", "ASYNC230", "DTZ", "ARG", "T201", "ASYNC109", "D", "S", "TRY"]
+"telegram/**.py" = ["TRY003"]
+"telegram/ext/_applicationbuilder.py" = ["TRY004"]
+"telegram/ext/filters.py" = ["D102"]
+"docs/**.py" = ["INP001", "ARG", "D", "TRY003", "S"]
+"examples/**.py" = ["ARG", "D", "S105", "TRY003"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

 # PYLINT:
 [tool.pylint."messages control"]
@@ -48,7 +164,7 @@ exclude-protected = ["_unfrozen"]
 # PYTEST:
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "--no-success-flaky-report -rsxX"
+addopts = "--no-success-flaky-report -rX"
 filterwarnings = [
    "error",
    "ignore::DeprecationWarning",
@@ -1,4 +0,0 @@
-r requirements.txt
-r requirements-dev.txt
-r requirements-opts.txt
-r docs/requirements-docs.txt
@@ -0,0 +1,5 @@
+-e .[all]
+# needed for pre-commit hooks in the git commit command
+pre-commit
+-r requirements-unit-tests.txt
+-r docs/requirements-docs.txt
@@ -1,10 +0,0 @@
-pre-commit  # needed for pre-commit hooks in the git commit command
-
-# For the test suite
-pytest==7.4.4
-pytest-asyncio==0.21.1  # needed because pytest doesn't come with native support for coroutines as tests
-pytest-xdist==3.5.0  # xdist runs tests in parallel
-flaky  # Used for flaky tests (flaky decorator)
-beautifulsoup4  # used in test_official for parsing tg docs
-
-wheel  # required for building the wheels for releases
@@ -1,27 +0,0 @@
-# Format:
-# package_name==version # req-1, req-2, req-3!ext
-# `pip install ptb-raw[req-1/2]` will install `package_name`
-# `pip install ptb[req-1/2/3]` will also install `package_name`
-
-# Make sure to install those as additional_dependencies in the
-# pre-commit hooks for pylint & mypy
-# Also update the readme accordingly
-
-# When dependencies release new versions and tests succeed, we should try to expand the allowed
-# versions and only increase the lower bound if necessary
-
-httpx[socks] # socks
-httpx[http2] # http2
-cryptography!=3.4,!=3.4.1,!=3.4.2,!=3.4.3,>=39.0.1 # passport
-aiolimiter~=1.1.0 # rate-limiter!ext
-
-# tornado is rather stable, but let's not allow the next mayor release without prior testing
-tornado~=6.4 # webhooks!ext
-
-# Cachetools and APS don't have a strict stability policy.
-# Let's be cautious for now.
-cachetools~=5.3.3 # callback-data!ext
-APScheduler~=3.10.4 # job-queue!ext
-
-# pytz is required by APS and just needs the lower bound due to #2120
-pytz>=2018.6 # job-queue!ext
@@ -0,0 +1,19 @@
+-e .
+
+# required for building the wheels for releases
+build
+
+# For the test suite
+pytest==8.3.3
+
+# needed because pytest doesn't come with native support for coroutines as tests
+pytest-asyncio==0.21.2
+
+# xdist runs tests in parallel
+pytest-xdist==3.6.1
+
+# Used for flaky tests (flaky decorator)
+flaky>=3.8.1
+
+# used in test_official for parsing tg docs
+beautifulsoup4
@@ -1,10 +0,0 @@
-# Make sure to install those as additional_dependencies in the
-# pre-commit hooks for pylint & mypy
-# Also update the readme accordingly
-
-# When dependencies release new versions and tests succeed, we should try to expand the allowed
-# versions and only increase the lower bound if necessary
-
-# httpx has no stable release yet, but we've had no stability problems since v20.0a0 either
-# Since there have been requests to relax the bound a bit, we allow versions < 1.0.0
-httpx ~= 0.27
@@ -1,8 +1,5 @@
-[metadata]
-license_files = LICENSE, LICENSE.dual, LICENSE.lesser
-
 [flake8]
 max-line-length = 99
 ignore = W503, W605
 extend-ignore = E203, E704
-exclude = setup.py, setup_raw.py docs/source/conf.py
+exclude = docs/source/conf.py
@@ -1,131 +0,0 @@
-#!/usr/bin/env python
-"""The setup and build script for the python-telegram-bot library."""
-import subprocess
-import sys
-from collections import defaultdict
-from pathlib import Path
-from typing import Any, Dict, List, Tuple
-
-from setuptools import find_packages, setup
-
-
-def get_requirements() -> List[str]:
-    """Build the requirements list for this project"""
-    requirements_list = []
-
-    with Path("requirements.txt").open(encoding="utf-8") as reqs:
-        for install in reqs:
-            if install.startswith("#"):
-                continue
-            requirements_list.append(install.strip())
-
-    return requirements_list
-
-
-def get_packages_requirements(raw: bool = False) -> Tuple[List[str], List[str]]:
-    """Build the package & requirements list for this project"""
-    reqs = get_requirements()
-
-    exclude = ["tests*", "docs*"]
-    if raw:
-        exclude.append("telegram.ext*")
-
-    packs = find_packages(exclude=exclude)
-
-    return packs, reqs
-
-
-def get_optional_requirements(raw: bool = False) -> Dict[str, List[str]]:
-    """Build the optional dependencies"""
-    requirements = defaultdict(list)
-
-    with Path("requirements-opts.txt").open(encoding="utf-8") as reqs:
-        for line in reqs:
-            effective_line = line.strip()
-            if not effective_line or effective_line.startswith("#"):
-                continue
-            dependency, names = effective_line.split("#")
-            dependency = dependency.strip()
-            for name in names.split(","):
-                effective_name = name.strip()
-                if effective_name.endswith("!ext"):
-                    if raw:
-                        continue
-                    effective_name = effective_name[:-4]
-                    requirements["ext"].append(dependency)
-                requirements[effective_name].append(dependency)
-                requirements["all"].append(dependency)
-
-    return requirements
-
-
-def get_setup_kwargs(raw: bool = False) -> Dict[str, Any]:
-    """Builds a dictionary of kwargs for the setup function"""
-    packages, requirements = get_packages_requirements(raw=raw)
-
-    raw_ext = "-raw" if raw else ""
-    readme = Path(f'README{"_RAW" if raw else ""}.rst')
-
-    version_file = Path("telegram/_version.py").read_text(encoding="utf-8")
-    first_part = version_file.split("# SETUP.PY MARKER")[0]
-    exec(first_part)  # pylint: disable=exec-used
-
-    return {
-        "script_name": f"setup{raw_ext}.py",
-        "name": f"python-telegram-bot{raw_ext}",
-        "version": locals()["__version__"],
-        "author": "Leandro Toledo",
-        "author_email": "devs@python-telegram-bot.org",
-        "license": "LGPLv3",
-        "url": "https://python-telegram-bot.org/",
-        # Keywords supported by PyPI can be found at
-        # https://github.com/pypa/warehouse/blob/aafc5185e57e67d43487ce4faa95913dd4573e14/
-        # warehouse/templates/packaging/detail.html#L20-L58
-        "project_urls": {
-            "Documentation": "https://docs.python-telegram-bot.org",
-            "Bug Tracker": "https://github.com/python-telegram-bot/python-telegram-bot/issues",
-            "Source Code": "https://github.com/python-telegram-bot/python-telegram-bot",
-            "News": "https://t.me/pythontelegrambotchannel",
-            "Changelog": "https://docs.python-telegram-bot.org/en/stable/changelog.html",
-        },
-        "download_url": f"https://pypi.org/project/python-telegram-bot{raw_ext}/",
-        "keywords": "python telegram bot api wrapper",
-        "description": "We have made you a wrapper you can't refuse",
-        "long_description": readme.read_text(encoding="utf-8"),
-        "long_description_content_type": "text/x-rst",
-        "packages": packages,
-        "install_requires": requirements,
-        "extras_require": get_optional_requirements(raw=raw),
-        "include_package_data": True,
-        "classifiers": [
-            "Development Status :: 5 - Production/Stable",
-            "Intended Audience :: Developers",
-            "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
-            "Operating System :: OS Independent",
-            "Topic :: Software Development :: Libraries :: Python Modules",
-            "Topic :: Communications :: Chat",
-            "Topic :: Internet",
-            "Programming Language :: Python",
-            "Programming Language :: Python :: 3",
-            "Programming Language :: Python :: 3.8",
-            "Programming Language :: Python :: 3.9",
-            "Programming Language :: Python :: 3.10",
-            "Programming Language :: Python :: 3.11",
-            "Programming Language :: Python :: 3.12",
-        ],
-        "python_requires": ">=3.8",
-    }
-
-
-def main() -> None:
-    # If we're building, build ptb-raw as well
-    if set(sys.argv[1:]) in [{"bdist_wheel"}, {"sdist"}, {"sdist", "bdist_wheel"}]:
-        args = ["python", "setup_raw.py"]
-        args.extend(sys.argv[1:])
-        subprocess.run(args, check=True, capture_output=True)
-
-    setup(**get_setup_kwargs(raw=False))
-
-
-if __name__ == "__main__":
-    main()
@@ -1,8 +0,0 @@
-#!/usr/bin/env python
-"""The setup and build script for the python-telegram-bot-raw library."""
-
-from setuptools import setup
-
-from setup import get_setup_kwargs
-
-setup(**get_setup_kwargs(raw=True))
@@ -22,6 +22,15 @@ __author__ = "devs@python-telegram-bot.org"
 __all__ = (
    "Animation",
    "Audio",
+    "BackgroundFill",
+    "BackgroundFillFreeformGradient",
+    "BackgroundFillGradient",
+    "BackgroundFillSolid",
+    "BackgroundType",
+    "BackgroundTypeChatTheme",
+    "BackgroundTypeFill",
+    "BackgroundTypePattern",
+    "BackgroundTypeWallpaper",
    "Birthdate",
    "Bot",
    "BotCommand",
@@ -46,6 +55,7 @@ __all__ = (
    "CallbackQuery",
    "Chat",
    "ChatAdministratorRights",
+    "ChatBackground",
    "ChatBoost",
    "ChatBoostAdded",
    "ChatBoostRemoved",
@@ -54,6 +64,7 @@ __all__ = (
    "ChatBoostSourceGiveaway",
    "ChatBoostSourcePremium",
    "ChatBoostUpdated",
+    "ChatFullInfo",
    "ChatInviteLink",
    "ChatJoinRequest",
    "ChatLocation",
@@ -131,6 +142,10 @@ __all__ = (
    "InputMediaPhoto",
    "InputMediaVideo",
    "InputMessageContent",
+    "InputPaidMedia",
+    "InputPaidMediaPhoto",
+    "InputPaidMediaVideo",
+    "InputPollOption",
    "InputSticker",
    "InputTextMessageContent",
    "InputVenueMessageContent",
@@ -161,6 +176,12 @@ __all__ = (
    "MessageReactionCountUpdated",
    "MessageReactionUpdated",
    "OrderInfo",
+    "PaidMedia",
+    "PaidMediaInfo",
+    "PaidMediaPhoto",
+    "PaidMediaPreview",
+    "PaidMediaPurchased",
+    "PaidMediaVideo",
    "PassportData",
    "PassportElementError",
    "PassportElementErrorDataField",
@@ -184,10 +205,16 @@ __all__ = (
    "ReactionType",
    "ReactionTypeCustomEmoji",
    "ReactionTypeEmoji",
+    "ReactionTypePaid",
+    "RefundedPayment",
    "ReplyKeyboardMarkup",
    "ReplyKeyboardRemove",
    "ReplyParameters",
    "ResidentialAddress",
+    "RevenueWithdrawalState",
+    "RevenueWithdrawalStateFailed",
+    "RevenueWithdrawalStatePending",
+    "RevenueWithdrawalStateSucceeded",
    "SecureData",
    "SecureValue",
    "SentWebAppMessage",
@@ -195,6 +222,8 @@ __all__ = (
    "ShippingAddress",
    "ShippingOption",
    "ShippingQuery",
+    "StarTransaction",
+    "StarTransactions",
    "Sticker",
    "StickerSet",
    "Story",
@@ -202,6 +231,11 @@ __all__ = (
    "SwitchInlineQueryChosenChat",
    "TelegramObject",
    "TextQuote",
+    "TransactionPartner",
+    "TransactionPartnerFragment",
+    "TransactionPartnerOther",
+    "TransactionPartnerTelegramAds",
+    "TransactionPartnerUser",
    "Update",
    "User",
    "UserChatBoosts",
@@ -230,7 +264,6 @@ __all__ = (
    "warnings",
 )

-
 from . import _version, constants, error, helpers, request, warnings
 from ._birthdate import Birthdate
 from ._bot import Bot
@@ -258,6 +291,18 @@ from ._business import (
 from ._callbackquery import CallbackQuery
 from ._chat import Chat
 from ._chatadministratorrights import ChatAdministratorRights
+from ._chatbackground import (
+    BackgroundFill,
+    BackgroundFillFreeformGradient,
+    BackgroundFillGradient,
+    BackgroundFillSolid,
+    BackgroundType,
+    BackgroundTypeChatTheme,
+    BackgroundTypeFill,
+    BackgroundTypePattern,
+    BackgroundTypeWallpaper,
+    ChatBackground,
+)
 from ._chatboost import (
    ChatBoost,
    ChatBoostAdded,
@@ -269,6 +314,7 @@ from ._chatboost import (
    ChatBoostUpdated,
    UserChatBoosts,
 )
+from ._chatfullinfo import ChatFullInfo
 from ._chatinvitelink import ChatInviteLink
 from ._chatjoinrequest import ChatJoinRequest
 from ._chatlocation import ChatLocation
@@ -299,6 +345,9 @@ from ._files.inputmedia import (
    InputMediaDocument,
    InputMediaPhoto,
    InputMediaVideo,
+    InputPaidMedia,
+    InputPaidMediaPhoto,
+    InputPaidMediaVideo,
 )
 from ._files.inputsticker import InputSticker
 from ._files.location import Location
@@ -371,6 +420,14 @@ from ._messageorigin import (
    MessageOriginUser,
 )
 from ._messagereactionupdated import MessageReactionCountUpdated, MessageReactionUpdated
+from ._paidmedia import (
+    PaidMedia,
+    PaidMediaInfo,
+    PaidMediaPhoto,
+    PaidMediaPreview,
+    PaidMediaPurchased,
+    PaidMediaVideo,
+)
 from ._passport.credentials import (
    Credentials,
    DataCredentials,
@@ -399,13 +456,33 @@ from ._payment.invoice import Invoice
 from ._payment.labeledprice import LabeledPrice
 from ._payment.orderinfo import OrderInfo
 from ._payment.precheckoutquery import PreCheckoutQuery
+from ._payment.refundedpayment import RefundedPayment
 from ._payment.shippingaddress import ShippingAddress
 from ._payment.shippingoption import ShippingOption
 from ._payment.shippingquery import ShippingQuery
+from ._payment.stars import (
+    RevenueWithdrawalState,
+    RevenueWithdrawalStateFailed,
+    RevenueWithdrawalStatePending,
+    RevenueWithdrawalStateSucceeded,
+    StarTransaction,
+    StarTransactions,
+    TransactionPartner,
+    TransactionPartnerFragment,
+    TransactionPartnerOther,
+    TransactionPartnerTelegramAds,
+    TransactionPartnerUser,
+)
 from ._payment.successfulpayment import SuccessfulPayment
-from ._poll import Poll, PollAnswer, PollOption
+from ._poll import InputPollOption, Poll, PollAnswer, PollOption
 from ._proximityalerttriggered import ProximityAlertTriggered
-from ._reaction import ReactionCount, ReactionType, ReactionTypeCustomEmoji, ReactionTypeEmoji
+from ._reaction import (
+    ReactionCount,
+    ReactionType,
+    ReactionTypeCustomEmoji,
+    ReactionTypeEmoji,
+    ReactionTypePaid,
+)
 from ._reply import ExternalReplyInfo, ReplyParameters, TextQuote
 from ._replykeyboardmarkup import ReplyKeyboardMarkup
 from ._replykeyboardremove import ReplyKeyboardRemove
@@ -445,8 +522,8 @@ __version_info__: _version.Version = _version.__version_info__
 #:
 #: .. versionchanged:: 20.0
 #:    This constant was previously named ``bot_api_version``.
-__bot_api_version__: str = _version.__bot_api_version__
+__bot_api_version__: str = constants.BOT_API_VERSION
 #: :class:`typing.NamedTuple`: Shortcut for :const:`telegram.constants.BOT_API_VERSION_INFO`.
 #:
 #: .. versionadded:: 20.0
-__bot_api_version_info__: constants._BotAPIVersion = _version.__bot_api_version_info__
+__bot_api_version_info__: constants._BotAPIVersion = constants.BOT_API_VERSION_INFO
@@ -17,6 +17,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/].
 # pylint: disable=missing-module-docstring
+# ruff: noqa: T201, D100, S603, S607
 import subprocess
 import sys
 from typing import Optional
@@ -17,7 +17,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/].
 """This module contains an object that represents a Telegram Birthday."""
-from datetime import datetime
+from datetime import date
 from typing import Optional

 from telegram._telegramobject import TelegramObject
@@ -26,7 +26,7 @@ from telegram._utils.types import JSONDict

 class Birthdate(TelegramObject):
    """
-    This object represents a user's birthday.
+    This object describes the birthdate of a user.

    Objects of this class are comparable in terms of equality. Two objects of this class are
    considered equal, if their :attr:`day`, and :attr:`month` are equal.
@@ -70,19 +70,23 @@ class Birthdate(TelegramObject):

        self._freeze()

-    def to_date(self, year: Optional[int] = None) -> datetime:
-        """Return the birthdate as a datetime object.
+    def to_date(self, year: Optional[int] = None) -> date:
+        """Return the birthdate as a date object.
+
+        .. versionchanged:: 21.2
+           Now returns a :obj:`datetime.date` object instead of a :obj:`datetime.datetime` object,
+           as was originally intended.

        Args:
            year (:obj:`int`, optional): The year to use. Required, if the :attr:`year` was not
                present.

        Returns:
-            :obj:`datetime.datetime`: The birthdate as a datetime object.
+            :obj:`datetime.date`: The birthdate as a date object.
        """
        if self.year is None and year is None:
            raise ValueError(
                "The `year` argument is required if the `year` attribute was not present."
            )

-        return datetime(year or self.year, self.month, self.day)  # type: ignore[arg-type]
+        return date(year or self.year, self.month, self.day)  # type: ignore[arg-type]
@@ -84,13 +84,19 @@ class BotCommandScope(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BotCommandScope"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BotCommandScope"]:
        """Converts JSON data to the appropriate :class:`BotCommandScope` object, i.e. takes
        care of selecting the correct subclass.

        Args:
            data (Dict[:obj:`str`, ...]): The JSON data.
-            bot (:class:`telegram.Bot`): The bot associated with this object.
+            bot (:class:`telegram.Bot`, optional): The bot associated with this object. Defaults to
+                :obj:`None`, in which case shortcut methods will not be available.
+
+                .. versionchanged:: 21.4
+                   :paramref:`bot` is now optional and defaults to :obj:`None`

        Returns:
            The Telegram object.
@@ -106,7 +106,9 @@ class BusinessConnection(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BusinessConnection"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessConnection"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -175,7 +177,9 @@ class BusinessMessagesDeleted(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BusinessMessagesDeleted"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessMessagesDeleted"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -189,7 +193,7 @@ class BusinessMessagesDeleted(TelegramObject):

 class BusinessIntro(TelegramObject):
    """
-    This object represents the intro of a business account.
+    This object contains information about the start page settings of a Telegram Business account.

    Objects of this class are comparable in terms of equality.
    Two objects of this class are considered equal, if their
@@ -232,7 +236,9 @@ class BusinessIntro(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BusinessIntro"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessIntro"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -246,7 +252,7 @@ class BusinessIntro(TelegramObject):

 class BusinessLocation(TelegramObject):
    """
-    This object represents the location of a business account.
+    This object contains information about the location of a Telegram Business account.

    Objects of this class are comparable in terms of equality.
    Two objects of this class are considered equal, if their
@@ -284,7 +290,9 @@ class BusinessLocation(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BusinessLocation"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessLocation"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -298,7 +306,7 @@ class BusinessLocation(TelegramObject):

 class BusinessOpeningHoursInterval(TelegramObject):
    """
-    This object represents the time intervals describing business opening hours.
+    This object describes an interval of time during which a business is open.

    Objects of this class are comparable in terms of equality.
    Two objects of this class are considered equal, if their
@@ -390,7 +398,7 @@ class BusinessOpeningHoursInterval(TelegramObject):

 class BusinessOpeningHours(TelegramObject):
    """
-    This object represents the opening hours of a business account.
+    This object describes the opening hours of a business.

    Objects of this class are comparable in terms of equality.
    Two objects of this class are considered equal, if their
@@ -431,7 +439,9 @@ class BusinessOpeningHours(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BusinessOpeningHours"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessOpeningHours"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -93,7 +93,7 @@ class CallbackQuery(TelegramObject):
            with the callback button that originated the query.

            .. versionchanged:: 20.8
-               Objects maybe be of type :class:`telegram.MaybeInaccessibleMessage` since Bot API
+               Objects may be of type :class:`telegram.MaybeInaccessibleMessage` since Bot API
               7.0.
        data (:obj:`str` | :obj:`object`): Optional. Data associated with the callback button.
            Be aware that the message, which originated the query, can contain no callback buttons
@@ -148,7 +148,9 @@ class CallbackQuery(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["CallbackQuery"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["CallbackQuery"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -260,6 +262,8 @@ class CallbackQuery(TelegramObject):
                entities=entities,
                chat_id=None,
                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
            )
        return await self._get_message().edit_text(
            text=text,
@@ -281,6 +285,7 @@ class CallbackQuery(TelegramObject):
        reply_markup: Optional["InlineKeyboardMarkup"] = None,
        parse_mode: ODVInput[str] = DEFAULT_NONE,
        caption_entities: Optional[Sequence["MessageEntity"]] = None,
+        show_caption_above_media: Optional[bool] = None,
        *,
        read_timeout: ODVInput[float] = DEFAULT_NONE,
        write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -326,6 +331,9 @@ class CallbackQuery(TelegramObject):
                caption_entities=caption_entities,
                chat_id=None,
                message_id=None,
+                show_caption_above_media=show_caption_above_media,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
            )
        return await self._get_message().edit_caption(
            caption=caption,
@@ -337,6 +345,7 @@ class CallbackQuery(TelegramObject):
            parse_mode=parse_mode,
            api_kwargs=api_kwargs,
            caption_entities=caption_entities,
+            show_caption_above_media=show_caption_above_media,
        )

    async def edit_message_reply_markup(
@@ -385,6 +394,8 @@ class CallbackQuery(TelegramObject):
                api_kwargs=api_kwargs,
                chat_id=None,
                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
            )
        return await self._get_message().edit_reply_markup(
            reply_markup=reply_markup,
@@ -442,6 +453,8 @@ class CallbackQuery(TelegramObject):
                api_kwargs=api_kwargs,
                chat_id=None,
                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
            )
        return await self._get_message().edit_media(
            media=media,
@@ -461,6 +474,7 @@ class CallbackQuery(TelegramObject):
        horizontal_accuracy: Optional[float] = None,
        heading: Optional[int] = None,
        proximity_alert_radius: Optional[int] = None,
+        live_period: Optional[int] = None,
        *,
        location: Optional[Location] = None,
        read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -509,8 +523,11 @@ class CallbackQuery(TelegramObject):
                horizontal_accuracy=horizontal_accuracy,
                heading=heading,
                proximity_alert_radius=proximity_alert_radius,
+                live_period=live_period,
                chat_id=None,
                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
            )
        return await self._get_message().edit_live_location(
            latitude=latitude,
@@ -525,6 +542,7 @@ class CallbackQuery(TelegramObject):
            horizontal_accuracy=horizontal_accuracy,
            heading=heading,
            proximity_alert_radius=proximity_alert_radius,
+            live_period=live_period,
        )

    async def stop_message_live_location(
@@ -573,6 +591,8 @@ class CallbackQuery(TelegramObject):
                api_kwargs=api_kwargs,
                chat_id=None,
                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
            )
        return await self._get_message().stop_live_location(
            reply_markup=reply_markup,
@@ -812,6 +832,7 @@ class CallbackQuery(TelegramObject):
        protect_content: ODVInput[bool] = DEFAULT_NONE,
        message_thread_id: Optional[int] = None,
        reply_parameters: Optional["ReplyParameters"] = None,
+        show_caption_above_media: Optional[bool] = None,
        *,
        allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
        reply_to_message_id: Optional[int] = None,
@@ -858,6 +879,7 @@ class CallbackQuery(TelegramObject):
            protect_content=protect_content,
            message_thread_id=message_thread_id,
            reply_parameters=reply_parameters,
+            show_caption_above_media=show_caption_above_media,
        )

    MAX_ANSWER_TEXT_LENGTH: Final[int] = (
@@ -80,8 +80,9 @@ class ChatAdministratorRights(TelegramObject):
            .. versionadded:: 20.6
            .. versionchanged:: 21.0
                |non_optional_story_argument|
-        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit
-            stories posted by other users.
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive

            .. versionadded:: 20.6
            .. versionchanged:: 21.0
@@ -128,8 +129,9 @@ class ChatAdministratorRights(TelegramObject):
            .. versionadded:: 20.6
            .. versionchanged:: 21.0
                |non_optional_story_argument|
-        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit
-            stories posted by other users.
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive

            .. versionadded:: 20.6
            .. versionchanged:: 21.0
@@ -0,0 +1,546 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# 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
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains objects related to chat backgrounds."""
+from typing import TYPE_CHECKING, Dict, Final, Optional, Sequence, Tuple, Type
+
+from telegram import constants
+from telegram._files.document import Document
+from telegram._telegramobject import TelegramObject
+from telegram._utils import enum
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class BackgroundFill(TelegramObject):
+    """Base class for Telegram BackgroundFill Objects. It can be one of:
+
+    * :class:`telegram.BackgroundFillSolid`
+    * :class:`telegram.BackgroundFillGradient`
+    * :class:`telegram.BackgroundFillFreeformGradient`
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        type (:obj:`str`): Type of the background fill. Can be one of:
+            :attr:`~telegram.BackgroundFill.SOLID`, :attr:`~telegram.BackgroundFill.GRADIENT`
+            or :attr:`~telegram.BackgroundFill.FREEFORM_GRADIENT`.
+
+    Attributes:
+        type (:obj:`str`): Type of the background fill. Can be one of:
+            :attr:`~telegram.BackgroundFill.SOLID`, :attr:`~telegram.BackgroundFill.GRADIENT`
+            or :attr:`~telegram.BackgroundFill.FREEFORM_GRADIENT`.
+    """
+
+    __slots__ = ("type",)
+
+    SOLID: Final[constants.BackgroundFillType] = constants.BackgroundFillType.SOLID
+    """:const:`telegram.constants.BackgroundFillType.SOLID`"""
+    GRADIENT: Final[constants.BackgroundFillType] = constants.BackgroundFillType.GRADIENT
+    """:const:`telegram.constants.BackgroundFillType.GRADIENT`"""
+    FREEFORM_GRADIENT: Final[constants.BackgroundFillType] = (
+        constants.BackgroundFillType.FREEFORM_GRADIENT
+    )
+    """:const:`telegram.constants.BackgroundFillType.FREEFORM_GRADIENT`"""
+
+    def __init__(
+        self,
+        type: str,  # pylint: disable=redefined-builtin
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required by all subclasses
+        self.type: str = enum.get_member(constants.BackgroundFillType, type, type)
+
+        self._id_attrs = (self.type,)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BackgroundFill"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        _class_mapping: Dict[str, Type[BackgroundFill]] = {
+            cls.SOLID: BackgroundFillSolid,
+            cls.GRADIENT: BackgroundFillGradient,
+            cls.FREEFORM_GRADIENT: BackgroundFillFreeformGradient,
+        }
+
+        if cls is BackgroundFill and data.get("type") in _class_mapping:
+            return _class_mapping[data.pop("type")].de_json(data=data, bot=bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class BackgroundFillSolid(BackgroundFill):
+    """
+    The background is filled using the selected color.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`color` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        color (:obj:`int`): The color of the background fill in the `RGB24` format.
+
+    Attributes:
+        type (:obj:`str`): Type of the background fill. Always
+            :attr:`~telegram.BackgroundFill.SOLID`.
+        color (:obj:`int`): The color of the background fill in the `RGB24` format.
+    """
+
+    __slots__ = ("color",)
+
+    def __init__(
+        self,
+        color: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.SOLID, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.color: int = color
+
+            self._id_attrs = (self.color,)
+
+
+class BackgroundFillGradient(BackgroundFill):
+    """
+    The background is a gradient fill.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`top_color`, :attr:`bottom_color`
+    and :attr:`rotation_angle` are equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        top_color (:obj:`int`): Top color of the gradient in the `RGB24` format.
+        bottom_color (:obj:`int`): Bottom color of the gradient in the `RGB24` format.
+        rotation_angle (:obj:`int`): Clockwise rotation angle of the background
+            fill in degrees;
+            0-:tg-const:`telegram.constants.BackgroundFillLimit.MAX_ROTATION_ANGLE`.
+
+
+    Attributes:
+        type (:obj:`str`): Type of the background fill. Always
+            :attr:`~telegram.BackgroundFill.GRADIENT`.
+        top_color (:obj:`int`): Top color of the gradient in the `RGB24` format.
+        bottom_color (:obj:`int`): Bottom color of the gradient in the `RGB24` format.
+        rotation_angle (:obj:`int`): Clockwise rotation angle of the background
+            fill in degrees;
+            0-:tg-const:`telegram.constants.BackgroundFillLimit.MAX_ROTATION_ANGLE`.
+    """
+
+    __slots__ = ("bottom_color", "rotation_angle", "top_color")
+
+    def __init__(
+        self,
+        top_color: int,
+        bottom_color: int,
+        rotation_angle: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.GRADIENT, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.top_color: int = top_color
+            self.bottom_color: int = bottom_color
+            self.rotation_angle: int = rotation_angle
+
+            self._id_attrs = (self.top_color, self.bottom_color, self.rotation_angle)
+
+
+class BackgroundFillFreeformGradient(BackgroundFill):
+    """
+    The background is a freeform gradient that rotates after every message in the chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`colors` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        colors (Sequence[:obj:`int`]): A list of the 3 or 4 base colors that are used to
+            generate the freeform gradient in the `RGB24` format
+
+    Attributes:
+        type (:obj:`str`): Type of the background fill. Always
+            :attr:`~telegram.BackgroundFill.FREEFORM_GRADIENT`.
+        colors (Sequence[:obj:`int`]): A list of the 3 or 4 base colors that are used to
+            generate the freeform gradient in the `RGB24` format
+    """
+
+    __slots__ = ("colors",)
+
+    def __init__(
+        self,
+        colors: Sequence[int],
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.FREEFORM_GRADIENT, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.colors: Tuple[int, ...] = parse_sequence_arg(colors)
+
+            self._id_attrs = (self.colors,)
+
+
+class BackgroundType(TelegramObject):
+    """Base class for Telegram BackgroundType Objects. It can be one of:
+
+    * :class:`telegram.BackgroundTypeFill`
+    * :class:`telegram.BackgroundTypeWallpaper`
+    * :class:`telegram.BackgroundTypePattern`
+    * :class:`telegram.BackgroundTypeChatTheme`.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        type (:obj:`str`): Type of the background. Can be one of:
+            :attr:`~telegram.BackgroundType.FILL`, :attr:`~telegram.BackgroundType.WALLPAPER`
+            :attr:`~telegram.BackgroundType.PATTERN` or
+            :attr:`~telegram.BackgroundType.CHAT_THEME`.
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Can be one of:
+            :attr:`~telegram.BackgroundType.FILL`, :attr:`~telegram.BackgroundType.WALLPAPER`
+            :attr:`~telegram.BackgroundType.PATTERN` or
+            :attr:`~telegram.BackgroundType.CHAT_THEME`.
+
+    """
+
+    __slots__ = ("type",)
+
+    FILL: Final[constants.BackgroundTypeType] = constants.BackgroundTypeType.FILL
+    """:const:`telegram.constants.BackgroundTypeType.FILL`"""
+    WALLPAPER: Final[constants.BackgroundTypeType] = constants.BackgroundTypeType.WALLPAPER
+    """:const:`telegram.constants.BackgroundTypeType.WALLPAPER`"""
+    PATTERN: Final[constants.BackgroundTypeType] = constants.BackgroundTypeType.PATTERN
+    """:const:`telegram.constants.BackgroundTypeType.PATTERN`"""
+    CHAT_THEME: Final[constants.BackgroundTypeType] = constants.BackgroundTypeType.CHAT_THEME
+    """:const:`telegram.constants.BackgroundTypeType.CHAT_THEME`"""
+
+    def __init__(
+        self,
+        type: str,  # pylint: disable=redefined-builtin
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required by all subclasses
+        self.type: str = enum.get_member(constants.BackgroundTypeType, type, type)
+
+        self._id_attrs = (self.type,)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BackgroundType"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        _class_mapping: Dict[str, Type[BackgroundType]] = {
+            cls.FILL: BackgroundTypeFill,
+            cls.WALLPAPER: BackgroundTypeWallpaper,
+            cls.PATTERN: BackgroundTypePattern,
+            cls.CHAT_THEME: BackgroundTypeChatTheme,
+        }
+
+        if cls is BackgroundType and data.get("type") in _class_mapping:
+            return _class_mapping[data.pop("type")].de_json(data=data, bot=bot)
+
+        if "fill" in data:
+            data["fill"] = BackgroundFill.de_json(data.get("fill"), bot)
+
+        if "document" in data:
+            data["document"] = Document.de_json(data.get("document"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class BackgroundTypeFill(BackgroundType):
+    """
+    The background is automatically filled based on the selected colors.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`fill` and :attr:`dark_theme_dimming` are equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        fill (:class:`telegram.BackgroundFill`): The background fill.
+        dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a
+            percentage;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`.
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Always
+            :attr:`~telegram.BackgroundType.FILL`.
+        fill (:class:`telegram.BackgroundFill`): The background fill.
+        dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a
+            percentage;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`.
+    """
+
+    __slots__ = ("dark_theme_dimming", "fill")
+
+    def __init__(
+        self,
+        fill: BackgroundFill,
+        dark_theme_dimming: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.FILL, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.fill: BackgroundFill = fill
+            self.dark_theme_dimming: int = dark_theme_dimming
+
+            self._id_attrs = (self.fill, self.dark_theme_dimming)
+
+
+class BackgroundTypeWallpaper(BackgroundType):
+    """
+    The background is a wallpaper in the `JPEG` format.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`document` and :attr:`dark_theme_dimming` are equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        document (:class:`telegram.Document`): Document with the wallpaper
+        dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a
+            percentage;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`.
+        is_blurred (:obj:`bool`, optional): :obj:`True`, if the wallpaper is downscaled to fit
+            in a 450x450 square and then box-blurred with radius 12
+        is_moving (:obj:`bool`, optional): :obj:`True`, if the background moves slightly
+            when the device is tilted
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Always
+            :attr:`~telegram.BackgroundType.WALLPAPER`.
+        document (:class:`telegram.Document`): Document with the wallpaper
+        dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a
+            percentage;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`.
+        is_blurred (:obj:`bool`): Optional. :obj:`True`, if the wallpaper is downscaled to fit
+            in a 450x450 square and then box-blurred with radius 12
+        is_moving (:obj:`bool`): Optional. :obj:`True`, if the background moves slightly
+            when the device is tilted
+    """
+
+    __slots__ = ("dark_theme_dimming", "document", "is_blurred", "is_moving")
+
+    def __init__(
+        self,
+        document: Document,
+        dark_theme_dimming: int,
+        is_blurred: Optional[bool] = None,
+        is_moving: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.WALLPAPER, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            # Required
+            self.document: Document = document
+            self.dark_theme_dimming: int = dark_theme_dimming
+            # Optionals
+            self.is_blurred: Optional[bool] = is_blurred
+            self.is_moving: Optional[bool] = is_moving
+
+            self._id_attrs = (self.document, self.dark_theme_dimming)
+
+
+class BackgroundTypePattern(BackgroundType):
+    """
+    The background is a `PNG` or `TGV` (gzipped subset of `SVG` with `MIME` type
+    `"application/x-tgwallpattern"`) pattern to be combined with the background fill
+    chosen by the user.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`document` and :attr:`fill` and :attr:`intensity` are equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        document (:class:`telegram.Document`): Document with the pattern.
+        fill (:class:`telegram.BackgroundFill`): The background fill that is combined with
+            the pattern.
+        intensity (:obj:`int`): Intensity of the pattern when it is shown above the filled
+            background;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_INTENSITY`.
+        is_inverted (:obj:`int`, optional): :obj:`True`, if the background fill must be applied
+            only to the pattern itself. All other pixels are black in this case. For dark
+            themes only.
+        is_moving (:obj:`bool`, optional): :obj:`True`, if the background moves slightly
+            when the device is tilted.
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Always
+            :attr:`~telegram.BackgroundType.PATTERN`.
+        document (:class:`telegram.Document`): Document with the pattern.
+        fill (:class:`telegram.BackgroundFill`): The background fill that is combined with
+            the pattern.
+        intensity (:obj:`int`): Intensity of the pattern when it is shown above the filled
+            background;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_INTENSITY`.
+        is_inverted (:obj:`int`): Optional. :obj:`True`, if the background fill must be applied
+            only to the pattern itself. All other pixels are black in this case. For dark
+            themes only.
+        is_moving (:obj:`bool`): Optional. :obj:`True`, if the background moves slightly
+            when the device is tilted.
+    """
+
+    __slots__ = (
+        "document",
+        "fill",
+        "intensity",
+        "is_inverted",
+        "is_moving",
+    )
+
+    def __init__(
+        self,
+        document: Document,
+        fill: BackgroundFill,
+        intensity: int,
+        is_inverted: Optional[bool] = None,
+        is_moving: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.PATTERN, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            # Required
+            self.document: Document = document
+            self.fill: BackgroundFill = fill
+            self.intensity: int = intensity
+            # Optionals
+            self.is_inverted: Optional[bool] = is_inverted
+            self.is_moving: Optional[bool] = is_moving
+
+            self._id_attrs = (self.document, self.fill, self.intensity)
+
+
+class BackgroundTypeChatTheme(BackgroundType):
+    """
+    The background is taken directly from a built-in chat theme.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`theme_name` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        theme_name (:obj:`str`): Name of the chat theme, which is usually an emoji.
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Always
+            :attr:`~telegram.BackgroundType.CHAT_THEME`.
+        theme_name (:obj:`str`): Name of the chat theme, which is usually an emoji.
+    """
+
+    __slots__ = ("theme_name",)
+
+    def __init__(
+        self,
+        theme_name: str,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.CHAT_THEME, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.theme_name: str = theme_name
+
+            self._id_attrs = (self.theme_name,)
+
+
+class ChatBackground(TelegramObject):
+    """
+    This object represents a chat background.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is  equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        type (:class:`telegram.BackgroundType`): Type of the background.
+
+    Attributes:
+        type (:class:`telegram.BackgroundType`): Type of the background.
+    """
+
+    __slots__ = ("type",)
+
+    def __init__(
+        self,
+        type: BackgroundType,  # pylint: disable=redefined-builtin
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.type: BackgroundType = type
+
+        self._id_attrs = (self.type,)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBackground"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["type"] = BackgroundType.de_json(data.get("type"), bot)
+
+        return super().de_json(data=data, bot=bot)
@@ -110,7 +110,9 @@ class ChatBoostSource(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["ChatBoostSource"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBoostSource"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -185,15 +187,22 @@ class ChatBoostSourceGiftCode(ChatBoostSource):

 class ChatBoostSourceGiveaway(ChatBoostSource):
    """
-    The boost was obtained by the creation of a Telegram Premium giveaway. This boosts the chat 4
-    times for the duration of the corresponding Telegram Premium subscription.
+    The boost was obtained by the creation of a Telegram Premium giveaway or a Telegram Star.
+    This boosts the chat 4 times for the duration of the corresponding Telegram Premium
+    subscription for Telegram Premium giveaways and :attr:`prize_star_count` / 500 times for
+    one year for Telegram Star giveaways.

    .. versionadded:: 20.8

    Args:
        giveaway_message_id (:obj:`int`): Identifier of a message in the chat with the giveaway;
            the message could have been deleted already. May be 0 if the message isn't sent yet.
-        user (:class:`telegram.User`, optional): User that won the prize in the giveaway if any.
+        user (:class:`telegram.User`, optional): User that won the prize in the giveaway if any;
+            for Telegram Premium giveaways only.
+        prize_star_count (:obj:`int`, optional): The number of Telegram Stars to be split between
+            giveaway winners; for Telegram Star giveaways only.
+
+            .. versionadded:: 21.6
        is_unclaimed (:obj:`bool`, optional): :obj:`True`, if the giveaway was completed, but
            there was no user to win the prize.

@@ -203,17 +212,22 @@ class ChatBoostSourceGiveaway(ChatBoostSource):
        giveaway_message_id (:obj:`int`): Identifier of a message in the chat with the giveaway;
            the message could have been deleted already. May be 0 if the message isn't sent yet.
        user (:class:`telegram.User`): Optional. User that won the prize in the giveaway if any.
+        prize_star_count (:obj:`int`): Optional. The number of Telegram Stars to be split between
+            giveaway winners; for Telegram Star giveaways only.
+
+            .. versionadded:: 21.6
        is_unclaimed (:obj:`bool`): Optional. :obj:`True`, if the giveaway was completed, but
            there was no user to win the prize.
    """

-    __slots__ = ("giveaway_message_id", "is_unclaimed", "user")
+    __slots__ = ("giveaway_message_id", "is_unclaimed", "prize_star_count", "user")

    def __init__(
        self,
        giveaway_message_id: int,
        user: Optional[User] = None,
        is_unclaimed: Optional[bool] = None,
+        prize_star_count: Optional[int] = None,
        *,
        api_kwargs: Optional[JSONDict] = None,
    ):
@@ -222,6 +236,7 @@ class ChatBoostSourceGiveaway(ChatBoostSource):
        with self._unfrozen():
            self.giveaway_message_id: int = giveaway_message_id
            self.user: Optional[User] = user
+            self.prize_star_count: Optional[int] = prize_star_count
            self.is_unclaimed: Optional[bool] = is_unclaimed


@@ -275,7 +290,9 @@ class ChatBoost(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["ChatBoost"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBoost"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -325,7 +342,9 @@ class ChatBoostUpdated(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["ChatBoostUpdated"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBoostUpdated"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -382,7 +401,9 @@ class ChatBoostRemoved(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["ChatBoostRemoved"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBoostRemoved"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -429,7 +450,9 @@ class UserChatBoosts(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["UserChatBoosts"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["UserChatBoosts"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

@@ -0,0 +1,549 @@
+#!/usr/bin/env python
+# pylint: disable=redefined-builtin
+#
+# A library that provides a Python interface to the Telegram Bot API
+# 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
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram ChatFullInfo."""
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+
+from telegram._birthdate import Birthdate
+from telegram._chat import Chat, _ChatBase
+from telegram._chatlocation import ChatLocation
+from telegram._chatpermissions import ChatPermissions
+from telegram._files.chatphoto import ChatPhoto
+from telegram._reaction import ReactionType
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot, BusinessIntro, BusinessLocation, BusinessOpeningHours, Message
+
+
+class ChatFullInfo(_ChatBase):
+    """
+    This object contains full information about a chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`~telegram.Chat.id` is equal.
+
+    .. versionadded:: 21.2
+
+    .. versionchanged:: 21.3
+        Explicit support for all shortcut methods known from :class:`telegram.Chat` on this
+        object. Previously those were only available because this class inherited from
+        :class:`telegram.Chat`.
+
+    Args:
+        id (:obj:`int`): Unique identifier for this chat.
+        type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`,
+            :attr:`SUPERGROUP` or :attr:`CHANNEL`.
+        accent_color_id (:obj:`int`, optional): Identifier of the
+            :class:`accent color <telegram.constants.AccentColor>` for the chat name and
+            backgrounds of the chat photo, reply header, and link preview. See `accent colors`_
+            for more details.
+
+            .. versionadded:: 20.8
+        max_reaction_count (:obj:`int`): The maximum number of reactions that can be set on a
+            message in the chat.
+
+            .. versionadded:: 21.2
+        title (:obj:`str`, optional): Title, for supergroups, channels and group chats.
+        username (:obj:`str`, optional): Username, for private chats, supergroups and channels if
+            available.
+        first_name (:obj:`str`, optional): First name of the other party in a private chat.
+        last_name (:obj:`str`, optional): Last name of the other party in a private chat.
+        is_forum (:obj:`bool`, optional): :obj:`True`, if the supergroup chat is a forum
+            (has topics_ enabled).
+
+            .. versionadded:: 20.0
+        photo (:class:`telegram.ChatPhoto`, optional): Chat photo.
+        active_usernames (Sequence[:obj:`str`], optional):  If set, the list of all `active chat
+            usernames <https://telegram.org/blog/topics-in-groups-collectible-usernames\
+            #collectible-usernames>`_; for private chats, supergroups and channels.
+
+            .. versionadded:: 20.0
+        birthdate (:class:`telegram.Birthdate`, optional): For private chats,
+            the date of birth of the user.
+
+            .. versionadded:: 21.1
+        business_intro (:class:`telegram.BusinessIntro`, optional): For private chats with
+            business accounts, the intro of the business.
+
+            .. versionadded:: 21.1
+        business_location (:class:`telegram.BusinessLocation`, optional): For private chats with
+            business accounts, the location of the business.
+
+            .. versionadded:: 21.1
+        business_opening_hours (:class:`telegram.BusinessOpeningHours`, optional): For private
+            chats with business accounts, the opening hours of the business.
+
+            .. versionadded:: 21.1
+        personal_chat (:class:`telegram.Chat`, optional): For private chats, the personal channel
+            of the user.
+
+            .. versionadded:: 21.1
+        available_reactions (Sequence[:class:`telegram.ReactionType`], optional): List of available
+            reactions allowed in the chat. If omitted, then all of
+            :const:`telegram.constants.ReactionEmoji` are allowed.
+
+            .. versionadded:: 20.8
+        background_custom_emoji_id (:obj:`str`, optional): Custom emoji identifier of emoji chosen
+            by the chat for the reply header and link preview background.
+
+            .. versionadded:: 20.8
+        profile_accent_color_id (:obj:`int`, optional): Identifier of the
+            :class:`accent color <telegram.constants.ProfileAccentColor>` for the chat's profile
+            background. See profile `accent colors`_ for more details.
+
+            .. versionadded:: 20.8
+        profile_background_custom_emoji_id (:obj:`str`, optional): Custom emoji identifier of
+            the emoji chosen by the chat for its profile background.
+
+            .. versionadded:: 20.8
+        emoji_status_custom_emoji_id (:obj:`str`, optional): Custom emoji identifier of emoji
+            status of the chat or the other party in a private chat.
+
+            .. versionadded:: 20.0
+        emoji_status_expiration_date (:class:`datetime.datetime`, optional): Expiration date of
+            emoji status of the chat or the other party in a private chat, as a datetime object,
+            if any.
+
+            |datetime_localization|
+
+            .. versionadded:: 20.5
+        bio (:obj:`str`, optional): Bio of the other party in a private chat.
+        has_private_forwards (:obj:`bool`, optional): :obj:`True`, if privacy settings of the other
+            party in the private chat allows to use ``tg://user?id=<user_id>`` links only in chats
+            with the user.
+
+            .. versionadded:: 13.9
+        has_restricted_voice_and_video_messages (:obj:`bool`, optional): :obj:`True`, if the
+            privacy settings of the other party restrict sending voice and video note messages
+            in the private chat.
+
+            .. versionadded:: 20.0
+        join_to_send_messages (:obj:`bool`, optional): :obj:`True`, if users need to join the
+            supergroup before they can send messages.
+
+            .. versionadded:: 20.0
+        join_by_request (:obj:`bool`, optional): :obj:`True`, if all users directly joining the
+            supergroup without using an invite link need to be approved by supergroup
+            administrators.
+
+            .. versionadded:: 20.0
+        description (:obj:`str`, optional): Description, for groups, supergroups and channel chats.
+        invite_link (:obj:`str`, optional): Primary invite link, for groups, supergroups and
+            channel.
+        pinned_message (:class:`telegram.Message`, optional): The most recent pinned message
+            (by sending date).
+        permissions (:class:`telegram.ChatPermissions`): Optional. Default chat member permissions,
+            for groups and supergroups.
+        slow_mode_delay (:obj:`int`, optional): For supergroups, the minimum allowed delay between
+            consecutive messages sent by each unprivileged user.
+        unrestrict_boost_count (:obj:`int`, optional): For supergroups, the minimum number of
+            boosts that a non-administrator user needs to add in order to ignore slow mode and chat
+            permissions.
+
+            .. versionadded:: 21.0
+        message_auto_delete_time (:obj:`int`, optional): The time after which all messages sent to
+            the chat will be automatically deleted; in seconds.
+
+            .. versionadded:: 13.4
+        has_aggressive_anti_spam_enabled (:obj:`bool`, optional): :obj:`True`, if aggressive
+            anti-spam checks are enabled in the supergroup. The field is only available to chat
+            administrators.
+
+            .. versionadded:: 20.0
+        has_hidden_members (:obj:`bool`, optional): :obj:`True`, if non-administrators can only
+            get the list of bots and administrators in the chat.
+
+            .. versionadded:: 20.0
+        has_protected_content (:obj:`bool`, optional): :obj:`True`, if messages from the chat can't
+            be forwarded to other chats.
+
+            .. versionadded:: 13.9
+        has_visible_history (:obj:`bool`, optional): :obj:`True`, if new chat members will have
+            access to old messages; available only to chat administrators.
+
+            .. versionadded:: 20.8
+        sticker_set_name (:obj:`str`, optional): For supergroups, name of group sticker set.
+        can_set_sticker_set (:obj:`bool`, optional): :obj:`True`, if the bot can change group the
+            sticker set.
+        custom_emoji_sticker_set_name (:obj:`str`, optional): For supergroups, the name of the
+            group's custom emoji sticker set. Custom emoji from this set can be used by all users
+            and bots in the group.
+
+            .. versionadded:: 21.0
+        linked_chat_id (:obj:`int`, optional): Unique identifier for the linked chat, i.e. the
+            discussion group identifier for a channel and vice versa; for supergroups and channel
+            chats.
+        location (:class:`telegram.ChatLocation`, optional): For supergroups, the location to which
+            the supergroup is connected.
+        can_send_paid_media (:obj:`bool`, optional): :obj:`True`, if paid media messages can be
+            sent or forwarded to the channel chat. The field is available only for channel chats.
+
+            .. versionadded:: 21.4
+
+    Attributes:
+        id (:obj:`int`): Unique identifier for this chat.
+        type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`,
+            :attr:`SUPERGROUP` or :attr:`CHANNEL`.
+        accent_color_id (:obj:`int`): Optional. Identifier of the
+            :class:`accent color <telegram.constants.AccentColor>` for the chat name and
+            backgrounds of the chat photo, reply header, and link preview. See `accent colors`_
+            for more details.
+
+            .. versionadded:: 20.8
+        max_reaction_count (:obj:`int`): The maximum number of reactions that can be set on a
+            message in the chat.
+
+            .. versionadded:: 21.2
+        title (:obj:`str`, optional): Title, for supergroups, channels and group chats.
+        username (:obj:`str`, optional): Username, for private chats, supergroups and channels if
+            available.
+        first_name (:obj:`str`, optional): First name of the other party in a private chat.
+        last_name (:obj:`str`, optional): Last name of the other party in a private chat.
+        is_forum (:obj:`bool`, optional): :obj:`True`, if the supergroup chat is a forum
+            (has topics_ enabled).
+
+            .. versionadded:: 20.0
+        photo (:class:`telegram.ChatPhoto`): Optional. Chat photo.
+        active_usernames (Tuple[:obj:`str`]): Optional. If set, the list of all `active chat
+            usernames <https://telegram.org/blog/topics-in-groups-collectible-usernames\
+            #collectible-usernames>`_; for private chats, supergroups and channels.
+
+            This list is empty if the chat has no active usernames or this chat instance was not
+            obtained via :meth:`~telegram.Bot.get_chat`.
+
+            .. versionadded:: 20.0
+        birthdate (:class:`telegram.Birthdate`): Optional. For private chats,
+            the date of birth of the user.
+
+            .. versionadded:: 21.1
+        business_intro (:class:`telegram.BusinessIntro`): Optional. For private chats with
+            business accounts, the intro of the business.
+
+            .. versionadded:: 21.1
+        business_location (:class:`telegram.BusinessLocation`): Optional. For private chats with
+            business accounts, the location of the business.
+
+            .. versionadded:: 21.1
+        business_opening_hours (:class:`telegram.BusinessOpeningHours`): Optional. For private
+            chats with business accounts, the opening hours of the business.
+
+            .. versionadded:: 21.1
+        personal_chat (:class:`telegram.Chat`): Optional. For private chats, the personal channel
+            of the user.
+
+            .. versionadded:: 21.1
+        available_reactions (Tuple[:class:`telegram.ReactionType`]): Optional. List of available
+            reactions allowed in the chat. If omitted, then all of
+            :const:`telegram.constants.ReactionEmoji` are allowed.
+
+            .. versionadded:: 20.8
+        background_custom_emoji_id (:obj:`str`): Optional. Custom emoji identifier of emoji chosen
+            by the chat for the reply header and link preview background.
+
+            .. versionadded:: 20.8
+        profile_accent_color_id (:obj:`int`): Optional. Identifier of the
+            :class:`accent color <telegram.constants.ProfileAccentColor>` for the chat's profile
+            background. See profile `accent colors`_ for more details.
+
+            .. versionadded:: 20.8
+        profile_background_custom_emoji_id (:obj:`str`): Optional. Custom emoji identifier of
+            the emoji chosen by the chat for its profile background.
+
+            .. versionadded:: 20.8
+        emoji_status_custom_emoji_id (:obj:`str`): Optional. Custom emoji identifier of emoji
+            status of the chat or the other party in a private chat.
+
+            .. versionadded:: 20.0
+        emoji_status_expiration_date (:class:`datetime.datetime`): Optional. Expiration date of
+            emoji status of the chat or the other party in a private chat, as a datetime object,
+            if any.
+
+            |datetime_localization|
+
+            .. versionadded:: 20.5
+        bio (:obj:`str`): Optional. Bio of the other party in a private chat.
+        has_private_forwards (:obj:`bool`): Optional. :obj:`True`, if privacy settings of the other
+            party in the private chat allows to use ``tg://user?id=<user_id>`` links only in chats
+            with the user.
+
+            .. versionadded:: 13.9
+        has_restricted_voice_and_video_messages (:obj:`bool`): Optional. :obj:`True`, if the
+            privacy settings of the other party restrict sending voice and video note messages
+            in the private chat.
+
+            .. versionadded:: 20.0
+        join_to_send_messages (:obj:`bool`): Optional. :obj:`True`, if users need to join
+            the supergroup before they can send messages.
+
+            .. versionadded:: 20.0
+        join_by_request (:obj:`bool`): Optional. :obj:`True`, if all users directly joining the
+            supergroup without using an invite link need to be approved by supergroup
+            administrators.
+
+            .. versionadded:: 20.0
+        description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats.
+        invite_link (:obj:`str`): Optional. Primary invite link, for groups, supergroups and
+            channel.
+        pinned_message (:class:`telegram.Message`): Optional. The most recent pinned message
+            (by sending date).
+        permissions (:class:`telegram.ChatPermissions`): Optional. Default chat member permissions,
+            for groups and supergroups.
+        slow_mode_delay (:obj:`int`): Optional. For supergroups, the minimum allowed delay between
+            consecutive messages sent by each unprivileged user.
+        unrestrict_boost_count (:obj:`int`): Optional. For supergroups, the minimum number of
+            boosts that a non-administrator user needs to add in order to ignore slow mode and chat
+            permissions.
+
+            .. versionadded:: 21.0
+        message_auto_delete_time (:obj:`int`): Optional. The time after which all messages sent to
+            the chat will be automatically deleted; in seconds.
+
+            .. versionadded:: 13.4
+        has_aggressive_anti_spam_enabled (:obj:`bool`): Optional. :obj:`True`, if aggressive
+            anti-spam checks are enabled in the supergroup. The field is only available to chat
+            administrators.
+
+            .. versionadded:: 20.0
+        has_hidden_members (:obj:`bool`): Optional. :obj:`True`, if non-administrators can only
+            get the list of bots and administrators in the chat.
+
+            .. versionadded:: 20.0
+        has_protected_content (:obj:`bool`): Optional. :obj:`True`, if messages from the chat can't
+            be forwarded to other chats.
+
+            .. versionadded:: 13.9
+        has_visible_history (:obj:`bool`): Optional. :obj:`True`, if new chat members will have
+            access to old messages; available only to chat administrators.
+
+            .. versionadded:: 20.8
+        sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set.
+        can_set_sticker_set (:obj:`bool`): Optional. :obj:`True`, if the bot can change group the
+            sticker set.
+        custom_emoji_sticker_set_name (:obj:`str`): Optional. For supergroups, the name of the
+            group's custom emoji sticker set. Custom emoji from this set can be used by all users
+            and bots in the group.
+
+            .. versionadded:: 21.0
+        linked_chat_id (:obj:`int`): Optional. Unique identifier for the linked chat, i.e. the
+            discussion group identifier for a channel and vice versa; for supergroups and channel
+            chats.
+        location (:class:`telegram.ChatLocation`): Optional. For supergroups, the location to which
+            the supergroup is connected.
+        can_send_paid_media (:obj:`bool`): Optional. :obj:`True`, if paid media messages can be
+            sent or forwarded to the channel chat. The field is available only for channel chats.
+
+            .. versionadded:: 21.4
+
+    .. _accent colors: https://core.telegram.org/bots/api#accent-colors
+    .. _topics: https://telegram.org/blog/topics-in-groups-collectible-usernames#topics-in-groups
+    """
+
+    __slots__ = (
+        "accent_color_id",
+        "active_usernames",
+        "available_reactions",
+        "background_custom_emoji_id",
+        "bio",
+        "birthdate",
+        "business_intro",
+        "business_location",
+        "business_opening_hours",
+        "can_send_paid_media",
+        "can_set_sticker_set",
+        "custom_emoji_sticker_set_name",
+        "description",
+        "emoji_status_custom_emoji_id",
+        "emoji_status_expiration_date",
+        "has_aggressive_anti_spam_enabled",
+        "has_hidden_members",
+        "has_private_forwards",
+        "has_protected_content",
+        "has_restricted_voice_and_video_messages",
+        "has_visible_history",
+        "invite_link",
+        "join_by_request",
+        "join_to_send_messages",
+        "linked_chat_id",
+        "location",
+        "max_reaction_count",
+        "message_auto_delete_time",
+        "permissions",
+        "personal_chat",
+        "photo",
+        "pinned_message",
+        "profile_accent_color_id",
+        "profile_background_custom_emoji_id",
+        "slow_mode_delay",
+        "sticker_set_name",
+        "unrestrict_boost_count",
+    )
+
+    def __init__(
+        self,
+        id: int,
+        type: str,
+        accent_color_id: int,
+        max_reaction_count: int,
+        title: Optional[str] = None,
+        username: Optional[str] = None,
+        first_name: Optional[str] = None,
+        last_name: Optional[str] = None,
+        is_forum: Optional[bool] = None,
+        photo: Optional[ChatPhoto] = None,
+        active_usernames: Optional[Sequence[str]] = None,
+        birthdate: Optional[Birthdate] = None,
+        business_intro: Optional["BusinessIntro"] = None,
+        business_location: Optional["BusinessLocation"] = None,
+        business_opening_hours: Optional["BusinessOpeningHours"] = None,
+        personal_chat: Optional["Chat"] = None,
+        available_reactions: Optional[Sequence[ReactionType]] = None,
+        background_custom_emoji_id: Optional[str] = None,
+        profile_accent_color_id: Optional[int] = None,
+        profile_background_custom_emoji_id: Optional[str] = None,
+        emoji_status_custom_emoji_id: Optional[str] = None,
+        emoji_status_expiration_date: Optional[datetime] = None,
+        bio: Optional[str] = None,
+        has_private_forwards: Optional[bool] = None,
+        has_restricted_voice_and_video_messages: Optional[bool] = None,
+        join_to_send_messages: Optional[bool] = None,
+        join_by_request: Optional[bool] = None,
+        description: Optional[str] = None,
+        invite_link: Optional[str] = None,
+        pinned_message: Optional["Message"] = None,
+        permissions: Optional[ChatPermissions] = None,
+        slow_mode_delay: Optional[int] = None,
+        unrestrict_boost_count: Optional[int] = None,
+        message_auto_delete_time: Optional[int] = None,
+        has_aggressive_anti_spam_enabled: Optional[bool] = None,
+        has_hidden_members: Optional[bool] = None,
+        has_protected_content: Optional[bool] = None,
+        has_visible_history: Optional[bool] = None,
+        sticker_set_name: Optional[str] = None,
+        can_set_sticker_set: Optional[bool] = None,
+        custom_emoji_sticker_set_name: Optional[str] = None,
+        linked_chat_id: Optional[int] = None,
+        location: Optional[ChatLocation] = None,
+        can_send_paid_media: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(
+            id=id,
+            type=type,
+            title=title,
+            username=username,
+            first_name=first_name,
+            last_name=last_name,
+            is_forum=is_forum,
+            api_kwargs=api_kwargs,
+        )
+
+        # Required and unique to this class-
+        with self._unfrozen():
+            self.max_reaction_count: int = max_reaction_count
+            self.photo: Optional[ChatPhoto] = photo
+            self.bio: Optional[str] = bio
+            self.has_private_forwards: Optional[bool] = has_private_forwards
+            self.description: Optional[str] = description
+            self.invite_link: Optional[str] = invite_link
+            self.pinned_message: Optional[Message] = pinned_message
+            self.permissions: Optional[ChatPermissions] = permissions
+            self.slow_mode_delay: Optional[int] = slow_mode_delay
+            self.message_auto_delete_time: Optional[int] = (
+                int(message_auto_delete_time) if message_auto_delete_time is not None else None
+            )
+            self.has_protected_content: Optional[bool] = has_protected_content
+            self.has_visible_history: Optional[bool] = has_visible_history
+            self.sticker_set_name: Optional[str] = sticker_set_name
+            self.can_set_sticker_set: Optional[bool] = can_set_sticker_set
+            self.linked_chat_id: Optional[int] = linked_chat_id
+            self.location: Optional[ChatLocation] = location
+            self.join_to_send_messages: Optional[bool] = join_to_send_messages
+            self.join_by_request: Optional[bool] = join_by_request
+            self.has_restricted_voice_and_video_messages: Optional[bool] = (
+                has_restricted_voice_and_video_messages
+            )
+            self.active_usernames: Tuple[str, ...] = parse_sequence_arg(active_usernames)
+            self.emoji_status_custom_emoji_id: Optional[str] = emoji_status_custom_emoji_id
+            self.emoji_status_expiration_date: Optional[datetime] = emoji_status_expiration_date
+            self.has_aggressive_anti_spam_enabled: Optional[bool] = (
+                has_aggressive_anti_spam_enabled
+            )
+            self.has_hidden_members: Optional[bool] = has_hidden_members
+            self.available_reactions: Optional[Tuple[ReactionType, ...]] = parse_sequence_arg(
+                available_reactions
+            )
+            self.accent_color_id: Optional[int] = accent_color_id
+            self.background_custom_emoji_id: Optional[str] = background_custom_emoji_id
+            self.profile_accent_color_id: Optional[int] = profile_accent_color_id
+            self.profile_background_custom_emoji_id: Optional[str] = (
+                profile_background_custom_emoji_id
+            )
+            self.unrestrict_boost_count: Optional[int] = unrestrict_boost_count
+            self.custom_emoji_sticker_set_name: Optional[str] = custom_emoji_sticker_set_name
+            self.birthdate: Optional[Birthdate] = birthdate
+            self.personal_chat: Optional[Chat] = personal_chat
+            self.business_intro: Optional[BusinessIntro] = business_intro
+            self.business_location: Optional[BusinessLocation] = business_location
+            self.business_opening_hours: Optional[BusinessOpeningHours] = business_opening_hours
+            self.can_send_paid_media: Optional[bool] = can_send_paid_media
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatFullInfo"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["emoji_status_expiration_date"] = from_timestamp(
+            data.get("emoji_status_expiration_date"), tzinfo=loc_tzinfo
+        )
+
+        data["photo"] = ChatPhoto.de_json(data.get("photo"), bot)
+
+        from telegram import (  # pylint: disable=import-outside-toplevel
+            BusinessIntro,
+            BusinessLocation,
+            BusinessOpeningHours,
+            Message,
+        )
+
+        data["pinned_message"] = Message.de_json(data.get("pinned_message"), bot)
+        data["permissions"] = ChatPermissions.de_json(data.get("permissions"), bot)
+        data["location"] = ChatLocation.de_json(data.get("location"), bot)
+        data["available_reactions"] = ReactionType.de_list(data.get("available_reactions"), bot)
+        data["birthdate"] = Birthdate.de_json(data.get("birthdate"), bot)
+        data["personal_chat"] = Chat.de_json(data.get("personal_chat"), bot)
+        data["business_intro"] = BusinessIntro.de_json(data.get("business_intro"), bot)
+        data["business_location"] = BusinessLocation.de_json(data.get("business_location"), bot)
+        data["business_opening_hours"] = BusinessOpeningHours.de_json(
+            data.get("business_opening_hours"), bot
+        )
+
+        return super().de_json(data=data, bot=bot)
@@ -69,6 +69,16 @@ class ChatInviteLink(TelegramObject):
            created using this link.

            .. versionadded:: 13.8
+        subscription_period (:obj:`int`, optional): The number of seconds the subscription will be
+            active for before the next payment.
+
+            .. versionadded:: 21.5
+        subscription_price (:obj:`int`, optional): The amount of Telegram Stars a user must pay
+            initially and after each subsequent subscription period to be a member of the chat
+            using the link.
+
+            .. versionadded:: 21.5
+
    Attributes:
        invite_link (:obj:`str`): The invite link. If the link was created by another chat
            administrator, then the second part of the link will be replaced with ``'…'``.
@@ -96,6 +106,15 @@ class ChatInviteLink(TelegramObject):
            created using this link.

            .. versionadded:: 13.8
+        subscription_period (:obj:`int`): Optional. The number of seconds the subscription will be
+            active for before the next payment.
+
+            .. versionadded:: 21.5
+        subscription_price (:obj:`int`): Optional. The amount of Telegram Stars a user must pay
+            initially and after each subsequent subscription period to be a member of the chat
+            using the link.
+
+            .. versionadded:: 21.5

    """

@@ -109,6 +128,8 @@ class ChatInviteLink(TelegramObject):
        "member_limit",
        "name",
        "pending_join_request_count",
+        "subscription_period",
+        "subscription_price",
    )

    def __init__(
@@ -122,6 +143,8 @@ class ChatInviteLink(TelegramObject):
        member_limit: Optional[int] = None,
        name: Optional[str] = None,
        pending_join_request_count: Optional[int] = None,
+        subscription_period: Optional[int] = None,
+        subscription_price: Optional[int] = None,
        *,
        api_kwargs: Optional[JSONDict] = None,
    ):
@@ -140,6 +163,9 @@ class ChatInviteLink(TelegramObject):
        self.pending_join_request_count: Optional[int] = (
            int(pending_join_request_count) if pending_join_request_count is not None else None
        )
+        self.subscription_period: Optional[int] = subscription_period
+        self.subscription_price: Optional[int] = subscription_price
+
        self._id_attrs = (
            self.invite_link,
            self.creates_join_request,
@@ -151,7 +177,9 @@ class ChatInviteLink(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["ChatInviteLink"]:
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatInviteLink"]:
        """See :meth:`telegram.TelegramObject.de_json`."""
        data = cls._parse_data(data)

--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Bibo-Joshi	e314e78d06	Bump Version to v21.6 (#4486 )	2024-09-19 20:17:08 +02:00
Harshil	67a97ae5a7	API 7.10 (#4461 , #4460 , #4463 , #4464 ) Co-authored-by: aelkheir <90580077+aelkheir@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-09-17 18:09:19 +02:00
dependabot[bot]	9248c539d0	Bump `pytest` from 8.3.2 to 8.3.3 (#4475 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-09-14 08:17:31 +02:00
Bibo-Joshi	6b5e46cc08	Improve Type Completeness (#4466 )	2024-09-14 08:16:39 +02:00
Harshil	b3155b2e55	Update Python 3.13 Test Suite to RC2 (#4471 )	2024-09-13 19:32:22 +02:00
Bibo-Joshi	ec909e62cf	Enforce the `offline_bot` Fixture in `Test*WithoutRequest` (#4465 )	2024-09-13 19:10:09 +02:00
Bibo-Joshi	1223e851c3	Add Parameter `httpx_kwargs` to `HTTPXRequest` (#4451 )	2024-09-11 22:34:18 +02:00
Bibo-Joshi	0b352b043e	Make Tests for `telegram.ext` Independent of Networking (#4454 )	2024-09-09 07:32:32 +02:00
Bibo-Joshi	b9d2efdec5	Rename Testing Base Classes (#4453 )	2024-09-03 05:24:25 +02:00
Bibo-Joshi	8c692d1008	Bump Version to v21.5 (#4449 )	2024-09-01 15:25:34 +02:00
Bibo-Joshi	970d2ab085	Documentation Improvements (#4400 , #4448 ) Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Palaptin <100526200+Palaptin@users.noreply.github.com>	2024-09-01 14:12:41 +02:00
dependabot[bot]	60b439ff42	Update `cachetools` requirement from <5.5.0,>=5.3.3 to >=5.3.3,<5.6.0 (#4437 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-09-01 10:35:11 +02:00
Bibo-Joshi	b17b0d248d	Improve PyPI Automation (#4375 )	2024-09-01 09:34:20 +02:00
Bibo-Joshi	e0f36867cc	Add `MessageEntity.shift_entities` and `MessageEntity.concatenate` (#4376 )	2024-09-01 09:33:12 +02:00
Poolitzer	01f689373c	Bot API 7.9 (#4429 ) Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>	2024-09-01 09:32:42 +02:00
Bibo-Joshi	1e05381133	Update Test Suite to New Test Channel Setup (#4435 )	2024-08-26 20:16:35 +02:00
Martin Hjelmare	a05362c79a	Remove Surplus Logging from `Updater` Network Loop (#4432 )	2024-08-19 16:40:28 +02:00
Palaptin	fbf07bf126	Improve Fixture Usage in `test_message.py` (#4431 )	2024-08-19 16:14:01 +02:00
Harshil	3017bf00a4	Update Python 3.13 Test Suite to RC1 (#4415 )	2024-08-13 17:58:08 +02:00
dependabot[bot]	374875c786	Bump `sphinx` from 7.4.7 to 8.0.2 and `furo` from 2024.7.18 to 2024.8.6 (#4412 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>	2024-08-13 17:57:26 +02:00
Harshil	8f9db63f4f	Bump `ruff` and Add New Rules (#4416 ) Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-08-07 21:56:46 +02:00
Harshil	1787586902	Bugfix for "Available In" Admonitions (#4413 )	2024-08-03 22:47:38 +02:00
dependabot[bot]	9c50a38512	Bump `test-summary/action` from 2.3 to 2.4 (#4410 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <dependabot[bot]@users.noreply.github.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2024-08-03 17:27:39 +02:00
Bibo-Joshi	3a49372591	Add Parameter `read_file_handle` to `InputFile` (#4388 )	2024-08-02 22:28:38 +02:00
dependabot[bot]	e637d1733c	Bump `pytest` from 8.2.2 to 8.3.2 (#4403 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-08-02 14:01:31 +02:00
dependabot[bot]	b89f5d6126	Bump `dependabot/fetch-metadata` from 2.1.0 to 2.2.0 (#4411 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <dependabot[bot]@users.noreply.github.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2024-08-02 14:00:26 +02:00
Bibo-Joshi	6578c76068	API 7.8 (#4408 )	2024-08-02 13:43:27 +02:00
Bibo-Joshi	a967dbe37a	Document Return Types of `RequestData` Members (#4396 )	2024-08-02 13:41:39 +02:00
dependabot[bot]	af76a8485f	Update `cachetools` requirement from ~=5.3.3 to >=5.3.3,<5.5.0 (#4390 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-07-24 21:03:54 +02:00
MOHD YUSUF	8a205b10c0	Add Introductory Paragraphs to Telegram Types Subsections (#4389 ) Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2024-07-24 21:02:53 +02:00
dependabot[bot]	6d70c56159	Bump `sphinx` from 7.3.7 to 7.4.7 (#4395 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-07-21 21:23:21 +02:00
Pablo Martínez	0913b859d7	Add Internal Constants for Encodings (#4378 )	2024-07-21 21:13:30 +02:00
Bibo-Joshi	c3f17bb18e	Start Adapting to RTD Addons (#4386 )	2024-07-21 21:12:30 +02:00
dependabot[bot]	006a290b7b	Bump `furo` from 2024.5.6 to 2024.7.18 (#4392 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-07-21 21:05:01 +02:00
Jãїиãм	422993b8ab	Add Parameter `game_pattern` to `CallbackQueryHandler` (#4353 )	2024-07-13 21:26:44 +02:00
Bibo-Joshi	2ac4e009d0	Bump version to v21.4 (#4371 )	2024-07-12 17:40:42 +02:00
Bibo-Joshi	efe1392e73	Automate PyPI Releases (#4364 )	2024-07-12 16:44:41 +02:00
Bibo-Joshi	0a673e8f7e	Documentation Improvements (#4303 ) Co-authored-by: poolitzer <github@poolitzer.eu>	2024-07-12 16:33:42 +02:00
Bibo-Joshi	86c8cae40d	Restructure Readme (#4362 )	2024-07-10 20:36:47 +02:00
Bibo-Joshi	f737702544	Use a Composite Action for Testing Type Completeness (#4367 )	2024-07-10 17:33:04 +02:00
Bibo-Joshi	06f1da576e	Stabilize Some Concurrency Usages in Test Suite (#4360 )	2024-07-10 17:11:22 +02:00
Bibo-Joshi	7a470d57c8	Add a Test Case for `MenuButton` (#4363 )	2024-07-10 17:10:33 +02:00
Poolitzer	1714bfd8f6	Deprecate Inclusion of `successful_payment` in `Message.effective_attachment` (#4365 )	2024-07-09 23:33:57 +02:00
Poolitzer	71e4015e22	API 7.7 (#4356 ) Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-07-09 10:35:18 +02:00
Harshil	52237cf00c	Add `filters.PAID_MEDIA` (#4357 )	2024-07-07 22:23:31 +02:00
Harshil	dba7866aab	API 7.6 (#4333 , #4341 , #4342 , #4334 , #4335 , #4344 , #4348 , #4351 ) Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-07-07 13:08:52 +02:00
Bibo-Joshi	98bed6f01a	Log Received Data on Deserialization Errors (#4304 )	2024-07-06 16:09:04 +02:00
Antares	42d7c8c477	Add `MessageEntity.adjust_message_entities_to_utf_16` Utility Function (#4323 ) Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>	2024-07-06 16:08:29 +02:00
Poolitzer	8018e5ff3f	Extend `SuccessfulPayment` Test (#4349 )	2024-07-05 23:03:54 +02:00
Harshil	c39839b026	Small Fixes for `test_stars.py` (#4347 )	2024-07-05 18:44:41 +02:00
Harshil	4213c12c5b	Use Python 3.13 Beta 3 in Test Suite (#4336 ) Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2024-07-03 19:04:45 +02:00
pre-commit-ci[bot]	97226b1ae3	Bump `pre-commit` Hooks to Latest Versions (#4337 ) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2024-07-03 18:29:09 +02:00
Harshil	146ec54a00	API 7.5 (#4312 , #4311 , #4315 , #4328 , #4316 ) Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-07-01 21:45:37 +02:00
Bibo-Joshi	df8aae0a38	Fix Link-Check Workflow (#4332 )	2024-07-01 20:43:54 +02:00
Bibo-Joshi	4ccc80f9c1	Make Argument `bot` of `TelegramObject.de_json` Optional (#4320 )	2024-07-01 19:59:54 +02:00
Harshil	cfc75bb08b	Bump `ruff` and Add New Rules (#4329 )	2024-06-30 18:22:12 +02:00
Palaptin	51ef571a07	Add Lower Bound for `flaky` Dependency (#4322 )	2024-06-23 20:15:37 +02:00
Harshil	9ce0f49882	Add Support for Python 3.13 Beta (#4253 ) Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-06-18 22:25:02 +02:00
dependabot[bot]	5b1e7399a4	Bump `pytest` from 8.2.1 to 8.2.2 (#4294 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-06-18 22:20:47 +02:00
Harshil	a83046e1ec	Add `mise-en-place` to `.gitignore` (#4300 )	2024-06-17 19:32:47 +02:00
Bibo-Joshi	44e8292838	Drop `python-telegram-bot-raw` And Switch to `pyproject.toml` Based Packaging (#4288 )	2024-06-15 10:29:19 +02:00
Hinrich Mahler	a9f6afd015	Bump version to v21.3	2024-06-07 16:52:22 +02:00
Bibo-Joshi	78c945d485	Documentation Improvements (#4264 )	2024-06-07 16:13:55 +02:00
Trijeet Modak	9e70ac8b7a	Add Parameter `chat_id` to `ChatMemberHandler` (#4290 )	2024-06-06 17:31:45 +02:00
Harshil	cf728496e4	API 7.4 (#4276 , #4278 , #4279 , #4280 , #4286 , #4283 , #4285 ) Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-06-03 19:39:31 +02:00
dependabot[bot]	078d775250	Bump `pytest` from 8.2.0 to 8.2.1 (#4272 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-06-03 19:25:54 +02:00
Bibo-Joshi	57298aa076	Deprecate `python-telegram-bot-raw` (#4270 )	2024-06-01 21:19:38 +02:00
Bibo-Joshi	2c299bb109	Add `setuptools` to `requirements-dev.txt` (#4282 )	2024-05-30 21:02:41 +02:00
Harshil	c1c5438f37	Remove Functionality Deprecated in Bot API 7.3 (#4266 )	2024-05-29 19:59:23 +02:00
Bibo-Joshi	6ba7a097f4	Update Settings for pre-commit.ci (#4265 )	2024-05-22 17:43:45 +02:00
Hinrich Mahler	6fc45a803d	Bump version to v21.2	2024-05-20 17:23:38 +02:00
Harshil	512a0b7417	Add Version to `PTBDeprecationWarning` (#4262 )	2024-05-20 16:12:34 +02:00
Bibo-Joshi	7d952d8707	Documentation Improvements (#4217 ) Co-authored-by: poolitzer <github@poolitzer.eu>	2024-05-20 15:53:04 +02:00
Bibo-Joshi	b496fabf62	Call `Application.post_stop` Only if `Application.stop` was called (#4211 )	2024-05-20 15:52:30 +02:00
Bibo-Joshi	637b8e260b	Handle `SystemExit` raised in Handlers (#4157 )	2024-05-20 15:27:08 +02:00
Bibo-Joshi	912fe45d8c	Handle Exceptions in building `CallbackContext` (#4222 )	2024-05-20 15:25:56 +02:00
Bibo-Joshi	805b7bff32	API 7.3 (#4243 , #4248 , #4247 , #4242 , #4246 , #4260 ) Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Abdelrahman Elkheir <90580077+aelkheir@users.noreply.github.com>	2024-05-20 15:25:25 +02:00
Harshil	f3bd0f1462	Add New Rules to `ruff` Config (#4250 )	2024-05-12 09:13:20 +02:00
dependabot[bot]	5b0e0b5f78	Bump `furo` from 2024.4.27 to 2024.5.6 (#4252 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-05-11 15:37:54 +02:00
Bibo-Joshi	c4623c4476	Make `Birthdate.to_date` Return a `datetime.date` Object (#4251 ) Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>	2024-05-10 22:23:19 +02:00
Bibo-Joshi	ee6e82d7ad	Remove Functionality Deprecated by Bot API 7.2 (#4245 )	2024-05-10 17:42:22 +02:00
pre-commit-ci[bot]	c34f4811ea	`pre-commit` autoupdate (#4239 ) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>	2024-05-07 07:42:09 +02:00
dependabot[bot]	d768abdd6b	Bump `pytest` from 8.1.1 to 8.2.0 (#4231 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-05-06 22:36:18 +02:00
dependabot[bot]	2561ffd16b	Bump `dependabot/fetch-metadata` from 2.0.0 to 2.1.0 (#4228 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <dependabot[bot]@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-05-06 22:35:52 +02:00
Bibo-Joshi	622fdf7fa3	Adapt Test Suite to Changes in Error Messages (#4238 )	2024-05-06 22:35:11 +02:00
dependabot[bot]	615f1bf20b	Bump `pytest-asyncio` from 0.21.1 to 0.21.2 (#4232 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-05-05 10:03:38 +02:00
dependabot[bot]	7a8b1be5a4	Bump `pytest-xdist` from 3.6.0 to 3.6.1 (#4233 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-05-04 17:30:18 +02:00
dependabot[bot]	3a8ace2e8b	Bump `furo` from 2024.1.29 to 2024.4.27 (#4230 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-05-04 11:12:26 +02:00
dependabot[bot]	169bd47de3	Bump `srvaroa/labeler` from 1.10.0 to 1.10.1 (#4227 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-05-04 11:07:21 +02:00
dependabot[bot]	a956dcc6a4	Bump `pytest` from 7.4.4 to 8.1.1 (#4218 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2024-04-28 22:32:20 +02:00
Bibo-Joshi	ee88973fee	Bump `pytest-xdist` from 3.5.0 to 3.6.0 Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-04-20 10:44:39 +02:00
dependabot[bot]	8f9fc65be0	Bump `sphinx` from 7.2.6 to 7.3.7 (#4215 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-04-20 09:22:42 +02:00
				`@@ -1 +0,0 @@`
				`include LICENSE LICENSE.lesser requirements.txt requirements-opts.txt README_RAW.rst telegram/py.typed`
				`@@ -0,0 +1 @@`
				.. \|app_run_shutdown\| replace:: The app will shut down when :exc:`KeyboardInterrupt` or :exc:`SystemExit` is raised. This also works from within handlers, error handlers and jobs. However, using :meth:`~telegram.ext.Application.stop_running` will give a somewhat cleaner shutdown behavior than manually raising those exceptions. On unix, the app will also shut down on receiving the signals specified by