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

@@ -87,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.
@@ -288,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
@@ -60,7 +60,7 @@ jobs:
 
       - 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@08eff52bf64351f401fb50d4972fa95b9f2c2d1b # v2.4.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

@@ -24,7 +24,7 @@ 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 }}

.github/workflows/docs-linkcheck.yml

@@ -19,7 +19,7 @@ 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 }}

.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@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
+        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,7 +17,7 @@ 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
@@ -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/
@@ -155,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,7 +17,7 @@ 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
@@ -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

@@ -23,7 +23,7 @@ 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 }}

.github/workflows/type_completeness.yml

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

@@ -9,9 +9,6 @@ on:
   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: {}
 
@@ -25,7 +22,7 @@ jobs:
         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 }}
@@ -86,7 +83,7 @@ jobs:
             .test_report_optionals_junit.xml
 
       - name: Submit coverage
-        uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24  # v5.4.3
+        uses: codecov/codecov-action@fdcc8476540edceab3de004e990f80d881c6cc00  # v5.5.0
         with:
           env_vars: OS,PYTHON
           name: ${{ matrix.os }}-${{ matrix.python-version }}

.gitignore

@@ -97,4 +97,7 @@ 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

@@ -26,7 +26,7 @@ build:
   jobs:
     install:
       - pip install -U pip
-      - pip install .[all] --group 'all'  # install all the dependency groups
+      - 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

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
@@ -159,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,<6.2.0 <https://cachetools.readthedocs.io/en/latest/>`_ library. Use this, if you want to use `arbitrary callback_data <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_.
+* ``pip install "python-telegram-bot[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]"``.
@@ -206,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.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/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.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.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:

docs/source/telegram.inputchecklist.rst

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

docs/source/telegram.inputchecklisttask.rst

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

docs/source/telegram.suggestedpostapprovalfailed.rst

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

docs/source/telegram.suggestedpostapproved.rst

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

docs/source/telegram.suggestedpostdeclined.rst

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

docs/source/telegram.suggestedpostinfo.rst

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

docs/source/telegram.suggestedpostpaid.rst

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

docs/source/telegram.suggestedpostparameters.rst

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

docs/source/telegram.suggestedpostprice.rst

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

docs/source/telegram.suggestedpostrefunded.rst

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

docs/substitutions/global.rst

@@ -96,6 +96,10 @@
 
 .. |allow_paid_broadcast| replace:: Pass True to allow up to :tg-const:`telegram.constants.FloodLimit.PAID_MESSAGES_PER_SECOND` messages per second, ignoring `broadcasting limits <https://core.telegram.org/bots/faq#how-can-i-message-all-of-my-bot-39s-subscribers-at-once>`__ for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's balance.
 
+.. |direct_messages_topic_id| replace:: Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
+
+.. |suggested_post_parameters| replace:: An object containing the parameters of the suggested post to send; for direct messages chats only. If the message is sent as a reply to another suggested post, then that suggested post is automatically declined.
+
 .. |tz-naive-dtms| replace:: For timezone naive :obj:`datetime.datetime` objects, the default timezone of the bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used.
 
 .. |org-verify| replace:: `on behalf of the organization <https://telegram.org/verify#third-party-verification>`__

examples/arbitrarycallbackdatabot.py

@@ -11,6 +11,7 @@ Note:
 To use arbitrary callback data, you must install PTB via
 `pip install "python-telegram-bot[callback-data]"`
 """
+
 import logging
 from typing import cast
 

examples/conversationbot.py

@@ -145,7 +145,9 @@ def main() -> None:
     conv_handler = ConversationHandler(
         entry_points=[CommandHandler("start", start)],
         states={
-            GENDER: [MessageHandler(filters.Regex("^(Boy|Girl|Other)$"), gender)],
+            # Use case-insensitive regex to accept gender input regardless of letter casing,
+            # e.g., "boy", "BOY", "Girl", etc., will all be matched
+            GENDER: [MessageHandler(filters.Regex("(?i)^(Boy|Girl|Other)$"), gender)],
             PHOTO: [MessageHandler(filters.PHOTO, photo), CommandHandler("skip", skip_photo)],
             LOCATION: [
                 MessageHandler(filters.LOCATION, location),

examples/customwebhookbot/djangobot.py

@@ -13,6 +13,7 @@ Set bot Token, URL, admin CHAT_ID and PORT after the imports.
 You may also need to change the `listen` value in the uvicorn configuration to match your setup.
 Press Ctrl-C on the command line or send a signal to the process to stop the bot.
 """
+
 import asyncio
 import html
 import json

examples/customwebhookbot/flaskbot.py

@@ -13,6 +13,7 @@ Set bot Token, URL, admin CHAT_ID and PORT after the imports.
 You may also need to change the `listen` value in the uvicorn configuration to match your setup.
 Press Ctrl-C on the command line or send a signal to the process to stop the bot.
 """
+
 import asyncio
 import html
 import logging

examples/customwebhookbot/quartbot.py

@@ -13,6 +13,7 @@ Set bot Token, URL, admin CHAT_ID and PORT after the imports.
 You may also need to change the `listen` value in the uvicorn configuration to match your setup.
 Press Ctrl-C on the command line or send a signal to the process to stop the bot.
 """
+
 import asyncio
 import html
 import logging

examples/customwebhookbot/starlettebot.py

@@ -13,6 +13,7 @@ Set bot Token, URL, admin CHAT_ID and PORT after the imports.
 You may also need to change the `listen` value in the uvicorn configuration to match your setup.
 Press Ctrl-C on the command line or send a signal to the process to stop the bot.
 """
+
 import asyncio
 import html
 import logging

examples/errorhandlerbot.py

@@ -3,6 +3,7 @@
 # This program is dedicated to the public domain under the CC0 license.
 
 """This is a very simple example on how one could implement a custom error handler."""
+
 import html
 import json
 import logging

examples/inlinebot.py

@@ -14,6 +14,7 @@ Basic inline bot example. Applies different text transformations.
 Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
+
 import logging
 from html import escape
 from uuid import uuid4

examples/inlinekeyboard.py

@@ -6,6 +6,7 @@
 Basic example for a bot that uses inline keyboards. For an in-depth explanation, check out
  https://github.com/python-telegram-bot/python-telegram-bot/wiki/InlineKeyboard-Example.
 """
+
 import logging
 
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update

examples/inlinekeyboard2.py

@@ -14,6 +14,7 @@ ConversationHandler.
 Send /start to initiate the conversation.
 Press Ctrl-C on the command line to stop the bot.
 """
+
 import logging
 
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update

examples/passportbot.py

@@ -14,6 +14,7 @@ Note:
 To use Telegram Passport, you must install PTB via
 `pip install "python-telegram-bot[passport]"`
 """
+
 import logging
 from pathlib import Path
 

examples/pollbot.py

@@ -7,6 +7,7 @@ Basic example for a bot that works with polls. Only 3 people are allowed to inte
 poll/quiz the bot generates. The preview command generates a closed poll/quiz, exactly like the
 one the user sends the bot
 """
+
 import logging
 
 from telegram import (

examples/rawapibot.py

@@ -5,6 +5,7 @@ This is built on the API wrapper, see echobot.py to see the same example built
 on the telegram.ext bot framework.
 This program is dedicated to the public domain under the CC0 license.
 """
+
 import asyncio
 import contextlib
 import datetime as dtm

examples/webappbot.py

@@ -8,6 +8,7 @@ The static website for this website is hosted by the PTB team for your convenien
 Currently only showcases starting the WebApp via a KeyboardButton, as all other methods would
 require a bot token.
 """
+
 import json
 import logging
 

pyproject.toml

@@ -52,14 +52,12 @@ dependencies = [
 "Support" = "https://t.me/pythontelegrambotgroup"
 
 [project.optional-dependencies]
-# Make sure to install those as additional_dependencies in the
-# pre-commit hooks for pylint & mypy
-# Also update the readme accordingly
+# Make sure to install those as additional_dependencies in the pre-commit hooks
 #
 # When dependencies release new versions and tests succeed, we should try to expand the allowed
 # versions and only increase the lower bound if necessary
 #
-# When adding new groups, make sure to update `ext` and `all` accordingly
+# When adding new extras, make sure to update `ext` and `all` accordingly
 
 # Optional dependencies for production
 all = [
@@ -67,7 +65,7 @@ all = [
 ]
 callback-data = [
     # Cachetools doesn't have a strict stability policy. Let's be cautious for now.
-    "cachetools>=5.3.3,<6.2.0",
+    "cachetools>=5.3.3,<6.3.0",
 ]
 ext = [
     "python-telegram-bot[callback-data,job-queue,rate-limiter,webhooks]",
@@ -100,11 +98,11 @@ tests = [
     # required for building the wheels for releases
     "build",
     # For the test suite
-    "pytest==8.4.0",
+    "pytest==8.4.2",
     # needed because pytest doesn't come with native support for coroutines as tests
     "pytest-asyncio==0.21.2",
     # xdist runs tests in parallel
-    "pytest-xdist==3.6.1",
+    "pytest-xdist==3.8.0",
     # Used for flaky tests (flaky decorator)
     "flaky>=3.8.1",
     # used in test_official for parsing tg docs
@@ -120,7 +118,7 @@ tests = [
 docs = [
     "chango~=0.4.0; python_version >= '3.12'",
     "sphinx==8.2.3; python_version >= '3.11'",
-    "furo==2024.8.6",
+    "furo==2025.7.19",
     "sphinx-paramlinks==0.6.0",
     "sphinxcontrib-mermaid==1.0.0",
     "sphinx-copybutton==0.5.2",
@@ -128,14 +126,18 @@ docs = [
     # Temporary. See #4387
     "sphinx-build-compatibility @ git+https://github.com/readthedocs/sphinx-build-compatibility.git@58aabc5f207c6c2421f23d3578adc0b14af57047",
     # For python 3.14 support, we need a version of pydantic-core >= 2.35.0, since it upgrades the
-    # rust toolchain, required for building the project. But there isn't a version of pydantic
-    # which allows that pydantic-core version yet, so we use the latest commit on the
-    # pydantic repository, which has the required version of pydantic-core.
-    # This should ideally be done in `chango`'s dependencies. We can remove this once a new pydantic
-    # version is released.
-    "pydantic @ git+https://github.com/pydantic/pydantic ; python_version >= '3.14'"
+    # rust toolchain, required for building the project.
+    # This should ideally be done in `chango`'s dependencies. We can remove this once a new
+    # stable pydantic version is released.
+    "pydantic >= 2.12.0a1 ; python_version >= '3.14'"
 ]
-all = ["pre-commit", { include-group = "tests" }, { include-group = "docs" }]
+linting = [
+    "pre-commit",
+    "ruff==0.12.7",
+    "mypy==1.16.1",
+    "pylint==3.3.7"
+]
+all = [{ include-group = "tests" }, { include-group = "docs" }, { include-group = "linting"}]
 
 # HATCH
 [tool.hatch.version]
@@ -146,7 +148,7 @@ path = "src/telegram/_version.py"
 # See also https://github.com/pypa/hatch/issues/1230 for discussion
 # the source distribution will include most of the files in the root directory
 [tool.hatch.build.targets.sdist]
-exclude = [".venv*", "venv*", ".github"]
+exclude = [".venv*", "venv*", ".github", "uv.lock"]
 # the wheel will only include the src/telegram package
 [tool.hatch.build.targets.wheel]
 packages = ["src/telegram"]
@@ -156,15 +158,6 @@ packages = ["src/telegram"]
 sys_path = "changes"
 chango_instance = { name= "chango_instance", module = "config" }
 
-# BLACK:
-[tool.black]
-line-length = 99
-
-# ISORT:
-[tool.isort]  # black config
-profile = "black"
-line_length = 99
-
 # RUFF:
 [tool.ruff]
 line-length = 99

setup.cfg

@@ -1,5 +0,0 @@
-[flake8]
-max-line-length = 99
-ignore = W503, W605
-extend-ignore = E203, E704
-exclude = docs/source/conf.py

src/telegram/__init__.py

@@ -82,12 +82,18 @@ __all__ = (
     "ChatPermissions",
     "ChatPhoto",
     "ChatShared",
+    "Checklist",
+    "ChecklistTask",
+    "ChecklistTasksAdded",
+    "ChecklistTasksDone",
     "ChosenInlineResult",
     "Contact",
     "CopyTextButton",
     "Credentials",
     "DataCredentials",
     "Dice",
+    "DirectMessagePriceChanged",
+    "DirectMessagesTopic",
     "Document",
     "EncryptedCredentials",
     "EncryptedPassportElement",
@@ -138,6 +144,8 @@ __all__ = (
     "InlineQueryResultVideo",
     "InlineQueryResultVoice",
     "InlineQueryResultsButton",
+    "InputChecklist",
+    "InputChecklistTask",
     "InputContactMessageContent",
     "InputFile",
     "InputInvoiceMessageContent",
@@ -257,6 +265,14 @@ __all__ = (
     "StoryAreaTypeUniqueGift",
     "StoryAreaTypeWeather",
     "SuccessfulPayment",
+    "SuggestedPostApprovalFailed",
+    "SuggestedPostApproved",
+    "SuggestedPostDeclined",
+    "SuggestedPostInfo",
+    "SuggestedPostPaid",
+    "SuggestedPostParameters",
+    "SuggestedPostPrice",
+    "SuggestedPostRefunded",
     "SwitchInlineQueryChosenChat",
     "TelegramObject",
     "TextQuote",
@@ -302,6 +318,7 @@ __all__ = (
     "warnings",
 )
 
+from telegram._inputchecklist import InputChecklist, InputChecklistTask
 from telegram._payment.stars.staramount import StarAmount
 from telegram._payment.stars.startransactions import StarTransaction, StarTransactions
 from telegram._payment.stars.transactionpartner import (
@@ -381,9 +398,12 @@ from ._chatmember import (
 )
 from ._chatmemberupdated import ChatMemberUpdated
 from ._chatpermissions import ChatPermissions
+from ._checklists import Checklist, ChecklistTask, ChecklistTasksAdded, ChecklistTasksDone
 from ._choseninlineresult import ChosenInlineResult
 from ._copytextbutton import CopyTextButton
 from ._dice import Dice
+from ._directmessagepricechanged import DirectMessagePriceChanged
+from ._directmessagestopic import DirectMessagesTopic
 from ._files._inputstorycontent import (
     InputStoryContent,
     InputStoryContentPhoto,
@@ -561,6 +581,16 @@ from ._storyarea import (
     StoryAreaTypeUniqueGift,
     StoryAreaTypeWeather,
 )
+from ._suggestedpost import (
+    SuggestedPostApprovalFailed,
+    SuggestedPostApproved,
+    SuggestedPostDeclined,
+    SuggestedPostInfo,
+    SuggestedPostPaid,
+    SuggestedPostParameters,
+    SuggestedPostPrice,
+    SuggestedPostRefunded,
+)
 from ._switchinlinequerychosenchat import SwitchInlineQueryChosenChat
 from ._telegramobject import TelegramObject
 from ._uniquegift import (