Bump Version to v22.3 (#4870)

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

.github/CONTRIBUTING.rst

@@ -22,12 +22,16 @@ Setting things up
 
       $ git remote add upstream https://github.com/python-telegram-bot/python-telegram-bot
 
-4. Install dependencies:
+4. Install the package in development mode as well as optional dependencies and development dependencies.
+   Note that the `--group` argument requires `pip` 25.1 or later.
+   
+   Alternatively, you can use your preferred package manager (such as uv, hatch, poetry, etc.) instead of pip.
 
    .. code-block:: bash
 
-      $ pip install -r requirements-dev-all.txt
+      $ pip install -e .[all] --group all
 
+   Installing the package itself is necessary because python-telegram-bot uses a src-based layout where the package code is located in the ``src/`` directory.
 
 5. Install pre-commit hooks:
 

.github/workflows/chango.yml

@@ -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/dependabot-prs.yml

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

.github/workflows/docs-admonitions.yml

@@ -2,7 +2,7 @@ name: Test Admonitions Generation
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - docs/**
       - .github/workflows/docs-admonitions.yml
   push:
@@ -28,14 +28,14 @@ jobs:
         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

@@ -23,13 +23,13 @@ jobs:
         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

@@ -21,13 +21,13 @@ jobs:
         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@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1
       - name: Run zizmor
         run: uvx zizmor --persona=pedantic --format sarif . > results.sarif
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Upload SARIF file
-        uses: github/codeql-action/upload-sarif@28deaeda66b76a05916b6923827895f2b14ab387 # v3.28.16
+        uses: github/codeql-action/upload-sarif@181d5eefc20863364f96762470ba6f862bdef56b # v3.29.2
         with:
           sarif_file: results.sarif
           category: zizmor

.github/workflows/release_pypi.yml

@@ -21,7 +21,7 @@ jobs:
         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
@@ -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
@@ -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:

.github/workflows/release_test_pypi.yml

@@ -21,7 +21,7 @@ jobs:
         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
@@ -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

.github/workflows/test_official.yml

@@ -2,7 +2,7 @@ name: Bot API Tests
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - tests/**
   push:
     branches:
@@ -27,14 +27,13 @@ jobs:
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@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:

.github/workflows/unit_tests.yml

@@ -2,11 +2,10 @@ name: Unit Tests
 on:
   pull_request:
     paths:
-      - telegram/**
+      - src/telegram/**
       - tests/**
       - .github/workflows/unit_tests.yml
       - pyproject.toml
-      - requirements-unit-tests.txt
   push:
     branches:
       - master
@@ -22,7 +21,7 @@ jobs:
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14.0-beta.3']
         os: [ubuntu-latest, windows-latest, macos-latest]
       fail-fast: False
     steps:
@@ -30,18 +29,14 @@ jobs:
         with:
           persist-credentials: false
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@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 +58,10 @@ jobs:
           TO_TEST="test_no_passport.py or test_datetime.py or test_defaults.py or test_jobqueue.py or test_applicationbuilder.py or test_ratelimiter.py or test_updater.py or test_callbackdatacache.py or test_request.py"
           pytest -v --cov -k "${TO_TEST}" --junit-xml=.test_report_no_optionals_junit.xml
           opt_dep_status=$?
-
+          
           # Test the rest
           export TEST_WITH_OPT_DEPS='true'
-          # need to manually install pytz here, because it's no longer in the optional reqs
-          pip install .[all] pytz
+          pip install .[all]
           # `-n auto --dist worksteal` uses pytest-xdist to run tests on multiple CPU
           # workers. Increasing number of workers has little effect on test duration, but it seems
           # to increase flakyness.
@@ -92,14 +86,14 @@ jobs:
             .test_report_optionals_junit.xml
 
       - name: Submit coverage
-        uses: codecov/codecov-action@ad3126e916f78f00edff4ed0317cf185271ccc2d  # v5.4.2
+        uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24  # v5.4.3
         with:
           env_vars: OS,PYTHON
           name: ${{ matrix.os }}-${{ matrix.python-version }}
           fail_ci_if_error: true
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Upload test results to Codecov
-        uses: codecov/test-results-action@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,8 @@ telegram.jpg
 
 # virtual env
 venv*
+pyvenv.cfg
+Scripts/
 
 # environment manager:
 .mise.toml

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ ci:
 
 repos:
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.11.9'
+    rev: 'v0.12.2'
     hooks:
     -   id: ruff
         name: ruff
@@ -25,11 +25,11 @@ repos:
         - --diff
         - --check
 -   repo: https://github.com/PyCQA/flake8
-    rev: 7.2.0
+    rev: 7.3.0
     hooks:
     -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v3.3.6
+    rev: v3.3.7
     hooks:
     -   id: pylint
         files: ^(?!(tests|docs)).*\.py$
@@ -41,7 +41,7 @@ repos:
           - aiolimiter~=1.1,<1.3
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.15.0
+    rev: v1.16.1
     hooks:
     -   id: mypy
         name: mypy-ptb
@@ -68,7 +68,7 @@ repos:
         - cachetools>=5.3.3,<5.5.0
         - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.19.1
+    rev: v3.20.0
     hooks:
     -   id: pyupgrade
         args:

.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 'all'  # install all the dependency groups
+
     post_build:
       # Based on https://github.com/readthedocs/readthedocs.org/issues/3242#issuecomment-1410321534
       # This provides a HTML zip file for download, with the same structure as the hosted website

AUTHORS.rst

@@ -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.1-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.1** are natively supported by this library.
 In addition, Bot API functionality not yet natively included can still be used as described `in our wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Forward-Compatibility>`_.
 
 Notable Features
@@ -114,6 +114,8 @@ You can also install ``python-telegram-bot`` from source, though this is usually
     $ pip install build
     $ python -m build
 
+You can also use your favored package manager (such as ``uv``, ``hatch``, ``poetry``, etc.) instead of ``pip``.
+
 Verifying Releases
 ~~~~~~~~~~~~~~~~~~
 
@@ -139,7 +141,7 @@ As these features are *optional*, the corresponding 3rd party dependencies are n
 Instead, they are listed as optional dependencies.
 This allows to avoid unnecessary dependency conflicts for users who don't need the optional features.
 
-The only required dependency is `httpx ~= 0.27 <https://www.python-httpx.org>`_ for
+The only required dependency is `httpx >=0.27,<0.29 <https://www.python-httpx.org>`_ for
 ``telegram.request.HTTPXRequest``, the default networking backend.
 
 ``python-telegram-bot`` is most useful when used along with additional libraries.
@@ -157,7 +159,7 @@ PTB can be installed with optional dependencies:
 * ``pip install "python-telegram-bot[http2]"`` installs `httpx[http2] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to use HTTP/2.
 * ``pip install "python-telegram-bot[rate-limiter]"`` installs `aiolimiter~=1.1,<1.3 <https://aiolimiter.readthedocs.io/en/stable/>`_. Use this, if you want to use ``telegram.ext.AIORateLimiter``.
 * ``pip install "python-telegram-bot[webhooks]"`` installs the `tornado~=6.4 <https://www.tornadoweb.org/en/stable/>`_ library. Use this, if you want to use ``telegram.ext.Updater.start_webhook``/``telegram.ext.Application.run_webhook``.
-* ``pip install "python-telegram-bot[callback-data]"`` installs the `cachetools>=5.3.3,<5.6.0 <https://cachetools.readthedocs.io/en/latest/>`_ library. Use this, if you want to use `arbitrary callback_data <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_.
+* ``pip install "python-telegram-bot[callback-data]"`` installs the `cachetools>=5.3.3,<6.2.0 <https://cachetools.readthedocs.io/en/latest/>`_ library. Use this, if you want to use `arbitrary callback_data <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_.
 * ``pip install "python-telegram-bot[job-queue]"`` installs the `APScheduler>=3.10.4,<3.12.0 <https://apscheduler.readthedocs.io/en/3.x/>`_ library. Use this, if you want to use the ``telegram.ext.JobQueue``.
 
 To install multiple optional dependencies, separate them by commas, e.g. ``pip install "python-telegram-bot[socks,webhooks]"``.

changes/22.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/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/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

@@ -390,6 +390,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 +449,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,7 @@ Available Types
     telegram.chatshared
     telegram.contact
     telegram.dice
+    telegram.directmessagepricechanged
     telegram.document
     telegram.externalreplyinfo
     telegram.file
@@ -85,6 +90,8 @@ Available Types
     telegram.inaccessiblemessage
     telegram.inlinekeyboardbutton
     telegram.inlinekeyboardmarkup
+    telegram.inputchecklist
+    telegram.inputchecklisttask
     telegram.inputfile
     telegram.inputmedia
     telegram.inputmediaanimation

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

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

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

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

docs/source/telegram.revenuewithdrawalstate.rst

@@ -4,4 +4,3 @@ RevenueWithdrawalState
 .. autoclass:: telegram.RevenueWithdrawalState
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject

docs/source/telegram.revenuewithdrawalstatefailed.rst

@@ -4,4 +4,3 @@ RevenueWithdrawalStateFailed
 .. autoclass:: telegram.RevenueWithdrawalStateFailed
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject

docs/source/telegram.revenuewithdrawalstatepending.rst

@@ -4,4 +4,3 @@ RevenueWithdrawalStatePending
 .. autoclass:: telegram.RevenueWithdrawalStatePending
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject

docs/source/telegram.revenuewithdrawalstatesucceeded.rst

@@ -4,4 +4,3 @@ RevenueWithdrawalStateSucceeded
 .. autoclass:: telegram.RevenueWithdrawalStateSucceeded
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject

docs/source/telegram.startransaction.rst

@@ -4,4 +4,3 @@ StarTransaction
 .. autoclass:: telegram.StarTransaction
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject

docs/source/telegram.startransactions.rst

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

docs/source/telegram.sticker.rst

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

docs/source/telegram.transactionpartner.rst

@@ -4,4 +4,3 @@ TransactionPartner
 .. autoclass:: telegram.TransactionPartner
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject

docs/source/telegram.transactionpartnerchat.rst

@@ -4,4 +4,3 @@ TransactionPartnerChat
 .. autoclass:: telegram.TransactionPartnerChat
     :members:
     :show-inheritance:
-    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartnerfragment.rst

@@ -4,4 +4,3 @@ TransactionPartnerFragment
 .. autoclass:: telegram.TransactionPartnerFragment
     :members:
     :show-inheritance:
-    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartnerother.rst

@@ -4,4 +4,3 @@ TransactionPartnerOther
 .. autoclass:: telegram.TransactionPartnerOther
     :members:
     :show-inheritance:
-    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartnertelegramads.rst

@@ -4,4 +4,3 @@ TransactionPartnerTelegramAds
 .. autoclass:: telegram.TransactionPartnerTelegramAds
     :members:
     :show-inheritance:
-    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartnertelegramapi.rst

@@ -4,4 +4,3 @@ TransactionPartnerTelegramApi
 .. autoclass:: telegram.TransactionPartnerTelegramApi
     :members:
     :show-inheritance:
-    :inherited-members: TransactionPartner

docs/source/telegram.transactionpartneruser.rst

@@ -4,4 +4,3 @@ TransactionPartnerUser
 .. autoclass:: telegram.TransactionPartnerUser
     :members:
     :show-inheritance:
-    :inherited-members: TransactionPartner

docs/source/telegram.video.rst

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

docs/source/telegram.videonote.rst

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

docs/source/telegram.voice.rst

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

docs/substitutions/global.rst

@@ -80,7 +80,7 @@
 
 .. |reply_quote| replace:: If set to :obj:`True`, the reply is sent as an actual reply to this message. If ``reply_to_message_id`` is passed, this parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
 
-.. |do_quote| replace:: If set to :obj:`True`, the replied message is quoted. For a dict, it must be the output of :meth:`~telegram.Message.build_reply_arguments` to specify exact ``reply_parameters``. If ``reply_to_message_id`` or ``reply_parameters`` are passed, this parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
+.. |do_quote| replace:: If set to :obj:`True`, the replied message is quoted. For a dict, it must be the output of :meth:`~telegram.Message.build_reply_arguments` to specify exact ``reply_parameters``. If ``reply_to_message_id`` or ``reply_parameters`` are passed, this parameter will be ignored. When passing dict-valued input, ``do_quote`` is mutually exclusive with ``allow_sending_without_reply``. Default: :obj:`True` in group chats and :obj:`False` in private chats.
 
 .. |non_optional_story_argument| replace:: As of this version, this argument is now required. In accordance with our `stability policy <https://docs.python-telegram-bot.org/en/stable/stability_policy.html>`__, the signature will be kept as optional for now, though they are mandatory and an error will be raised if you don't pass it.
 
@@ -101,3 +101,5 @@
 .. |org-verify| replace:: `on behalf of the organization <https://telegram.org/verify#third-party-verification>`__
 
 .. |time-period-input| replace:: :class:`datetime.timedelta` objects are accepted in addition to plain :obj:`int` values.
+
+.. |time-period-int-deprecated| replace:: In a future major version this attribute will be of type :obj:`datetime.timedelta`. You can opt-in early by setting `PTB_TIMEDELTA=true`  or ``PTB_TIMEDELTA=1`` as an environment variable.

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/rawapibot.py

@@ -7,6 +7,7 @@ This program is dedicated to the public domain under the CC0 license.
 """
 import asyncio
 import contextlib
+import datetime as dtm
 import logging
 from typing import NoReturn
 
@@ -47,7 +48,9 @@ async def main() -> NoReturn:
 async def echo(bot: Bot, update_id: int) -> int:
     """Echo the message the user sent."""
     # Request updates after the last update_id
-    updates = await bot.get_updates(offset=update_id, timeout=10, allowed_updates=Update.ALL_TYPES)
+    updates = await bot.get_updates(
+        offset=update_id, timeout=dtm.timedelta(seconds=10), allowed_updates=Update.ALL_TYPES
+    )
     for update in updates:
         next_update_id = update.update_id + 1
 

pyproject.toml

@@ -36,9 +36,10 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-    "httpx ~= 0.27",
+    "httpx >=0.27,<0.29",
 ]
 
 [project.urls]
@@ -66,7 +67,7 @@ all = [
 ]
 callback-data = [
     # Cachetools doesn't have a strict stability policy. Let's be cautious for now.
-    "cachetools>=5.3.3,<5.6.0",
+    "cachetools>=5.3.3,<6.2.0",
 ]
 ext = [
     "python-telegram-bot[callback-data,job-queue,rate-limiter,webhooks]",
@@ -91,19 +92,64 @@ socks = [
 ]
 webhooks = [
     # tornado is rather stable, but let's not allow the next major release without prior testing
-    "tornado~=6.4",
+    "tornado~=6.5",
 ]
 
+[dependency-groups]
+tests = [
+    # required for building the wheels for releases
+    "build",
+    # For the test suite
+    "pytest==8.4.0",
+    # 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",
+    # Used for flaky tests (flaky decorator)
+    "flaky>=3.8.1",
+    # used in test_official for parsing tg docs
+    "beautifulsoup4",
+    # For testing with timezones. Might not be needed on all systems, but to ensure that unit tests
+    # run correctly on all systems, we include it here.
+    "tzdata",
+    # We've deprecated support pytz, but we still need it for testing that it works with the library.
+    "pytz",
+    # Install coverage:
+    "pytest-cov"
+]
+docs = [
+    "chango~=0.4.0; python_version >= '3.12'",
+    "sphinx==8.2.3; python_version >= '3.11'",
+    "furo==2024.8.6",
+    "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",
+    # 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'"
+]
+all = ["pre-commit", { include-group = "tests" }, { include-group = "docs" }]
 
 # HATCH
 [tool.hatch.version]
 # dynamically evaluates the `__version__` variable in that file
 source = "code"
-path = "telegram/_version.py"
-search-paths = ["telegram"]
+path = "src/telegram/_version.py"
 
-[tool.hatch.build]
-packages = ["telegram"]
+# 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"]
+# the wheel will only include the src/telegram package
+[tool.hatch.build.targets.wheel]
+packages = ["src/telegram"]
 
 # CHANGO
 [tool.chango]
@@ -136,9 +182,9 @@ select = ["E", "F", "I", "PL", "UP", "RUF", "PTH", "C4", "B", "PIE", "SIM", "RET
 [tool.ruff.lint.per-file-ignores]
 "tests/*.py" = ["B018"]
 "tests/**.py" = ["RUF012", "ASYNC230", "DTZ", "ARG", "T201", "ASYNC109", "D", "S", "TRY"]
-"telegram/**.py" = ["TRY003"]
-"telegram/ext/_applicationbuilder.py" = ["TRY004"]
-"telegram/ext/filters.py" = ["D102"]
+"src/telegram/**.py" = ["TRY003"]
+"src/telegram/ext/_applicationbuilder.py" = ["TRY004"]
+"src/telegram/ext/filters.py" = ["D102"]
 "docs/**.py" = ["INP001", "ARG", "D", "TRY003", "S"]
 "examples/**.py" = ["ARG", "D", "S105", "TRY003"]
 
@@ -166,6 +212,7 @@ exclude-protected = ["_unfrozen"]
 # PYTEST:
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
 addopts = "--no-success-flaky-report -rX"
 filterwarnings = [
     "error",
@@ -188,6 +235,7 @@ log_cli_format = "%(funcName)s - Line %(lineno)d - %(message)s"
 
 # MYPY:
 [tool.mypy]
+mypy_path = "src"
 warn_unused_ignores = true
 warn_unused_configs = true
 disallow_untyped_defs = true
@@ -230,12 +278,12 @@ ignore_missing_imports = true
 # COVERAGE:
 [tool.coverage.run]
 branch = true
-source = ["telegram"]
+source = ["src/telegram"]
 parallel = true
 concurrency = ["thread", "multiprocessing"]
 omit = [
     "tests/",
-    "telegram/__main__.py"
+    "src/telegram/__main__.py"
 ]
 
 [tool.coverage.report]

requirements-dev-all.txt

@@ -1,5 +0,0 @@
--e .[all]
-# needed for pre-commit hooks in the git commit command
-pre-commit
--r requirements-unit-tests.txt
--r docs/requirements-docs.txt

requirements-unit-tests.txt

@@ -1,23 +0,0 @@
--e .
-
-# required for building the wheels for releases
-build
-
-# For the test suite
-pytest==8.3.5
-
-# 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
-
-# Used for flaky tests (flaky decorator)
-flaky>=3.8.1
-
-# used in test_official for parsing tg docs
-beautifulsoup4
-
-# For testing with timezones. Might not be needed on all systems, but to ensure that unit tests
-# run correctly on all systems, we include it here.
-tzdata

src/telegram/__init__.py

@@ -82,12 +82,17 @@ __all__ = (
     "ChatPermissions",
     "ChatPhoto",
     "ChatShared",
+    "Checklist",
+    "ChecklistTask",
+    "ChecklistTasksAdded",
+    "ChecklistTasksDone",
     "ChosenInlineResult",
     "Contact",
     "CopyTextButton",
     "Credentials",
     "DataCredentials",
     "Dice",
+    "DirectMessagePriceChanged",
     "Document",
     "EncryptedCredentials",
     "EncryptedPassportElement",
@@ -138,6 +143,8 @@ __all__ = (
     "InlineQueryResultVideo",
     "InlineQueryResultVoice",
     "InlineQueryResultsButton",
+    "InputChecklist",
+    "InputChecklistTask",
     "InputContactMessageContent",
     "InputFile",
     "InputInvoiceMessageContent",
@@ -302,6 +309,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 +389,11 @@ 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 ._files._inputstorycontent import (
     InputStoryContent,
     InputStoryContentPhoto,

src/telegram/__main__.py

@@ -17,7 +17,7 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 # pylint: disable=missing-module-docstring
-# ruff: noqa: T201, D100, S603, S607
+# ruff: noqa: T201, D100, S607
 import subprocess
 import sys
 from typing import Optional

src/telegram/_bot.py

@@ -78,6 +78,7 @@ from telegram._games.gamehighscore import GameHighScore
 from telegram._gifts import AcceptedGiftTypes, Gift, Gifts
 from telegram._inline.inlinequeryresultsbutton import InlineQueryResultsButton
 from telegram._inline.preparedinlinemessage import PreparedInlineMessage
+from telegram._inputchecklist import InputChecklist
 from telegram._menubutton import MenuButton
 from telegram._message import Message
 from telegram._messageid import MessageId
@@ -3176,7 +3177,7 @@ class Bot(TelegramObject, contextlib.AbstractAsyncContextManager["Bot"]):
             google_place_id (:obj:`str`, optional): Google Places identifier of the venue.
             google_place_type (:obj:`str`, optional): Google Places type of the venue. (See
                 `supported types \
-                <https://developers.google.com/maps/documentation/places/web-service/supported_types>`_.)
+                <https://developers.google.com/maps/documentation/places/web-service/place-types>`_.)
             disable_notification (:obj:`bool`, optional): |disable_notification|
             protect_content (:obj:`bool`, optional): |protect_content|
 
@@ -4519,7 +4520,7 @@ class Bot(TelegramObject, contextlib.AbstractAsyncContextManager["Bot"]):
         self,
         offset: Optional[int] = None,
         limit: Optional[int] = None,
-        timeout: Optional[int] = None,
+        timeout: Optional[TimePeriod] = None,
         allowed_updates: Optional[Sequence[str]] = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -4554,9 +4555,12 @@ class Bot(TelegramObject, contextlib.AbstractAsyncContextManager["Bot"]):
                 between :tg-const:`telegram.constants.PollingLimit.MIN_LIMIT`-
                 :tg-const:`telegram.constants.PollingLimit.MAX_LIMIT` are accepted.
                 Defaults to ``100``.
-            timeout (:obj:`int`, optional): Timeout in seconds for long polling. Defaults to ``0``,
-                i.e. usual short polling. Should be positive, short polling should be used for
-                testing purposes only.
+            timeout (:obj:`int` | :class:`datetime.timedelta`, optional): Timeout in seconds for
+                long polling. Defaults to ``0``, i.e. usual short polling. Should be positive,
+                short polling should be used for testing purposes only.
+
+                .. versionchanged:: v22.2
+                    |time-period-input|
             allowed_updates (Sequence[:obj:`str`]), optional): A sequence the types of
                 updates you want your bot to receive. For example, specify ["message",
                 "edited_channel_post", "callback_query"] to only receive updates of these types.
@@ -4591,6 +4595,12 @@ class Bot(TelegramObject, contextlib.AbstractAsyncContextManager["Bot"]):
         else:
             arg_read_timeout = self._request[0].read_timeout or 0
 
+        read_timeout = (
+            (arg_read_timeout + timeout.total_seconds())
+            if isinstance(timeout, dtm.timedelta)
+            else (arg_read_timeout + timeout if timeout else arg_read_timeout)
+        )
+
         # Ideally we'd use an aggressive read timeout for the polling. However,
         # * Short polling should return within 2 seconds.
         # * Long polling poses a different problem: the connection might have been dropped while
@@ -4601,7 +4611,7 @@ class Bot(TelegramObject, contextlib.AbstractAsyncContextManager["Bot"]):
             await self._post(
                 "getUpdates",
                 data,
-                read_timeout=arg_read_timeout + timeout if timeout else arg_read_timeout,
+                read_timeout=read_timeout,
                 write_timeout=write_timeout,
                 connect_timeout=connect_timeout,
                 pool_timeout=pool_timeout,
@@ -7546,6 +7556,142 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
         )
         return Poll.de_json(result, self)
 
+    async def send_checklist(
+        self,
+        business_connection_id: str,
+        chat_id: int,
+        checklist: InputChecklist,
+        disable_notification: ODVInput[bool] = DEFAULT_NONE,
+        protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_effect_id: Optional[str] = None,
+        reply_parameters: Optional["ReplyParameters"] = None,
+        reply_markup: Optional["InlineKeyboardMarkup"] = None,
+        *,
+        allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
+        reply_to_message_id: Optional[int] = None,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Message:
+        """
+        Use this method to send a checklist on behalf of a connected business account.
+
+        .. versionadded:: 22.3
+
+        Args:
+            business_connection_id (:obj:`str`):
+                |business_id_str|
+            chat_id (:obj:`int`):
+                Unique identifier for the target chat.
+            checklist (:class:`telegram.InputChecklist`):
+                The checklist to send.
+            disable_notification (:obj:`bool`, optional):
+                |disable_notification|
+            protect_content (:obj:`bool`, optional):
+                |protect_content|
+            message_effect_id (:obj:`str`, optional):
+                |message_effect_id|
+            reply_parameters (:class:`telegram.ReplyParameters`, optional):
+                |reply_parameters|
+            reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional):
+                An object for an inline keyboard
+
+        Keyword Args:
+            allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply|
+                Mutually exclusive with :paramref:`reply_parameters`, which this is a convenience
+                parameter for
+            reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id|
+                Mutually exclusive with :paramref:`reply_parameters`, which this is a convenience
+                parameter for
+
+        Returns:
+            :class:`telegram.Message`: On success, the sent Message is returned.
+
+        Raises:
+            :class:`telegram.error.TelegramError`
+
+        """
+        data: JSONDict = {
+            "chat_id": chat_id,
+            "checklist": checklist,
+        }
+
+        return await self._send_message(
+            "sendChecklist",
+            data,
+            disable_notification=disable_notification,
+            reply_markup=reply_markup,
+            protect_content=protect_content,
+            reply_parameters=reply_parameters,
+            message_effect_id=message_effect_id,
+            business_connection_id=business_connection_id,
+            allow_sending_without_reply=allow_sending_without_reply,
+            reply_to_message_id=reply_to_message_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def edit_message_checklist(
+        self,
+        business_connection_id: str,
+        chat_id: int,
+        message_id: int,
+        checklist: InputChecklist,
+        reply_markup: Optional["InlineKeyboardMarkup"] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Message:
+        """
+        Use this method to edit a checklist on behalf of a connected business account.
+
+        .. versionadded:: 22.3
+
+        Args:
+            business_connection_id (:obj:`str`):
+                |business_id_str|
+            chat_id (:obj:`int`):
+                Unique identifier for the target chat.
+            message_id (:obj:`int`):
+                Unique identifier for the target message.
+            checklist (:class:`telegram.InputChecklist`):
+                The new checklist.
+            reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional):
+                An object for the new inline keyboard for the message.
+
+        Returns:
+            :class:`telegram.Message`: On success, the sent Message is returned.
+
+        Raises:
+            :class:`telegram.error.TelegramError`
+
+        """
+        data: JSONDict = {
+            "chat_id": chat_id,
+            "message_id": message_id,
+            "checklist": checklist,
+        }
+
+        return await self._send_message(
+            "editMessageChecklist",
+            data,
+            reply_markup=reply_markup,
+            business_connection_id=business_connection_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
     async def send_dice(
         self,
         chat_id: Union[int, str],
@@ -11063,6 +11209,36 @@ CHAT_ACTIVITY_TIMEOUT` seconds.
             api_kwargs=api_kwargs,
         )
 
+    async def get_my_star_balance(
+        self,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> StarAmount:
+        """A method to get the current Telegram Stars balance of the bot. Requires no parameters.
+
+        .. versionadded:: 22.3
+
+        Returns:
+            :class:`telegram.StarAmount`
+
+        Raises:
+            :class:`telegram.error.TelegramError`
+        """
+        return StarAmount.de_json(
+            await self._post(
+                "getMyStarBalance",
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+            )
+        )
+
     def to_dict(self, recursive: bool = True) -> JSONDict:  # noqa: ARG002
         """See :meth:`telegram.TelegramObject.to_dict`."""
         data: JSONDict = {"id": self.id, "username": self.username, "first_name": self.first_name}
@@ -11235,6 +11411,10 @@ CHAT_ACTIVITY_TIMEOUT` seconds.
     """Alias for :meth:`send_poll`"""
     stopPoll = stop_poll
     """Alias for :meth:`stop_poll`"""
+    sendChecklist = send_checklist
+    """Alias for :meth:`send_checklist`"""
+    editMessageChecklist = edit_message_checklist
+    """Alias for :meth:`edit_message_checklist`"""
     sendDice = send_dice
     """Alias for :meth:`send_dice`"""
     getMyCommands = get_my_commands
@@ -11377,3 +11557,5 @@ CHAT_ACTIVITY_TIMEOUT` seconds.
     """Alias for :meth:`remove_chat_verification`"""
     removeUserVerification = remove_user_verification
     """Alias for :meth:`remove_user_verification`"""
+    getMyStarBalance = get_my_star_balance
+    """Alias for :meth:`get_my_star_balance`"""