Bump Version to v22.3 (#4870)

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

.github/CONTRIBUTING.rst

@@ -22,12 +22,16 @@ Setting things up
 
       $ git remote add upstream https://github.com/python-telegram-bot/python-telegram-bot
 
-4. Install dependencies:
+4. Install the package in development mode as well as optional dependencies and development dependencies.
+   Note that the `--group` argument requires `pip` 25.1 or later.
+   
+   Alternatively, you can use your preferred package manager (such as uv, hatch, poetry, etc.) instead of pip.
 
    .. code-block:: bash
 
-      $ pip install -r requirements-dev-all.txt
+      $ pip install -e .[all] --group all
 
+   Installing the package itself is necessary because python-telegram-bot uses a src-based layout where the package code is located in the ``src/`` directory.
 
 5. Install pre-commit hooks:
 
@@ -157,45 +161,47 @@ Check-list for PRs
 This checklist is a non-exhaustive reminder of things that should be done before a PR is merged, both for you as contributor and for the maintainers.
 Feel free to copy (parts of) the checklist to the PR description to remind you or the maintainers of open points or if you have questions on anything.
 
-- Added ``.. versionadded:: NEXT.VERSION``, ``.. versionchanged:: NEXT.VERSION``, ``.. deprecated:: NEXT.VERSION`` or ``.. versionremoved:: NEXT.VERSION`` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
-- Created new or adapted existing unit tests
-- Documented code changes according to the `CSI standard <https://standards.mousepawmedia.com/en/stable/csi.html>`__
-- Added myself alphabetically to ``AUTHORS.rst`` (optional)
-- Added new classes & modules to the docs and all suitable ``__all__`` s
-- Checked the `Stability Policy <https://docs.python-telegram-bot.org/stability_policy.html>`_ in case of deprecations or changes to documented behavior
+.. code-block:: markdown
 
-**If the PR contains API changes (otherwise, you can ignore this passage)**
+    ## Check-list for PRs
 
-- Checked the Bot API specific sections of the `Stability Policy <https://docs.python-telegram-bot.org/stability_policy.html>`_
-- Created a PR to remove functionality deprecated in the previous Bot API release (`see here <https://docs.python-telegram-bot.org/en/stable/stability_policy.html#case-2>`_)
+    - [ ] Added `.. versionadded:: NEXT.VERSION`, ``.. versionchanged:: NEXT.VERSION``, ``.. deprecated:: NEXT.VERSION`` or ``.. versionremoved:: NEXT.VERSION` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
+    - [ ] Created new or adapted existing unit tests
+    - [ ] Documented code changes according to the [CSI standard](https://standards.mousepawmedia.com/en/stable/csi.html)
+    - [ ] Added myself alphabetically to `AUTHORS.rst` (optional)
+    - [ ] Added new classes & modules to the docs and all suitable ``__all__`` s
+    - [ ] Checked the [Stability Policy](https://docs.python-telegram-bot.org/stability_policy.html) in case of deprecations or changes to documented behavior
 
--  New classes:
+    **If the PR contains API changes (otherwise, you can ignore this passage)**
 
-   - Added ``self._id_attrs`` and corresponding documentation
-   - ``__init__`` accepts ``api_kwargs`` as kw-only
+    - [ ] Checked the Bot API specific sections of the [Stability Policy](https://docs.python-telegram-bot.org/stability_policy.html)
+    - [ ] Created a PR to remove functionality deprecated in the previous Bot API release ([see here](https://docs.python-telegram-bot.org/en/stable/stability_policy.html#case-2))
 
--  Added new shortcuts:
+    - New Classes
 
-   - In :class:`~telegram.Chat` & :class:`~telegram.User` for all methods that accept ``chat/user_id``
-   - In :class:`~telegram.Message` for all methods that accept ``chat_id`` and ``message_id``
-   - For new :class:`~telegram.Message` shortcuts: Added ``quote`` argument if methods accepts ``reply_to_message_id``
-   - In :class:`~telegram.CallbackQuery` for all methods that accept either ``chat_id`` and ``message_id`` or ``inline_message_id``
+        - [ ] Added `self._id_attrs` and corresponding documentation
+        - [ ] `__init__` accepts `api_kwargs` as keyword-only
 
--  If relevant:
+    - Added New Shortcuts
 
-   - Added new constants at :mod:`telegram.constants` and shortcuts to them as class variables
-   - Link new and existing constants in docstrings instead of hard-coded numbers and strings
-   - Add new message types to :attr:`telegram.Message.effective_attachment`
-   - Added new handlers for new update types
+        - [ ] In [`telegram.Chat`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.chat.html) \& [`telegram.User`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.user.html) for all methods that accept `chat/user_id`
+        - [ ] In [`telegram.Message`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.message.html) for all methods that accept `chat_id` and `message_id`
+        - [ ] For new `telegram.Message` shortcuts: Added `quote` argument if methods accept `reply_to_message_id`
+        - [ ] In [`telegram.CallbackQuery`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.callbackquery.html) for all methods that accept either `chat_id` and `message_id` or `inline_message_id`
 
-     - Add the handlers to the warning loop in the :class:`~telegram.ext.ConversationHandler`
+    - If Relevant
 
-   - Added new filters for new message (sub)types
-   - Added or updated documentation for the changed class(es) and/or method(s)
-   - Added the new method(s) to ``_extbot.py``
-   - Added or updated ``bot_methods.rst``
-   - Updated the Bot API version number in all places: ``README.rst`` (including the badge) and ``telegram.constants.BOT_API_VERSION_INFO``
-   - Added logic for arbitrary callback data in :class:`telegram.ext.ExtBot` for new methods that either accept a ``reply_markup`` in some form or have a return type that is/contains :class:`~telegram.Message`
+        - [ ] Added new constants at `telegram.constants` and shortcuts to them as class variables
+        - [ ] Linked new and existing constants in docstrings instead of hard-coded numbers and strings
+        - [ ] Added new message types to `telegram.Message.effective_attachment`
+        - [ ] Added new handlers for new update types
+            - [ ] Added the handlers to the warning loop in the [`telegram.ext.ConversationHandler`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.conversationhandler.html)
+        - [ ] Added new filters for new message (sub)types
+        - [ ] Added or updated documentation for the changed class(es) and/or method(s)
+        - [ ] Added the new method(s) to `_extbot.py`
+        - [ ] Added or updated `bot_methods.rst`
+        - [ ] Updated the Bot API version number in all places: `README.rst` (including the badge) and `telegram.constants.BOT_API_VERSION_INFO`
+        - [ ] Added logic for arbitrary callback data in `telegram.ext.ExtBot` for new methods that either accept a `reply_markup` in some form or have a return type that is/contains [`telegram.Message`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.message.html)
 
 Documenting
 ===========

.github/workflows/assets/release_template.html

@@ -0,0 +1,5 @@
+<b>We've just released {tag}</b>.
+Thank you to everyone who contributed to this release.
+As usual, upgrade using <code>pip install -U python-telegram-bot</code>.
+
+The release notes can be found <a href="https://docs.python-telegram-bot.org/en/{tag}/changelog.html">here</a>.

.github/workflows/chango.yml

@@ -0,0 +1,66 @@
+name: Chango
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+permissions: {}
+
+jobs:
+  create-chango-fragment:
+    permissions:
+      # Give the default GITHUB_TOKEN write permission to commit and push the
+      # added or changed files to the repository.
+      contents: write
+    name: Create chango Fragment
+    runs-on: ubuntu-latest
+    outputs:
+      IS_RELEASE_PR: ${{ steps.check_title.outputs.IS_RELEASE_PR }}
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          # needed for commit and push step at the end
+          persist-credentials: true
+      - name: Check PR Title
+        id: check_title
+        run: | # zizmor: ignore[template-injection]
+          if [[ "$(echo "${{ github.event.pull_request.title }}" | tr '[:upper:]' '[:lower:]')" =~ ^bump\ version\ to\ .* ]]; then
+            echo "COMMIT_AND_PUSH=false" >> $GITHUB_OUTPUT
+            echo "IS_RELEASE_PR=true" >> $GITHUB_OUTPUT
+          else
+            echo "COMMIT_AND_PUSH=true" >> $GITHUB_OUTPUT
+            echo "IS_RELEASE_PR=false" >> $GITHUB_OUTPUT
+          fi
+
+      # Create the new fragment
+      - uses: Bibo-Joshi/chango@9d6bd9d7612eca5fab2c5161687011be59baaf19 # v0.4.0
+        with:
+          github-token: ${{ secrets.CHANGO_PAT }}
+          query-issue-types: true
+          commit-and-push: ${{ steps.check_title.outputs.COMMIT_AND_PUSH }}
+
+      # Run `chango release` if applicable - needs some additional setup.
+      - name: Set up Python
+        if: steps.check_title.outputs.IS_RELEASE_PR == 'true'
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.x"
+
+      - name: Do Release
+        if: steps.check_title.outputs.IS_RELEASE_PR == 'true'
+        run: |
+          cd ./target-repo
+          git add changes/unreleased/*
+          pip install . --group docs
+          VERSION_TAG=$(python -c "from telegram import __version__; print(f'{__version__}')")
+          chango release --uid $VERSION_TAG
+
+      - name: Commit & Push
+        if: steps.check_title.outputs.IS_RELEASE_PR == 'true'
+        uses: stefanzweifel/git-auto-commit-action@778341af668090896ca464160c2def5d1d1a3eb0 # v6.0.1
+        with:
+          commit_message: "Do chango Release"
+          repository: ./target-repo

.github/workflows/dependabot-prs.yml

@@ -18,7 +18,7 @@ jobs:
 
     - name: Fetch Dependabot metadata
       id: dependabot-metadata
-      uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 # v2.3.0
+      uses: dependabot/fetch-metadata@08eff52bf64351f401fb50d4972fa95b9f2c2d1b # v2.4.0
 
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       with:

.github/workflows/docs-admonitions.yml

@@ -0,0 +1,41 @@
+name: Test Admonitions Generation
+on:
+  pull_request:
+    paths:
+      - src/telegram/**
+      - docs/**
+      - .github/workflows/docs-admonitions.yml
+  push:
+    branches:
+      - master
+
+permissions: {}
+
+jobs:
+  test-admonitions:
+    name: Test Admonitions Generation
+    runs-on: ${{matrix.os}}
+    permissions:
+      # for uploading artifacts
+      actions: write
+    strategy:
+      matrix:
+        python-version: ['3.12']
+        os: [ubuntu-latest]
+      fail-fast: False
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install dependencies
+        run: |
+          python -W ignore -m pip install --upgrade pip
+          python -W ignore -m pip install .[all] --group all
+      - name: Test autogeneration of admonitions
+        run: pytest -v --tb=short tests/docs/admonition_inserter.py

.github/workflows/docs-linkcheck.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: ['3.10']
+        python-version: ['3.12']
         os: [ubuntu-latest]
       fail-fast: False
     steps:
@@ -23,19 +23,19 @@ jobs:
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         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
+          python -W ignore -m pip install .[all] --group all
       - name: Check Links
-        run: sphinx-build docs/source docs/build/html -W --keep-going -j auto -b linkcheck
+        run: sphinx-build docs/source docs/build/html --keep-going -j auto -b linkcheck
       - name: Upload linkcheck output
         # Run also if the previous steps failed
         if: always()
-        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: linkcheck-output
           path: docs/build/html/output.*

.github/workflows/docs.yml

@@ -1,53 +0,0 @@
-name: Test Documentation Build
-on:
-  pull_request:
-    paths:
-      - telegram/**
-      - docs/**
-  push:
-    branches:
-      - master
-
-permissions: {}
-
-jobs:
-  test-sphinx-build:
-    name: test-sphinx-build
-    runs-on: ${{matrix.os}}
-    permissions:
-      # for uploading artifacts
-      actions: write
-    strategy:
-      matrix:
-        python-version: ['3.10']
-        os: [ubuntu-latest]
-      fail-fast: False
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
-        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@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
-        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

.github/workflows/gha_security.yml

@@ -21,13 +21,13 @@ jobs:
         with:
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1
       - 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
+        uses: github/codeql-action/upload-sarif@181d5eefc20863364f96762470ba6f862bdef56b # v3.29.2
         with:
           sarif_file: results.sarif
           category: zizmor

.github/workflows/labelling.yml

@@ -13,7 +13,7 @@ jobs:
       pull-requests: write # for srvaroa/labeler to add labels in PR
     runs-on: ubuntu-latest
     steps:
-    - uses: srvaroa/labeler@fe4b1c73bb8abf2f14a44a6912a8b4fee835d631 # v1.12.0
+    - uses: srvaroa/labeler@0a20eccb8c94a1ee0bed5f16859aece1c45c3e55 # v1.13.0
       # Config file at .github/labeler.yml
       env:
         GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/release_pypi.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.x"
       - name: Install pypa/build
@@ -30,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@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: python-package-distributions
           path: dist/
@@ -55,12 +55,12 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: python-package-distributions
           path: dist/
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
 
   compute-signatures:
     name: Compute SHA1 Sums and Sign with Sigstore
@@ -74,7 +74,7 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: python-package-distributions
           path: dist/
@@ -86,13 +86,13 @@ jobs:
               sha1sum $file > $file.sha1
           done
       - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46 # v3.0.0
+        uses: sigstore/gh-action-sigstore-python@f7ad0af51a5648d09a20d00370f0a91c3bdf8f84 # v3.0.1
         with:
           inputs: >-
             ./dist/*.tar.gz
             ./dist/*.whl
       - name: Store the distribution packages and signatures
-        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -110,8 +110,11 @@ jobs:
       actions: read  # for downloading artifacts
 
     steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
       - name: Download all the dists
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -119,13 +122,14 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
           TAG: ${{ needs.build.outputs.TAG }}
-        # Create a tag and a GitHub Release. The description can be changed later, as for now
-        # we don't define it through this workflow.
+        # Create a tag and a GitHub Release. The description is filled by the static template, we
+        # just insert the correct tag in the template.
         run: >-
+          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
           gh release create
           "$TAG"
           --repo '${{ github.repository }}'
-          --generate-notes
+          --notes-file -
       - name: Upload artifact signatures to GitHub Release
         env:
           GITHUB_TOKEN: ${{ github.token }}
@@ -137,3 +141,32 @@ jobs:
           gh release upload
           "$TAG" dist/**
           --repo '${{ github.repository }}'
+
+  telegram-channel:
+    name: Publish to Telegram Channel
+    needs:
+      # required to have the output available for the env var
+      - build
+      - github-release
+
+    runs-on: ubuntu-latest
+    environment:
+      name: release_pypi
+    permissions: {}
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - name: Publish to Telegram Channel
+        env:
+          TAG: ${{ needs.build.outputs.TAG }}
+          # This secret is configured only for the `pypi-release` branch
+          BOT_TOKEN: ${{ secrets.CHANNEL_BOT_TOKEN }}
+        run: >-
+          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
+          curl
+          -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendMessage"
+          -d "chat_id=@pythontelegrambotchannel"
+          -d "parse_mode=HTML"
+          --data-urlencode "text@-"

.github/workflows/release_test_pypi.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.x"
       - name: Install pypa/build
@@ -30,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@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: python-package-distributions
           path: dist/
@@ -55,12 +55,12 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: python-package-distributions
           path: dist/
       - name: Publish to Test PyPI
-        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
         with:
           repository-url: https://test.pypi.org/legacy/
 
@@ -76,7 +76,7 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: python-package-distributions
           path: dist/
@@ -88,13 +88,13 @@ jobs:
               sha1sum $file > $file.sha1
           done
       - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46 # v3.0.0
+        uses: sigstore/gh-action-sigstore-python@f7ad0af51a5648d09a20d00370f0a91c3bdf8f84 # v3.0.1
         with:
           inputs: >-
             ./dist/*.tar.gz
             ./dist/*.whl
       - name: Store the distribution packages and signatures
-        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -112,8 +112,11 @@ jobs:
       actions: read  # for downloading artifacts
 
     steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
       - name: Download all the dists
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -121,14 +124,15 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
           TAG: ${{ needs.build.outputs.TAG }}
-        # Create a GitHub Release *draft*. The description can be changed later, as for now
-        # we don't define it through this workflow.
+        # Create a tag and a GitHub Release *draft*. The description is filled by the static
+        # template, we just insert the correct tag in the template.
         run: >-
+          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
           gh release create
           "$TAG"
           --repo '${{ github.repository }}'
-          --generate-notes
           --draft
+          --notes-file -
       - name: Upload artifact signatures to GitHub Release
         env:
           GITHUB_TOKEN: ${{ github.token }}

.github/workflows/test_official.yml

@@ -2,7 +2,7 @@ name: Bot API Tests
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - tests/**
   push:
     branches:
@@ -27,14 +27,13 @@ jobs:
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         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
+          python -W ignore -m pip install .[all] --group tests
       - name: Compare to official api
         run: |
           pytest -v tests/test_official/test_official.py --junit-xml=.test_report_official.xml

.github/workflows/type_completeness.yml

@@ -2,7 +2,7 @@ name: Check Type Completeness
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - pyproject.toml
       - .github/workflows/type_completeness.yml
   push:

.github/workflows/unit_tests.yml

@@ -2,11 +2,10 @@ name: Unit Tests
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - tests/**
       - .github/workflows/unit_tests.yml
       - pyproject.toml
-      - requirements-unit-tests.txt
   push:
     branches:
       - master
@@ -22,7 +21,7 @@ jobs:
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14.0-beta.3']
         os: [ubuntu-latest, windows-latest, macos-latest]
       fail-fast: False
     steps:
@@ -30,18 +29,14 @@ jobs:
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         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 -U pytest-cov
-          python -W ignore -m pip install .
-          python -W ignore -m pip install -r requirements-unit-tests.txt
-          python -W ignore -m pip install pytest-xdist
+          python -W ignore -m pip install . --group tests
 
       - name: Test with pytest
         # We run 4 different suites here
@@ -63,11 +58,10 @@ jobs:
           TO_TEST="test_no_passport.py or test_datetime.py or test_defaults.py or test_jobqueue.py or test_applicationbuilder.py or test_ratelimiter.py or test_updater.py or test_callbackdatacache.py or test_request.py"
           pytest -v --cov -k "${TO_TEST}" --junit-xml=.test_report_no_optionals_junit.xml
           opt_dep_status=$?
-
+          
           # Test the rest
           export TEST_WITH_OPT_DEPS='true'
-          # need to manually install pytz here, because it's no longer in the optional reqs
-          pip install .[all] pytz
+          pip install .[all]
           # `-n auto --dist worksteal` uses pytest-xdist to run tests on multiple CPU
           # workers. Increasing number of workers has little effect on test duration, but it seems
           # to increase flakyness.
@@ -92,14 +86,14 @@ jobs:
             .test_report_optionals_junit.xml
 
       - name: Submit coverage
-        uses: codecov/codecov-action@1e68e06f1dbfde0e4cefc87efeba9e4643565303  # v5.1.2
+        uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24  # v5.4.3
         with:
           env_vars: OS,PYTHON
           name: ${{ matrix.os }}-${{ matrix.python-version }}
           fail_ci_if_error: true
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Upload test results to Codecov
-        uses: codecov/test-results-action@4e79e65778be1cecd5df25e14af1eafb6df80ea9 # v1.0.2
+        uses: codecov/test-results-action@47f89e9acb64b76debcd5ea40642d25a4adced9f # v1.1.1
         if: ${{ !cancelled() }}
         with:
           files: .test_report_no_optionals_junit.xml,.test_report_optionals_junit.xml

.gitignore

@@ -93,6 +93,8 @@ telegram.jpg
 
 # virtual env
 venv*
+pyvenv.cfg
+Scripts/
 
 # environment manager:
 .mise.toml

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ ci:
 
 repos:
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.8.6'
+    rev: 'v0.12.2'
     hooks:
     -   id: ruff
         name: ruff
@@ -18,18 +18,18 @@ repos:
           - cachetools>=5.3.3,<5.5.0
           - aiolimiter~=1.1,<1.3
 -   repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.10.0
+    rev: 25.1.0
     hooks:
     -   id: black
         args:
         - --diff
         - --check
 -   repo: https://github.com/PyCQA/flake8
-    rev: 7.1.1
+    rev: 7.3.0
     hooks:
     -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v3.3.3
+    rev: v3.3.7
     hooks:
     -   id: pylint
         files: ^(?!(tests|docs)).*\.py$
@@ -41,7 +41,7 @@ repos:
           - aiolimiter~=1.1,<1.3
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.14.1
+    rev: v1.16.1
     hooks:
     -   id: mypy
         name: mypy-ptb
@@ -68,13 +68,13 @@ repos:
         - cachetools>=5.3.3,<5.5.0
         - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.19.1
+    rev: v3.20.0
     hooks:
     -   id: pyupgrade
         args:
           - --py39-plus
 -   repo: https://github.com/pycqa/isort
-    rev: 5.13.2
+    rev: 6.0.1
     hooks:
     -   id: isort
         name: isort

.readthedocs.yml

@@ -18,13 +18,16 @@ python:
   install:
     - method: pip
       path: .
-    - requirements: docs/requirements-docs.txt
 
 build:
   os: ubuntu-22.04
   tools:
     python: "3"  # latest stable cpython version
   jobs:
+    install:
+      - pip install -U pip
+      - pip install .[all] --group 'all'  # install all the dependency groups
+
     post_build:
       # Based on https://github.com/readthedocs/readthedocs.org/issues/3242#issuecomment-1410321534
       # This provides a HTML zip file for download, with the same structure as the hosted website

AUTHORS.rst

@@ -7,10 +7,8 @@ The current development team includes
 
 - `Hinrich Mahler <https://github.com/Bibo-Joshi>`_ (maintainer)
 - `Poolitzer <https://github.com/Poolitzer>`_ (community liaison)
-- `Shivam <https://github.com/Starry69>`_
 - `Harshil <https://github.com/harshil21>`_
-- `Dmitry Kolomatskiy <https://github.com/lemontree210>`_
-- `Aditya <https://github.com/clot27>`_
+- `Abdelrahman <https://github.com/aelkheir>`_
 
 Emeritus maintainers include
 `Jannes Höke <https://github.com/jh0ker>`_ (`@jh0ker <https://t.me/jh0ker>`_ on Telegram),
@@ -21,7 +19,7 @@ Contributors
 
 The following wonderful people contributed directly or indirectly to this project:
 
-- `Abdelrahman <https://github.com/aelkheir>`_
+- `Aditya <https://github.com/clot27>`_
 - `Abshar <https://github.com/abxhr>`_
 - `Abubakar Alaya <https://github.com/Ecode2>`_
 - `Alateas <https://github.com/alateas>`_
@@ -42,6 +40,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `daimajia <https://github.com/daimajia>`_
 - `Daniel Reed <https://github.com/nmlorg>`_
 - `D David Livingston <https://github.com/daviddl9>`_
+- `Dmitry Kolomatskiy <https://github.com/lemontree210>`_
 - `DonalDuck004 <https://github.com/DonalDuck004>`_
 - `Eana Hufwe <https://github.com/blueset>`_
 - `Ehsan Online <https://github.com/ehsanonline>`_
@@ -81,6 +80,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Kirill Vasin <https://github.com/vasinkd>`_
 - `Kjwon15 <https://github.com/kjwon15>`_
 - `Li-aung Yip <https://github.com/LiaungYip>`_
+- `locobott <https://github.com/locobott>`_
 - `Loo Zheng Yuan <https://github.com/loozhengyuan>`_
 - `LRezende <https://github.com/lrezende>`_
 - `Luca Bellanti <https://github.com/Trifase>`_
@@ -110,6 +110,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Patrick Hofmann <https://github.com/PH89>`_
 - `Paul Larsen <https://github.com/PaulSonOfLars>`_
 - `Pawan <https://github.com/pawanrai9999>`_
+- `Philipp Isachenko <https://github.com/Aweryc>`_
 - `Pieter Schutz <https://github.com/eldinnie>`_
 - `Piraty <https://github.com/piraty>`_
 - `Poolitzer <https://github.com/Poolitzer>`_
@@ -122,6 +123,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Sam Mosleh <https://github.com/sam-mosleh>`_
 - `Sascha <https://github.com/saschalalala>`_
 - `Shelomentsev D <https://github.com/shelomentsevd>`_
+- `Shivam <https://github.com/Starry69>`_
 - `Shivam Saini <https://github.com/shivamsn97>`_
 - `Siloé Garcez <https://github.com/roast-lord>`_
 - `Simon Schürrle <https://github.com/SitiSchu>`_

README.rst

@@ -11,7 +11,7 @@
    :target: https://pypi.org/project/python-telegram-bot/
    :alt: Supported Python versions
 
-.. image:: https://img.shields.io/badge/Bot%20API-8.3-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-9.1-blue?logo=telegram
    :target: https://core.telegram.org/bots/api-changelog
    :alt: Supported Bot API version
 
@@ -19,7 +19,7 @@
    :target: https://pypistats.org/packages/python-telegram-bot
    :alt: PyPi Package Monthly Download
 
-.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
+.. image:: https://app.readthedocs.org/projects/python-telegram-bot/badge/?version=stable
    :target: https://docs.python-telegram-bot.org/en/stable/
    :alt: Documentation Status
 
@@ -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.3** are natively supported by this library.
+All types and methods of the Telegram Bot API **9.1** are natively supported by this library.
 In addition, Bot API functionality not yet natively included can still be used as described `in our wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Forward-Compatibility>`_.
 
 Notable Features
@@ -114,6 +114,8 @@ You can also install ``python-telegram-bot`` from source, though this is usually
     $ pip install build
     $ python -m build
 
+You can also use your favored package manager (such as ``uv``, ``hatch``, ``poetry``, etc.) instead of ``pip``.
+
 Verifying Releases
 ~~~~~~~~~~~~~~~~~~
 
@@ -139,7 +141,7 @@ As these features are *optional*, the corresponding 3rd party dependencies are n
 Instead, they are listed as optional dependencies.
 This allows to avoid unnecessary dependency conflicts for users who don't need the optional features.
 
-The only required dependency is `httpx ~= 0.27 <https://www.python-httpx.org>`_ for
+The only required dependency is `httpx >=0.27,<0.29 <https://www.python-httpx.org>`_ for
 ``telegram.request.HTTPXRequest``, the default networking backend.
 
 ``python-telegram-bot`` is most useful when used along with additional libraries.
@@ -157,7 +159,7 @@ PTB can be installed with optional dependencies:
 * ``pip install "python-telegram-bot[http2]"`` installs `httpx[http2] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to use HTTP/2.
 * ``pip install "python-telegram-bot[rate-limiter]"`` installs `aiolimiter~=1.1,<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[callback-data]"`` installs the `cachetools>=5.3.3,<6.2.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,<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]"``.

changes/22.0_2025-03-15/4671.7B3boYRvHdGzsrZgkpKp7B.toml

@@ -0,0 +1,19 @@
+breaking = """This release removes all functionality that was deprecated in v20.x. This is in line with our :ref:`stability policy <stability-policy>`.
+This includes the following changes:
+
+- Removed ``filters.CHAT`` (all messages have an associated chat) and ``filters.StatusUpdate.USER_SHARED`` (use ``filters.StatusUpdate.USERS_SHARED`` instead).
+- Removed ``Defaults.disable_web_page_preview`` and ``Defaults.quote``. Use ``Defaults.link_preview_options`` and ``Defaults.do_quote`` instead.
+- Removed ``ApplicationBuilder.(get_updates_)proxy_url`` and ``HTTPXRequest.proxy_url``. Use ``ApplicationBuilder.(get_updates_)proxy`` and ``HTTPXRequest.proxy`` instead.
+- Removed the ``*_timeout`` arguments of ``Application.run_polling`` and ``Updater.start_webhook``. Instead, specify the values via ``ApplicationBuilder.get_updates_*_timeout``.
+- Removed ``constants.InlineQueryLimit.MIN_SWITCH_PM_TEXT_LENGTH``. Use ``constants.InlineQueryResultsButtonLimit.MAX_START_PARAMETER_LENGTH`` instead.
+- Removed the argument ``quote`` of ``Message.reply_*``. Use ``do_quote`` instead.
+- Removed the superfluous ``EncryptedPassportElement.credentials`` without replacement.
+- Changed attribute value of ``PassportFile.file_date`` from :obj:`int` to :class:`datetime.datetime`. Make sure to adjust your code accordingly.
+- Changed the attribute value of ``PassportElementErrors.file_hashes`` from :obj:`list` to :obj:`tuple`. Make sure to adjust your code accordingly.
+- Make ``BaseRequest.read_timeout`` an abstract property. If you subclass ``BaseRequest``, you need to implement this property.
+- The default value for ``write_timeout`` now defaults to ``DEFAULT_NONE`` also for bot methods that send media. Previously, it was ``20``. If you subclass ``BaseRequest``, make sure to use your desired write timeout if ``RequestData.multipart_data`` is set.
+"""
+[[pull_requests]]
+uid = "4671"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4659"]

changes/22.0_2025-03-15/4672.G9szuJ7pRafycByfem2DrT.toml

@@ -0,0 +1,5 @@
+documentation = "Add `chango <https://chango.readthedocs.io/stable/>`_ As Changelog Management Tool"
+[[pull_requests]]
+uid = "4672"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4321"]

changes/22.0_2025-03-15/4697.GzyGCEgj74G6bTEDbuFjUU.toml

@@ -0,0 +1,5 @@
+internal = "Bump github/codeql-action from 3.28.8 to 3.28.10"
+[[pull_requests]]
+uid = "4697"
+author_uid = "dependabot"
+closes_threads = []

changes/22.0_2025-03-15/4698.Fkzr3oU2qcFmFX28xfoja5.toml

@@ -0,0 +1,5 @@
+internal = "Bump srvaroa/labeler from 1.12.0 to 1.13.0"
+[[pull_requests]]
+uid = "4698"
+author_uid = "dependabot"
+closes_threads = []

changes/22.0_2025-03-15/4699.LYAYfKXX7C7wqT54kRPnVy.toml

@@ -0,0 +1,5 @@
+internal = "Bump astral-sh/setup-uv from 5.2.2 to 5.3.1"
+[[pull_requests]]
+uid = "4699"
+author_uid = "dependabot"
+closes_threads = []

changes/22.0_2025-03-15/4700.nm6R6YTnkmCo5evbykz4kz.toml

@@ -0,0 +1,5 @@
+internal = "Bump Bibo-Joshi/chango from 0.3.1 to 0.3.2"
+[[pull_requests]]
+uid = "4700"
+author_uid = "dependabot"
+closes_threads = []

changes/22.0_2025-03-15/4701.ah8Wi4SWc22EbgBc4KQeqH.toml

@@ -0,0 +1,5 @@
+internal = "Bump pypa/gh-action-pypi-publish from 1.12.3 to 1.12.4"
+[[pull_requests]]
+uid = "4701"
+author_uid = "dependabot"
+closes_threads = []

changes/22.0_2025-03-15/4709.dbwPVaU8vSacVkMLhiMjyJ.toml

@@ -0,0 +1,5 @@
+internal = "Bump pytest from 8.3.4 to 8.3.5"
+[[pull_requests]]
+uid = "4709"
+author_uid = "dependabot"
+closes_threads = []

changes/22.0_2025-03-15/4710.CSNixpvxJdLFaM6xSQ39Zf.toml

@@ -0,0 +1,5 @@
+internal = "Bump sphinx from 8.1.3 to 8.2.3"
+[[pull_requests]]
+uid = "4710"
+author_uid = "dependabot"
+closes_threads = []

changes/22.0_2025-03-15/4712.8ckkAPAXGzedityWEyv363.toml

@@ -0,0 +1,5 @@
+internal = "Bump Bibo-Joshi/chango from 0.3.2 to 0.4.0"
+[[pull_requests]]
+uid = "4712"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.0_2025-03-15/4719.d4xMztC8JjrbVgEscxvMWX.toml

@@ -0,0 +1,5 @@
+internal = "Bump Version to v22.0"
+[[pull_requests]]
+uid = "4719"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.1_2025-05-15/4692.dVZs28GuwTFnNJdWkvPbNv.toml

@@ -0,0 +1,5 @@
+breaking = "Drop backward compatibility for ``user_id`` in ``send_gift`` by updating the order of parameters. Please adapt your code accordingly or use keyword arguments."
+[[pull_requests]]
+uid = "4692"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.1_2025-05-15/4730.GsSUQSXzV8TF2Wav4CXRdd.toml

@@ -0,0 +1,9 @@
+documentation = "Documentation Improvements. Among others, add missing ``Returns`` field in ``User.get_profile_photos``"
+[[pull_requests]]
+uid = "4730"
+author_uid = "Bibo-Joshi"
+closes_threads = []
+[[pull_requests]]
+uid = "4740"
+author_uid = "aelkheir"
+closes_threads = []

changes/22.1_2025-05-15/4733.BRLwsEuh76974FPJRuiBjf.toml

@@ -0,0 +1,5 @@
+bugfixes = "Ensure execution of ``Bot.shutdown()`` even if ``Bot.get_me()`` fails in ``Bot.initialize()``"
+[[pull_requests]]
+uid = "4733"
+author_uid = "Poolitzer"
+closes_threads = []

changes/22.1_2025-05-15/4741.nVLBrFX4p8jTCBjMRqaYoQ.toml

@@ -0,0 +1,5 @@
+internal = "Bump codecov/test-results-action from 1.0.2 to 1.1.0"
+[[pull_requests]]
+uid = "4741"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4742.oEA6MjYXMafdbu2akWT5tC.toml

@@ -0,0 +1,5 @@
+internal = "Bump actions/setup-python from 5.4.0 to 5.5.0"
+[[pull_requests]]
+uid = "4742"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4743.SpMm4vvAMjEreykTcGwzcF.toml

@@ -0,0 +1,5 @@
+internal = "Bump github/codeql-action from 3.28.10 to 3.28.13"
+[[pull_requests]]
+uid = "4743"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4744.a4tsF64kZPA2noP7HtTzTX.toml

@@ -0,0 +1,5 @@
+internal = "Bump astral-sh/setup-uv from 5.3.1 to 5.4.1"
+[[pull_requests]]
+uid = "4744"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4745.emNmhxtvtTP9uLNQxpcVSj.toml

@@ -0,0 +1,5 @@
+internal = "Bump actions/download-artifact from 4.1.8 to 4.2.1"
+[[pull_requests]]
+uid = "4745"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4746.gWnX3BCxbvujQ8B2QejtTK.toml

@@ -0,0 +1,5 @@
+internal = "Reenable ``test_official`` Blocked by Debug Remnant"
+[[pull_requests]]
+uid = "4746"
+author_uid = "aelkheir"
+closes_threads = []

changes/22.1_2025-05-15/4747.MLmApvpGdwN7J24j7fXsDU.toml

@@ -0,0 +1,5 @@
+documentation = "Update ``AUTHORS.rst``, Adding `@aelkheir <https://github.com/aelkheir>`_ to Active Development Team"
+[[pull_requests]]
+uid = "4747"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.1_2025-05-15/4748.j3cKusZZKqTLbc542K4sqJ.toml

@@ -0,0 +1,5 @@
+internal = "Bump `pre-commit` Hooks to Latest Versions"
+[[pull_requests]]
+uid = "4748"
+author_uid = "pre-commit-ci"
+closes_threads = []

changes/22.1_2025-05-15/4756.JT5nmUmGRG6qDEh5ScMn5f.toml

@@ -0,0 +1,51 @@
+features = "Full Support for Bot API 9.0"
+deprecations = """This release comes with several deprecations, in line with our :ref:`stability policy <stability-policy>`.
+This includes the following:
+
+- Deprecated ``telegram.constants.StarTransactionsLimit.NANOSTAR_MIN_AMOUNT`` and ``telegram.constants.StarTransactionsLimit.NANOSTAR_MAX_AMOUNT``. These members will be replaced by ``telegram.constants.NanostarLimit.MIN_AMOUNT`` and ``telegram.constants.NanostarLimit.MAX_AMOUNT``.
+- Deprecated the class ``telegram.constants.StarTransactions``. Its only member ``telegram.constants.StarTransactions.NANOSTAR_VALUE`` will be replaced by ``telegram.constants.Nanostar.VALUE``.
+- Bot API 9.0 deprecated ``BusinessConnection.can_reply`` in favor of ``BusinessConnection.rights``
+- Bot API 9.0 deprecated ``ChatFullInfo.can_send_gift`` in favor of ``ChatFullInfo.accepted_gift_types``.
+- Bot API 9.0 introduced these new required fields to existing classes:
+  - ``TransactionPartnerUser.transaction_type``
+  - ``ChatFullInfo.accepted_gift_types``
+
+  Passing these values as positional arguments is deprecated. We encourage you to use keyword arguments instead, as the the signature will be updated in a future release.
+
+These deprecations are backward compatible, but we strongly recommend to update your code to use the new members.
+"""
+[[pull_requests]]
+uid = "4756"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4754"]
+[[pull_requests]]
+uid = "4757"
+author_uid = "Bibo-Joshi"
+closes_threads = []
+[[pull_requests]]
+uid = "4759"
+author_uid = "Bibo-Joshi"
+closes_threads = []
+[[pull_requests]]
+uid = "4763"
+author_uid = "aelkheir"
+closes_threads = []
+[[pull_requests]]
+uid = "4766"
+author_uid = "Bibo-Joshi"
+[[pull_requests]]
+uid = "4769"
+author_uid = "aelkheir"
+closes_threads = []
+[[pull_requests]]
+uid = "4773"
+author_uid = "aelkheir"
+closes_threads = []
+[[pull_requests]]
+uid = "4781"
+author_uid = "aelkheir"
+closes_threads = []
+[[pull_requests]]
+uid = "4782"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.1_2025-05-15/4758.dSyCdBJWEJroH2GynR2VaJ.toml

@@ -0,0 +1,5 @@
+internal = "Fine-tune ``chango`` and release workflows"
+[[pull_requests]]
+uid = "4758"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4720"]

changes/22.1_2025-05-15/4761.mmsngFA6b4ccdEzEpFTZS3.toml

@@ -0,0 +1,6 @@
+bugfixes = "Fix Handling of ``Defaults`` for ``InputPaidMedia``"
+
+[[pull_requests]]
+uid = "4761"
+author_uid = "ngrogolev"
+closes_threads = ["4753"]

changes/22.1_2025-05-15/4762.PbcJGM8KPBMbKri3fdHKjh.toml

@@ -0,0 +1,5 @@
+documentation = "Clarify Documentation and Type Hints of ``InputMedia`` and ``InputPaidMedia``. Note that the ``media`` parameter accepts only objects of type ``str`` and ``InputFile``. The respective subclasses of ``Input(Paid)Media`` each accept a broader range of input type for the ``media`` parameter."
+[[pull_requests]]
+uid = "4762"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.1_2025-05-15/4775.kkLon84t7Vy5REKRe9LwPH.toml

@@ -0,0 +1,5 @@
+internal = "Bump codecov/codecov-action from 5.1.2 to 5.4.2"
+[[pull_requests]]
+uid = "4775"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4776.g83DxRk4WVWCC8rCd6ocFC.toml

@@ -0,0 +1,5 @@
+internal = "Bump actions/upload-artifact from 4.5.0 to 4.6.2"
+[[pull_requests]]
+uid = "4776"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4777.Lhgz8xFtQjgrKM2KvNfxwD.toml

@@ -0,0 +1,5 @@
+internal = "Bump stefanzweifel/git-auto-commit-action from 5.1.0 to 5.2.0"
+[[pull_requests]]
+uid = "4777"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4778.CeUSPNLbGGsqP2Vo4xKkdp.toml

@@ -0,0 +1,5 @@
+internal = "Bump github/codeql-action from 3.28.13 to 3.28.16"
+[[pull_requests]]
+uid = "4778"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4779.UqcbJVKYxwTtrBEGDgb3VS.toml

@@ -0,0 +1,5 @@
+internal = "Bump actions/download-artifact from 4.2.1 to 4.3.0"
+[[pull_requests]]
+uid = "4779"
+author_uid = "dependabot"
+closes_threads = []

changes/22.1_2025-05-15/4791.QycEvQbiaiJKraKDhAfFWM.toml

@@ -0,0 +1,5 @@
+other = "Bump Version to v22.1"
+[[pull_requests]]
+uid = "4791"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.2_2025-06-29/4750.jJBu7iAgZa96hdqcpHK96W.toml

@@ -0,0 +1,36 @@
+features = "Use `timedelta` to represent time periods in class arguments and attributes"
+deprecations = """In this release, we're migrating attributes of Telegram objects that represent durations/time periods from having :obj:`int` type to Python's native :class:`datetime.timedelta`. This change is opt-in for now to allow for a smooth transition phase. It will become opt-out in future releases.
+
+Set ``PTB_TIMEDELTA=true`` or ``PTB_TIMEDELTA=1`` as an environment variable to make these attributes return :obj:`datetime.timedelta` objects instead of integers. Support for :obj:`int` values is deprecated and will be removed in a future major version.
+
+Affected Attributes:
+- :attr:`telegram.ChatFullInfo.slow_mode_delay` and :attr:`telegram.ChatFullInfo.message_auto_delete_time`
+- :attr:`telegram.Animation.duration`
+- :attr:`telegram.Audio.duration`
+- :attr:`telegram.Video.duration` and :attr:`telegram.Video.start_timestamp`
+- :attr:`telegram.VideoNote.duration`
+- :attr:`telegram.Voice.duration`
+- :attr:`telegram.PaidMediaPreview.duration`
+- :attr:`telegram.VideoChatEnded.duration`
+- :attr:`telegram.InputMediaVideo.duration`
+- :attr:`telegram.InputMediaAnimation.duration`
+- :attr:`telegram.InputMediaAudio.duration`
+- :attr:`telegram.InputPaidMediaVideo.duration`
+- :attr:`telegram.InlineQueryResultGif.gif_duration`
+- :attr:`telegram.InlineQueryResultMpeg4Gif.mpeg4_duration`
+- :attr:`telegram.InlineQueryResultVideo.video_duration`
+- :attr:`telegram.InlineQueryResultAudio.audio_duration`
+- :attr:`telegram.InlineQueryResultVoice.voice_duration`
+- :attr:`telegram.InlineQueryResultLocation.live_period`
+- :attr:`telegram.Poll.open_period`
+- :attr:`telegram.Location.live_period`
+- :attr:`telegram.MessageAutoDeleteTimerChanged.message_auto_delete_time`
+- :attr:`telegram.ChatInviteLink.subscription_period`
+- :attr:`telegram.InputLocationMessageContent.live_period`
+- :attr:`telegram.error.RetryAfter.retry_after`
+"""
+internal = "Modify `test_official` to handle time periods as timedelta automatically."
+[[pull_requests]]
+uid = "4750"
+author_uid = "aelkheir"
+closes_threads = ["4575"]

changes/22.2_2025-06-29/4792.YsK6LmbEhZv6y3dvhHbXD7.toml

@@ -0,0 +1,5 @@
+internal = "Fix Bug in Automated Channel Announcement"
+[[pull_requests]]
+uid = "4792"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.2_2025-06-29/4793.mDR5p3mrSmPFQkvWFGWBmD.toml

@@ -0,0 +1,5 @@
+internal = "Fix a Failing Test Case"
+[[pull_requests]]
+uid = "4793"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.2_2025-06-29/4798.g7G3jRf2ns4ath9LRFEcit.toml

@@ -0,0 +1,5 @@
+internal = "Rework Repository to `src` Layout"
+[[pull_requests]]
+uid = "4798"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4797"]

changes/22.2_2025-06-29/4800.2Z9Q8uvzdU2TqMJ9biBLam.toml

@@ -0,0 +1,5 @@
+dependencies = "Implement PEP 735 Dependency Groups for Development Dependencies"
+[[pull_requests]]
+uid = "4800"
+author_uid = "harshil21"
+closes_threads = ["4795"]

changes/22.2_2025-06-29/4801.feKaYKKZTZq2KBjhyxVVAM.toml

@@ -0,0 +1,5 @@
+dependencies = "Update cachetools requirement from <5.6.0,>=5.3.3 to >=5.3.3,<6.1.0"
+[[pull_requests]]
+uid = "4801"
+author_uid = "dependabot"
+closes_threads = []

changes/22.2_2025-06-29/4802.RMLufX4UazobYg5aZojyoD.toml

@@ -0,0 +1,14 @@
+bugfixes = """
+Fixed a bug where calling ``Application.remove/add_handler`` during update handling can cause a ``RuntimeError`` in ``Application.process_update``.
+
+.. hint::
+    Calling ``Application.add/remove_handler`` now has no influence on calls to :meth:`process_update` that are
+    already in progress. The same holds for ``Application.add/remove_error_handler`` and ``Application.process_error``, respectively.
+
+    .. warning::
+        This behavior should currently be considered an implementation detail and not as guaranteed behavior.
+"""
+[[pull_requests]]
+uid = "4802"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4803"]

changes/22.2_2025-06-29/4810.KyRnffWk3ARyQFNcF88Uh3.toml

@@ -0,0 +1,20 @@
+documentation = """Documentation Improvements. Among other things
+
+* mention alternative package managers in README and contribution guide
+* remove ``furo-sphinx-search``
+"""
+
+[[pull_requests]]
+uid = "4810"
+author_uid = "Bibo-Joshi"
+closes_threads = []
+
+[[pull_requests]]
+uid = "4824"
+author_uid = "Aweryc"
+closes_threads = ["4823"]
+
+[[pull_requests]]
+uid = "4826"
+author_uid = "harshil21"
+closes_threads = []

changes/22.2_2025-06-29/4811.TQgVr5Sa6uDFtWXdTS5wfw.toml

@@ -0,0 +1,5 @@
+internal = "Bump github/codeql-action from 3.28.16 to 3.28.18"
+[[pull_requests]]
+uid = "4811"
+author_uid = "dependabot"
+closes_threads = []

changes/22.2_2025-06-29/4812.i4aqsTfCkdEs8uYNYS59si.toml

@@ -0,0 +1,5 @@
+internal = "Bump actions/setup-python from 5.5.0 to 5.6.0"
+[[pull_requests]]
+uid = "4812"
+author_uid = "dependabot"
+closes_threads = []

changes/22.2_2025-06-29/4813.cnbzL2eSRzj3i9NcUMFyFo.toml

@@ -0,0 +1,5 @@
+internal = "Bump dependabot/fetch-metadata from 2.3.0 to 2.4.0"
+[[pull_requests]]
+uid = "4813"
+author_uid = "dependabot"
+closes_threads = []

changes/22.2_2025-06-29/4814.RMQVXTNywcpBQ3HkX2TuyA.toml

@@ -0,0 +1,5 @@
+internal = "Bump codecov/codecov-action from 5.4.2 to 5.4.3"
+[[pull_requests]]
+uid = "4814"
+author_uid = "dependabot"
+closes_threads = []

changes/22.2_2025-06-29/4815.9dLSFHFozQiAM7oCpX4NyL.toml

@@ -0,0 +1,5 @@
+internal = "Bump codecov/test-results-action from 1.1.0 to 1.1.1"
+[[pull_requests]]
+uid = "4815"
+author_uid = "dependabot"
+closes_threads = []

changes/22.2_2025-06-29/4816.hhYVDfdzUgoQoMNRKkCDjb.toml

@@ -0,0 +1,5 @@
+internal = "Fix Typo in `TelegramObject._get_attrs`"
+[[pull_requests]]
+uid = "4816"
+author_uid = "harshil21"
+closes_threads = []

changes/22.2_2025-06-29/4817.ZHx38jvj9zKRNZfQh9Xrpb.toml

@@ -0,0 +1,5 @@
+bugfixes = "Allow for pattern matching empty inline queries"
+[[pull_requests]]
+uid = "4817"
+author_uid = "locobott"
+closes_threads = []

changes/22.2_2025-06-29/4818.3VPDqqEWEhDCrTipFY8KKU.toml

@@ -0,0 +1,12 @@
+bugfixes = """
+Correctly parse parameter ``allow_sending_without_reply`` in ``Message.reply_*`` when used in combination with ``do_quote=True``.
+
+.. hint::
+
+   Using ``dict`` valued input for ``do_quote`` along with passing ``allow_sending_without_reply`` is not supported and will raise an error.
+"""
+
+[[pull_requests]]
+uid = "4818"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4807"]

changes/22.2_2025-06-29/4820.7bFkjLSeWKdNVhThPpVMAT.toml

@@ -0,0 +1,5 @@
+dependencies = "Bump ``httpx`` from ~=0.27 to >=0.27,<0.29"
+[[pull_requests]]
+uid = "4820"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4819"]

changes/22.2_2025-06-29/4822.DrW3tJ3KoB8kTmHtNnNEpQ.toml

@@ -0,0 +1,5 @@
+other = "Improve Informativeness of Network Errors Raised by ``BaseRequest.post/retrieve``"
+
+[[pull_requests]]
+uid = "4822"
+author_uid = "Bibo-Joshi"

changes/22.2_2025-06-29/4825.R7wiTzvN37KAV656s9kfnC.toml

@@ -0,0 +1,5 @@
+other = "Add Python 3.14 Beta To Test Matrix. *Python 3.14 is not officially supported by PTB yet!*"
+[[pull_requests]]
+uid = "4825"
+author_uid = "harshil21"
+closes_threads = []

changes/22.2_2025-06-29/4830.EZzGEAk7DiFuedKPoQMMvd.toml

@@ -0,0 +1,5 @@
+dependencies = "Update ``cachetools`` requirement from <6.1.0,>=5.3.3 to >=5.3.3,<6.2.0"
+
+[[pull_requests]]
+uid = "4830"
+author_uid = "dependabot"

changes/22.2_2025-06-29/4834.oBWsiGWNMuoSXvJNom6N6A.toml

@@ -0,0 +1,5 @@
+other = "Bump Version to v22.2"
+[[pull_requests]]
+uid = "4834"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.3_2025-07-20/4837.cVTsY7pxfQqgVXfFW9hgZK.toml

@@ -0,0 +1,6 @@
+internal = "Update API Token for Local Testing Bot"
+
+[[pull_requests]]
+uid = "4837"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/22.3_2025-07-20/4839.gExNhF7C6kR5VrBg6cBaar.toml

@@ -0,0 +1,5 @@
+documentation = "Documentation Improvements. Among others, fix links to source code."
+[[pull_requests]]
+uid = "4839"
+author_uid = "aelkheir"
+closes_threads = ["4838"]

changes/22.3_2025-07-20/4840.jz9uGugc5DUd8x8pQHPyzg.toml

@@ -0,0 +1,5 @@
+internal = "Bump stefanzweifel/git-auto-commit-action from 5.2.0 to 6.0.1"
+[[pull_requests]]
+uid = "4840"
+author_uid = "dependabot"
+closes_threads = []

changes/22.3_2025-07-20/4841.HHVCCXXZbYAaaQVmKHCJm2.toml

@@ -0,0 +1,5 @@
+internal = "Bump github/codeql-action from 3.28.18 to 3.29.2"
+[[pull_requests]]
+uid = "4841"
+author_uid = "dependabot"
+closes_threads = []

changes/22.3_2025-07-20/4842.PSW9ZbxENhwfRhbSfemCwE.toml

@@ -0,0 +1,5 @@
+internal = "Bump astral-sh/setup-uv from 5.4.1 to 6.3.1"
+[[pull_requests]]
+uid = "4842"
+author_uid = "dependabot"
+closes_threads = []

changes/22.3_2025-07-20/4843.f5aZ5Vpxevw8fEEudawU5u.toml

@@ -0,0 +1,5 @@
+internal = "Bump sigstore/gh-action-sigstore-python from 3.0.0 to 3.0.1"
+[[pull_requests]]
+uid = "4843"
+author_uid = "dependabot"
+closes_threads = []

changes/22.3_2025-07-20/4847.8ujbbBbaZ2VTEdRLeqirSZ.toml

@@ -0,0 +1,18 @@
+highlights = "Full Support for Bot API 9.1"
+
+features = """
+New filters based on Bot API 9.1:
+
+* ``filters.StatusUpdate.DIRECT_MESSAGE_PRICE_CHANGED`` for ``Message.direct_message_price_changed``
+* ``filters.StatusUpdate.CHECKLIST_TASKS_ADDED`` for ``Message.checklist_tasks_added``
+* ``filters.StatusUpdate.CHECKLIST_TASKS_DONE`` for ``Message.checklist_tasks_done``
+* ``filters.CHECKLIST`` for ``Message.checklist``
+"""
+
+pull_requests = [
+  { uid = "4847", author_uid = "Bibo-Joshi", closes_threads = ["4845"] },
+  { uid = "4848", author_uid = "Bibo-Joshi" },
+  { uid = "4849", author_uid = "harshil21" },
+  { uid = "4851", author_uid = "harshil21" },
+  { uid = "4857", author_uid = "aelkheir" },
+]

changes/22.3_2025-07-20/4852.mz3RDjX636ZdGoR456C6v9.toml

@@ -0,0 +1,11 @@
+breaking = """Remove Functionality Deprecated in API 9.0
+
+* Remove deprecated argument and attribute ``BusinessConnection.can_reply``.
+* Remove deprecated argument and attribute ``ChatFullInfo.can_send_gift``
+* Remove deprecated class ``constants.StarTransactions``. Please instead use :attr:`telegram.constants.Nanostar.VALUE`.
+* Remove deprecated attributes ``constants.StarTransactionsLimit.NANOSTAR_MIN_AMOUNT`` and ``constants.StarTransactionsLimit.NANOSTAR_MAX_AMOUNT``. Please instead use :attr:`telegram.constants.NanostarLimit.MIN_AMOUNT` and :attr:`telegram.constants.NanostarLimit.MAX_AMOUNT`.
+"""
+[[pull_requests]]
+uid = "4852"
+author_uid = "aelkheir"
+closes_threads = []

changes/22.3_2025-07-20/4855.8hCFRFMeMaRWpBEYaxrTMq.toml

@@ -0,0 +1,5 @@
+other= "Make Gender Input Case-Insensitive in ``conversationbot.py``"
+[[pull_requests]]
+uid = "4855"
+author_uid = "fengxiaohu"
+closes_threads = ["4846"]

changes/22.3_2025-07-20/4858.ajt46xDsbfzFqcghJ2rP6g.toml

@@ -0,0 +1,5 @@
+internal = "Bump `pre-commit` Hooks to Latest Versions"
+[[pull_requests]]
+uid = "4858"
+author_uid = "pre-commit-ci"
+closes_threads = []

changes/22.3_2025-07-20/4870.QeVo4BE5TNouLRJjCFbRMo.toml

@@ -0,0 +1,5 @@
+other = "Bump Version to v22.3"
+[[pull_requests]]
+uid = "4870"
+author_uid = "Bibo-Joshi"
+closes_threads = []

changes/LEGACY.rst

@@ -1,8 +1,14 @@
-.. _ptb-changelog:
+Version 21.11.1
+===============
 
-=========
-Changelog
-=========
+*Released 2025-03-01*
+
+This is the technical changelog for version 21.11. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Documentation Improvements
+--------------------------
+
+- Fix ReadTheDocs Build (:pr:`4695`)
 
 Version 21.11
 =============

changes/config.py

@@ -0,0 +1,105 @@
+# noqa: INP001
+# pylint: disable=import-error
+"""Configuration for the chango changelog tool"""
+
+import re
+from collections.abc import Collection
+from pathlib import Path
+from typing import Optional
+
+from chango import Version
+from chango.concrete import DirectoryChanGo, DirectoryVersionScanner, HeaderVersionHistory
+from chango.concrete.sections import GitHubSectionChangeNote, Section, SectionVersionNote
+
+version_scanner = DirectoryVersionScanner(base_directory=".", unreleased_directory="unreleased")
+
+
+class ChangoSectionChangeNote(
+    GitHubSectionChangeNote.with_sections(  # type: ignore[misc]
+        [
+            Section(uid="highlights", title="Highlights", sort_order=0),
+            Section(uid="breaking", title="Breaking Changes", sort_order=1),
+            Section(uid="security", title="Security Changes", sort_order=2),
+            Section(uid="deprecations", title="Deprecations", sort_order=3),
+            Section(uid="features", title="New Features", sort_order=4),
+            Section(uid="bugfixes", title="Bug Fixes", sort_order=5),
+            Section(uid="dependencies", title="Dependencies", sort_order=6),
+            Section(uid="other", title="Other Changes", sort_order=7),
+            Section(uid="documentation", title="Documentation", sort_order=8),
+            Section(uid="internal", title="Internal Changes", sort_order=9),
+        ]
+    )
+):
+    """Custom change note type for PTB. Mainly overrides get_sections to map labels to sections"""
+
+    OWNER = "python-telegram-bot"
+    REPOSITORY = "python-telegram-bot"
+
+    @classmethod
+    def get_sections(
+        cls,
+        labels: Collection[str],
+        issue_types: Optional[Collection[str]],
+    ) -> set[str]:
+        """Override get_sections to have customized auto-detection of relevant sections based on
+        the pull request and linked issues. Certainly not perfect in all cases, but should be a
+        good start for most PRs.
+        """
+        combined_labels = set(labels) | (set(issue_types or []))
+
+        mapping = {
+            "🐛 bug": "bugfixes",
+            "💡 feature": "features",
+            "🧹 chore": "internal",
+            "⚙️ bot-api": "features",
+            "⚙️ documentation": "documentation",
+            "⚙️ tests": "internal",
+            "⚙️ ci-cd": "internal",
+            "⚙️ security": "security",
+            "⚙️ examples": "documentation",
+            "⚙️ type-hinting": "other",
+            "🛠 refactor": "internal",
+            "🛠 breaking": "breaking",
+            "⚙️ dependencies": "dependencies",
+            "🔗 github-actions": "internal",
+            "🛠 code-quality": "internal",
+        }
+
+        # we want to return *all* from the mapping that are in the combined_labels
+        # removing superfluous sections from the fragment is a tad easier than adding them
+        found = {section for label, section in mapping.items() if label in combined_labels}
+
+        # if we have not found any sections, we default to "other"
+        return found or {"other"}
+
+
+class CustomChango(DirectoryChanGo):
+    """Custom ChanGo class for overriding release"""
+
+    def release(self, version: Version) -> bool:
+        """replace "14.5" with version.uid except in the contrib guide
+        then call super
+        """
+        root = Path(__file__).parent.parent / "src"
+        python_files = root.rglob("*.py")
+        pattern = re.compile(r"NEXT\.VERSION")
+        excluded_paths = {root / "docs/source/contribute.rst"}
+        for file_path in python_files:
+            if str(file_path) in excluded_paths:
+                continue
+
+            content = file_path.read_text(encoding="utf-8")
+            modified = pattern.sub(version.uid, content)
+
+            if content != modified:
+                file_path.write_text(modified, encoding="utf-8")
+
+        return super().release(version)
+
+
+chango_instance = CustomChango(
+    change_note_type=ChangoSectionChangeNote,
+    version_note_type=SectionVersionNote,
+    version_history_type=HeaderVersionHistory,
+    scanner=version_scanner,
+)

docs/auxil/kwargs_insertion.py

@@ -47,29 +47,29 @@ keyword_args = [
     "",
 ]
 
-media_write_timeout_deprecation_methods = [
-    "send_photo",
+media_write_timeout_change_methods = [
+    "add_sticker_to_set",
+    "create_new_sticker_set",
+    "send_animation",
     "send_audio",
     "send_document",
+    "send_media_group",
+    "send_photo",
     "send_sticker",
     "send_video",
     "send_video_note",
-    "send_animation",
     "send_voice",
-    "send_media_group",
     "set_chat_photo",
     "upload_sticker_file",
-    "add_sticker_to_set",
-    "create_new_sticker_set",
 ]
-media_write_timeout_deprecation = [
+media_write_timeout_change = [
     "    write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
     "        :paramref:`telegram.request.BaseRequest.post.write_timeout`. By default, ``20`` "
     "        seconds are used as write timeout."
     "",
     "",
-    "       .. deprecated:: 20.7",
-    "           In future versions, the default value will be changed to "
+    "       .. versionchanged:: 22.0",
+    "           The default value changed to "
     "           :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
     "",
     "",

docs/auxil/sphinx_hooks.py

@@ -15,12 +15,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/].
-import collections.abc
 import contextlib
 import inspect
 import re
 import typing
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from sphinx.application import Sphinx
 
@@ -32,11 +32,15 @@ from docs.auxil.kwargs_insertion import (
     find_insert_pos_for_kwargs,
     get_updates_read_timeout_addition,
     keyword_args,
-    media_write_timeout_deprecation,
-    media_write_timeout_deprecation_methods,
+    media_write_timeout_change,
+    media_write_timeout_change_methods,
 )
 from docs.auxil.link_code import LINE_NUMBERS
 
+if TYPE_CHECKING:
+    import collections.abc
+
+
 ADMONITION_INSERTER = AdmonitionInserter()
 
 # Some base classes are implementation detail
@@ -51,6 +55,8 @@ PRIVATE_BASE_CLASSES = {
 }
 
 
+# Resolves to the parent directory of `telegram/`, depending on installation setup,
+# could either be `<absolute_path>/src` or `<absolute_path>/site-packages`
 FILE_ROOT = Path(inspect.getsourcefile(telegram)).parent.parent.resolve()
 
 
@@ -116,9 +122,9 @@ def autodoc_process_docstring(
 
             if (
                 "post.write_timeout`. Defaults to" in to_insert
-                and method_name in media_write_timeout_deprecation_methods
+                and method_name in media_write_timeout_change_methods
             ):
-                effective_insert: list[str] = media_write_timeout_deprecation
+                effective_insert: list[str] = media_write_timeout_change
             elif get_updates and to_insert.lstrip().startswith("read_timeout"):
                 effective_insert = [to_insert, *get_updates_read_timeout_addition]
             else:
@@ -128,7 +134,7 @@ def autodoc_process_docstring(
             insert_idx += len(effective_insert)
 
         ADMONITION_INSERTER.insert_admonitions(
-            obj=typing.cast(collections.abc.Callable, obj),
+            obj=typing.cast("collections.abc.Callable", obj),
             docstring_lines=lines,
         )
 
@@ -136,7 +142,7 @@ def autodoc_process_docstring(
     # (where applicable)
     if what == "class":
         ADMONITION_INSERTER.insert_admonitions(
-            obj=typing.cast(type, obj),  # since "what" == class, we know it's not just object
+            obj=typing.cast("type", obj),  # since "what" == class, we know it's not just object
             docstring_lines=lines,
         )
 
@@ -157,7 +163,7 @@ def autodoc_process_docstring(
     with contextlib.suppress(Exception):
         source_lines, start_line = inspect.getsourcelines(obj)
         end_line = start_line + len(source_lines)
-        file = Path(inspect.getsourcefile(obj)).relative_to(FILE_ROOT)
+        file = Path("src") / Path(inspect.getsourcefile(obj)).relative_to(FILE_ROOT)
         LINE_NUMBERS[name] = (file, start_line, end_line)
 
     # Since we don't document the `__init__`, we call this manually to have it available for

docs/requirements-docs.txt

@@ -1,9 +0,0 @@
-sphinx==8.1.3
-furo==2024.8.6
-furo-sphinx-search @ git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1
-sphinx-paramlinks==0.6.0
-sphinxcontrib-mermaid==1.0.0
-sphinx-copybutton==0.5.2
-sphinx-inline-tabs==2023.4.21
-# Temporary. See #4387
-sphinx-build-compatibility @ git+https://github.com/readthedocs/sphinx-build-compatibility.git@58aabc5f207c6c2421f23d3578adc0b14af57047

docs/source/changelog.rst

@@ -1 +1,9 @@
-.. include:: ../../CHANGES.rst
+.. _ptb-changelog:
+
+=========
+Changelog
+=========
+
+.. chango::
+
+.. include:: ../../changes/LEGACY.rst

docs/source/conf.py

@@ -8,6 +8,11 @@ from pathlib import Path
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 from sphinx.application import Sphinx
 
+if sys.version_info < (3, 12):
+    # Due to dependency on chango
+    raise RuntimeError("This documentation needs at least Python 3.12")
+
+
 sys.path.insert(0, str(Path("../..").resolve().absolute()))
 
 # -- General configuration ------------------------------------------------
@@ -36,6 +41,7 @@ needs_sphinx = "8.1.3"
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "chango.sphinx_ext",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
@@ -45,13 +51,15 @@ extensions = [
     "sphinx_copybutton",
     "sphinx_inline_tabs",
     "sphinxcontrib.mermaid",
-    "sphinx_search.extension",
 ]
 
 # Temporary. See #4387
 if os.environ.get("READTHEDOCS", "") == "True":
     extensions.append("sphinx_build_compatibility.extension")
 
+# Configuration for the chango sphinx directive
+chango_pyproject_toml_path = Path(__file__).parent.parent.parent
+
 # For shorter links to Wiki in docstrings
 extlinks = {
     "wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s"),
@@ -116,6 +124,8 @@ linkcheck_ignore = [
     # The doc-fixes branch may not always exist - doesn't matter, we only link to it from the
     # contributing guide
     re.escape("https://docs.python-telegram-bot.org/en/doc-fixes"),
+    # Apparently has some human-verification check and gives 403 in the sphinx build
+    re.escape("https://stackoverflow.com/questions/tagged/python-telegram-bot"),
 ]
 linkcheck_allowed_redirects = {
     # Redirects to the default version are okay

docs/source/examples.rst

@@ -61,7 +61,7 @@ for this one, too!
 :any:`examples.nestedconversationbot`
 -------------------------------------
 
-A even more complex example of a bot that uses the nested
+An even more complex example of a bot that uses the nested
 ``ConversationHandler``\ s. While it’s certainly not that complex that
 you couldn’t built it without nested ``ConversationHanldler``\ s, it
 gives a good impression on how to work with them. Of course, there is a

docs/source/inclusions/bot_methods.rst

@@ -161,8 +161,6 @@
       - Used for unpinning a message
     * - :meth:`~telegram.Bot.unpin_all_chat_messages`
       - Used for unpinning all pinned chat messages
-    * - :meth:`~telegram.Bot.get_business_connection`
-      - Used for getting information about the business account.
     * - :meth:`~telegram.Bot.get_user_profile_photos`
       - Used for obtaining user's profile pictures
     * - :meth:`~telegram.Bot.get_chat`
@@ -392,10 +390,70 @@
       - Used to generate an HTTP link for an invoice
     * - :meth:`~telegram.Bot.edit_user_star_subscription`
       - Used for editing a user's star subscription
+    * - :meth:`~telegram.Bot.get_my_star_balance`
+      - Used for obtaining the bot's Telegram Stars balance
     * - :meth:`~telegram.Bot.get_star_transactions`
       - Used for obtaining the bot's Telegram Stars transactions
     * - :meth:`~telegram.Bot.refund_star_payment`
       - Used for refunding a payment in Telegram Stars
+    * - :meth:`~telegram.Bot.gift_premium_subscription`
+      - Used for gifting Telegram Premium to another user.
+
+.. raw:: html
+
+   </details>
+   <br>
+
+.. raw:: html
+
+   <details>
+   <summary>Business Related Methods</summary>
+
+.. list-table::
+    :align: left
+    :widths: 1 4
+
+    * - :meth:`~telegram.Bot.get_business_connection`
+      - Used for getting information about the business account.
+    * - :meth:`~telegram.Bot.get_business_account_gifts`
+      - Used for getting gifts owned by the business account.
+    * - :meth:`~telegram.Bot.get_business_account_star_balance`
+      - Used for getting the amount of Stars owned by the business account.
+    * - :meth:`~telegram.Bot.read_business_message`
+      - Used for marking a message as read.
+    * - :meth:`~telegram.Bot.delete_story`
+      - Used for deleting business stories posted by the bot.
+    * - :meth:`~telegram.Bot.delete_business_messages`
+      - Used for deleting business messages.
+    * - :meth:`~telegram.Bot.remove_business_account_profile_photo`
+      - Used for removing the business accounts profile photo
+    * - :meth:`~telegram.Bot.set_business_account_name`
+      - Used for setting the business account name.
+    * - :meth:`~telegram.Bot.set_business_account_username`
+      - Used for setting the business account username.
+    * - :meth:`~telegram.Bot.set_business_account_bio`
+      - Used for setting the business account bio.
+    * - :meth:`~telegram.Bot.set_business_account_gift_settings`
+      - Used for setting the business account gift settings.
+    * - :meth:`~telegram.Bot.set_business_account_profile_photo`
+      - Used for setting the business accounts profile photo
+    * - :meth:`~telegram.Bot.post_story`
+      - Used for posting a story on behalf of business account.
+    * - :meth:`~telegram.Bot.edit_story`
+      - Used for editing business stories posted by the bot.
+    * - :meth:`~telegram.Bot.convert_gift_to_stars`
+      - Used for converting owned reqular gifts to stars.
+    * - :meth:`~telegram.Bot.upgrade_gift`
+      - Used for upgrading owned regular gifts to unique ones.
+    * - :meth:`~telegram.Bot.transfer_gift`
+      - Used for transferring owned unique gifts to another user.
+    * - :meth:`~telegram.Bot.transfer_business_account_stars`
+      - Used for transfering Stars from the business account balance to the bot's balance.
+    * - :meth:`~telegram.Bot.send_checklist`
+      - Used for sending a checklist on behalf of the business account.
+    * - :meth:`~telegram.Bot.edit_message_checklist`
+      - Used for editing a checklist on behalf of the business account.
+
 
 .. raw:: html
 

docs/source/stability_policy.rst

@@ -1,3 +1,5 @@
+.. _stability-policy:
+
 Stability Policy
 ================
 

docs/source/telegram.acceptedgifttypes.rst

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

docs/source/telegram.animation.rst

@@ -6,4 +6,4 @@ Animation
 .. autoclass:: telegram.Animation
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TelegramObject, object

docs/source/telegram.at-tree.rst

@@ -4,6 +4,7 @@ Available Types
 .. toctree::
     :titlesonly:
 
+    telegram.acceptedgifttypes
     telegram.animation
     telegram.audio
     telegram.birthdate
@@ -19,6 +20,7 @@ Available Types
     telegram.botdescription
     telegram.botname
     telegram.botshortdescription
+    telegram.businessbotrights
     telegram.businessconnection
     telegram.businessintro
     telegram.businesslocation
@@ -29,6 +31,10 @@ Available Types
     telegram.chat
     telegram.chatadministratorrights
     telegram.chatbackground
+    telegram.checklist
+    telegram.checklisttask
+    telegram.checklisttasksadded
+    telegram.checklisttasksdone
     telegram.copytextbutton
     telegram.backgroundtype
     telegram.backgroundtypefill
@@ -64,6 +70,7 @@ Available Types
     telegram.chatshared
     telegram.contact
     telegram.dice
+    telegram.directmessagepricechanged
     telegram.document
     telegram.externalreplyinfo
     telegram.file
@@ -75,6 +82,7 @@ Available Types
     telegram.forumtopicreopened
     telegram.generalforumtopichidden
     telegram.generalforumtopicunhidden
+    telegram.giftinfo
     telegram.giveaway
     telegram.giveawaycompleted
     telegram.giveawaycreated
@@ -82,6 +90,8 @@ Available Types
     telegram.inaccessiblemessage
     telegram.inlinekeyboardbutton
     telegram.inlinekeyboardmarkup
+    telegram.inputchecklist
+    telegram.inputchecklisttask
     telegram.inputfile
     telegram.inputmedia
     telegram.inputmediaanimation
@@ -92,13 +102,20 @@ Available Types
     telegram.inputpaidmedia
     telegram.inputpaidmediaphoto
     telegram.inputpaidmediavideo
+    telegram.inputprofilephoto
+    telegram.inputprofilephotoanimated
+    telegram.inputprofilephotostatic
     telegram.inputpolloption
+    telegram.inputstorycontent
+    telegram.inputstorycontentphoto
+    telegram.inputstorycontentvideo
     telegram.keyboardbutton
     telegram.keyboardbuttonpolltype
     telegram.keyboardbuttonrequestchat
     telegram.keyboardbuttonrequestusers
     telegram.linkpreviewoptions
     telegram.location
+    telegram.locationaddress
     telegram.loginurl
     telegram.maybeinaccessiblemessage
     telegram.menubutton
@@ -116,12 +133,17 @@ Available Types
     telegram.messageoriginuser
     telegram.messagereactioncountupdated
     telegram.messagereactionupdated
+    telegram.ownedgift
+    telegram.ownedgiftregular
+    telegram.ownedgifts
+    telegram.ownedgiftunique
     telegram.paidmedia
     telegram.paidmediainfo
     telegram.paidmediaphoto
     telegram.paidmediapreview
     telegram.paidmediapurchased
     telegram.paidmediavideo
+    telegram.paidmessagepricechanged
     telegram.photosize
     telegram.poll
     telegram.pollanswer
@@ -138,9 +160,23 @@ Available Types
     telegram.sentwebappmessage
     telegram.shareduser
     telegram.story
+    telegram.storyarea
+    telegram.storyareaposition
+    telegram.storyareatype
+    telegram.storyareatypelink
+    telegram.storyareatypelocation
+    telegram.storyareatypesuggestedreaction
+    telegram.storyareatypeuniquegift
+    telegram.storyareatypeweather
     telegram.switchinlinequerychosenchat
     telegram.telegramobject
     telegram.textquote
+    telegram.uniquegift
+    telegram.uniquegiftbackdrop
+    telegram.uniquegiftbackdropcolors
+    telegram.uniquegiftinfo
+    telegram.uniquegiftmodel
+    telegram.uniquegiftsymbol
     telegram.update
     telegram.user
     telegram.userchatboosts

docs/source/telegram.audio.rst

@@ -6,4 +6,4 @@ Audio
 .. autoclass:: telegram.Audio
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TelegramObject, object

docs/source/telegram.businessbotrights.rst

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

docs/source/telegram.chat.rst

@@ -5,4 +5,4 @@ Chat
 .. autoclass:: telegram.Chat
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TelegramObject, object