Bump Version to v22.6 (#5108)

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:
 
@@ -83,7 +87,7 @@ Here's how to make a one-off code change.
 
      - Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
 
-   -  In addition, PTB uses some formatting/styling and linting tools in the pre-commit setup. Some of those tools also have command line tools that can help to run these tools outside of the pre-commit step. If you'd like to leverage that, please have a look at the `pre-commit config file`_ for an overview of which tools (and which versions of them) are used. For example, we use `Black`_ for code formatting. Plugins for Black exist for some `popular editors`_. You can use those instead of manually formatting everything.
+   -  In addition, PTB uses some formatting/styling and linting tools in the pre-commit setup. Some of those tools also have command line tools that can help to run these tools outside of the pre-commit step. If you'd like to leverage that, please have a look at the `pre-commit config file`_ for an overview of which tools (and which versions of them) are used. For example, we use `Ruff`_ for linting and formatting.
 
    - Please ensure that the code you write is well-tested and that all automated tests still pass. We
      have dedicated an `testing page`_ to help you with that.
@@ -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
 ===========
@@ -282,8 +288,7 @@ to add new required arguments. It's also more explicit and easier to read.
 .. _`MyPy`: https://mypy.readthedocs.io/en/stable/index.html
 .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
 .. _`pre-commit config file`: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.pre-commit-config.yaml
-.. _`Black`: https://black.readthedocs.io/en/stable/index.html
-.. _`popular editors`: https://black.readthedocs.io/en/stable/integrations/editors.html
+.. _`Ruff`: https://docs.astral.sh/ruff/
 .. _`RTD`: https://docs.python-telegram-bot.org/
 .. _`RTD build`: https://docs.python-telegram-bot.org/en/doc-fixes
 .. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html

.github/copilot-instructions.md

@@ -0,0 +1,40 @@
+This is a python project which is a wrapper for the Telegram Bot API. Please read the contributing
+guidelines mentioned in .github/CONTRIBUTING.rst to know how to contribute to this project. The 
+README.rst file lists the features and usage of the project.
+
+### Development Environment:
+
+Your development environment is set up using `uv`, a tool for managing Python environments and dependencies.
+Your environment has all extra dependencies and groups installed, on Python 3.13. Please continue using `uv` for managing your development environment,
+and for any scripts or tools you need to run.
+
+Some example commands on `uv`:
+- `uv sync --all-extras --all-groups --locked` to install all dependencies and groups required by the project.
+- `uv run -p 3.14 --all-groups --all-extras --locked tests/` to run tests on a specific Python version. Please use the `-p` flag often.
+- `uv pip install <package>` to install a package in the current environment.
+
+If uv is somehow not available, you can install it using `pip install uv`.
+
+### Repository Structure:
+
+The repository follows a standard structure for Python projects. Here are some key directories and files:
+
+- `src/`: This directory contains the main source code for the project.
+- `tests/`: This directory contains test cases for the project.
+- `pyproject.toml`: This file contains the project metadata and dependencies.
+- `.github/`: This directory contains GitHub-specific files, including workflows and issue templates.
+
+
+### Things to keep in mind while coding:
+
+- Ensure that your code is properly and fully typed. All your code should be compatible from
+  Python 3.9 to 3.14. Don't use the `typing_extensions` module.
+- Read the stability guide mentioned at docs/source/stability_policy.rst to understand if your changes
+  are breaking or incompatible.
+- Try to make sure your code is asyncio-friendly and thread-safe.
+- Run `uv run pre-commit` to run pre-commit hooks before committing your changes, but after `git add`ing them.
+- Make sure you always test your changes. Either update or write new tests in the `tests/` directory.
+
+### Pull Requests:
+
+When you create a pull request, please also add the appropriate labels to it.

.github/dependabot.yml

@@ -1,14 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "pip"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "friday"
-
-  # Updates the dependencies of the GitHub Actions workflows
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "monthly"
-      day: "friday"

.github/renovate.json5

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [ // See what config:best-practices does: https://docs.renovatebot.com/presets-config/#configbest-practices
+    "config:best-practices",
+    // Opt-in to updating the pre-commit-config.yaml file too:
+    ":enablePreCommit",
+    ":prConcurrentLimitNone"  // No limits on the number of open PRs.
+  ],
+
+  // Add pull request labels:
+  "labels": ["⚙️ ci-cd"],
+
+  // Bump even patch versions:
+  "bumpVersion": "patch",
+
+  // Let Renovate decide how to update. See docs: https://docs.renovatebot.com/configuration-options/#rangestrategy
+  "rangeStrategy": "auto",
+
+  // Update the lock files:
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": ["* 0-3 1 * *"],  // https://docs.renovatebot.com/presets-schedule/#schedulemonthly
+    "automerge": true
+  },
+
+  // Enable automerge globally:
+  "automerge": true,
+
+  // Group package updates together:
+  "packageRules": [
+    // Linting dependencies in pyproject.toml in sync with the pre-commit-config hooks:
+    // Unfortunately it seems we need to do this for every dependency group (https://github.com/python-telegram-bot/python-telegram-bot/pull/4887#discussion_r2272025832):
+    {
+      "description": "Group Ruff updates together",
+      "matchPackageNames": ["ruff", "astral-sh/ruff-pre-commit"],
+      "groupName": "Ruff"
+    },
+    {
+      "description": "Group mypy updates together",
+      "matchPackageNames": ["mypy", "pre-commit/mirrors-mypy"],
+      "groupName": "Mypy"
+    },
+    {
+      "description": "Group pylint updates together",
+      "matchPackageNames": ["pylint", "PyCQA/pylint"],
+      "groupName": "Pylint"
+    },
+    {
+      "description": "Group chango updates together",
+      "matchPackageNames": ["chango", "Bibo-Joshi/chango"],
+      "groupName": "Chango"
+    },
+
+    // Don't automerge major updates for project dependencies:
+    {
+      "matchUpdateTypes": ["major"],
+      "matchDepTypes": ["project.dependencies", "project.optional-dependencies"],
+      "automerge": false
+    },
+
+    // Apply the "dependencies" label to all updates of optional/required dependencies:
+    {
+      "matchDepTypes": ["project.optional-dependencies", "project.dependencies"],
+      "labels": ["⚙️ dependencies"]
+    },
+
+    // Workflow and dev-dependencies update once a month
+    // https://docs.renovatebot.com/presets-schedule/#schedulemonthly
+    {
+      "matchFileNames": [".github/workflows/**"],
+      "schedule": ["* 0-3 1 * *"]
+    },
+    {
+      "matchDepTypes": ["dependency-groups"],
+      "schedule": ["* 0-3 1 * *"]
+    }
+  ],
+
+  // Increase the number of PR's Renovate can create in a hour. Default is 2.
+  "prHourlyLimit": 5,
+
+  // Temporarily disabled:
+  "ignoreDeps": ["pytest-asyncio"],
+
+  // schedule to allow PR's from Renovate:
+  "schedule": ["* * * * 0"]  // Every Sunday
+
+}

.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,69 @@
+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@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        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@bc58df46ef3ba8f15b8d744929998b7ae8a222d4 # 0.6.1
+        with:
+          # passing this custom token has two purposes
+          # 1. it allows us to fetch info about issue types
+          # 2. it ensures that the push will also re-trigger workflows
+          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@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.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@28e16e81777b558cc906c8750092100bbb34c5e3 # v7.0.0
+        with:
+          commit_message: "Do chango Release"
+          repository: ./target-repo

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,42 @@
+# This file is for the copilot agent on Github. This helps to set up the development environment
+# See the docs here: https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment#preinstalling-tools-or-dependencies-in-copilots-environment
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
+      contents: read
+      pull-requests: write  # So copilot can add labels to the PR
+
+    # You can define any steps you want, and they will run before the agent starts.
+    # If you do not check out your code, Copilot will do this for you.
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        with:
+          # Install a specific version of uv.
+          version: "0.9.13"
+          # Install 3.13:
+          python-version: 3.13
+
+      - name: Install the project
+        run: uv sync --all-extras --all-groups --locked

.github/workflows/dependabot-prs.yml

@@ -1,38 +0,0 @@
-name: Process Dependabot PRs
-
-on:
-  pull_request:
-    types: [opened, reopened]
-
-jobs:
-  process-dependabot-prs:
-    permissions:
-      pull-requests: read
-      contents: write
-
-    runs-on: ubuntu-latest
-    if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }}
-    steps:
-
-    - name: Fetch Dependabot metadata
-      id: dependabot-metadata
-      uses: dependabot/fetch-metadata@v2.2.0
-
-    - uses: actions/checkout@v4
-      with:
-        ref: ${{ github.event.pull_request.head.ref }}
-
-    - name: Update Version Number in Other Files
-      uses: jacobtomlinson/gha-find-replace@v3
-      with:
-        find: ${{ steps.dependabot-metadata.outputs.previous-version }}
-        replace: ${{ steps.dependabot-metadata.outputs.new-version }}
-        regex: false
-        exclude: CHANGES.rst
-
-    - name: Commit & Push Changes to PR
-      uses: EndBug/add-and-commit@v9.1.4
-      with:
-        message: 'Update version number in other files'
-        committer_name: GitHub Actions
-        committer_email: 41898282+github-actions[bot]@users.noreply.github.com

.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@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.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

@@ -7,24 +7,35 @@ on:
     paths:
       - .github/workflows/docs-linkcheck.yml
 
+permissions: {}
+
 jobs:
   test-sphinx-build:
     name: test-sphinx-linkcheck
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: ['3.10']
+        python-version: ['3.12']
         os: [ubuntu-latest]
       fail-fast: False
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.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@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: linkcheck-output
+          path: docs/build/html/output.*

.github/workflows/docs.yml

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

.github/workflows/gha_security.yml

@@ -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@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+      - 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@fdbfb4d2750291e159f0156def62b853c2798ca2 # v4.31.5
+        with:
+          sarif_file: results.sarif
+          category: zizmor

.github/workflows/labelling.yml

@@ -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@0a20eccb8c94a1ee0bed5f16859aece1c45c3e55 # v1.13.0
       # Config file at .github/labeler.yml
       env:
         GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/lock.yml

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

.github/workflows/release_pypi.yml

@@ -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@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.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@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.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@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         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@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
 
   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@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         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@f832326173235dcb00dd5d92cd3f353de3188e6c # v3.1.0
         with:
           inputs: >-
             ./dist/*.tar.gz
             ./dist/*.whl
       - name: Store the distribution packages and signatures
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -98,10 +107,14 @@ jobs:
 
     permissions:
       contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      actions: read  # for downloading artifacts
 
     steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
       - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -109,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
-          '${{ env.TAG }}'
+          "$TAG"
           --repo '${{ github.repository }}'
-          --generate-notes
+          --notes-file -
       - name: Upload artifact signatures to GitHub Release
         env:
           GITHUB_TOKEN: ${{ github.token }}
@@ -125,5 +139,34 @@ jobs:
         # sigstore-produced signatures and certificates.
         run: >-
           gh release upload
-          '${{ env.TAG }}' dist/**
+          "$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@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        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

@@ -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@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.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@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.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@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         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@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
         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@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         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@f832326173235dcb00dd5d92cd3f353de3188e6c # v3.1.0
         with:
           inputs: >-
             ./dist/*.tar.gz
             ./dist/*.whl
       - name: Store the distribution packages and signatures
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -100,10 +109,14 @@ jobs:
 
     permissions:
       contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      actions: read  # for downloading artifacts
 
     steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
       - name: Download all the dists
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -111,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
-          '${{ env.TAG }}'
+          "$TAG"
           --repo '${{ github.repository }}'
-          --generate-notes
           --draft
+          --notes-file -
       - name: Upload artifact signatures to GitHub Release
         env:
           GITHUB_TOKEN: ${{ github.token }}
@@ -128,5 +142,5 @@ jobs:
         # sigstore-produced signatures and certificates.
         run: >-
           gh release upload
-          '${{ env.TAG }}' dist/**
+          "$TAG" dist/**
           --repo '${{ github.repository }}'

.github/workflows/stale.yml

@@ -3,17 +3,22 @@ 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@997185467fa4f803885201cee163a9f38240193d # v10.1.1
         with:
           # PRs never get stale
           days-before-stale: 3
           days-before-close: 2
           days-before-pr-stale: -1
           stale-issue-label: '📋 stale'
-          only-labels: 'question'
+          only-issue-types: '❔ question'
           stale-issue-message: ''
           close-issue-message: 'This issue has been automatically closed due to inactivity. Feel free to comment in order to reopen or ask again in our Telegram support group at https://t.me/pythontelegrambotgroup.'

.github/workflows/test_official.yml

@@ -2,7 +2,7 @@ name: Bot API Tests
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - tests/**
   push:
     branches:
@@ -11,6 +11,8 @@ on:
     # Run monday and friday morning at 03:07 - odd time to spread load on GitHub Actions
     - cron: '7 3 * * 1,5'
 
+permissions: {}
+
 jobs:
   check-conformity:
     name: check-conformity
@@ -21,16 +23,17 @@ jobs:
         os: [ubuntu-latest]
       fail-fast: False
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.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
@@ -41,7 +44,7 @@ jobs:
 
       - name: Test Summary
         id: test_summary
-        uses: test-summary/action@v2.4
+        uses: test-summary/action@31493c76ec9e7aa675f1585d3ed6f1da69269a86 # v2.4
         if: always()  # always run, even if tests fail
         with:
           paths: .test_report_official.xml

.github/workflows/type_completeness.yml

@@ -2,19 +2,21 @@ name: Check Type Completeness
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - pyproject.toml
       - .github/workflows/type_completeness.yml
   push:
     branches:
       - master
 
+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 # 1.0.1
         with:
           package-name: telegram
           python-version: 3.12

.github/workflows/type_completeness_monthly.yml

@@ -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 # 1.0.1
         id: pyright-type-completeness
         with:
           package-name: telegram
           python-version: 3.12
           pyright-version: ~=1.1.367
       - name: Check Output
-        uses: jannekem/run-python-script-action@v1
+        uses: jannekem/run-python-script-action@bbfca66c612a28f3eeca0ae40e1f810265e2ea68 # v1.7
         env:
           TYPE_COMPLETENESS: ${{ steps.pyright-type-completeness.outputs.base-completeness-score }}
         with:

.github/workflows/unit_tests.yml

@@ -2,17 +2,15 @@ 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
-  schedule:
-    # Run monday and friday morning at 03:07 - odd time to spread load on GitHub Actions
-    - cron: '7 3 * * 1,5'
+
+permissions: {}
 
 jobs:
   pytest:
@@ -20,24 +18,25 @@ jobs:
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
         os: [ubuntu-latest, windows-latest, macos-latest]
+        include:
+          - python-version: '3.14t'
+            os: ubuntu-latest
       fail-fast: False
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.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
@@ -59,7 +58,7 @@ 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'
           pip install .[all]
@@ -79,7 +78,7 @@ jobs:
 
       - name: Test Summary
         id: test_summary
-        uses: test-summary/action@v2.4
+        uses: test-summary/action@31493c76ec9e7aa675f1585d3ed6f1da69269a86 # v2.4
         if: always()  # always run, even if tests fail
         with:
           paths: |
@@ -87,14 +86,14 @@ jobs:
             .test_report_optionals_junit.xml
 
       - name: Submit coverage
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7  # v5.5.1
         with:
           env_vars: OS,PYTHON
           name: ${{ matrix.os }}-${{ matrix.python-version }}
           fail_ci_if_error: true
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Upload test results to Codecov
-        uses: codecov/test-results-action@v1
+        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

@@ -67,6 +67,7 @@ docs/_build/
 # PyBuilder
 target/
 .idea/
+.run/
 
 # Sublime Text 2
 *.sublime*
@@ -92,6 +93,11 @@ telegram.jpg
 
 # virtual env
 venv*
+pyvenv.cfg
+Scripts/
 
 # environment manager:
-.mise.toml
+.mise.toml
+
+# Support for uv.lock will come in a future PR. See #4796
+uv.lock

.pre-commit-config.yaml

@@ -1,83 +1,60 @@
-# Make sure that the additional_dependencies here match pyproject.toml
-
 ci:
     autofix_prs: false
+    # We use Renovate to update this file now, but we can't disable automatic pre-commit updates
+    # when using the `pre-commit` GitHub Action, so we set the schedule to quarterly to avoid
+    # frequent updates.
     autoupdate_schedule: quarterly
     autoupdate_commit_msg: 'Bump `pre-commit` Hooks to Latest Versions'
 
 repos:
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.5.6'
+    rev: 'v0.14.13'
     hooks:
-    -   id: ruff
-        name: ruff
-        additional_dependencies:
-          - httpx~=0.27
-          - tornado~=6.4
-          - APScheduler~=3.10.4
-          - cachetools>=5.3.3,<5.5.0
-          - aiolimiter~=1.1.0
--   repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.4.2
-    hooks:
-    -   id: black
-        args:
-        - --diff
-        - --check
--   repo: https://github.com/PyCQA/flake8
-    rev: 7.1.0
-    hooks:
-    -   id: flake8
+    # Run the linter:
+    -   id: ruff-check
+        name: ruff check
+    # Run the formatter:
+    -   id: ruff-format
+        name: ruff format
 -   repo: https://github.com/PyCQA/pylint
-    rev: v3.2.4
+    rev: v4.0.4
     hooks:
     -   id: pylint
         files: ^(?!(tests|docs)).*\.py$
+        language: python
         additional_dependencies:
           - httpx~=0.27
           - tornado~=6.4
-          - APScheduler~=3.10.4
-          - cachetools>=5.3.3,<5.5.0
-          - aiolimiter~=1.1.0
+          - APScheduler>=3.10.4,<3.12.0
+          - cachetools>=5.3.3,<6.3.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.19.1
     hooks:
     -   id: mypy
         name: mypy-ptb
         files: ^(?!(tests|examples|docs)).*\.py$
+        language: python
         additional_dependencies:
           - types-pytz
           - types-cryptography
           - types-cachetools
           - httpx~=0.27
           - tornado~=6.4
-          - APScheduler~=3.10.4
-          - cachetools>=5.3.3,<5.5.0
-          - aiolimiter~=1.1.0
+          - APScheduler>=3.10.4,<3.12.0
+          - cachetools>=5.3.3,<6.3.0
+          - aiolimiter~=1.1,<1.3
           - . # this basically does `pip install -e .`
     - id: mypy
       name: mypy-examples
       files: ^examples/.*\.py$
+      language: python
       args:
         - --no-strict-optional
         - --follow-imports=silent
       additional_dependencies:
         - tornado~=6.4
-        - APScheduler~=3.10.4
-        - cachetools>=5.3.3,<5.5.0
+        - APScheduler>=3.10.4,<3.12.0
+        - cachetools>=5.3.3,<6.3.0
         - . # this basically does `pip install -e .`
--   repo: https://github.com/asottile/pyupgrade
-    rev: v3.16.0
-    hooks:
-    -   id: pyupgrade
-        args:
-          - --py39-plus
--   repo: https://github.com/pycqa/isort
-    rev: 5.13.2
-    hooks:
-    -   id: isort
-        name: isort
-        args:
-        - --diff
-        - --check

.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 'docs' --group 'tests' # install most 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>`_
@@ -31,6 +29,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>`_
@@ -41,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>`_
@@ -58,12 +58,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,20 +74,24 @@ 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>`_
 - `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>`_
 - `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>`_
@@ -104,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>`_
@@ -111,10 +118,12 @@ 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
 - `Sahil Sharma <https://github.com/sahilsharma811>`_
 - `Sam Mosleh <https://github.com/sam-mosleh>`_
 - `Sascha <https://github.com/saschalalala>`_
 - `Shelomentsev D <https://github.com/shelomentsevd>`_
+- `Shivam <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-7.11-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-9.3-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
 
@@ -70,7 +70,7 @@ Introduction
 
 This library provides a pure Python, asynchronous interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
-It's compatible with Python versions **3.9+**.
+It's compatible with Python versions **3.10+**.
 
 In addition to the pure API implementation, this library features several convenience methods and shortcuts as well as a number of high-level classes to
 make the development of bots easy and straightforward. These classes are contained in the
@@ -81,7 +81,7 @@ After installing_ the library, be sure to check out the section on `working with
 Telegram API support
 ~~~~~~~~~~~~~~~~~~~~
 
-All types and methods of the Telegram Bot API **7.11** are natively supported by this library.
+All types and methods of the Telegram Bot API **9.3** 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.
@@ -155,10 +157,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[callback-data]"`` installs the `cachetools>=5.3.3,<6.3.0 <https://cachetools.readthedocs.io/en/latest/>`_ library. Use this, if you want to use `arbitrary callback_data <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_.
+* ``pip install "python-telegram-bot[job-queue]"`` installs the `APScheduler>=3.10.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]"``.
 
@@ -204,7 +206,7 @@ Concurrency
 ~~~~~~~~~~~
 
 Since v20.0, ``python-telegram-bot`` is built on top of Pythons ``asyncio`` module.
-Because ``asyncio`` is in general single-threaded, ``python-telegram-bot`` does currently not aim to be thread-safe.
+Because ``asyncio`` is in general single-threaded, ``python-telegram-bot`` currently does not aim to be thread-safe.
 Noteworthy parts of ``python-telegram-bots`` API that are likely to cause issues (e.g. race conditions) when used in a multi-threaded setting include:
 
 * ``telegram.ext.Application/Updater.update_queue``
@@ -213,6 +215,12 @@ Noteworthy parts of ``python-telegram-bots`` API that are likely to cause issues
 * ``telegram.ext.BasePersistence``
 * all classes in the ``telegram.ext.filters`` module that allow to add/remove allowed users/chats at runtime
 
+Free threading
+~~~~~~~~~~~~~~
+
+While ``python-telegram-bot`` is tested to work with Python 3.14 free threading, we do not guarantee that
+PTB is thread-safe for all use cases. Please see issue `#4873 <https://github.com/python-telegram-bot/python-telegram-bot/issues/4873>`_ for more information.
+
 Contributing
 ------------
 

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 ``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/22.4_2025-09-13/4869.7GK56NC89XswBFUCiWXtqc.toml

@@ -0,0 +1,5 @@
+features = "Extend :meth:`telegram.Message.delete` shortcut to support business message deletion"
+[[pull_requests]]
+uid = "4869"
+author_uid = "jainamoswal"
+closes_threads = ["4867"]

changes/22.4_2025-09-13/4875.29srP6fENz7FrGGoWSkPNa.toml

@@ -0,0 +1,5 @@
+bugfixes = "Adapt logic on getting the event loop in ``Application.run_polling/webhook`` to Python 3.14"
+[[pull_requests]]
+uid = "4875"
+author_uid = "harshil21"
+closes_threads = ["4874"]

changes/22.4_2025-09-13/4878.AbGo6aozTWquUjnzzpSdyX.toml

@@ -0,0 +1,9 @@
+documentation = "Documentation Improvements"
+
+[[pull_requests]]
+uid = "4878"
+author_uid = "Bibo-Joshi"
+
+[[pull_requests]]
+uid = "4872"
+author_uid = "Ca5parAD"

changes/22.4_2025-09-13/4879.kABAi45KpR2H6jqJu6NtDS.toml

@@ -0,0 +1,5 @@
+internal = "Address Failing Unit Test for ``send_paid_media``"
+
+[[pull_requests]]
+uid = "4879"
+author_uid = "Bibo-Joshi"

changes/22.4_2025-09-13/4880.42PW26hGpLypMJMxTeiQZ6.toml

@@ -0,0 +1,6 @@
+internal = "Improve Internal Logic for Network Retries"
+
+[[pull_requests]]
+uid = "4880"
+author_uid = "Bibo-Joshi"
+closes_threads = ["4871"]

changes/22.4_2025-09-13/4881.dJNT656MVxJk9DgcoRePip.toml

@@ -0,0 +1,6 @@
+features = "Add convenience properties for ``firstname``, ``lastname``, and ``username`` to ``SharedUser`` and ``ChatShared``"
+internal = "Introduce utility module ``_utils.usernames`` refactoring convenience properties around Telegram Objects' ``firstname``, ``lastname``, and ``username``"
+pull_requests = [
+  { uid = "4881", author_uid = "aelkheir" },
+  { uid = "4713", author_uid = "david-shiko" },
+]

changes/22.4_2025-09-13/4882.JpgQAHHnCponMKStbC4JsG.toml

@@ -0,0 +1,10 @@
+other = """
+Set the default connection pool size for ``HTTPXRequest`` to 256 to allow more concurrent requests by default. Drop the ``httpx`` parameter ``max_keepalive_connections``. This way, the ``httpx`` default of 20 is used, leading to a smaller number of idle connections in large connection pools.
+
+.. hint::
+   If you manually build the ``HTTPXRequest`` objects, please be aware that these changes also applies to you. Kindly double check your settings. To specify custom limits, you can set them via the parameter ``httpx_kwargs`` of ``HTTPXRequest``. See also  `the httpx documentation <https://www.python-httpx.org/advanced/resource-limits/>`__ for more details on these settings."
+"""
+[[pull_requests]]
+uid = "4882"
+author_uid = "Poolitzer"
+closes_threads = []

changes/22.4_2025-09-13/4884.ADcdCj6GrMaKffYSLzWdsL.toml

@@ -0,0 +1,5 @@
+internal = "Add Copilot Instructions and Setup Steps"
+[[pull_requests]]
+uid = "4884"
+author_uid = "harshil21"
+closes_threads = []

changes/22.4_2025-09-13/4886.XSHPk83uhDQdYzurbb4xx9.toml

@@ -0,0 +1,5 @@
+internal = "Remove ``black``, ``isort``, ``flake8``, and ``pyupgrade`` in favor of ``ruff``"
+[[pull_requests]]
+uid = "4886"
+author_uid = "harshil21"
+closes_threads = []

changes/22.4_2025-09-13/4887.5yypYZV7Sq5PN4ihmf2NUr.toml

@@ -0,0 +1,5 @@
+internal = "Use Renovate to Keep Dependencies Up-To-Date"
+[[pull_requests]]
+uid = "4887"
+author_uid = "renovatebot"
+closes_threads = []