Use Lock instead of semaphore

Add an example on concurrency in FSM
Try setting up infrastructure for optimistic locking. Example will follow
2026-06-20 08:05:27 +00:00 · 2025-02-06 12:05:20 +01:00 · 2025-02-06 11:57:18 +01:00 · 2025-02-05 23:40:15 +01:00 · 2025-02-05 13:13:21 +01:00 · 2025-02-05 12:26:02 +01:00
460 changed files with 6237 additions and 3546 deletions
@@ -5,6 +5,9 @@ updates:
    schedule:
      interval: "weekly"
      day: "friday"
+    labels:
+      - "⚙️ dependencies"
+      - "🔗 python"

  # Updates the dependencies of the GitHub Actions workflows
  - package-ecosystem: "github-actions"
@@ -12,3 +15,6 @@ updates:
    schedule:
      interval: "monthly"
      day: "friday"
+    labels:
+      - "⚙️ dependencies"
+      - "🔗 github-actions"
@@ -4,6 +4,8 @@ on:
  pull_request:
    types: [opened, reopened]

+permissions: {}
+
 jobs:
  process-dependabot-prs:
    permissions:
@@ -16,14 +18,15 @@ jobs:

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

-    - uses: actions/checkout@v4
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      with:
        ref: ${{ github.event.pull_request.head.ref }}
+        persist-credentials: false

    - name: Update Version Number in Other Files
-      uses: jacobtomlinson/gha-find-replace@v3
+      uses: jacobtomlinson/gha-find-replace@f1069b438f125e5395d84d1c6fd3b559a7880cb5 # v3
      with:
        find: ${{ steps.dependabot-metadata.outputs.previous-version }}
        replace: ${{ steps.dependabot-metadata.outputs.new-version }}
@@ -31,7 +34,7 @@ jobs:
        exclude: CHANGES.rst

    - name: Commit & Push Changes to PR
-      uses: EndBug/add-and-commit@v9.1.4
+      uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5 # v9.1.4
      with:
        message: 'Update version number in other files'
        committer_name: GitHub Actions
@@ -1,30 +0,0 @@
-name: Check Links in Documentation
-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:
-    name: test-sphinx-linkcheck
-    runs-on: ${{matrix.os}}
-    strategy:
-      matrix:
-        python-version: ['3.10']
-        os: [ubuntu-latest]
-      fail-fast: False
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: |
-          python -W ignore -m pip install --upgrade pip
-          python -W ignore -m pip install -r requirements-dev-all.txt
-      - name: Check Links
-        run: sphinx-build docs/source docs/build/html -W --keep-going -j auto -b linkcheck
@@ -1,46 +0,0 @@
-name: Test Documentation Build
-on:
-  pull_request:
-    paths:
-      - telegram/**
-      - docs/**
-  push:
-    branches:
-      - master
-
-jobs:
-  test-sphinx-build:
-    name: test-sphinx-build
-    runs-on: ${{matrix.os}}
-    strategy:
-      matrix:
-        python-version: ['3.10']
-        os: [ubuntu-latest]
-      fail-fast: False
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: 'pip'
-          cache-dependency-path: '**/requirements*.txt'
-      - name: Install dependencies
-        run: |
-          python -W ignore -m pip install --upgrade pip
-          python -W ignore -m pip install -r requirements-dev-all.txt
-      - name: Test autogeneration of admonitions
-        run: pytest -v --tb=short tests/docs/admonition_inserter.py
-      - name: Build docs
-        run: sphinx-build docs/source docs/build/html -W --keep-going -j auto
-      - name: Upload docs
-        uses: actions/upload-artifact@v4
-        with:
-          name: HTML Docs
-          retention-days: 7
-          path: |
-            # Exclude the .doctrees folder and .buildinfo file from the artifact
-            # since they are not needed and add to the size
-            docs/build/html/*
-            !docs/build/html/.doctrees
-            !docs/build/html/.buildinfo
@@ -0,0 +1,33 @@
+name: GitHub Actions Security Analysis
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions: {}
+
+jobs:
+  zizmor:
+    name: Security Analysis with zizmor
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
+      - name: Run zizmor
+        run: uvx zizmor --persona=pedantic --format sarif . > results.sarif
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@dd746615b3b9d728a6a37ca2045b68ca76d4841a # v3.28.8
+        with:
+          sarif_file: results.sarif
+          category: zizmor
@@ -4,6 +4,8 @@ on:
  pull_request:
    types: [opened]

+permissions: {}
+
 jobs:
  pre-commit-ci:
    permissions:
@@ -11,7 +13,7 @@ jobs:
      pull-requests: write # for srvaroa/labeler to add labels in PR
    runs-on: ubuntu-latest
    steps:
-    - uses: srvaroa/labeler@v1.11.1
+    - uses: srvaroa/labeler@fe4b1c73bb8abf2f14a44a6912a8b4fee835d631 # v1.12.0
      # Config file at .github/labeler.yml
      env:
        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
@@ -4,11 +4,17 @@ on:
  schedule:
    - cron: '8 4 * * *'

+permissions: {}
+
 jobs:
  lock:
    runs-on: ubuntu-latest
+    permissions:
+      # For locking the threads
+      issues: write
+      pull-requests: write
    steps:
-      - uses: dessant/lock-threads@v5.0.1
+      - uses: dessant/lock-threads@1bf7ec25051fe7c00bdd17e6a7cf3d7bfb7dc771 # v5.0.1
        with:
          github-token: ${{ github.token }}
          issue-inactive-days: '7'
@@ -4,17 +4,24 @@ on:
  # manually trigger the workflow
  workflow_dispatch:

+permissions: {}
+
 jobs:
  build:
    name: Build Distribution
    runs-on: ubuntu-latest
    outputs:
      TAG: ${{ steps.get_tag.outputs.TAG }}
+    permissions:
+      # for uploading artifacts
+      actions: write

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
        with:
          python-version: "3.x"
      - name: Install pypa/build
@@ -23,7 +30,7 @@ jobs:
      - name: Build a binary wheel and a source tarball
        run: python3 -m build
      - name: Store the distribution packages
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
        with:
          name: python-package-distributions
          path: dist/
@@ -44,15 +51,16 @@ jobs:
      url: https://pypi.org/p/python-telegram-bot
    permissions:
      id-token: write  # IMPORTANT: mandatory for trusted publishing
+      actions: read  # for downloading artifacts

    steps:
      - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          name: python-package-distributions
          path: dist/
      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3

  compute-signatures:
    name: Compute SHA1 Sums and Sign with Sigstore
@@ -62,10 +70,11 @@ jobs:

    permissions:
      id-token: write  # IMPORTANT: mandatory for sigstore
+      actions: write  # for up/downloading artifacts

    steps:
      - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          name: python-package-distributions
          path: dist/
@@ -77,13 +86,13 @@ jobs:
              sha1sum $file > $file.sha1
          done
      - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46 # v3.0.0
        with:
          inputs: >-
            ./dist/*.tar.gz
            ./dist/*.whl
      - name: Store the distribution packages and signatures
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
        with:
          name: python-package-distributions-and-signatures
          path: dist/
@@ -98,10 +107,11 @@ jobs:

    permissions:
      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      actions: read  # for downloading artifacts

    steps:
      - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          name: python-package-distributions-and-signatures
          path: dist/
@@ -113,7 +123,7 @@ jobs:
        # we don't define it through this workflow.
        run: >-
          gh release create
-          '${{ env.TAG }}'
+          "$TAG"
          --repo '${{ github.repository }}'
          --generate-notes
      - name: Upload artifact signatures to GitHub Release
@@ -125,5 +135,5 @@ jobs:
        # sigstore-produced signatures and certificates.
        run: >-
          gh release upload
-          '${{ env.TAG }}' dist/**
+          "$TAG" dist/**
          --repo '${{ github.repository }}'
@@ -4,17 +4,24 @@ on:
  # manually trigger the workflow
  workflow_dispatch:

+permissions: {}
+
 jobs:
  build:
    name: Build Distribution
    runs-on: ubuntu-latest
    outputs:
      TAG: ${{ steps.get_tag.outputs.TAG }}
+    permissions:
+      # for uploading artifacts
+      actions: write

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
        with:
          python-version: "3.x"
      - name: Install pypa/build
@@ -23,7 +30,7 @@ jobs:
      - name: Build a binary wheel and a source tarball
        run: python3 -m build
      - name: Store the distribution packages
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
        with:
          name: python-package-distributions
          path: dist/
@@ -44,15 +51,16 @@ jobs:
      url: https://test.pypi.org/p/python-telegram-bot
    permissions:
      id-token: write  # IMPORTANT: mandatory for trusted publishing
+      actions: read  # for downloading artifacts

    steps:
      - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          name: python-package-distributions
          path: dist/
      - name: Publish to Test PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
        with:
          repository-url: https://test.pypi.org/legacy/

@@ -64,10 +72,11 @@ jobs:

    permissions:
      id-token: write  # IMPORTANT: mandatory for sigstore
+      actions: write  # for up/downloading artifacts

    steps:
      - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          name: python-package-distributions
          path: dist/
@@ -79,13 +88,13 @@ jobs:
              sha1sum $file > $file.sha1
          done
      - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46 # v3.0.0
        with:
          inputs: >-
            ./dist/*.tar.gz
            ./dist/*.whl
      - name: Store the distribution packages and signatures
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
        with:
          name: python-package-distributions-and-signatures
          path: dist/
@@ -100,10 +109,11 @@ jobs:

    permissions:
      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      actions: read  # for downloading artifacts

    steps:
      - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          name: python-package-distributions-and-signatures
          path: dist/
@@ -115,7 +125,7 @@ jobs:
        # we don't define it through this workflow.
        run: >-
          gh release create
-          '${{ env.TAG }}'
+          "$TAG"
          --repo '${{ github.repository }}'
          --generate-notes
          --draft
@@ -128,5 +138,5 @@ jobs:
        # sigstore-produced signatures and certificates.
        run: >-
          gh release upload
-          '${{ env.TAG }}' dist/**
+          "$TAG" dist/**
          --repo '${{ github.repository }}'
@@ -3,11 +3,16 @@ on:
  schedule:
    - cron: '42 2 * * *'

+permissions: {}
+
 jobs:
  stale:
    runs-on: ubuntu-latest
+    permissions:
+      # For adding labels and closing
+      issues: write
    steps:
-      - uses: actions/stale@v9
+      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9.1.0
        with:
          # PRs never get stale
          days-before-stale: 3
@@ -1,47 +0,0 @@
-name: Bot API Tests
-on:
-  pull_request:
-    paths:
-      - telegram/**
-      - tests/**
-  push:
-    branches:
-      - master
-  schedule:
-    # Run monday and friday morning at 03:07 - odd time to spread load on GitHub Actions
-    - cron: '7 3 * * 1,5'
-
-jobs:
-  check-conformity:
-    name: check-conformity
-    runs-on: ${{matrix.os}}
-    strategy:
-      matrix:
-        python-version: [3.11]
-        os: [ubuntu-latest]
-      fail-fast: False
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: |
-          python -W ignore -m pip install --upgrade pip
-          python -W ignore -m pip install .[all]
-          python -W ignore -m pip install -r requirements-unit-tests.txt
-      - name: Compare to official api
-        run: |
-          pytest -v tests/test_official/test_official.py --junit-xml=.test_report_official.xml
-          exit $?
-        env:
-          TEST_OFFICIAL: "true"
-        shell: bash --noprofile --norc {0}
-
-      - name: Test Summary
-        id: test_summary
-        uses: test-summary/action@v2.4
-        if: always()  # always run, even if tests fail
-        with:
-          paths: .test_report_official.xml
@@ -1,21 +0,0 @@
-name: Check Type Completeness
-on:
-  pull_request:
-    paths:
-      - telegram/**
-      - pyproject.toml
-      - .github/workflows/type_completeness.yml
-  push:
-    branches:
-      - master
-
-jobs:
-  test-type-completeness:
-    name:   test-type-completeness
-    runs-on: ubuntu-latest
-    steps:
-      - uses: Bibo-Joshi/pyright-type-completeness@1.0.1
-        with:
-          package-name: telegram
-          python-version: 3.12
-          pyright-version: ~=1.1.367
@@ -4,19 +4,21 @@ on:
    # Run first friday of the month at 03:17 - odd time to spread load on GitHub Actions
    - cron: '17 3 1-7 * 5'

+permissions: {}
+
 jobs:
  test-type-completeness:
    name:   test-type-completeness
    runs-on: ubuntu-latest
    steps:
-      - uses: Bibo-Joshi/pyright-type-completeness@1.0.1
+      - uses: Bibo-Joshi/pyright-type-completeness@c85a67ff3c66f51dcbb2d06bfcf4fe83a57d69cc # v1.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
+        uses: jannekem/run-python-script-action@bbfca66c612a28f3eeca0ae40e1f810265e2ea68 # v1.7
        env:
          TYPE_COMPLETENESS: ${{ steps.pyright-type-completeness.outputs.base-completeness-score }}
        with:
@@ -67,6 +67,7 @@ docs/_build/
 # PyBuilder
 target/
 .idea/
+.run/

 # Sublime Text 2
 *.sublime*
@@ -7,7 +7,7 @@ ci:

 repos:
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.5.6'
+    rev: 'v0.8.6'
    hooks:
    -   id: ruff
        name: ruff
@@ -16,20 +16,20 @@ repos:
          - tornado~=6.4
          - APScheduler~=3.10.4
          - cachetools>=5.3.3,<5.5.0
-          - aiolimiter~=1.1.0
+          - aiolimiter~=1.1,<1.3
 -   repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.4.2
+    rev: 24.10.0
    hooks:
    -   id: black
        args:
        - --diff
        - --check
 -   repo: https://github.com/PyCQA/flake8
-    rev: 7.1.0
+    rev: 7.1.1
    hooks:
    -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v3.2.4
+    rev: v3.3.3
    hooks:
    -   id: pylint
        files: ^(?!(tests|docs)).*\.py$
@@ -38,10 +38,10 @@ repos:
          - tornado~=6.4
          - APScheduler~=3.10.4
          - cachetools>=5.3.3,<5.5.0
-          - aiolimiter~=1.1.0
+          - aiolimiter~=1.1,<1.3
          - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.10.1
+    rev: v1.14.1
    hooks:
    -   id: mypy
        name: mypy-ptb
@@ -54,7 +54,7 @@ repos:
          - tornado~=6.4
          - APScheduler~=3.10.4
          - cachetools>=5.3.3,<5.5.0
-          - aiolimiter~=1.1.0
+          - aiolimiter~=1.1,<1.3
          - . # this basically does `pip install -e .`
    - id: mypy
      name: mypy-examples
@@ -68,7 +68,7 @@ repos:
        - cachetools>=5.3.3,<5.5.0
        - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.16.0
+    rev: v3.19.1
    hooks:
    -   id: pyupgrade
        args:
@@ -31,6 +31,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Ambro17 <https://github.com/Ambro17>`_
 - `Andrej Zhilenkov <https://github.com/Andrej730>`_
 - `Anton Tagunov <https://github.com/anton-tagunov>`_
+- `Anya Marcano <https://github.com/AnyaMarcanito>`
 - `Avanatiker <https://github.com/Avanatiker>`_
 - `Balduro <https://github.com/Balduro>`_
 - `Bibo-Joshi <https://github.com/Bibo-Joshi>`_
@@ -58,12 +59,14 @@ The following wonderful people contributed directly or indirectly to this projec
 - `gamgi <https://github.com/gamgi>`_
 - `Gauthamram Ravichandran <https://github.com/GauthamramRavichandran>`_
 - `Harshil <https://github.com/harshil21>`_
+- `Henry Galue <https://github.com/henryg311>`
 - `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>`_
+- `Jeamhowards Montiel <https://github.com/Jeam-zx>`
 - `jeffffc <https://github.com/jeffffc>`_
 - `Jelle Besseling <https://github.com/pingiun>`_
 - `jh0ker <https://github.com/jh0ker>`_
@@ -72,6 +75,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Joscha Götzer <https://github.com/Rostgnom>`_
 - `jossalgon <https://github.com/jossalgon>`_
 - `JRoot3D <https://github.com/JRoot3D>`_
+- `Juan Cuevas <https://github.com/cuevasrja>`
 - `kenjitagawa <https://github.com/kenjitagawa>`_
 - `kennethcheo <https://github.com/kennethcheo>`_
 - `Kirill Vasin <https://github.com/vasinkd>`_
@@ -81,11 +85,13 @@ 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>`_
 - `Michael Elovskikh <https://github.com/wronglink>`_
 - `Miguel C. R. <https://github.com/MiguelX413>`_
+- `Miguel Salomon <https://github.com/Migueldsc12>`
 - `miles <https://github.com/miles170>`_
 - `Mischa Krüger <https://github.com/Makman2>`_
 - `Mohd Yusuf <https://github.com/mohdyusuf2312>`_
@@ -111,7 +117,7 @@ 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>`_
+- Snehashish Biswas
 - `Sahil Sharma <https://github.com/sahilsharma811>`_
 - `Sam Mosleh <https://github.com/sam-mosleh>`_
 - `Sascha <https://github.com/saschalalala>`_
@@ -4,6 +4,74 @@
 Changelog
 =========

+Version 21.10
+=============
+
+*Released 2025-01-03*
+
+This is the technical changelog for version 21.10. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 8.2 (:pr:`4633`)
+- Bump ``apscheduler`` & Deprecate ``pytz`` Support (:pr:`4582`)
+
+New Features
+------------
+- Add Parameter ``pattern`` to ``JobQueue.jobs()`` (:pr:`4613` closes :issue:`4544`)
+- Allow Input of Type ``Sticker`` for Several Methods (:pr:`4616` closes :issue:`4580`)
+
+Bug Fixes
+---------
+- Ensure Forward Compatibility of ``Gift`` and ``Gifts`` (:pr:`4634` closes :issue:`4637`)
+
+
+Documentation Improvements & Internal Changes
+---------------------------------------------
+
+- Use Custom Labels for ``dependabot`` PRs (:pr:`4621`)
+- Remove Redundant ``pylint`` Suppressions (:pr:`4628`)
+- Update Copyright to 2025 (:pr:`4631`)
+- Refactor Module Structure and Tests for Star Payments Classes (:pr:`4615` closes :issue:`4593`)
+- Unify ``datetime`` Imports (:pr:`4605` by `cuevasrja <https://github.com/cuevasrja>`_ closes :issue:`4577`)
+- Add Static Security Analysis of GitHub Actions Workflows (:pr:`4606`)
+
+Dependency Updates
+------------------
+
+- Bump ``astral-sh/setup-uv`` from 4.2.0 to 5.1.0 (:pr:`4625`)
+- Bump ``codecov/codecov-action`` from 5.1.1 to 5.1.2 (:pr:`4622`)
+- Bump ``actions/upload-artifact`` from 4.4.3 to 4.5.0 (:pr:`4623`)
+- Bump ``github/codeql-action`` from 3.27.9 to 3.28.0 (:pr:`4624`)
+
+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*
@@ -18,7 +86,7 @@ Major Changes
 Documentation Improvements
 --------------------------

- Documentation Improvements (:pr:`4565` by `Snehashish06 <https://github.com/Snehashish06>`_, :pr:`4573`)
+- Documentation Improvements (:pr:`4565` by Snehashish06, :pr:`4573`)

 Version 21.7
 ============
@@ -11,7 +11,7 @@
   :target: https://pypi.org/project/python-telegram-bot/
   :alt: Supported Python versions

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

@@ -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 **8.0** are natively supported by this library.
+All types and methods of the Telegram Bot API **8.2** 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
@@ -155,10 +155,10 @@ 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,<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``.
+* ``pip install "python-telegram-bot[job-queue]"`` installs the `APScheduler>=3.10.4,<3.12.0 <https://apscheduler.readthedocs.io/en/3.x/>`_ library. 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]"``.

@@ -1,6 +1,6 @@
 #
 #  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2024
+#  Copyright (C) 2015-2025
 #  Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 #  This program is free software: you can redistribute it and/or modify
@@ -16,18 +16,55 @@
 #  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
 from collections import defaultdict
 from collections.abc import Iterator
-from typing import Any, Union
+from socket import socket
+from types import FunctionType
+from typing import Union
+
+from apscheduler.job import Job as APSJob

 import telegram
+import telegram._utils.defaultvalue
+import telegram._utils.types
 import telegram.ext
+import telegram.ext._utils.types
+from tests.auxil.slots import mro_slots
+
+# Define the namespace for type resolution. This helps dealing with the internal imports that
+# we do in many places
+# The .copy() is important to avoid modifying the original namespace
+TG_NAMESPACE = vars(telegram).copy()
+TG_NAMESPACE.update(vars(telegram._utils.types))
+TG_NAMESPACE.update(vars(telegram._utils.defaultvalue))
+TG_NAMESPACE.update(vars(telegram.ext))
+TG_NAMESPACE.update(vars(telegram.ext._utils.types))
+TG_NAMESPACE.update(vars(telegram.ext._applicationbuilder))
+TG_NAMESPACE.update({"socket": socket, "APSJob": APSJob})


-def _iter_own_public_methods(cls: type) -> Iterator[tuple[str, type]]:
+class PublicMethod(typing.NamedTuple):
+    name: str
+    method: FunctionType
+
+
+def _is_inherited_method(cls: type, method_name: str) -> bool:
+    """Checks if a method is inherited from a parent class.
+    Inheritance is not considered if the parent class is private.
+    Recurses through all direcot or indirect parent classes.
+    """
+    # The [1:] slice is used to exclude the class itself from the MRO.
+    for base in cls.__mro__[1:]:
+        if method_name in base.__dict__ and not base.__name__.startswith("_"):
+            return True
+    return False
+
+
+def _iter_own_public_methods(cls: type) -> Iterator[PublicMethod]:
    """Iterates over methods of a class that are not protected/private,
    not camelCase and not inherited from the parent class.

@@ -35,13 +72,15 @@ def _iter_own_public_methods(cls: type) -> Iterator[tuple[str, type]]:

    This function is defined outside the class because it is used to create class constants.
    """
-    return (
-        m
-        for m in inspect.getmembers(cls, predicate=inspect.isfunction)  # not .ismethod
-        if not m[0].startswith("_")
-        and m[0].islower()  # to avoid camelCase methods
-        and m[0] in cls.__dict__  # method is not inherited from parent class
-    )
+
+    # Use .isfunction() instead of .ismethod() because we want to include static methods.
+    for m in inspect.getmembers(cls, predicate=inspect.isfunction):
+        if (
+            not m[0].startswith("_")
+            and m[0].islower()  # to avoid camelCase methods
+            and not _is_inherited_method(cls, m[0])
+        ):
+            yield PublicMethod(m[0], m[1])


 class AdmonitionInserter:
@@ -58,18 +97,12 @@ class AdmonitionInserter:
    start and end markers.
    """

-    FORWARD_REF_SKIP_PATTERN = re.compile(r"^ForwardRef\('DefaultValue\[\w+]'\)$")
-    """A pattern that will be used to skip known ForwardRef's that need not be resolved
-    to a Telegram class, e.g.:
-    ForwardRef('DefaultValue[None]')
-    ForwardRef('DefaultValue[DVValueType]')
-    """
-
-    METHOD_NAMES_FOR_BOT_AND_APPBUILDER: typing.ClassVar[dict[type, str]] = {
-        cls: tuple(m[0] for m in _iter_own_public_methods(cls))  # m[0] means we take only names
-        for cls in (telegram.Bot, telegram.ext.ApplicationBuilder)
+    METHOD_NAMES_FOR_BOT_APP_APPBUILDER: typing.ClassVar[dict[type, str]] = {
+        cls: tuple(m.name for m in _iter_own_public_methods(cls))
+        for cls in (telegram.Bot, telegram.ext.ApplicationBuilder, telegram.ext.Application)
    }
-    """A dictionary mapping Bot and ApplicationBuilder classes to their relevant methods that will
+    """A dictionary mapping Bot, Application & ApplicationBuilder classes to their relevant methods
+    that will
    be mentioned in 'Returned in' and 'Use in' admonitions in other classes' docstrings.
    Methods must be public, not aliases, not inherited from TelegramObject.
    """
@@ -83,13 +116,20 @@ class AdmonitionInserter:
        """Dictionary with admonitions. Contains sub-dictionaries, one per admonition type.
        Each sub-dictionary matches bot methods (for "Shortcuts") or telegram classes (for other
        admonition types) to texts of admonitions, e.g.:
+
        ```
        {
-        "use_in": {<class 'telegram._chatinvitelink.ChatInviteLink'>:
-        <"Use in" admonition for ChatInviteLink>, ...},
-        "available_in": {<class 'telegram._chatinvitelink.ChatInviteLink'>:
-        <"Available in" admonition">, ...},
-        "returned_in": {...}
+            "use_in": {
+                <class 'telegram._chatinvitelink.ChatInviteLink'>:
+                    <"Use in" admonition for ChatInviteLink>,
+                ...
+            },
+            "available_in": {
+                <class 'telegram._chatinvitelink.ChatInviteLink'>:
+                    <"Available in" admonition">,
+                ...
+            },
+            "returned_in": {...}
        }
        ```
        """
@@ -128,34 +168,6 @@ class AdmonitionInserter:
        # i.e. {telegram._files.sticker.Sticker: {":attr:`telegram.Message.sticker`", ...}}
        attrs_for_class = defaultdict(set)

-        # The following regex is supposed to capture a class name in a line like this:
-        # media (:obj:`str` | :class:`telegram.InputFile`): Audio file to send.
-        #
-        # Note that even if such typing description spans over multiple lines but each line ends
-        # with a backslash (otherwise Sphinx will throw an error)
-        # (e.g. EncryptedPassportElement.data), then Sphinx will combine these lines into a single
-        # line automatically, and it will contain no backslash (only some extra many whitespaces
-        # from the indentation).
-
-        attr_docstr_pattern = re.compile(
-            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|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.
-            r".*$",  # Any number of characters, end of string (end of line)
-            re.VERBOSE,
-        )
-
-        # for properties: there is no attr name in docstring.  Just check if there's a class name.
-        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|obj):`~?(?P<class_name>[\w.]*)`")
-
        classes_to_inspect = inspect.getmembers(telegram, inspect.isclass) + inspect.getmembers(
            telegram.ext, inspect.isclass
        )
@@ -166,40 +178,31 @@ class AdmonitionInserter:
            # docstrings.
            name_of_inspected_class_in_docstr = self._generate_class_name_for_link(inspected_class)

-            # Parsing part of the docstring with attributes (parsing of properties follows later)
-            docstring_lines = inspect.getdoc(inspected_class).splitlines()
-            lines_with_attrs = []
-            for idx, line in enumerate(docstring_lines):
-                if line.strip() == "Attributes:":
-                    lines_with_attrs = docstring_lines[idx + 1 :]
-                    break
+            # Writing to dictionary: matching the class found in the type hint
+            # and its subclasses to the attribute of the class being inspected.
+            # The class in the attribute typehint (or its subclass) is the key,
+            # ReST link to attribute of the class currently being inspected is the value.

-            for line in lines_with_attrs:
-                if not (line_match := attr_docstr_pattern.match(line)):
-                    continue
-
-                target_attr = line_match.group("attr_name")
-                # a typing description of one attribute can contain multiple classes
-                for match in single_class_name_pattern.finditer(line):
-                    name_of_class_in_attr = match.group("class_name")
-
-                    # Writing to dictionary: matching the class found in the docstring
-                    # and its subclasses to the attribute of the class being inspected.
-                    # The class in the attribute docstring (or its subclass) is the key,
-                    # ReST link to attribute of the class currently being inspected is the value.
-                    try:
-                        self._resolve_arg_and_add_link(
-                            arg=name_of_class_in_attr,
-                            dict_of_methods_for_class=attrs_for_class,
-                            link=f":attr:`{name_of_inspected_class_in_docstr}.{target_attr}`",
-                        )
-                    except NotImplementedError as e:
-                        raise NotImplementedError(
-                            "Error generating Sphinx 'Available in' admonition "
-                            f"(admonition_inserter.py). Class {name_of_class_in_attr} present in "
-                            f"attribute {target_attr} of class {name_of_inspected_class_in_docstr}"
-                            f" could not be resolved. {e!s}"
-                        ) from e
+            # best effort - args of __init__ means not all attributes are covered, but there is no
+            # other way to get type hints of all attributes, other than doing ast parsing maybe.
+            # (Docstring parsing was discontinued with the closing of #4414)
+            type_hints = typing.get_type_hints(inspected_class.__init__, localns=TG_NAMESPACE)
+            class_attrs = [slot for slot in mro_slots(inspected_class) if not slot.startswith("_")]
+            for target_attr in class_attrs:
+                try:
+                    self._resolve_arg_and_add_link(
+                        dict_of_methods_for_class=attrs_for_class,
+                        link=f":attr:`{name_of_inspected_class_in_docstr}.{target_attr}`",
+                        type_hints={target_attr: type_hints.get(target_attr)},
+                        resolve_nested_type_vars=False,
+                    )
+                except NotImplementedError as e:
+                    raise NotImplementedError(
+                        "Error generating Sphinx 'Available in' admonition "
+                        f"(admonition_inserter.py). Class {inspected_class} present in "
+                        f"attribute {target_attr} of class {name_of_inspected_class_in_docstr}"
+                        f" could not be resolved. {e!s}"
+                    ) from e

            # Properties need to be parsed separately because they act like attributes but not
            # listed as attributes.
@@ -210,39 +213,29 @@ class AdmonitionInserter:
                if prop_name not in inspected_class.__dict__:
                    continue

-                # 1. Can't use typing.get_type_hints because double-quoted type hints
-                #    (like "Application") will throw a NameError
-                # 2. Can't use inspect.signature because return annotations of properties can be
-                #    hard to parse (like "(self) -> BD").
-                # 3. fget is used to access the actual function under the property wrapper
-                docstring = inspect.getdoc(getattr(inspected_class, prop_name).fget)
-                if docstring is None:
-                    continue
+                # fget is used to access the actual function under the property wrapper
+                type_hints = typing.get_type_hints(
+                    getattr(inspected_class, prop_name).fget, localns=TG_NAMESPACE
+                )

-                first_line = docstring.splitlines()[0]
-                if not prop_docstring_pattern.match(first_line):
-                    continue
-
-                for match in single_class_name_pattern.finditer(first_line):
-                    name_of_class_in_prop = match.group("class_name")
-
-                    # Writing to dictionary: matching the class found in the docstring and its
-                    # subclasses to the property of the class being inspected.
-                    # The class in the property docstring (or its subclass) is the key,
-                    # ReST link to property of the class currently being inspected is the value.
-                    try:
-                        self._resolve_arg_and_add_link(
-                            arg=name_of_class_in_prop,
-                            dict_of_methods_for_class=attrs_for_class,
-                            link=f":attr:`{name_of_inspected_class_in_docstr}.{prop_name}`",
-                        )
-                    except NotImplementedError as e:
-                        raise NotImplementedError(
-                            "Error generating Sphinx 'Available in' admonition "
-                            f"(admonition_inserter.py). Class {name_of_class_in_prop} present in "
-                            f"property {prop_name} of class {name_of_inspected_class_in_docstr}"
-                            f" could not be resolved. {e!s}"
-                        ) from e
+                # Writing to dictionary: matching the class found in the docstring and its
+                # subclasses to the property of the class being inspected.
+                # The class in the property docstring (or its subclass) is the key,
+                # ReST link to property of the class currently being inspected is the value.
+                try:
+                    self._resolve_arg_and_add_link(
+                        dict_of_methods_for_class=attrs_for_class,
+                        link=f":attr:`{name_of_inspected_class_in_docstr}.{prop_name}`",
+                        type_hints={prop_name: type_hints.get("return")},
+                        resolve_nested_type_vars=False,
+                    )
+                except NotImplementedError as e:
+                    raise NotImplementedError(
+                        "Error generating Sphinx 'Available in' admonition "
+                        f"(admonition_inserter.py). Class {inspected_class} present in "
+                        f"property {prop_name} of class {name_of_inspected_class_in_docstr}"
+                        f" could not be resolved. {e!s}"
+                    ) from e

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

@@ -250,29 +243,28 @@ class AdmonitionInserter:
        """Creates a dictionary with 'Returned in' admonitions for classes that are returned
        in Bot's and ApplicationBuilder's methods.
        """
-
        # Generate a mapping of classes to ReST links to Bot methods which return it,
        # i.e. {<class 'telegram._message.Message'>: {:meth:`telegram.Bot.send_message`, ...}}
        methods_for_class = defaultdict(set)

-        for cls, method_names in self.METHOD_NAMES_FOR_BOT_AND_APPBUILDER.items():
+        for cls, method_names in self.METHOD_NAMES_FOR_BOT_APP_APPBUILDER.items():
            for method_name in method_names:
-                sig = inspect.signature(getattr(cls, method_name))
-                ret_annot = sig.return_annotation
-
                method_link = self._generate_link_to_method(method_name, cls)
+                arg = getattr(cls, method_name)
+                ret_type_hint = typing.get_type_hints(arg, localns=TG_NAMESPACE)

                try:
                    self._resolve_arg_and_add_link(
-                        arg=ret_annot,
                        dict_of_methods_for_class=methods_for_class,
                        link=method_link,
+                        type_hints={"return": ret_type_hint.get("return")},
+                        resolve_nested_type_vars=False,
                    )
                except NotImplementedError as e:
                    raise NotImplementedError(
                        "Error generating Sphinx 'Returned in' admonition "
                        f"(admonition_inserter.py). {cls}, method {method_name}. "
-                        f"Couldn't resolve type hint in return annotation {ret_annot}. {e!s}"
+                        f"Couldn't resolve type hint in return annotation {ret_type_hint}. {e!s}"
                    ) from e

        return self._generate_admonitions(methods_for_class, admonition_type="returned_in")
@@ -299,8 +291,13 @@ class AdmonitionInserter:
        # inspect methods of all telegram classes for return statements that indicate
        # that this given method is a shortcut for a Bot method
        for _class_name, cls in inspect.getmembers(telegram, predicate=inspect.isclass):
-            # no need to inspect Bot's own methods, as Bot can't have shortcuts in Bot
+            if not cls.__module__.startswith("telegram"):
+                # For some reason inspect.getmembers() also yields some classes that are
+                # imported in the namespace but not part of the telegram module.
+                continue
+
            if cls is telegram.Bot:
+                # no need to inspect Bot's own methods, as Bot can't have shortcuts in Bot
                continue

            for method_name, method in _iter_own_public_methods(cls):
@@ -310,9 +307,7 @@ class AdmonitionInserter:
                        continue

                    bot_method = getattr(telegram.Bot, bot_method_match.group())
-
                    link_to_shortcut_method = self._generate_link_to_method(method_name, cls)
-
                    shortcuts_for_bot_method[bot_method].add(link_to_shortcut_method)

        return self._generate_admonitions(shortcuts_for_bot_method, admonition_type="shortcuts")
@@ -327,26 +322,24 @@ class AdmonitionInserter:
        # {:meth:`telegram.Bot.answer_inline_query`, ...}}
        methods_for_class = defaultdict(set)

-        for cls, method_names in self.METHOD_NAMES_FOR_BOT_AND_APPBUILDER.items():
+        for cls, method_names in self.METHOD_NAMES_FOR_BOT_APP_APPBUILDER.items():
            for method_name in method_names:
                method_link = self._generate_link_to_method(method_name, cls)

-                sig = inspect.signature(getattr(cls, method_name))
-                parameters = sig.parameters
-
-                for param in parameters.values():
-                    try:
-                        self._resolve_arg_and_add_link(
-                            arg=param.annotation,
-                            dict_of_methods_for_class=methods_for_class,
-                            link=method_link,
-                        )
-                    except NotImplementedError as e:
-                        raise NotImplementedError(
-                            "Error generating Sphinx 'Use in' admonition "
-                            f"(admonition_inserter.py). {cls}, method {method_name}, parameter "
-                            f"{param}: Couldn't resolve type hint {param.annotation}. {e!s}"
-                        ) from e
+                arg = getattr(cls, method_name)
+                param_type_hints = typing.get_type_hints(arg, localns=TG_NAMESPACE)
+                param_type_hints.pop("return", None)
+                try:
+                    self._resolve_arg_and_add_link(
+                        dict_of_methods_for_class=methods_for_class,
+                        link=method_link,
+                        type_hints=param_type_hints,
+                    )
+                except NotImplementedError as e:
+                    raise NotImplementedError(
+                        "Error generating Sphinx 'Use in' admonition "
+                        f"(admonition_inserter.py). {cls}, method {method_name}, parameter "
+                    ) from e

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

@@ -362,7 +355,7 @@ class AdmonitionInserter:
        for idx, value in list(enumerate(lines)):
            if value.startswith(
                (
-                    ".. seealso:",
+                    # ".. seealso:",
                    # The docstring contains heading "Examples:", but Sphinx will have it converted
                    # to ".. admonition: Examples":
                    ".. admonition:: Examples",
@@ -435,12 +428,12 @@ class AdmonitionInserter:
        return admonition_for_class

    @staticmethod
-    def _generate_class_name_for_link(cls: type) -> str:
+    def _generate_class_name_for_link(cls_: type) -> str:
        """Generates class name that can be used in a ReST link."""

        # Check for potential presence of ".ext.", we will need to keep it.
-        ext = ".ext" if ".ext." in str(cls) else ""
-        return f"telegram{ext}.{cls.__name__}"
+        ext = ".ext" if ".ext." in str(cls_) else ""
+        return f"telegram{ext}.{cls_.__name__}"

    def _generate_link_to_method(self, method_name: str, cls: type) -> str:
        """Generates a ReST link to a method of a telegram class."""
@@ -448,19 +441,22 @@ class AdmonitionInserter:
        return f":meth:`{self._generate_class_name_for_link(cls)}.{method_name}`"

    @staticmethod
-    def _iter_subclasses(cls: type) -> Iterator:
+    def _iter_subclasses(cls_: type) -> Iterator:
+        if not hasattr(cls_, "__subclasses__") or cls_ is telegram.TelegramObject:
+            return iter([])
        return (
            # exclude private classes
            c
-            for c in cls.__subclasses__()
+            for c in cls_.__subclasses__()
            if not str(c).split(".")[-1].startswith("_")
        )

    def _resolve_arg_and_add_link(
        self,
-        arg: Any,
        dict_of_methods_for_class: defaultdict,
        link: str,
+        type_hints: dict[str, type],
+        resolve_nested_type_vars: bool = True,
    ) -> None:
        """A helper method. Tries to resolve the arg into a valid class. In case of success,
        adds the link (to a method, attribute, or property) for that class' and its subclasses'
@@ -468,7 +464,9 @@ class AdmonitionInserter:

        **Modifies dictionary in place.**
        """
-        for cls in self._resolve_arg(arg):
+        type_hints.pop("self", None)
+
+        for cls in self._resolve_arg(type_hints, resolve_nested_type_vars):
            # When trying to resolve an argument from args or return annotation,
            # the method _resolve_arg returns None if nothing could be resolved.
            # Also, if class was resolved correctly, "telegram" will definitely be in its str().
@@ -480,88 +478,67 @@ class AdmonitionInserter:
            for subclass in self._iter_subclasses(cls):
                dict_of_methods_for_class[subclass].add(link)

-    def _resolve_arg(self, arg: Any) -> Iterator[Union[type, None]]:
+    def _resolve_arg(
+        self,
+        type_hints: dict[str, type],
+        resolve_nested_type_vars: bool,
+    ) -> list[type]:
        """Analyzes an argument of a method and recursively yields classes that the argument
        or its sub-arguments (in cases like Union[...]) belong to, if they can be resolved to
        telegram or telegram.ext classes.

+        Args:
+            type_hints: A dictionary of argument names and their types.
+            resolve_nested_type_vars: If True, nested type variables (like Application[BT, …])
+                will be resolved to their actual classes. If False, only the outermost type
+                variable will be resolved. *Only* affects ptb classes, not built-in types.
+                Useful for checking the return type of methods, where nested type variables
+                are not really useful.
+
        Raises `NotImplementedError`.
        """

-        origin = typing.get_origin(arg)
+        def _is_ptb_class(cls: type) -> bool:
+            if not hasattr(cls, "__module__"):
+                return False
+            return cls.__module__.startswith("telegram")

-        if (
-            origin in (collections.abc.Callable, typing.IO)
-            or arg is None
-            # no other check available (by type or origin) for these:
-            or str(type(arg)) in ("<class 'typing._SpecialForm'>", "<class 'ellipsis'>")
-        ):
-            pass
+        # will be edited in place
+        telegram_classes = set()

-        # RECURSIVE CALLS
-        # for cases like Union[Sequence....
-        elif origin in (
-            Union,
-            collections.abc.Coroutine,
-            collections.abc.Sequence,
-        ):
-            for sub_arg in typing.get_args(arg):
-                yield from self._resolve_arg(sub_arg)
+        def recurse_type(type_, is_recursed_from_ptb_class: bool):
+            next_is_recursed_from_ptb_class = is_recursed_from_ptb_class or _is_ptb_class(type_)

-        elif isinstance(arg, typing.TypeVar):
-            # gets access to the "bound=..." parameter
-            yield from self._resolve_arg(arg.__bound__)
-        # END RECURSIVE CALLS
+            if hasattr(type_, "__origin__"):  # For generic types like Union, List, etc.
+                # Make sure it's not a telegram.ext generic type (e.g. ContextTypes[...])
+                org = typing.get_origin(type_)
+                if "telegram.ext" in str(org):
+                    telegram_classes.add(org)

-        elif isinstance(arg, typing.ForwardRef):
-            m = self.FORWARD_REF_PATTERN.match(str(arg))
-            # We're sure it's a ForwardRef, so, unless it belongs to known exceptions,
-            # the class must be resolved.
-            # If it isn't resolved, we'll have the program throw an exception to be sure.
-            try:
-                cls = self._resolve_class(m.group("class_name"))
-            except AttributeError as exc:
-                # skip known ForwardRef's that need not be resolved to a Telegram class
-                if self.FORWARD_REF_SKIP_PATTERN.match(str(arg)):
-                    pass
-                else:
-                    raise NotImplementedError(f"Could not process ForwardRef: {arg}") from exc
-            else:
-                yield cls
+                args = typing.get_args(type_)
+                for arg in args:
+                    recurse_type(arg, next_is_recursed_from_ptb_class)
+            elif isinstance(type_, typing.TypeVar) and (
+                resolve_nested_type_vars or not is_recursed_from_ptb_class
+            ):
+                # gets access to the "bound=..." parameter
+                recurse_type(type_.__bound__, next_is_recursed_from_ptb_class)
+            elif inspect.isclass(type_) and "telegram" in inspect.getmodule(type_).__name__:
+                telegram_classes.add(type_)
+            elif isinstance(type_, typing.ForwardRef):
+                # Resolving ForwardRef is not easy. https://peps.python.org/pep-0749/ will
+                # hopefully make it better by introducing typing.resolve_forward_ref() in py3.14
+                # but that's not there yet
+                # So for now we fall back to a best effort approach of guessing if the class is
+                # available in tg or tg.ext
+                with contextlib.suppress(AttributeError):
+                    telegram_classes.add(self._resolve_class(type_.__forward_arg__))

-        # For custom generics like telegram.ext._application.Application[~BT, ~CCT, ~UD...].
-        # This must come before the check for isinstance(type) because GenericAlias can also be
-        # recognized as type if it belongs to <class 'types.GenericAlias'>.
-        elif str(type(arg)) in (
-            "<class 'typing._GenericAlias'>",
-            "<class 'types.GenericAlias'>",
-            "<class 'typing._LiteralGenericAlias'>",
-        ):
-            if "telegram" in str(arg):
-                # get_origin() of telegram.ext._application.Application[~BT, ~CCT, ~UD...]
-                # will produce <class 'telegram.ext._application.Application'>
-                yield origin
+        for type_hint in type_hints.values():
+            if type_hint is not None:
+                recurse_type(type_hint, False)

-        elif isinstance(arg, type):
-            if "telegram" in str(arg):
-                yield arg
-
-        # For some reason "InlineQueryResult", "InputMedia" & some others are currently not
-        # recognized as ForwardRefs and are identified as plain strings.
-        elif isinstance(arg, str):
-            # args like "ApplicationBuilder[BT, CCT, UD, CD, BD, JQ]" can be recognized as strings.
-            # Remove whatever is in the square brackets because it doesn't need to be parsed.
-            arg = re.sub(r"\[.+]", "", arg)
-
-            cls = self._resolve_class(arg)
-            # Here we don't want an exception to be thrown since we're not sure it's ForwardRef
-            if cls is not None:
-                yield cls
-
-        else:
-            raise NotImplementedError(
-                f"Cannot process argument {arg} of type {type(arg)} (origin {origin})"
-            )
+        return list(telegram_classes)

    @staticmethod
    def _resolve_class(name: str) -> Union[type, None]:
@@ -581,16 +558,14 @@ class AdmonitionInserter:
            f"telegram.ext.{name}",
            f"telegram.ext.filters.{name}",
        ):
-            try:
-                return eval(option)
            # NameError will be raised if trying to eval just name and it doesn't work, e.g.
            # "Name 'ApplicationBuilder' is not defined".
            # AttributeError will be raised if trying to e.g. eval f"telegram.{name}" when the
            # class denoted by `name` actually belongs to `telegram.ext`:
            # "module 'telegram' has no attribute 'ApplicationBuilder'".
            # If neither option works, this is not a PTB class.
-            except (NameError, AttributeError):
-                continue
+            with contextlib.suppress(NameError, AttributeError):
+                return eval(option)
        return None


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

 from docutils.nodes import Element
@@ -75,7 +75,7 @@ class TGConstXRefRole(PyXRefRole):
            ):
                return str(value), target
            if (
-                isinstance(value, datetime.datetime)
+                isinstance(value, dtm.datetime)
                and value == telegram.constants.ZERO_DATE
                and target in ("telegram.constants.ZERO_DATE",)
            ):
@@ -61,5 +61,5 @@
 }
 .admonition.returned-in > ul, .admonition.available-in > ul, .admonition.use-in > ul, .admonition.shortcuts > ul {
  max-height: 200px;
-  overflow-y: scroll;
+  overflow-y: auto;
 }
@@ -13,7 +13,7 @@ sys.path.insert(0, str(Path("../..").resolve().absolute()))
 # -- General configuration ------------------------------------------------
 # General information about the project.
 project = "python-telegram-bot"
-copyright = "2015-2024, Leandro Toledo"
+copyright = "2015-2025, Leandro Toledo"
 author = "Leandro Toledo"

 # The version info for the project you're documenting, acts as replacement for
@@ -183,6 +183,29 @@
   </details>
   <br>

+.. raw:: html
+
+   <details>
+   <summary>Verification on behalf of an organization</summary>
+
+.. list-table::
+    :align: left
+    :widths: 1 4
+
+    * - :meth:`~telegram.Bot.verify_chat`
+      - Used for verifying a chat
+    * - :meth:`~telegram.Bot.verify_user`
+      - Used for verifying a user
+    * - :meth:`~telegram.Bot.remove_chat_verification`
+      - Used for removing the verification from a chat
+    * - :meth:`~telegram.Bot.remove_user_verification`
+      - Used for removing the verification from a user
+
+.. raw:: html
+
+   </details>
+   <br>
+
 .. raw:: html

   <details>
@@ -0,0 +1,6 @@
+AffiliateInfo
+=============
+
+.. autoclass:: telegram.AffiliateInfo
+    :members:
+    :show-inheritance:
@@ -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__
@@ -9,6 +9,7 @@ Your bot can accept payments from Telegram users. Please see the `introduction t
 .. toctree::
    :titlesonly:

+    telegram.affiliateinfo
    telegram.invoice
    telegram.labeledprice
    telegram.orderinfo
@@ -25,6 +26,7 @@ Your bot can accept payments from Telegram users. Please see the `introduction t
    telegram.startransactions
    telegram.successfulpayment
    telegram.transactionpartner
+    telegram.transactionpartneraffiliateprogram
    telegram.transactionpartnerfragment
    telegram.transactionpartnerother
    telegram.transactionpartnertelegramads
@@ -0,0 +1,6 @@
+TransactionPartnerAffiliateProgram
+===================================
+
+.. autoclass:: telegram.TransactionPartnerAffiliateProgram
+    :members:
+    :show-inheritance:
@@ -96,4 +96,6 @@

 .. |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.
+.. |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.
+
+.. |time-period-input| replace:: :class:`datetime.timedelta` objects are accepted in addition to plain :obj:`int` values.
@@ -0,0 +1,203 @@
+#!/usr/bin/env python
+# pylint: disable=unused-argument
+# This program is dedicated to the public domain under the CC0 license.
+"""Simple state machine to handle user support.
+One admin is supported. The admin can have one active conversation at a time. Other users
+are put on hold until the admin finishes the current conversation.
+In each conversation, the admin and the user take turns to send messages.
+"""
+import logging
+from typing import Optional
+
+from telegram import Update
+from telegram.ext import (
+    Application,
+    CommandHandler,
+    ContextTypes,
+    FiniteStateMachine,
+    MessageHandler,
+    State,
+    StateInfo,
+    filters,
+)
+
+# Enable logging
+logging.basicConfig(
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.DEBUG
+)
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+logging.getLogger("telegram").setLevel(logging.WARNING)
+logging.getLogger("telegram.ext.Application").setLevel(logging.DEBUG)
+
+logger = logging.getLogger(__name__)
+
+
+class UserSupportMachine(FiniteStateMachine[Optional[int]]):
+
+    HOLD = State("HOLD")
+    WELCOMING = State("WELCOMING")
+    WAITING_FOR_REPLY = State("WAITING_FOR_REPLY")
+    WRITING = State("WRITING")
+
+    def __init__(self, admin_id: int):
+        self.admin_id = admin_id
+        super().__init__()
+
+    def _get_admin_state(self) -> tuple[State, int]:
+        return self._states[self.admin_id]
+
+    def get_state_info(self, update: object) -> StateInfo[Optional[int]]:
+        if not isinstance(update, Update) or not (user := update.effective_user):
+            key = None
+            state, version = self.states[key]
+            return StateInfo(key=key, state=state, version=version)
+
+        # Admin is easy - just return the state
+        admin_state, admin_version = self._get_admin_state()
+        if user.id == self.admin_id:
+            logging.debug("Returning admin state: %s", admin_state)
+            return StateInfo(self.admin_id, admin_state, admin_version)
+
+        # If the user state is active in the conversation, we can just return that state
+        user_state, user_version = self._states[user.id]
+        if user_state.matches(self.WELCOMING | self.WRITING | self.WAITING_FOR_REPLY):
+            logging.debug("Returning user state: %s", user_state)
+            return StateInfo(user.id, user_state, user_version)
+
+        # On first interaction, we need to determine what to do with the user
+        # if the admin is not idle, we put the user on hold. Otherwise, they may send the first
+        # message, and we put the admin in waiting for reply to avoid another user occupying the
+        # admin first
+        effective_user_state = self.HOLD if admin_state != State.IDLE else self.WELCOMING
+        self._do_set_state(user.id, effective_user_state, user_version)
+        if effective_user_state == self.WELCOMING:
+            self._do_set_state(self.admin_id, self.WAITING_FOR_REPLY)
+
+        logging.debug("Returning user state: %s", effective_user_state)
+        return StateInfo(user.id, effective_user_state, user_version)
+
+
+async def welcome_user(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await update.effective_message.forward(context.bot_data["admin_id"])
+    suffix = ""
+    if UserSupportMachine.HOLD in context.fsm.get_state_history(context.fsm_state_info.key)[:-1]:
+        suffix = " Thank you for patiently waiting. We hope you enjoyed the music."
+
+    await update.effective_message.reply_text(
+        "Welcome! Your message has been forwarded to the admin. "
+        f"They will get back to you soon.{suffix}"
+    )
+    await context.set_state(UserSupportMachine.WAITING_FOR_REPLY)
+    await context.fsm.set_state(context.bot_data["admin_id"], UserSupportMachine.WRITING)
+    context.bot_data["active_user"] = update.effective_user.id
+
+
+async def conversation_timeout(context: ContextTypes.DEFAULT_TYPE) -> None:
+    active_user = context.bot_data.get("active_user")
+    admin_id = context.bot_data["admin_id"]
+
+    async def handle(user_id: int) -> None:
+        await context.bot.send_message(
+            user_id, "The conversation has been stopped due to inactivity."
+        )
+        await context.fsm.set_state(user_id, State.IDLE)
+
+    if active_user:
+        await handle(active_user)
+    await handle(admin_id)
+
+
+async def handle_reply(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    if not (active_user := context.bot_data.get("active_user")):
+        logger.warning("No active user found, ignoring message")
+
+    target = (
+        active_user
+        if update.effective_user.id == (admin_id := context.bot_data["admin_id"])
+        else admin_id
+    )
+    await context.bot.send_message(target, update.effective_message.text)
+    logging.debug("Forwarded message to %s", target)
+    await context.set_state(UserSupportMachine.WAITING_FOR_REPLY)
+    logging.debug("Done setting state to WAITING_FOR_REPLY for %s", target)
+    await context.fsm.set_state(target, UserSupportMachine.WRITING)
+    logging.debug("Done setting state to WRITING for %s, context.fsm_key")
+
+    context.fsm.schedule_timeout(
+        when=30,
+        callback=conversation_timeout,
+        cancel_keys=[active_user, admin_id],
+    )
+
+
+async def stop_conversation(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    text = "The conversation has been stopped."
+    admin_id = context.bot_data["admin_id"]
+    active_user = context.bot_data.get("active_user")
+
+    await context.bot.send_message(admin_id, text)
+    await context.fsm.set_state(admin_id, State.IDLE)
+    if active_user:
+        await context.bot.send_message(active_user, text)
+        await context.fsm.set_state(active_user, State.IDLE)
+
+
+async def hold_melody(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await update.effective_message.reply_text(
+        "You have been put on hold. The admin will get back to you soon. Please hear some music "
+        "while you wait: https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+    )
+
+
+async def not_your_turn(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await update.effective_message.reply_text(
+        "It's not your turn yet. Please wait for the other party to reply to your message."
+    )
+
+
+async def unsupported_message(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await update.effective_message.reply_text("This message is not supported.")
+
+
+def main() -> None:
+    application = Application.builder().token("TOKEN").build()
+    application.fsm = UserSupportMachine(admin_id=123456)
+    application.fsm.set_job_queue(application.job_queue)
+    application.bot_data["admin_id"] = application.fsm.admin_id
+
+    # Users are welcomed only if they are in the corresponding state
+    application.add_handler(
+        MessageHandler(~filters.User(application.fsm.admin_id) & filters.TEXT, welcome_user),
+        state=UserSupportMachine.WELCOMING,
+    )
+
+    # Conversation logic:
+    # * forward messages between user and admin
+    # * stop the conversation at any time (admin or user)
+    # * point out that the other party is currently writing
+    # Important: Order matters!
+    application.add_handler(
+        CommandHandler("stop", stop_conversation),
+        state=UserSupportMachine.WAITING_FOR_REPLY | UserSupportMachine.WRITING,
+    )
+    application.add_handler(
+        MessageHandler(filters.TEXT, handle_reply), state=UserSupportMachine.WRITING
+    )
+    application.add_handler(
+        MessageHandler(filters.TEXT, not_your_turn), state=UserSupportMachine.WAITING_FOR_REPLY
+    )
+
+    # If the admin is busy, put the user on hold
+    application.add_handler(
+        MessageHandler(filters.TEXT, hold_melody), state=UserSupportMachine.HOLD
+    )
+
+    # Fallback
+    application.add_handler(MessageHandler(filters.ALL, unsupported_message), state=State.ANY)
+
+    application.run_polling(allowed_updates=Update.ALL_TYPES)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,172 @@
+#!/usr/bin/env python
+# pylint: disable=unused-argument
+# This program is dedicated to the public domain under the CC0 license.
+"""State machine bot showcasing how concurrency can be handled with FSM.
+How to use:
+
+* Use Case 1: Concurrent balance updates
+    - /unsafe_update <balance_update>: Unsafe update of the wallet balance. Send the command
+        multiple times in quick succession (less than 1 second) to see the effect
+    - /safe_update <balance_update>: Safe update of the wallet balance. Send the command
+        multiple times in quick succession (less than 1 second) to see the effect
+
+* Use Case 2: Declare a winner - who is the fastest?
+    - /unsafe_declare_winner: Unsafe declaration of the user as winner. Send the command
+        multiple times in quick succession (less than 1 second) to see the effect. Needs restart
+        after the winner is declared.
+    - /safe_declare_winner: Safe declaration of the user as winner. Send the command
+        multiple times in quick succession (less than 1 second) to see the effect. Needs restart
+        after the winner is declared.
+"""
+import asyncio
+import logging
+
+from telegram import Update
+from telegram.constants import ChatAction
+from telegram.ext import (
+    Application,
+    CommandHandler,
+    ContextTypes,
+    FiniteStateMachine,
+    MessageHandler,
+    State,
+    StateInfo,
+    filters,
+)
+
+# Enable logging
+logging.basicConfig(
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.DEBUG
+)
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+logging.getLogger("telegram").setLevel(logging.WARNING)
+logging.getLogger("telegram.ext.Application").setLevel(logging.DEBUG)
+
+logger = logging.getLogger(__name__)
+
+
+class ConcurrentMachine(FiniteStateMachine[None]):
+    """This FSM only knows a global state for the whole bot"""
+
+    UPDATING_BALANCE = State("UPDATING_BALANCE")
+    WINNER_DECLARED = State("WINNER_DECLARED")
+
+    def get_state_info(self, update: object) -> StateInfo[None]:
+        state, version = self.states[None]
+        return StateInfo(key=None, state=state, version=version)
+
+
+########################################
+# Use case 1: Concurrent balance updates
+########################################
+
+
+async def update_balance(context: ContextTypes.DEFAULT_TYPE, update: Update) -> None:
+    initial_balance = context.bot_data.get("balance", 0)
+    balance_update = int(context.args[0])
+    # Simulate heavy computation
+    await update.effective_message.reply_text(
+        f"Initiating balance update: {initial_balance}. Updating ..."
+    )
+    await update.effective_chat.send_action(ChatAction.TYPING)
+    await asyncio.sleep(4.5)
+    new_balance = context.bot_data["balance"] = initial_balance + balance_update
+    await update.effective_message.reply_text(f"Balance updated. New balance: {new_balance}")
+
+
+async def unsafe_update(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Unsafe update of the wallet balance"""
+    # Simulate heavy computation *before* the update is processed
+    await asyncio.sleep(1)
+
+    await context.fsm.set_state(context.fsm_state_info.key, ConcurrentMachine.UPDATING_BALANCE)
+
+    # At this point, the lock is released such that multiple updates can update
+    # the balance concurrently. This can lead to race conditions.
+    await update_balance(context, update)
+
+    await context.fsm.set_state(context.fsm_state_info.key, State.IDLE)
+
+
+async def safe_update(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Safe update of the wallet balance"""
+    # Simulate heavy computation *before* the update is processed
+    await asyncio.sleep(1)
+
+    async with context.as_fsm_state(ConcurrentMachine.UPDATING_BALANCE):
+        # At this point, the lock is acquired such that only one update can update
+        # the balance at a time. This prevents race conditions.
+        await update_balance(context, update)
+
+
+async def busy(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Busy state"""
+    await update.effective_message.reply_text("I'm busy, try again later.")
+
+
+####################################################
+# Use case 2: Declare a winner - who is the fastest?
+####################################################
+
+
+async def declare_winner_unsafe(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Declare the user as winner"""
+    # Simulate heavy computation *before* the update is processed
+    await asyncio.sleep(1)
+
+    # Unsafe state update: No version check, so the state might have already changed
+    await context.fsm.set_state(context.fsm_state_info.key, ConcurrentMachine.WINNER_DECLARED)
+    await update.effective_message.reply_text("You are the winner!")
+
+
+async def declare_winner_safe(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Declare the user as winner"""
+    # Simulate heavy computation *before* the update is processed
+    await asyncio.sleep(1)
+
+    try:
+        await context.set_state(ConcurrentMachine.WINNER_DECLARED)
+        await update.effective_message.reply_text("You are the winner!")
+    except ValueError:
+        await update.effective_message.reply_text(
+            "Sorry, you are too late. Someone else was faster."
+        )
+
+
+def main() -> None:
+    application = Application.builder().token("TOKEN").concurrent_updates(True).build()
+    application.fsm = ConcurrentMachine()
+
+    # Note: OR-combination of states is used here to allow both use cases to be handled
+    # in parallel. Not really necessary for the showcasing, just a nice touch :)
+
+    # Use case 2: Declare a winner - who is the fastest?
+    application.add_handler(
+        CommandHandler("unsafe_declare_winner", declare_winner_unsafe),
+        state=State.IDLE | ConcurrentMachine.UPDATING_BALANCE,
+    )
+    application.add_handler(
+        CommandHandler("safe_declare_winner", declare_winner_safe),
+        state=State.IDLE | ConcurrentMachine.UPDATING_BALANCE,
+    )
+
+    # Use case 1: Concurrent balance updates
+    application.add_handler(
+        CommandHandler("unsafe_update", unsafe_update, has_args=1),
+        state=State.IDLE | ConcurrentMachine.WINNER_DECLARED,
+    )
+    application.add_handler(
+        CommandHandler("safe_update", safe_update, has_args=1),
+        state=State.IDLE | ConcurrentMachine.WINNER_DECLARED,
+    )
+    # Order matters, so this needs to be added last
+    application.add_handler(
+        MessageHandler(filters.ALL, busy), state=ConcurrentMachine.UPDATING_BALANCE
+    )
+
+    application.run_polling(allowed_updates=Update.ALL_TYPES)
+
+
+if __name__ == "__main__":
+    main()
@@ -10,7 +10,7 @@ description = "We have made you a wrapper you can't refuse"
 readme = "README.rst"
 requires-python = ">=3.9"
 license = "LGPL-3.0-only"
-license-files = { paths = ["LICENSE", "LICENSE.dual", "LICENSE.lesser"] }
+license-files = ["LICENSE", "LICENSE.dual", "LICENSE.lesser"]
 authors = [
    { name = "Leandro Toledo", email = "devs@python-telegram-bot.org" }
 ]
@@ -76,9 +76,7 @@ http2 = [
 ]
 job-queue = [
    # APS doesn't have a strict stability policy. Let's be cautious for now.
-    "APScheduler~=3.10.4",
-    # pytz is required by APS and just needs the lower bound due to #2120
-    "pytz>=2018.6",
+    "APScheduler>=3.10.4,<3.12.0",
 ]
 passport = [
    "cryptography!=3.4,!=3.4.1,!=3.4.2,!=3.4.3,>=39.0.1",
@@ -86,7 +84,7 @@ passport = [
    "cffi >= 1.17.0rc1; python_version > '3.12'"
 ]
 rate-limiter = [
-    "aiolimiter~=1.1.0",
+    "aiolimiter>=1.1,<1.3",
 ]
 socks = [
    "httpx[socks]",
@@ -149,7 +147,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]
@@ -180,8 +179,8 @@ markers = [
    "req",
 ]
 asyncio_mode = "auto"
-log_format = "%(funcName)s - Line %(lineno)d - %(message)s"
-# log_level = "DEBUG"  # uncomment to see DEBUG logs
+log_cli_format = "%(funcName)s - Line %(lineno)d - %(message)s"
+# log_cli_level = "DEBUG"  # uncomment to see DEBUG logs

 # MYPY:
 [tool.mypy]
@@ -4,7 +4,7 @@
 build

 # For the test suite
-pytest==8.3.3
+pytest==8.3.4

 # needed because pytest doesn't come with native support for coroutines as tests
 pytest-asyncio==0.21.2
@@ -16,4 +16,8 @@ pytest-xdist==3.6.1
 flaky>=3.8.1

 # used in test_official for parsing tg docs
-beautifulsoup4
+beautifulsoup4
+
+# For testing with timezones. Might not be needed on all systems, but to ensure that unit tests
+# run correctly on all systems, we include it here.
+tzdata
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -20,6 +20,7 @@

 __author__ = "devs@python-telegram-bot.org"
 __all__ = (
+    "AffiliateInfo",
    "Animation",
    "Audio",
    "BackgroundFill",
@@ -236,6 +237,7 @@ __all__ = (
    "TelegramObject",
    "TextQuote",
    "TransactionPartner",
+    "TransactionPartnerAffiliateProgram",
    "TransactionPartnerFragment",
    "TransactionPartnerOther",
    "TransactionPartnerTelegramAds",
@@ -269,6 +271,17 @@ __all__ = (
    "warnings",
 )

+from telegram._payment.stars.startransactions import StarTransaction, StarTransactions
+from telegram._payment.stars.transactionpartner import (
+    TransactionPartner,
+    TransactionPartnerAffiliateProgram,
+    TransactionPartnerFragment,
+    TransactionPartnerOther,
+    TransactionPartnerTelegramAds,
+    TransactionPartnerTelegramApi,
+    TransactionPartnerUser,
+)
+
 from . import _version, constants, error, helpers, request, warnings
 from ._birthdate import Birthdate
 from ._bot import Bot
@@ -468,19 +481,12 @@ from ._payment.refundedpayment import RefundedPayment
 from ._payment.shippingaddress import ShippingAddress
 from ._payment.shippingoption import ShippingOption
 from ._payment.shippingquery import ShippingQuery
-from ._payment.stars import (
+from ._payment.stars.affiliateinfo import AffiliateInfo
+from ._payment.stars.revenuewithdrawalstate import (
    RevenueWithdrawalState,
    RevenueWithdrawalStateFailed,
    RevenueWithdrawalStatePending,
    RevenueWithdrawalStateSucceeded,
-    StarTransaction,
-    StarTransactions,
-    TransactionPartner,
-    TransactionPartnerFragment,
-    TransactionPartnerOther,
-    TransactionPartnerTelegramAds,
-    TransactionPartnerTelegramApi,
-    TransactionPartnerUser,
 )
 from ._payment.successfulpayment import SuccessfulPayment
 from ._poll import InputPollOption, Poll, PollAnswer, PollOption
@@ -1,7 +1,7 @@
 # !/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,7 +17,7 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Birthday."""
-from datetime import date
+import datetime as dtm
 from typing import Optional

 from telegram._telegramobject import TelegramObject
@@ -70,7 +70,7 @@ class Birthdate(TelegramObject):

        self._freeze()

-    def to_date(self, year: Optional[int] = None) -> date:
+    def to_date(self, year: Optional[int] = None) -> dtm.date:
        """Return the birthdate as a date object.

        .. versionchanged:: 21.2
@@ -89,4 +89,4 @@ class Birthdate(TelegramObject):
                "The `year` argument is required if the `year` attribute was not present."
            )

-        return date(year or self.year, self.month, self.day)  # type: ignore[arg-type]
+        return dtm.date(year or self.year, self.month, self.day)  # type: ignore[arg-type]
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -84,9 +84,7 @@ class BotCommandScope(TelegramObject):
        self._freeze()

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

@@ -104,9 +102,6 @@ class BotCommandScope(TelegramObject):
        """
        data = cls._parse_data(data)

-        if not data:
-            return None
-
        _class_mapping: dict[str, type[BotCommandScope]] = {
            cls.DEFAULT: BotCommandScopeDefault,
            cls.ALL_PRIVATE_CHATS: BotCommandScopeAllPrivateChats,
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -2,7 +2,7 @@
 # pylint: disable=redefined-builtin
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,9 +18,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 Telegram Business related classes."""
-
+import datetime as dtm
 from collections.abc import Sequence
-from datetime import datetime
 from typing import TYPE_CHECKING, Optional

 from telegram._chat import Chat
@@ -28,7 +27,7 @@ from telegram._files.location import Location
 from telegram._files.sticker import Sticker
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
-from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.argumentparsing import de_json_optional, de_list_optional, parse_sequence_arg
 from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
 from telegram._utils.types import JSONDict

@@ -81,7 +80,7 @@ class BusinessConnection(TelegramObject):
        id: str,
        user: "User",
        user_chat_id: int,
-        date: datetime,
+        date: dtm.datetime,
        can_reply: bool,
        is_enabled: bool,
        *,
@@ -91,7 +90,7 @@ class BusinessConnection(TelegramObject):
        self.id: str = id
        self.user: User = user
        self.user_chat_id: int = user_chat_id
-        self.date: datetime = date
+        self.date: dtm.datetime = date
        self.can_reply: bool = can_reply
        self.is_enabled: bool = is_enabled

@@ -107,20 +106,15 @@ class BusinessConnection(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        # Get the local timezone from the bot if it has defaults
        loc_tzinfo = extract_tzinfo_from_defaults(bot)

        data["date"] = from_timestamp(data.get("date"), tzinfo=loc_tzinfo)
-        data["user"] = User.de_json(data.get("user"), bot)
+        data["user"] = de_json_optional(data.get("user"), User, bot)

        return super().de_json(data=data, bot=bot)

@@ -178,16 +172,11 @@ class BusinessMessagesDeleted(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["chat"] = Chat.de_json(data.get("chat"), bot)
+        data["chat"] = de_json_optional(data.get("chat"), Chat, bot)

        return super().de_json(data=data, bot=bot)

@@ -237,16 +226,11 @@ class BusinessIntro(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(
-        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
-    ) -> Optional["BusinessIntro"]:
+    def de_json(cls, data: JSONDict, bot: Optional["Bot"] = None) -> "BusinessIntro":
        """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)
+        data["sticker"] = de_json_optional(data.get("sticker"), Sticker, bot)

        return super().de_json(data=data, bot=bot)

@@ -291,16 +275,11 @@ class BusinessLocation(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["location"] = Location.de_json(data.get("location"), bot)
+        data["location"] = de_json_optional(data.get("location"), Location, bot)

        return super().de_json(data=data, bot=bot)

@@ -440,17 +419,12 @@ class BusinessOpeningHours(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["opening_hours"] = BusinessOpeningHoursInterval.de_list(
-            data.get("opening_hours"), bot
+        data["opening_hours"] = de_list_optional(
+            data.get("opening_hours"), BusinessOpeningHoursInterval, bot
        )

        return super().de_json(data=data, bot=bot)
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -26,8 +26,9 @@ from telegram._files.location import Location
 from telegram._message import MaybeInaccessibleMessage, Message
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import JSONDict, ODVInput, ReplyMarkup
+from telegram._utils.types import JSONDict, ODVInput, ReplyMarkup, TimePeriod

 if TYPE_CHECKING:
    from telegram import (
@@ -149,17 +150,12 @@ class CallbackQuery(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["from_user"] = User.de_json(data.pop("from", None), bot)
-        data["message"] = Message.de_json(data.get("message"), bot)
+        data["from_user"] = de_json_optional(data.pop("from", None), User, bot)
+        data["message"] = de_json_optional(data.get("message"), Message, bot)

        return super().de_json(data=data, bot=bot)

@@ -168,7 +164,7 @@ class CallbackQuery(TelegramObject):
        text: Optional[str] = None,
        show_alert: Optional[bool] = None,
        url: Optional[str] = None,
-        cache_time: Optional[int] = None,
+        cache_time: Optional[TimePeriod] = None,
        *,
        read_timeout: ODVInput[float] = DEFAULT_NONE,
        write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -475,7 +471,7 @@ class CallbackQuery(TelegramObject):
        horizontal_accuracy: Optional[float] = None,
        heading: Optional[int] = None,
        proximity_alert_radius: Optional[int] = None,
-        live_period: Optional[int] = None,
+        live_period: Optional[TimePeriod] = None,
        *,
        location: Optional[Location] = None,
        read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -2,7 +2,7 @@
 # pylint: disable=redefined-builtin
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,8 +18,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 Chat."""
+import datetime as dtm
 from collections.abc import Sequence
-from datetime import datetime
 from html import escape
 from typing import TYPE_CHECKING, Final, Optional, Union

@@ -31,7 +31,14 @@ from telegram._reaction import ReactionType
 from telegram._telegramobject import TelegramObject
 from telegram._utils import enum
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import CorrectOptionID, FileInput, JSONDict, ODVInput, ReplyMarkup
+from telegram._utils.types import (
+    CorrectOptionID,
+    FileInput,
+    JSONDict,
+    ODVInput,
+    ReplyMarkup,
+    TimePeriod,
+)
 from telegram.helpers import escape_markdown
 from telegram.helpers import mention_html as helpers_mention_html
 from telegram.helpers import mention_markdown as helpers_mention_markdown
@@ -384,7 +391,7 @@ class _ChatBase(TelegramObject):
        self,
        user_id: int,
        revoke_messages: Optional[bool] = None,
-        until_date: Optional[Union[int, datetime]] = None,
+        until_date: Optional[Union[int, dtm.datetime]] = None,
        *,
        read_timeout: ODVInput[float] = DEFAULT_NONE,
        write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -656,7 +663,7 @@ class _ChatBase(TelegramObject):
        self,
        user_id: int,
        permissions: ChatPermissions,
-        until_date: Optional[Union[int, datetime]] = None,
+        until_date: Optional[Union[int, dtm.datetime]] = None,
        use_independent_chat_permissions: Optional[bool] = None,
        *,
        read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1339,7 +1346,7 @@ class _ChatBase(TelegramObject):
    async def send_audio(
        self,
        audio: Union[FileInput, "Audio"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
        performer: Optional[str] = None,
        title: Optional[str] = None,
        caption: Optional[str] = None,
@@ -1668,7 +1675,7 @@ class _ChatBase(TelegramObject):
        longitude: Optional[float] = None,
        disable_notification: ODVInput[bool] = DEFAULT_NONE,
        reply_markup: Optional[ReplyMarkup] = None,
-        live_period: Optional[int] = None,
+        live_period: Optional[TimePeriod] = None,
        horizontal_accuracy: Optional[float] = None,
        heading: Optional[int] = None,
        proximity_alert_radius: Optional[int] = None,
@@ -1727,7 +1734,7 @@ class _ChatBase(TelegramObject):
    async def send_animation(
        self,
        animation: Union[FileInput, "Animation"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
        width: Optional[int] = None,
        height: Optional[int] = None,
        caption: Optional[str] = None,
@@ -1915,7 +1922,7 @@ class _ChatBase(TelegramObject):
    async def send_video(
        self,
        video: Union[FileInput, "Video"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
        caption: Optional[str] = None,
        disable_notification: ODVInput[bool] = DEFAULT_NONE,
        reply_markup: Optional[ReplyMarkup] = None,
@@ -1987,7 +1994,7 @@ class _ChatBase(TelegramObject):
    async def send_video_note(
        self,
        video_note: Union[FileInput, "VideoNote"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
        length: Optional[int] = None,
        disable_notification: ODVInput[bool] = DEFAULT_NONE,
        reply_markup: Optional[ReplyMarkup] = None,
@@ -2045,7 +2052,7 @@ class _ChatBase(TelegramObject):
    async def send_voice(
        self,
        voice: Union[FileInput, "Voice"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
        caption: Optional[str] = None,
        disable_notification: ODVInput[bool] = DEFAULT_NONE,
        reply_markup: Optional[ReplyMarkup] = None,
@@ -2115,8 +2122,8 @@ class _ChatBase(TelegramObject):
        reply_markup: Optional[ReplyMarkup] = None,
        explanation: Optional[str] = None,
        explanation_parse_mode: ODVInput[str] = DEFAULT_NONE,
-        open_period: Optional[int] = None,
-        close_date: Optional[Union[int, datetime]] = None,
+        open_period: Optional[TimePeriod] = None,
+        close_date: Optional[Union[int, dtm.datetime]] = None,
        explanation_entities: Optional[Sequence["MessageEntity"]] = None,
        protect_content: ODVInput[bool] = DEFAULT_NONE,
        message_thread_id: Optional[int] = None,
@@ -2588,7 +2595,7 @@ class _ChatBase(TelegramObject):

    async def create_invite_link(
        self,
-        expire_date: Optional[Union[int, datetime]] = None,
+        expire_date: Optional[Union[int, dtm.datetime]] = None,
        member_limit: Optional[int] = None,
        name: Optional[str] = None,
        creates_join_request: Optional[bool] = None,
@@ -2632,7 +2639,7 @@ class _ChatBase(TelegramObject):
    async def edit_invite_link(
        self,
        invite_link: Union[str, "ChatInviteLink"],
-        expire_date: Optional[Union[int, datetime]] = None,
+        expire_date: Optional[Union[int, dtm.datetime]] = None,
        member_limit: Optional[int] = None,
        name: Optional[str] = None,
        creates_join_request: Optional[bool] = None,
@@ -2708,7 +2715,7 @@ class _ChatBase(TelegramObject):

    async def create_subscription_invite_link(
        self,
-        subscription_period: int,
+        subscription_period: TimePeriod,
        subscription_price: int,
        name: Optional[str] = None,
        *,
@@ -3443,6 +3450,7 @@ class _ChatBase(TelegramObject):
        text: Optional[str] = None,
        text_parse_mode: ODVInput[str] = DEFAULT_NONE,
        text_entities: Optional[Sequence["MessageEntity"]] = None,
+        pay_for_upgrade: Optional[bool] = None,
        *,
        read_timeout: ODVInput[float] = DEFAULT_NONE,
        write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -3470,6 +3478,69 @@ class _ChatBase(TelegramObject):
            text=text,
            text_parse_mode=text_parse_mode,
            text_entities=text_entities,
+            pay_for_upgrade=pay_for_upgrade,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def verify(
+        self,
+        custom_description: 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,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.verify_chat(chat_id=update.effective_chat.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.verify_chat`.
+
+        .. versionadded:: 21.10
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().verify_chat(
+            chat_id=self.id,
+            custom_description=custom_description,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def remove_verification(
+        self,
+        *,
+        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.remove_chat_verification(chat_id=update.effective_chat.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.remove_chat_verification`.
+
+        .. versionadded:: 21.10
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().remove_chat_verification(
+            chat_id=self.id,
            read_timeout=read_timeout,
            write_timeout=write_timeout,
            connect_timeout=connect_timeout,
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -24,7 +24,7 @@ from telegram import constants
 from telegram._files.document import Document
 from telegram._telegramobject import TelegramObject
 from telegram._utils import enum
-from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.argumentparsing import de_json_optional, parse_sequence_arg
 from telegram._utils.types import JSONDict

 if TYPE_CHECKING:
@@ -79,15 +79,10 @@ class BackgroundFill(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        _class_mapping: dict[str, type[BackgroundFill]] = {
            cls.SOLID: BackgroundFillSolid,
            cls.GRADIENT: BackgroundFillGradient,
@@ -270,15 +265,10 @@ class BackgroundType(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        _class_mapping: dict[str, type[BackgroundType]] = {
            cls.FILL: BackgroundTypeFill,
            cls.WALLPAPER: BackgroundTypeWallpaper,
@@ -290,10 +280,10 @@ class BackgroundType(TelegramObject):
            return _class_mapping[data.pop("type")].de_json(data=data, bot=bot)

        if "fill" in data:
-            data["fill"] = BackgroundFill.de_json(data.get("fill"), bot)
+            data["fill"] = de_json_optional(data.get("fill"), BackgroundFill, bot)

        if "document" in data:
-            data["document"] = Document.de_json(data.get("document"), bot)
+            data["document"] = de_json_optional(data.get("document"), Document, bot)

        return super().de_json(data=data, bot=bot)

@@ -533,15 +523,10 @@ class ChatBackground(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["type"] = BackgroundType.de_json(data.get("type"), bot)
+        data["type"] = de_json_optional(data.get("type"), BackgroundType, bot)

        return super().de_json(data=data, bot=bot)
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,9 +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 ChatBoosts."""
-
+import datetime as dtm
 from collections.abc import Sequence
-from datetime import datetime
 from typing import TYPE_CHECKING, Final, Optional

 from telegram import constants
@@ -27,7 +26,7 @@ from telegram._chat import Chat
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
 from telegram._utils import enum
-from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.argumentparsing import de_json_optional, de_list_optional, parse_sequence_arg
 from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
 from telegram._utils.types import JSONDict

@@ -111,15 +110,10 @@ class ChatBoostSource(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        _class_mapping: dict[str, type[ChatBoostSource]] = {
            cls.PREMIUM: ChatBoostSourcePremium,
            cls.GIFT_CODE: ChatBoostSourceGiftCode,
@@ -130,7 +124,7 @@ class ChatBoostSource(TelegramObject):
            return _class_mapping[data.pop("source")].de_json(data=data, bot=bot)

        if "user" in data:
-            data["user"] = User.de_json(data.get("user"), bot)
+            data["user"] = de_json_optional(data.get("user"), User, bot)

        return super().de_json(data=data, bot=bot)

@@ -274,8 +268,8 @@ class ChatBoost(TelegramObject):
    def __init__(
        self,
        boost_id: str,
-        add_date: datetime,
-        expiration_date: datetime,
+        add_date: dtm.datetime,
+        expiration_date: dtm.datetime,
        source: ChatBoostSource,
        *,
        api_kwargs: Optional[JSONDict] = None,
@@ -283,27 +277,22 @@ class ChatBoost(TelegramObject):
        super().__init__(api_kwargs=api_kwargs)

        self.boost_id: str = boost_id
-        self.add_date: datetime = add_date
-        self.expiration_date: datetime = expiration_date
+        self.add_date: dtm.datetime = add_date
+        self.expiration_date: dtm.datetime = expiration_date
        self.source: ChatBoostSource = source

        self._id_attrs = (self.boost_id, self.add_date, self.expiration_date, self.source)
        self._freeze()

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

-        if not data:
-            return None
-
-        data["source"] = ChatBoostSource.de_json(data.get("source"), bot)
+        data["source"] = de_json_optional(data.get("source"), ChatBoostSource, bot)
        loc_tzinfo = extract_tzinfo_from_defaults(bot)
-        data["add_date"] = from_timestamp(data["add_date"], tzinfo=loc_tzinfo)
-        data["expiration_date"] = from_timestamp(data["expiration_date"], tzinfo=loc_tzinfo)
+        data["add_date"] = from_timestamp(data.get("add_date"), tzinfo=loc_tzinfo)
+        data["expiration_date"] = from_timestamp(data.get("expiration_date"), tzinfo=loc_tzinfo)

        return super().de_json(data=data, bot=bot)

@@ -343,17 +332,12 @@ class ChatBoostUpdated(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["chat"] = Chat.de_json(data.get("chat"), bot)
-        data["boost"] = ChatBoost.de_json(data.get("boost"), bot)
+        data["chat"] = de_json_optional(data.get("chat"), Chat, bot)
+        data["boost"] = de_json_optional(data.get("boost"), ChatBoost, bot)

        return super().de_json(data=data, bot=bot)

@@ -386,7 +370,7 @@ class ChatBoostRemoved(TelegramObject):
        self,
        chat: Chat,
        boost_id: str,
-        remove_date: datetime,
+        remove_date: dtm.datetime,
        source: ChatBoostSource,
        *,
        api_kwargs: Optional[JSONDict] = None,
@@ -395,26 +379,21 @@ class ChatBoostRemoved(TelegramObject):

        self.chat: Chat = chat
        self.boost_id: str = boost_id
-        self.remove_date: datetime = remove_date
+        self.remove_date: dtm.datetime = remove_date
        self.source: ChatBoostSource = source

        self._id_attrs = (self.chat, self.boost_id, self.remove_date, self.source)
        self._freeze()

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

-        if not data:
-            return None
-
-        data["chat"] = Chat.de_json(data.get("chat"), bot)
-        data["source"] = ChatBoostSource.de_json(data.get("source"), bot)
+        data["chat"] = de_json_optional(data.get("chat"), Chat, bot)
+        data["source"] = de_json_optional(data.get("source"), ChatBoostSource, bot)
        loc_tzinfo = extract_tzinfo_from_defaults(bot)
-        data["remove_date"] = from_timestamp(data["remove_date"], tzinfo=loc_tzinfo)
+        data["remove_date"] = from_timestamp(data.get("remove_date"), tzinfo=loc_tzinfo)

        return super().de_json(data=data, bot=bot)

@@ -451,15 +430,10 @@ class UserChatBoosts(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["boosts"] = ChatBoost.de_list(data.get("boosts"), bot)
+        data["boosts"] = de_list_optional(data.get("boosts"), ChatBoost, bot)

        return super().de_json(data=data, bot=bot)
@@ -2,7 +2,7 @@
 # pylint: disable=redefined-builtin
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,8 +18,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 ChatFullInfo."""
+import datetime as dtm
 from collections.abc import Sequence
-from datetime import datetime
 from typing import TYPE_CHECKING, Optional

 from telegram._birthdate import Birthdate
@@ -28,7 +28,7 @@ from telegram._chatlocation import ChatLocation
 from telegram._chatpermissions import ChatPermissions
 from telegram._files.chatphoto import ChatPhoto
 from telegram._reaction import ReactionType
-from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.argumentparsing import de_json_optional, de_list_optional, parse_sequence_arg
 from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
 from telegram._utils.types import JSONDict

@@ -422,7 +422,7 @@ class ChatFullInfo(_ChatBase):
        profile_accent_color_id: Optional[int] = None,
        profile_background_custom_emoji_id: Optional[str] = None,
        emoji_status_custom_emoji_id: Optional[str] = None,
-        emoji_status_expiration_date: Optional[datetime] = None,
+        emoji_status_expiration_date: Optional[dtm.datetime] = None,
        bio: Optional[str] = None,
        has_private_forwards: Optional[bool] = None,
        has_restricted_voice_and_video_messages: Optional[bool] = None,
@@ -486,7 +486,9 @@ class ChatFullInfo(_ChatBase):
            )
            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.emoji_status_expiration_date: Optional[dtm.datetime] = (
+                emoji_status_expiration_date
+            )
            self.has_aggressive_anti_spam_enabled: Optional[bool] = (
                has_aggressive_anti_spam_enabled
            )
@@ -510,15 +512,10 @@ class ChatFullInfo(_ChatBase):
            self.can_send_paid_media: Optional[bool] = can_send_paid_media

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

-        if not data:
-            return None
-
        # Get the local timezone from the bot if it has defaults
        loc_tzinfo = extract_tzinfo_from_defaults(bot)

@@ -526,7 +523,7 @@ class ChatFullInfo(_ChatBase):
            data.get("emoji_status_expiration_date"), tzinfo=loc_tzinfo
        )

-        data["photo"] = ChatPhoto.de_json(data.get("photo"), bot)
+        data["photo"] = de_json_optional(data.get("photo"), ChatPhoto, bot)

        from telegram import (  # pylint: disable=import-outside-toplevel
            BusinessIntro,
@@ -535,16 +532,20 @@ class ChatFullInfo(_ChatBase):
            Message,
        )

-        data["pinned_message"] = Message.de_json(data.get("pinned_message"), bot)
-        data["permissions"] = ChatPermissions.de_json(data.get("permissions"), bot)
-        data["location"] = ChatLocation.de_json(data.get("location"), bot)
-        data["available_reactions"] = ReactionType.de_list(data.get("available_reactions"), bot)
-        data["birthdate"] = Birthdate.de_json(data.get("birthdate"), bot)
-        data["personal_chat"] = Chat.de_json(data.get("personal_chat"), bot)
-        data["business_intro"] = BusinessIntro.de_json(data.get("business_intro"), bot)
-        data["business_location"] = BusinessLocation.de_json(data.get("business_location"), bot)
-        data["business_opening_hours"] = BusinessOpeningHours.de_json(
-            data.get("business_opening_hours"), bot
+        data["pinned_message"] = de_json_optional(data.get("pinned_message"), Message, bot)
+        data["permissions"] = de_json_optional(data.get("permissions"), ChatPermissions, bot)
+        data["location"] = de_json_optional(data.get("location"), ChatLocation, bot)
+        data["available_reactions"] = de_list_optional(
+            data.get("available_reactions"), ReactionType, bot
+        )
+        data["birthdate"] = de_json_optional(data.get("birthdate"), Birthdate, bot)
+        data["personal_chat"] = de_json_optional(data.get("personal_chat"), Chat, bot)
+        data["business_intro"] = de_json_optional(data.get("business_intro"), BusinessIntro, bot)
+        data["business_location"] = de_json_optional(
+            data.get("business_location"), BusinessLocation, bot
+        )
+        data["business_opening_hours"] = de_json_optional(
+            data.get("business_opening_hours"), BusinessOpeningHours, bot
        )

        return super().de_json(data=data, bot=bot)
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,11 +17,12 @@
 # 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 an invite link for a chat."""
-import datetime
+import datetime as dtm
 from typing import TYPE_CHECKING, Optional

 from telegram._telegramobject import TelegramObject
 from telegram._user import User
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
 from telegram._utils.types import JSONDict

@@ -139,7 +140,7 @@ class ChatInviteLink(TelegramObject):
        creates_join_request: bool,
        is_primary: bool,
        is_revoked: bool,
-        expire_date: Optional[datetime.datetime] = None,
+        expire_date: Optional[dtm.datetime] = None,
        member_limit: Optional[int] = None,
        name: Optional[str] = None,
        pending_join_request_count: Optional[int] = None,
@@ -157,7 +158,7 @@ class ChatInviteLink(TelegramObject):
        self.is_revoked: bool = is_revoked

        # Optionals
-        self.expire_date: Optional[datetime.datetime] = expire_date
+        self.expire_date: Optional[dtm.datetime] = expire_date
        self.member_limit: Optional[int] = member_limit
        self.name: Optional[str] = name
        self.pending_join_request_count: Optional[int] = (
@@ -177,19 +178,14 @@ class ChatInviteLink(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        # Get the local timezone from the bot if it has defaults
        loc_tzinfo = extract_tzinfo_from_defaults(bot)

-        data["creator"] = User.de_json(data.get("creator"), bot)
+        data["creator"] = de_json_optional(data.get("creator"), User, bot)
        data["expire_date"] = from_timestamp(data.get("expire_date", None), tzinfo=loc_tzinfo)

        return super().de_json(data=data, bot=bot)
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,13 +17,14 @@
 # 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 ChatJoinRequest."""
-import datetime
+import datetime as dtm
 from typing import TYPE_CHECKING, Optional

 from telegram._chat import Chat
 from telegram._chatinvitelink import ChatInviteLink
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
 from telegram._utils.defaultvalue import DEFAULT_NONE
 from telegram._utils.types import JSONDict, ODVInput
@@ -106,7 +107,7 @@ class ChatJoinRequest(TelegramObject):
        self,
        chat: Chat,
        from_user: User,
-        date: datetime.datetime,
+        date: dtm.datetime,
        user_chat_id: int,
        bio: Optional[str] = None,
        invite_link: Optional[ChatInviteLink] = None,
@@ -117,7 +118,7 @@ class ChatJoinRequest(TelegramObject):
        # Required
        self.chat: Chat = chat
        self.from_user: User = from_user
-        self.date: datetime.datetime = date
+        self.date: dtm.datetime = date
        self.user_chat_id: int = user_chat_id

        # Optionals
@@ -129,22 +130,17 @@ class ChatJoinRequest(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        # Get the local timezone from the bot if it has defaults
        loc_tzinfo = extract_tzinfo_from_defaults(bot)

-        data["chat"] = Chat.de_json(data.get("chat"), bot)
-        data["from_user"] = User.de_json(data.pop("from", None), bot)
+        data["chat"] = de_json_optional(data.get("chat"), Chat, bot)
+        data["from_user"] = de_json_optional(data.pop("from", None), User, bot)
        data["date"] = from_timestamp(data.get("date", None), tzinfo=loc_tzinfo)
-        data["invite_link"] = ChatInviteLink.de_json(data.get("invite_link"), bot)
+        data["invite_link"] = de_json_optional(data.get("invite_link"), ChatInviteLink, bot)

        return super().de_json(data=data, bot=bot)

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -23,6 +23,7 @@ from typing import TYPE_CHECKING, Final, Optional
 from telegram import constants
 from telegram._files.location import Location
 from telegram._telegramobject import TelegramObject
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.types import JSONDict

 if TYPE_CHECKING:
@@ -68,16 +69,11 @@ class ChatLocation(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["location"] = Location.de_json(data.get("location"), bot)
+        data["location"] = de_json_optional(data.get("location"), Location, bot)

        return super().de_json(data=data, bot=bot)

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,12 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChatMember."""

-import datetime
+import datetime as dtm
 from typing import TYPE_CHECKING, Final, Optional

 from telegram import constants
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
 from telegram._utils.types import JSONDict

@@ -105,15 +106,10 @@ class ChatMember(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        _class_mapping: dict[str, type[ChatMember]] = {
            cls.OWNER: ChatMemberOwner,
            cls.ADMINISTRATOR: ChatMemberAdministrator,
@@ -126,12 +122,12 @@ class ChatMember(TelegramObject):
        if cls is ChatMember and data.get("status") in _class_mapping:
            return _class_mapping[data.pop("status")].de_json(data=data, bot=bot)

-        data["user"] = User.de_json(data.get("user"), bot)
+        data["user"] = de_json_optional(data.get("user"), User, bot)
        if "until_date" in data:
            # Get the local timezone from the bot if it has defaults
            loc_tzinfo = extract_tzinfo_from_defaults(bot)

-            data["until_date"] = from_timestamp(data["until_date"], tzinfo=loc_tzinfo)
+            data["until_date"] = from_timestamp(data.get("until_date"), tzinfo=loc_tzinfo)

        # This is a deprecated field that TG still returns for backwards compatibility
        # Let's filter it out to speed up the de-json process
@@ -413,13 +409,13 @@ class ChatMemberMember(ChatMember):
    def __init__(
        self,
        user: User,
-        until_date: Optional[datetime.datetime] = None,
+        until_date: Optional[dtm.datetime] = None,
        *,
        api_kwargs: Optional[JSONDict] = None,
    ):
        super().__init__(status=ChatMember.MEMBER, user=user, api_kwargs=api_kwargs)
        with self._unfrozen():
-            self.until_date: Optional[datetime.datetime] = until_date
+            self.until_date: Optional[dtm.datetime] = until_date


 class ChatMemberRestricted(ChatMember):
@@ -566,7 +562,7 @@ class ChatMemberRestricted(ChatMember):
        can_send_other_messages: bool,
        can_add_web_page_previews: bool,
        can_manage_topics: bool,
-        until_date: datetime.datetime,
+        until_date: dtm.datetime,
        can_send_audios: bool,
        can_send_documents: bool,
        can_send_photos: bool,
@@ -587,7 +583,7 @@ class ChatMemberRestricted(ChatMember):
            self.can_send_other_messages: bool = can_send_other_messages
            self.can_add_web_page_previews: bool = can_add_web_page_previews
            self.can_manage_topics: bool = can_manage_topics
-            self.until_date: datetime.datetime = until_date
+            self.until_date: dtm.datetime = until_date
            self.can_send_audios: bool = can_send_audios
            self.can_send_documents: bool = can_send_documents
            self.can_send_photos: bool = can_send_photos
@@ -656,10 +652,10 @@ class ChatMemberBanned(ChatMember):
    def __init__(
        self,
        user: User,
-        until_date: datetime.datetime,
+        until_date: dtm.datetime,
        *,
        api_kwargs: Optional[JSONDict] = None,
    ):
        super().__init__(status=ChatMember.BANNED, user=user, api_kwargs=api_kwargs)
        with self._unfrozen():
-            self.until_date: datetime.datetime = until_date
+            self.until_date: dtm.datetime = until_date
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -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 ChatMemberUpdated."""
-import datetime
+import datetime as dtm
 from typing import TYPE_CHECKING, Optional, Union

 from telegram._chat import Chat
@@ -25,6 +25,7 @@ from telegram._chatinvitelink import ChatInviteLink
 from telegram._chatmember import ChatMember
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
 from telegram._utils.types import JSONDict

@@ -108,7 +109,7 @@ class ChatMemberUpdated(TelegramObject):
        self,
        chat: Chat,
        from_user: User,
-        date: datetime.datetime,
+        date: dtm.datetime,
        old_chat_member: ChatMember,
        new_chat_member: ChatMember,
        invite_link: Optional[ChatInviteLink] = None,
@@ -121,7 +122,7 @@ class ChatMemberUpdated(TelegramObject):
        # Required
        self.chat: Chat = chat
        self.from_user: User = from_user
-        self.date: datetime.datetime = date
+        self.date: dtm.datetime = date
        self.old_chat_member: ChatMember = old_chat_member
        self.new_chat_member: ChatMember = new_chat_member
        self.via_chat_folder_invite_link: Optional[bool] = via_chat_folder_invite_link
@@ -141,24 +142,19 @@ class ChatMemberUpdated(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        # Get the local timezone from the bot if it has defaults
        loc_tzinfo = extract_tzinfo_from_defaults(bot)

-        data["chat"] = Chat.de_json(data.get("chat"), bot)
-        data["from_user"] = User.de_json(data.pop("from", None), bot)
+        data["chat"] = de_json_optional(data.get("chat"), Chat, bot)
+        data["from_user"] = de_json_optional(data.pop("from", None), User, bot)
        data["date"] = from_timestamp(data.get("date"), tzinfo=loc_tzinfo)
-        data["old_chat_member"] = ChatMember.de_json(data.get("old_chat_member"), bot)
-        data["new_chat_member"] = ChatMember.de_json(data.get("new_chat_member"), bot)
-        data["invite_link"] = ChatInviteLink.de_json(data.get("invite_link"), bot)
+        data["old_chat_member"] = de_json_optional(data.get("old_chat_member"), ChatMember, bot)
+        data["new_chat_member"] = de_json_optional(data.get("new_chat_member"), ChatMember, bot)
+        data["invite_link"] = de_json_optional(data.get("invite_link"), ChatInviteLink, bot)

        return super().de_json(data=data, bot=bot)

@@ -179,9 +175,7 @@ class ChatMemberUpdated(TelegramObject):
        self,
    ) -> dict[
        str,
-        tuple[
-            Union[str, bool, datetime.datetime, User], Union[str, bool, datetime.datetime, User]
-        ],
+        tuple[Union[str, bool, dtm.datetime, User], Union[str, bool, dtm.datetime, User]],
    ]:
        """Computes the difference between :attr:`old_chat_member` and :attr:`new_chat_member`.

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -231,15 +231,10 @@ class ChatPermissions(TelegramObject):
        return cls(*(14 * (False,)))

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

-        if not data:
-            return None
-
        api_kwargs = {}
        # This is a deprecated field that TG still returns for backwards compatibility
        # Let's filter it out to speed up the de-json process
@@ -2,7 +2,7 @@
 # pylint: disable=too-many-arguments
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -24,6 +24,7 @@ from typing import TYPE_CHECKING, Optional
 from telegram._files.location import Location
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.types import JSONDict

 if TYPE_CHECKING:
@@ -92,18 +93,13 @@ class ChosenInlineResult(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
        # Required
-        data["from_user"] = User.de_json(data.pop("from", None), bot)
+        data["from_user"] = de_json_optional(data.pop("from", None), User, bot)
        # Optionals
-        data["location"] = Location.de_json(data.get("location"), bot)
+        data["location"] = de_json_optional(data.get("location"), Location, bot)

        return super().de_json(data=data, bot=bot)
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -21,6 +21,7 @@ from typing import TYPE_CHECKING, Optional, TypeVar

 from telegram._files._basemedium import _BaseMedium
 from telegram._files.photosize import PhotoSize
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.types import JSONDict

 if TYPE_CHECKING:
@@ -82,17 +83,14 @@ class _BaseThumbedMedium(_BaseMedium):

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

-        if not data:
-            return None
-
        # In case this wasn't already done by the subclass
        if not isinstance(data.get("thumbnail"), PhotoSize):
-            data["thumbnail"] = PhotoSize.de_json(data.get("thumbnail"), bot)
+            data["thumbnail"] = de_json_optional(data.get("thumbnail"), PhotoSize, bot)

        api_kwargs = {}
        # This is a deprecated field that TG still returns for backwards compatibility
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -26,7 +26,7 @@ from telegram._files.file import File
 from telegram._files.photosize import PhotoSize
 from telegram._telegramobject import TelegramObject
 from telegram._utils import enum
-from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.argumentparsing import de_json_optional, de_list_optional, parse_sequence_arg
 from telegram._utils.types import JSONDict

 if TYPE_CHECKING:
@@ -194,16 +194,13 @@ class Sticker(_BaseThumbedMedium):
    """:const:`telegram.constants.StickerType.CUSTOM_EMOJI`"""

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

-        if not data:
-            return None
-
-        data["thumbnail"] = PhotoSize.de_json(data.get("thumbnail"), bot)
-        data["mask_position"] = MaskPosition.de_json(data.get("mask_position"), bot)
-        data["premium_animation"] = File.de_json(data.get("premium_animation"), bot)
+        data["thumbnail"] = de_json_optional(data.get("thumbnail"), PhotoSize, bot)
+        data["mask_position"] = de_json_optional(data.get("mask_position"), MaskPosition, bot)
+        data["premium_animation"] = de_json_optional(data.get("premium_animation"), File, bot)

        api_kwargs = {}
        # This is a deprecated field that TG still returns for backwards compatibility
@@ -306,15 +303,12 @@ class StickerSet(TelegramObject):
        self._freeze()

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

-        data["thumbnail"] = PhotoSize.de_json(data.get("thumbnail"), bot)
-        data["stickers"] = Sticker.de_list(data.get("stickers"), bot)
+        data["thumbnail"] = de_json_optional(data.get("thumbnail"), PhotoSize, bot)
+        data["stickers"] = de_list_optional(data.get("stickers"), Sticker, bot)

        api_kwargs = {}
        # These are deprecated fields that TG still returns for backwards compatibility
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -22,6 +22,7 @@ from typing import TYPE_CHECKING, Optional

 from telegram._files.location import Location
 from telegram._telegramobject import TelegramObject
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.types import JSONDict

 if TYPE_CHECKING:
@@ -103,13 +104,10 @@ class Venue(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["location"] = Location.de_json(data.get("location"), bot)
+        data["location"] = de_json_optional(data.get("location"), Location, bot)

        return super().de_json(data=data, bot=bot)
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -24,7 +24,7 @@ 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.argumentparsing import de_json_optional, de_list_optional, parse_sequence_arg
 from telegram._utils.strings import TextEncoding
 from telegram._utils.types import JSONDict

@@ -124,16 +124,13 @@ class Game(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["photo"] = PhotoSize.de_list(data.get("photo"), bot)
-        data["text_entities"] = MessageEntity.de_list(data.get("text_entities"), bot)
-        data["animation"] = Animation.de_json(data.get("animation"), bot)
+        data["photo"] = de_list_optional(data.get("photo"), PhotoSize, bot)
+        data["text_entities"] = de_list_optional(data.get("text_entities"), MessageEntity, bot)
+        data["animation"] = de_json_optional(data.get("animation"), Animation, bot)

        return super().de_json(data=data, bot=bot)

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -22,6 +22,7 @@ from typing import TYPE_CHECKING, Optional

 from telegram._telegramobject import TelegramObject
 from telegram._user import User
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.types import JSONDict

 if TYPE_CHECKING:
@@ -61,15 +62,10 @@ class GameHighScore(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["user"] = User.de_json(data.get("user"), bot)
+        data["user"] = de_json_optional(data.get("user"), User, bot)

        return super().de_json(data=data, bot=bot)
@@ -2,7 +2,7 @@
 # pylint: disable=redefined-builtin
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -23,7 +23,7 @@ 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.argumentparsing import de_json_optional, de_list_optional, parse_sequence_arg
 from telegram._utils.types import JSONDict

 if TYPE_CHECKING:
@@ -46,6 +46,10 @@ class Gift(TelegramObject):
            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
+        upgrade_star_count (:obj:`int`, optional): The number of Telegram Stars that must be paid
+            to upgrade the gift to a unique one
+
+            .. versionadded:: 21.10

    Attributes:
        id (:obj:`str`): Unique identifier of the gift
@@ -55,10 +59,21 @@ class Gift(TelegramObject):
            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
+        upgrade_star_count (:obj:`int`): Optional. The number of Telegram Stars that must be paid
+            to upgrade the gift to a unique one
+
+            .. versionadded:: 21.10

    """

-    __slots__ = ("id", "remaining_count", "star_count", "sticker", "total_count")
+    __slots__ = (
+        "id",
+        "remaining_count",
+        "star_count",
+        "sticker",
+        "total_count",
+        "upgrade_star_count",
+    )

    def __init__(
        self,
@@ -67,6 +82,7 @@ class Gift(TelegramObject):
        star_count: int,
        total_count: Optional[int] = None,
        remaining_count: Optional[int] = None,
+        upgrade_star_count: Optional[int] = None,
        *,
        api_kwargs: Optional[JSONDict] = None,
    ):
@@ -76,21 +92,19 @@ class Gift(TelegramObject):
        self.star_count: int = star_count
        self.total_count: Optional[int] = total_count
        self.remaining_count: Optional[int] = remaining_count
+        self.upgrade_star_count: Optional[int] = upgrade_star_count

        self._id_attrs = (self.id,)

        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: Optional["Bot"] = None) -> Optional["Gift"]:
+    def de_json(cls, data: JSONDict, bot: Optional["Bot"] = None) -> "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)
+        data["sticker"] = de_json_optional(data.get("sticker"), Sticker, bot)
+        return super().de_json(data=data, bot=bot)


 class Gifts(TelegramObject):
@@ -125,12 +139,9 @@ class Gifts(TelegramObject):
        self._freeze()

    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: Optional["Bot"] = None) -> Optional["Gifts"]:
+    def de_json(cls, data: JSONDict, bot: Optional["Bot"] = None) -> "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)
+        data["gifts"] = de_list_optional(data.get("gifts"), Gift, bot)
+        return super().de_json(data=data, bot=bot)
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,14 +17,14 @@
 # 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 objects that are related to Telegram giveaways."""
-import datetime
+import datetime as dtm
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Optional

 from telegram._chat import Chat
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
-from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.argumentparsing import de_json_optional, de_list_optional, parse_sequence_arg
 from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
 from telegram._utils.types import JSONDict

@@ -105,7 +105,7 @@ class Giveaway(TelegramObject):
    def __init__(
        self,
        chats: Sequence[Chat],
-        winners_selection_date: datetime.datetime,
+        winners_selection_date: dtm.datetime,
        winner_count: int,
        only_new_members: Optional[bool] = None,
        has_public_winners: Optional[bool] = None,
@@ -119,7 +119,7 @@ class Giveaway(TelegramObject):
        super().__init__(api_kwargs=api_kwargs)

        self.chats: tuple[Chat, ...] = tuple(chats)
-        self.winners_selection_date: datetime.datetime = winners_selection_date
+        self.winners_selection_date: dtm.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
@@ -137,19 +137,14 @@ class Giveaway(TelegramObject):
        self._freeze()

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

-        if data is None:
-            return None
-
        # Get the local timezone from the bot if it has defaults
        loc_tzinfo = extract_tzinfo_from_defaults(bot)

-        data["chats"] = tuple(Chat.de_list(data.get("chats"), bot))
+        data["chats"] = de_list_optional(data.get("chats"), Chat, bot)
        data["winners_selection_date"] = from_timestamp(
            data.get("winners_selection_date"), tzinfo=loc_tzinfo
        )
@@ -260,7 +255,7 @@ class GiveawayWinners(TelegramObject):
        self,
        chat: Chat,
        giveaway_message_id: int,
-        winners_selection_date: datetime.datetime,
+        winners_selection_date: dtm.datetime,
        winner_count: int,
        winners: Sequence[User],
        additional_chat_count: Optional[int] = None,
@@ -277,7 +272,7 @@ class GiveawayWinners(TelegramObject):

        self.chat: Chat = chat
        self.giveaway_message_id: int = giveaway_message_id
-        self.winners_selection_date: datetime.datetime = winners_selection_date
+        self.winners_selection_date: dtm.datetime = winners_selection_date
        self.winner_count: int = winner_count
        self.winners: tuple[User, ...] = tuple(winners)
        self.additional_chat_count: Optional[int] = additional_chat_count
@@ -299,20 +294,15 @@ class GiveawayWinners(TelegramObject):
        self._freeze()

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

-        if data is None:
-            return None
-
        # Get the local timezone from the bot if it has defaults
        loc_tzinfo = extract_tzinfo_from_defaults(bot)

-        data["chat"] = Chat.de_json(data.get("chat"), bot)
-        data["winners"] = tuple(User.de_list(data.get("winners"), bot))
+        data["chat"] = de_json_optional(data.get("chat"), Chat, bot)
+        data["winners"] = de_list_optional(data.get("winners"), User, bot)
        data["winners_selection_date"] = from_timestamp(
            data.get("winners_selection_date"), tzinfo=loc_tzinfo
        )
@@ -376,18 +366,13 @@ class GiveawayCompleted(TelegramObject):
        self._freeze()

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

-        if data is None:
-            return None
-
        # Unfortunately, this needs to be here due to cyclic imports
        from telegram._message import Message  # pylint: disable=import-outside-toplevel

-        data["giveaway_message"] = Message.de_json(data.get("giveaway_message"), bot)
+        data["giveaway_message"] = de_json_optional(data.get("giveaway_message"), Message, bot)

        return super().de_json(data=data, bot=bot)
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -26,6 +26,7 @@ from telegram._games.callbackgame import CallbackGame
 from telegram._loginurl import LoginUrl
 from telegram._switchinlinequerychosenchat import SwitchInlineQueryChosenChat
 from telegram._telegramobject import TelegramObject
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.types import JSONDict
 from telegram._webappinfo import WebAppInfo

@@ -296,22 +297,17 @@ class InlineKeyboardButton(TelegramObject):
        )

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

-        if not data:
-            return None
-
-        data["login_url"] = LoginUrl.de_json(data.get("login_url"), bot)
-        data["web_app"] = WebAppInfo.de_json(data.get("web_app"), bot)
-        data["callback_game"] = CallbackGame.de_json(data.get("callback_game"), bot)
-        data["switch_inline_query_chosen_chat"] = SwitchInlineQueryChosenChat.de_json(
-            data.get("switch_inline_query_chosen_chat"), bot
+        data["login_url"] = de_json_optional(data.get("login_url"), LoginUrl, bot)
+        data["web_app"] = de_json_optional(data.get("web_app"), WebAppInfo, bot)
+        data["callback_game"] = de_json_optional(data.get("callback_game"), CallbackGame, bot)
+        data["switch_inline_query_chosen_chat"] = de_json_optional(
+            data.get("switch_inline_query_chosen_chat"), SwitchInlineQueryChosenChat, bot
        )
-        data["copy_text"] = CopyTextButton.de_json(data.get("copy_text"), bot)
+        data["copy_text"] = de_json_optional(data.get("copy_text"), CopyTextButton, bot)

        return super().de_json(data=data, bot=bot)

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -91,12 +91,8 @@ class InlineKeyboardMarkup(TelegramObject):
        self._freeze()

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

        keyboard = []
        for row in data["inline_keyboard"]:
@@ -2,7 +2,7 @@
 # pylint: disable=too-many-arguments
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -27,8 +27,9 @@ from telegram._files.location import Location
 from telegram._inline.inlinequeryresultsbutton import InlineQueryResultsButton
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
+from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import JSONDict, ODVInput
+from telegram._utils.types import JSONDict, ODVInput, TimePeriod

 if TYPE_CHECKING:
    from telegram import Bot, InlineQueryResult
@@ -126,17 +127,12 @@ class InlineQuery(TelegramObject):
        self._freeze()

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

-        if not data:
-            return None
-
-        data["from_user"] = User.de_json(data.pop("from", None), bot)
-        data["location"] = Location.de_json(data.get("location"), bot)
+        data["from_user"] = de_json_optional(data.pop("from", None), User, bot)
+        data["location"] = de_json_optional(data.get("location"), Location, bot)

        return super().de_json(data=data, bot=bot)

@@ -145,7 +141,7 @@ class InlineQuery(TelegramObject):
        results: Union[
            Sequence["InlineQueryResult"], Callable[[int], Optional[Sequence["InlineQueryResult"]]]
        ],
-        cache_time: Optional[int] = None,
+        cache_time: Optional[TimePeriod] = None,
        is_personal: Optional[bool] = None,
        next_offset: Optional[str] = None,
        button: Optional[InlineQueryResultsButton] = None,
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -23,7 +23,9 @@ from typing import TYPE_CHECKING, Optional
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._utils.types import JSONDict
+from telegram._utils.warnings import warn
 from telegram.constants import InlineQueryResultType
+from telegram.warnings import PTBDeprecationWarning

 if TYPE_CHECKING:
    from telegram import InputMessageContent
@@ -50,6 +52,10 @@ class InlineQueryResultArticle(InlineQueryResult):
        url (:obj:`str`, optional): URL of the result.
        hide_url (:obj:`bool`, optional): Pass :obj:`True`, if you don't want the URL to be shown
            in the message.
+
+            .. deprecated:: 21.10
+                This attribute will be removed in future PTB versions. Pass an empty string as URL
+                instead.
        description (:obj:`str`, optional): Short description of the result.
        thumbnail_url (:obj:`str`, optional): Url of the thumbnail for the result.

@@ -74,6 +80,10 @@ class InlineQueryResultArticle(InlineQueryResult):
        url (:obj:`str`): Optional. URL of the result.
        hide_url (:obj:`bool`): Optional. Pass :obj:`True`, if you don't want the URL to be shown
            in the message.
+
+            .. deprecated:: 21.10
+                This attribute will be removed in future PTB versions. Pass an empty string as URL
+                instead.
        description (:obj:`str`): Optional. Short description of the result.
        thumbnail_url (:obj:`str`): Optional. Url of the thumbnail for the result.

@@ -123,6 +133,15 @@ class InlineQueryResultArticle(InlineQueryResult):
            # Optional
            self.reply_markup: Optional[InlineKeyboardMarkup] = reply_markup
            self.url: Optional[str] = url
+            if hide_url is not None:
+                warn(
+                    PTBDeprecationWarning(
+                        "21.10",
+                        "The argument `hide_url` will be removed in future PTB"
+                        "versions. Pass an empty string as URL instead.",
+                    ),
+                    stacklevel=2,
+                )
            self.hide_url: Optional[bool] = hide_url
            self.description: Optional[str] = description
            self.thumbnail_url: Optional[str] = thumbnail_url
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2024
+# Copyright (C) 2015-2025
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Hinrich Mahler	b1fff6d90a	Use Lock instead of semaphore	2025-02-06 12:05:20 +01:00
Hinrich Mahler	31af1a9db8	Add an example on concurrency in FSM	2025-02-06 11:57:18 +01:00
Hinrich Mahler	4441543043	Try setting up infrastructure for optimistic locking. Example will follow	2025-02-05 23:40:15 +01:00
Hinrich Mahler	646ba37391	Move internal state storage to FiniteStateMachine and add state history	2025-02-05 13:13:21 +01:00
Hinrich Mahler	817b71d914	Disable tests harder …	2025-02-05 12:26:02 +01:00
Hinrich Mahler	434cbfade8	Add Some Abstractions for Timeout Jobs	2025-02-05 12:22:07 +01:00
Hinrich Mahler	34832d9db9	Temporarily Disable Tests on this branch	2025-02-05 11:17:47 +01:00
Hinrich Mahler	07225b9a02	Add State.ANY for fallbacks and allow handling multiple states for one update	2025-02-05 10:52:10 +01:00
Hinrich Mahler	0c06ba0a90	Initial FSM PoC	2025-02-04 21:36:40 +01:00
Bibo-Joshi	dfb0ae3747	Use Fine Grained Permissions for GitHub Actions Workflows (#4668 )	2025-02-02 10:24:46 +01:00
dependabot[bot]	64006aa7ae	Bump `actions/setup-python` from 5.3.0 to 5.4.0 (#4665 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2025-02-02 09:52:35 +01:00
dependabot[bot]	69ddc47a6e	Bump `dependabot/fetch-metadata` from 2.2.0 to 2.3.0 (#4666 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-02-02 09:34:10 +01:00
Bibo-Joshi	a2150b3751	Accept `datetime.timedelta` Input in `Bot` Method Parameters (#4651 )	2025-02-02 09:31:18 +01:00
dependabot[bot]	79acc1ae53	Bump `actions/stale` from 9.0.0 to 9.1.0 (#4667 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-02-02 09:22:47 +01:00
dependabot[bot]	4cdb1a0cf7	Bump `astral-sh/setup-uv` from 5.1.0 to 5.2.2 (#4664 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-02-02 09:09:55 +01:00
dependabot[bot]	6319f4bae1	Bump `codecov/test-results-action` from 1.0.1 to 1.0.2 (#4663 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-02-02 09:09:13 +01:00
Harshil	d7e063dbad	Overhaul Admonition Insertion in Documentation (#4462 ) Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2025-01-31 19:23:09 +01:00
Bibo-Joshi	5dd7b8f1e2	Extend Customization Support for `Bot.base_(file_)url` (#4632 )	2025-01-23 06:01:27 +01:00
Bibo-Joshi	61b87ba318	Support `allow_paid_broadcast` in `AIORateLimiter` (#4627 )	2025-01-23 05:59:39 +01:00
Bibo-Joshi	dd592cdd7c	Simplify Handling of Empty Data in `TelegramObject.de_json` and Friends (#4617 )	2025-01-14 17:12:55 +01:00
Bibo-Joshi	f57dd52100	Add `BaseUpdateProcessor.current_concurrent_updates` (#4626 )	2025-01-14 17:00:20 +01:00
pre-commit-ci[bot]	16605c54d7	Bump `pre-commit` Hooks to Latest Versions (#4643 ) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2025-01-07 18:11:35 +01:00
Bibo-Joshi	e4b0f8cb64	Bump Version to v21.10 (#4639 )	2025-01-03 12:11:53 +01:00
Poolitzer	f2dc0175cd	Full Support for Bot API 8.2 (#4633 ) Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2025-01-03 11:39:35 +01:00
Bibo-Joshi	a781a4fddb	Add Parameter `pattern` to `JobQueue.jobs()` (#4613 )	2025-01-02 10:03:39 +01:00
Bibo-Joshi	679d038979	Ensure Forward Compatibility of `Gift` and `Gifts` (#4634 )	2025-01-02 09:17:01 +01:00
dependabot[bot]	d0a6e5141c	Bump APS & Deprecate `pytz` Support (#4582 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>	2025-01-01 19:43:52 +01:00
Bibo-Joshi	5f35304e63	Update Copyright to 2025 (#4631 )	2025-01-01 14:51:12 +01:00
Poolitzer	3fc50c78eb	Remove Redundant `pylint` Suppressions (#4628 )	2024-12-31 15:13:31 +01:00
dependabot[bot]	3c9bba63eb	Bump `astral-sh/setup-uv` from 4.2.0 to 5.1.0 (#4625 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-12-31 11:47:39 +01:00
dependabot[bot]	a9a7b07b10	Bump `codecov/codecov-action` from 5.1.1 to 5.1.2 (#4622 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-12-31 11:41:56 +01:00
dependabot[bot]	e1e7b621f1	Bump `actions/upload-artifact` from 4.4.3 to 4.5.0 (#4623 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-12-30 23:03:03 +01:00
dependabot[bot]	dfb3c13d1d	Bump `github/codeql-action` from 3.27.9 to 3.28.0 (#4624 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-12-30 23:02:43 +01:00
Bibo-Joshi	f7a3f67a9f	Use Custom Labels for `dependabot` PRs (#4621 )	2024-12-30 22:50:23 +01:00
Bibo-Joshi	a6cd9c5292	Allow Input of Type `Sticker` for Several Methods (#4616 )	2024-12-29 20:16:46 +01:00
Bibo-Joshi	df20e49db1	Refactor Module Structure and Tests for Star Payments Classes (#4615 )	2024-12-29 17:58:37 +01:00
Juan Andrés Cuevas	4f255b6e21	Unify `datetime` Imports (#4605 ) Co-authored-by: Miguel Salomon <128310363+Migueldsc12@users.noreply.github.com> Co-authored-by: Jeamhowards Montiel <106713677+Jeam-zx@users.noreply.github.com> Co-authored-by: Snehashish Biswas <coderrx06@gmail.com> Co-authored-by: Luis Pérez <luis.i.perez.0@gmail.com> Co-authored-by: henryg311 <55552582+henryg311@users.noreply.github.com> Co-authored-by: AnyaMarcanito <129221958+AnyaMarcanito@users.noreply.github.com> Co-authored-by: Jeam Montiel <19-10234@usb.ve>	2024-12-15 10:26:37 +01:00
Bibo-Joshi	4afe174b5c	Add Static Security Analysis of GitHub Actions Workflows (#4606 )	2024-12-13 22:16:31 +01:00
Bibo-Joshi	2ac52018c2	Bump Version to v21.9 (#4601 )	2024-12-07 13:39:41 +01:00
dependabot[bot]	ca7a30963d	Update `aiolimiter` requirement from ~=1.1.0 to >=1.1,<1.3 (#4595 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <dependabot[bot]@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-12-07 11:31:52 +01:00
dependabot[bot]	c42a230b96	Bump `pytest` from 8.3.3 to 8.3.4 (#4596 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>	2024-12-07 11:15:53 +01:00
Luis Pérez	ce9742a602	Use `MessageLimit.DEEP_LINK_LENGTH` in `helpers.create_deep_linked_url` (#4597 )	2024-12-07 10:25:13 +01:00
Bibo-Joshi	43279543a3	Full Support for Bot API 8.1 (#4594 )	2024-12-07 10:20:08 +01:00
Luis Pérez	eda2172617	Allow `Sequence` Input for `allowed_updates` in `Application` and `Updater` Methods (#4589 )	2024-12-04 21:20:12 +01:00
dependabot[bot]	89dfa37dbf	Bump `codecov/codecov-action` from 4 to 5 (#4585 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-12-04 21:04:47 +01:00
Luis Pérez	3709c2fa93	Bump `pylint` to v3.3.2 to Improve Python 3.13 Support (#4590 )	2024-12-04 20:54:03 +01:00
dependabot[bot]	da93fe94ae	Bump `srvaroa/labeler` from 1.11.1 to 1.12.0 (#4586 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-12-02 06:17:52 +01:00