Bump Version to v21.9 (#4601)

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>

.github/CONTRIBUTING.rst

@@ -210,7 +210,7 @@ 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 installed as explained above.
+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

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,7 +1,7 @@
 name: Bug Report
 description: Create a report to help us improve
-title: "[BUG]"
-labels: ["bug :bug:"]
+labels: ["📋 triage"]
+type: '🐛 bug'
 
 body:
   - type: markdown

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -1,7 +1,7 @@
 name: Feature Request
 description: Suggest an idea for this project
-title: "[FEATURE]"
-labels: ["enhancement"]
+labels: ["📋 triage"]
+type: '💡 feature'
 
 body:
   - type: textarea

.github/ISSUE_TEMPLATE/question.yml

@@ -1,7 +1,7 @@
 name: Question
 description: Get help with errors or general questions
-title: "[QUESTION]"
 labels: ["question"]
+type: '❔ question'
 
 body:
   - type: markdown

.github/labeler.yml

@@ -3,7 +3,7 @@
 version: 1
 
 labels:
-- label: "dependencies"
+- label: "⚙️ dependencies"
   authors: ["dependabot[bot]", "pre-commit-ci[bot]"]
-- label: "code quality ✨"
+- label: "🛠 code-quality"
   authors: ["pre-commit-ci[bot]"]

.github/workflows/dependabot-prs.yml

@@ -16,7 +16,7 @@ jobs:
 
     - name: Fetch Dependabot metadata
       id: dependabot-metadata
-      uses: dependabot/fetch-metadata@v2.1.0
+      uses: dependabot/fetch-metadata@v2.2.0
 
     - uses: actions/checkout@v4
       with:

.github/workflows/docs-linkcheck.yml

@@ -3,6 +3,9 @@ on:
   schedule:
     # First day of month at 05:46 in every 2nd month
     - cron: '46 5 1 */2 *'
+  pull_request:
+    paths:
+      - .github/workflows/docs-linkcheck.yml
 
 jobs:
   test-sphinx-build:
@@ -10,7 +13,7 @@ jobs:
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: [3.9]
+        python-version: ['3.10']
         os: [ubuntu-latest]
       fail-fast: False
     steps:

.github/workflows/docs.yml

@@ -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:

.github/workflows/labelling.yml

@@ -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.1
+    - uses: srvaroa/labeler@v1.12.0
       # Config file at .github/labeler.yml
       env:
         GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/release_pypi.yml

@@ -1,17 +1,15 @@
 name: Publish to PyPI
 
 on:
-  # Run on any tag
-  push:
-    tags:
-      - '**'
-  # manually trigger the workflow - for testing only
+  # 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
@@ -29,11 +27,15 @@ jobs:
         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
-    # only publish to PyPI on tag pushes
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
     needs:
       - build
     runs-on: ubuntu-latest
@@ -52,42 +54,11 @@ jobs:
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
-  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-pypi
-      - publish-to-test-pypi
-    # run if either of the publishing jobs ran successfully
-    # see also:
-    # https://github.com/actions/runner/issues/491#issuecomment-850884422
-    if: |
-      always() && (
-        (needs.publish-to-pypi.result == 'success') ||
-        (needs.publish-to-test-pypi.result == 'success')
-      )
 
     permissions:
       id-token: write  # IMPORTANT: mandatory for sigstore
@@ -106,7 +77,7 @@ jobs:
               sha1sum $file > $file.sha1
           done
       - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@v2.1.1
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
         with:
           inputs: >-
             ./dist/*.tar.gz
@@ -120,13 +91,8 @@ jobs:
   github-release:
     name: Upload to GitHub Release
     needs:
-      - publish-to-pypi
+      - build
       - compute-signatures
-    if: |
-      always() && (
-        (needs.publish-to-pypi.result == 'success') &&
-        (needs.compute-signatures.result == 'success')
-      )
 
     runs-on: ubuntu-latest
 
@@ -142,63 +108,22 @@ jobs:
       - name: Create GitHub Release
         env:
           GITHUB_TOKEN: ${{ github.token }}
-        # Create a GitHub Release for this tag. The description can be changed later, as for now
+          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
-          '${{ github.ref_name }}'
+          '${{ 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
-          '${{ github.ref_name }}' dist/**
-          --repo '${{ github.repository }}'
-
-  github-test-release:
-    name: Upload to GitHub Release Draft
-    needs:
-      - publish-to-test-pypi
-      - compute-signatures
-    if: |
-      always() && (
-        (needs.publish-to-test-pypi.result == 'success') &&
-        (needs.compute-signatures.result == 'success')
-      )
-    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 }}
-        # 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
-          '${{ github.ref_name }}'
-          --repo '${{ github.repository }}'
-          --generate-notes
-          --draft
-      - name: Upload artifact signatures to GitHub Release
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-        # Upload to GitHub Release using the `gh` CLI.
-        # `dist/` contains the built packages, and the
-        # sigstore-produced signatures and certificates.
-        run: >-
-          gh release upload
-          '${{ github.ref_name }}' dist/**
+          '${{ env.TAG }}' dist/**
           --repo '${{ github.repository }}'

.github/workflows/release_test_pypi.yml

@@ -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 }}'

.github/workflows/stale.yml

@@ -13,7 +13,7 @@ jobs:
           days-before-stale: 3
           days-before-close: 2
           days-before-pr-stale: -1
-          stale-issue-label: 'stale'
+          stale-issue-label: '📋 stale'
           only-labels: 'question'
           stale-issue-message: ''
           close-issue-message: 'This issue has been automatically closed due to inactivity. Feel free to comment in order to reopen or ask again in our Telegram support group at https://t.me/pythontelegrambotgroup.'

.github/workflows/test_official.yml

@@ -41,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

.github/workflows/type_completeness.yml

@@ -14,7 +14,7 @@ jobs:
     name:   test-type-completeness
     runs-on: ubuntu-latest
     steps:
-      - uses: Bibo-Joshi/pyright-type-completeness@1.0.0
+      - uses: Bibo-Joshi/pyright-type-completeness@1.0.1
         with:
           package-name: telegram
           python-version: 3.12

.github/workflows/type_completeness_monthly.yml

@@ -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.1
+        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)

.github/workflows/unit_tests.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13.0-beta.3']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
         os: [ubuntu-latest, windows-latest, macos-latest]
       fail-fast: False
     steps:
@@ -37,7 +37,7 @@ jobs:
           python -W ignore -m pip install -U pytest-cov
           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]
+          python -W ignore -m pip install pytest-xdist
 
       - name: Test with pytest
         # We run 4 different suites here
@@ -57,21 +57,17 @@ jobs:
           # - without socks support
           # - without http2 support
           TO_TEST="test_no_passport.py or test_datetime.py or test_defaults.py or test_jobqueue.py or test_applicationbuilder.py or test_ratelimiter.py or test_updater.py or test_callbackdatacache.py or test_request.py"
-          pytest -v --cov -k "${TO_TEST}"
-          # Rerun only failed tests (--lf), and don't run any tests if none failed (--lfnf=none)
-          pytest -v --cov --cov-append -k "${TO_TEST}" --lf --lfnf=none --junit-xml=.test_report_no_optionals.xml
-          # No tests were selected, convert returned status code to 0
-          opt_dep_status=$(( $? == 5 ? 0 : $? ))
+          pytest -v --cov -k "${TO_TEST}" --junit-xml=.test_report_no_optionals_junit.xml
+          opt_dep_status=$?
 
           # Test the rest
           export TEST_WITH_OPT_DEPS='true'
           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.
-          pytest -v --cov --cov-append -n auto --dist loadfile
-          pytest -v --cov --cov-append -n auto --dist loadfile --lf --lfnf=none --junit-xml=.test_report_optionals.xml
-          main_status=$(( $? == 5 ? 0 : $? ))
+          # `-n auto --dist worksteal` uses pytest-xdist to run tests on multiple CPU
+          # workers. Increasing number of workers has little effect on test duration, but it seems
+          # to increase flakyness.
+          pytest -v --cov --cov-append -n auto --dist worksteal --junit-xml=.test_report_optionals_junit.xml
+          main_status=$?
           # exit with non-zero status if any of the two pytest runs failed
           exit $(( ${opt_dep_status} || ${main_status} ))
         env:
@@ -83,17 +79,23 @@ 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_no_optionals.xml
-            .test_report_optionals.xml
+            .test_report_no_optionals_junit.xml
+            .test_report_optionals_junit.xml
 
       - name: Submit coverage
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         with:
           env_vars: OS,PYTHON
           name: ${{ matrix.os }}-${{ matrix.python-version }}
           fail_ci_if_error: true
           token: ${{ secrets.CODECOV_TOKEN }}
+      - name: Upload test results to Codecov
+        uses: codecov/test-results-action@v1
+        if: ${{ !cancelled() }}
+        with:
+          files: .test_report_no_optionals_junit.xml,.test_report_optionals_junit.xml
+          token: ${{ secrets.CODECOV_TOKEN }}

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ ci:
 
 repos:
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.5.0'
+    rev: 'v0.5.6'
     hooks:
     -   id: ruff
         name: ruff
@@ -15,8 +15,8 @@ repos:
           - httpx~=0.27
           - tornado~=6.4
           - APScheduler~=3.10.4
-          - cachetools~=5.3.3
-          - aiolimiter~=1.1.0
+          - cachetools>=5.3.3,<5.5.0
+          - aiolimiter~=1.1,<1.3
 -   repo: https://github.com/psf/black-pre-commit-mirror
     rev: 24.4.2
     hooks:
@@ -29,7 +29,7 @@ repos:
     hooks:
     -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v3.2.4
+    rev: v3.3.2
     hooks:
     -   id: pylint
         files: ^(?!(tests|docs)).*\.py$
@@ -37,8 +37,8 @@ repos:
           - httpx~=0.27
           - tornado~=6.4
           - APScheduler~=3.10.4
-          - cachetools~=5.3.3
-          - aiolimiter~=1.1.0
+          - cachetools>=5.3.3,<5.5.0
+          - aiolimiter~=1.1,<1.3
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.10.1
@@ -53,8 +53,8 @@ repos:
           - httpx~=0.27
           - tornado~=6.4
           - APScheduler~=3.10.4
-          - cachetools~=5.3.3
-          - aiolimiter~=1.1.0
+          - cachetools>=5.3.3,<5.5.0
+          - aiolimiter~=1.1,<1.3
           - . # this basically does `pip install -e .`
     - id: mypy
       name: mypy-examples
@@ -65,14 +65,14 @@ 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.16.0
     hooks:
     -   id: pyupgrade
         args:
-          - --py38-plus
+          - --py39-plus
 -   repo: https://github.com/pycqa/isort
     rev: 5.13.2
     hooks:

AUTHORS.rst

@@ -23,6 +23,7 @@ The following wonderful people contributed directly or indirectly to this projec
 
 - `Abdelrahman <https://github.com/aelkheir>`_
 - `Abshar <https://github.com/abxhr>`_
+- `Abubakar Alaya <https://github.com/Ecode2>`_
 - `Alateas <https://github.com/alateas>`_
 - `Ales Dokshanin <https://github.com/alesdokshanin>`_
 - `Alexandre <https://github.com/xTudoS>`_
@@ -60,6 +61,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>`_
@@ -79,6 +81,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `LRezende <https://github.com/lrezende>`_
 - `Luca Bellanti <https://github.com/Trifase>`_
 - `Lucas Molinari <https://github.com/lucasmolinari>`_
+- `Luis Pérez <https://github.com/nemacysts>`_
 - `macrojames <https://github.com/macrojames>`_
 - `Matheus Lemos <https://github.com/mlemosf>`_
 - `Michael Dix <https://github.com/Eisberge>`_
@@ -86,6 +89,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 +100,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>`_
@@ -107,11 +112,13 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Rahiel Kasim <https://github.com/rahiel>`_
 - `Riko Naka <https://github.com/rikonaka>`_
 - `Rizlas <https://github.com/rizlas>`_
+- `Snehashish Biswas <https://github.com/Snehashish06>`_
 - `Sahil Sharma <https://github.com/sahilsharma811>`_
 - `Sam Mosleh <https://github.com/sam-mosleh>`_
 - `Sascha <https://github.com/saschalalala>`_
 - `Shelomentsev D <https://github.com/shelomentsevd>`_
 - `Shivam Saini <https://github.com/shivamsn97>`_
+- `Siloé Garcez <https://github.com/roast-lord>`_
 - `Simon Schürrle <https://github.com/SitiSchu>`_
 - `sooyhwang <https://github.com/sooyhwang>`_
 - `syntx <https://github.com/syntx>`_

CHANGES.rst

@@ -4,6 +4,182 @@
 Changelog
 =========
 
+Version 21.9
+============
+
+*Released 2024-12-07*
+
+This is the technical changelog for version 21.9. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 8.1 (:pr:`4594` closes :issue:`4592`)
+
+Minor Changes
+-------------
+
+- Use ``MessageLimit.DEEP_LINK_LENGTH`` in ``helpers.create_deep_linked_url`` (:pr:`4597` by `nemacysts <https://github.com/nemacysts>`_)
+- Allow ``Sequence`` Input for ``allowed_updates`` in ``Application`` and ``Updater`` Methods (:pr:`4589` by `nemacysts <https://github.com/nemacysts>`_)
+
+Dependency Updates
+------------------
+
+- Update ``aiolimiter`` requirement from ~=1.1.0 to >=1.1,<1.3 (:pr:`4595`)
+- Bump ``pytest`` from 8.3.3 to 8.3.4 (:pr:`4596`)
+- Bump ``codecov/codecov-action`` from 4 to 5 (:pr:`4585`)
+- Bump ``pylint`` to v3.3.2 to Improve Python 3.13 Support (:pr:`4590` by `nemacysts <https://github.com/nemacysts>`_)
+- Bump ``srvaroa/labeler`` from 1.11.1 to 1.12.0 (:pr:`4586`)
+
+Version 21.8
+============
+*Released 2024-12-01*
+
+This is the technical changelog for version 21.8. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 8.0 (:pr:`4568`, :pr:`4566` closes :issue:`4567`, :pr:`4572`, :pr:`4571`, :pr:`4570`, :pr:`4576`, :pr:`4574`)
+
+Documentation Improvements
+--------------------------
+
+- Documentation Improvements (:pr:`4565` by `Snehashish06 <https://github.com/Snehashish06>`_, :pr:`4573`)
+
+Version 21.7
+============
+*Released 2024-11-04*
+
+This is the technical changelog for version 21.7. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.11 (:pr:`4546` closes :issue:`4543`)
+- Add ``Message.reply_paid_media`` (:pr:`4551`)
+- Drop Support for Python 3.8 (:pr:`4398` by `elpekenin <https://github.com/elpekenin>`_)
+
+Minor Changes
+-------------
+
+- Allow ``Sequence`` in ``Application.add_handlers`` (:pr:`4531` by `roast-lord <https://github.com/roast-lord>`_ closes :issue:`4530`)
+- Improve Exception Handling in ``File.download_*`` (:pr:`4542`)
+- Use Stable Python 3.13 Release in Test Suite (:pr:`4535`)
+
+Documentation Improvements
+--------------------------
+
+- Documentation Improvements (:pr:`4536` by `Ecode2 <https://github.com/Ecode2>`_, :pr:`4556`)
+- Fix Linkcheck Workflow (:pr:`4545`)
+- Use ``sphinx-build-compatibility`` to Keep Sphinx Compatibility (:pr:`4492`)
+
+Internal Changes
+----------------
+
+- Improve Test Instability Caused by ``Message`` Fixtures (:pr:`4507`)
+- Stabilize Some Flaky Tests (:pr:`4500`)
+- Reduce Creation of HTTP Clients in Tests (:pr:`4493`)
+- Update ``pytest-xdist`` Usage (:pr:`4491`)
+- Fix Failing Tests by Making Them Independent (:pr:`4494`)
+- Introduce Codecov's Test Analysis (:pr:`4487`)
+- Maintenance Work on ``Bot`` Tests (:pr:`4489`)
+- Introduce ``conftest.py`` for File Related Tests (:pr:`4488`)
+- Update Issue Templates to Use Issue Types (:pr:`4553`)
+- Update Automation to Label Changes (:pr:`4552`)
+
+Dependency Updates
+------------------
+
+- Bump ``srvaroa/labeler`` from 1.11.0 to 1.11.1 (:pr:`4549`)
+- Bump ``sphinx`` from 8.0.2 to 8.1.3 (:pr:`4532`)
+- Bump ``sphinxcontrib-mermaid`` from 0.9.2 to 1.0.0 (:pr:`4529`)
+- Bump ``srvaroa/labeler`` from 1.10.1 to 1.11.0 (:pr:`4509`)
+- Bump ``Bibo-Joshi/pyright-type-completeness`` from 1.0.0 to 1.0.1 (:pr:`4510`)
+
+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
 ============
 

README.rst

@@ -11,7 +11,7 @@
    :target: https://pypi.org/project/python-telegram-bot/
    :alt: Supported Python versions
 
-.. image:: https://img.shields.io/badge/Bot%20API-7.7-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-8.1-blue?logo=telegram
    :target: https://core.telegram.org/bots/api-changelog
    :alt: Supported Bot API version
 
@@ -70,7 +70,7 @@ Introduction
 
 This library provides a pure Python, asynchronous interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
-It's compatible with Python versions **3.8+**.
+It's compatible with Python versions **3.9+**.
 
 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
@@ -81,7 +81,7 @@ After installing_ the library, be sure to check out the section on `working with
 Telegram API support
 ~~~~~~~~~~~~~~~~~~~~
 
-All types and methods of the Telegram Bot API **7.7** are natively supported by this library.
+All types and methods of the Telegram Bot API **8.1** 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
@@ -119,9 +119,9 @@ Verifying Releases
 
 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://sigstore.dev>`_.
+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``.
+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?tab=readme-ov-file>`_. 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``.
@@ -155,9 +155,9 @@ PTB can be installed with optional dependencies:
 * ``pip install "python-telegram-bot[passport]"`` installs the `cryptography>=39.0.1 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
 * ``pip install "python-telegram-bot[socks]"`` installs `httpx[socks] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
 * ``pip install "python-telegram-bot[http2]"`` installs `httpx[http2] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to use HTTP/2.
-* ``pip install "python-telegram-bot[rate-limiter]"`` installs `aiolimiter~=1.1.0 <https://aiolimiter.readthedocs.io/en/stable/>`_. Use this, if you want to use ``telegram.ext.AIORateLimiter``.
+* ``pip install "python-telegram-bot[rate-limiter]"`` installs `aiolimiter~=1.1,<1.3 <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]"``.
@@ -230,6 +230,6 @@ 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.
+Derivative 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>
+.. _`GitHub releases page`: https://github.com/python-telegram-bot/python-telegram-bot/releases

docs/auxil/admonition_inserter.py

@@ -20,7 +20,8 @@ import inspect
 import re
 import typing
 from collections import defaultdict
-from typing import Any, Iterator, Union
+from collections.abc import Iterator
+from typing import Any, Union
 
 import telegram
 import telegram.ext
@@ -140,7 +141,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 +150,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 +367,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 ",

docs/auxil/kwargs_insertion.py

@@ -16,7 +16,6 @@
 #  You should have received a copy of the GNU Lesser Public License
 #  along with this program.  If not, see [http://www.gnu.org/licenses/].
 import inspect
-from typing import List
 
 keyword_args = [
     "Keyword Arguments:",
@@ -85,7 +84,7 @@ get_updates_read_timeout_addition = [
 ]
 
 
-def find_insert_pos_for_kwargs(lines: List[str]) -> int:
+def find_insert_pos_for_kwargs(lines: list[str]) -> int:
     """Finds the correct position to insert the keyword arguments and returns the index."""
     for idx, value in reversed(list(enumerate(lines))):  # reversed since :returns: is at the end
         if value.startswith("Returns"):

docs/auxil/link_code.py

@@ -21,7 +21,6 @@ https://github.com/sphinx-doc/sphinx/issues/1556 is closed
 """
 import subprocess
 from pathlib import Path
-from typing import Dict, Tuple
 
 from sphinx.util import logging
 
@@ -32,7 +31,7 @@ sphinx_logger = logging.getLogger(__name__)
 
 # must be a module-level variable so that it can be written to by the `autodoc-process-docstring`
 # event handler in `sphinx_hooks.py`
-LINE_NUMBERS: Dict[str, Tuple[Path, int, int]] = {}
+LINE_NUMBERS: dict[str, tuple[Path, int, int]] = {}
 
 
 def _git_branch() -> str:

docs/auxil/sphinx_hooks.py

@@ -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
@@ -153,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
@@ -188,6 +187,11 @@ def autodoc_process_bases(app, name, obj, option, bases: list) -> None:
             bases[idx] = ":class:`enum.IntEnum`"
             continue
 
+        if "FloatEnum" in base:
+            bases[idx] = ":class:`enum.Enum`"
+            bases.insert(0, ":class:`float`")
+            continue
+
         # Drop generics (at least for now)
         if base.endswith("]"):
             base = base.split("[", maxsplit=1)[0]

docs/auxil/tg_const_role.py

@@ -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

docs/requirements-docs.txt

@@ -1,7 +1,9 @@
-sphinx==7.3.7
-furo==2024.5.6
+sphinx==8.1.3
+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
+sphinxcontrib-mermaid==1.0.0
 sphinx-copybutton==0.5.2
-sphinx-inline-tabs==2023.4.21
+sphinx-inline-tabs==2023.4.21
+# Temporary. See #4387
+sphinx-build-compatibility @ git+https://github.com/readthedocs/sphinx-build-compatibility.git@58aabc5f207c6c2421f23d3578adc0b14af57047

docs/source/conf.py

@@ -1,3 +1,4 @@
+import os
 import re
 import sys
 from pathlib import Path
@@ -29,7 +30,7 @@ version = telegram.__version__
 release = telegram.__version__
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = "6.1.3"
+needs_sphinx = "8.1.3"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -47,6 +48,10 @@ extensions = [
     "sphinx_search.extension",
 ]
 
+# Temporary. See #4387
+if os.environ.get("READTHEDOCS", "") == "True":
+    extensions.append("sphinx_build_compatibility.extension")
+
 # For shorter links to Wiki in docstrings
 extlinks = {
     "wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s"),
@@ -251,7 +256,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 ---------------------------------------------
 

docs/source/inclusions/bot_methods.rst

@@ -25,6 +25,8 @@
           - Used for sending documents
         * - :meth:`~telegram.Bot.send_game`
           - Used for sending a game
+        * - :meth:`~telegram.Bot.send_gift`
+          - Used for sending a gift
         * - :meth:`~telegram.Bot.send_invoice`
           - Used for sending an invoice
         * - :meth:`~telegram.Bot.send_location`
@@ -151,6 +153,8 @@
       - Used for setting a chat title
     * - :meth:`~telegram.Bot.set_chat_description`
       - Used for setting the description of a chat
+    * - :meth:`~telegram.Bot.set_user_emoji_status`
+      - Used for setting the users status emoji
     * - :meth:`~telegram.Bot.pin_chat_message`
       - Used for pinning a message
     * - :meth:`~telegram.Bot.unpin_chat_message`
@@ -355,7 +359,7 @@
 .. raw:: html
 
    <details>
-   <summary>Miscellaneous</summary>
+   <summary>Payments and Stars</summary>
 
 .. list-table::
     :align: left
@@ -363,18 +367,39 @@
 
     * - :meth:`~telegram.Bot.create_invoice_link`
       - Used to generate an HTTP link for an invoice
+    * - :meth:`~telegram.Bot.edit_user_star_subscription`
+      - Used for editing a user's star subscription
+    * - :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
+
+   </details>
+   <br>
+
+.. raw:: html
+
+   <details>
+   <summary>Miscellaneous</summary>
+
+.. list-table::
+    :align: left
+    :widths: 1 4
+
     * - :meth:`~telegram.Bot.close`
       - Used for closing server instance when switching to another local server
     * - :meth:`~telegram.Bot.log_out`
       - Used for logging out from cloud Bot API server
     * - :meth:`~telegram.Bot.get_file`
       - Used for getting basic info about a file
+    * - :meth:`~telegram.Bot.get_available_gifts`
+      - Used for getting information about gifts available for sending
     * - :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
+    * - :meth:`~telegram.Bot.save_prepared_inline_message`
+      - Used for storing a message to be sent by a user of a Mini App
 
 .. raw:: html
 

docs/source/telegram.affiliateinfo.rst

@@ -0,0 +1,6 @@
+AffiliateInfo
+=============
+
+.. autoclass:: telegram.AffiliateInfo
+    :members:
+    :show-inheritance:

docs/source/telegram.at-tree.rst

@@ -29,6 +29,7 @@ Available Types
     telegram.chat
     telegram.chatadministratorrights
     telegram.chatbackground
+    telegram.copytextbutton
     telegram.backgroundtype
     telegram.backgroundtypefill
     telegram.backgroundtypewallpaper
@@ -92,7 +93,6 @@ Available Types
     telegram.inputpaidmediaphoto
     telegram.inputpaidmediavideo
     telegram.inputpolloption
-    telegram.inputsticker
     telegram.keyboardbutton
     telegram.keyboardbuttonpolltype
     telegram.keyboardbuttonrequestchat
@@ -120,6 +120,7 @@ Available Types
     telegram.paidmediainfo
     telegram.paidmediaphoto
     telegram.paidmediapreview
+    telegram.paidmediapurchased
     telegram.paidmediavideo
     telegram.photosize
     telegram.poll
@@ -130,6 +131,7 @@ Available Types
     telegram.reactiontype
     telegram.reactiontypecustomemoji
     telegram.reactiontypeemoji
+    telegram.reactiontypepaid
     telegram.replykeyboardmarkup
     telegram.replykeyboardremove
     telegram.replyparameters

docs/source/telegram.constants.rst

@@ -5,5 +5,5 @@ telegram.constants Module
     :members:
     :show-inheritance:
     :no-undoc-members:
-    :inherited-members: Enum, EnumMeta, str, int
+    :inherited-members: Enum, EnumMeta, str, int, float
     :exclude-members: __format__, __new__, __repr__, __str__

docs/source/telegram.copytextbutton.rst

@@ -0,0 +1,6 @@
+CopyTextButton
+==============
+
+.. autoclass:: telegram.CopyTextButton
+    :members:
+    :show-inheritance:

docs/source/telegram.ext.handlers-tree.rst

@@ -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

docs/source/telegram.ext.paidmediapurchasedhandler.rst

@@ -0,0 +1,6 @@
+PaidMediaPurchasedHandler
+=========================
+
+.. autoclass:: telegram.ext.PaidMediaPurchasedHandler
+    :members:
+    :show-inheritance:

docs/source/telegram.games-tree.rst

@@ -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:
 

docs/source/telegram.gift.rst

@@ -0,0 +1,6 @@
+Gift
+====
+
+.. autoclass:: telegram.Gift
+    :members:
+    :show-inheritance:

docs/source/telegram.gifts.rst

@@ -0,0 +1,6 @@
+Gifts
+=====
+
+.. autoclass:: telegram.Gifts
+    :members:
+    :show-inheritance:

docs/source/telegram.inline-tree.rst

@@ -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:
 
@@ -34,3 +42,4 @@ Inline Mode
     telegram.inputvenuemessagecontent
     telegram.inputcontactmessagecontent
     telegram.inputinvoicemessagecontent
+    telegram.preparedinlinemessage

docs/source/telegram.paidmediapurchased.rst

@@ -0,0 +1,6 @@
+PaidMediaPurchased
+==================
+
+.. autoclass:: telegram.PaidMediaPurchased
+    :members:
+    :show-inheritance:

docs/source/telegram.passport-tree.rst

@@ -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:
 

docs/source/telegram.payments-tree.rst

@@ -1,9 +1,15 @@
+.. _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:
 
+    telegram.affiliateinfo
     telegram.invoice
     telegram.labeledprice
     telegram.orderinfo
@@ -20,7 +26,9 @@ Payments
     telegram.startransactions
     telegram.successfulpayment
     telegram.transactionpartner
+    telegram.transactionpartneraffiliateprogram
     telegram.transactionpartnerfragment
     telegram.transactionpartnerother
     telegram.transactionpartnertelegramads
+    telegram.transactionpartnertelegramapi
     telegram.transactionpartneruser

docs/source/telegram.preparedinlinemessage.rst

@@ -0,0 +1,6 @@
+PreparedInlineMessage
+=====================
+
+.. autoclass:: telegram.PreparedInlineMessage
+    :members:
+    :show-inheritance:

docs/source/telegram.reactiontypepaid.rst

@@ -0,0 +1,6 @@
+ReactionTypePaid
+================
+
+.. autoclass:: telegram.ReactionTypePaid
+    :members:
+    :show-inheritance:

docs/source/telegram.stickers-tree.rst

@@ -1,9 +1,14 @@
 Stickers
 --------
 
+The following methods and objects allow your bot to handle stickers and sticker sets.
+
 .. toctree::
     :titlesonly:
 
+    telegram.gift
+    telegram.gifts
+    telegram.inputsticker
     telegram.maskposition
     telegram.sticker
     telegram.stickerset

docs/source/telegram.transactionpartneraffiliateprogram.rst

@@ -0,0 +1,6 @@
+TransactionPartnerAffiliateProgram
+===================================
+
+.. autoclass:: telegram.TransactionPartnerAffiliateProgram
+    :members:
+    :show-inheritance:

docs/source/telegram.transactionpartnerfragment.rst

@@ -4,4 +4,4 @@ TransactionPartnerFragment
 .. autoclass:: telegram.TransactionPartnerFragment
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartnerother.rst

@@ -4,4 +4,4 @@ TransactionPartnerOther
 .. autoclass:: telegram.TransactionPartnerOther
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartnertelegramads.rst

@@ -4,4 +4,4 @@ TransactionPartnerTelegramAds
 .. autoclass:: telegram.TransactionPartnerTelegramAds
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartnertelegramapi.rst

@@ -0,0 +1,7 @@
+TransactionPartnerTelegramApi
+=============================
+
+.. autoclass:: telegram.TransactionPartnerTelegramApi
+    :members:
+    :show-inheritance:
+    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartneruser.rst

@@ -4,4 +4,4 @@ TransactionPartnerUser
 .. autoclass:: telegram.TransactionPartnerUser
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TransactionPartner

docs/substitutions/global.rst

@@ -60,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.
@@ -91,3 +93,7 @@
 .. |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>`__
+
+.. |allow_paid_broadcast| replace:: Pass True to allow up to :tg-const:`telegram.constants.FloodLimit.PAID_MESSAGES_PER_SECOND` messages per second, ignoring `broadcasting limits <https://core.telegram.org/bots/faq#how-can-i-message-all-of-my-bot-39s-subscribers-at-once>`__ for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's balance.
+
+.. |tz-naive-dtms| replace:: For timezone naive :obj:`datetime.datetime` objects, the default timezone of the bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used.

examples/arbitrarycallbackdatabot.py

@@ -12,7 +12,7 @@ To use arbitrary callback data, you must install PTB via
 `pip install "python-telegram-bot[callback-data]"`
 """
 import logging
-from typing import List, Tuple, cast
+from typing import cast
 
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import (
@@ -36,7 +36,7 @@ logger = logging.getLogger(__name__)
 
 async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Sends a message with 5 inline buttons attached."""
-    number_list: List[int] = []
+    number_list: list[int] = []
     await update.message.reply_text("Please choose:", reply_markup=build_keyboard(number_list))
 
 
@@ -55,7 +55,7 @@ async def clear(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     await update.effective_message.reply_text("All clear!")
 
 
-def build_keyboard(current_list: List[int]) -> InlineKeyboardMarkup:
+def build_keyboard(current_list: list[int]) -> InlineKeyboardMarkup:
     """Helper function to build the next inline keyboard."""
     return InlineKeyboardMarkup.from_column(
         [InlineKeyboardButton(str(i), callback_data=(i, current_list)) for i in range(1, 6)]
@@ -69,7 +69,7 @@ async def list_button(update: Update, context: ContextTypes.DEFAULT_TYPE) -> Non
     # Get the data from the callback_data.
     # If you're using a type checker like MyPy, you'll have to use typing.cast
     # to make the checker get the expected type of the callback_data
-    number, number_list = cast(Tuple[int, List[int]], query.data)
+    number, number_list = cast(tuple[int, list[int]], query.data)
     # append the number to the list
     number_list.append(number)
 

examples/chatmemberbot.py

@@ -12,7 +12,7 @@ bot.
 """
 
 import logging
-from typing import Optional, Tuple
+from typing import Optional
 
 from telegram import Chat, ChatMember, ChatMemberUpdated, Update
 from telegram.constants import ParseMode
@@ -37,7 +37,7 @@ logging.getLogger("httpx").setLevel(logging.WARNING)
 logger = logging.getLogger(__name__)
 
 
-def extract_status_change(chat_member_update: ChatMemberUpdated) -> Optional[Tuple[bool, bool]]:
+def extract_status_change(chat_member_update: ChatMemberUpdated) -> Optional[tuple[bool, bool]]:
     """Takes a ChatMemberUpdated instance and extracts whether the 'old_chat_member' was a member
     of the chat and whether the 'new_chat_member' is a member of the chat. Returns None, if
     the status didn't change.

examples/contexttypesbot.py

@@ -12,7 +12,7 @@ bot.
 
 import logging
 from collections import defaultdict
-from typing import DefaultDict, Optional, Set
+from typing import Optional
 
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.constants import ParseMode
@@ -40,7 +40,7 @@ class ChatData:
     """Custom class for chat_data. Here we store data per message."""
 
     def __init__(self) -> None:
-        self.clicks_per_message: DefaultDict[int, int] = defaultdict(int)
+        self.clicks_per_message: defaultdict[int, int] = defaultdict(int)
 
 
 # The [ExtBot, dict, ChatData, dict] is for type checkers like mypy
@@ -57,7 +57,7 @@ class CustomContext(CallbackContext[ExtBot, dict, ChatData, dict]):
         self._message_id: Optional[int] = None
 
     @property
-    def bot_user_ids(self) -> Set[int]:
+    def bot_user_ids(self) -> set[int]:
         """Custom shortcut to access a value stored in the bot_data dict"""
         return self.bot_data.setdefault("user_ids", set())
 

examples/conversationbot2.py

@@ -15,7 +15,6 @@ bot.
 """
 
 import logging
-from typing import Dict
 
 from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update
 from telegram.ext import (
@@ -46,7 +45,7 @@ reply_keyboard = [
 markup = ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True)
 
 
-def facts_to_str(user_data: Dict[str, str]) -> str:
+def facts_to_str(user_data: dict[str, str]) -> str:
     """Helper function for formatting the gathered user info."""
     facts = [f"{key} - {value}" for key, value in user_data.items()]
     return "\n".join(facts).join(["\n", "\n"])

examples/nestedconversationbot.py

@@ -15,7 +15,7 @@ bot.
 """
 
 import logging
-from typing import Any, Dict, Tuple
+from typing import Any
 
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import (
@@ -66,7 +66,7 @@ END = ConversationHandler.END
 
 
 # Helper
-def _name_switcher(level: str) -> Tuple[str, str]:
+def _name_switcher(level: str) -> tuple[str, str]:
     if level == PARENTS:
         return "Father", "Mother"
     return "Brother", "Sister"
@@ -122,7 +122,7 @@ async def adding_self(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str
 async def show_data(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Pretty print gathered data."""
 
-    def pretty_print(data: Dict[str, Any], level: str) -> str:
+    def pretty_print(data: dict[str, Any], level: str) -> str:
         people = data.get(level)
         if not people:
             return "\nNo information yet."
@@ -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)],
         },

examples/paymentbot.py

@@ -2,7 +2,7 @@
 # pylint: disable=unused-argument
 # This program is dedicated to the public domain under the CC0 license.
 
-"""Basic example for a bot that can receive payment from user."""
+"""Basic example for a bot that can receive payments from users."""
 
 import logging
 
@@ -26,36 +26,36 @@ logging.getLogger("httpx").setLevel(logging.WARNING)
 
 logger = logging.getLogger(__name__)
 
+# Insert the token from your payment provider.
+# In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
 PAYMENT_PROVIDER_TOKEN = "PAYMENT_PROVIDER_TOKEN"
 
 
 async def start_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Displays info on how to use the bot."""
+    """Provides instructions on how to use the bot."""
     msg = (
-        "Use /shipping to get an invoice for shipping-payment, or /noshipping for an "
+        "Use /shipping to receive an invoice with shipping included, or /noshipping for an "
         "invoice without shipping."
     )
-
     await update.message.reply_text(msg)
 
 
 async def start_with_shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Sends an invoice with shipping-payment."""
+    """Sends an invoice which triggers a shipping query."""
     chat_id = update.message.chat_id
     title = "Payment Example"
-    description = "Payment Example using python-telegram-bot"
-    # select a payload just for you to recognize its the donation from your bot
+    description = "Example of a payment process using the python-telegram-bot library."
+    # Unique payload to identify this payment request as being from your bot
     payload = "Custom-Payload"
-    # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
+    # Set up the currency.
+    # List of supported currencies: https://core.telegram.org/bots/payments#supported-currencies
     currency = "USD"
-    # price in dollars
+    # Price in dollars
     price = 1
-    # price * 100 so as to include 2 decimal points
-    # check https://core.telegram.org/bots/payments#supported-currencies for more details
+    # Convert price to cents from dollars.
     prices = [LabeledPrice("Test", price * 100)]
-
-    # optionally pass need_name=True, need_phone_number=True,
-    # need_email=True, need_shipping_address=True, is_flexible=True
+    # Optional parameters like need_shipping_address and is_flexible trigger extra user prompts
+    # https://docs.python-telegram-bot.org/en/stable/telegram.bot.html#telegram.Bot.send_invoice
     await context.bot.send_invoice(
         chat_id,
         title,
@@ -75,17 +75,16 @@ async def start_with_shipping_callback(update: Update, context: ContextTypes.DEF
 async def start_without_shipping_callback(
     update: Update, context: ContextTypes.DEFAULT_TYPE
 ) -> None:
-    """Sends an invoice without shipping-payment."""
+    """Sends an invoice without requiring shipping details."""
     chat_id = update.message.chat_id
     title = "Payment Example"
-    description = "Payment Example using python-telegram-bot"
-    # select a payload just for you to recognize its the donation from your bot
+    description = "Example of a payment process using the python-telegram-bot library."
+    # Unique payload to identify this payment request as being from your bot
     payload = "Custom-Payload"
-    # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
     currency = "USD"
-    # price in dollars
+    # Price in dollars
     price = 1
-    # price * 100 so as to include 2 decimal points
+    # Convert price to cents from dollars.
     prices = [LabeledPrice("Test", price * 100)]
 
     # optionally pass need_name=True, need_phone_number=True,
@@ -96,65 +95,65 @@ async def start_without_shipping_callback(
 
 
 async def shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Answers the ShippingQuery with ShippingOptions"""
+    """Handles the ShippingQuery with available shipping options."""
     query = update.shipping_query
-    # check the payload, is this from your bot?
+    # Verify if the payload matches, ensure it's from your bot
     if query.invoice_payload != "Custom-Payload":
-        # answer False pre_checkout_query
+        # If not, respond with an error
         await query.answer(ok=False, error_message="Something went wrong...")
         return
 
-    # First option has a single LabeledPrice
+    # Define available shipping options
+    # First option with a single price entry
     options = [ShippingOption("1", "Shipping Option A", [LabeledPrice("A", 100)])]
-    # second option has an array of LabeledPrice objects
+    # Second option with multiple price entries
     price_list = [LabeledPrice("B1", 150), LabeledPrice("B2", 200)]
     options.append(ShippingOption("2", "Shipping Option B", price_list))
     await query.answer(ok=True, shipping_options=options)
 
 
-# after (optional) shipping, it's the pre-checkout
+# After (optional) shipping, process the pre-checkout step
 async def precheckout_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Answers the PreQecheckoutQuery"""
+    """Responds to the PreCheckoutQuery as the final confirmation for checkout."""
     query = update.pre_checkout_query
-    # check the payload, is this from your bot?
+    # Verify if the payload matches, ensure it's from your bot
     if query.invoice_payload != "Custom-Payload":
-        # answer False pre_checkout_query
+        # If not, respond with an error
         await query.answer(ok=False, error_message="Something went wrong...")
     else:
         await query.answer(ok=True)
 
 
-# finally, after contacting the payment provider...
+# Final callback after successful payment
 async def successful_payment_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Confirms the successful payment."""
-    # do something after successfully receiving payment?
-    await update.message.reply_text("Thank you for your payment!")
+    """Acknowledges successful payment and thanks the user."""
+    await update.message.reply_text("Thank you for your payment.")
 
 
 def main() -> None:
-    """Run the bot."""
+    """Starts the bot and sets up handlers."""
     # Create the Application and pass it your bot's token.
     application = Application.builder().token("TOKEN").build()
 
-    # simple start function
+    # Start command to display usage instructions
     application.add_handler(CommandHandler("start", start_callback))
 
-    # Add command handler to start the payment invoice
+    # Command handlers for starting the payment process
     application.add_handler(CommandHandler("shipping", start_with_shipping_callback))
     application.add_handler(CommandHandler("noshipping", start_without_shipping_callback))
 
-    # Optional handler if your product requires shipping
+    # Handler for shipping query (if product requires shipping)
     application.add_handler(ShippingQueryHandler(shipping_callback))
 
-    # Pre-checkout handler to final check
+    # Pre-checkout handler for verifying payment details.
     application.add_handler(PreCheckoutQueryHandler(precheckout_callback))
 
-    # Success! Notify your user!
+    # Handler for successful payment. Notify the user that the payment was successful.
     application.add_handler(
         MessageHandler(filters.SUCCESSFUL_PAYMENT, successful_payment_callback)
     )
 
-    # Run the bot until the user presses Ctrl-C
+    # Start polling for updates until interrupted (CTRL+C)
     application.run_polling(allowed_updates=Update.ALL_TYPES)
 
 

examples/persistentconversationbot.py

@@ -15,7 +15,6 @@ bot.
 """
 
 import logging
-from typing import Dict
 
 from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update
 from telegram.ext import (
@@ -47,7 +46,7 @@ reply_keyboard = [
 markup = ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True)
 
 
-def facts_to_str(user_data: Dict[str, str]) -> str:
+def facts_to_str(user_data: dict[str, str]) -> str:
     """Helper function for formatting the gathered user info."""
     facts = [f"{key} - {value}" for key, value in user_data.items()]
     return "\n".join(facts).join(["\n", "\n"])

pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 name = "python-telegram-bot"
 description = "We have made you a wrapper you can't refuse"
 readme = "README.rst"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 license = "LGPL-3.0-only"
 license-files = { paths = ["LICENSE", "LICENSE.dual", "LICENSE.lesser"] }
 authors = [
@@ -31,7 +31,6 @@ classifiers = [
     "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",
@@ -67,7 +66,7 @@ all = [
 ]
 callback-data = [
     # Cachetools doesn't have a strict stability policy. Let's be cautious for now.
-    "cachetools~=5.3.3",
+    "cachetools>=5.3.3,<5.6.0",
 ]
 ext = [
     "python-telegram-bot[callback-data,job-queue,rate-limiter,webhooks]",
@@ -87,7 +86,7 @@ passport = [
     "cffi >= 1.17.0rc1; python_version > '3.12'"
 ]
 rate-limiter = [
-    "aiolimiter~=1.1.0",
+    "aiolimiter>=1.1,<1.3",
 ]
 socks = [
     "httpx[socks]",
@@ -128,14 +127,21 @@ explicit-preview-rules = true  # TODO: Drop this when RUF022 and RUF023 are out
 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", "YTT", "DTZ", "ARG", "T20", "FURB"]
+          "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", "ASYNC230", "DTZ", "ARG", "T201"]
-"docs/**.py" = ["INP001", "ARG"]
-"examples/**.py" = ["ARG"]
+"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"]
@@ -143,7 +149,8 @@ enable = ["useless-suppression"]
 disable = ["duplicate-code", "too-many-arguments", "too-many-public-methods",
         "too-few-public-methods", "broad-exception-caught", "too-many-instance-attributes",
         "fixme", "missing-function-docstring", "missing-class-docstring", "too-many-locals",
-        "too-many-lines", "too-many-branches", "too-many-statements", "cyclic-import"
+        "too-many-lines", "too-many-branches", "too-many-statements", "cyclic-import",
+        "too-many-positional-arguments",
 ]
 
 [tool.pylint.main]
@@ -185,7 +192,7 @@ disallow_untyped_defs = true
 disallow_incomplete_defs = true
 disallow_untyped_decorators = true
 show_error_codes = true
-python_version = "3.8"
+python_version = "3.9"
 
 # For some files, it's easier to just disable strict-optional all together instead of
 # cluttering the code with `# type: ignore`s or stuff like

requirements-unit-tests.txt

@@ -4,7 +4,7 @@
 build
 
 # For the test suite
-pytest==8.2.2
+pytest==8.3.4
 
 # needed because pytest doesn't come with native support for coroutines as tests
 pytest-asyncio==0.21.2

telegram/__init__.py

@@ -20,6 +20,7 @@
 
 __author__ = "devs@python-telegram-bot.org"
 __all__ = (
+    "AffiliateInfo",
     "Animation",
     "Audio",
     "BackgroundFill",
@@ -81,6 +82,7 @@ __all__ = (
     "ChatShared",
     "ChosenInlineResult",
     "Contact",
+    "CopyTextButton",
     "Credentials",
     "DataCredentials",
     "Dice",
@@ -100,6 +102,8 @@ __all__ = (
     "GameHighScore",
     "GeneralForumTopicHidden",
     "GeneralForumTopicUnhidden",
+    "Gift",
+    "Gifts",
     "Giveaway",
     "GiveawayCompleted",
     "GiveawayCreated",
@@ -180,6 +184,7 @@ __all__ = (
     "PaidMediaInfo",
     "PaidMediaPhoto",
     "PaidMediaPreview",
+    "PaidMediaPurchased",
     "PaidMediaVideo",
     "PassportData",
     "PassportElementError",
@@ -199,11 +204,13 @@ __all__ = (
     "PollAnswer",
     "PollOption",
     "PreCheckoutQuery",
+    "PreparedInlineMessage",
     "ProximityAlertTriggered",
     "ReactionCount",
     "ReactionType",
     "ReactionTypeCustomEmoji",
     "ReactionTypeEmoji",
+    "ReactionTypePaid",
     "RefundedPayment",
     "ReplyKeyboardMarkup",
     "ReplyKeyboardRemove",
@@ -230,9 +237,11 @@ __all__ = (
     "TelegramObject",
     "TextQuote",
     "TransactionPartner",
+    "TransactionPartnerAffiliateProgram",
     "TransactionPartnerFragment",
     "TransactionPartnerOther",
     "TransactionPartnerTelegramAds",
+    "TransactionPartnerTelegramApi",
     "TransactionPartnerUser",
     "Update",
     "User",
@@ -328,6 +337,7 @@ from ._chatmember import (
 from ._chatmemberupdated import ChatMemberUpdated
 from ._chatpermissions import ChatPermissions
 from ._choseninlineresult import ChosenInlineResult
+from ._copytextbutton import CopyTextButton
 from ._dice import Dice
 from ._files.animation import Animation
 from ._files.audio import Audio
@@ -368,6 +378,7 @@ from ._forumtopic import (
 from ._games.callbackgame import CallbackGame
 from ._games.game import Game
 from ._games.gamehighscore import GameHighScore
+from ._gifts import Gift, Gifts
 from ._giveaway import Giveaway, GiveawayCompleted, GiveawayCreated, GiveawayWinners
 from ._inline.inlinekeyboardbutton import InlineKeyboardButton
 from ._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
@@ -400,6 +411,7 @@ from ._inline.inputlocationmessagecontent import InputLocationMessageContent
 from ._inline.inputmessagecontent import InputMessageContent
 from ._inline.inputtextmessagecontent import InputTextMessageContent
 from ._inline.inputvenuemessagecontent import InputVenueMessageContent
+from ._inline.preparedinlinemessage import PreparedInlineMessage
 from ._keyboardbutton import KeyboardButton
 from ._keyboardbuttonpolltype import KeyboardButtonPollType
 from ._keyboardbuttonrequest import KeyboardButtonRequestChat, KeyboardButtonRequestUsers
@@ -418,7 +430,14 @@ from ._messageorigin import (
     MessageOriginUser,
 )
 from ._messagereactionupdated import MessageReactionCountUpdated, MessageReactionUpdated
-from ._paidmedia import PaidMedia, PaidMediaInfo, PaidMediaPhoto, PaidMediaPreview, PaidMediaVideo
+from ._paidmedia import (
+    PaidMedia,
+    PaidMediaInfo,
+    PaidMediaPhoto,
+    PaidMediaPreview,
+    PaidMediaPurchased,
+    PaidMediaVideo,
+)
 from ._passport.credentials import (
     Credentials,
     DataCredentials,
@@ -452,6 +471,7 @@ from ._payment.shippingaddress import ShippingAddress
 from ._payment.shippingoption import ShippingOption
 from ._payment.shippingquery import ShippingQuery
 from ._payment.stars import (
+    AffiliateInfo,
     RevenueWithdrawalState,
     RevenueWithdrawalStateFailed,
     RevenueWithdrawalStatePending,
@@ -459,15 +479,23 @@ from ._payment.stars import (
     StarTransaction,
     StarTransactions,
     TransactionPartner,
+    TransactionPartnerAffiliateProgram,
     TransactionPartnerFragment,
     TransactionPartnerOther,
     TransactionPartnerTelegramAds,
+    TransactionPartnerTelegramApi,
     TransactionPartnerUser,
 )
 from ._payment.successfulpayment import SuccessfulPayment
 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

telegram/__main__.py

@@ -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/].
 # pylint: disable=missing-module-docstring
-# ruff: noqa: T201
+# ruff: noqa: T201, D100, S603, S607
 import subprocess
 import sys
 from typing import Optional

telegram/_botcommandscope.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 # pylint: disable=redefined-builtin
 """This module contains objects representing Telegram bot command scopes."""
-from typing import TYPE_CHECKING, Dict, Final, Optional, Type, Union
+from typing import TYPE_CHECKING, Final, Optional, Union
 
 from telegram import constants
 from telegram._telegramobject import TelegramObject
@@ -91,7 +91,7 @@ class BotCommandScope(TelegramObject):
         care of selecting the correct subclass.
 
         Args:
-            data (Dict[:obj:`str`, ...]): The JSON data.
+            data (dict[:obj:`str`, ...]): The JSON data.
             bot (:class:`telegram.Bot`, optional): The bot associated with this object. Defaults to
                 :obj:`None`, in which case shortcut methods will not be available.
 
@@ -107,7 +107,7 @@ class BotCommandScope(TelegramObject):
         if not data:
             return None
 
-        _class_mapping: Dict[str, Type[BotCommandScope]] = {
+        _class_mapping: dict[str, type[BotCommandScope]] = {
             cls.DEFAULT: BotCommandScopeDefault,
             cls.ALL_PRIVATE_CHATS: BotCommandScopeAllPrivateChats,
             cls.ALL_GROUP_CHATS: BotCommandScopeAllGroupChats,

telegram/_business.py

@@ -19,8 +19,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/]
 """This module contains the Telegram Business related classes."""
 
+from collections.abc import Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from typing import TYPE_CHECKING, Optional
 
 from telegram._chat import Chat
 from telegram._files.location import Location
@@ -145,7 +146,7 @@ class BusinessMessagesDeleted(TelegramObject):
         business_connection_id (:obj:`str`): Unique identifier of the business connection.
         chat (:class:`telegram.Chat`): Information about a chat in the business account. The bot
             may not have access to the chat or the corresponding user.
-        message_ids (Tuple[:obj:`int`]): A list of identifiers of the deleted messages in the
+        message_ids (tuple[:obj:`int`]): A list of identifiers of the deleted messages in the
             chat of the business account.
     """
 
@@ -166,7 +167,7 @@ class BusinessMessagesDeleted(TelegramObject):
         super().__init__(api_kwargs=api_kwargs)
         self.business_connection_id: str = business_connection_id
         self.chat: Chat = chat
-        self.message_ids: Tuple[int, ...] = parse_sequence_arg(message_ids)
+        self.message_ids: tuple[int, ...] = parse_sequence_arg(message_ids)
 
         self._id_attrs = (
             self.business_connection_id,
@@ -359,37 +360,37 @@ class BusinessOpeningHoursInterval(TelegramObject):
         self.opening_minute: int = opening_minute
         self.closing_minute: int = closing_minute
 
-        self._opening_time: Optional[Tuple[int, int, int]] = None
-        self._closing_time: Optional[Tuple[int, int, int]] = None
+        self._opening_time: Optional[tuple[int, int, int]] = None
+        self._closing_time: Optional[tuple[int, int, int]] = None
 
         self._id_attrs = (self.opening_minute, self.closing_minute)
 
         self._freeze()
 
-    def _parse_minute(self, minute: int) -> Tuple[int, int, int]:
+    def _parse_minute(self, minute: int) -> tuple[int, int, int]:
         return (minute // 1440, minute % 1440 // 60, minute % 1440 % 60)
 
     @property
-    def opening_time(self) -> Tuple[int, int, int]:
+    def opening_time(self) -> tuple[int, int, int]:
         """Convenience attribute. A :obj:`tuple` parsed from :attr:`opening_minute`. It contains
         the `weekday`, `hour` and `minute` in the same ranges as :attr:`datetime.datetime.weekday`,
         :attr:`datetime.datetime.hour` and :attr:`datetime.datetime.minute`
 
         Returns:
-            Tuple[:obj:`int`, :obj:`int`, :obj:`int`]:
+            tuple[:obj:`int`, :obj:`int`, :obj:`int`]:
         """
         if self._opening_time is None:
             self._opening_time = self._parse_minute(self.opening_minute)
         return self._opening_time
 
     @property
-    def closing_time(self) -> Tuple[int, int, int]:
+    def closing_time(self) -> tuple[int, int, int]:
         """Convenience attribute. A :obj:`tuple` parsed from :attr:`closing_minute`. It contains
         the `weekday`, `hour` and `minute` in the same ranges as :attr:`datetime.datetime.weekday`,
         :attr:`datetime.datetime.hour` and :attr:`datetime.datetime.minute`
 
         Returns:
-            Tuple[:obj:`int`, :obj:`int`, :obj:`int`]:
+            tuple[:obj:`int`, :obj:`int`, :obj:`int`]:
         """
         if self._closing_time is None:
             self._closing_time = self._parse_minute(self.closing_minute)

telegram/_callbackquery.py

@@ -18,7 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 # pylint: disable=redefined-builtin
 """This module contains an object that represents a Telegram CallbackQuery"""
-from typing import TYPE_CHECKING, Final, Optional, Sequence, Tuple, Union
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, Optional, Union
 
 from telegram import constants
 from telegram._files.location import Location
@@ -676,7 +677,7 @@ class CallbackQuery(TelegramObject):
         connect_timeout: ODVInput[float] = DEFAULT_NONE,
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
         api_kwargs: Optional[JSONDict] = None,
-    ) -> Tuple["GameHighScore", ...]:
+    ) -> tuple["GameHighScore", ...]:
         """Shortcut for either::
 
             await update.callback_query.message.get_game_high_score(*args, **kwargs)
@@ -695,7 +696,7 @@ class CallbackQuery(TelegramObject):
            Raises :exc:`TypeError` if :attr:`message` is not accessible.
 
         Returns:
-            Tuple[:class:`telegram.GameHighScore`]
+            tuple[:class:`telegram.GameHighScore`]
 
         Raises:
             :exc:`TypeError` if :attr:`message` is not accessible.
@@ -833,6 +834,7 @@ class CallbackQuery(TelegramObject):
         message_thread_id: Optional[int] = None,
         reply_parameters: Optional["ReplyParameters"] = None,
         show_caption_above_media: Optional[bool] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         reply_to_message_id: Optional[int] = None,
@@ -880,6 +882,7 @@ class CallbackQuery(TelegramObject):
             message_thread_id=message_thread_id,
             reply_parameters=reply_parameters,
             show_caption_above_media=show_caption_above_media,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     MAX_ANSWER_TEXT_LENGTH: Final[int] = (

telegram/_chat.py

@@ -18,9 +18,10 @@
 # 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 Chat."""
+from collections.abc import Sequence
 from datetime import datetime
 from html import escape
-from typing import TYPE_CHECKING, Final, Optional, Sequence, Tuple, Union
+from typing import TYPE_CHECKING, Final, Optional, Union
 
 from telegram import constants
 from telegram._chatpermissions import ChatPermissions
@@ -43,6 +44,7 @@ if TYPE_CHECKING:
         ChatMember,
         Contact,
         Document,
+        Gift,
         InlineKeyboardMarkup,
         InputMediaAudio,
         InputMediaDocument,
@@ -296,7 +298,7 @@ class _ChatBase(TelegramObject):
         connect_timeout: ODVInput[float] = DEFAULT_NONE,
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
         api_kwargs: Optional[JSONDict] = None,
-    ) -> Tuple["ChatMember", ...]:
+    ) -> tuple["ChatMember", ...]:
         """Shortcut for::
 
              await bot.get_chat_administrators(update.effective_chat.id, *args, **kwargs)
@@ -305,7 +307,7 @@ class _ChatBase(TelegramObject):
         :meth:`telegram.Bot.get_chat_administrators`.
 
         Returns:
-            Tuple[:class:`telegram.ChatMember`]: A tuple of administrators in a chat. An Array of
+            tuple[:class:`telegram.ChatMember`]: A tuple of administrators in a chat. An Array of
             :class:`telegram.ChatMember` objects that contains information about all
             chat administrators except other bots. If the chat is a group or a supergroup
             and no administrators were appointed, only the creator will be returned.
@@ -905,6 +907,7 @@ class _ChatBase(TelegramObject):
         self,
         message_id: int,
         disable_notification: ODVInput[bool] = DEFAULT_NONE,
+        business_connection_id: Optional[str] = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -932,11 +935,13 @@ class _ChatBase(TelegramObject):
             connect_timeout=connect_timeout,
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
+            business_connection_id=business_connection_id,
         )
 
     async def unpin_message(
         self,
         message_id: Optional[int] = None,
+        business_connection_id: Optional[str] = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -963,6 +968,7 @@ class _ChatBase(TelegramObject):
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
             message_id=message_id,
+            business_connection_id=business_connection_id,
         )
 
     async def unpin_all_messages(
@@ -1007,6 +1013,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1048,6 +1055,7 @@ class _ChatBase(TelegramObject):
             api_kwargs=api_kwargs,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def delete_message(
@@ -1125,6 +1133,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1136,7 +1145,7 @@ class _ChatBase(TelegramObject):
         caption: Optional[str] = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Optional[Sequence["MessageEntity"]] = None,
-    ) -> Tuple["Message", ...]:
+    ) -> tuple["Message", ...]:
         """Shortcut for::
 
              await bot.send_media_group(update.effective_chat.id, *args, **kwargs)
@@ -1144,7 +1153,7 @@ class _ChatBase(TelegramObject):
         For the documentation of the arguments, please see :meth:`telegram.Bot.send_media_group`.
 
         Returns:
-            Tuple[:class:`telegram.Message`]: On success, a tuple of :class:`~telegram.Message`
+            tuple[:class:`telegram.Message`]: On success, a tuple of :class:`~telegram.Message`
             instances that were sent is returned.
 
         """
@@ -1167,6 +1176,7 @@ class _ChatBase(TelegramObject):
             reply_parameters=reply_parameters,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_chat_action(
@@ -1220,6 +1230,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         show_caption_above_media: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
@@ -1263,6 +1274,7 @@ class _ChatBase(TelegramObject):
             has_spoiler=has_spoiler,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
             show_caption_above_media=show_caption_above_media,
         )
 
@@ -1279,6 +1291,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1320,6 +1333,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_audio(
@@ -1339,6 +1353,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1384,6 +1399,7 @@ class _ChatBase(TelegramObject):
             thumbnail=thumbnail,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_document(
@@ -1401,6 +1417,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1444,6 +1461,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_dice(
@@ -1456,6 +1474,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1492,6 +1511,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_game(
@@ -1504,6 +1524,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1540,6 +1561,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_invoice(
@@ -1571,6 +1593,7 @@ class _ChatBase(TelegramObject):
         message_thread_id: Optional[int] = None,
         reply_parameters: Optional["ReplyParameters"] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1636,6 +1659,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             reply_parameters=reply_parameters,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_location(
@@ -1653,6 +1677,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1696,6 +1721,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_animation(
@@ -1716,6 +1742,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         show_caption_above_media: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
@@ -1763,6 +1790,7 @@ class _ChatBase(TelegramObject):
             thumbnail=thumbnail,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
             show_caption_above_media=show_caption_above_media,
         )
 
@@ -1777,6 +1805,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1814,6 +1843,7 @@ class _ChatBase(TelegramObject):
             emoji=emoji,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_venue(
@@ -1833,6 +1863,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -1878,6 +1909,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_video(
@@ -1899,6 +1931,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         show_caption_above_media: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
@@ -1947,6 +1980,7 @@ class _ChatBase(TelegramObject):
             has_spoiler=has_spoiler,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
             show_caption_above_media=show_caption_above_media,
         )
 
@@ -1963,6 +1997,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -2004,6 +2039,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_voice(
@@ -2020,6 +2056,7 @@ class _ChatBase(TelegramObject):
         reply_parameters: Optional["ReplyParameters"] = None,
         business_connection_id: Optional[str] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -2062,6 +2099,7 @@ class _ChatBase(TelegramObject):
             message_thread_id=message_thread_id,
             business_connection_id=business_connection_id,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_poll(
@@ -2087,6 +2125,7 @@ class _ChatBase(TelegramObject):
         question_parse_mode: ODVInput[str] = DEFAULT_NONE,
         question_entities: Optional[Sequence["MessageEntity"]] = None,
         message_effect_id: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -2124,6 +2163,7 @@ class _ChatBase(TelegramObject):
             connect_timeout=connect_timeout,
             pool_timeout=pool_timeout,
             message_effect_id=message_effect_id,
+            allow_paid_broadcast=allow_paid_broadcast,
             explanation=explanation,
             explanation_parse_mode=explanation_parse_mode,
             open_period=open_period,
@@ -2151,6 +2191,7 @@ class _ChatBase(TelegramObject):
         message_thread_id: Optional[int] = None,
         reply_parameters: Optional["ReplyParameters"] = None,
         show_caption_above_media: Optional[bool] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -2192,6 +2233,7 @@ class _ChatBase(TelegramObject):
             protect_content=protect_content,
             message_thread_id=message_thread_id,
             show_caption_above_media=show_caption_above_media,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def copy_message(
@@ -2207,6 +2249,7 @@ class _ChatBase(TelegramObject):
         message_thread_id: Optional[int] = None,
         reply_parameters: Optional["ReplyParameters"] = None,
         show_caption_above_media: Optional[bool] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         reply_to_message_id: Optional[int] = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
@@ -2248,6 +2291,7 @@ class _ChatBase(TelegramObject):
             protect_content=protect_content,
             message_thread_id=message_thread_id,
             show_caption_above_media=show_caption_above_media,
+            allow_paid_broadcast=allow_paid_broadcast,
         )
 
     async def send_copies(
@@ -2264,7 +2308,7 @@ class _ChatBase(TelegramObject):
         connect_timeout: ODVInput[float] = DEFAULT_NONE,
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
         api_kwargs: Optional[JSONDict] = None,
-    ) -> Tuple["MessageId", ...]:
+    ) -> tuple["MessageId", ...]:
         """Shortcut for::
 
              await bot.copy_messages(chat_id=update.effective_chat.id, *args, **kwargs)
@@ -2276,7 +2320,7 @@ class _ChatBase(TelegramObject):
         .. versionadded:: 20.8
 
         Returns:
-            Tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId`
+            tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId`
             of the sent messages is returned.
 
         """
@@ -2309,7 +2353,7 @@ class _ChatBase(TelegramObject):
         connect_timeout: ODVInput[float] = DEFAULT_NONE,
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
         api_kwargs: Optional[JSONDict] = None,
-    ) -> Tuple["MessageId", ...]:
+    ) -> tuple["MessageId", ...]:
         """Shortcut for::
 
              await bot.copy_messages(from_chat_id=update.effective_chat.id, *args, **kwargs)
@@ -2321,7 +2365,7 @@ class _ChatBase(TelegramObject):
         .. versionadded:: 20.8
 
         Returns:
-            Tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId`
+            tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId`
             of the sent messages is returned.
 
         """
@@ -2438,7 +2482,7 @@ class _ChatBase(TelegramObject):
         connect_timeout: ODVInput[float] = DEFAULT_NONE,
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
         api_kwargs: Optional[JSONDict] = None,
-    ) -> Tuple["MessageId", ...]:
+    ) -> tuple["MessageId", ...]:
         """Shortcut for::
 
              await bot.forward_messages(chat_id=update.effective_chat.id, *args, **kwargs)
@@ -2450,7 +2494,7 @@ class _ChatBase(TelegramObject):
         .. versionadded:: 20.8
 
         Returns:
-            Tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId`
+            tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId`
             of sent messages is returned.
 
         """
@@ -2481,7 +2525,7 @@ class _ChatBase(TelegramObject):
         connect_timeout: ODVInput[float] = DEFAULT_NONE,
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
         api_kwargs: Optional[JSONDict] = None,
-    ) -> Tuple["MessageId", ...]:
+    ) -> tuple["MessageId", ...]:
         """Shortcut for::
 
              await bot.forward_messages(from_chat_id=update.effective_chat.id, *args, **kwargs)
@@ -2493,7 +2537,7 @@ class _ChatBase(TelegramObject):
         .. versionadded:: 20.8
 
         Returns:
-            Tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId`
+            tuple[:class:`telegram.MessageId`]: On success, a tuple of :class:`~telegram.MessageId`
             of sent messages is returned.
 
         """
@@ -2662,6 +2706,81 @@ class _ChatBase(TelegramObject):
             api_kwargs=api_kwargs,
         )
 
+    async def create_subscription_invite_link(
+        self,
+        subscription_period: int,
+        subscription_price: int,
+        name: Optional[str] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> "ChatInviteLink":
+        """Shortcut for::
+
+            await bot.create_chat_subscription_invite_link(
+                chat_id=update.effective_chat.id, *args, **kwargs
+            )
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.create_chat_subscription_invite_link`.
+
+        .. versionadded:: 21.5
+
+        Returns:
+            :class:`telegram.ChatInviteLink`
+        """
+        return await self.get_bot().create_chat_subscription_invite_link(
+            chat_id=self.id,
+            subscription_period=subscription_period,
+            subscription_price=subscription_price,
+            name=name,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def edit_subscription_invite_link(
+        self,
+        invite_link: Union[str, "ChatInviteLink"],
+        name: Optional[str] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> "ChatInviteLink":
+        """Shortcut for::
+
+            await bot.edit_chat_subscription_invite_link(
+                chat_id=update.effective_chat.id, *args, **kwargs
+            )
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.edit_chat_subscription_invite_link`.
+
+        .. versionadded:: 21.5
+
+        Returns:
+            :class:`telegram.ChatInviteLink`
+
+        """
+        return await self.get_bot().edit_chat_subscription_invite_link(
+            chat_id=self.id,
+            invite_link=invite_link,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+            name=name,
+        )
+
     async def approve_join_request(
         self,
         user_id: int,
@@ -3270,6 +3389,9 @@ class _ChatBase(TelegramObject):
         protect_content: ODVInput[bool] = DEFAULT_NONE,
         reply_parameters: Optional["ReplyParameters"] = None,
         reply_markup: Optional[ReplyMarkup] = None,
+        business_connection_id: Optional[str] = None,
+        payload: Optional[str] = None,
+        allow_paid_broadcast: Optional[bool] = None,
         *,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         reply_to_message_id: Optional[int] = None,
@@ -3310,6 +3432,49 @@ class _ChatBase(TelegramObject):
             connect_timeout=connect_timeout,
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
+            business_connection_id=business_connection_id,
+            payload=payload,
+            allow_paid_broadcast=allow_paid_broadcast,
+        )
+
+    async def send_gift(
+        self,
+        gift_id: Union[str, "Gift"],
+        text: Optional[str] = None,
+        text_parse_mode: ODVInput[str] = DEFAULT_NONE,
+        text_entities: Optional[Sequence["MessageEntity"]] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.send_gift(user_id=update.effective_chat.id, *args, **kwargs )
+
+        For the documentation of the arguments, please see :meth:`telegram.Bot.send_gift`.
+
+        Caution:
+            Can only work, if the chat is a private chat, see :attr:`type`.
+
+        .. versionadded:: 21.8
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().send_gift(
+            user_id=self.id,
+            gift_id=gift_id,
+            text=text,
+            text_parse_mode=text_parse_mode,
+            text_entities=text_entities,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
         )
 
 

telegram/_chatbackground.py

@@ -17,7 +17,8 @@
 # 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 collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, Optional
 
 from telegram import constants
 from telegram._files.document import Document
@@ -87,7 +88,7 @@ class BackgroundFill(TelegramObject):
         if not data:
             return None
 
-        _class_mapping: Dict[str, Type[BackgroundFill]] = {
+        _class_mapping: dict[str, type[BackgroundFill]] = {
             cls.SOLID: BackgroundFillSolid,
             cls.GRADIENT: BackgroundFillGradient,
             cls.FREEFORM_GRADIENT: BackgroundFillFreeformGradient,
@@ -212,7 +213,7 @@ class BackgroundFillFreeformGradient(BackgroundFill):
         super().__init__(type=self.FREEFORM_GRADIENT, api_kwargs=api_kwargs)
 
         with self._unfrozen():
-            self.colors: Tuple[int, ...] = parse_sequence_arg(colors)
+            self.colors: tuple[int, ...] = parse_sequence_arg(colors)
 
             self._id_attrs = (self.colors,)
 
@@ -278,7 +279,7 @@ class BackgroundType(TelegramObject):
         if not data:
             return None
 
-        _class_mapping: Dict[str, Type[BackgroundType]] = {
+        _class_mapping: dict[str, type[BackgroundType]] = {
             cls.FILL: BackgroundTypeFill,
             cls.WALLPAPER: BackgroundTypeWallpaper,
             cls.PATTERN: BackgroundTypePattern,
@@ -307,7 +308,7 @@ class BackgroundTypeFill(BackgroundType):
     .. versionadded:: 21.2
 
     Args:
-        fill (:obj:`telegram.BackgroundFill`): The background 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`.
@@ -315,7 +316,7 @@ class BackgroundTypeFill(BackgroundType):
     Attributes:
         type (:obj:`str`): Type of the background. Always
             :attr:`~telegram.BackgroundType.FILL`.
-        fill (:obj:`telegram.BackgroundFill`): The background 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`.
@@ -349,7 +350,7 @@ class BackgroundTypeWallpaper(BackgroundType):
     .. versionadded:: 21.2
 
     Args:
-        document (:obj:`telegram.Document`): Document with the 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`.
@@ -361,7 +362,7 @@ class BackgroundTypeWallpaper(BackgroundType):
     Attributes:
         type (:obj:`str`): Type of the background. Always
             :attr:`~telegram.BackgroundType.WALLPAPER`.
-        document (:obj:`telegram.Document`): Document with the 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`.
@@ -407,8 +408,8 @@ class BackgroundTypePattern(BackgroundType):
     .. versionadded:: 21.2
 
     Args:
-        document (:obj:`telegram.Document`): Document with the pattern.
-        fill (:obj:`telegram.BackgroundFill`): The background fill that is combined with
+        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;
@@ -422,8 +423,8 @@ class BackgroundTypePattern(BackgroundType):
     Attributes:
         type (:obj:`str`): Type of the background. Always
             :attr:`~telegram.BackgroundType.PATTERN`.
-        document (:obj:`telegram.Document`): Document with the pattern.
-        fill (:obj:`telegram.BackgroundFill`): The background fill that is combined with
+        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;
@@ -511,10 +512,10 @@ class ChatBackground(TelegramObject):
     .. versionadded:: 21.2
 
     Args:
-        type (:obj:`telegram.BackgroundType`): Type of the background.
+        type (:class:`telegram.BackgroundType`): Type of the background.
 
     Attributes:
-        type (:obj:`telegram.BackgroundType`): Type of the background.
+        type (:class:`telegram.BackgroundType`): Type of the background.
     """
 
     __slots__ = ("type",)

telegram/_chatboost.py

@@ -18,8 +18,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram ChatBoosts."""
 
+from collections.abc import Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Dict, Final, Optional, Sequence, Tuple, Type
+from typing import TYPE_CHECKING, Final, Optional
 
 from telegram import constants
 from telegram._chat import Chat
@@ -119,7 +120,7 @@ class ChatBoostSource(TelegramObject):
         if not data:
             return None
 
-        _class_mapping: Dict[str, Type[ChatBoostSource]] = {
+        _class_mapping: dict[str, type[ChatBoostSource]] = {
             cls.PREMIUM: ChatBoostSourcePremium,
             cls.GIFT_CODE: ChatBoostSourceGiftCode,
             cls.GIVEAWAY: ChatBoostSourceGiveaway,
@@ -187,15 +188,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.
 
@@ -205,17 +213,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,
     ):
@@ -224,6 +237,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
 
 
@@ -418,7 +432,7 @@ class UserChatBoosts(TelegramObject):
             user.
 
     Attributes:
-        boosts (Tuple[:class:`telegram.ChatBoost`]): List of boosts added to the chat by the user.
+        boosts (tuple[:class:`telegram.ChatBoost`]): List of boosts added to the chat by the user.
     """
 
     __slots__ = ("boosts",)
@@ -431,7 +445,7 @@ class UserChatBoosts(TelegramObject):
     ):
         super().__init__(api_kwargs=api_kwargs)
 
-        self.boosts: Tuple[ChatBoost, ...] = parse_sequence_arg(boosts)
+        self.boosts: tuple[ChatBoost, ...] = parse_sequence_arg(boosts)
 
         self._id_attrs = (self.boosts,)
         self._freeze()

telegram/_chatfullinfo.py

@@ -18,8 +18,9 @@
 # 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 collections.abc import Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from typing import TYPE_CHECKING, Optional
 
 from telegram._birthdate import Birthdate
 from telegram._chat import Chat, _ChatBase
@@ -78,7 +79,7 @@ class ChatFullInfo(_ChatBase):
             #collectible-usernames>`_; for private chats, supergroups and channels.
 
             .. versionadded:: 20.0
-        birthdate (:obj:`telegram.Birthdate`, optional): For private chats,
+        birthdate (:class:`telegram.Birthdate`, optional): For private chats,
             the date of birth of the user.
 
             .. versionadded:: 21.1
@@ -94,8 +95,8 @@ class ChatFullInfo(_ChatBase):
             chats with business accounts, the opening hours of the business.
 
             .. versionadded:: 21.1
-        personal_chat (:obj:`telegram.Chat`, optional): For private chats, the personal channel of
-            the user.
+        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
@@ -224,7 +225,7 @@ class ChatFullInfo(_ChatBase):
 
             .. versionadded:: 20.0
         photo (:class:`telegram.ChatPhoto`): Optional. Chat photo.
-        active_usernames (Tuple[:obj:`str`]): Optional. If set, the list of all `active chat
+        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.
 
@@ -232,7 +233,7 @@ class ChatFullInfo(_ChatBase):
             obtained via :meth:`~telegram.Bot.get_chat`.
 
             .. versionadded:: 20.0
-        birthdate (:obj:`telegram.Birthdate`): Optional. For private chats,
+        birthdate (:class:`telegram.Birthdate`): Optional. For private chats,
             the date of birth of the user.
 
             .. versionadded:: 21.1
@@ -248,11 +249,11 @@ class ChatFullInfo(_ChatBase):
             chats with business accounts, the opening hours of the business.
 
             .. versionadded:: 21.1
-        personal_chat (:obj:`telegram.Chat`): Optional. For private chats, the personal channel of
-            the user.
+        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
+        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.
 
@@ -483,14 +484,14 @@ class ChatFullInfo(_ChatBase):
             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.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(
+            self.available_reactions: Optional[tuple[ReactionType, ...]] = parse_sequence_arg(
                 available_reactions
             )
             self.accent_color_id: Optional[int] = accent_color_id

telegram/_chatinvitelink.py

@@ -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,

telegram/_chatmember.py

@@ -17,8 +17,9 @@
 # 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 ChatMember."""
+
 import datetime
-from typing import TYPE_CHECKING, Dict, Final, Optional, Type
+from typing import TYPE_CHECKING, Final, Optional
 
 from telegram import constants
 from telegram._telegramobject import TelegramObject
@@ -113,7 +114,7 @@ class ChatMember(TelegramObject):
         if not data:
             return None
 
-        _class_mapping: Dict[str, Type[ChatMember]] = {
+        _class_mapping: dict[str, type[ChatMember]] = {
             cls.OWNER: ChatMemberOwner,
             cls.ADMINISTRATOR: ChatMemberAdministrator,
             cls.MEMBER: ChatMemberMember,
@@ -391,24 +392,34 @@ class ChatMemberMember(ChatMember):
 
     Args:
         user (:class:`telegram.User`): Information about the user.
+        until_date (:class:`datetime.datetime`, optional): Date when the user's subscription will
+            expire.
+
+            .. versionadded:: 21.5
 
     Attributes:
         status (:obj:`str`): The member's status in the chat,
             always :tg-const:`telegram.ChatMember.MEMBER`.
         user (:class:`telegram.User`): Information about the user.
+        until_date (:class:`datetime.datetime`): Optional. Date when the user's subscription will
+            expire.
+
+            .. versionadded:: 21.5
 
     """
 
-    __slots__ = ()
+    __slots__ = ("until_date",)
 
     def __init__(
         self,
         user: User,
+        until_date: Optional[datetime.datetime] = None,
         *,
         api_kwargs: Optional[JSONDict] = None,
     ):
         super().__init__(status=ChatMember.MEMBER, user=user, api_kwargs=api_kwargs)
-        self._freeze()
+        with self._unfrozen():
+            self.until_date: Optional[datetime.datetime] = until_date
 
 
 class ChatMemberRestricted(ChatMember):

telegram/_chatmemberupdated.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChatMemberUpdated."""
 import datetime
-from typing import TYPE_CHECKING, Dict, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Optional, Union
 
 from telegram._chat import Chat
 from telegram._chatinvitelink import ChatInviteLink
@@ -162,7 +162,7 @@ class ChatMemberUpdated(TelegramObject):
 
         return super().de_json(data=data, bot=bot)
 
-    def _get_attribute_difference(self, attribute: str) -> Tuple[object, object]:
+    def _get_attribute_difference(self, attribute: str) -> tuple[object, object]:
         try:
             old = self.old_chat_member[attribute]
         except KeyError:
@@ -177,9 +177,9 @@ class ChatMemberUpdated(TelegramObject):
 
     def difference(
         self,
-    ) -> Dict[
+    ) -> dict[
         str,
-        Tuple[
+        tuple[
             Union[str, bool, datetime.datetime, User], Union[str, bool, datetime.datetime, User]
         ],
     ]:
@@ -198,7 +198,7 @@ class ChatMemberUpdated(TelegramObject):
         .. versionadded:: 13.5
 
         Returns:
-            Dict[:obj:`str`, Tuple[:class:`object`, :class:`object`]]: A dictionary mapping
+            dict[:obj:`str`, tuple[:class:`object`, :class:`object`]]: A dictionary mapping
             attribute names to tuples of the form ``(old_value, new_value)``
         """
         # we first get the names of the attributes that have changed

telegram/_copytextbutton.py

@@ -0,0 +1,55 @@
+#!/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 an object that represents a Telegram CopyTextButton."""
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class CopyTextButton(TelegramObject):
+    """
+    This object represents an inline keyboard button that copies specified text to the clipboard.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`text` is equal.
+
+    .. versionadded:: 21.7
+
+    Args:
+        text (:obj:`str`): The text to be copied to the clipboard;
+            :tg-const:`telegram.constants.InlineKeyboardButtonLimit.MIN_COPY_TEXT`-
+            :tg-const:`telegram.constants.InlineKeyboardButtonLimit.MAX_COPY_TEXT` characters
+
+    Attributes:
+        text (:obj:`str`): The text to be copied to the clipboard;
+            :tg-const:`telegram.constants.InlineKeyboardButtonLimit.MIN_COPY_TEXT`-
+            :tg-const:`telegram.constants.InlineKeyboardButtonLimit.MAX_COPY_TEXT` characters
+
+    """
+
+    __slots__ = ("text",)
+
+    def __init__(self, text: str, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+        self.text: str = text
+
+        self._id_attrs = (self.text,)
+
+        self._freeze()

telegram/_dice.py

@@ -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 Dice."""
-from typing import Final, List, Optional
+from typing import Final, Optional
 
 from telegram import constants
 from telegram._telegramobject import TelegramObject
@@ -114,8 +114,8 @@ class Dice(TelegramObject):
 
     .. versionadded:: 13.4
     """
-    ALL_EMOJI: Final[List[str]] = list(constants.DiceEmoji)
-    """List[:obj:`str`]: A list of all available dice emoji."""
+    ALL_EMOJI: Final[list[str]] = list(constants.DiceEmoji)
+    """list[:obj:`str`]: A list of all available dice emoji."""
 
     MIN_VALUE: Final[int] = constants.DiceLimit.MIN_VALUE
     """:const:`telegram.constants.DiceLimit.MIN_VALUE`

telegram/_files/_basethumbedmedium.py

@@ -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/].
 """Common base class for media objects with thumbnails"""
-from typing import TYPE_CHECKING, Optional, Type, TypeVar
+from typing import TYPE_CHECKING, Optional, TypeVar
 
 from telegram._files._basemedium import _BaseMedium
 from telegram._files.photosize import PhotoSize
@@ -82,7 +82,7 @@ class _BaseThumbedMedium(_BaseMedium):
 
     @classmethod
     def de_json(
-        cls: Type[ThumbedMT_co], data: Optional[JSONDict], bot: Optional["Bot"] = None
+        cls: type[ThumbedMT_co], data: Optional[JSONDict], bot: Optional["Bot"] = None
     ) -> Optional[ThumbedMT_co]:
         """See :meth:`telegram.TelegramObject.de_json`."""
         data = cls._parse_data(data)

telegram/_files/file.py

@@ -128,9 +128,8 @@ class File(TelegramObject):
     ) -> Path:
         """
         Download this file. By default, the file is saved in the current working directory with
-        :attr:`file_path` as file name. If the file has no filename, the file ID will be used as
-        filename. If :paramref:`custom_path` is supplied as a :obj:`str` or :obj:`pathlib.Path`,
-        it will be saved to that path.
+        :attr:`file_path` as file name. If :paramref:`custom_path` is supplied as a :obj:`str` or
+        :obj:`pathlib.Path`, it will be saved to that path.
 
         Note:
             If :paramref:`custom_path` isn't provided and :attr:`file_path` is the path of a
@@ -152,6 +151,11 @@ class File(TelegramObject):
             * This method was previously called ``download``. It was split into
               :meth:`download_to_drive` and :meth:`download_to_memory`.
 
+        .. versionchanged:: 21.7
+            Raises :exc:`RuntimeError` if :attr:`file_path` is not set. Note that files without
+            a :attr:`file_path` could never be downloaded, as this attribute is mandatory for that
+            operation.
+
         Args:
             custom_path (:class:`pathlib.Path` | :obj:`str` , optional): The path where the file
                 will be saved to. If not specified, will be saved in the current working directory
@@ -175,7 +179,13 @@ class File(TelegramObject):
         Returns:
             :class:`pathlib.Path`: Returns the Path object the file was downloaded to.
 
+        Raises:
+            RuntimeError: If :attr:`file_path` is not set.
+
         """
+        if not self.file_path:
+            raise RuntimeError("No `file_path` available for this file. Can not download.")
+
         local_file = is_local_file(self.file_path)
         url = None if local_file else self._get_encoded_url()
 
@@ -198,10 +208,8 @@ class File(TelegramObject):
             filename = Path(custom_path)
         elif local_file:
             return Path(self.file_path)
-        elif self.file_path:
-            filename = Path(Path(self.file_path).name)
         else:
-            filename = Path.cwd() / self.file_id
+            filename = Path(Path(self.file_path).name)
 
         buf = await self.get_bot().request.retrieve(
             url,
@@ -237,6 +245,11 @@ class File(TelegramObject):
 
         .. versionadded:: 20.0
 
+        .. versionchanged:: 21.7
+            Raises :exc:`RuntimeError` if :attr:`file_path` is not set. Note that files without
+            a :attr:`file_path` could never be downloaded, as this attribute is mandatory for that
+            operation.
+
         Args:
             out (:obj:`io.BufferedIOBase`): A file-like object. Must be opened for writing in
                 binary mode.
@@ -254,7 +267,13 @@ class File(TelegramObject):
             pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to
                 :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to
                 :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.
+
+        Raises:
+            RuntimeError: If :attr:`file_path` is not set.
         """
+        if not self.file_path:
+            raise RuntimeError("No `file_path` available for this file. Can not download.")
+
         local_file = is_local_file(self.file_path)
         url = None if local_file else self._get_encoded_url()
         path = Path(self.file_path) if local_file else None
@@ -283,6 +302,11 @@ class File(TelegramObject):
     ) -> bytearray:
         """Download this file and return it as a bytearray.
 
+        .. versionchanged:: 21.7
+            Raises :exc:`RuntimeError` if :attr:`file_path` is not set. Note that files without
+            a :attr:`file_path` could never be downloaded, as this attribute is mandatory for that
+            operation.
+
         Args:
             buf (:obj:`bytearray`, optional): Extend the given bytearray with the downloaded data.
 
@@ -312,7 +336,13 @@ class File(TelegramObject):
             :obj:`bytearray`: The same object as :paramref:`buf` if it was specified. Otherwise a
             newly allocated :obj:`bytearray`.
 
+        Raises:
+            RuntimeError: If :attr:`file_path` is not set.
+
         """
+        if not self.file_path:
+            raise RuntimeError("No `file_path` available for this file. Can not download.")
+
         if buf is None:
             buf = bytearray()
 

telegram/_files/inputfile.py

@@ -22,7 +22,8 @@ import mimetypes
 from typing import IO, Optional, Union
 from uuid import uuid4
 
-from telegram._utils.files import load_file
+from telegram._utils.files import guess_file_name, load_file
+from telegram._utils.strings import TextEncoding
 from telegram._utils.types import FieldTuple
 
 _DEFAULT_MIME_TYPE = "application/octet-stream"
@@ -52,9 +53,36 @@ class InputFile:
         attach (:obj:`bool`, optional): Pass :obj:`True` if the parameter this file belongs to in
             the request to Telegram should point to the multipart data via an ``attach://`` URI.
             Defaults to `False`.
+        read_file_handle (:obj:`bool`, optional): If :obj:`True` and :paramref:`obj` is a file
+            handle, the data will be read from the file handle on initialization of this object.
+            If :obj:`False`, the file handle will be passed on to the
+            :attr:`networking backend <telegram.request.BaseRequest.do_request>` which will have
+            to handle the reading. Defaults to :obj:`True`.
+
+            Tip:
+                If you upload extremely large files, you may want to set this to :obj:`False` to
+                avoid reading the complete file into memory. Additionally, this may be supported
+                better by the networking backend (in particular it is handled better by
+                the default :class:`~telegram.request.HTTPXRequest`).
+
+            Important:
+                If you set this to :obj:`False`, you have to ensure that the file handle is still
+                open when the request is made. In particular, the following snippet can *not* work
+                as expected.
+
+                .. code-block:: python
+
+                    with open('file.txt', 'rb') as file:
+                        input_file = InputFile(file, read_file_handle=False)
+
+                    # here the file handle is already closed and the upload will fail
+                    await bot.send_document(chat_id, input_file)
+
+            .. versionadded:: 21.5
+
 
     Attributes:
-        input_file_content (:obj:`bytes`): The binary content of the file to send.
+        input_file_content (:obj:`bytes` | :class:`IO`): The binary content of the file to send.
         attach_name (:obj:`str`): Optional. If present, the parameter this file belongs to in
             the request to Telegram should point to the multipart data via a an URI of the form
             ``attach://<attach_name>`` URI.
@@ -70,14 +98,18 @@ class InputFile:
         obj: Union[IO[bytes], bytes, str],
         filename: Optional[str] = None,
         attach: bool = False,
+        read_file_handle: bool = True,
     ):
         if isinstance(obj, bytes):
-            self.input_file_content: bytes = obj
+            self.input_file_content: Union[bytes, IO[bytes]] = obj
         elif isinstance(obj, str):
-            self.input_file_content = obj.encode("utf-8")
-        else:
+            self.input_file_content = obj.encode(TextEncoding.UTF_8)
+        elif read_file_handle:
             reported_filename, self.input_file_content = load_file(obj)
             filename = filename or reported_filename
+        else:
+            self.input_file_content = obj
+            filename = filename or guess_file_name(obj)
 
         self.attach_name: Optional[str] = "attached" + uuid4().hex if attach else None
 
@@ -94,8 +126,11 @@ class InputFile:
     def field_tuple(self) -> FieldTuple:
         """Field tuple representing the contents of the file for upload to the Telegram servers.
 
+        .. versionchanged:: 21.5
+            Content may now be a file handle.
+
         Returns:
-            Tuple[:obj:`str`, :obj:`bytes`, :obj:`str`]:
+            tuple[:obj:`str`, :obj:`bytes` | :class:`IO`, :obj:`str`]:
         """
         return self.filename, self.input_file_content, self.mimetype
 

telegram/_files/inputmedia.py

@@ -17,7 +17,8 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """Base class for Telegram InputMedia Objects."""
-from typing import Final, Optional, Sequence, Tuple, Union
+from collections.abc import Sequence
+from typing import Final, Optional, Union
 
 from telegram import constants
 from telegram._files.animation import Animation
@@ -50,8 +51,8 @@ class InputMedia(TelegramObject):
 
     Args:
         media_type (:obj:`str`): Type of media that the instance represents.
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Animation` |  :class:`telegram.Audio` | \
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` | \
+            :class:`pathlib.Path` | :class:`telegram.Animation` |  :class:`telegram.Audio` | \
             :class:`telegram.Document` | :class:`telegram.PhotoSize` | \
             :class:`telegram.Video`): File to send.
             |fileinputnopath|
@@ -74,7 +75,7 @@ class InputMedia(TelegramObject):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -99,7 +100,7 @@ class InputMedia(TelegramObject):
         self.type: str = enum.get_member(constants.InputMediaType, media_type, media_type)
         self.media: Union[str, InputFile, Animation, Audio, Document, PhotoSize, Video] = media
         self.caption: Optional[str] = caption
-        self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+        self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
         self.parse_mode: ODVInput[str] = parse_mode
 
         self._freeze()
@@ -128,8 +129,9 @@ class InputPaidMedia(TelegramObject):
 
     Args:
         type (:obj:`str`): Type of media that the instance represents.
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.PhotoSize` | :class:`telegram.Video`): File to send. |fileinputnopath|
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` | \
+            :class:`pathlib.Path` | :class:`telegram.PhotoSize` | :class:`telegram.Video`): File
+            to send. |fileinputnopath|
             Lastly you can pass an existing telegram media object of the corresponding type
             to send.
 
@@ -167,8 +169,8 @@ class InputPaidMediaPhoto(InputPaidMedia):
     .. versionadded:: 21.4
 
     Args:
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.PhotoSize`): File to send. |fileinputnopath|
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` | \
+            :class:`pathlib.Path` | :class:`telegram.PhotoSize`): File to send. |fileinputnopath|
             Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
 
     Attributes:
@@ -207,8 +209,8 @@ class InputPaidMediaVideo(InputPaidMedia):
            changed by Telegram.
 
     Args:
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Video`): File to send. |fileinputnopath|
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` | \
+            :class:`pathlib.Path` | :class:`telegram.Video`): File to send. |fileinputnopath|
             Lastly you can pass an existing :class:`telegram.Video` object to send.
         thumbnail (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`, \
                 optional): |thumbdocstringnopath|
@@ -278,8 +280,8 @@ class InputMediaAnimation(InputMedia):
       |removed_thumb_note|
 
     Args:
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Animation`): File to send. |fileinputnopath|
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` | \
+            :class:`pathlib.Path` | :class:`telegram.Animation`): File to send. |fileinputnopath|
             Lastly you can pass an existing :class:`telegram.Animation` object to send.
 
             .. versionchanged:: 13.2
@@ -320,7 +322,7 @@ class InputMediaAnimation(InputMedia):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -401,8 +403,8 @@ class InputMediaPhoto(InputMedia):
     .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
     Args:
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.PhotoSize`): File to send. |fileinputnopath|
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` | \
+            :class:`pathlib.Path` | :class:`telegram.PhotoSize`): File to send. |fileinputnopath|
             Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
 
             .. versionchanged:: 13.2
@@ -435,7 +437,7 @@ class InputMediaPhoto(InputMedia):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -501,8 +503,8 @@ class InputMediaVideo(InputMedia):
       |removed_thumb_note|
 
     Args:
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Video`): File to send. |fileinputnopath|
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` | \
+            :class:`pathlib.Path` | :class:`telegram.Video`): File to send. |fileinputnopath|
             Lastly you can pass an existing :class:`telegram.Video` object to send.
 
             .. versionchanged:: 13.2
@@ -545,7 +547,7 @@ class InputMediaVideo(InputMedia):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -639,8 +641,8 @@ class InputMediaAudio(InputMedia):
       |removed_thumb_note|
 
     Args:
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Audio`): File to send. |fileinputnopath|
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` | \
+            :class:`pathlib.Path` | :class:`telegram.Audio`): File to send. |fileinputnopath|
             Lastly you can pass an existing :class:`telegram.Audio` object to send.
 
             .. versionchanged:: 13.2
@@ -675,7 +677,7 @@ class InputMediaAudio(InputMedia):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -743,8 +745,8 @@ class InputMediaDocument(InputMedia):
       |removed_thumb_note|
 
     Args:
-        media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Document`): File to send. |fileinputnopath|
+        media (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` \
+            | :class:`pathlib.Path` | :class:`telegram.Document`): File to send. |fileinputnopath|
             Lastly you can pass an existing :class:`telegram.Document` object to send.
 
             .. versionchanged:: 13.2
@@ -778,7 +780,7 @@ class InputMediaDocument(InputMedia):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 

telegram/_files/inputsticker.py

@@ -18,7 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram InputSticker."""
 
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple, Union
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional, Union
 
 from telegram._files.sticker import MaskPosition
 from telegram._telegramobject import TelegramObject
@@ -41,14 +42,15 @@ class InputSticker(TelegramObject):
         order of the arguments has changed.
 
     Args:
-        sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`): The
+        sticker (:obj:`str` | :term:`file object` | :class:`~telegram.InputFile` | :obj:`bytes` \
+            | :class:`pathlib.Path`): The
             added sticker. |uploadinputnopath| Animated and video stickers can't be uploaded via
             HTTP URL.
         emoji_list (Sequence[:obj:`str`]): Sequence of
             :tg-const:`telegram.constants.StickerLimit.MIN_STICKER_EMOJI` -
             :tg-const:`telegram.constants.StickerLimit.MAX_STICKER_EMOJI` emoji associated with the
             sticker.
-        mask_position (:obj:`telegram.MaskPosition`, optional): Position where the mask should be
+        mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask should be
             placed on faces. For ":tg-const:`telegram.constants.StickerType.MASK`" stickers only.
         keywords (Sequence[:obj:`str`], optional): Sequence of
             0-:tg-const:`telegram.constants.StickerLimit.MAX_SEARCH_KEYWORDS` search keywords
@@ -66,13 +68,13 @@ class InputSticker(TelegramObject):
 
     Attributes:
         sticker (:obj:`str` | :class:`telegram.InputFile`): The added sticker.
-        emoji_list (Tuple[:obj:`str`]): Tuple of
+        emoji_list (tuple[:obj:`str`]): Tuple of
             :tg-const:`telegram.constants.StickerLimit.MIN_STICKER_EMOJI` -
             :tg-const:`telegram.constants.StickerLimit.MAX_STICKER_EMOJI` emoji associated with the
             sticker.
-        mask_position (:obj:`telegram.MaskPosition`): Optional. Position where the mask should be
+        mask_position (:class:`telegram.MaskPosition`): Optional. Position where the mask should be
             placed on faces. For ":tg-const:`telegram.constants.StickerType.MASK`" stickers only.
-        keywords (Tuple[:obj:`str`]): Optional. Tuple of
+        keywords (tuple[:obj:`str`]): Optional. Tuple of
             0-:tg-const:`telegram.constants.StickerLimit.MAX_SEARCH_KEYWORDS` search keywords
             for the sticker with the total length of up to
             :tg-const:`telegram.constants.StickerLimit.MAX_KEYWORD_LENGTH` characters. For
@@ -109,9 +111,9 @@ class InputSticker(TelegramObject):
             local_mode=True,
             attach=True,
         )
-        self.emoji_list: Tuple[str, ...] = parse_sequence_arg(emoji_list)
+        self.emoji_list: tuple[str, ...] = parse_sequence_arg(emoji_list)
         self.format: str = format
         self.mask_position: Optional[MaskPosition] = mask_position
-        self.keywords: Tuple[str, ...] = parse_sequence_arg(keywords)
+        self.keywords: tuple[str, ...] = parse_sequence_arg(keywords)
 
         self._freeze()

telegram/_files/sticker.py

@@ -17,7 +17,8 @@
 # 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 that represent stickers."""
-from typing import TYPE_CHECKING, Final, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, Optional
 
 from telegram import constants
 from telegram._files._basethumbedmedium import _BaseThumbedMedium
@@ -259,7 +260,7 @@ class StickerSet(TelegramObject):
     Attributes:
         name (:obj:`str`): Sticker set name.
         title (:obj:`str`): Sticker set title.
-        stickers (Tuple[:class:`telegram.Sticker`]): List of all set stickers.
+        stickers (tuple[:class:`telegram.Sticker`]): List of all set stickers.
 
             .. versionchanged:: 20.0
                 |tupleclassattrs|
@@ -296,7 +297,7 @@ class StickerSet(TelegramObject):
         super().__init__(api_kwargs=api_kwargs)
         self.name: str = name
         self.title: str = title
-        self.stickers: Tuple[Sticker, ...] = parse_sequence_arg(stickers)
+        self.stickers: tuple[Sticker, ...] = parse_sequence_arg(stickers)
         self.sticker_type: str = sticker_type
         # Optional
         self.thumbnail: Optional[PhotoSize] = thumbnail

telegram/_games/game.py

@@ -17,13 +17,15 @@
 # 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 Game."""
-from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._files.animation import Animation
 from telegram._files.photosize import PhotoSize
 from telegram._messageentity import MessageEntity
 from telegram._telegramobject import TelegramObject
 from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.strings import TextEncoding
 from telegram._utils.types import JSONDict
 
 if TYPE_CHECKING:
@@ -64,7 +66,7 @@ class Game(TelegramObject):
     Attributes:
         title (:obj:`str`): Title of the game.
         description (:obj:`str`): Description of the game.
-        photo (Tuple[:class:`telegram.PhotoSize`]): Photo that will be displayed in the game
+        photo (tuple[:class:`telegram.PhotoSize`]): Photo that will be displayed in the game
             message in chats.
 
             .. versionchanged:: 20.0
@@ -75,7 +77,7 @@ class Game(TelegramObject):
             when the bot calls :meth:`telegram.Bot.set_game_score`, or manually edited
             using :meth:`telegram.Bot.edit_message_text`.
             0-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters.
-        text_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. Special entities that
+        text_entities (tuple[:class:`telegram.MessageEntity`]): Optional. Special entities that
             appear in text, such as usernames, URLs, bot commands, etc.
             This tuple is empty if the message does not contain text entities.
 
@@ -111,10 +113,10 @@ class Game(TelegramObject):
         # Required
         self.title: str = title
         self.description: str = description
-        self.photo: Tuple[PhotoSize, ...] = parse_sequence_arg(photo)
+        self.photo: tuple[PhotoSize, ...] = parse_sequence_arg(photo)
         # Optionals
         self.text: Optional[str] = text
-        self.text_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(text_entities)
+        self.text_entities: tuple[MessageEntity, ...] = parse_sequence_arg(text_entities)
         self.animation: Optional[Animation] = animation
 
         self._id_attrs = (self.title, self.description, self.photo)
@@ -157,12 +159,12 @@ class Game(TelegramObject):
         if not self.text:
             raise RuntimeError("This Game has no 'text'.")
 
-        entity_text = self.text.encode("utf-16-le")
+        entity_text = self.text.encode(TextEncoding.UTF_16_LE)
         entity_text = entity_text[entity.offset * 2 : (entity.offset + entity.length) * 2]
 
-        return entity_text.decode("utf-16-le")
+        return entity_text.decode(TextEncoding.UTF_16_LE)
 
-    def parse_text_entities(self, types: Optional[List[str]] = None) -> Dict[MessageEntity, str]:
+    def parse_text_entities(self, types: Optional[list[str]] = None) -> dict[MessageEntity, str]:
         """
         Returns a :obj:`dict` that maps :class:`telegram.MessageEntity` to :obj:`str`.
         It contains entities from this message filtered by their
@@ -175,13 +177,13 @@ class Game(TelegramObject):
             See :attr:`parse_text_entity` for more info.
 
         Args:
-            types (List[:obj:`str`], optional): List of :class:`telegram.MessageEntity` types as
+            types (list[:obj:`str`], optional): List of :class:`telegram.MessageEntity` types as
                 strings. If the :attr:`~telegram.MessageEntity.type` attribute of an entity is
                 contained in this list, it will be returned. Defaults to
                 :attr:`telegram.MessageEntity.ALL_TYPES`.
 
         Returns:
-            Dict[:class:`telegram.MessageEntity`, :obj:`str`]: A dictionary of entities mapped to
+            dict[:class:`telegram.MessageEntity`, :obj:`str`]: A dictionary of entities mapped to
             the text that belongs to them, calculated based on UTF-16 codepoints.
 
         """

telegram/_gifts.py

@@ -0,0 +1,136 @@
+#!/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 classes related to gifs sent by bots."""
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
+
+from telegram._files.sticker import Sticker
+from telegram._telegramobject import TelegramObject
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class Gift(TelegramObject):
+    """This object represents a gift that can be sent by the bot.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal if their :attr:`id` is equal.
+
+    .. versionadded:: 21.8
+
+    Args:
+        id (:obj:`str`): Unique identifier of the gift
+        sticker (:class:`~telegram.Sticker`): The sticker that represents the gift
+        star_count (:obj:`int`): The number of Telegram Stars that must be paid to send the sticker
+        total_count (:obj:`int`, optional): The total number of the gifts of this type that can be
+            sent; for limited gifts only
+        remaining_count (:obj:`int`, optional): The number of remaining gifts of this type that can
+            be sent; for limited gifts only
+
+    Attributes:
+        id (:obj:`str`): Unique identifier of the gift
+        sticker (:class:`~telegram.Sticker`): The sticker that represents the gift
+        star_count (:obj:`int`): The number of Telegram Stars that must be paid to send the sticker
+        total_count (:obj:`int`): Optional. The total number of the gifts of this type that can be
+            sent; for limited gifts only
+        remaining_count (:obj:`int`): Optional. The number of remaining gifts of this type that can
+            be sent; for limited gifts only
+
+    """
+
+    __slots__ = ("id", "remaining_count", "star_count", "sticker", "total_count")
+
+    def __init__(
+        self,
+        id: str,
+        sticker: Sticker,
+        star_count: int,
+        total_count: Optional[int] = None,
+        remaining_count: Optional[int] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.id: str = id
+        self.sticker: Sticker = sticker
+        self.star_count: int = star_count
+        self.total_count: Optional[int] = total_count
+        self.remaining_count: Optional[int] = remaining_count
+
+        self._id_attrs = (self.id,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(cls, data: Optional[JSONDict], bot: Optional["Bot"] = None) -> Optional["Gift"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["sticker"] = Sticker.de_json(data.get("sticker"), bot)
+        return cls(**data)
+
+
+class Gifts(TelegramObject):
+    """This object represent a list of gifts.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal if their :attr:`gifts` are equal.
+
+    .. versionadded:: 21.8
+
+    Args:
+        gifts (Sequence[:class:`Gift`]): The sequence of gifts
+
+    Attributes:
+        gifts (tuple[:class:`Gift`]): The sequence of gifts
+
+    """
+
+    __slots__ = ("gifts",)
+
+    def __init__(
+        self,
+        gifts: Sequence[Gift],
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.gifts: tuple[Gift, ...] = parse_sequence_arg(gifts)
+
+        self._id_attrs = (self.gifts,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(cls, data: Optional[JSONDict], bot: Optional["Bot"] = None) -> Optional["Gifts"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["gifts"] = Gift.de_list(data.get("gifts"), bot)
+        return cls(**data)

telegram/_giveaway.py

@@ -18,7 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an objects that are related to Telegram giveaways."""
 import datetime
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._chat import Chat
 from telegram._telegramobject import TelegramObject
@@ -41,7 +42,7 @@ class Giveaway(TelegramObject):
     .. versionadded:: 20.8
 
     Args:
-        chats (Tuple[:class:`telegram.Chat`]): The list of chats which the user must join to
+        chats (tuple[:class:`telegram.Chat`]): The list of chats which the user must join to
             participate in the giveaway.
         winners_selection_date (:class:`datetime.datetime`): The date when the giveaway winner will
             be selected. |datetime_localization|
@@ -56,8 +57,13 @@ class Giveaway(TelegramObject):
             country codes indicating the countries from which eligible users for the giveaway must
             come. If empty, then all users can participate in the giveaway. Users with a phone
             number that was bought on Fragment can always participate in giveaways.
+        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
         premium_subscription_month_count (:obj:`int`, optional): The number of months the Telegram
-            Premium subscription won from the giveaway will be active for.
+            Premium subscription won from the giveaway will be active for; for Telegram Premium
+            giveaways only.
 
     Attributes:
         chats (Sequence[:class:`telegram.Chat`]): The list of chats which the user must join to
@@ -71,12 +77,17 @@ class Giveaway(TelegramObject):
         has_public_winners (:obj:`True`): Optional. :obj:`True`, if the list of giveaway winners
             will be visible to everyone
         prize_description (:obj:`str`): Optional. Description of additional giveaway prize
-        country_codes (Tuple[:obj:`str`]): Optional. A tuple of two-letter ISO 3166-1 alpha-2
+        country_codes (tuple[:obj:`str`]): Optional. A tuple of two-letter ISO 3166-1 alpha-2
             country codes indicating the countries from which eligible users for the giveaway must
             come. If empty, then all users can participate in the giveaway. Users with a phone
             number that was bought on Fragment can always participate in giveaways.
+        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
         premium_subscription_month_count (:obj:`int`): Optional. The number of months the Telegram
-            Premium subscription won from the giveaway will be active for.
+            Premium subscription won from the giveaway will be active for; for Telegram Premium
+            giveaways only.
     """
 
     __slots__ = (
@@ -86,6 +97,7 @@ class Giveaway(TelegramObject):
         "only_new_members",
         "premium_subscription_month_count",
         "prize_description",
+        "prize_star_count",
         "winner_count",
         "winners_selection_date",
     )
@@ -100,19 +112,21 @@ class Giveaway(TelegramObject):
         prize_description: Optional[str] = None,
         country_codes: Optional[Sequence[str]] = None,
         premium_subscription_month_count: Optional[int] = None,
+        prize_star_count: Optional[int] = None,
         *,
         api_kwargs: Optional[JSONDict] = None,
     ):
         super().__init__(api_kwargs=api_kwargs)
 
-        self.chats: Tuple[Chat, ...] = tuple(chats)
+        self.chats: tuple[Chat, ...] = tuple(chats)
         self.winners_selection_date: datetime.datetime = winners_selection_date
         self.winner_count: int = winner_count
         self.only_new_members: Optional[bool] = only_new_members
         self.has_public_winners: Optional[bool] = has_public_winners
         self.prize_description: Optional[str] = prize_description
-        self.country_codes: Tuple[str, ...] = parse_sequence_arg(country_codes)
+        self.country_codes: tuple[str, ...] = parse_sequence_arg(country_codes)
         self.premium_subscription_month_count: Optional[int] = premium_subscription_month_count
+        self.prize_star_count: Optional[int] = prize_star_count
 
         self._id_attrs = (
             self.chats,
@@ -126,7 +140,7 @@ class Giveaway(TelegramObject):
     def de_json(
         cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
     ) -> Optional["Giveaway"]:
-        """See :obj:`telegram.TelegramObject.de_json`."""
+        """See :meth:`telegram.TelegramObject.de_json`."""
         data = cls._parse_data(data)
 
         if data is None:
@@ -145,13 +159,28 @@ class Giveaway(TelegramObject):
 
 class GiveawayCreated(TelegramObject):
     """This object represents a service message about the creation of a scheduled giveaway.
-    Currently holds no information.
+
+    Args:
+        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
+
+    Attributes:
+        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
+
     """
 
-    __slots__ = ()
+    __slots__ = ("prize_star_count",)
 
-    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+    def __init__(
+        self, prize_star_count: Optional[int] = None, *, api_kwargs: Optional[JSONDict] = None
+    ):
         super().__init__(api_kwargs=api_kwargs)
+        self.prize_star_count: Optional[int] = prize_star_count
 
         self._freeze()
 
@@ -173,6 +202,10 @@ class GiveawayWinners(TelegramObject):
         winner_count (:obj:`int`): Total number of winners in the giveaway
         winners	(Sequence[:class:`telegram.User`]): List of up to
             :tg-const:`telegram.constants.GiveawayLimit.MAX_WINNERS` winners of the giveaway
+        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
         additional_chat_count (:obj:`int`, optional): The number of other chats the user had to
             join in order to be eligible for the giveaway
         premium_subscription_month_count (:obj:`int`, optional): The number of months the Telegram
@@ -190,10 +223,14 @@ class GiveawayWinners(TelegramObject):
         winners_selection_date (:class:`datetime.datetime`): Point in time when winners of the
             giveaway were selected. |datetime_localization|
         winner_count (:obj:`int`): Total number of winners in the giveaway
-        winners	(Tuple[:class:`telegram.User`]): tuple of up to
+        winners	(tuple[:class:`telegram.User`]): tuple of up to
             :tg-const:`telegram.constants.GiveawayLimit.MAX_WINNERS` winners of the giveaway
         additional_chat_count (:obj:`int`): Optional. The number of other chats the user had to
             join in order to be eligible for the giveaway
+        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
         premium_subscription_month_count (:obj:`int`): Optional. The number of months the Telegram
             Premium subscription won from the giveaway will be active for
         unclaimed_prize_count (:obj:`int`): Optional. Number of undistributed prizes
@@ -211,6 +248,7 @@ class GiveawayWinners(TelegramObject):
         "only_new_members",
         "premium_subscription_month_count",
         "prize_description",
+        "prize_star_count",
         "unclaimed_prize_count",
         "was_refunded",
         "winner_count",
@@ -231,6 +269,7 @@ class GiveawayWinners(TelegramObject):
         only_new_members: Optional[bool] = None,
         was_refunded: Optional[bool] = None,
         prize_description: Optional[str] = None,
+        prize_star_count: Optional[int] = None,
         *,
         api_kwargs: Optional[JSONDict] = None,
     ):
@@ -240,13 +279,14 @@ class GiveawayWinners(TelegramObject):
         self.giveaway_message_id: int = giveaway_message_id
         self.winners_selection_date: datetime.datetime = winners_selection_date
         self.winner_count: int = winner_count
-        self.winners: Tuple[User, ...] = tuple(winners)
+        self.winners: tuple[User, ...] = tuple(winners)
         self.additional_chat_count: Optional[int] = additional_chat_count
         self.premium_subscription_month_count: Optional[int] = premium_subscription_month_count
         self.unclaimed_prize_count: Optional[int] = unclaimed_prize_count
         self.only_new_members: Optional[bool] = only_new_members
         self.was_refunded: Optional[bool] = was_refunded
         self.prize_description: Optional[str] = prize_description
+        self.prize_star_count: Optional[int] = prize_star_count
 
         self._id_attrs = (
             self.chat,
@@ -262,7 +302,7 @@ class GiveawayWinners(TelegramObject):
     def de_json(
         cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
     ) -> Optional["GiveawayWinners"]:
-        """See :obj:`telegram.TelegramObject.de_json`."""
+        """See :meth:`telegram.TelegramObject.de_json`."""
         data = cls._parse_data(data)
 
         if data is None:
@@ -295,21 +335,29 @@ class GiveawayCompleted(TelegramObject):
         unclaimed_prize_count (:obj:`int`, optional): Number of undistributed prizes
         giveaway_message (:class:`telegram.Message`, optional): Message with the giveaway that was
             completed, if it wasn't deleted
+        is_star_giveaway (:obj:`bool`, optional): :obj:`True`, if the giveaway is a Telegram Star
+            giveaway. Otherwise, currently, the giveaway is a Telegram Premium giveaway.
 
+            .. versionadded:: 21.6
     Attributes:
         winner_count (:obj:`int`): Number of winners in the giveaway
         unclaimed_prize_count (:obj:`int`): Optional. Number of undistributed prizes
         giveaway_message (:class:`telegram.Message`): Optional. Message with the giveaway that was
             completed, if it wasn't deleted
+        is_star_giveaway (:obj:`bool`): Optional. :obj:`True`, if the giveaway is a Telegram Star
+            giveaway. Otherwise, currently, the giveaway is a Telegram Premium giveaway.
+
+            .. versionadded:: 21.6
     """
 
-    __slots__ = ("giveaway_message", "unclaimed_prize_count", "winner_count")
+    __slots__ = ("giveaway_message", "is_star_giveaway", "unclaimed_prize_count", "winner_count")
 
     def __init__(
         self,
         winner_count: int,
         unclaimed_prize_count: Optional[int] = None,
         giveaway_message: Optional["Message"] = None,
+        is_star_giveaway: Optional[bool] = None,
         *,
         api_kwargs: Optional[JSONDict] = None,
     ):
@@ -318,6 +366,7 @@ class GiveawayCompleted(TelegramObject):
         self.winner_count: int = winner_count
         self.unclaimed_prize_count: Optional[int] = unclaimed_prize_count
         self.giveaway_message: Optional[Message] = giveaway_message
+        self.is_star_giveaway: Optional[bool] = is_star_giveaway
 
         self._id_attrs = (
             self.winner_count,
@@ -330,7 +379,7 @@ class GiveawayCompleted(TelegramObject):
     def de_json(
         cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
     ) -> Optional["GiveawayCompleted"]:
-        """See :obj:`telegram.TelegramObject.de_json`."""
+        """See :meth:`telegram.TelegramObject.de_json`."""
         data = cls._parse_data(data)
 
         if data is None:

telegram/_inline/inlinekeyboardbutton.py

@@ -21,6 +21,7 @@
 from typing import TYPE_CHECKING, Final, Optional, Union
 
 from telegram import constants
+from telegram._copytextbutton import CopyTextButton
 from telegram._games.callbackgame import CallbackGame
 from telegram._loginurl import LoginUrl
 from telegram._switchinlinequerychosenchat import SwitchInlineQueryChosenChat
@@ -99,7 +100,7 @@ class InlineKeyboardButton(TelegramObject):
 
             .. seealso:: :wiki:`Arbitrary callback_data <Arbitrary-callback_data>`
 
-        web_app (:obj:`telegram.WebAppInfo`, optional): Description of the `Web App
+        web_app (:class:`telegram.WebAppInfo`, optional): Description of the `Web App
             <https://core.telegram.org/bots/webapps>`_  that will be launched when the user presses
             the button. The Web App will be able to send an arbitrary message on behalf of the user
             using the method :meth:`~telegram.Bot.answer_web_app_query`. Available only in
@@ -107,16 +108,14 @@ class InlineKeyboardButton(TelegramObject):
             a Telegram Business account.
 
             .. versionadded:: 20.0
-        switch_inline_query (:obj:`str`, optional): If set, pressing the button will insert the
-            bot's username and the specified inline query in the current chat's input field. May be
-            empty, in which case only the bot's username will be inserted.
-
-            This offers a quick way for the user to open your bot in inline mode in the same chat -
-            good for selecting something from multiple options. Not supported in channels and for
-            messages sent on behalf of a Telegram Business account.
+        switch_inline_query (:obj:`str`, optional): If set, pressing the button will prompt the
+            user to select one of their chats, open that chat and insert the bot's username and the
+            specified inline query in the input field. May be empty, in which case just the bot's
+            username will be inserted. Not supported for messages sent on behalf of a Telegram
+            Business account.
 
             Tip:
-                This is similar to the new parameter :paramref:`switch_inline_query_chosen_chat`,
+                This is similar to the parameter :paramref:`switch_inline_query_chosen_chat`,
                 but gives no control over which chats can be selected.
         switch_inline_query_current_chat (:obj:`str`, optional): If set, pressing the button will
             insert the bot's username and the specified inline query in the current chat's input
@@ -125,6 +124,10 @@ class InlineKeyboardButton(TelegramObject):
             This offers a quick way for the user to open your bot in inline mode in the same chat
             - good for selecting something from multiple options. Not supported in channels and for
             messages sent on behalf of a Telegram Business account.
+        copy_text (:class:`telegram.CopyTextButton`, optional): Description of the button that
+            copies the specified text to the clipboard.
+
+            .. versionadded:: 21.7
         callback_game (:class:`telegram.CallbackGame`, optional): Description of the game that will
             be launched when the user presses the button
 
@@ -137,7 +140,7 @@ class InlineKeyboardButton(TelegramObject):
             Note:
                 This type of button **must** always be the first button in the first row and can
                 only be used in invoice messages.
-        switch_inline_query_chosen_chat (:obj:`telegram.SwitchInlineQueryChosenChat`, optional):
+        switch_inline_query_chosen_chat (:class:`telegram.SwitchInlineQueryChosenChat`, optional):
             If set, pressing the button will prompt the user to select one of their chats of the
             specified type, open that chat and insert the bot's username and the specified inline
             query in the input field. Not supported for messages sent on behalf of a Telegram
@@ -170,7 +173,7 @@ class InlineKeyboardButton(TelegramObject):
             to the bot when the button is pressed, UTF-8
             :tg-const:`telegram.InlineKeyboardButton.MIN_CALLBACK_DATA`-
             :tg-const:`telegram.InlineKeyboardButton.MAX_CALLBACK_DATA` bytes.
-        web_app (:obj:`telegram.WebAppInfo`): Optional. Description of the `Web App
+        web_app (:class:`telegram.WebAppInfo`): Optional. Description of the `Web App
             <https://core.telegram.org/bots/webapps>`_  that will be launched when the user presses
             the button. The Web App will be able to send an arbitrary message on behalf of the user
             using the method :meth:`~telegram.Bot.answer_web_app_query`. Available only in
@@ -178,16 +181,14 @@ class InlineKeyboardButton(TelegramObject):
             a Telegram Business account.
 
             .. versionadded:: 20.0
-        switch_inline_query (:obj:`str`): Optional. If set, pressing the button will insert the
-            bot's username and the specified inline query in the current chat's input field. May be
-            empty, in which case only the bot's username will be inserted.
-
-            This offers a quick way for the user to open your bot in inline mode in the same chat -
-            good for selecting something from multiple options. Not supported in channels and for
-            messages sent on behalf of a Telegram Business account.
+        switch_inline_query (:obj:`str`): Optional. If set, pressing the button will prompt the
+            user to select one of their chats, open that chat and insert the bot's username and the
+            specified inline query in the input field. May be empty, in which case just the bot's
+            username will be inserted. Not supported for messages sent on behalf of a Telegram
+            Business account.
 
             Tip:
-                This is similar to the new parameter :paramref:`switch_inline_query_chosen_chat`,
+                This is similar to the parameter :paramref:`switch_inline_query_chosen_chat`,
                 but gives no control over which chats can be selected.
         switch_inline_query_current_chat (:obj:`str`): Optional. If set, pressing the button will
             insert the bot's username and the specified inline query in the current chat's input
@@ -196,6 +197,10 @@ class InlineKeyboardButton(TelegramObject):
             This offers a quick way for the user to open your bot in inline mode in the same chat
             - good for selecting something from multiple options. Not supported in channels and for
             messages sent on behalf of a Telegram Business account.
+        copy_text (:class:`telegram.CopyTextButton`): Optional. Description of the button that
+            copies the specified text to the clipboard.
+
+            .. versionadded:: 21.7
         callback_game (:class:`telegram.CallbackGame`): Optional. Description of the game that will
             be launched when the user presses the button.
 
@@ -208,7 +213,7 @@ class InlineKeyboardButton(TelegramObject):
             Note:
                 This type of button **must** always be the first button in the first row and can
                 only be used in invoice messages.
-        switch_inline_query_chosen_chat (:obj:`telegram.SwitchInlineQueryChosenChat`): Optional.
+        switch_inline_query_chosen_chat (:class:`telegram.SwitchInlineQueryChosenChat`): Optional.
             If set, pressing the button will prompt the user to select one of their chats of the
             specified type, open that chat and insert the bot's username and the specified inline
             query in the input field. Not supported for messages sent on behalf of a Telegram
@@ -228,6 +233,7 @@ class InlineKeyboardButton(TelegramObject):
     __slots__ = (
         "callback_data",
         "callback_game",
+        "copy_text",
         "login_url",
         "pay",
         "switch_inline_query",
@@ -250,6 +256,7 @@ class InlineKeyboardButton(TelegramObject):
         login_url: Optional[LoginUrl] = None,
         web_app: Optional[WebAppInfo] = None,
         switch_inline_query_chosen_chat: Optional[SwitchInlineQueryChosenChat] = None,
+        copy_text: Optional[CopyTextButton] = None,
         *,
         api_kwargs: Optional[JSONDict] = None,
     ):
@@ -269,6 +276,7 @@ class InlineKeyboardButton(TelegramObject):
         self.switch_inline_query_chosen_chat: Optional[SwitchInlineQueryChosenChat] = (
             switch_inline_query_chosen_chat
         )
+        self.copy_text: Optional[CopyTextButton] = copy_text
         self._id_attrs = ()
         self._set_id_attrs()
 
@@ -303,6 +311,7 @@ class InlineKeyboardButton(TelegramObject):
         data["switch_inline_query_chosen_chat"] = SwitchInlineQueryChosenChat.de_json(
             data.get("switch_inline_query_chosen_chat"), bot
         )
+        data["copy_text"] = CopyTextButton.de_json(data.get("copy_text"), bot)
 
         return super().de_json(data=data, bot=bot)
 

telegram/_inline/inlinekeyboardmarkup.py

@@ -17,7 +17,8 @@
 # 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 InlineKeyboardMarkup."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardbutton import InlineKeyboardButton
 from telegram._telegramobject import TelegramObject
@@ -57,7 +58,7 @@ class InlineKeyboardMarkup(TelegramObject):
                 |sequenceclassargs|
 
     Attributes:
-        inline_keyboard (Tuple[Tuple[:class:`telegram.InlineKeyboardButton`]]): Tuple of
+        inline_keyboard (tuple[tuple[:class:`telegram.InlineKeyboardButton`]]): Tuple of
             button rows, each represented by a tuple of :class:`~telegram.InlineKeyboardButton`
             objects.
 
@@ -81,7 +82,7 @@ class InlineKeyboardMarkup(TelegramObject):
                 "InlineKeyboardButtons"
             )
         # Required
-        self.inline_keyboard: Tuple[Tuple[InlineKeyboardButton, ...], ...] = tuple(
+        self.inline_keyboard: tuple[tuple[InlineKeyboardButton, ...], ...] = tuple(
             tuple(row) for row in inline_keyboard
         )
 

telegram/_inline/inlinequery.py

@@ -19,7 +19,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram InlineQuery."""
 
-from typing import TYPE_CHECKING, Callable, Final, Optional, Sequence, Union
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Callable, Final, Optional, Union
 
 from telegram import constants
 from telegram._files.location import Location

telegram/_inline/inlinequeryresultaudio.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultAudio."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -73,7 +74,7 @@ class InlineQueryResultAudio(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -124,6 +125,6 @@ class InlineQueryResultAudio(InlineQueryResult):
             self.audio_duration: Optional[int] = audio_duration
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content

telegram/_inline/inlinequeryresultcachedaudio.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultCachedAudio."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -68,7 +69,7 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -110,6 +111,6 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
             # Optionals
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content

telegram/_inline/inlinequeryresultcacheddocument.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultCachedDocument."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -72,7 +73,7 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -120,6 +121,6 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
             self.description: Optional[str] = description
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content

telegram/_inline/inlinequeryresultcachedgif.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultCachedGif."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -74,7 +75,7 @@ class InlineQueryResultCachedGif(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -124,7 +125,7 @@ class InlineQueryResultCachedGif(InlineQueryResult):
             self.title: Optional[str] = title
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content
             self.show_caption_above_media: Optional[bool] = show_caption_above_media

telegram/_inline/inlinequeryresultcachedmpeg4gif.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultMpeg4Gif."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -74,7 +75,7 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -124,7 +125,7 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
             self.title: Optional[str] = title
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content
             self.show_caption_above_media: Optional[bool] = show_caption_above_media

telegram/_inline/inlinequeryresultcachedphoto.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultPhoto"""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -76,7 +77,7 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -129,7 +130,7 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
             self.description: Optional[str] = description
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content
             self.show_caption_above_media: Optional[bool] = show_caption_above_media

telegram/_inline/inlinequeryresultcachedvideo.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultCachedVideo."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -72,7 +73,7 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -125,7 +126,7 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
             self.description: Optional[str] = description
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content
             self.show_caption_above_media: Optional[bool] = show_caption_above_media

telegram/_inline/inlinequeryresultcachedvoice.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultCachedVoice."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -70,7 +71,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
 
             .. versionchanged:: 20.0
 
@@ -115,6 +116,6 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
             # Optionals
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content

telegram/_inline/inlinequeryresultdocument.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultDocument"""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -86,7 +87,7 @@ class InlineQueryResultDocument(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -155,7 +156,7 @@ class InlineQueryResultDocument(InlineQueryResult):
             # Optionals
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.description: Optional[str] = description
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content

telegram/_inline/inlinequeryresultgif.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultGif."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -50,16 +51,14 @@ class InlineQueryResultGif(InlineQueryResult):
         gif_width (:obj:`int`, optional): Width of the GIF.
         gif_height (:obj:`int`, optional): Height of the GIF.
         gif_duration (:obj:`int`, optional): Duration of the GIF in seconds.
-        thumbnail_url (:obj:`str`, optional): URL of the static (JPEG or GIF) or animated (MPEG4)
+        thumbnail_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4)
             thumbnail for the result.
 
-            Warning:
-                The Bot API does **not** define this as an optional argument. It is formally
-                optional for backwards compatibility with the deprecated :paramref:`thumb_url`.
-                If you pass neither :paramref:`thumbnail_url` nor :paramref:`thumb_url`,
-                :class:`ValueError` will be raised.
-
             .. versionadded:: 20.2
+
+            ..versionchanged:: 20.5
+              |thumbnail_url_mandatory|
+
         thumbnail_mime_type (:obj:`str`, optional): MIME type of the thumbnail, must be one of
             ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``.
 
@@ -82,10 +81,6 @@ class InlineQueryResultGif(InlineQueryResult):
 
             .. versionadded:: 21.3
 
-    Raises:
-        :class:`ValueError`: If neither :paramref:`thumbnail_url` nor :paramref:`thumb_url` is
-            supplied or if both are supplied and are not equal.
-
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.GIF`.
         id (:obj:`str`): Unique identifier for this result,
@@ -108,7 +103,7 @@ class InlineQueryResultGif(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -172,7 +167,7 @@ class InlineQueryResultGif(InlineQueryResult):
             self.title: Optional[str] = title
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content
             self.thumbnail_mime_type: Optional[str] = thumbnail_mime_type

telegram/_inline/inlinequeryresultmpeg4gif.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultMpeg4Gif."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -51,16 +52,14 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         mpeg4_width (:obj:`int`, optional): Video width.
         mpeg4_height (:obj:`int`, optional): Video height.
         mpeg4_duration (:obj:`int`, optional): Video duration in seconds.
-        thumbnail_url (:obj:`str`, optional): URL of the static (JPEG or GIF) or animated (MPEG4)
+        thumbnail_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4)
             thumbnail for the result.
 
-            Warning:
-                The Bot API does **not** define this as an optional argument. It is formally
-                optional for backwards compatibility with the deprecated :paramref:`thumb_url`.
-                If you pass neither :paramref:`thumbnail_url` nor :paramref:`thumb_url`,
-                :class:`ValueError` will be raised.
-
             .. versionadded:: 20.2
+
+            ..versionchanged:: 20.5
+              |thumbnail_url_mandatory|
+
         thumbnail_mime_type (:obj:`str`, optional): MIME type of the thumbnail, must be one of
             ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``.
 
@@ -83,9 +82,6 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         show_caption_above_media (:obj:`bool`, optional): Pass |show_cap_above_med|
 
             .. versionadded:: 21.3
-    Raises:
-        :class:`ValueError`: If neither :paramref:`thumbnail_url` nor :paramref:`thumb_url` is
-            supplied or if both are supplied and are not equal.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.MPEG4GIF`.
@@ -109,7 +105,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
 
             .. versionchanged:: 20.0
 
@@ -173,7 +169,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
             self.title: Optional[str] = title
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content
             self.thumbnail_mime_type: Optional[str] = thumbnail_mime_type

telegram/_inline/inlinequeryresultphoto.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultPhoto."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -48,15 +49,13 @@ class InlineQueryResultPhoto(InlineQueryResult):
             :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         photo_url (:obj:`str`): A valid URL of the photo. Photo must be in JPEG format. Photo size
             must not exceed 5MB.
-        thumbnail_url (:obj:`str`, optional): URL of the thumbnail for the photo.
-
-            Warning:
-                The Bot API does **not** define this as an optional argument. It is formally
-                optional for backwards compatibility with the deprecated :paramref:`thumb_url`.
-                If you pass neither :paramref:`thumbnail_url` nor :paramref:`thumb_url`,
-                :class:`ValueError` will be raised.
+        thumbnail_url (:obj:`str`): URL of the thumbnail for the photo.
 
             .. versionadded:: 20.2
+
+            ..versionchanged:: 20.5
+              |thumbnail_url_mandatory|
+
         photo_width (:obj:`int`, optional): Width of the photo.
         photo_height (:obj:`int`, optional): Height of the photo.
         title (:obj:`str`, optional): Title for the result.
@@ -78,10 +77,6 @@ class InlineQueryResultPhoto(InlineQueryResult):
 
             .. versionadded:: 21.3
 
-    Raises:
-        :class:`ValueError`: If neither :paramref:`thumbnail_url` nor :paramref:`thumb_url` is
-            supplied or if both are supplied and are not equal.
-
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.PHOTO`.
         id (:obj:`str`): Unique identifier for this result,
@@ -98,7 +93,7 @@ class InlineQueryResultPhoto(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr|
 
             .. versionchanged:: 20.0
 
@@ -160,7 +155,7 @@ class InlineQueryResultPhoto(InlineQueryResult):
             self.description: Optional[str] = description
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
             self.input_message_content: Optional[InputMessageContent] = input_message_content
             self.show_caption_above_media: Optional[bool] = show_caption_above_media

telegram/_inline/inlinequeryresultvideo.py

@@ -17,7 +17,8 @@
 # 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 the classes that represent Telegram InlineQueryResultVideo."""
-from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
@@ -55,20 +56,12 @@ class InlineQueryResultVideo(InlineQueryResult):
         mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4".
         thumbnail_url (:obj:`str`, optional): URL of the thumbnail (JPEG only) for the video.
 
-            Warning:
-                The Bot API does **not** define this as an optional argument. It is formally
-                optional for backwards compatibility with the deprecated :paramref:`thumb_url`.
-                If you pass neither :paramref:`thumbnail_url` nor :paramref:`thumb_url`,
-                :class:`ValueError` will be raised.
-
             .. versionadded:: 20.2
-        title (:obj:`str`, optional): Title for the result.
 
-            Warning:
-                The Bot API does **not** define this as an optional argument. It is formally
-                optional to ensure backwards compatibility of :paramref:`thumbnail_url` with the
-                deprecated :paramref:`thumb_url`, which required that :paramref:`thumbnail_url`
-                become optional. :class:`TypeError` will be raised if no ``title`` is passed.
+            ..versionchanged:: 20.5
+              |thumbnail_url_mandatory|
+
+        title (:obj:`str`): Title for the result.
         caption (:obj:`str`, optional): Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
@@ -92,11 +85,6 @@ class InlineQueryResultVideo(InlineQueryResult):
 
             .. versionadded:: 21.3
 
-    Raises:
-        :class:`ValueError`: If neither :paramref:`thumbnail_url` nor :paramref:`thumb_url` is
-            supplied or if both are supplied and are not equal.
-        :class:`TypeError`: If no :paramref:`title` is passed.
-
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.VIDEO`.
         id (:obj:`str`): Unique identifier for this result,
@@ -112,7 +100,7 @@ class InlineQueryResultVideo(InlineQueryResult):
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
         parse_mode (:obj:`str`): Optional. |parse_mode|
-        caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional.
+        caption_entities (tuple[:class:`telegram.MessageEntity`]): Optional.
             |captionentitiesattr|
 
             .. versionchanged:: 20.0
@@ -184,7 +172,7 @@ class InlineQueryResultVideo(InlineQueryResult):
             # Optional
             self.caption: Optional[str] = caption
             self.parse_mode: ODVInput[str] = parse_mode
-            self.caption_entities: Tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
+            self.caption_entities: tuple[MessageEntity, ...] = parse_sequence_arg(caption_entities)
             self.video_width: Optional[int] = video_width
             self.video_height: Optional[int] = video_height
             self.video_duration: Optional[int] = video_duration