Bump Version to v22.4 (#4939)

Co-authored-by: Ca5parAD <github.unearned388@passmail.net>
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
Co-authored-by: Poolitzer <github@poolitzer.eu>
Co-authored-by: aelkheir <90580077+aelkheir@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.
@@ -284,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,20 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "pip"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "friday"
-    labels:
-      - "⚙️ dependencies"
-      - "🔗 python"
-
-  # Updates the dependencies of the GitHub Actions workflows
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "monthly"
-      day: "friday"
-    labels:
-      - "⚙️ dependencies"
-      - "🔗 github-actions"

.github/renovate.json5

@@ -0,0 +1,81 @@
+{
+  "$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": ["dependencies"],
+
+  // 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": ["* * * * 1,4"]  // Run sometime on Monday and Thursday
+  },
+
+  // Bump the versions even in other files:
+  "bumpVersions": [
+    {
+      "name": "Update dependency versions in README.rst",
+      "filePatterns": ["README.rst"],
+      "matchStrings": [
+        "cryptography>=(?<version>\\d+\\.\\d+\\.\\d+)",
+        "aiolimiter~=(?<version>\\d+\\.\\d+\\.\\d+)",
+        "tornado~=(?<version>\\d+\\.\\d+)",
+        "cachetools>=(?<version>\\d+\\.\\d+\\.\\d+)",        // Lower bound only
+        "APScheduler>=(?<version>\\d+\\.\\d+\\.\\d+)"        // Lower bound only
+      ],
+      "bumpType": "minor"
+    }
+  ],
+
+  // 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"
+    },
+    // Automerge PR's for minor/patch/pin/digest (except major) updates:
+    {
+      "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
+      "automerge": true
+    }
+  ],
+
+  // 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,6"]  // Every weekend
+
+}

.github/workflows/chango.yml

@@ -20,7 +20,7 @@ jobs:
       IS_RELEASE_PR: ${{ steps.check_title.outputs.IS_RELEASE_PR }}
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           # needed for commit and push step at the end
           persist-credentials: true
@@ -36,7 +36,7 @@ jobs:
           fi
 
       # Create the new fragment
-      - uses: Bibo-Joshi/chango@9d6bd9d7612eca5fab2c5161687011be59baaf19 # v0.4.0
+      - uses: Bibo-Joshi/chango@9d6bd9d7612eca5fab2c5161687011be59baaf19 # 0.4.0
         with:
           github-token: ${{ secrets.CHANGO_PAT }}
           query-issue-types: true
@@ -45,7 +45,7 @@ jobs:
       # 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@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.x"
 
@@ -54,13 +54,13 @@ jobs:
         run: |
           cd ./target-repo
           git add changes/unreleased/*
-          pip install . -r docs/requirements-docs.txt
+          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@b863ae1933cb653a53c021fe36dbb774e1fb9403 # v5.2.0
+        uses: stefanzweifel/git-auto-commit-action@778341af668090896ca464160c2def5d1d1a3eb0 # v6.0.1
         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@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@557e51de59eb14aaaba2ed9621916900a91d50c6
+        with:
+          # Install a specific version of uv.
+          version: "0.8.3"
+          # 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,41 +0,0 @@
-name: Process Dependabot PRs
-
-on:
-  pull_request:
-    types: [opened, reopened]
-
-permissions: {}
-
-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@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 # v2.3.0
-
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      with:
-        ref: ${{ github.event.pull_request.head.ref }}
-        persist-credentials: false
-
-    - name: Update Version Number in Other Files
-      uses: jacobtomlinson/gha-find-replace@f1069b438f125e5395d84d1c6fd3b559a7880cb5 # 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@a94899bca583c204427a224a7af87c02f9b325d5 # 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

@@ -2,7 +2,7 @@ name: Test Admonitions Generation
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - docs/**
       - .github/workflows/docs-admonitions.yml
   push:
@@ -24,18 +24,18 @@ jobs:
         os: [ubuntu-latest]
       fail-fast: False
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'
-          cache-dependency-path: '**/requirements*.txt'
+          cache-dependency-path: 'pyproject.toml'
       - 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: Test autogeneration of admonitions
         run: pytest -v --tb=short tests/docs/admonition_inserter.py

.github/workflows/docs-linkcheck.yml

@@ -19,17 +19,17 @@ jobs:
         os: [ubuntu-latest]
       fail-fast: False
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.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 --keep-going -j auto -b linkcheck
       - name: Upload linkcheck output

.github/workflows/gha_security.yml

@@ -17,17 +17,17 @@ jobs:
       security-events: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5.4.1
+        uses: astral-sh/setup-uv@557e51de59eb14aaaba2ed9621916900a91d50c6 # v6.6.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@28deaeda66b76a05916b6923827895f2b14ab387 # v3.28.16
+        uses: github/codeql-action/upload-sarif@2d92b76c45b91eb80fc44c74ce3fce0ee94e8f9d # v3.30.0
         with:
           sarif_file: results.sarif
-          category: zizmor
+          category: zizmor

.github/workflows/release_pypi.yml

@@ -17,11 +17,11 @@ jobs:
       actions: write
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.x"
       - name: Install pypa/build
@@ -55,7 +55,7 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: python-package-distributions
           path: dist/
@@ -74,7 +74,7 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: python-package-distributions
           path: dist/
@@ -86,7 +86,7 @@ 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
@@ -110,11 +110,11 @@ jobs:
       actions: read  # for downloading artifacts
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: python-package-distributions-and-signatures
           path: dist/
@@ -145,7 +145,9 @@ jobs:
   telegram-channel:
     name: Publish to Telegram Channel
     needs:
-        - github-release
+      # required to have the output available for the env var
+      - build
+      - github-release
 
     runs-on: ubuntu-latest
     environment:
@@ -153,7 +155,7 @@ jobs:
     permissions: {}
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Publish to Telegram Channel

.github/workflows/release_test_pypi.yml

@@ -17,11 +17,11 @@ jobs:
       actions: write
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.x"
       - name: Install pypa/build
@@ -55,7 +55,7 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: python-package-distributions
           path: dist/
@@ -76,7 +76,7 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: python-package-distributions
           path: dist/
@@ -88,7 +88,7 @@ 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
@@ -112,11 +112,11 @@ jobs:
       actions: read  # for downloading artifacts
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: python-package-distributions-and-signatures
           path: dist/

.github/workflows/test_official.yml

@@ -2,7 +2,7 @@ name: Bot API Tests
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - tests/**
   push:
     branches:
@@ -23,18 +23,17 @@ jobs:
         os: [ubuntu-latest]
       fail-fast: False
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.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:
@@ -16,7 +16,7 @@ jobs:
     name:   test-type-completeness
     runs-on: ubuntu-latest
     steps:
-      - uses: Bibo-Joshi/pyright-type-completeness@c85a67ff3c66f51dcbb2d06bfcf4fe83a57d69cc # v1.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

@@ -11,7 +11,7 @@ jobs:
     name:   test-type-completeness
     runs-on: ubuntu-latest
     steps:
-      - uses: Bibo-Joshi/pyright-type-completeness@c85a67ff3c66f51dcbb2d06bfcf4fe83a57d69cc # v1.0.1
+      - uses: Bibo-Joshi/pyright-type-completeness@c85a67ff3c66f51dcbb2d06bfcf4fe83a57d69cc # 1.0.1
         id: pyright-type-completeness
         with:
           package-name: telegram

.github/workflows/unit_tests.yml

@@ -2,17 +2,13 @@ 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: {}
 
@@ -22,26 +18,22 @@ 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:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.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 +55,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 +83,14 @@ jobs:
             .test_report_optionals_junit.xml
 
       - name: Submit coverage
-        uses: codecov/codecov-action@ad3126e916f78f00edff4ed0317cf185271ccc2d  # v5.4.2
+        uses: codecov/codecov-action@fdcc8476540edceab3de004e990f80d881c6cc00  # v5.5.0
         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@f2dba722c67b86c6caa034178c6e4d35335f6706 # v1.1.0
+        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,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,38 +1,27 @@
-# 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.11.9'
+    rev: 'v0.12.7'
     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,<1.3
--   repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 25.1.0
-    hooks:
-    -   id: black
-        args:
-        - --diff
-        - --check
--   repo: https://github.com/PyCQA/flake8
-    rev: 7.2.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.3.6
+    rev: v3.3.7
     hooks:
     -   id: pylint
         files: ^(?!(tests|docs)).*\.py$
+        language: python
         additional_dependencies:
           - httpx~=0.27
           - tornado~=6.4
@@ -41,11 +30,12 @@ repos:
           - aiolimiter~=1.1,<1.3
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.15.0
+    rev: v1.16.1
     hooks:
     -   id: mypy
         name: mypy-ptb
         files: ^(?!(tests|examples|docs)).*\.py$
+        language: python
         additional_dependencies:
           - types-pytz
           - types-cryptography
@@ -59,6 +49,7 @@ repos:
     - id: mypy
       name: mypy-examples
       files: ^examples/.*\.py$
+      language: python
       args:
         - --no-strict-optional
         - --follow-imports=silent
@@ -67,17 +58,3 @@ repos:
         - APScheduler~=3.10.4
         - cachetools>=5.3.3,<5.5.0
         - . # this basically does `pip install -e .`
--   repo: https://github.com/asottile/pyupgrade
-    rev: v3.19.1
-    hooks:
-    -   id: pyupgrade
-        args:
-          - --py39-plus
--   repo: https://github.com/pycqa/isort
-    rev: 6.0.1
-    hooks:
-    -   id: isort
-        name: isort
-        args:
-        - --diff
-        - --check

.readthedocs.yml

@@ -18,13 +18,16 @@ python:
   install:
     - method: pip
       path: .
-    - requirements: requirements-dev-all.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

@@ -80,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>`_
@@ -109,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>`_

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-9.0-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-9.2-blue?logo=telegram
    :target: https://core.telegram.org/bots/api-changelog
    :alt: Supported Bot API version
 
@@ -81,7 +81,7 @@ After installing_ the library, be sure to check out the section on `working with
 Telegram API support
 ~~~~~~~~~~~~~~~~~~~~
 
-All types and methods of the Telegram Bot API **9.0** are natively supported by this library.
+All types and methods of the Telegram Bot API **9.2** are natively supported by this library.
 In addition, Bot API functionality not yet natively included can still be used as described `in our wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Forward-Compatibility>`_.
 
 Notable Features
@@ -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.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``

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/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 = "renovate[bot]"
+closes_threads = []

changes/22.4_2025-09-13/4890.oCzELerGo8dqPygShWMV9S.toml

@@ -0,0 +1,5 @@
+internal = "Add and use a ``uv.lock`` lockfile when setting up the development environment using ``uv``."
+[[pull_requests]]
+uid = "4890"
+author_uid = "harshil21"
+closes_threads = ["4796"]

changes/22.4_2025-09-13/4892.iRGvURLUGiMSMEDfdpP5jB.toml

@@ -0,0 +1,5 @@
+internal = "Bump ``pytest`` from 8.4.0 to 8.4.1"
+[[pull_requests]]
+uid = "4892"
+author_uid = "dependabot"
+closes_threads = []

changes/22.4_2025-09-13/4893.Fbkdqj4bmTTH6e54gRPwvc.toml

@@ -0,0 +1,5 @@
+internal = "Bump ``pytest-xdist`` from 3.6.1 to 3.8.0"
+[[pull_requests]]
+uid = "4893"
+author_uid = "dependabot"
+closes_threads = []

changes/22.4_2025-09-13/4894.PLQSCgnKXygrGdkekTbx8q.toml

@@ -0,0 +1,5 @@
+documentation = "Bump ``furo`` from 2024.8.6 to 2025.7.19"
+[[pull_requests]]
+uid = "4894"
+author_uid = "dependabot"
+closes_threads = []

changes/22.4_2025-09-13/4895.UECAN369MCuQaLnTmtYFGr.toml

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

changes/22.4_2025-09-13/4896.R92Xq7W6PDbabuk6aZ5FZt.toml

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

changes/22.4_2025-09-13/4906.Fju7LDJgwCz2sxgQy9muBG.toml

@@ -0,0 +1,5 @@
+features = "Add ``filters.FORUM`` to filter messages from forum topic chats"
+[[pull_requests]]
+uid = "4906"
+author_uid = "harshil21"
+closes_threads = []

changes/22.4_2025-09-13/4908.KnwujH2JruNRZSrTTvvc9B.toml

@@ -0,0 +1,5 @@
+bugfixes = "Fix ``ResourceWarning`` when passing ``pathlib.Path`` objects to methods which accept file input"
+[[pull_requests]]
+uid = "4908"
+author_uid = "harshil21"
+closes_threads = ["4907"]

changes/22.4_2025-09-13/4911.kiF45Y4cfPGMq5cuLpa5da.toml

@@ -0,0 +1,14 @@
+features = "Full Support for Bot API 9.2"
+
+pull_requests = [
+    { uid = "4911", author_uid = "aelkheir", closes_threads = ["4910"] },
+    { uid = "4918", author_uid = "Poolitzer" },
+    { uid = "4917", author_uid = "Poolitzer" },
+    { uid = "4914", author_uid = "harshil21"},
+    { uid = "4916", author_uid = "harshil21"},
+    { uid = "4912", author_uid = "aelkheir" },
+    { uid = "4921", author_uid = "aelkheir" },
+    { uid = "4936", author_uid = "Bibo-Joshi" },
+    { uid = "4935", author_uid = "Bibo-Joshi" },
+    { uid = "4931", author_uid = "aelkheir" },
+]

changes/22.4_2025-09-13/4915.D3x6MoyYYDaUcB7jmLUyeY.toml

@@ -0,0 +1,5 @@
+internal = "Don't update ``uv.lock`` in copilot runtime environment"
+[[pull_requests]]
+uid = "4915"
+author_uid = "harshil21"
+closes_threads = []

changes/22.4_2025-09-13/4923.AEztvspxU4Ajz7N3ms56Wq.toml

@@ -0,0 +1,5 @@
+dependencies = "Update cachetools requirement from <6.2.0,>=5.3.3 to >=5.3.3,<6.3.0"
+[[pull_requests]]
+uid = "4923"
+author_uid = "dependabot[bot]"
+closes_threads = []

changes/22.4_2025-09-13/4925.FCwe9rrjgv5GmfvuhHXjHg.toml

@@ -0,0 +1,5 @@
+internal = "Bump actions/checkout from 4.2.2 to 5.0.0"
+[[pull_requests]]
+uid = "4925"
+author_uid = "dependabot"
+closes_threads = []

changes/22.4_2025-09-13/4926.GMcTfT2hSAdmdT7wi73mzZ.toml

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

changes/22.4_2025-09-13/4927.mHtL79KfGaRw3LEMdHN6Ry.toml

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

changes/22.4_2025-09-13/4928.ej4TvW3TjhqhpUHNyne2r4.toml

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

changes/22.4_2025-09-13/4929.P2dSYTjRtQtXPdKyaDHPJA.toml

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

changes/22.4_2025-09-13/4933.CPGgVg7gvHC3dqmhzAVDVo.toml

@@ -0,0 +1,5 @@
+internal = "Bump pytest from 8.4.1 to 8.4.2"
+[[pull_requests]]
+uid = "4933"
+author_uid = "dependabot"
+closes_threads = []

changes/22.4_2025-09-13/4934.W4nUZkUHd9Hw4mGaLA6Ayf.toml

@@ -0,0 +1,5 @@
+internal = "Use Tagged Release of `pydantic` in Development Dependencies"
+[[pull_requests]]
+uid = "4934"
+author_uid = "harshil21"
+closes_threads = ["4932"]

changes/22.4_2025-09-13/4939.YDNzLiFegKD2difT6yr6P7.toml

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

changes/config.py

@@ -80,7 +80,7 @@ class CustomChango(DirectoryChanGo):
         """replace "14.5" with version.uid except in the contrib guide
         then call super
         """
-        root = Path(__file__).parent.parent / "telegram"
+        root = Path(__file__).parent.parent / "src"
         python_files = root.rglob("*.py")
         pattern = re.compile(r"NEXT\.VERSION")
         excluded_paths = {root / "docs/source/contribute.rst"}

docs/auxil/link_code.py

@@ -19,6 +19,7 @@
 to link to the correct files & lines on github. Can be simplified once
 https://github.com/sphinx-doc/sphinx/issues/1556 is closed
 """
+
 import subprocess
 from pathlib import Path
 

docs/auxil/sphinx_hooks.py

@@ -55,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()
 
 
@@ -161,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,10 +0,0 @@
-chango~=0.4.0
-sphinx==8.2.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/conf.py

@@ -51,7 +51,6 @@ extensions = [
     "sphinx_copybutton",
     "sphinx_inline_tabs",
     "sphinxcontrib.mermaid",
-    "sphinx_search.extension",
 ]
 
 # Temporary. See #4387

docs/source/inclusions/bot_methods.rst

@@ -121,6 +121,10 @@
       - Used for approving a chat join request
     * - :meth:`~telegram.Bot.decline_chat_join_request`
       - Used for declining a chat join request
+    * - :meth:`~telegram.Bot.approve_suggested_post`
+      - Used for approving a suggested post
+    * - :meth:`~telegram.Bot.decline_suggested_post`
+      - Used for declining a suggested post
     * - :meth:`~telegram.Bot.ban_chat_member`
       - Used for banning a member from the chat
     * - :meth:`~telegram.Bot.unban_chat_member`
@@ -390,6 +394,8 @@
       - 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`
@@ -447,6 +453,10 @@
       - 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/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

@@ -31,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
@@ -66,6 +70,8 @@ Available Types
     telegram.chatshared
     telegram.contact
     telegram.dice
+    telegram.directmessagepricechanged
+    telegram.directmessagestopic
     telegram.document
     telegram.externalreplyinfo
     telegram.file
@@ -85,6 +91,8 @@ Available Types
     telegram.inaccessiblemessage
     telegram.inlinekeyboardbutton
     telegram.inlinekeyboardmarkup
+    telegram.inputchecklist
+    telegram.inputchecklisttask
     telegram.inputfile
     telegram.inputmedia
     telegram.inputmediaanimation
@@ -161,6 +169,14 @@ Available Types
     telegram.storyareatypesuggestedreaction
     telegram.storyareatypeuniquegift
     telegram.storyareatypeweather
+    telegram.suggestedpostapprovalfailed
+    telegram.suggestedpostapproved
+    telegram.suggestedpostdeclined
+    telegram.suggestedpostinfo
+    telegram.suggestedpostpaid
+    telegram.suggestedpostparameters
+    telegram.suggestedpostprice
+    telegram.suggestedpostrefunded
     telegram.switchinlinequerychosenchat
     telegram.telegramobject
     telegram.textquote

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.chat.rst

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

docs/source/telegram.chatfullinfo.rst

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

docs/source/telegram.checklist.rst

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

docs/source/telegram.checklisttask.rst

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

docs/source/telegram.checklisttasksadded.rst

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

docs/source/telegram.checklisttasksdone.rst

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

docs/source/telegram.constants.rst

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

docs/source/telegram.directmessagepricechanged.rst

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

docs/source/telegram.directmessagestopic.rst

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